AgentScope

+ {/* File list */} + {files.length > 0 && ( +

+ {files.map((file, index) => ( +

+ {file.status === 'processing' && ( + + )} + {file.name} + +

+ ))} +

+ )} + + {/* Input area */} +

+ {/* Hidden measurement element */} + + {value} + + +

setValue(e.target.value)}
+							onKeyDown={handleKeyDown}
+							onFocus={() => setIsFocused(true)}
+							onBlur={() => setIsFocused(false)}
+							placeholder={defaultPlaceholder}
+							disabled={disabled}
+							rows={1}
+							className="w-full resize-none rounded-md border-0 bg-transparent px-3 py-2 text-sm outline-none placeholder:text-muted-foreground focus:outline-none disabled:cursor-not-allowed disabled:opacity-50"
+							style={{
+								maxHeight: 'calc(1.5em * 6)',
+								lineHeight: '1.5em',
+								overflowY: 'auto',
+							}}
+							autoFocus={true}
+						/>
+
+						{/* Autocomplete suggestion - using absolute positioning overlay */}
+						{suggestion && isFocused && (
+							<div
+								className="pointer-events-none absolute left-0 top-0 px-3 py-2 text-sm"
+								style={{
+									lineHeight: '1.5em',
+									whiteSpace: 'pre-wrap',
+									wordWrap: 'break-word',
+								}}
+							>
+								{/* Invisible input text */}
+								<span className="invisible">{value}</span>
+								{/* Suggestion text */}
+								<span className="text-muted-foreground">{suggestion}</span>
+								{/* Tab hint */}
+								<span className="ml-2 text-xs text-muted-foreground/60">
+									<Kbd>Tab</Kbd> {t('textInput.toComplete')}
+								</span>
+							</div>
+						)}
+					</div>
+
+					{/* Button row */}
+					<div className="mt-2 flex items-center justify-between">
+						<div>
+							<span
+								className={`text-muted-foreground text-sm ${!isFocused && 'hidden'}`}
+							>
+								<Kbd>{isMac() ? '⇧' : 'Shift'}</Kbd> + <Kbd>Enter</Kbd>{' '}
+								{t('textInput.newLine')}
+							</span>
+						</div>
+						<div className="flex gap-2">
+							{/* Attachment button */}
+							<Tooltip>
+								<TooltipTrigger asChild>
+									<Button
+										type="button"
+										variant="ghost"
+										size="icon"
+										onClick={() => fileInputRef.current?.click()}
+										disabled={attachDisabled}
+										className="shrink-0 rounded-full"
+									>
+										<Paperclip className="h-4 w-4" />
+									</Button>
+								</TooltipTrigger>
+								<TooltipContent>
+									{attachDisabled && allowedInputTypes?.length === 0
+										? t('textInput.attachNotSupported')
+										: t('textInput.attach')}
+								</TooltipContent>
+							</Tooltip>
+
+							{/* Send / Stop button — driven by ``sendButton`` config */}
+							<Tooltip>
+								<TooltipTrigger asChild>
+									<Button
+										type="button"
+										onClick={sendButton.onClick}
+										disabled={sendButton.disabled}
+										size="icon"
+										className="shrink-0 rounded-full"
+									>
+										<sendButton.icon className="h-4 w-4" />
+									</Button>
+								</TooltipTrigger>
+								<TooltipContent>{sendButton.tooltip}</TooltipContent>
+							</Tooltip>
+
+							{/* Hidden file input */}
+							<input
+								ref={fileInputRef}
+								type="file"
+								multiple
+								accept={acceptAttr}
+								onChange={handleFileSelect}
+								className="hidden"
+							/>
+						</div>
+					</div>
+				</div>
+			</div>
+		);
+	},
+);
+
+TextInput.displayName = 'TextInput';
diff --git a/examples/web_ui/frontend/src/components/chat/tool-renderers/BashRenderer.tsx b/examples/web_ui/frontend/src/components/chat/tool-renderers/BashRenderer.tsx
new file mode 100644
index 0000000..82b5f37
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/chat/tool-renderers/BashRenderer.tsx
@@ -0,0 +1,58 @@
+import {
+	defaultGetDisplayName,
+	defaultRenderCallArgs,
+	defaultRenderGroup,
+	defaultRenderResult,
+} from './DefaultRenderer';
+import type { ToolRenderer } from './types';
+
+function parseInput(input: string): Record<string, unknown> {
+	try {
+		return JSON.parse(input);
+	} catch {
+		return {};
+	}
+}
+
+export const BashRenderer: ToolRenderer = {
+	getDisplayName: () => 'Bash',
+
+	renderCallArgs: (call) => {
+		const { command } = parseInput(call.input) as { command?: string };
+		return command || call.input;
+	},
+
+	renderResult: (call, result, t) => {
+		if (call.state === 'asking' || !result || result.state === 'running') {
+			return t('common.running');
+		}
+		if (result.state === 'interrupted') {
+			return t('common.interrupted');
+		}
+		return undefined;
+	},
+
+	renderConfirmBody: (call) => {
+		const { command, description } = parseInput(call.input) as {
+			command?: string;
+			description?: string;
+		};
+		return (
+			<div className="w-full max-w-full overflow-hidden text-ellipsis truncate">
+				<div className="text-secondary-foreground font-mono">{command}</div>
+				{description && <div className="text-muted-foreground">{description}</div>}
+			</div>
+		);
+	},
+
+	renderGroup: (calls, t) =>
+		defaultRenderGroup(calls, t, {
+			getDisplayName: (call) =>
+				BashRenderer.getDisplayName?.(call, t) ?? defaultGetDisplayName(call),
+			renderCallArgs: (call) =>
+				BashRenderer.renderCallArgs?.(call, t) ?? defaultRenderCallArgs(call),
+			renderResult: (call, result) =>
+				BashRenderer.renderResult?.(call, result, t) ??
+				defaultRenderResult(call, result, t),
+		}),
+};
diff --git a/examples/web_ui/frontend/src/components/chat/tool-renderers/DefaultRenderer.tsx b/examples/web_ui/frontend/src/components/chat/tool-renderers/DefaultRenderer.tsx
new file mode 100644
index 0000000..6b01dba
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/chat/tool-renderers/DefaultRenderer.tsx
@@ -0,0 +1,136 @@
+import type { ToolCallBlock, ToolResultBlock } from '@agentscope-ai/agentscope/message';
+import { ChevronRight } from 'lucide-react';
+import * as mime from 'mime-types';
+import type { ReactNode } from 'react';
+
+import { CornerLine, ToolStateIcon } from './_shared';
+import type { TFunction, ToolCallWithResult } from './types';
+import { Button } from '@/components/ui/button.tsx';
+import {
+	Collapsible,
+	CollapsibleContent,
+	CollapsibleTrigger,
+} from '@/components/ui/collapsible.tsx';
+
+function processToolInput(input: string): string {
+	try {
+		const obj = JSON.parse(input);
+		const entries = Object.entries(obj).map(([k, v]) => `${k}: "${v}"`);
+		return entries.join('\n');
+	} catch {
+		return input;
+	}
+}
+
+export function defaultGetDisplayName(call: ToolCallBlock): string {
+	return call.name;
+}
+
+export function defaultRenderCallArgs(call: ToolCallBlock): ReactNode {
+	if (call.input.length <= 2) return null;
+	return processToolInput(call.input);
+}
+
+export function defaultRenderResult(
+	call: ToolCallBlock,
+	result: ToolResultBlock,
+	t: TFunction,
+	maxLines = 7,
+): ReactNode {
+	if (call.state === 'asking' || !result || result.state === 'running') {
+		return <span>{t('common.running')} ...</span>;
+	}
+	if (result.state === 'interrupted') {
+		return <span>{t('common.interrupted')}</span>;
+	}
+
+	let resultStr: string;
+	if (typeof result.output === 'string') {
+		resultStr = result.output;
+	} else {
+		const parts = result.output.map((b) => {
+			if (b.type === 'text') return b.text;
+			const mainType = b.source.media_type.split('/')[0].toUpperCase();
+			const ext = (mime.extension(b.source.media_type) || 'bin').toLowerCase();
+			return `[${mainType}.${ext}]`;
+		});
+		resultStr = parts.join('\n');
+	}
+
+	let lines = resultStr.split('\n');
+	if (lines.length > maxLines) {
+		const total = lines.length;
+		lines = lines.slice(0, maxLines);
+		lines.push(t('tool.moreLines', { count: total - maxLines }));
+	}
+
+	return (
+		<div className="flex flex-col flex-1 min-w-0">
+			{lines.map((line, i) => (
+				<div key={i} className="truncate">
+					{line}
+				</div>
+			))}
+		</div>
+	);
+}
+
+export function defaultRenderConfirmBody(call: ToolCallBlock): ReactNode {
+	return (
+		<div className="w-full max-w-full overflow-hidden text-ellipsis truncate">
+			<div className="text-secondary-foreground">{call.input}</div>
+		</div>
+	);
+}
+
+/**
+ * Default group layout: each call is an independent block with a state icon,
+ * `displayName(args)` header line, and (optionally) a corner-line-prefixed
+ * result block beneath it. Used by tools without a custom `renderGroup`,
+ * e.g. arbitrary MCP tools.
+ *
+ * `getDisplayName` / `renderCallArgs` / `renderResult` are passed in from
+ * `index.ts` so this function stays decoupled from the renderer registry.
+ */
+export function defaultRenderGroup(
+	calls: ToolCallWithResult[],
+	_t: TFunction,
+	resolvers: {
+		getDisplayName: (call: ToolCallBlock) => string;
+		renderCallArgs: (call: ToolCallBlock) => ReactNode;
+		renderResult: (call: ToolCallBlock, result: ToolResultBlock) => ReactNode;
+	},
+): ReactNode {
+	return (
+		<>
+			{calls.map(({ call, result }) => {
+				const displayName = resolvers.getDisplayName(call);
+				const args = resolvers.renderCallArgs(call);
+				const resultContent = result ? resolvers.renderResult(call, result) : null;
+				return (
+					<Collapsible key={call.id} className="flex flex-col w-full max-w-full text-sm">
+						<CollapsibleTrigger asChild>
+							<Button
+								variant={'ghost'}
+								className="group hover:bg-transparent data-[state=open]:bg-transparent justify-start px-0 gap-2 active:!translate-y-0"
+							>
+								<ToolStateIcon states={[result?.state]} />
+								<strong className="shrink-0 text-primary">{displayName}</strong>
+								{args && <span className="truncate min-w-0 text-left">{args}</span>}
+								{resultContent && (
+									<ChevronRight className="size-3 shrink-0 group-data-[state=open]:rotate-90" />
+								)}
+							</Button>
+						</CollapsibleTrigger>
+						{resultContent && (
+							<CollapsibleContent className="flex flex-row gap-x-2 pl-6 max-w-full">
+								<CornerLine />
+								{resultContent}
+							</CollapsibleContent>
+						)}
+					</Collapsible>
+				);
+			})}
+		</>
+	);
+}
diff --git a/examples/web_ui/frontend/src/components/chat/tool-renderers/DiffPreview.tsx b/examples/web_ui/frontend/src/components/chat/tool-renderers/DiffPreview.tsx
new file mode 100644
index 0000000..c222f95
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/chat/tool-renderers/DiffPreview.tsx
@@ -0,0 +1,204 @@
+import { ChevronDown, MoreHorizontal, Minus, Plus } from 'lucide-react';
+import type { ReactElement } from 'react';
+import { useMemo, useState } from 'react';
+import { Decoration, Diff, Hunk, parseDiff } from 'react-diff-view';
+import type { ChangeData, DiffType, GutterOptions, HunkData } from 'react-diff-view';
+
+import 'react-diff-view/style/index.css';
+
+const MAX_VISIBLE_DIFF_LINES = 18;
+
+interface DiffPreviewProps {
+	/**
+	 * Pre-computed unified-diff text (produced by the backend Edit / Write
+	 * tools and delivered via ``ToolResultBlock.metadata.diff``). It carries
+	 * absolute file line numbers and naturally handles multi-hunk diffs from
+	 * ``replace_all``. The component renders nothing if this is empty.
+	 */
+	unifiedDiff: string;
+}
+
+function hunkLineCount(hunk: HunkData): number {
+	return hunk.changes.length;
+}
+
+function getVisibleHunks(hunks: HunkData[], expanded: boolean): HunkData[] {
+	if (expanded) return hunks;
+
+	let visibleLineCount = 0;
+	const visibleHunks: HunkData[] = [];
+
+	for (const hunk of hunks) {
+		const remaining = MAX_VISIBLE_DIFF_LINES - visibleLineCount;
+		if (remaining <= 0) break;
+		const hunkLines = hunkLineCount(hunk);
+		if (hunkLines <= remaining) {
+			visibleHunks.push(hunk);
+			visibleLineCount += hunkLines;
+			continue;
+		}
+		// Hunk doesn't fit in the remaining budget. If we haven't shown
+		// anything yet (typical for new-file / full-rewrite diffs that
+		// produce a single very large hunk), include a truncated slice so
+		// the user still sees the start of the change. Otherwise stop so
+		// we never overshoot ``MAX_VISIBLE_DIFF_LINES``.
+		if (visibleHunks.length === 0) {
+			visibleHunks.push(truncateHunkChanges(hunk, remaining));
+		}
+		break;
+	}
+
+	return visibleHunks;
+}
+
+/**
+ * Build a new ``HunkData`` containing only the first ``maxLines`` changes of
+ * ``hunk``. ``oldLines`` / ``newLines`` are recomputed from the slice so
+ * react-diff-view's line-number accounting stays internally consistent.
+ */
+function truncateHunkChanges(hunk: HunkData, maxLines: number): HunkData {
+	if (hunk.changes.length <= maxLines) return hunk;
+	const changes = hunk.changes.slice(0, maxLines);
+	let oldLines = 0;
+	let newLines = 0;
+	for (const change of changes) {
+		if (change.type === 'normal') {
+			oldLines += 1;
+			newLines += 1;
+		} else if (change.type === 'delete') {
+			oldLines += 1;
+		} else if (change.type === 'insert') {
+			newLines += 1;
+		}
+	}
+	return { ...hunk, changes, oldLines, newLines };
+}
+
+function countHiddenLines(allHunks: HunkData[], visibleHunks: HunkData[]): number {
+	const total = allHunks.reduce((sum, hunk) => sum + hunkLineCount(hunk), 0);
+	const visible = visibleHunks.reduce((sum, hunk) => sum + hunkLineCount(hunk), 0);
+	return Math.max(0, total - visible);
+}
+
+function getLineClassName({ changes }: { changes: Array<{ type: string }> }): string {
+	if (changes.some((change) => change.type === 'insert')) {
+		return 'bg-emerald-500/10';
+	}
+	if (changes.some((change) => change.type === 'delete')) {
+		return 'bg-red-500/10';
+	}
+	return 'bg-transparent';
+}
+
+// Pick the line number we want to display in the single visible gutter column.
+// - normal rows show the new-side line number (mirrors GitHub's unified view)
+// - insert / delete rows only have one `lineNumber` field, so use it directly
+function getDisplayedLineNumber(change: ChangeData): number | undefined {
+	if (change.type === 'normal') return change.newLineNumber;
+	return change.lineNumber;
+}
+
+// Render only the "new" side of each row. The "old" side <col> is removed
+// from the table layout via `visibility: collapse` (see arbitrary variants
+// on the table className below), so the unified diff effectively renders
+// as a single gutter column showing `<line-number> +/-`.
+function renderGutter({ change, side }: GutterOptions) {
+	if (side === 'old') return null;
+
+	let marker = null;
+	if (change.type === 'insert') {
+		marker = <Plus className="size-2.5 text-emerald-600 dark:text-emerald-400" />;
+	} else if (change.type === 'delete') {
+		marker = <Minus className="size-2.5 text-red-600 dark:text-red-400" />;
+	}
+
+	return (
+		<span className="inline-flex w-full items-center justify-between tabular-nums">
+			<span>{getDisplayedLineNumber(change)}</span>
+			{marker}
+		</span>
+	);
+}
+
+// Lines between two consecutive hunks that the unified diff omitted.
+// ``hunk.oldStart`` is 1-based and ``oldLines`` is the count of old-side
+// lines covered (including context). So the next hunk's ``oldStart`` minus
+// the end of the previous hunk gives the gap.
+function gapLinesBetween(prev: HunkData, next: HunkData): number {
+	return next.oldStart - (prev.oldStart + prev.oldLines);
+}
+
+export function DiffPreview({ unifiedDiff }: DiffPreviewProps) {
+	const [expanded, setExpanded] = useState(false);
+	const diffFile = useMemo(
+		() => parseDiff(unifiedDiff, { nearbySequences: 'zip' })[0],
+		[unifiedDiff],
+	);
+
+	if (!diffFile || diffFile.hunks.length === 0) {
+		return <div className="text-xs text-muted-foreground">No textual changes detected.</div>;
+	}
+
+	const visibleHunks = getVisibleHunks(diffFile.hunks, expanded);
+	const hiddenLines = countHiddenLines(diffFile.hunks, visibleHunks);
+
+	return (
+		<Diff
+			diffType={diffFile.type as DiffType}
+			hunks={visibleHunks}
+			viewType="unified"
+			renderGutter={renderGutter}
+			className="w-full border-collapse font-mono text-xs leading-5 [&>colgroup>col:first-child]:!w-0 [&>colgroup>col:first-child]:[visibility:collapse] [&_td.diff-gutter:first-of-type]:!p-0 [&_td.diff-gutter:first-of-type]:!border-r-0 [&_td.diff-gutter:first-of-type]:!w-0"
+			hunkClassName="align-top"
+			lineClassName="align-top"
+			gutterClassName="select-none border-r border-border px-2 text-right text-muted-foreground"
+			codeClassName="whitespace-pre-wrap break-all px-3"
+			generateLineClassName={getLineClassName}
+		>
+			{(hunks) => {
+				const children: ReactElement[] = [];
+
+				hunks.forEach((hunk, idx) => {
+					if (idx > 0) {
+						// Insert an ellipsis decoration between hunks so it's
+						// visually obvious there are skipped lines between
+						// e.g. an edit at line 20 and another at line 70.
+						const gap = gapLinesBetween(hunks[idx - 1], hunk);
+						children.push(
+							<Decoration key={`gap-${hunk.oldStart}-${hunk.newStart}`}>
+								<div className="flex items-center gap-2 border-y border-dashed border-border bg-muted/30 px-3 py-1 text-[10px] text-muted-foreground select-none">
+									<MoreHorizontal className="h-3 w-3" />
+									<span className="tabular-nums">
+										{gap > 0
+											? `${gap} unchanged line${gap === 1 ? '' : 's'}`
+											: 'unchanged lines'}
+									</span>
+								</div>
+							</Decoration>,
+						);
+					}
+					children.push(
+						<Hunk key={`hunk-${hunk.oldStart}-${hunk.newStart}`} hunk={hunk} />,
+					);
+				});
+
+				if (hiddenLines > 0) {
+					children.push(
+						<Decoration key="collapsed-diff-lines">
+							<button
+								type="button"
+								className="flex w-full items-center justify-center gap-1 border-t border-border bg-muted/50 px-3 py-2 text-xs text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+								onClick={() => setExpanded(true)}
+							>
+								<ChevronDown className="h-3.5 w-3.5" />
+								{hiddenLines} more lines (click to expand)
+							</button>
+						</Decoration>,
+					);
+				}
+
+				return children;
+			}}
+		</Diff>
+	);
+}
diff --git a/examples/web_ui/frontend/src/components/chat/tool-renderers/EditRenderer.tsx b/examples/web_ui/frontend/src/components/chat/tool-renderers/EditRenderer.tsx
new file mode 100644
index 0000000..54286e1
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/chat/tool-renderers/EditRenderer.tsx
@@ -0,0 +1,108 @@
+import unidiff from 'unidiff';
+
+import {
+	defaultGetDisplayName,
+	defaultRenderCallArgs,
+	defaultRenderGroup,
+	defaultRenderResult,
+} from './DefaultRenderer';
+import { DiffPreview } from './DiffPreview';
+import type { ToolRenderer } from './types';
+import {
+	countDiffStats,
+	DiffStats,
+	getFilePath,
+	getResultDiff,
+	parseInput,
+	tryGetFileName,
+} from '@/components/chat/tool-renderers/_shared.tsx';
+
+/**
+ * Count the real inserted / deleted lines between ``oldText`` and ``newText``
+ * by computing a unified diff and tallying the leading ``+`` / ``-`` markers.
+ * This is the per-occurrence diff size — for ``replace_all`` the backend
+ * reports the totalled counts via ``result.metadata`` (see ``countDiffStats``).
+ */
+function countLineChanges(
+	oldText: string,
+	newText: string,
+): { insertions: number; deletions: number } {
+	const diffText = unidiff.diffAsText(oldText, newText, { context: 0 });
+	return countDiffStats(diffText);
+}
+
+function renderEditDiff(result: { metadata?: Record<string, unknown> }) {
+	// The post-execution diff is always produced by the backend Edit tool
+	// (with absolute line numbers and one hunk per replaced occurrence).
+	// If it's missing we deliberately render nothing — falling back to a
+	// client-side diff of ``old_string`` / ``new_string`` would silently
+	// produce misleading line numbers and miss the other replace_all
+	// occurrences.
+	const unifiedDiff = getResultDiff(result);
+	if (!unifiedDiff) return null;
+	return <DiffPreview unifiedDiff={unifiedDiff} />;
+}
+
+export const EditRenderer: ToolRenderer = {
+	getDisplayName: (call) => call.name,
+
+	renderCallArgs: (call) => {
+		// While the tool-call JSON is still streaming, ``call.input`` is a
+		// partial dict and parsing yields the wrong file name / empty
+		// strings. Return an empty fragment (not ``null``) so the index.ts
+		// ``?? defaultRenderCallArgs`` fallback doesn't dump the raw JSON.
+		const fileName = tryGetFileName(call.input);
+		if (!fileName) return <></>;
+		const input = parseInput(call.input);
+		const oldString = typeof input.old_string === 'string' ? input.old_string : '';
+		const newString = typeof input.new_string === 'string' ? input.new_string : '';
+		// Use the real per-occurrence insert/delete counts rather than the
+		// raw line counts of old_string / new_string (which over-count when
+		// most lines are unchanged context).
+		const { insertions, deletions } = countLineChanges(oldString, newString);
+
+		return (
+			<div className="flex items-center gap-2 font-normal">
+				{fileName}
+				<DiffStats insertions={insertions} deletions={deletions} />
+			</div>
+		);
+	},
+
+	renderConfirmBody: (call) => (
+		<div className="w-full max-w-full overflow-hidden text-ellipsis truncate">
+			<div className="text-secondary-foreground">{getFilePath(call.input)}</div>
+		</div>
+	),
+
+	renderGroup: (calls, t) =>
+		defaultRenderGroup(calls, t, {
+			getDisplayName: (call) =>
+				EditRenderer.getDisplayName?.(call, t) ?? defaultGetDisplayName(call),
+			renderCallArgs: (call) => {
+				// When the backend has provided the post-execution unified diff
+				// (handles replace_all correctly), prefer its insert/delete
+				// counts over the per-occurrence client-side estimate.
+				const enriched = calls.find((c) => c.call.id === call.id);
+				const resultDiff = enriched?.result
+					? getResultDiff(enriched.result as { metadata?: Record<string, unknown> })
+					: undefined;
+				if (resultDiff) {
+					const fileName = tryGetFileName(call.input);
+					if (!fileName) return null;
+					const { insertions, deletions } = countDiffStats(resultDiff);
+					return (
+						<div className="flex items-center gap-2 font-normal">
+							{fileName}
+							<DiffStats insertions={insertions} deletions={deletions} />
+						</div>
+					);
+				}
+				return EditRenderer.renderCallArgs?.(call, t) ?? defaultRenderCallArgs(call);
+			},
+			renderResult: (call, result) =>
+				(result.state === 'success' ? renderEditDiff(result) : null) ??
+				EditRenderer.renderResult?.(call, result, t) ??
+				defaultRenderResult(call, result, t),
+		}),
+};
diff --git a/examples/web_ui/frontend/src/components/chat/tool-renderers/GlobRenderer.tsx b/examples/web_ui/frontend/src/components/chat/tool-renderers/GlobRenderer.tsx
new file mode 100644
index 0000000..e823367
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/chat/tool-renderers/GlobRenderer.tsx
@@ -0,0 +1,30 @@
+import { ToolCallGroupList } from './_shared';
+import type { ToolRenderer } from './types';
+
+function parseInput(input: string): Record<string, unknown> {
+	try {
+		return JSON.parse(input);
+	} catch {
+		return {};
+	}
+}
+
+function getPattern(input: string): string {
+	const { pattern } = parseInput(input) as { pattern?: string };
+	return pattern || input;
+}
+
+export const GlobRenderer: ToolRenderer = {
+	getDisplayName: (_call, t) => t('tool.glob.name'),
+
+	renderCallArgs: (call) => getPattern(call.input),
+
+	renderGroup: (calls, t) => (
+		<ToolCallGroupList
+			calls={calls}
+			inline
+			label={<strong className="truncate text-primary text-sm">{t('tool.glob.name')}</strong>}
+			renderItem={(item) => getPattern(item.call.input)}
+		/>
+	),
+};
diff --git a/examples/web_ui/frontend/src/components/chat/tool-renderers/GrepRenderer.tsx b/examples/web_ui/frontend/src/components/chat/tool-renderers/GrepRenderer.tsx
new file mode 100644
index 0000000..656c3ec
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/chat/tool-renderers/GrepRenderer.tsx
@@ -0,0 +1,30 @@
+import { ToolCallGroupList } from './_shared';
+import type { ToolRenderer } from './types';
+
+function parseInput(input: string): Record<string, unknown> {
+	try {
+		return JSON.parse(input);
+	} catch {
+		return {};
+	}
+}
+
+function getPattern(input: string): string {
+	const { pattern } = parseInput(input) as { pattern?: string };
+	return pattern || input;
+}
+
+export const GrepRenderer: ToolRenderer = {
+	getDisplayName: (_call, t) => t('tool.grep.name'),
+
+	renderCallArgs: (call) => getPattern(call.input),
+
+	renderGroup: (calls, t) => (
+		<ToolCallGroupList
+			calls={calls}
+			inline
+			label={<strong className="truncate text-primary text-sm">{t('tool.grep.name')}</strong>}
+			renderItem={(item) => getPattern(item.call.input)}
+		/>
+	),
+};
diff --git a/examples/web_ui/frontend/src/components/chat/tool-renderers/ReadRenderer.tsx b/examples/web_ui/frontend/src/components/chat/tool-renderers/ReadRenderer.tsx
new file mode 100644
index 0000000..e74376c
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/chat/tool-renderers/ReadRenderer.tsx
@@ -0,0 +1,116 @@
+/* eslint-disable react-refresh/only-export-components -- renderer constant is co-located with its inline component by design */
+import type { ToolResultBlock } from '@agentscope-ai/agentscope/message';
+import { ChevronRight } from 'lucide-react';
+import { useState } from 'react';
+
+import { CornerLine, getFilePath, ToolStateIcon } from './_shared';
+import type { TFunction, ToolCallWithResult, ToolRenderer } from './types';
+import { Button } from '@/components/ui/button.tsx';
+import { Collapsible, CollapsibleContent, CollapsibleTrigger } from '@/components/ui/collapsible';
+import { formatNumber } from '@/utils/common';
+
+/** Count lines in a tool result's output string, including text content from
+ * non-text blocks. Returns 0 when the result is missing or empty. */
+function countResultLines(result?: ToolResultBlock): number {
+	if (!result) return 0;
+	let str: string;
+	if (typeof result.output === 'string') {
+		str = result.output;
+	} else {
+		str = result.output.map((b) => (b.type === 'text' ? b.text : '')).join('\n');
+	}
+	if (!str) return 0;
+	return str.split('\n').length;
+}
+
+/** Collapse consecutive Read calls of the same `file_path` into one bucket so
+ * the path is shown once, followed by one corner-row per call. Order is
+ * preserved; a different path or a re-occurrence after another path starts a
+ * new bucket. */
+function groupByConsecutivePath(
+	calls: ToolCallWithResult[],
+): Array<{ path: string; calls: ToolCallWithResult[] }> {
+	const groups: Array<{ path: string; calls: ToolCallWithResult[] }> = [];
+	for (const item of calls) {
+		const path = getFilePath(item.call.input);
+		const last = groups[groups.length - 1];
+		if (last && last.path === path) {
+			last.calls.push(item);
+		} else {
+			groups.push({ path, calls: [item] });
+		}
+	}
+	return groups;
+}
+
+function ReadGroup({ calls, t }: { calls: ToolCallWithResult[]; t: TFunction }) {
+	const [open, setOpen] = useState(false);
+	const name = t('tool.read.name');
+
+	return (
+		<Collapsible open={open} onOpenChange={setOpen} className="flex flex-col w-full ">
+			<CollapsibleTrigger asChild>
+				<Button
+					variant={'ghost'}
+					className="group hover:bg-transparent data-[state=open]:bg-transparent justify-start px-0 gap-2 active:!translate-y-0"
+				>
+					<ToolStateIcon states={calls.map((c) => c.result?.state)} />
+					<span className="flex items-center text-sm truncate gap-1">
+						<strong className="text-primary">{name}</strong>
+						{t('tool.read.fileCount', { count: calls.length })}
+					</span>
+					<ChevronRight className="size-3 group-data-[state=open]:rotate-90" />
+				</Button>
+			</CollapsibleTrigger>
+			<CollapsibleContent className="pl-6 pt-2 flex flex-col gap-y-2 text-sm">
+				{groupByConsecutivePath(calls).map((group, gIdx) => (
+					<div key={gIdx} className="flex flex-col min-w-0">
+						<div className="truncate">
+							{/*<strong className="text-primary">{name}</strong>*/}
+							{/*<span className="text-muted-foreground">({group.path})</span>*/}
+							<span
+								className={
+									'text-xs !overflow-visible !whitespace-normal !text-clip break-all'
+								}
+							>
+								{group.path}
+							</span>
+						</div>
+						{group.calls.map(({ call, result }) => {
+							if (!result) return null;
+							const lines = countResultLines(result);
+							return (
+								<div
+									key={call.id}
+									className="flex flex-row gap-x-2 items-center pl-2 text-xs"
+								>
+									<CornerLine />
+									<span className="text-muted-foreground">
+										{t('tool.read.lineCount', {
+											count: lines,
+											formatted: formatNumber(lines),
+										})}
+									</span>
+								</div>
+							);
+						})}
+					</div>
+				))}
+			</CollapsibleContent>
+		</Collapsible>
+	);
+}
+
+export const ReadRenderer: ToolRenderer = {
+	getDisplayName: (_call, t) => t('tool.read.name'),
+
+	renderCallArgs: (call) => getFilePath(call.input),
+
+	renderConfirmBody: (call) => (
+		<div className="w-full max-w-full overflow-hidden text-ellipsis truncate">
+			<div className="text-secondary-foreground">{getFilePath(call.input)}</div>
+		</div>
+	),
+
+	renderGroup: (calls, t) => <ReadGroup calls={calls} t={t} />,
+};
diff --git a/examples/web_ui/frontend/src/components/chat/tool-renderers/TaskCreateRenderer.tsx b/examples/web_ui/frontend/src/components/chat/tool-renderers/TaskCreateRenderer.tsx
new file mode 100644
index 0000000..e4340b7
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/chat/tool-renderers/TaskCreateRenderer.tsx
@@ -0,0 +1,91 @@
+/* eslint-disable react-refresh/only-export-components -- renderer constant is co-located with its inline component by design */
+import { useState } from 'react';
+
+import { CornerLine, ToolStateIcon } from './_shared';
+import type { TFunction, ToolCallWithResult, ToolRenderer } from './types';
+import { Collapsible, CollapsibleContent, CollapsibleTrigger } from '@/components/ui/collapsible';
+
+function parseInput(input: string): Record<string, unknown> {
+	try {
+		return JSON.parse(input);
+	} catch {
+		return {};
+	}
+}
+
+/**
+ * Collapsed: "TaskCreate  Created 3 tasks ..."
+ * Expanded:
+ *   TaskCreate  Created 3 tasks
+ *     Research duck facts
+ *       Find five interesting facts about ducks
+ *     Write summary
+ *       Compile the research into a brief summary
+ *     Review code
+ *       Check for bugs and style issues
+ */
+function TaskCreateGroup({ calls, t }: { calls: ToolCallWithResult[]; t: TFunction }) {
+	const [open, setOpen] = useState(false);
+
+	return (
+		<Collapsible open={open} onOpenChange={setOpen} className="flex flex-col w-full">
+			<CollapsibleTrigger className="flex flex-row gap-x-2 w-full max-w-full items-center cursor-pointer text-left">
+				<ToolStateIcon states={calls.map((c) => c.result?.state)} />
+				<span className="text-sm flex-1 min-w-0 truncate">
+					<strong className="text-primary">{t('tool.taskCreate.label')}</strong>{' '}
+					{t('tool.taskCreate.count', { count: calls.length })}
+					{!open && <span className="text-muted-foreground"> ...</span>}
+				</span>
+			</CollapsibleTrigger>
+			<CollapsibleContent className="pl-6 pt-2 flex flex-col gap-y-2 text-sm">
+				{calls.map(({ call, result }) => {
+					const input = parseInput(call.input);
+					const subject = (input.subject as string) || '(untitled)';
+					const description = (input.description as string) || '';
+					// Extract the numeric task id from result text:
+					// "Task (id=3) created successfully: ..."
+					const resultText =
+						typeof result?.output === 'string'
+							? result.output
+							: Array.isArray(result?.output)
+								? result.output.map((b) => ('text' in b ? b.text : '')).join('')
+								: '';
+					const idMatch = resultText.match(/^Task $id=(\d+)$/);
+					const taskId = idMatch ? idMatch[1] : null;
+					return (
+						<div key={call.id} className="flex flex-col min-w-0">
+							<span className="text-xs break-all font-medium">
+								{taskId && (
+									<span className="text-muted-foreground font-mono">
+										#{taskId}
+									</span>
+								)}
+								{taskId && ' '}
+								{subject}
+							</span>
+							{description && (
+								<div className="flex flex-row gap-x-2 items-start pl-2 text-xs">
+									<CornerLine />
+									<span className="text-muted-foreground break-all">
+										{description}
+									</span>
+								</div>
+							)}
+						</div>
+					);
+				})}
+			</CollapsibleContent>
+		</Collapsible>
+	);
+}
+
+export const TaskCreateRenderer: ToolRenderer = {
+	getDisplayName: (_call, t) => t('tool.taskCreate.name'),
+
+	renderCallArgs: (call) => {
+		const input = parseInput(call.input);
+		return (input.subject as string) || '';
+	},
+
+	renderGroup: (calls, t) => <TaskCreateGroup calls={calls} t={t} />,
+};
diff --git a/examples/web_ui/frontend/src/components/chat/tool-renderers/WriteRenderer.tsx b/examples/web_ui/frontend/src/components/chat/tool-renderers/WriteRenderer.tsx
new file mode 100644
index 0000000..a5d63b3
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/chat/tool-renderers/WriteRenderer.tsx
@@ -0,0 +1,93 @@
+import {
+	defaultGetDisplayName,
+	defaultRenderCallArgs,
+	defaultRenderGroup,
+	defaultRenderResult,
+} from './DefaultRenderer';
+import { DiffPreview } from './DiffPreview';
+import type { ToolRenderer } from './types';
+import {
+	countDiffStats,
+	DiffStats,
+	getFilePath,
+	getResultDiff,
+	tryGetFileName,
+} from '@/components/chat/tool-renderers/_shared.tsx';
+
+export const WriteRenderer: ToolRenderer = {
+	getDisplayName: (call) => call.name,
+
+	renderCallArgs: (call) => {
+		// While the tool-call JSON is still streaming, ``call.input`` is a
+		// partial dict (e.g. ``{"file_path": "foo", "content": "...``) and
+		// parsing yields the wrong file name or none at all. Render an empty
+		// fragment (not ``null``) so the index.ts ``?? defaultRenderCallArgs``
+		// fallback doesn't kick in and dump the raw JSON string.
+		const fileName = tryGetFileName(call.input);
+		if (!fileName) return <></>;
+		// Pre-execution we only know the new ``content`` (not the previous
+		// file body), so any ``+N`` count would be misleading on overwrites.
+		// The post-execution renderGroup override below adds ``+N -M`` once
+		// ``metadata.diff`` arrives.
+		return <div className="flex items-center gap-2 font-normal">{fileName}</div>;
+	},
+
+	renderConfirmBody: (call) => (
+		<div className="w-full max-w-full overflow-hidden text-ellipsis truncate">
+			<div className="text-secondary-foreground">{getFilePath(call.input)}</div>
+		</div>
+	),
+
+	renderResult: (call, result, t) => {
+		if (result.state === 'success') {
+			// The backend Write tool always attaches a unified diff in
+			// ``metadata.diff`` (correctly representing both new-file
+			// creation against /dev/null and overwrites of existing files
+			// with absolute line numbers). If it's missing we fall through
+			// rather than render a misleading client-side diff.
+			const unifiedDiff = getResultDiff(result as { metadata?: Record<string, unknown> });
+			if (unifiedDiff) {
+				return <DiffPreview unifiedDiff={unifiedDiff} />;
+			}
+			return undefined;
+		}
+		if (call.state === 'asking' || !result || result.state === 'running') {
+			return t('common.running');
+		}
+		if (result.state === 'interrupted') {
+			return t('common.interrupted');
+		}
+		return undefined;
+	},
+
+	renderGroup: (calls, t) =>
+		defaultRenderGroup(calls, t, {
+			getDisplayName: (call) =>
+				WriteRenderer.getDisplayName?.(call, t) ?? defaultGetDisplayName(call),
+			renderCallArgs: (call) => {
+				// Once the backend has produced the post-execution unified
+				// diff, compute and show the real ``+N -M`` stats — this
+				// correctly accounts for overwrites of existing files
+				// (which the pre-execution renderCallArgs cannot know).
+				const enriched = calls.find((c) => c.call.id === call.id);
+				const resultDiff = enriched?.result
+					? getResultDiff(enriched.result as { metadata?: Record<string, unknown> })
+					: undefined;
+				if (resultDiff) {
+					const fileName = tryGetFileName(call.input);
+					if (!fileName) return null;
+					const { insertions, deletions } = countDiffStats(resultDiff);
+					return (
+						<div className="flex items-center gap-2 font-normal">
+							{fileName}
+							<DiffStats insertions={insertions} deletions={deletions} />
+						</div>
+					);
+				}
+				return WriteRenderer.renderCallArgs?.(call, t) ?? defaultRenderCallArgs(call);
+			},
+			renderResult: (call, result) =>
+				WriteRenderer.renderResult?.(call, result, t) ??
+				defaultRenderResult(call, result, t),
+		}),
+};
diff --git a/examples/web_ui/frontend/src/components/chat/tool-renderers/_shared.tsx b/examples/web_ui/frontend/src/components/chat/tool-renderers/_shared.tsx
new file mode 100644
index 0000000..33b6d3a
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/chat/tool-renderers/_shared.tsx
@@ -0,0 +1,207 @@
+import type { ToolResultBlock } from '@agentscope-ai/agentscope/message';
+import { Circle, Minus, Plus } from 'lucide-react';
+import type { ReactNode } from 'react';
+
+import type { ToolCallWithResult } from './types';
+import lineCornerSvg from '@/assets/images/line-corner.svg';
+import lineVerticalSvg from '@/assets/images/line-vertical.svg';
+import { formatNumber } from '@/utils/common.ts';
+
+/**
+ * Pick the connector image for an item at `index` of `total`:
+ * corner for the last row, vertical otherwise.
+ */
+function getLineImage(index: number, total: number): string {
+	return index === total - 1 ? lineCornerSvg : lineVerticalSvg;
+}
+
+/**
+ * Single tree-line cell. Use inside flex rows where one column is the line
+ * and the next is the actual content.
+ */
+export function TreeLine({
+	index,
+	total,
+	className = 'w-3 h-full',
+}: {
+	index: number;
+	total: number;
+	className?: string;
+}) {
+	return (
+		<div className="flex-shrink-0 h-full items-center">
+			<img src={getLineImage(index, total)} alt="" className={className} />
+		</div>
+	);
+}
+
+/**
+ * Single corner-only line, used when only one trailing item exists.
+ */
+export function CornerLine({ className = 'w-3 h-4' }: { className?: string }) {
+	return (
+		<div className="flex-shrink-0">
+			<img src={lineCornerSvg} alt="" className={className} />
+		</div>
+	);
+}
+
+/**
+ * Aggregated state icon over a list of tool result states. Mirrors the
+ * pre-refactor priority: running/undefined → pulsing muted; all success →
+ * green; any error → red; any interrupted → yellow; otherwise muted.
+ */
+export function ToolStateIcon({ states }: { states: (ToolResultBlock['state'] | undefined)[] }) {
+	if (states.includes('running') || states.includes(undefined)) {
+		return (
+			<Circle className="size-2.5 text-muted-foreground fill-muted-foreground animate-pulse shrink-0" />
+		);
+	}
+	if (states.every((state) => state === 'success')) {
+		return <Circle className="size-2.5 text-green-500 fill-green-500 shrink-0" />;
+	}
+	if (states.some((state) => state === 'error')) {
+		return <Circle className="size-2.5 text-red-500 fill-red-500 shrink-0" />;
+	}
+	if (states.some((state) => state === 'interrupted')) {
+		return <Circle className="size-2.5 text-yellow-500 fill-yellow-500 shrink-0" />;
+	}
+	return <Circle className="size-2.5 text-muted-foreground fill-muted-foreground shrink-0" />;
+}
+
+/**
+ * Header + indented item list, used by Read / Glob / Grep group renderers.
+ * Each item shows only the per-call args (no result), connected by SVG tree
+ * lines. `inline` lays items horizontally instead of stacked.
+ */
+export function ToolCallGroupList({
+	calls,
+	label,
+	renderItem,
+	inline,
+}: {
+	calls: ToolCallWithResult[];
+	label: ReactNode;
+	renderItem: (item: ToolCallWithResult) => ReactNode;
+	inline?: boolean;
+}) {
+	return (
+		<div className="flex flex-col w-full">
+			<div className="flex flex-row gap-x-2 w-full max-w-full items-center">
+				<ToolStateIcon states={calls.map((item) => item.result?.state)} />
+				{label}
+			</div>
+			<div className={`flex ${inline ? 'flex-row' : 'flex-col'} gap-x-2 pl-6 max-w-full`}>
+				{calls.map((item, index) => (
+					<div
+						key={item.call.id}
+						className="flex flex-row gap-x-2 w-full max-w-full items-stretch"
+					>
+						<TreeLine index={index} total={calls.length} />
+						<div className="truncate flex-1 min-w-0 text-sm">{renderItem(item)}</div>
+					</div>
+				))}
+			</div>
+		</div>
+	);
+}
+
+/**
+ * Parse the input arguments from the given string.
+ * @param input
+ * @returns The JSON Record or empty object if parsing fails.
+ */
+export function parseInput(input: string): Record<string, unknown> {
+	try {
+		return JSON.parse(input);
+	} catch {
+		return {};
+	}
+}
+
+/**
+ * Get the filepath from the input arguments
+ * @param input
+ * @returns The filepath from the input string
+ */
+export function getFilePath(input: string): string {
+	const { file_path } = parseInput(input) as { file_path?: string };
+	return file_path || input;
+}
+
+/**
+ * Get the filename
+ * @param input
+ * @returns The filename from the input string, considering different OS path separators.
+ */
+export function getFileName(input: string): string {
+	const filePath = getFilePath(input);
+	const segments = filePath.split(/[/\\]+/).filter(Boolean);
+	return segments.length > 0 ? segments[segments.length - 1] : filePath;
+}
+
+/**
+ * Like ``getFileName`` but returns ``undefined`` when the input is not yet
+ * a fully parseable JSON object with a non-empty ``file_path`` field. Use
+ * this in ``renderCallArgs`` so partial JSON streamed during tool-call
+ * generation doesn't render a garbled file name (e.g. a fragment of the
+ * ``content`` field being mistaken for the path).
+ */
+export function tryGetFileName(input: string): string | undefined {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(input);
+	} catch {
+		return undefined;
+	}
+	if (!parsed || typeof parsed !== 'object') return undefined;
+	const filePath = (parsed as { file_path?: unknown }).file_path;
+	if (typeof filePath !== 'string' || filePath.length === 0) return undefined;
+	const segments = filePath.split(/[/\\]+/).filter(Boolean);
+	return segments.length > 0 ? segments[segments.length - 1] : filePath;
+}
+
+/**
+ * Tally inserted / deleted lines from a unified diff text. The leading
+ * ``+++`` / ``---`` lines (file headers) are excluded.
+ */
+export function countDiffStats(diffText: string): {
+	insertions: number;
+	deletions: number;
+} {
+	let insertions = 0;
+	let deletions = 0;
+	for (const line of diffText.split('\n')) {
+		if (line.startsWith('+') && !line.startsWith('+++')) insertions++;
+		else if (line.startsWith('-') && !line.startsWith('---')) deletions++;
+	}
+	return { insertions, deletions };
+}
+
+/**
+ * Extract the ``diff`` field from a ToolResultBlock metadata bag, returning
+ * ``undefined`` when missing or empty so callers can use it with ``??``.
+ */
+export function getResultDiff(result: { metadata?: Record<string, unknown> }): string | undefined {
+	const diff = result.metadata?.diff;
+	return typeof diff === 'string' && diff.length > 0 ? diff : undefined;
+}
+
+/**
+ * Compact ``+N -M`` badge used in tool call headers for Edit / Write to show
+ * how many lines were inserted and deleted.
+ */
+export function DiffStats({ insertions, deletions }: { insertions: number; deletions: number }) {
+	return (
+		<div className="flex items-center gap-0.5">
+			<div className="flex items-center text-emerald-600 dark:text-emerald-400">
+				<Plus className="size-2.5 stroke-2" />
+				{formatNumber(insertions)}
+			</div>
+			<div className="flex items-center text-red-600 dark:text-red-400">
+				<Minus className="size-2.5 stroke-2" />
+				{formatNumber(deletions)}
+			</div>
+		</div>
+	);
+}
diff --git a/examples/web_ui/frontend/src/components/chat/tool-renderers/index.ts b/examples/web_ui/frontend/src/components/chat/tool-renderers/index.ts
new file mode 100644
index 0000000..fa0f164
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/chat/tool-renderers/index.ts
@@ -0,0 +1,80 @@
+import type { ToolCallBlock, ToolResultBlock } from '@agentscope-ai/agentscope/message';
+import type { ReactNode } from 'react';
+
+import { BashRenderer } from './BashRenderer';
+import {
+	defaultGetDisplayName,
+	defaultRenderCallArgs,
+	defaultRenderConfirmBody,
+	defaultRenderGroup,
+	defaultRenderResult,
+} from './DefaultRenderer';
+import { EditRenderer } from './EditRenderer';
+import { GlobRenderer } from './GlobRenderer';
+import { GrepRenderer } from './GrepRenderer';
+import { ReadRenderer } from './ReadRenderer';
+import { TaskCreateRenderer } from './TaskCreateRenderer';
+import type { TFunction, ToolCallWithResult, ToolRenderer } from './types';
+import { WriteRenderer } from './WriteRenderer';
+
+const renderers: Record<string, ToolRenderer> = {
+	Bash: BashRenderer,
+	Read: ReadRenderer,
+	Write: WriteRenderer,
+	Edit: EditRenderer,
+	Glob: GlobRenderer,
+	Grep: GrepRenderer,
+	TaskCreate: TaskCreateRenderer,
+};
+
+function getRenderer(toolName: string): ToolRenderer {
+	return renderers[toolName] ?? {};
+}
+
+export function getDisplayName(call: ToolCallBlock, t: TFunction): string {
+	const r = getRenderer(call.name);
+	return r.getDisplayName?.(call, t) ?? defaultGetDisplayName(call);
+}
+
+export function renderCallArgs(call: ToolCallBlock, t: TFunction): ReactNode {
+	const r = getRenderer(call.name);
+	return r.renderCallArgs?.(call, t) ?? defaultRenderCallArgs(call);
+}
+
+export function renderResult(
+	call: ToolCallBlock,
+	result: ToolResultBlock,
+	t: TFunction,
+): ReactNode {
+	const r = getRenderer(call.name);
+	return r.renderResult?.(call, result, t) ?? defaultRenderResult(call, result, t);
+}
+
+export function renderConfirmBody(call: ToolCallBlock, t: TFunction): ReactNode {
+	const r = getRenderer(call.name);
+	return r.renderConfirmBody?.(call, t) ?? defaultRenderConfirmBody(call);
+}
+
+/**
+ * Render a group of consecutive tool calls of the same name.
+ *
+ * - If the tool's renderer defines `renderGroup`, delegate to it.
+ * - Otherwise fall back to `defaultRenderGroup`, wired with this registry's
+ *   resolvers so per-tool `getDisplayName` / `renderCallArgs` / `renderResult`
+ *   still apply.
+ */
+export function renderToolGroup(
+	toolName: string,
+	calls: ToolCallWithResult[],
+	t: TFunction,
+): ReactNode {
+	const r = getRenderer(toolName);
+	if (r.renderGroup) {
+		return r.renderGroup(calls, t);
+	}
+	return defaultRenderGroup(calls, t, {
+		getDisplayName: (call) => getDisplayName(call, t),
+		renderCallArgs: (call) => renderCallArgs(call, t),
+		renderResult: (call, result) => renderResult(call, result, t),
+	});
+}
diff --git a/examples/web_ui/frontend/src/components/chat/tool-renderers/types.ts b/examples/web_ui/frontend/src/components/chat/tool-renderers/types.ts
new file mode 100644
index 0000000..3fb7853
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/chat/tool-renderers/types.ts
@@ -0,0 +1,23 @@
+import type { ToolCallBlock, ToolResultBlock } from '@agentscope-ai/agentscope/message';
+import type { ReactNode } from 'react';
+
+export type TFunction = (key: string, params?: Record<string, unknown>) => string;
+
+export interface ToolCallWithResult {
+	call: ToolCallBlock;
+	result?: ToolResultBlock;
+}
+
+export interface ToolRenderer {
+	getDisplayName?: (call: ToolCallBlock, t: TFunction) => string;
+	renderCallArgs?: (call: ToolCallBlock, t: TFunction) => ReactNode;
+	renderResult?: (call: ToolCallBlock, result: ToolResultBlock, t: TFunction) => ReactNode;
+	renderConfirmBody?: (call: ToolCallBlock, t: TFunction) => ReactNode;
+	/**
+	 * Render a group of consecutive tool calls of the same name.
+	 * Receives the visible (non-truncated) calls — `MessageBubble` truncates
+	 * at the first `asking` call before invoking, and renders ConfirmCard
+	 * separately.
+	 */
+	renderGroup?: (calls: ToolCallWithResult[], t: TFunction) => ReactNode;
+}
diff --git a/examples/web_ui/frontend/src/components/dialog/AddSkillDialog.tsx b/examples/web_ui/frontend/src/components/dialog/AddSkillDialog.tsx
new file mode 100644
index 0000000..75141f9
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/dialog/AddSkillDialog.tsx
@@ -0,0 +1,83 @@
+import { CircleAlert, Loader2, PlusCircle } from 'lucide-react';
+import { useState, type ReactNode } from 'react';
+
+import { Button } from '@/components/ui/button';
+import {
+	Dialog,
+	DialogContent,
+	DialogDescription,
+	DialogFooter,
+	DialogHeader,
+	DialogTitle,
+	DialogTrigger,
+} from '@/components/ui/dialog';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+import { useTranslation } from '@/i18n/useI18n';
+
+interface AddSkillDialogProps {
+	children: ReactNode;
+	onAdd: (skillPath: string) => Promise<void>;
+}
+
+export function AddSkillDialog({ children, onAdd }: AddSkillDialogProps) {
+	const { t } = useTranslation();
+	const [open, setOpen] = useState(false);
+	const [skillPath, setSkillPath] = useState('');
+	const [loading, setLoading] = useState(false);
+	const [error, setError] = useState<string | null>(null);
+
+	const handleSubmit = async () => {
+		if (!skillPath.trim()) return;
+		setLoading(true);
+		setError(null);
+		try {
+			await onAdd(skillPath.trim());
+			setSkillPath('');
+			setOpen(false);
+		} catch (e) {
+			setError((e as Error).message);
+		} finally {
+			setLoading(false);
+		}
+	};
+
+	return (
+		<Dialog open={open} onOpenChange={setOpen}>
+			<DialogTrigger asChild>{children}</DialogTrigger>
+			<DialogContent className="!w-[500px] !max-w-[500px]">
+				<DialogHeader>
+					<DialogTitle>{t('dialog-skill-add.title')}</DialogTitle>
+					<DialogDescription>{t('dialog-skill-add.description')}</DialogDescription>
+				</DialogHeader>
+				<div className="flex flex-col gap-y-2">
+					<Label htmlFor="skill-path">{t('dialog-skill-add.pathLabel')}</Label>
+					<Input
+						id="skill-path"
+						placeholder={t('dialog-skill-add.pathPlaceholder')}
+						value={skillPath}
+						onChange={(e) => setSkillPath(e.target.value)}
+						onKeyDown={(e) => {
+							if (e.key === 'Enter') handleSubmit();
+						}}
+					/>
+					{error && <p className="text-destructive text-sm">{error}</p>}
+				</div>
+				<DialogFooter>
+					<Button variant="ghost" onClick={() => setOpen(false)} disabled={loading}>
+						<CircleAlert className="size-3.5" />
+						{t('common.cancel')}
+					</Button>
+					<Button onClick={handleSubmit} disabled={loading || !skillPath.trim()}>
+						{loading ? (
+							<Loader2 className="size-3.5 animate-spin" />
+						) : (
+							<PlusCircle className="size-3.5" />
+						)}
+						{loading ? t('dialog-mcp-create.adding') : t('common.add')}
+					</Button>
+				</DialogFooter>
+			</DialogContent>
+		</Dialog>
+	);
+}
diff --git a/examples/web_ui/frontend/src/components/dialog/AgentDialog.tsx b/examples/web_ui/frontend/src/components/dialog/AgentDialog.tsx
new file mode 100644
index 0000000..e217af6
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/dialog/AgentDialog.tsx
@@ -0,0 +1,137 @@
+import { CircleAlert, Loader2, PlusCircle } from 'lucide-react';
+import { useEffect, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import type { ContextConfig, InviteConfig, ReActConfig } from '@/api';
+import {
+	AgentFormFields,
+	defaultAgentFormValues,
+	type AgentFormValues,
+	type AgentSection,
+} from '@/components/form/AgentFormFields';
+import type { SchemaFormValue } from '@/components/form/SchemaForm';
+import { Alert, AlertDescription } from '@/components/ui/alert.tsx';
+import { Button } from '@/components/ui/button';
+import {
+	Dialog,
+	DialogContent,
+	DialogFooter,
+	DialogHeader,
+	DialogTitle,
+	DialogDescription,
+	DialogTrigger,
+} from '@/components/ui/dialog';
+import { useAgents } from '@/hooks/useAgents';
+import { useAgentSchema } from '@/hooks/useAgentSchema';
+import { formatApiErrorForAlert } from '@/lib/api-error';
+
+interface Props {
+	onCreated?: () => void;
+	triggerId?: string;
+}
+
+export function AgentDialog({ onCreated, triggerId }: Props) {
+	const { create } = useAgents();
+	const { t } = useTranslation();
+	const { schema } = useAgentSchema();
+	const [open, setOpen] = useState(false);
+	const [submitting, setSubmitting] = useState(false);
+	const [values, setValues] = useState<AgentFormValues | null>(null);
+	const [errorMsg, setErrorMsg] = useState('');
+
+	useEffect(() => {
+		if (open && schema && !values) {
+			setValues(defaultAgentFormValues(schema));
+		}
+		if (!open) {
+			setValues(null);
+			setErrorMsg('');
+		}
+	}, [open, schema, values]);
+
+	const handleChange = (section: AgentSection, key: string, value: SchemaFormValue) => {
+		setErrorMsg('');
+		setValues((prev) =>
+			prev ? { ...prev, [section]: { ...prev[section], [key]: value } } : prev,
+		);
+	};
+
+	const handleSubmit = async () => {
+		if (!values) return;
+		const name = (values.identity.name as string | undefined)?.trim();
+		if (!name) return;
+		setErrorMsg('');
+		setSubmitting(true);
+		try {
+			await create(
+				{
+					name,
+					system_prompt: values.identity.system_prompt as string | undefined,
+					context_config: values.context_config as unknown as ContextConfig,
+					react_config: values.react_config as unknown as ReActConfig,
+					invite_config: values.invite_config as unknown as InviteConfig,
+				},
+				{ silent: true },
+			);
+			setOpen(false);
+			onCreated?.();
+		} catch (e) {
+			setErrorMsg(formatApiErrorForAlert(e));
+		} finally {
+			setSubmitting(false);
+		}
+	};
+
+	const nameValid = !!(values?.identity.name as string | undefined)?.trim();
+
+	return (
+		<Dialog open={open} onOpenChange={setOpen}>
+			<DialogTrigger asChild>
+				<Button id={triggerId}>
+					<PlusCircle />
+					<span>{t('dialog-agent-create.trigger')}</span>
+				</Button>
+			</DialogTrigger>
+			<DialogContent className="!w-[500px] !max-w-[500px]">
+				<DialogHeader>
+					<DialogTitle>{t('dialog-agent-create.title')}</DialogTitle>
+					<DialogDescription className="sr-only">
+						{t('dialog-agent-create.description')}
+					</DialogDescription>
+				</DialogHeader>
+				<div className="no-scrollbar -mx-4 max-h-[75vh] overflow-y-auto px-4">
+					{schema && values ? (
+						<AgentFormFields schema={schema} values={values} onChange={handleChange} />
+					) : (
+						<p className="text-muted-foreground text-sm">{t('common.loading')}</p>
+					)}
+				</div>
+				{errorMsg && (
+					<Alert variant="destructive">
+						<CircleAlert />
+						<AlertDescription className="whitespace-pre-wrap">
+							{errorMsg}
+						</AlertDescription>
+					</Alert>
+				)}
+				<DialogFooter>
+					<Button variant="ghost" onClick={() => setOpen(false)} disabled={submitting}>
+						<CircleAlert className="size-3.5" />
+						{t('common.cancel')}
+					</Button>
+					<Button
+						onClick={handleSubmit}
+						disabled={!nameValid || submitting || !schema || !values}
+					>
+						{submitting ? (
+							<Loader2 className="size-3.5 animate-spin" />
+						) : (
+							<PlusCircle className="size-3.5" />
+						)}
+						{submitting ? t('common.creating') : t('common.create')}
+					</Button>
+				</DialogFooter>
+			</DialogContent>
+		</Dialog>
+	);
+}
diff --git a/examples/web_ui/frontend/src/components/dialog/CreateCredentialDialog.tsx b/examples/web_ui/frontend/src/components/dialog/CreateCredentialDialog.tsx
new file mode 100644
index 0000000..e76b7d5
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/dialog/CreateCredentialDialog.tsx
@@ -0,0 +1,152 @@
+import { CircleAlert, Loader2, PlusCircle } from 'lucide-react';
+import { useState, useEffect } from 'react';
+
+import { credentialApi } from '@/api';
+import type { CredentialSchema } from '@/api';
+import { SchemaForm, type SchemaFormValue } from '@/components/form/SchemaForm';
+import { Button } from '@/components/ui/button';
+import {
+	Dialog,
+	DialogContent,
+	DialogHeader,
+	DialogTitle,
+	DialogDescription,
+	DialogFooter,
+} from '@/components/ui/dialog';
+import { Field, FieldGroup, FieldLabel } from '@/components/ui/field.tsx';
+import {
+	Select,
+	SelectContent,
+	SelectItem,
+	SelectTrigger,
+	SelectValue,
+} from '@/components/ui/select';
+import { useCredentials } from '@/hooks/useCredentials';
+import { useTranslation } from '@/i18n/useI18n.ts';
+
+interface Props {
+	open: boolean;
+	onOpenChange: (open: boolean) => void;
+	onCreated?: () => void;
+	defaultType?: string;
+}
+
+export function CreateCredentialDialog({ open, onOpenChange, onCreated, defaultType }: Props) {
+	const { create } = useCredentials();
+	const { t } = useTranslation();
+	const [schemas, setSchemas] = useState<CredentialSchema[]>([]);
+	const [loadingSchemas, setLoadingSchemas] = useState(false);
+	const [selectedType, setSelectedType] = useState('');
+	const [values, setValues] = useState<Record<string, SchemaFormValue>>({});
+	const [submitting, setSubmitting] = useState(false);
+
+	useEffect(() => {
+		if (!open) return;
+		setLoadingSchemas(true);
+		credentialApi
+			.schemas()
+			.then((res) => {
+				setSchemas(res.schemas);
+				if (res.schemas.length > 0) {
+					const first = (res.schemas[0].properties.type?.const as string) ?? '';
+					setSelectedType(defaultType ?? first);
+				}
+			})
+			.finally(() => setLoadingSchemas(false));
+	}, [open, defaultType]);
+
+	const selectedSchema = schemas.find(
+		(s) => (s.properties.type?.const as string) === selectedType,
+	);
+
+	const handleTypeChange = (type: string) => {
+		setSelectedType(type);
+		setValues({});
+	};
+
+	const handleSubmit = async () => {
+		if (!selectedSchema) return;
+		setSubmitting(true);
+		try {
+			const data: Record<string, unknown> = { type: selectedType };
+			for (const [key, prop] of Object.entries(selectedSchema.properties)) {
+				if (key === 'id' || key === 'type' || prop.const !== undefined) continue;
+				const val = values[key];
+				if (val !== undefined && val !== '') data[key] = val;
+			}
+			await create({ data });
+			onOpenChange(false);
+			onCreated?.();
+		} finally {
+			setSubmitting(false);
+		}
+	};
+
+	return (
+		<Dialog open={open} onOpenChange={onOpenChange}>
+			<DialogContent className="!w-[500px] !max-w-[500px]">
+				<DialogHeader>
+					<DialogTitle>{t('dialog-credential-create.title')}</DialogTitle>
+					<DialogDescription>
+						{t('dialog-credential-create.description')}
+					</DialogDescription>
+				</DialogHeader>
+				<FieldGroup>
+					<Field>
+						<FieldLabel>{t('dialog-credential-create.selectType')}</FieldLabel>
+						<Select
+							value={selectedType}
+							onValueChange={handleTypeChange}
+							disabled={loadingSchemas}
+						>
+							<SelectTrigger>
+								<SelectValue
+									placeholder={
+										loadingSchemas
+											? t('common.loading')
+											: t('dialog-credential-create.selectTypePlaceholder')
+									}
+								/>
+							</SelectTrigger>
+							<SelectContent>
+								{schemas.map((s) => (
+									<SelectItem
+										key={s.properties.type?.const as string}
+										value={s.properties.type?.const as string}
+									>
+										{s.title}
+									</SelectItem>
+								))}
+							</SelectContent>
+						</Select>
+					</Field>
+					{selectedSchema && (
+						<SchemaForm
+							schema={selectedSchema}
+							values={values}
+							onChange={(key, val) => setValues((prev) => ({ ...prev, [key]: val }))}
+						/>
+					)}
+				</FieldGroup>
+				<DialogFooter>
+					<Button
+						variant="ghost"
+						onClick={() => onOpenChange(false)}
+						disabled={submitting}
+					>
+						<CircleAlert className="size-3.5" />
+						{t('common.cancel')}
+					</Button>
+					<Button onClick={handleSubmit} disabled={submitting || !selectedSchema}>
+						{submitting ? (
+							<Loader2 className="size-3.5 animate-spin" />
+						) : (
+							<PlusCircle className="size-3.5" />
+						)}
+						{submitting ? t('common.creating') : t('common.create')}
+					</Button>
+				</DialogFooter>
+			</DialogContent>
+		</Dialog>
+	);
+}
diff --git a/examples/web_ui/frontend/src/components/dialog/CreateKnowledgeBaseDialog.tsx b/examples/web_ui/frontend/src/components/dialog/CreateKnowledgeBaseDialog.tsx
new file mode 100644
index 0000000..bf6a4fc
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/dialog/CreateKnowledgeBaseDialog.tsx
@@ -0,0 +1,246 @@
+import { CircleAlert, Info, Loader2, PlusCircle } from 'lucide-react';
+import { useEffect, useMemo, useState } from 'react';
+
+import type { EmbeddingModelCard, EmbeddingModelConfig } from '@/api';
+import { DimensionSelect } from '@/components/select/DimensionSelect';
+import { EmbeddingSelect } from '@/components/select/EmbeddingSelect';
+import { Alert, AlertDescription, AlertTitle } from '@/components/ui/alert.tsx';
+import { Button } from '@/components/ui/button.tsx';
+import {
+	Dialog,
+	DialogContent,
+	DialogDescription,
+	DialogFooter,
+	DialogHeader,
+	DialogTitle,
+} from '@/components/ui/dialog.tsx';
+import { Field, FieldGroup, FieldLabel } from '@/components/ui/field.tsx';
+import { Input } from '@/components/ui/input.tsx';
+import { Textarea } from '@/components/ui/textarea.tsx';
+import { useKbEmbeddingModels } from '@/hooks/useKbEmbeddingModels';
+import { useKnowledgeBases } from '@/hooks/useKnowledgeBases';
+import { useTranslation } from '@/i18n/useI18n.ts';
+
+interface Props {
+	open: boolean;
+	onOpenChange: (open: boolean) => void;
+	onCreated?: (knowledgeBaseId: string) => void;
+	onAddCredential?: () => void;
+	/**
+	 * Bumped externally (e.g. after a credential is created) to ask the
+	 * embedding selector to refetch its options.
+	 */
+	credentialRefetchTrigger?: number;
+}
+
+interface SelectedEmbedding {
+	type: string;
+	credentialId: string;
+	model: string;
+	card: EmbeddingModelCard;
+}
+
+export function CreateKnowledgeBaseDialog({
+	open,
+	onOpenChange,
+	onCreated,
+	onAddCredential,
+	credentialRefetchTrigger,
+}: Props) {
+	const { t } = useTranslation();
+	const { create } = useKnowledgeBases();
+	const { providers, policy, loading } = useKbEmbeddingModels(credentialRefetchTrigger);
+
+	const [name, setName] = useState('');
+	const [description, setDescription] = useState('');
+	const [selected, setSelected] = useState<SelectedEmbedding | null>(null);
+	const [dimension, setDimension] = useState<number | null>(null);
+	const [submitting, setSubmitting] = useState(false);
+	const [errorKey, setErrorKey] = useState<string | null>(null);
+
+	useEffect(() => {
+		if (!open) {
+			setName('');
+			setDescription('');
+			setSelected(null);
+			setDimension(null);
+			setErrorKey(null);
+			setSubmitting(false);
+		}
+	}, [open]);
+
+	const dimensionOptions = useMemo<number[] | null>(() => {
+		if (!selected) return null;
+		const sd = selected.card.supported_dimensions;
+		return sd && sd.length > 0 ? sd : [selected.card.dimensions];
+	}, [selected]);
+
+	const handleSelectEmbedding = (sel: SelectedEmbedding) => {
+		setSelected(sel);
+		const sd = sel.card.supported_dimensions;
+		const defaultDim =
+			sd && sd.length > 0
+				? sd.includes(sel.card.dimensions)
+					? sel.card.dimensions
+					: sd[0]
+				: sel.card.dimensions;
+		setDimension(defaultDim);
+	};
+
+	const handleSubmit = async () => {
+		if (!name.trim()) {
+			setErrorKey('dialog-knowledge-base-create.errors.nameRequired');
+			return;
+		}
+		if (!selected) {
+			setErrorKey('dialog-knowledge-base-create.errors.embeddingRequired');
+			return;
+		}
+		if (dimension == null || dimension <= 0) {
+			setErrorKey('dialog-knowledge-base-create.errors.dimensionRequired');
+			return;
+		}
+		setErrorKey(null);
+		setSubmitting(true);
+		try {
+			const config: EmbeddingModelConfig = {
+				type: selected.type,
+				credential_id: selected.credentialId,
+				model: selected.model,
+				dimensions: dimension,
+				parameters: {},
+			};
+			const knowledgeBaseId = await create({
+				name: name.trim(),
+				description: description.trim(),
+				embedding_model_config: config,
+			});
+			onCreated?.(knowledgeBaseId);
+			onOpenChange(false);
+		} finally {
+			setSubmitting(false);
+		}
+	};
+
+	const isLockedPolicy = policy && policy.kind !== 'any';
+	const noCompatibleModels = !loading && providers.length === 0;
+
+	return (
+		<Dialog open={open} onOpenChange={onOpenChange}>
+			<DialogContent className="!w-[500px] !max-w-[500px]">
+				<DialogHeader>
+					<DialogTitle>{t('dialog-knowledge-base-create.title')}</DialogTitle>
+					<DialogDescription>
+						{t('dialog-knowledge-base-create.description')}
+					</DialogDescription>
+				</DialogHeader>
+
+				{isLockedPolicy && policy?.dimension != null && (
+					<Alert>
+						<Info className="size-4" />
+						<AlertTitle>
+							{t('dialog-knowledge-base-create.policy.lockedTitle', {
+								dimension: policy.dimension,
+							})}
+						</AlertTitle>
+						<AlertDescription>
+							{t('dialog-knowledge-base-create.policy.lockedDescription', {
+								dimension: policy.dimension,
+							})}
+						</AlertDescription>
+					</Alert>
+				)}
+
+				{noCompatibleModels && (
+					<Alert variant="destructive">
+						<CircleAlert className="size-4" />
+						<AlertTitle>
+							{t('dialog-knowledge-base-create.policy.noCompatibleTitle')}
+						</AlertTitle>
+						<AlertDescription>
+							{isLockedPolicy && policy?.dimension != null
+								? t('dialog-knowledge-base-create.policy.noCompatibleLocked', {
+										dimension: policy.dimension,
+									})
+								: t('dialog-knowledge-base-create.policy.noCompatibleAny')}
+						</AlertDescription>
+					</Alert>
+				)}
+
+				<FieldGroup>
+					<Field>
+						<FieldLabel>{t('dialog-knowledge-base-create.name.label')}</FieldLabel>
+						<Input
+							value={name}
+							onChange={(e) => setName(e.target.value)}
+							placeholder={t('dialog-knowledge-base-create.name.placeholder')}
+							disabled={submitting}
+						/>
+					</Field>
+					<Field>
+						<FieldLabel>
+							{t('dialog-knowledge-base-create.descriptionField.label')}
+						</FieldLabel>
+						<Textarea
+							value={description}
+							onChange={(e) => setDescription(e.target.value)}
+							placeholder={t(
+								'dialog-knowledge-base-create.descriptionField.placeholder',
+							)}
+							disabled={submitting}
+							rows={3}
+						/>
+					</Field>
+					<Field orientation="horizontal">
+						<FieldLabel>
+							{t('dialog-knowledge-base-create.embeddingModel.label')}
+						</FieldLabel>
+						<EmbeddingSelect
+							value={
+								selected
+									? {
+											type: selected.type,
+											credential_id: selected.credentialId,
+											model: selected.model,
+										}
+									: null
+							}
+							providers={providers}
+							loading={loading}
+							onChange={handleSelectEmbedding}
+							onAddCredential={onAddCredential}
+						/>
+					</Field>
+					<Field orientation="horizontal">
+						<FieldLabel>{t('dialog-knowledge-base-create.dimension.label')}</FieldLabel>
+						<DimensionSelect
+							value={dimension}
+							options={dimensionOptions}
+							onChange={setDimension}
+							disabled={submitting}
+						/>
+					</Field>
+					{errorKey && <p className="text-destructive text-sm">{t(errorKey)}</p>}
+				</FieldGroup>
+				<DialogFooter>
+					<Button
+						variant="ghost"
+						onClick={() => onOpenChange(false)}
+						disabled={submitting}
+					>
+						<CircleAlert className="size-3.5" />
+						{t('common.cancel')}
+					</Button>
+					<Button onClick={handleSubmit} disabled={submitting || noCompatibleModels}>
+						{submitting ? (
+							<Loader2 className="size-3.5 animate-spin" />
+						) : (
+							<PlusCircle className="size-3.5" />
+						)}
+						{submitting ? t('common.creating') : t('common.create')}
+					</Button>
+				</DialogFooter>
+			</DialogContent>
+		</Dialog>
+	);
+}
diff --git a/examples/web_ui/frontend/src/components/dialog/DeleteDialog.tsx b/examples/web_ui/frontend/src/components/dialog/DeleteDialog.tsx
new file mode 100644
index 0000000..e502ee8
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/dialog/DeleteDialog.tsx
@@ -0,0 +1,70 @@
+import { Loader2, CheckCircle, CircleAlert } from 'lucide-react';
+import { useState } from 'react';
+import type { ReactNode } from 'react';
+
+import { Button } from '@/components/ui/button';
+import {
+	Dialog,
+	DialogContent,
+	DialogHeader,
+	DialogTitle,
+	DialogDescription,
+	DialogFooter,
+} from '@/components/ui/dialog';
+import { useTranslation } from '@/i18n/useI18n';
+
+interface Props {
+	open: boolean;
+	onOpenChange: (open: boolean) => void;
+	title: string;
+	description?: ReactNode;
+	confirmLabel?: string;
+	onConfirm: () => Promise<void>;
+}
+
+export function DeleteDialog({
+	open,
+	onOpenChange,
+	title,
+	description,
+	confirmLabel,
+	onConfirm,
+}: Props) {
+	const { t } = useTranslation();
+	const [deleting, setDeleting] = useState(false);
+
+	const handleConfirm = async () => {
+		setDeleting(true);
+		try {
+			await onConfirm();
+			onOpenChange(false);
+		} finally {
+			setDeleting(false);
+		}
+	};
+
+	return (
+		<Dialog open={open} onOpenChange={onOpenChange}>
+			<DialogContent className="max-w-sm">
+				<DialogHeader>
+					<DialogTitle>{title}</DialogTitle>
+					{description && <DialogDescription>{description}</DialogDescription>}
+				</DialogHeader>
+				<DialogFooter>
+					<Button variant="ghost" onClick={() => onOpenChange(false)} disabled={deleting}>
+						<CircleAlert className="size-3.5" />
+						{t('common.cancel')}
+					</Button>
+					<Button onClick={handleConfirm} disabled={deleting} autoFocus>
+						{deleting ? (
+							<Loader2 className="size-3.5 animate-spin" />
+						) : (
+							<CheckCircle className="size-3.5" />
+						)}
+						{confirmLabel ?? t('common.confirm')}
+					</Button>
+				</DialogFooter>
+			</DialogContent>
+		</Dialog>
+	);
+}
diff --git a/examples/web_ui/frontend/src/components/dialog/EditAgentDialog.tsx b/examples/web_ui/frontend/src/components/dialog/EditAgentDialog.tsx
new file mode 100644
index 0000000..859e9c1
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/dialog/EditAgentDialog.tsx
@@ -0,0 +1,151 @@
+import { CircleAlert, Loader2, Save } from 'lucide-react';
+import { useEffect, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import type { AgentView, ContextConfig, InviteConfig, ReActConfig } from '@/api';
+import {
+	AgentFormFields,
+	defaultAgentFormValues,
+	type AgentFormValues,
+	type AgentSection,
+} from '@/components/form/AgentFormFields';
+import type { SchemaFormValue } from '@/components/form/SchemaForm';
+import { Alert, AlertDescription } from '@/components/ui/alert.tsx';
+import { Button } from '@/components/ui/button';
+import {
+	Dialog,
+	DialogContent,
+	DialogFooter,
+	DialogHeader,
+	DialogTitle,
+	DialogDescription,
+} from '@/components/ui/dialog';
+import { useAgents } from '@/hooks/useAgents';
+import { useAgentSchema } from '@/hooks/useAgentSchema';
+import { formatApiErrorForAlert } from '@/lib/api-error';
+
+interface Props {
+	open: boolean;
+	onOpenChange: (open: boolean) => void;
+	agent: AgentView;
+	onUpdated?: () => void;
+}
+
+export function EditAgentDialog({ open, onOpenChange, agent, onUpdated }: Props) {
+	const { update } = useAgents();
+	const { t } = useTranslation();
+	const { schema } = useAgentSchema();
+	const [submitting, setSubmitting] = useState(false);
+	const [values, setValues] = useState<AgentFormValues | null>(null);
+	const [errorMsg, setErrorMsg] = useState('');
+
+	useEffect(() => {
+		if (!open || !schema) {
+			if (!open) {
+				setValues(null);
+				setErrorMsg('');
+			}
+			return;
+		}
+		// Start from schema defaults, then overlay the existing agent's data so
+		// any unset fields fall back to defaults rather than empty.
+		const base = defaultAgentFormValues(schema);
+		const d = agent.data;
+		setValues({
+			identity: {
+				...base.identity,
+				name: d.name,
+				system_prompt: d.system_prompt,
+			},
+			context_config: { ...base.context_config, ...(d.context_config ?? {}) },
+			react_config: { ...base.react_config, ...(d.react_config ?? {}) },
+			invite_config: { ...base.invite_config, ...(d.invite_config ?? {}) },
+		});
+		setErrorMsg('');
+	}, [open, schema, agent]);
+
+	const handleChange = (section: AgentSection, key: string, value: SchemaFormValue) => {
+		setErrorMsg('');
+		setValues((prev) =>
+			prev ? { ...prev, [section]: { ...prev[section], [key]: value } } : prev,
+		);
+	};
+
+	const handleSubmit = async () => {
+		if (!values) return;
+		const name = (values.identity.name as string | undefined)?.trim();
+		if (!name) return;
+		setErrorMsg('');
+		setSubmitting(true);
+		try {
+			await update(
+				agent.id,
+				{
+					name,
+					system_prompt: values.identity.system_prompt as string | undefined,
+					context_config: values.context_config as unknown as ContextConfig,
+					react_config: values.react_config as unknown as ReActConfig,
+					invite_config: values.invite_config as unknown as InviteConfig,
+				},
+				{ silent: true },
+			);
+			onOpenChange(false);
+			onUpdated?.();
+		} catch (e) {
+			setErrorMsg(formatApiErrorForAlert(e));
+		} finally {
+			setSubmitting(false);
+		}
+	};
+
+	const nameValid = !!(values?.identity.name as string | undefined)?.trim();
+
+	return (
+		<Dialog open={open} onOpenChange={onOpenChange}>
+			<DialogContent className="!w-[500px] !max-w-[500px]">
+				<DialogHeader>
+					<DialogTitle>{t('dialog-agent-edit.title')}</DialogTitle>
+					<DialogDescription className="sr-only">
+						{t('dialog-agent-edit.description')}
+					</DialogDescription>
+				</DialogHeader>
+				<div className="no-scrollbar -mx-4 max-h-[75vh] overflow-y-auto px-4">
+					{schema && values ? (
+						<AgentFormFields schema={schema} values={values} onChange={handleChange} />
+					) : (
+						<p className="text-muted-foreground text-sm">{t('common.loading')}</p>
+					)}
+				</div>
+				{errorMsg && (
+					<Alert variant="destructive">
+						<CircleAlert />
+						<AlertDescription className="whitespace-pre-wrap">
+							{errorMsg}
+						</AlertDescription>
+					</Alert>
+				)}
+				<DialogFooter>
+					<Button
+						variant="ghost"
+						onClick={() => onOpenChange(false)}
+						disabled={submitting}
+					>
+						<CircleAlert className="size-3.5" />
+						{t('common.cancel')}
+					</Button>
+					<Button
+						onClick={handleSubmit}
+						disabled={!nameValid || submitting || !schema || !values}
+					>
+						{submitting ? (
+							<Loader2 className="size-3.5 animate-spin" />
+						) : (
+							<Save className="size-3.5" />
+						)}
+						{submitting ? t('common.saving') : t('common.save')}
+					</Button>
+				</DialogFooter>
+			</DialogContent>
+		</Dialog>
+	);
+}
diff --git a/examples/web_ui/frontend/src/components/dialog/EditCredentialDialog.tsx b/examples/web_ui/frontend/src/components/dialog/EditCredentialDialog.tsx
new file mode 100644
index 0000000..ba0e47d
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/dialog/EditCredentialDialog.tsx
@@ -0,0 +1,118 @@
+import { CircleAlert, Loader2, Save } from 'lucide-react';
+import { useState, useEffect } from 'react';
+
+import { credentialApi } from '@/api';
+import type { CredentialView, CredentialSchema } from '@/api';
+import { SchemaForm, type SchemaFormValue } from '@/components/form/SchemaForm';
+import { Button } from '@/components/ui/button';
+import {
+	Dialog,
+	DialogContent,
+	DialogHeader,
+	DialogTitle,
+	DialogDescription,
+	DialogFooter,
+} from '@/components/ui/dialog';
+import { useCredentials } from '@/hooks/useCredentials';
+import { useTranslation } from '@/i18n/useI18n';
+
+interface Props {
+	open: boolean;
+	onOpenChange: (open: boolean) => void;
+	credential: CredentialView;
+	onUpdated?: () => void;
+}
+
+export function EditCredentialDialog({ open, onOpenChange, credential, onUpdated }: Props) {
+	const { update } = useCredentials();
+	const { t } = useTranslation();
+	const [schema, setSchema] = useState<CredentialSchema | null>(null);
+	const [loadingSchema, setLoadingSchema] = useState(false);
+	const [values, setValues] = useState<Record<string, SchemaFormValue>>({});
+	const [submitting, setSubmitting] = useState(false);
+
+	const type = credential.data.type as string | undefined;
+
+	useEffect(() => {
+		if (!open || !type) return;
+		setLoadingSchema(true);
+		credentialApi
+			.schemas()
+			.then((res) => {
+				const matched = res.schemas.find(
+					(s) => (s.properties.type?.const as string) === type,
+				);
+				setSchema(matched ?? null);
+				// Pre-fill values from existing credential data (excluding writeOnly fields)
+				if (matched) {
+					const prefill: Record<string, SchemaFormValue> = {};
+					for (const [key, prop] of Object.entries(matched.properties)) {
+						if (key === 'id' || key === 'type' || prop.const !== undefined) continue;
+						if (prop.writeOnly) continue; // don't pre-fill secrets like api_key
+						const existing = credential.data[key];
+						if (existing !== undefined) {
+							prefill[key] = existing as SchemaFormValue;
+						}
+					}
+					setValues(prefill);
+				}
+			})
+			.finally(() => setLoadingSchema(false));
+	}, [open, type, credential.data]);
+
+	const handleSubmit = async () => {
+		if (!schema) return;
+		setSubmitting(true);
+		try {
+			const data: Record<string, unknown> = { ...credential.data };
+			for (const [key, prop] of Object.entries(schema.properties)) {
+				if (key === 'id' || key === 'type' || prop.const !== undefined) continue;
+				const val = values[key];
+				if (val !== undefined && val !== '') data[key] = val;
+			}
+			await update(credential.id, { data });
+			onOpenChange(false);
+			onUpdated?.();
+		} finally {
+			setSubmitting(false);
+		}
+	};
+
+	return (
+		<Dialog open={open} onOpenChange={onOpenChange}>
+			<DialogContent className="!w-[500px] !max-w-[500px]">
+				<DialogHeader>
+					<DialogTitle>{t('dialog-credential-edit.title')}</DialogTitle>
+					<DialogDescription>{t('dialog-credential-edit.description')}</DialogDescription>
+				</DialogHeader>
+				{loadingSchema ? (
+					<p className="text-muted-foreground text-sm">{t('common.loading')}</p>
+				) : schema ? (
+					<SchemaForm
+						schema={schema}
+						values={values}
+						onChange={(key, val) => setValues((prev) => ({ ...prev, [key]: val }))}
+					/>
+				) : null}
+				<DialogFooter>
+					<Button
+						variant="ghost"
+						onClick={() => onOpenChange(false)}
+						disabled={submitting}
+					>
+						<CircleAlert className="size-3.5" />
+						{t('common.cancel')}
+					</Button>
+					<Button onClick={handleSubmit} disabled={submitting || !schema}>
+						{submitting ? (
+							<Loader2 className="size-3.5 animate-spin" />
+						) : (
+							<Save className="size-3.5" />
+						)}
+						{submitting ? t('common.saving') : t('common.save')}
+					</Button>
+				</DialogFooter>
+			</DialogContent>
+		</Dialog>
+	);
+}
diff --git a/examples/web_ui/frontend/src/components/dialog/EditKnowledgeBaseDialog.tsx b/examples/web_ui/frontend/src/components/dialog/EditKnowledgeBaseDialog.tsx
new file mode 100644
index 0000000..7ffd58e
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/dialog/EditKnowledgeBaseDialog.tsx
@@ -0,0 +1,139 @@
+import { CheckCircle, CircleAlert, Loader2 } from 'lucide-react';
+import { useEffect, useState } from 'react';
+
+import type { KnowledgeBaseView } from '@/api';
+import { Badge } from '@/components/ui/badge.tsx';
+import { Button } from '@/components/ui/button.tsx';
+import {
+	Dialog,
+	DialogContent,
+	DialogDescription,
+	DialogFooter,
+	DialogHeader,
+	DialogTitle,
+} from '@/components/ui/dialog.tsx';
+import { Field, FieldGroup, FieldLabel } from '@/components/ui/field.tsx';
+import { Input } from '@/components/ui/input.tsx';
+import { Textarea } from '@/components/ui/textarea.tsx';
+import { useKnowledgeBases } from '@/hooks/useKnowledgeBases';
+import { useTranslation } from '@/i18n/useI18n.ts';
+
+interface Props {
+	open: boolean;
+	onOpenChange: (open: boolean) => void;
+	knowledgeBase: KnowledgeBaseView | null;
+	onUpdated?: (view: KnowledgeBaseView) => void;
+}
+
+/**
+ * Dialog to edit a knowledge base's mutable fields. Embedding model
+ * is shown as a read-only badge because it's pinned at creation time
+ * (the underlying collection is sized to its dimension).
+ */
+export function EditKnowledgeBaseDialog({ open, onOpenChange, knowledgeBase, onUpdated }: Props) {
+	const { t } = useTranslation();
+	const { update } = useKnowledgeBases();
+	const [name, setName] = useState('');
+	const [description, setDescription] = useState('');
+	const [submitting, setSubmitting] = useState(false);
+	const [errorKey, setErrorKey] = useState<string | null>(null);
+
+	useEffect(() => {
+		if (open && knowledgeBase) {
+			setName(knowledgeBase.name);
+			setDescription(knowledgeBase.description ?? '');
+			setErrorKey(null);
+			setSubmitting(false);
+		}
+	}, [open, knowledgeBase]);
+
+	const handleSubmit = async () => {
+		if (!knowledgeBase) return;
+		const trimmedName = name.trim();
+		if (!trimmedName) {
+			setErrorKey('dialog-knowledge-base-edit.errors.nameRequired');
+			return;
+		}
+		setErrorKey(null);
+		setSubmitting(true);
+		try {
+			const view = await update(knowledgeBase.id, {
+				name: trimmedName,
+				description: description.trim(),
+			});
+			onUpdated?.(view);
+			onOpenChange(false);
+		} finally {
+			setSubmitting(false);
+		}
+	};
+
+	const embeddingModelLabel = knowledgeBase
+		? `${knowledgeBase.embedding_model_config.model} · ${knowledgeBase.embedding_model_config.dimensions}d`
+		: '';
+
+	return (
+		<Dialog open={open} onOpenChange={onOpenChange}>
+			<DialogContent className="!w-[500px] !max-w-[500px]">
+				<DialogHeader>
+					<DialogTitle>{t('dialog-knowledge-base-edit.title')}</DialogTitle>
+					<DialogDescription>
+						{t('dialog-knowledge-base-edit.description')}
+					</DialogDescription>
+				</DialogHeader>
+				<FieldGroup>
+					<Field>
+						<FieldLabel>{t('dialog-knowledge-base-edit.name.label')}</FieldLabel>
+						<Input
+							value={name}
+							onChange={(e) => setName(e.target.value)}
+							placeholder={t('dialog-knowledge-base-edit.name.placeholder')}
+							disabled={submitting}
+						/>
+					</Field>
+					<Field>
+						<FieldLabel>
+							{t('dialog-knowledge-base-edit.descriptionField.label')}
+						</FieldLabel>
+						<Textarea
+							value={description}
+							onChange={(e) => setDescription(e.target.value)}
+							placeholder={t(
+								'dialog-knowledge-base-edit.descriptionField.placeholder',
+							)}
+							disabled={submitting}
+							rows={3}
+						/>
+					</Field>
+					<Field orientation="horizontal">
+						<FieldLabel>
+							{t('dialog-knowledge-base-edit.embeddingModel.label')}
+						</FieldLabel>
+						<Badge variant="secondary" className="font-mono">
+							{embeddingModelLabel}
+						</Badge>
+					</Field>
+					{errorKey && <p className="text-destructive text-sm">{t(errorKey)}</p>}
+				</FieldGroup>
+				<DialogFooter>
+					<Button
+						variant="ghost"
+						onClick={() => onOpenChange(false)}
+						disabled={submitting}
+					>
+						<CircleAlert className="size-3.5" />
+						{t('common.cancel')}
+					</Button>
+					<Button onClick={handleSubmit} disabled={submitting}>
+						{submitting ? (
+							<Loader2 className="size-3.5 animate-spin" />
+						) : (
+							<CheckCircle className="size-3.5" />
+						)}
+						{submitting ? t('common.saving') : t('common.save')}
+					</Button>
+				</DialogFooter>
+			</DialogContent>
+		</Dialog>
+	);
+}
diff --git a/examples/web_ui/frontend/src/components/dialog/MCPDialog.tsx b/examples/web_ui/frontend/src/components/dialog/MCPDialog.tsx
new file mode 100644
index 0000000..03d6bff
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/dialog/MCPDialog.tsx
@@ -0,0 +1,206 @@
+import { PlusCircle, Loader2, Check } from 'lucide-react';
+import { CircleAlert } from 'lucide-react';
+import { useState, useCallback } from 'react';
+import type { ReactNode } from 'react';
+
+import type { MCPClient, StdioMCPConfig, HttpMCPConfig } from '@/api/types';
+import { Alert, AlertDescription } from '@/components/ui/alert.tsx';
+import { Button } from '@/components/ui/button.tsx';
+import { Checkbox } from '@/components/ui/checkbox.tsx';
+import {
+	Dialog,
+	DialogContent,
+	DialogDescription,
+	DialogFooter,
+	DialogHeader,
+	DialogTitle,
+	DialogTrigger,
+} from '@/components/ui/dialog.tsx';
+import {
+	Field,
+	FieldContent,
+	FieldDescription,
+	FieldGroup,
+	FieldLabel,
+	FieldSet,
+} from '@/components/ui/field.tsx';
+import { InputGroup, InputGroupTextarea } from '@/components/ui/input-group.tsx';
+import { useTranslation } from '@/i18n/useI18n.ts';
+
+type Status = 'idle' | 'loading' | 'success' | 'error';
+
+interface Props {
+	children: ReactNode;
+	onAdd: (mcps: MCPClient[]) => Promise<void>;
+}
+
+function parseMcpConfig(
+	raw: string,
+	keepAlive: boolean,
+	t: (key: string, opts?: Record<string, string>) => string,
+): MCPClient[] {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (e) {
+		throw new Error(t('dialog-mcp-create.parseError', { message: (e as Error).message }));
+	}
+
+	const obj = parsed as Record<string, unknown>;
+	const servers = obj.mcpServers as Record<string, Record<string, unknown>> | undefined;
+	if (!servers || typeof servers !== 'object') {
+		throw new Error(t('dialog-mcp-create.missingMcpServers'));
+	}
+
+	const entries = Object.entries(servers);
+	if (entries.length === 0) {
+		throw new Error(t('dialog-mcp-create.emptyMcpServers'));
+	}
+
+	return entries.map(([name, config]) => {
+		let mcp_config: StdioMCPConfig | HttpMCPConfig;
+		if ('url' in config) {
+			mcp_config = {
+				type: 'http_mcp',
+				url: config.url as string,
+				headers: (config.headers as Record<string, string> | undefined) ?? null,
+				timeout: (config.timeout as number | undefined) ?? null,
+			};
+		} else {
+			mcp_config = {
+				type: 'stdio_mcp',
+				command: config.command as string,
+				args: (config.args as string[] | undefined) ?? null,
+				env: (config.env as Record<string, string> | undefined) ?? null,
+				cwd: (config.cwd as string | undefined) ?? null,
+			};
+		}
+		return { name, is_stateful: keepAlive, mcp_config };
+	});
+}
+
+export const CreateMCPDialog = ({ children, onAdd }: Props) => {
+	const { t } = useTranslation();
+	const [open, setOpen] = useState(false);
+	const [configValue, setConfigValue] = useState('');
+	const [keepAlive, setKeepAlive] = useState(true);
+	const [status, setStatus] = useState<Status>('idle');
+	const [errorMsg, setErrorMsg] = useState('');
+
+	const reset = useCallback(() => {
+		setConfigValue('');
+		setKeepAlive(true);
+		setStatus('idle');
+		setErrorMsg('');
+	}, []);
+
+	const handleOpenChange = useCallback(
+		(next: boolean) => {
+			if (!next) reset();
+			setOpen(next);
+		},
+		[reset],
+	);
+
+	const handleAdd = useCallback(async () => {
+		setErrorMsg('');
+		let mcpClients: MCPClient[];
+		try {
+			mcpClients = parseMcpConfig(configValue, keepAlive, t);
+		} catch (e) {
+			setErrorMsg((e as Error).message);
+			setStatus('error');
+			return;
+		}
+
+		setStatus('loading');
+		try {
+			await onAdd(mcpClients);
+			setStatus('success');
+			setTimeout(() => {
+				handleOpenChange(false);
+			}, 1500);
+		} catch (e) {
+			// ApiErrors are already shown via the global toast in client.ts.
+			// Show only local validation errors (e.g. duplicate name) inline.
+			const isApiError = e instanceof Error && e.name === 'ApiError';
+			if (!isApiError) {
+				setErrorMsg(e instanceof Error ? e.message : String(e));
+			}
+			setStatus('idle');
+		}
+	}, [configValue, keepAlive, t, onAdd, handleOpenChange]);
+
+	return (
+		<Dialog open={open} onOpenChange={handleOpenChange}>
+			<DialogTrigger asChild>{children}</DialogTrigger>
+			<DialogContent className="!w-[500px] !max-w-[500px]">
+				<DialogHeader>
+					<DialogTitle>{t('dialog-mcp-create.title')}</DialogTitle>
+					<DialogDescription>{t('dialog-mcp-create.description')}</DialogDescription>
+				</DialogHeader>
+				<FieldSet>
+					<FieldGroup>
+						<Field>
+							<FieldContent>
+								<FieldLabel>{t('dialog-mcp-create.configLabel')}</FieldLabel>
+							</FieldContent>
+							<InputGroup>
+								<InputGroupTextarea
+									className="max-h-100"
+									value={configValue}
+									onChange={(e) => setConfigValue(e.target.value)}
+									placeholder={
+										'{\n  "mcpServers": {\n    "playwright": {\n      "command": "npx",\n      "args": ["@playwright/mcp@latest"]\n    }\n  }\n}'
+									}
+								/>
+							</InputGroup>
+						</Field>
+						<Field orientation="horizontal">
+							<Checkbox
+								id="mcp-keep-alive"
+								checked={keepAlive}
+								onCheckedChange={(v) => setKeepAlive(v === true)}
+							/>
+							<FieldContent>
+								<FieldLabel htmlFor="mcp-keep-alive">
+									{t('dialog-mcp-create.keepAlive')}
+								</FieldLabel>
+								<FieldDescription>
+									{t('dialog-mcp-create.keepAliveDesc')}
+								</FieldDescription>
+							</FieldContent>
+						</Field>
+					</FieldGroup>
+				</FieldSet>
+				{errorMsg && (
+					<Alert variant="destructive">
+						<CircleAlert />
+						<AlertDescription>{errorMsg}</AlertDescription>
+					</Alert>
+				)}
+				<DialogFooter>
+					<Button variant="ghost" onClick={() => handleOpenChange(false)}>
+						<CircleAlert className="size-3.5" />
+						{t('common.cancel')}
+					</Button>
+					<Button
+						onClick={handleAdd}
+						disabled={status === 'loading' || status === 'success'}
+					>
+						{status === 'loading' && <Loader2 className="size-3.5 animate-spin" />}
+						{status === 'success' && <Check className="size-3.5" />}
+						{status !== 'loading' && status !== 'success' && (
+							<PlusCircle className="size-3.5" />
+						)}
+						{status === 'loading'
+							? t('dialog-mcp-create.adding')
+							: status === 'success'
+								? t('dialog-mcp-create.added')
+								: t('common.add')}
+					</Button>
+				</DialogFooter>
+			</DialogContent>
+		</Dialog>
+	);
+};
diff --git a/examples/web_ui/frontend/src/components/dialog/RenameSessionDialog.tsx b/examples/web_ui/frontend/src/components/dialog/RenameSessionDialog.tsx
new file mode 100644
index 0000000..8bd906f
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/dialog/RenameSessionDialog.tsx
@@ -0,0 +1,82 @@
+import { CheckCircle, CircleAlert, Loader2 } from 'lucide-react';
+import { useState, useEffect } from 'react';
+
+import { Button } from '@/components/ui/button';
+import {
+	Dialog,
+	DialogContent,
+	DialogFooter,
+	DialogHeader,
+	DialogTitle,
+	DialogDescription,
+} from '@/components/ui/dialog';
+import { Field, FieldGroup, FieldLabel } from '@/components/ui/field';
+import { Input } from '@/components/ui/input';
+import { useTranslation } from '@/i18n/useI18n';
+
+interface Props {
+	open: boolean;
+	onOpenChange: (open: boolean) => void;
+	currentName: string;
+	onConfirm: (name: string) => Promise<void>;
+}
+
+export function RenameSessionDialog({ open, onOpenChange, currentName, onConfirm }: Props) {
+	const { t } = useTranslation();
+	const [name, setName] = useState(currentName);
+	const [loading, setLoading] = useState(false);
+
+	useEffect(() => {
+		if (open) setName(currentName);
+	}, [open, currentName]);
+
+	const handleConfirm = async () => {
+		if (!name.trim()) return;
+		setLoading(true);
+		try {
+			await onConfirm(name.trim());
+			onOpenChange(false);
+		} finally {
+			setLoading(false);
+		}
+	};
+
+	return (
+		<Dialog open={open} onOpenChange={onOpenChange}>
+			<DialogContent>
+				<DialogHeader>
+					<DialogTitle>{t('dialog-session-rename.title')}</DialogTitle>
+					<DialogDescription>{t('dialog-session-rename.description')}</DialogDescription>
+				</DialogHeader>
+				<FieldGroup>
+					<Field>
+						<FieldLabel>{t('dialog-session-rename.label')}</FieldLabel>
+						<Input
+							value={name}
+							onChange={(e) => setName(e.target.value)}
+							placeholder={t('dialog-session-rename.placeholder')}
+							onKeyDown={(e) => {
+								if (e.key === 'Enter') handleConfirm();
+							}}
+							autoFocus
+						/>
+					</Field>
+				</FieldGroup>
+				<DialogFooter>
+					<Button variant="ghost" onClick={() => onOpenChange(false)} disabled={loading}>
+						<CircleAlert className="size-3.5" />
+						{t('common.cancel')}
+					</Button>
+					<Button onClick={handleConfirm} disabled={loading || !name.trim()}>
+						{loading ? (
+							<Loader2 className="size-3.5 animate-spin" />
+						) : (
+							<CheckCircle className="size-3.5" />
+						)}
+						{t('common.confirm')}
+					</Button>
+				</DialogFooter>
+			</DialogContent>
+		</Dialog>
+	);
+}
diff --git a/examples/web_ui/frontend/src/components/drawer/KnowledgeSearchDrawer.tsx b/examples/web_ui/frontend/src/components/drawer/KnowledgeSearchDrawer.tsx
new file mode 100644
index 0000000..45db3ff
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/drawer/KnowledgeSearchDrawer.tsx
@@ -0,0 +1,199 @@
+import { FlaskConical, Loader2, Search } from 'lucide-react';
+import { useState } from 'react';
+
+import type { VectorSearchResult } from '@/api';
+import { Badge } from '@/components/ui/badge.tsx';
+import { Button } from '@/components/ui/button.tsx';
+import {
+	Empty,
+	EmptyDescription,
+	EmptyHeader,
+	EmptyMedia,
+	EmptyTitle,
+} from '@/components/ui/empty.tsx';
+import { Input } from '@/components/ui/input.tsx';
+import { Label } from '@/components/ui/label.tsx';
+import {
+	Sheet,
+	SheetContent,
+	SheetDescription,
+	SheetFooter,
+	SheetHeader,
+	SheetTitle,
+} from '@/components/ui/sheet.tsx';
+import { Textarea } from '@/components/ui/textarea.tsx';
+import { useKnowledgeBases } from '@/hooks/useKnowledgeBases';
+import { useTranslation } from '@/i18n/useI18n.ts';
+
+interface Props {
+	open: boolean;
+	onOpenChange: (open: boolean) => void;
+	knowledgeBaseId: string;
+	knowledgeBaseName: string;
+}
+
+/**
+ * Right-side drawer for ad-hoc retrieval testing on a knowledge base.
+ * The user types a query, picks `top_k`, and inspects ranked chunks.
+ */
+export function KnowledgeSearchDrawer({
+	open,
+	onOpenChange,
+	knowledgeBaseId,
+	knowledgeBaseName,
+}: Props) {
+	const { t } = useTranslation();
+	const { search } = useKnowledgeBases();
+	const [query, setQuery] = useState('');
+	const [topK, setTopK] = useState(5);
+	const [loading, setLoading] = useState(false);
+	const [results, setResults] = useState<VectorSearchResult[] | null>(null);
+	const [error, setError] = useState<string | null>(null);
+
+	const handleSearch = async () => {
+		const trimmed = query.trim();
+		if (!trimmed) return;
+		setLoading(true);
+		setError(null);
+		try {
+			const res = await search(knowledgeBaseId, {
+				query: trimmed,
+				top_k: topK,
+			});
+			setResults(res.results);
+		} catch (e) {
+			setError((e as Error).message || String(e));
+			setResults(null);
+		} finally {
+			setLoading(false);
+		}
+	};
+
+	return (
+		<Sheet open={open} onOpenChange={onOpenChange}>
+			<SheetContent className="flex w-full sm:!max-w-[480px] flex-col gap-y-4 p-4">
+				<SheetHeader className="px-0">
+					<SheetTitle className="flex items-center gap-x-2">
+						<FlaskConical className="size-4" />
+						{t('knowledge.test.title')}
+					</SheetTitle>
+					<SheetDescription className="truncate">
+						{t('knowledge.test.description', { name: knowledgeBaseName })}
+					</SheetDescription>
+				</SheetHeader>
+
+				<div className="flex flex-col gap-y-3 px-0">
+					<div className="flex flex-col gap-y-1.5">
+						<Label htmlFor="kb-test-query" className="text-xs">
+							{t('knowledge.test.queryLabel')}
+						</Label>
+						<Textarea
+							id="kb-test-query"
+							value={query}
+							onChange={(e) => setQuery(e.target.value)}
+							placeholder={t('knowledge.test.queryPlaceholder')}
+							rows={3}
+							disabled={loading}
+						/>
+					</div>
+					<div className="flex items-center gap-x-3">
+						<div className="flex items-center gap-x-2">
+							<Label htmlFor="kb-test-topk" className="text-xs">
+								{t('knowledge.test.topKLabel')}
+							</Label>
+							<Input
+								id="kb-test-topk"
+								type="number"
+								min={1}
+								max={50}
+								value={topK}
+								onChange={(e) =>
+									setTopK(Math.max(1, Math.min(50, Number(e.target.value) || 1)))
+								}
+								className="w-20"
+								disabled={loading}
+							/>
+						</div>
+						<Button
+							className="ml-auto"
+							size="sm"
+							onClick={handleSearch}
+							disabled={loading || !query.trim()}
+						>
+							{loading ? (
+								<Loader2 className="size-3.5 animate-spin" />
+							) : (
+								<Search className="size-3.5" />
+							)}
+							{t('knowledge.test.searchButton')}
+						</Button>
+					</div>
+					{error && <p className="text-destructive text-sm">{error}</p>}
+				</div>
+
+				<div className="flex-1 overflow-y-auto px-0">
+					{results === null ? null : results.length === 0 ? (
+						<Empty className="border-none py-4">
+							<EmptyHeader>
+								<EmptyMedia variant="icon">
+									<Search />
+								</EmptyMedia>
+								<EmptyTitle>{t('knowledge.test.emptyTitle')}</EmptyTitle>
+								<EmptyDescription>
+									{t('knowledge.test.emptyDescription')}
+								</EmptyDescription>
+							</EmptyHeader>
+						</Empty>
+					) : (
+						<div className="flex flex-col gap-y-3">
+							{results.map((hit, idx) => (
+								<ResultCard
+									key={`${hit.document_id}-${idx}`}
+									hit={hit}
+									index={idx}
+								/>
+							))}
+						</div>
+					)}
+				</div>
+
+				<SheetFooter className="px-0">
+					<Button variant="ghost" onClick={() => onOpenChange(false)}>
+						{t('common.close')}
+					</Button>
+				</SheetFooter>
+			</SheetContent>
+		</Sheet>
+	);
+}
+
+function ResultCard({ hit, index }: { hit: VectorSearchResult; index: number }) {
+	const { t } = useTranslation();
+	const text =
+		hit.chunk.content && typeof hit.chunk.content === 'object' && 'text' in hit.chunk.content
+			? String(hit.chunk.content.text ?? '')
+			: JSON.stringify(hit.chunk.content);
+
+	return (
+		<div className="rounded-md border bg-card p-3 flex flex-col gap-y-2">
+			<div className="flex items-center gap-x-2 text-xs text-muted-foreground">
+				<Badge variant="secondary" className="font-mono">
+					#{index + 1}
+				</Badge>
+				<Badge variant="outline" className="font-mono">
+					{t('knowledge.test.score')}: {hit.score.toFixed(4)}
+				</Badge>
+				<span className="ml-auto truncate" title={hit.chunk.source}>
+					{hit.chunk.source}
+				</span>
+			</div>
+			<p className="text-sm whitespace-pre-wrap break-words">{text}</p>
+			<div className="text-xs text-muted-foreground">
+				{t('knowledge.test.chunkPosition', {
+					index: hit.chunk.chunk_index + 1,
+					total: hit.chunk.total_chunks,
+				})}
+			</div>
+		</div>
+	);
+}
diff --git a/examples/web_ui/frontend/src/components/error/RouteError.tsx b/examples/web_ui/frontend/src/components/error/RouteError.tsx
new file mode 100644
index 0000000..8dcf068
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/error/RouteError.tsx
@@ -0,0 +1,58 @@
+import { useEffect } from 'react';
+import { isRouteErrorResponse, useNavigate, useRouteError } from 'react-router-dom';
+
+import { Button } from '@/components/ui/button';
+import { useTranslation } from '@/i18n/useI18n';
+
+/**
+ * Reduce an unknown route error to a one-line, human-readable detail.
+ * Returns `null` when there is nothing meaningful to show (e.g. a
+ * nullish throw or a plain object), so the caller can hide the detail
+ * box instead of rendering "null" / "[object Object]".
+ */
+function formatErrorDetail(error: unknown): string | null {
+	if (isRouteErrorResponse(error)) return `${error.status} ${error.statusText}`;
+	if (error instanceof Error) return error.message || null;
+	if (typeof error === 'string') return error || null;
+	if (typeof error === 'number' || typeof error === 'boolean') return String(error);
+	return null;
+}
+
+/**
+ * Route-level error boundary. React Router renders this in place of the
+ * crashed route element instead of its bare developer overlay, so end
+ * users get a friendly, localized message plus recovery actions (retry /
+ * go home) rather than a raw stack trace. The full error (with stack) is
+ * still logged to the console for developers.
+ */
+export function RouteError() {
+	const error = useRouteError();
+	const navigate = useNavigate();
+	const { t } = useTranslation();
+
+	useEffect(() => {
+		console.error(error);
+	}, [error]);
+
+	const detail = formatErrorDetail(error);
+
+	return (
+		<div className="flex h-full w-full flex-col items-center justify-center gap-4 p-8 text-center">
+			<div role="alert" className="flex flex-col gap-1">
+				<h1 className="text-lg font-semibold">{t('common.error')}</h1>
+				<p className="text-muted-foreground text-sm">{t('error.description')}</p>
+			</div>
+			{detail && (
+				<pre className="text-muted-foreground bg-muted max-w-md overflow-auto rounded-md p-3 text-left text-xs whitespace-pre-wrap">
+					{detail}
+				</pre>
+			)}
+			<div className="flex gap-2">
+				<Button variant="outline" onClick={() => navigate(0)}>
+					{t('error.retry')}
+				</Button>
+				<Button onClick={() => navigate('/')}>{t('error.home')}</Button>
+			</div>
+		</div>
+	);
+}
diff --git a/examples/web_ui/frontend/src/components/form/AgentFormFields.tsx b/examples/web_ui/frontend/src/components/form/AgentFormFields.tsx
new file mode 100644
index 0000000..1099c67
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/form/AgentFormFields.tsx
@@ -0,0 +1,149 @@
+import { useTranslation } from 'react-i18next';
+
+import type { AgentSchemaV2Response, JSONSchema, JSONSchemaProperty } from '@/api';
+import { SchemaForm, type SchemaFormValue } from '@/components/form/SchemaForm';
+import {
+	FieldDescription,
+	FieldGroup,
+	FieldLegend,
+	FieldSeparator,
+	FieldSet,
+} from '@/components/ui/field';
+
+export type AgentSection = 'identity' | 'context_config' | 'react_config' | 'invite_config';
+
+export type AgentFormValues = {
+	[K in AgentSection]: Record<string, SchemaFormValue>;
+};
+
+interface Props {
+	schema: AgentSchemaV2Response;
+	values: AgentFormValues;
+	onChange: (section: AgentSection, key: string, value: SchemaFormValue) => void;
+}
+
+/**
+ * Section derivation from the flat `AgentData` schema. Ordered — controls
+ * the visual order of the fieldsets. "identity" carries every top-level
+ * property that is NOT one of the nested-object sections below, so any
+ * newly added scalar / boolean / textarea field on `AgentData` shows up
+ * in the identity fieldset automatically.
+ */
+const NESTED_SECTIONS: Array<{ key: Exclude<AgentSection, 'identity'>; i18n: string }> = [
+	{ key: 'context_config', i18n: 'context-config' },
+	{ key: 'react_config', i18n: 'react-config' },
+	{ key: 'invite_config', i18n: 'invite-config' },
+];
+
+const IDENTITY_I18N = 'identity';
+
+const toKebab = (s: string) => s.replace(/_/g, '-');
+
+/** Split the flat `AgentData` schema into the sections the form renders
+ * (currently four: `identity` + one per `NESTED_SECTIONS` entry). */
+function sliceSchema(root: JSONSchema): Record<AgentSection, JSONSchema> {
+	const props = root.properties ?? {};
+	const nestedKeys = new Set(NESTED_SECTIONS.map((s) => s.key));
+
+	const identityProps: Record<string, JSONSchemaProperty> = {};
+	for (const [k, prop] of Object.entries(props)) {
+		if (nestedKeys.has(k as Exclude<AgentSection, 'identity'>)) continue;
+		identityProps[k] = prop;
+	}
+
+	const identity: JSONSchema = {
+		type: 'object',
+		title: 'Identity',
+		properties: identityProps,
+		required: (root.required ?? []).filter(
+			(r) => !nestedKeys.has(r as Exclude<AgentSection, 'identity'>),
+		),
+	};
+
+	return {
+		identity,
+		context_config: (props.context_config as JSONSchema) ?? {
+			type: 'object',
+			properties: {},
+		},
+		react_config: (props.react_config as JSONSchema) ?? {
+			type: 'object',
+			properties: {},
+		},
+		invite_config: (props.invite_config as JSONSchema) ?? {
+			type: 'object',
+			properties: {},
+		},
+	};
+}
+
+export function AgentFormFields({ schema, values, onChange }: Props) {
+	const { t } = useTranslation();
+	const sections = sliceSchema(schema.schema);
+
+	const rows: Array<{ key: AgentSection; i18n: string; sectionSchema: JSONSchema }> = [
+		{ key: 'identity', i18n: IDENTITY_I18N, sectionSchema: sections.identity },
+		...NESTED_SECTIONS.map((s) => ({
+			key: s.key as AgentSection,
+			i18n: s.i18n,
+			sectionSchema: sections[s.key],
+		})),
+	];
+
+	return (
+		<FieldGroup>
+			{rows.map(({ key: sectionKey, i18n: sectionI18n, sectionSchema }, idx) => {
+				const legend = t(`agent-form.${sectionI18n}.legend`, {
+					defaultValue: sectionSchema.title ?? sectionKey,
+				});
+				const description = t(`agent-form.${sectionI18n}.description`, {
+					defaultValue: '',
+				});
+				return (
+					<div key={sectionKey}>
+						{idx > 0 && <FieldSeparator className="my-0" />}
+						<FieldSet>
+							<FieldLegend>{legend}</FieldLegend>
+							{description && <FieldDescription>{description}</FieldDescription>}
+							<SchemaForm
+								schema={sectionSchema}
+								values={values[sectionKey]}
+								onChange={(k, v) => onChange(sectionKey, k, v)}
+								idPrefix={`agent-form-${sectionI18n}`}
+								labelFor={(k, prop) =>
+									t(`agent-form.${sectionI18n}.${toKebab(k)}.label`, {
+										defaultValue: prop.title ?? k.replace(/_/g, ' '),
+									})
+								}
+								placeholderFor={(k, prop) =>
+									t(`agent-form.${sectionI18n}.${toKebab(k)}.placeholder`, {
+										defaultValue: prop.description ?? '',
+									}) || undefined
+								}
+							/>
+						</FieldSet>
+					</div>
+				);
+			})}
+		</FieldGroup>
+	);
+}
+
+/** Build a fresh `AgentFormValues` populated from each section schema's defaults. */
+export function defaultAgentFormValues(schema: AgentSchemaV2Response): AgentFormValues {
+	const sections = sliceSchema(schema.schema);
+	const fromDefaults = (section: JSONSchema): Record<string, SchemaFormValue> => {
+		const out: Record<string, SchemaFormValue> = {};
+		for (const [k, prop] of Object.entries(section.properties ?? {})) {
+			if (prop.const !== undefined) continue;
+			if (prop.default !== undefined) out[k] = prop.default as SchemaFormValue;
+		}
+		return out;
+	};
+	return {
+		identity: fromDefaults(sections.identity),
+		context_config: fromDefaults(sections.context_config),
+		react_config: fromDefaults(sections.react_config),
+		invite_config: fromDefaults(sections.invite_config),
+	};
+}
diff --git a/examples/web_ui/frontend/src/components/form/SchemaForm.tsx b/examples/web_ui/frontend/src/components/form/SchemaForm.tsx
new file mode 100644
index 0000000..d55ee88
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/form/SchemaForm.tsx
@@ -0,0 +1,220 @@
+import type { JSONSchema, JSONSchemaProperty } from '@/api';
+import { Checkbox } from '@/components/ui/checkbox';
+import { Field, FieldDescription, FieldGroup, FieldLabel } from '@/components/ui/field.tsx';
+import { Input } from '@/components/ui/input';
+import {
+	Select,
+	SelectContent,
+	SelectItem,
+	SelectTrigger,
+	SelectValue,
+} from '@/components/ui/select';
+import { Textarea } from '@/components/ui/textarea';
+
+const DEFAULT_SKIP_FIELDS = new Set(['id', 'type']);
+
+export type SchemaFormValue = string | number | boolean | null | undefined;
+
+interface Props {
+	schema: JSONSchema;
+	values: Record<string, SchemaFormValue>;
+	onChange: (key: string, value: SchemaFormValue) => void;
+	/** Field names to omit from rendering. Defaults to `id` and `type`. */
+	skipFields?: ReadonlySet<string>;
+	/** Optional override for a field label. Falls back to `prop.title`. */
+	labelFor?: (key: string, prop: JSONSchemaProperty) => string | undefined;
+	/** Optional override for a field's placeholder/description. */
+	placeholderFor?: (key: string, prop: JSONSchemaProperty) => string | undefined;
+	/** Optional override for the helper text shown under a field. */
+	descriptionFor?: (key: string, prop: JSONSchemaProperty) => string | undefined;
+	/** Prefix for generated DOM IDs (so multiple SchemaForms on one page don't collide). */
+	idPrefix?: string;
+}
+
+function effectiveType(prop: JSONSchemaProperty): string {
+	return prop.type ?? prop.anyOf?.find((t) => t.type !== 'null')?.type ?? 'string';
+}
+
+/** Surface enum values whether they appear at the property root or inside an
+ *  `anyOf` variant (Pydantic puts `Literal[...]` directly on the property and
+ *  `Literal[...] | None` on the non-null `anyOf` branch). */
+function enumValues(prop: JSONSchemaProperty): unknown[] | null {
+	if (prop.enum) return prop.enum;
+	for (const variant of prop.anyOf ?? []) {
+		const v = (variant as JSONSchemaProperty).enum;
+		if (v) return v;
+	}
+	return null;
+}
+
+function inferStep(type: string): number | string | undefined {
+	if (type === 'integer') return 1;
+	if (type === 'number') return 'any';
+	return undefined;
+}
+
+/** Extract initial values from a JSON Schema's `default` fields. */
+export function defaultValuesFromSchema(
+	schema: JSONSchema,
+	skipFields: ReadonlySet<string> = DEFAULT_SKIP_FIELDS,
+): Record<string, SchemaFormValue> {
+	const out: Record<string, SchemaFormValue> = {};
+	for (const [key, prop] of Object.entries(schema.properties ?? {})) {
+		if (skipFields.has(key) || prop.const !== undefined) continue;
+		if (prop.default !== undefined) {
+			out[key] = prop.default as SchemaFormValue;
+		}
+	}
+	return out;
+}
+
+export function SchemaForm({
+	schema,
+	values,
+	onChange,
+	skipFields = DEFAULT_SKIP_FIELDS,
+	labelFor,
+	placeholderFor,
+	descriptionFor,
+	idPrefix = 'schema-form',
+}: Props) {
+	const entries = Object.entries(schema.properties ?? {}).filter(
+		([key, prop]) => !skipFields.has(key) && prop.const === undefined,
+	);
+
+	return (
+		<FieldGroup>
+			{entries.map(([key, prop]) => {
+				const fieldId = `${idPrefix}-${key}`;
+				const isRequired = schema.required?.includes(key) ?? false;
+				const type = effectiveType(prop);
+				const isBoolean = type === 'boolean';
+				const isPassword = prop.format === 'password';
+				const isTextarea = prop.format === 'textarea';
+				const isNumber = type === 'number' || type === 'integer';
+				const enumOpts = enumValues(prop);
+
+				const label = labelFor?.(key, prop) ?? prop.title ?? key.replace(/_/g, ' ');
+				const placeholder = placeholderFor?.(key, prop) ?? prop.description;
+				const description = descriptionFor?.(key, prop);
+				const current = values[key];
+
+				if (isBoolean) {
+					return (
+						<Field key={key} orientation="horizontal">
+							<Checkbox
+								id={fieldId}
+								checked={!!current}
+								onCheckedChange={(checked) => onChange(key, !!checked)}
+							/>
+							<FieldLabel htmlFor={fieldId} className="font-normal">
+								{label}
+							</FieldLabel>
+							{description && <FieldDescription>{description}</FieldDescription>}
+						</Field>
+					);
+				}
+
+				if (enumOpts) {
+					const currentStr =
+						current === undefined || current === null ? '' : String(current);
+					return (
+						<Field key={key}>
+							<FieldLabel htmlFor={fieldId}>
+								{label}
+								{isRequired && <span className="text-destructive ml-0.5">*</span>}
+							</FieldLabel>
+							<Select value={currentStr} onValueChange={(v) => onChange(key, v)}>
+								<SelectTrigger id={fieldId} className="w-full">
+									<SelectValue placeholder={placeholder} />
+								</SelectTrigger>
+								<SelectContent>
+									{enumOpts.map((opt) => (
+										<SelectItem key={String(opt)} value={String(opt)}>
+											{String(opt)}
+										</SelectItem>
+									))}
+								</SelectContent>
+							</Select>
+							{description && <FieldDescription>{description}</FieldDescription>}
+						</Field>
+					);
+				}
+
+				if (isTextarea) {
+					return (
+						<Field key={key}>
+							<FieldLabel htmlFor={fieldId}>
+								{label}
+								{isRequired && <span className="text-destructive ml-0.5">*</span>}
+							</FieldLabel>
+							<Textarea
+								id={fieldId}
+								rows={3}
+								value={(current as string | undefined) ?? ''}
+								onChange={(e) => onChange(key, e.target.value)}
+								placeholder={placeholder}
+							/>
+							{description && <FieldDescription>{description}</FieldDescription>}
+						</Field>
+					);
+				}
+
+				if (isNumber) {
+					const min = prop.minimum ?? prop.exclusiveMinimum;
+					const max = prop.maximum ?? prop.exclusiveMaximum;
+					return (
+						<Field key={key}>
+							<FieldLabel htmlFor={fieldId}>
+								{label}
+								{isRequired && <span className="text-destructive ml-0.5">*</span>}
+							</FieldLabel>
+							<Input
+								id={fieldId}
+								type="number"
+								min={min}
+								max={max}
+								step={inferStep(type)}
+								value={
+									current === undefined || current === null ? '' : String(current)
+								}
+								onChange={(e) => {
+									const raw = e.target.value;
+									// Empty input → undefined so JSON.stringify drops the key
+									// and the backend applies its own default. Sending "" would
+									// fail Pydantic float/int coercion.
+									if (raw === '') {
+										onChange(key, undefined);
+										return;
+									}
+									const parsed =
+										type === 'integer' ? parseInt(raw, 10) : parseFloat(raw);
+									onChange(key, Number.isNaN(parsed) ? raw : parsed);
+								}}
+								placeholder={placeholder}
+							/>
+							{description && <FieldDescription>{description}</FieldDescription>}
+						</Field>
+					);
+				}
+
+				return (
+					<Field key={key}>
+						<FieldLabel htmlFor={fieldId}>
+							{label}
+							{isRequired && <span className="text-destructive ml-0.5">*</span>}
+						</FieldLabel>
+						<Input
+							id={fieldId}
+							type={isPassword ? 'password' : 'text'}
+							value={(current as string | undefined) ?? ''}
+							onChange={(e) => onChange(key, e.target.value)}
+							placeholder={placeholder}
+						/>
+						{description && <FieldDescription>{description}</FieldDescription>}
+					</Field>
+				);
+			})}
+		</FieldGroup>
+	);
+}
diff --git a/examples/web_ui/frontend/src/components/knowledge/KnowledgeDocumentsPanel.tsx b/examples/web_ui/frontend/src/components/knowledge/KnowledgeDocumentsPanel.tsx
new file mode 100644
index 0000000..d173a2b
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/knowledge/KnowledgeDocumentsPanel.tsx
@@ -0,0 +1,481 @@
+import { AlertCircle, CheckCircle2, FileText, Loader2, Plus, Trash2, X } from 'lucide-react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import { toast } from 'sonner';
+
+import { knowledgeBaseApi } from '@/api';
+import type { KnowledgeDocumentStatus, KnowledgeDocumentView } from '@/api';
+import { DeleteDialog } from '@/components/dialog/DeleteDialog.tsx';
+import { Button } from '@/components/ui/button.tsx';
+import {
+	Empty,
+	EmptyContent,
+	EmptyDescription,
+	EmptyHeader,
+	EmptyMedia,
+	EmptyTitle,
+} from '@/components/ui/empty.tsx';
+import { useUploadContext } from '@/context/UploadContext';
+import { isInFlight } from '@/context/uploadTypes';
+import type { UploadPhase, UploadTask } from '@/context/uploadTypes';
+import { useDocumentStatusPolling } from '@/hooks/useDocumentStatusPolling';
+import { useKnowledgeDocuments } from '@/hooks/useKnowledgeDocuments';
+import { useKnowledgeSupportedContentTypes } from '@/hooks/useKnowledgeSupportedContentTypes';
+import { cn } from '@/lib/utils';
+
+interface KnowledgeDocumentsPanelProps {
+	knowledgeBaseId: string;
+}
+
+/**
+ * A row that the panel renders. Either a server-side document (the
+ * canonical record after upload returns) or a still-uploading local
+ * task. Uploads that have already produced a `documentId` are routed
+ * through the server row so the panel never double-renders one.
+ */
+type Row =
+	| { kind: 'server'; doc: KnowledgeDocumentView; localTask: UploadTask | null }
+	| { kind: 'local'; task: UploadTask };
+
+const TERMINAL_SERVER_STATUSES: KnowledgeDocumentStatus[] = ['ready', 'error'];
+
+function formatSize(bytes: number): string {
+	if (!bytes) return '—';
+	const units = ['B', 'KB', 'MB', 'GB'];
+	let value = bytes;
+	let i = 0;
+	while (value >= 1024 && i < units.length - 1) {
+		value /= 1024;
+		i++;
+	}
+	return `${value.toFixed(value >= 100 || i === 0 ? 0 : 1)} ${units[i]}`;
+}
+
+function StatusBadge({ phase }: { phase: UploadPhase }) {
+	const { t } = useTranslation();
+	const label = t(`knowledge.document.status.${phase}`);
+	const tone = (() => {
+		switch (phase) {
+			case 'ready':
+				return 'bg-emerald-500/10 text-emerald-700 dark:text-emerald-400';
+			case 'error':
+				return 'bg-destructive/10 text-destructive';
+			case 'cancelled':
+				return 'bg-muted text-muted-foreground';
+			case 'queued':
+			case 'uploading':
+			case 'pending':
+			case 'parsing':
+			case 'chunking':
+			case 'indexing':
+			default:
+				return 'bg-primary/10 text-primary';
+		}
+	})();
+	return (
+		<span
+			className={cn(
+				'inline-flex items-center gap-x-1 rounded-md px-1.5 py-0.5 text-[10px] font-medium',
+				tone,
+			)}
+		>
+			{phase === 'ready' ? (
+				<CheckCircle2 className="size-3" />
+			) : phase === 'error' ? (
+				<AlertCircle className="size-3" />
+			) : phase === 'cancelled' ? null : (
+				<Loader2 className="size-3 animate-spin" />
+			)}
+			{label}
+		</span>
+	);
+}
+
+interface RowViewProps {
+	row: Row;
+	onCancel: (taskId: string) => void;
+	onDismiss: (taskId: string) => void;
+	onDelete: (doc: KnowledgeDocumentView) => void;
+}
+
+function RowView({ row, onCancel, onDismiss, onDelete }: RowViewProps) {
+	const { t } = useTranslation();
+
+	const filename = row.kind === 'server' ? row.doc.filename : row.task.filename;
+	const size = row.kind === 'server' ? row.doc.size : row.task.size;
+
+	// Phase resolution — the local task wins while the server hasn't
+	// caught up; once the server says `ready` / `error`, that's the
+	// truth.
+	const phase: UploadPhase = (() => {
+		if (row.kind === 'local') return row.task.phase;
+		const localPhase = row.localTask?.phase;
+		if (
+			localPhase &&
+			!TERMINAL_SERVER_STATUSES.includes(row.doc.status as KnowledgeDocumentStatus)
+		) {
+			return localPhase;
+		}
+		return row.doc.status;
+	})();
+
+	// Progress bar logic: byte-level during `uploading`; otherwise a
+	// coarse phase-derived value so the user gets visible movement.
+	const { progressValue, indeterminate } = (() => {
+		if (phase === 'uploading' && row.kind === 'local') {
+			if (!row.task.size) return { progressValue: 0, indeterminate: true };
+			return {
+				progressValue: Math.min(100, Math.round((row.task.loaded / row.task.size) * 100)),
+				indeterminate: false,
+			};
+		}
+		switch (phase) {
+			case 'queued':
+				return { progressValue: 5, indeterminate: false };
+			case 'pending':
+				return { progressValue: 35, indeterminate: true };
+			case 'parsing':
+				return { progressValue: 55, indeterminate: true };
+			case 'chunking':
+				return { progressValue: 75, indeterminate: true };
+			case 'indexing':
+				return { progressValue: 90, indeterminate: true };
+			case 'ready':
+				return { progressValue: 100, indeterminate: false };
+			default:
+				return { progressValue: 0, indeterminate: false };
+		}
+	})();
+
+	const error = row.kind === 'local' ? row.task.error : row.doc.error;
+	const chunkCount = row.kind === 'server' ? row.doc.chunk_count : row.task.documentId ? 0 : 0;
+
+	const taskIdForCancel =
+		row.kind === 'local' ? row.task.taskId : (row.localTask?.taskId ?? null);
+
+	const showProgress = phase !== 'ready' && phase !== 'cancelled';
+
+	return (
+		<div className="border-border bg-card flex flex-col gap-y-2 rounded-lg border p-3">
+			<div className="flex items-start gap-x-3">
+				<FileText className="text-muted-foreground mt-0.5 size-4 shrink-0" />
+				<div className="flex min-w-0 flex-1 flex-col gap-y-0.5">
+					<div className="flex items-center gap-x-2">
+						<span className="truncate text-sm font-medium">{filename}</span>
+						<StatusBadge phase={phase} />
+					</div>
+					<div className="text-muted-foreground flex items-center gap-x-2 text-xs">
+						<span>{formatSize(size)}</span>
+						{chunkCount > 0 && (
+							<>
+								<span>·</span>
+								<span>
+									{t('knowledge.document.chunkCount', {
+										count: chunkCount,
+									})}
+								</span>
+							</>
+						)}
+					</div>
+				</div>
+				<div className="flex shrink-0 items-center gap-x-1">
+					{phase === 'queued' || phase === 'uploading' ? (
+						<Button
+							variant="ghost"
+							size="icon-xs"
+							onClick={() => taskIdForCancel && onCancel(taskIdForCancel)}
+							aria-label={t('knowledge.document.actions.cancel')}
+						>
+							<X className="size-3.5" />
+						</Button>
+					) : phase === 'cancelled' || phase === 'error' ? (
+						row.kind === 'local' ? (
+							<Button
+								variant="ghost"
+								size="icon-xs"
+								onClick={() => onDismiss(row.task.taskId)}
+								aria-label={t('knowledge.document.actions.dismiss')}
+							>
+								<X className="size-3.5" />
+							</Button>
+						) : (
+							<Button
+								variant="ghost"
+								size="icon-xs"
+								onClick={() => onDelete(row.doc)}
+								aria-label={t('knowledge.document.actions.remove')}
+							>
+								<Trash2 className="size-3.5" />
+							</Button>
+						)
+					) : row.kind === 'server' ? (
+						<Button
+							variant="ghost"
+							size="icon-xs"
+							onClick={() => onDelete(row.doc)}
+							aria-label={t('knowledge.document.actions.remove')}
+						>
+							<Trash2 className="size-3.5" />
+						</Button>
+					) : null}
+				</div>
+			</div>
+			{showProgress && (
+				<div className="bg-muted relative h-1 w-full overflow-hidden rounded-full">
+					<div
+						className={cn(
+							'h-full rounded-full transition-all',
+							phase === 'error' ? 'bg-destructive' : 'bg-primary',
+							indeterminate && 'animate-pulse',
+						)}
+						style={{ width: `${progressValue}%` }}
+					/>
+				</div>
+			)}
+			{phase === 'error' && error && <p className="text-destructive text-xs">{error}</p>}
+		</div>
+	);
+}
+
+export function KnowledgeDocumentsPanel({ knowledgeBaseId }: KnowledgeDocumentsPanelProps) {
+	const { t } = useTranslation();
+	const fileInputRef = useRef<HTMLInputElement>(null);
+	const [dragOver, setDragOver] = useState(false);
+	const [deleteTarget, setDeleteTarget] = useState<KnowledgeDocumentView | null>(null);
+
+	const { enqueue, cancel, dismiss, tasksForKb, clearFinishedForKb } = useUploadContext();
+	const { documents, refetch } = useKnowledgeDocuments(knowledgeBaseId);
+	const tasks = tasksForKb(knowledgeBaseId);
+	const { statuses } = useDocumentStatusPolling({
+		knowledgeBaseId,
+		documents,
+	});
+	const { mediaTypes, extensions } = useKnowledgeSupportedContentTypes();
+
+	// Lowercased extension set used to gate `handleFiles`. Built once
+	// per render — the underlying list is shared across the app via a
+	// module-level cache so this stays cheap.
+	const extensionSet = useMemo(
+		() => new Set(extensions.map((ext) => ext.toLowerCase())),
+		[extensions],
+	);
+	// `<input accept>` takes a comma-separated string of MIME types and
+	// `.ext` tokens. We hand it both because browsers diverge on which
+	// they honour for any given filename — extensions filter the picker
+	// dialog, MIME types catch programmatic drops.
+	const acceptAttr = useMemo(
+		() => [...extensions, ...mediaTypes].join(','),
+		[extensions, mediaTypes],
+	);
+
+	// Refetch the canonical list whenever a polled doc reaches a
+	// terminal state — this is the single hook that pulls in the worker's
+	// final `chunk_count` and any updates to `error`.
+	const terminalIdsKey = useMemo(() => {
+		const ids: string[] = [];
+		for (const id of Object.keys(statuses)) {
+			const s = statuses[id];
+			if (s.status === 'ready' || s.status === 'error') ids.push(id);
+		}
+		return ids.join(',');
+	}, [statuses]);
+	const lastRefetchedKey = useRef('');
+	useEffect(() => {
+		if (!terminalIdsKey) return;
+		if (terminalIdsKey === lastRefetchedKey.current) return;
+		lastRefetchedKey.current = terminalIdsKey;
+		void refetch();
+	}, [terminalIdsKey, refetch]);
+
+	// Merge tasks + documents into a single ordered row list.
+	const rows: Row[] = useMemo(() => {
+		const tasksByDocId = new Map<string, UploadTask>();
+		const tasksWithoutDoc: UploadTask[] = [];
+		for (const task of tasks) {
+			if (task.documentId) tasksByDocId.set(task.documentId, task);
+			else tasksWithoutDoc.push(task);
+		}
+		const docRows: Row[] = documents.map((doc) => ({
+			kind: 'server',
+			doc,
+			localTask: tasksByDocId.get(doc.id) ?? null,
+		}));
+		const localRows: Row[] = tasksWithoutDoc.map((task) => ({
+			kind: 'local',
+			task,
+		}));
+		// Local-only rows go first (they're either uploading or queued
+		// — both are user-visible "I just hit upload" states).
+		return [...localRows, ...docRows];
+	}, [documents, tasks]);
+
+	const onUploadClick = useCallback(() => {
+		fileInputRef.current?.click();
+	}, []);
+
+	const handleFiles = useCallback(
+		(files: FileList | File[]) => {
+			const arr = Array.from(files);
+			if (arr.length === 0) return;
+			// When the capability list hasn't loaded yet, allow everything
+			// through — the backend still rejects unsupported uploads.
+			// Once we have the list, filter client-side by extension
+			// (`file.type` is unreliable across browsers/OSes).
+			const accepted: File[] = [];
+			for (const f of arr) {
+				if (extensionSet.size === 0) {
+					accepted.push(f);
+					continue;
+				}
+				const dot = f.name.lastIndexOf('.');
+				const ext = dot >= 0 ? f.name.slice(dot).toLowerCase() : '';
+				if (ext && extensionSet.has(ext)) {
+					accepted.push(f);
+				} else {
+					toast.error(
+						t('knowledge.document.unsupportedExtension', {
+							name: f.name,
+						}),
+					);
+				}
+			}
+			if (accepted.length === 0) return;
+			enqueue(knowledgeBaseId, accepted);
+		},
+		[enqueue, knowledgeBaseId, extensionSet, t],
+	);
+
+	const onFileInputChange = useCallback(
+		(e: React.ChangeEvent<HTMLInputElement>) => {
+			if (e.target.files) handleFiles(e.target.files);
+			// Reset so picking the same file twice re-fires the change.
+			e.target.value = '';
+		},
+		[handleFiles],
+	);
+
+	const onDrop = useCallback(
+		(e: React.DragEvent<HTMLDivElement>) => {
+			e.preventDefault();
+			setDragOver(false);
+			if (e.dataTransfer.files) handleFiles(e.dataTransfer.files);
+		},
+		[handleFiles],
+	);
+
+	const onDragOver = useCallback((e: React.DragEvent<HTMLDivElement>) => {
+		e.preventDefault();
+		setDragOver(true);
+	}, []);
+
+	const onDragLeave = useCallback(() => setDragOver(false), []);
+
+	const handleDelete = useCallback(async () => {
+		if (!deleteTarget) return;
+		try {
+			await knowledgeBaseApi.deleteDocument(knowledgeBaseId, deleteTarget.id);
+			await refetch();
+		} catch {
+			toast.error(t('knowledge.document.deleteError'));
+		}
+	}, [deleteTarget, knowledgeBaseId, refetch, t]);
+
+	const hasFinishedLocalTasks = tasks.some((t) => !isInFlight(t.phase));
+
+	const totalCount = rows.length;
+
+	return (
+		<div className="flex flex-col gap-y-4">
+			<div className="flex items-center justify-between">
+				<h3 className="text-sm font-semibold">
+					{t('knowledge.document.countLabel', { count: totalCount })}
+				</h3>
+				<div className="flex items-center gap-x-2">
+					{hasFinishedLocalTasks && (
+						<Button
+							variant="ghost"
+							size="sm"
+							onClick={() => clearFinishedForKb(knowledgeBaseId)}
+						>
+							{t('knowledge.document.actions.clearFinished')}
+						</Button>
+					)}
+					<Button variant="outline" size="sm" onClick={onUploadClick}>
+						<Plus className="size-3.5" />
+						{t('knowledge.document.uploadButtonShort')}
+					</Button>
+				</div>
+			</div>
+
+			<input
+				ref={fileInputRef}
+				type="file"
+				multiple
+				accept={acceptAttr || undefined}
+				className="hidden"
+				onChange={onFileInputChange}
+			/>
+
+			<div
+				onDrop={onDrop}
+				onDragOver={onDragOver}
+				onDragLeave={onDragLeave}
+				className={cn(
+					'rounded-lg border border-dashed transition-colors',
+					dragOver ? 'border-primary bg-primary/5' : 'border-border bg-transparent',
+				)}
+			>
+				{rows.length === 0 ? (
+					<Empty className="border-none py-6">
+						<EmptyHeader>
+							<EmptyMedia variant="icon">
+								<FileText />
+							</EmptyMedia>
+							<EmptyTitle>{t('knowledge.document.emptyTitle')}</EmptyTitle>
+							<EmptyDescription>
+								{t('knowledge.document.emptyDescription')}
+							</EmptyDescription>
+						</EmptyHeader>
+						<EmptyContent>
+							<Button variant="outline" size="sm" onClick={onUploadClick}>
+								<Plus className="size-3.5" />
+								{t('knowledge.document.uploadButton')}
+							</Button>
+							<p className="text-muted-foreground mt-2 text-xs">
+								{t('knowledge.document.dropHintIdle')}
+							</p>
+						</EmptyContent>
+					</Empty>
+				) : (
+					<div className="flex flex-col gap-y-2 p-2">
+						{rows.map((row) => (
+							<RowView
+								key={
+									row.kind === 'server'
+										? `srv-${row.doc.id}`
+										: `tsk-${row.task.taskId}`
+								}
+								row={row}
+								onCancel={cancel}
+								onDismiss={dismiss}
+								onDelete={setDeleteTarget}
+							/>
+						))}
+					</div>
+				)}
+			</div>
+
+			<DeleteDialog
+				open={deleteTarget !== null}
+				onOpenChange={(open) => {
+					if (!open) setDeleteTarget(null);
+				}}
+				title={t('knowledge.document.deleteConfirmTitle')}
+				description={t('knowledge.document.deleteConfirmDescription', {
+					name: deleteTarget?.filename ?? '',
+				})}
+				onConfirm={handleDelete}
+			/>
+		</div>
+	);
+}
diff --git a/examples/web_ui/frontend/src/components/layout/AppLayout.tsx b/examples/web_ui/frontend/src/components/layout/AppLayout.tsx
new file mode 100644
index 0000000..a8f4371
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/layout/AppLayout.tsx
@@ -0,0 +1,17 @@
+import { Outlet } from 'react-router-dom';
+
+import { AppSidebar } from '@/components/layout/AppSidebar';
+import { SidebarInset, SidebarProvider } from '@/components/ui/sidebar';
+
+export function AppLayout() {
+	return (
+		<div className="h-screen flex">
+			<SidebarProvider>
+				<AppSidebar />
+				<SidebarInset className="flex-1 overflow-hidden">
+					<Outlet />
+				</SidebarInset>
+			</SidebarProvider>
+		</div>
+	);
+}
diff --git a/examples/web_ui/frontend/src/components/layout/AppSidebar.tsx b/examples/web_ui/frontend/src/components/layout/AppSidebar.tsx
new file mode 100644
index 0000000..60aeb9a
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/layout/AppSidebar.tsx
@@ -0,0 +1,154 @@
+import {
+	BotMessageSquare,
+	Calendars,
+	Compass,
+	KeyRound,
+	Languages,
+	LibraryBig,
+	Settings,
+} from 'lucide-react';
+import { useOnborda } from 'onborda';
+import { useNavigate, useLocation } from 'react-router-dom';
+
+import AgentScope from '@/assets/images/agentscope.svg?react';
+import { CHAT_TOUR_NAME } from '@/components/tour/chatTourSteps';
+import {
+	Sidebar,
+	SidebarContent,
+	SidebarFooter,
+	SidebarGroup,
+	SidebarGroupContent,
+	SidebarHeader,
+	SidebarMenu,
+	SidebarMenuButton,
+	SidebarMenuItem,
+} from '@/components/ui/sidebar';
+import i18n from '@/i18n';
+import { useTranslation } from '@/i18n/useI18n';
+
+export function AppSidebar() {
+	const navigate = useNavigate();
+	const location = useLocation();
+	const { t } = useTranslation();
+	const { startOnborda } = useOnborda();
+
+	const handleStartTour = () => {
+		if (!location.pathname.startsWith('/chat')) {
+			// Page not mounted yet — leave a flag, navigate, and let the
+			// ChatTourController auto-trigger after ChatPage mounts.
+			sessionStorage.setItem('force_tour', '1');
+			navigate('/chat');
+		} else {
+			startOnborda(CHAT_TOUR_NAME);
+		}
+	};
+
+	const handleToggleLanguage = () => {
+		const next = i18n.language.startsWith('zh') ? 'en' : 'zh';
+		i18n.changeLanguage(next);
+	};
+
+	return (
+		<Sidebar collapsible="none" className="w-[calc(var(--sidebar-width-icon)+1px)]! border-r">
+			<SidebarHeader>
+				<div className="flex items-center justify-center h-12 mt-2">
+					<AgentScope className="size-8 items-center justify-center rounded-lg" />
+				</div>
+			</SidebarHeader>
+			<SidebarContent>
+				<SidebarGroup>
+					<SidebarGroupContent>
+						<SidebarMenu>
+							<SidebarMenuItem key={'chat'}>
+								<SidebarMenuButton
+									tooltip={{ children: t('common.chat'), hidden: false }}
+									isActive={
+										location.pathname === '/chat' ||
+										location.pathname.startsWith('/chat/')
+									}
+									onClick={() => navigate('/chat')}
+									className="px-2.5 md:px-2"
+								>
+									<BotMessageSquare />
+								</SidebarMenuButton>
+							</SidebarMenuItem>
+							<SidebarMenuItem>
+								<SidebarMenuButton
+									tooltip={{ children: t('common.schedule'), hidden: false }}
+									isActive={location.pathname === '/schedule'}
+									onClick={() => navigate('/schedule')}
+									className="px-2"
+								>
+									<Calendars />
+								</SidebarMenuButton>
+							</SidebarMenuItem>
+						</SidebarMenu>
+					</SidebarGroupContent>
+				</SidebarGroup>
+				<SidebarGroup>
+					<SidebarGroupContent>
+						<SidebarMenu>
+							<SidebarMenuItem>
+								<SidebarMenuButton
+									tooltip={{ children: t('common.credential'), hidden: false }}
+									isActive={location.pathname === '/credential'}
+									onClick={() => navigate('/credential')}
+									className="px-2"
+								>
+									<KeyRound />
+								</SidebarMenuButton>
+							</SidebarMenuItem>
+							<SidebarMenuItem>
+								<SidebarMenuButton
+									tooltip={{ children: t('common.knowledge'), hidden: false }}
+									isActive={location.pathname === '/knowledge'}
+									onClick={() => navigate('/knowledge')}
+									className="px-2"
+								>
+									<LibraryBig />
+								</SidebarMenuButton>
+							</SidebarMenuItem>
+						</SidebarMenu>
+					</SidebarGroupContent>
+				</SidebarGroup>
+			</SidebarContent>
+			<SidebarFooter>
+				<SidebarMenu>
+					<SidebarMenuItem>
+						<SidebarMenuButton
+							tooltip={{
+								children: i18n.language.startsWith('zh')
+									? t('common.switchToEn')
+									: t('common.switchToZh'),
+								hidden: false,
+							}}
+							onClick={handleToggleLanguage}
+							className="px-2"
+						>
+							<Languages />
+						</SidebarMenuButton>
+					</SidebarMenuItem>
+					<SidebarMenuItem>
+						<SidebarMenuButton
+							tooltip={{ children: t('tour.trigger'), hidden: false }}
+							onClick={handleStartTour}
+							className="px-2"
+						>
+							<Compass />
+						</SidebarMenuButton>
+					</SidebarMenuItem>
+					<SidebarMenuItem>
+						<SidebarMenuButton
+							tooltip={{ children: t('common.settings'), hidden: false }}
+							isActive={location.pathname === '/setup'}
+							onClick={() => navigate('/setup')}
+							className="px-2"
+						>
+							<Settings />
+						</SidebarMenuButton>
+					</SidebarMenuItem>
+				</SidebarMenu>
+			</SidebarFooter>
+		</Sidebar>
+	);
+}
diff --git a/examples/web_ui/frontend/src/components/panel/KnowledgeBasePanel.tsx b/examples/web_ui/frontend/src/components/panel/KnowledgeBasePanel.tsx
new file mode 100644
index 0000000..10d4eb3
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/panel/KnowledgeBasePanel.tsx
@@ -0,0 +1,156 @@
+import { FileX, Search, SearchX } from 'lucide-react';
+import { useMemo, useState } from 'react';
+
+import type { KnowledgeBaseView, SessionKnowledgeConfig } from '@/api';
+import { PanelEmpty } from '@/components/panel/PanelEmpty';
+import { Badge } from '@/components/ui/badge';
+import { Checkbox } from '@/components/ui/checkbox';
+import { InputGroup, InputGroupAddon, InputGroupInput } from '@/components/ui/input-group';
+import { Item, ItemContent, ItemDescription, ItemTitle } from '@/components/ui/item';
+import { useTranslation } from '@/i18n/useI18n';
+
+interface KnowledgeBasePanelProps {
+	/** The user's knowledge bases. */
+	knowledgeBases: KnowledgeBaseView[];
+	/** Whether the KB list is still loading. */
+	loading?: boolean;
+	/**
+	 * Current attachment for this session. `null` means no KBs attached
+	 * and the panel renders with an empty selection.
+	 */
+	value: SessionKnowledgeConfig | null;
+	/**
+	 * Persist a new attachment to the session. The owner is responsible
+	 * for awaiting the backend round-trip and refreshing session state.
+	 * Pass `null` to detach every KB.
+	 */
+	onChange: (next: SessionKnowledgeConfig | null) => void;
+	/** Disable the entire panel — e.g. when no session is selected. */
+	disabled?: boolean;
+}
+
+/**
+ * Pure content body for the Knowledge Base dock panel: a search box and
+ * a checkbox list of the user's KBs.
+ *
+ * Middleware parameter editing lives in
+ * {@link KnowledgeBaseParametersPopover}, which the owner mounts in the
+ * panel header's `actions` slot — that keeps this body focused on
+ * picking KBs rather than mixing two unrelated forms in the same scroll
+ * area.
+ */
+export function KnowledgeBasePanel({
+	knowledgeBases,
+	loading = false,
+	value,
+	onChange,
+	disabled = false,
+}: KnowledgeBasePanelProps) {
+	const { t } = useTranslation();
+	const [search, setSearch] = useState('');
+
+	const selectedIds = useMemo(() => new Set(value?.knowledge_base_ids ?? []), [value]);
+
+	const filtered = search
+		? knowledgeBases.filter((kb) => kb.name.toLowerCase().includes(search.toLowerCase()))
+		: knowledgeBases;
+
+	const toggleKb = (kbId: string, checked: boolean) => {
+		const next = new Set(selectedIds);
+		if (checked) next.add(kbId);
+		else next.delete(kbId);
+		const ids = Array.from(next);
+		if (ids.length === 0) {
+			onChange(null);
+			return;
+		}
+		onChange({
+			knowledge_base_ids: ids,
+			parameters: value?.parameters ?? {},
+		});
+	};
+
+	return (
+		<div className="flex flex-col flex-1 min-h-0 gap-y-2">
+			<span className="text-muted-foreground text-sm">
+				{t('panel.knowledge.description')}
+			</span>
+			<InputGroup>
+				<InputGroupInput
+					placeholder={t('panel.knowledge.searchPlaceholder')}
+					value={search}
+					onChange={(e) => setSearch(e.target.value)}
+					disabled={disabled}
+				/>
+				<InputGroupAddon align="inline-end">
+					<Search />
+				</InputGroupAddon>
+			</InputGroup>
+
+			<div className="flex flex-col flex-1 min-h-0 gap-y-3 overflow-y-auto">
+				{loading ? (
+					<div className="flex flex-1 items-center justify-center">
+						<p className="text-muted-foreground text-sm">{t('panel.loading')}</p>
+					</div>
+				) : filtered.length === 0 ? (
+					<PanelEmpty
+						icon={search ? SearchX : FileX}
+						title={
+							search ? t('panel.search.emptyTitle') : t('panel.knowledge.emptyTitle')
+						}
+						description={
+							search
+								? t('panel.search.emptyDescription', { query: search })
+								: t('panel.knowledge.emptyDescription')
+						}
+					/>
+				) : (
+					<div className="flex flex-col gap-y-2">
+						{filtered.map((kb) => {
+							const isSelected = selectedIds.has(kb.id);
+							const inputId = `kb-${kb.id}`;
+							return (
+								<Item
+									key={kb.id}
+									variant="outline"
+									data-selected={isSelected || undefined}
+								>
+									<Checkbox
+										id={inputId}
+										checked={isSelected}
+										disabled={disabled}
+										onCheckedChange={(checked) => toggleKb(kb.id, !!checked)}
+									/>
+									<ItemContent>
+										<ItemTitle>
+											<label htmlFor={inputId} className="cursor-pointer">
+												{kb.name}
+											</label>
+										</ItemTitle>
+										{kb.description ? (
+											<ItemDescription>{kb.description}</ItemDescription>
+										) : null}
+										<div className="flex flex-wrap gap-1 mt-1">
+											<Badge
+												variant="outline"
+												className="text-[10px] px-1 py-0"
+											>
+												{kb.embedding_model_config.model}
+											</Badge>
+											<Badge
+												variant="outline"
+												className="text-[10px] px-1 py-0"
+											>
+												{kb.embedding_model_config.dimensions}d
+											</Badge>
+										</div>
+									</ItemContent>
+								</Item>
+							);
+						})}
+					</div>
+				)}
+			</div>
+		</div>
+	);
+}
diff --git a/examples/web_ui/frontend/src/components/panel/McpPanel.tsx b/examples/web_ui/frontend/src/components/panel/McpPanel.tsx
new file mode 100644
index 0000000..bcbca73
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/panel/McpPanel.tsx
@@ -0,0 +1,146 @@
+import { PlusCircle, Search, SearchX, Trash, Unplug } from 'lucide-react';
+import { useState } from 'react';
+
+import type { MCPClient, MCPClientStatus } from '@/api';
+import { DeleteDialog } from '@/components/dialog/DeleteDialog.tsx';
+import { CreateMCPDialog } from '@/components/dialog/MCPDialog.tsx';
+import { PanelEmpty } from '@/components/panel/PanelEmpty';
+import { Button } from '@/components/ui/button';
+import { InputGroup, InputGroupAddon, InputGroupInput } from '@/components/ui/input-group';
+import { Item, ItemActions, ItemContent, ItemDescription, ItemTitle } from '@/components/ui/item';
+import { Kbd, KbdGroup } from '@/components/ui/kbd';
+import { useTranslation } from '@/i18n/useI18n.ts';
+
+interface McpPanelProps {
+	/** The MCP servers equipped in the workspace. */
+	mcps: MCPClientStatus[];
+	/** Whether the MCP list is still loading. */
+	loading?: boolean;
+	/**
+	 * Add one or more MCP servers to the workspace.
+	 *
+	 * @param mcps - The MCP client configs to add.
+	 */
+	onAdd: (mcps: MCPClient[]) => Promise<void>;
+	/**
+	 * Remove an MCP server by name.
+	 *
+	 * @param name - The MCP server name to remove.
+	 */
+	onRemove: (name: string) => Promise<void>;
+}
+
+/**
+ * Pure content body for the MCP dock panel: a search box, the list of
+ * equipped MCP servers, and an "Add MCP" action. Holds only local UI
+ * state (search text, delete confirmation target); all data arrives
+ * via props so it owns no data fetching.
+ *
+ * Renders without its own header/border — the surrounding `Panel`
+ * chrome (from `PanelDock`) provides those.
+ *
+ * @param mcps - The MCP servers to list.
+ * @param loading - Whether the list is loading.
+ * @param onAdd - Add-MCP callback.
+ * @param onRemove - Remove-MCP callback.
+ * @returns The MCP panel body.
+ */
+export function McpPanel({ mcps, loading = false, onAdd, onRemove }: McpPanelProps) {
+	const { t } = useTranslation();
+	const [search, setSearch] = useState('');
+	const [deleteOpen, setDeleteOpen] = useState(false);
+	const [deleteTarget, setDeleteTarget] = useState<string | null>(null);
+
+	const filtered = search
+		? mcps.filter((m) => m.name.toLowerCase().includes(search.toLowerCase()))
+		: mcps;
+
+	return (
+		<div className="flex flex-col flex-1 min-h-0 gap-y-2">
+			<span className="text-muted-foreground text-sm">{t('panel.mcp.description')}</span>
+			<InputGroup>
+				<InputGroupInput
+					placeholder={t('panel.mcp.searchPlaceholder')}
+					value={search}
+					onChange={(e) => setSearch(e.target.value)}
+				/>
+				<InputGroupAddon align="inline-end">
+					<Search />
+				</InputGroupAddon>
+			</InputGroup>
+
+			{loading ? (
+				<div className="flex flex-1 items-center justify-center">
+					<p className="text-muted-foreground text-sm">{t('panel.loading')}</p>
+				</div>
+			) : filtered.length === 0 ? (
+				<PanelEmpty
+					icon={search ? SearchX : Unplug}
+					title={search ? t('panel.search.emptyTitle') : t('panel.mcp.emptyTitle')}
+					description={
+						search
+							? t('panel.search.emptyDescription', { query: search })
+							: t('panel.mcp.emptyDescription')
+					}
+				/>
+			) : (
+				<div className="flex flex-col flex-1 min-h-0 overflow-y-auto gap-y-2">
+					{filtered.map((mcp) => (
+						<Item key={mcp.name} variant="outline">
+							<ItemContent>
+								<ItemTitle className="flex items-center gap-x-2">
+									<span
+										className={`size-2 shrink-0 rounded-full ${mcp.is_healthy ? 'bg-green-500' : 'bg-red-500'}`}
+									/>
+									{mcp.name}
+								</ItemTitle>
+								<ItemDescription>
+									<KbdGroup>
+										<Kbd>
+											{mcp.mcp_config.type === 'stdio_mcp' ? 'STDIO' : 'HTTP'}
+										</Kbd>
+										<Kbd>
+											{t('panel.mcp.tools', { count: mcp.tools.length })}
+										</Kbd>
+									</KbdGroup>
+								</ItemDescription>
+							</ItemContent>
+							<ItemActions>
+								<Button
+									variant="outline"
+									size="icon-sm"
+									onClick={() => {
+										setDeleteTarget(mcp.name);
+										setDeleteOpen(true);
+									}}
+								>
+									<Trash />
+								</Button>
+							</ItemActions>
+						</Item>
+					))}
+				</div>
+			)}
+
+			<CreateMCPDialog onAdd={onAdd}>
+				<Button variant="default">
+					<PlusCircle />
+					{t('panel.mcp.add')}
+				</Button>
+			</CreateMCPDialog>
+
+			<DeleteDialog
+				open={deleteOpen}
+				onOpenChange={setDeleteOpen}
+				title={t('common.deleteTitle', {
+					entity: t('dialog-mcp-delete.entity'),
+					name: deleteTarget ?? '',
+				})}
+				description={t('common.deleteDescription')}
+				onConfirm={async () => {
+					if (deleteTarget) await onRemove(deleteTarget);
+				}}
+			/>
+		</div>
+	);
+}
diff --git a/examples/web_ui/frontend/src/components/panel/PanelDock.tsx b/examples/web_ui/frontend/src/components/panel/PanelDock.tsx
new file mode 100644
index 0000000..de2cd72
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/panel/PanelDock.tsx
@@ -0,0 +1,183 @@
+import { X } from 'lucide-react';
+import { Fragment, type ReactNode } from 'react';
+
+import { Button } from '@/components/ui/button.tsx';
+import {
+	ResizableHandle,
+	ResizablePanel,
+	ResizablePanelGroup,
+} from '@/components/ui/resizable.tsx';
+import { Separator } from '@/components/ui/separator';
+
+/**
+ * Identifier for a dockable panel. Used both as the React key and to
+ * look its descriptor up in {@link PanelDockProps.panels}.
+ */
+export type PanelKey = 'plan' | 'mcp' | 'skill' | 'permission' | 'knowledge';
+
+/**
+ * The presentation of a single panel: header chrome plus its already
+ * data-bound content node. Built by the owner (ChatViewport) so that
+ * the dock itself stays free of any business/data dependency.
+ */
+export interface PanelDescriptor {
+	/** Header title shown in the panel's chrome. */
+	title: ReactNode;
+	/** Optional leading icon shown next to the title. */
+	icon?: ReactNode;
+	/**
+	 * Optional header-bar actions rendered to the left of the close
+	 * button — typically `<Button variant="ghost" size="icon-sm">` items
+	 * that open popovers / dropdowns (e.g. a parameters popover that
+	 * would otherwise crowd the panel body).
+	 */
+	actions?: ReactNode;
+	/**
+	 * The panel body. Constructed by the owner with live data
+	 * (e.g. `<TaskPanel tasksContext={...} />`) so it always reflects
+	 * the latest state on every owner re-render.
+	 */
+	content: ReactNode;
+}
+
+interface PanelDockProps {
+	/**
+	 * Controlled layout state. Outer array = columns (laid out left to
+	 * right), inner array = the panels stacked top to bottom within a
+	 * column (max 2). The dock never mutates this; it only renders it.
+	 */
+	layout: PanelKey[][];
+	/**
+	 * Lookup from {@link PanelKey} to its {@link PanelDescriptor}. Only
+	 * needs to contain keys that may appear in {@link layout}.
+	 */
+	panels: Record<PanelKey, PanelDescriptor>;
+	/**
+	 * Invoked when a panel's close button is clicked. The owner is
+	 * responsible for removing the key from {@link layout} (and dropping
+	 * the column if it becomes empty).
+	 *
+	 * @param key - The panel being closed.
+	 */
+	onClosePanel: (key: PanelKey) => void;
+}
+
+/**
+ * Minimum width of a dock column. Keeps a panel's content (search box,
+ * list items) from being squeezed unusably narrow.
+ */
+const COLUMN_MIN_WIDTH = '20rem';
+
+/**
+ * Minimum height of a single panel within a column. Guarantees the
+ * title bar plus a sliver of content stays visible.
+ */
+const PANEL_MIN_HEIGHT = '6rem';
+
+interface PanelProps {
+	title: ReactNode;
+	icon?: ReactNode;
+	actions?: ReactNode;
+	onClose: () => void;
+	children: ReactNode;
+}
+
+/**
+ * Generic panel chrome: a bordered container with a title bar (icon +
+ * title + optional actions + close button) and a flexible body. Content
+ * components are rendered as `children` and should not draw their own
+ * header/border.
+ *
+ * @param title - Header title.
+ * @param icon - Optional leading icon.
+ * @param actions - Optional nodes rendered to the left of the close
+ *   button (e.g. a settings popover trigger).
+ * @param onClose - Called when the close button is clicked.
+ * @param children - The panel body.
+ * @returns The panel chrome element.
+ */
+export const Panel = ({ title, icon, actions, onClose, children }: PanelProps) => {
+	return (
+		<div className="flex flex-1 flex-col border rounded-sm h-full py-1 min-h-0">
+			<div className="flex items-center justify-between px-2">
+				<span className="flex items-center gap-x-1.5 text-sm">
+					{icon}
+					{title}
+				</span>
+				<div className="flex items-center gap-x-0.5">
+					{actions}
+					{actions ? (
+						<Separator
+							orientation="vertical"
+							className="mx-0.5 data-vertical:h-4 data-vertical:self-center"
+						/>
+					) : null}
+					<Button variant="ghost" size="icon-sm" onClick={onClose}>
+						<X />
+					</Button>
+				</div>
+			</div>
+			<div className="flex flex-1 flex-col min-h-0 overflow-auto px-2">{children}</div>
+		</div>
+	);
+};
+
+/**
+ * A pure layout engine for the right-hand dockable panel area.
+ *
+ * Knows nothing about MCP / tasks / skills — it just arranges whatever
+ * panels {@link PanelDockProps.layout} describes into a grid of
+ * horizontally-resizable columns, each containing up to two
+ * vertically-resizable rows. The panel bodies arrive pre-built via
+ * {@link PanelDockProps.panels}.
+ *
+ * Rendered as a sibling of the chat panel inside the outer horizontal
+ * `ResizablePanelGroup`, so it emits one `ResizablePanel` per column
+ * (with a `ResizableHandle` between columns) to share that group.
+ *
+ * @param layout - Controlled column/panel arrangement.
+ * @param panels - Descriptor lookup for each panel key.
+ * @param onClosePanel - Close-request callback.
+ * @returns The column fragment, or `null` when no panels are open.
+ */
+export const PanelDock = ({ layout, panels, onClosePanel }: PanelDockProps) => {
+	if (layout.length === 0) return null;
+
+	return (
+		<>
+			{layout.map((column, colIndex) => (
+				<Fragment key={`col-${column.join('-')}`}>
+					{colIndex > 0 && <ResizableHandle withHandle className="bg-transparent" />}
+					<ResizablePanel className="p-1" minSize={COLUMN_MIN_WIDTH} defaultSize="22rem">
+						<ResizablePanelGroup orientation="vertical">
+							{column.map((key, rowIndex) => {
+								const descriptor = panels[key];
+								if (!descriptor) return null;
+								return (
+									<Fragment key={key}>
+										{rowIndex > 0 && (
+											<ResizableHandle
+												withHandle
+												className="bg-transparent"
+											/>
+										)}
+										<ResizablePanel className="py-1" minSize={PANEL_MIN_HEIGHT}>
+											<Panel
+												title={descriptor.title}
+												icon={descriptor.icon}
+												actions={descriptor.actions}
+												onClose={() => onClosePanel(key)}
+											>
+												{descriptor.content}
+											</Panel>
+										</ResizablePanel>
+									</Fragment>
+								);
+							})}
+						</ResizablePanelGroup>
+					</ResizablePanel>
+				</Fragment>
+			))}
+		</>
+	);
+};
diff --git a/examples/web_ui/frontend/src/components/panel/PanelEmpty.tsx b/examples/web_ui/frontend/src/components/panel/PanelEmpty.tsx
new file mode 100644
index 0000000..fe3032a
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/panel/PanelEmpty.tsx
@@ -0,0 +1,46 @@
+import type { LucideIcon } from 'lucide-react';
+
+import {
+	Empty,
+	EmptyDescription,
+	EmptyHeader,
+	EmptyMedia,
+	EmptyTitle,
+} from '@/components/ui/empty';
+import { cn } from '@/lib/utils';
+
+interface PanelEmptyProps {
+	/** Icon communicating the kind of emptiness (no data vs no results). */
+	icon: LucideIcon;
+	/** Short heading, e.g. "No MCP servers" or "No results". */
+	title: string;
+	/** Optional secondary explanation line. */
+	description?: string;
+	className?: string;
+}
+
+/**
+ * A reusable empty-state for dock panels. Fills the remaining vertical
+ * space and centers an icon + title + optional description. Callers
+ * distinguish a "no data yet" state from a "search found nothing"
+ * state via the {@link icon} and {@link title} they pass.
+ *
+ * @param icon - The lucide icon to show.
+ * @param title - The empty-state heading.
+ * @param description - Optional explanatory text.
+ * @param className - Extra classes for the wrapper.
+ * @returns The centered empty-state element.
+ */
+export function PanelEmpty({ icon: Icon, title, description, className }: PanelEmptyProps) {
+	return (
+		<Empty className={cn('flex-1 border-0 p-4', className)}>
+			<EmptyHeader>
+				<EmptyMedia variant="icon">
+					<Icon />
+				</EmptyMedia>
+				<EmptyTitle>{title}</EmptyTitle>
+				{description ? <EmptyDescription>{description}</EmptyDescription> : null}
+			</EmptyHeader>
+		</Empty>
+	);
+}
diff --git a/examples/web_ui/frontend/src/components/panel/PermissionPanel.tsx b/examples/web_ui/frontend/src/components/panel/PermissionPanel.tsx
new file mode 100644
index 0000000..4baf1a9
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/panel/PermissionPanel.tsx
@@ -0,0 +1,213 @@
+import type { PermissionContext, PermissionRule } from '@agentscope-ai/agentscope/permission';
+import { Ban, CircleHelp, FolderOpen, ShieldCheck, ShieldX } from 'lucide-react';
+import { useEffect, useRef, useState } from 'react';
+
+import { PanelEmpty } from '@/components/panel/PanelEmpty';
+import { Badge } from '@/components/ui/badge';
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip';
+import { useTranslation } from '@/i18n/useI18n';
+
+/** The behavior keys we render sections for (excludes ``passthrough``). */
+type RuleBehavior = 'allow' | 'deny' | 'ask';
+
+interface PermissionPanelProps {
+	/**
+	 * The permission context to render. Pass ``null`` when no data is
+	 * available yet (renders an empty state).
+	 */
+	permissionContext: PermissionContext | null;
+}
+
+/** i18n key suffix for each behavior group title. */
+const BEHAVIOR_META: Record<RuleBehavior, { i18nKey: string; icon: typeof ShieldCheck }> = {
+	allow: { i18nKey: 'panel.permission.allow', icon: ShieldCheck },
+	deny: { i18nKey: 'panel.permission.deny', icon: Ban },
+	ask: { i18nKey: 'panel.permission.ask', icon: CircleHelp },
+};
+
+/**
+ * A monospace value (a path or rule pattern) that truncates to fit its
+ * row. When (and only when) the text is actually clipped, hovering
+ * reveals the full value in a tooltip anchored to the left.
+ *
+ * @param value - The text to display.
+ * @returns The truncating value element, with a tooltip when clipped.
+ */
+function TruncatedCode({ value }: { value: string }) {
+	const ref = useRef<HTMLSpanElement>(null);
+	const [truncated, setTruncated] = useState(false);
+
+	useEffect(() => {
+		const el = ref.current;
+		if (!el) return;
+		const check = () => setTruncated(el.scrollWidth > el.clientWidth);
+		check();
+		const observer = new ResizeObserver(check);
+		observer.observe(el);
+		return () => observer.disconnect();
+	}, [value]);
+
+	return (
+		<Tooltip>
+			<TooltipTrigger asChild>
+				<span ref={ref} className="min-w-0 flex-1 truncate text-left font-mono text-xs">
+					{value}
+				</span>
+			</TooltipTrigger>
+			{truncated ? (
+				<TooltipContent side="left" className="max-w-sm font-mono break-all">
+					{value}
+				</TooltipContent>
+			) : null}
+		</Tooltip>
+	);
+}
+
+/**
+ * A single tool's rule card: a header naming the tool plus one row per
+ * matching rule (pattern on the left, source on the right).
+ *
+ * @param toolName - The tool these rules apply to.
+ * @param rules - The rules configured for this tool under one behavior.
+ * @returns The tool card element.
+ */
+function ToolRuleCard({ toolName, rules }: { toolName: string; rules: PermissionRule[] }) {
+	const { t } = useTranslation();
+	return (
+		<div className="rounded-md border">
+			<div className="flex items-center gap-x-2 border-b px-2 py-1.5 text-sm font-medium">
+				{toolName}
+				<Badge variant="secondary" className="ml-auto">
+					{rules.length}
+				</Badge>
+			</div>
+			<ul className="flex flex-col">
+				{rules.map((rule, index) => (
+					<li
+						key={`${rule.rule_content ?? '*'}-${index}`}
+						className="flex items-center justify-between gap-x-2 px-2 py-1.5 text-xs not-last:border-b"
+					>
+						{rule.rule_content ? (
+							<TruncatedCode value={rule.rule_content} />
+						) : (
+							<span className="min-w-0 flex-1 text-muted-foreground">
+								{t('panel.permission.anyInvocation')}
+							</span>
+						)}
+						<Badge variant="outline" className="shrink-0">
+							{rule.source}
+						</Badge>
+					</li>
+				))}
+			</ul>
+		</div>
+	);
+}
+
+/**
+ * One behavior group (allow / deny / ask): a titled section that lists
+ * a {@link ToolRuleCard} per tool that has rules under this behavior.
+ *
+ * @param behavior - The behavior category for this section.
+ * @param ruleMap - Rules keyed by tool name for this behavior.
+ * @returns The section element, or ``null`` when there are no rules.
+ */
+function BehaviorGroup({
+	behavior,
+	ruleMap,
+}: {
+	behavior: RuleBehavior;
+	ruleMap: Record<string, PermissionRule[]> | undefined;
+}) {
+	const { t } = useTranslation();
+	const entries = Object.entries(ruleMap ?? {}).filter(([, rules]) => rules.length > 0);
+	if (entries.length === 0) return null;
+
+	const meta = BEHAVIOR_META[behavior];
+	const Icon = meta.icon;
+
+	return (
+		<div className="flex flex-col gap-y-1.5">
+			<div className="flex items-center gap-x-1.5 text-xs font-medium text-muted-foreground">
+				<Icon className="size-3.5" />
+				{t(meta.i18nKey)}
+			</div>
+			{entries.map(([toolName, rules]) => (
+				<ToolRuleCard key={toolName} toolName={toolName} rules={rules} />
+			))}
+		</div>
+	);
+}
+
+/**
+ * Pure content body for the Permission dock panel. Shows the active
+ * permission mode, the working directories in scope, and the configured
+ * rules grouped by behavior (deny / ask / allow) and then by tool. Data
+ * arrives via props so it owns no data fetching.
+ *
+ * Renders without its own header/border — the surrounding `Panel`
+ * chrome (from `PanelDock`) provides those.
+ *
+ * @param permissionContext - The permission context, or ``null``.
+ * @returns The permission panel body.
+ */
+export function PermissionPanel({ permissionContext }: PermissionPanelProps) {
+	const { t } = useTranslation();
+	const workingDirs = Object.values(permissionContext?.working_directories ?? {});
+	const hasRules =
+		Object.keys(permissionContext?.allow_rules ?? {}).length > 0 ||
+		Object.keys(permissionContext?.deny_rules ?? {}).length > 0 ||
+		Object.keys(permissionContext?.ask_rules ?? {}).length > 0;
+
+	return (
+		<div className="flex flex-col flex-1 min-h-0 gap-y-3">
+			<span className="text-muted-foreground text-sm">
+				{t('panel.permission.description')}
+			</span>
+
+			<div className="flex flex-col flex-1 min-h-0 overflow-y-auto gap-y-4">
+				{/* Working directories — always shown, with an empty state. */}
+				<div className="flex flex-col gap-y-1.5">
+					<div className="flex items-center gap-x-1.5 text-xs font-medium text-muted-foreground">
+						<FolderOpen className="size-3.5" />
+						{t('panel.permission.workingDirectories')}
+					</div>
+					{workingDirs.length === 0 ? (
+						<p className="text-muted-foreground text-xs px-1 py-2">
+							{t('panel.permission.noWorkingDirectories')}
+						</p>
+					) : (
+						<ul className="flex flex-col rounded-md border">
+							{workingDirs.map((dir) => (
+								<li
+									key={dir.path}
+									className="flex items-center justify-between gap-x-2 px-2 py-1.5 text-xs not-last:border-b"
+								>
+									<TruncatedCode value={dir.path} />
+									<Badge variant="outline" className="shrink-0">
+										{dir.source}
+									</Badge>
+								</li>
+							))}
+						</ul>
+					)}
+				</div>
+
+				{/* Rules grouped by behavior, then by tool. */}
+				{hasRules ? (
+					<>
+						<BehaviorGroup behavior="deny" ruleMap={permissionContext?.deny_rules} />
+						<BehaviorGroup behavior="ask" ruleMap={permissionContext?.ask_rules} />
+						<BehaviorGroup behavior="allow" ruleMap={permissionContext?.allow_rules} />
+					</>
+				) : (
+					<PanelEmpty
+						icon={ShieldX}
+						title={t('panel.permission.emptyTitle')}
+						description={t('panel.permission.emptyDescription')}
+					/>
+				)}
+			</div>
+		</div>
+	);
+}
diff --git a/examples/web_ui/frontend/src/components/panel/SkillPanel.tsx b/examples/web_ui/frontend/src/components/panel/SkillPanel.tsx
new file mode 100644
index 0000000..98593dd
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/panel/SkillPanel.tsx
@@ -0,0 +1,131 @@
+import { FileX, PlusCircle, Search, SearchX, Trash } from 'lucide-react';
+import { useState } from 'react';
+
+import type { Skill } from '@/api';
+import { AddSkillDialog } from '@/components/dialog/AddSkillDialog.tsx';
+import { DeleteDialog } from '@/components/dialog/DeleteDialog.tsx';
+import { PanelEmpty } from '@/components/panel/PanelEmpty';
+import { Button } from '@/components/ui/button';
+import { InputGroup, InputGroupAddon, InputGroupInput } from '@/components/ui/input-group';
+import { Item, ItemActions, ItemContent, ItemDescription, ItemTitle } from '@/components/ui/item';
+import { useTranslation } from '@/i18n/useI18n.ts';
+
+interface SkillPanelProps {
+	/** The skills equipped in the workspace. */
+	skills: Skill[];
+	/** Whether the skill list is still loading. */
+	loading?: boolean;
+	/**
+	 * Add a skill to the workspace.
+	 *
+	 * @param skillPath - Path of the skill to add.
+	 */
+	onAdd: (skillPath: string) => Promise<void>;
+	/**
+	 * Remove a skill by name.
+	 *
+	 * @param name - The skill name to remove.
+	 */
+	onRemove: (name: string) => Promise<void>;
+}
+
+/**
+ * Pure content body for the Skill dock panel: a search box, the list
+ * of equipped skills, and an "Add Skill" action. Holds only local UI
+ * state (search text, delete confirmation target); all data arrives
+ * via props so it owns no data fetching.
+ *
+ * Renders without its own header/border — the surrounding `Panel`
+ * chrome (from `PanelDock`) provides those.
+ *
+ * @param skills - The skills to list.
+ * @param loading - Whether the list is loading.
+ * @param onAdd - Add-skill callback.
+ * @param onRemove - Remove-skill callback.
+ * @returns The skill panel body.
+ */
+export function SkillPanel({ skills, loading = false, onAdd, onRemove }: SkillPanelProps) {
+	const { t } = useTranslation();
+	const [search, setSearch] = useState('');
+	const [deleteOpen, setDeleteOpen] = useState(false);
+	const [deleteTarget, setDeleteTarget] = useState<string | null>(null);
+
+	const filtered = search
+		? skills.filter((s) => s.name.toLowerCase().includes(search.toLowerCase()))
+		: skills;
+
+	return (
+		<div className="flex flex-col flex-1 min-h-0 gap-y-2">
+			<span className="text-muted-foreground text-sm">{t('panel.skill.description')}</span>
+			<InputGroup>
+				<InputGroupInput
+					placeholder={t('panel.skill.searchPlaceholder')}
+					value={search}
+					onChange={(e) => setSearch(e.target.value)}
+				/>
+				<InputGroupAddon align="inline-end">
+					<Search />
+				</InputGroupAddon>
+			</InputGroup>
+
+			{loading ? (
+				<div className="flex flex-1 items-center justify-center">
+					<p className="text-muted-foreground text-sm">{t('panel.loading')}</p>
+				</div>
+			) : filtered.length === 0 ? (
+				<PanelEmpty
+					icon={search ? SearchX : FileX}
+					title={search ? t('panel.search.emptyTitle') : t('panel.skill.emptyTitle')}
+					description={
+						search
+							? t('panel.search.emptyDescription', { query: search })
+							: t('panel.skill.emptyDescription')
+					}
+				/>
+			) : (
+				<div className="flex flex-col flex-1 min-h-0 overflow-y-auto gap-y-2">
+					{filtered.map((skill) => (
+						<Item key={skill.name} variant="outline">
+							<ItemContent>
+								<ItemTitle>{skill.name}</ItemTitle>
+								<ItemDescription>{skill.description}</ItemDescription>
+							</ItemContent>
+							<ItemActions>
+								<Button
+									variant="outline"
+									size="icon-sm"
+									onClick={() => {
+										setDeleteTarget(skill.name);
+										setDeleteOpen(true);
+									}}
+								>
+									<Trash />
+								</Button>
+							</ItemActions>
+						</Item>
+					))}
+				</div>
+			)}
+
+			<AddSkillDialog onAdd={onAdd}>
+				<Button variant="default">
+					<PlusCircle />
+					{t('panel.skill.add')}
+				</Button>
+			</AddSkillDialog>
+
+			<DeleteDialog
+				open={deleteOpen}
+				onOpenChange={setDeleteOpen}
+				title={t('common.deleteTitle', {
+					entity: t('dialog-mcp-delete.skillEntity'),
+					name: deleteTarget ?? '',
+				})}
+				description={t('dialog-mcp-delete.skillDescription')}
+				onConfirm={async () => {
+					if (deleteTarget) await onRemove(deleteTarget);
+				}}
+			/>
+		</div>
+	);
+}
diff --git a/examples/web_ui/frontend/src/components/panel/TaskPanel.tsx b/examples/web_ui/frontend/src/components/panel/TaskPanel.tsx
new file mode 100644
index 0000000..6f465e4
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/panel/TaskPanel.tsx
@@ -0,0 +1,163 @@
+import type { Task, TaskContext } from '@agentscope-ai/agentscope/state';
+import { Ellipsis, ListX, Loader2, Square, SquareCheck } from 'lucide-react';
+import { useState } from 'react';
+
+import { PanelEmpty } from '@/components/panel/PanelEmpty';
+import { Badge } from '@/components/ui/badge';
+import { Button } from '@/components/ui/button';
+import { useTranslation } from '@/i18n/useI18n';
+import { cn } from '@/lib/utils';
+
+interface TaskPanelProps {
+	/**
+	 * The task context to render. Pass ``null`` when no data is
+	 * available yet (renders nothing).
+	 */
+	tasksContext: TaskContext | null;
+	className?: string;
+}
+
+/**
+ * State icon for a single task row.
+ *
+ * @param state - The task's current state.
+ * @returns An icon element sized for inline display.
+ */
+function StateIcon({ state }: { state: Task['state'] }) {
+	switch (state) {
+		case 'completed':
+			return <SquareCheck className="size-3 shrink-0" />;
+		case 'in_progress':
+			return <Loader2 className="size-3 animate-spin shrink-0" />;
+		default:
+			return <Square className="size-3 shrink-0" />;
+	}
+}
+
+/**
+ * Filters the task list so that only the last 3 of any leading run of
+ * completed tasks are shown; earlier ones are replaced by a single
+ * ellipsis sentinel.
+ *
+ * @param tasks - The full ordered task array.
+ * @returns An object with the visible task slice and a boolean flag
+ *   indicating whether the ellipsis row should be rendered.
+ */
+function filterTasksWithEllipsis(tasks: Task[]): {
+	showEllipsis: boolean;
+	visibleTasks: Task[];
+} {
+	// Count how many consecutive completed tasks appear at the front.
+	let consecutiveCompleted = 0;
+	for (const task of tasks) {
+		if (task.state === 'completed') {
+			consecutiveCompleted++;
+		} else {
+			break;
+		}
+	}
+
+	const MAX_VISIBLE_COMPLETED = 3;
+	if (consecutiveCompleted <= MAX_VISIBLE_COMPLETED) {
+		return { showEllipsis: false, visibleTasks: tasks };
+	}
+
+	// Discard all but the last MAX_VISIBLE_COMPLETED completed tasks.
+	return {
+		showEllipsis: true,
+		visibleTasks: tasks.slice(consecutiveCompleted - MAX_VISIBLE_COMPLETED),
+	};
+}
+
+/**
+ * Compact, read-only panel listing the agent's current tasks with
+ * their status and dependency information.
+ *
+ * Each row shows ``#id  [icon]  subject  [← blocked by #x, #y]``.
+ * The panel header displays a progress summary like ``Tasks (3/5)``.
+ * When there are more than 3 leading completed tasks, the earlier ones
+ * are collapsed into a single ``…`` separator row.
+ *
+ * @param tasksContext - The full ``TaskContext`` from ``AgentState``.
+ *   ``null`` hides the panel entirely.
+ * @param className - The className
+ * @returns A panel element, or ``null`` when there are no tasks.
+ */
+export function TaskPanel({ tasksContext, className }: TaskPanelProps) {
+	const { t } = useTranslation();
+	const [expanded, setExpanded] = useState(false);
+
+	if (!tasksContext || tasksContext.tasks.length === 0) {
+		return (
+			<PanelEmpty
+				icon={ListX}
+				title={t('panel.plan.emptyTitle')}
+				description={t('panel.plan.emptyDescription')}
+			/>
+		);
+	}
+
+	const { tasks } = tasksContext;
+	const completed = tasks.filter((task) => task.state === 'completed').length;
+	const { showEllipsis, visibleTasks } = filterTasksWithEllipsis(tasks);
+
+	const displayedTasks = expanded ? tasks : visibleTasks;
+
+	return (
+		<div className={cn('flex flex-col flex-1 min-h-0 text-sm', className)}>
+			<div className="flex flex-row items-center gap-x-2 shrink-0 pb-2">
+				<Badge variant={'secondary'} className="tracking-wide">
+					{t('panel.plan.completed', { count: completed })}
+				</Badge>
+				<Badge variant={'secondary'} className="tracking-wide">
+					{t('panel.plan.total', { count: tasks.length })}
+				</Badge>
+			</div>
+
+			<ul className="flex flex-col flex-1 min-h-0 gap-y-0.5 text-xs overflow-y-auto">
+				{showEllipsis && !expanded && (
+					<Button
+						size={'xs'}
+						variant={'ghost'}
+						className="flex items-center justify-center w-full"
+						onClick={() => setExpanded(true)}
+					>
+						<Ellipsis className="size-3 text-muted-foreground" />
+					</Button>
+				)}
+				{displayedTasks.map((task) => (
+					<li
+						key={task.id}
+						className={cn(
+							'flex gap-2 rounded px-2 py-1 items-center',
+							task.state === 'completed' && 'opacity-60',
+						)}
+					>
+						<StateIcon state={task.state} />
+						<div className="flex flex-col min-w-0 gap-0.5">
+							<span className="flex items-center gap-1.5">
+								<span className="text-xs font-mono text-muted-foreground">
+									#{task.id}
+								</span>
+								<span
+									className={cn(
+										'truncate ',
+										task.state === 'completed' && 'line-through',
+									)}
+								>
+									{task.subject}
+								</span>
+							</span>
+							{task.blocked_by.length > 0 && (
+								<span className="text-xs text-muted-foreground">
+									← {t('task-panel.blockedBy')}{' '}
+									{task.blocked_by.map((id) => `#${id}`).join(', ')}
+								</span>
+							)}
+						</div>
+					</li>
+				))}
+			</ul>
+		</div>
+	);
+}
diff --git a/examples/web_ui/frontend/src/components/popover/KnowledgeBaseParametersPopover.tsx b/examples/web_ui/frontend/src/components/popover/KnowledgeBaseParametersPopover.tsx
new file mode 100644
index 0000000..caa3fa6
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/popover/KnowledgeBaseParametersPopover.tsx
@@ -0,0 +1,277 @@
+import { ChevronDown, SlidersHorizontal } from 'lucide-react';
+import { useEffect, useState } from 'react';
+
+import type { JSONSchema, JSONSchemaProperty, SessionKnowledgeConfig } from '@/api';
+import { Button } from '@/components/ui/button';
+import {
+	DropdownMenu,
+	DropdownMenuContent,
+	DropdownMenuRadioGroup,
+	DropdownMenuRadioItem,
+	DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+import {
+	Popover,
+	PopoverContent,
+	PopoverDescription,
+	PopoverHeader,
+	PopoverTitle,
+	PopoverTrigger,
+} from '@/components/ui/popover';
+import { Switch } from '@/components/ui/switch';
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip';
+import { useTranslation } from '@/i18n/useI18n';
+
+interface Props {
+	/**
+	 * The current session-knowledge config. The popover edits its
+	 * `parameters` dict; `knowledge_base_ids` is preserved verbatim.
+	 * `null` means no KBs are attached — the trigger is then disabled
+	 * because there is nothing for the parameters to act on.
+	 */
+	value: SessionKnowledgeConfig | null;
+	/** JSON Schema describing the middleware's tunable parameters. */
+	schema: JSONSchema | null;
+	/** Persist a new config back to the session. */
+	onChange: (next: SessionKnowledgeConfig | null) => void;
+	/** Force-disable the trigger regardless of `value` (e.g. no session). */
+	disabled?: boolean;
+}
+
+type ParamValue = string | number | boolean | null | undefined;
+
+/** Look through `anyOf` to find the property's effective scalar type and
+ *  any enum constraint. Pydantic renders `Literal[...]` directly and
+ *  `Literal[...] | None` inside the non-null `anyOf` branch. */
+function resolve(prop: JSONSchemaProperty): {
+	type: string;
+	enumValues: unknown[] | null;
+} {
+	if (prop.type && prop.type !== 'null') {
+		return { type: prop.type, enumValues: prop.enum ?? null };
+	}
+	for (const variant of prop.anyOf ?? []) {
+		const v = variant as JSONSchemaProperty;
+		if (v.type && v.type !== 'null') {
+			return { type: v.type, enumValues: v.enum ?? prop.enum ?? null };
+		}
+	}
+	return { type: 'string', enumValues: prop.enum ?? null };
+}
+
+/**
+ * Trigger + popover that edits the `KnowledgeBaseMiddleware` parameters
+ * for the active session.
+ *
+ * Schema-driven (entries come from
+ * `KnowledgeBaseMiddleware.Parameters.model_json_schema()`) but with a
+ * hand-rolled label/control grid so labels stay flush-left and inputs
+ * align in a single right-hand column — same pattern as
+ * {@link ModelParametersPopover}. Enums render as
+ * {@link LlmSelect}-style `DropdownMenu` triggers instead of the native
+ * `<Select>` used by the shared {@link SchemaForm}.
+ *
+ * The trigger is disabled until at least one knowledge base is selected
+ * — until then the parameters have nothing to apply to.
+ */
+export function KnowledgeBaseParametersPopover({
+	value,
+	schema,
+	onChange,
+	disabled = false,
+}: Props) {
+	const { t } = useTranslation();
+
+	// Local draft so number inputs can transiently hold empty strings
+	// without racing the persisted `value.parameters`. Kept in sync with
+	// the source of truth whenever it changes (session switch, etc.).
+	const [paramValues, setParamValues] = useState<Record<string, ParamValue>>(
+		(value?.parameters ?? {}) as Record<string, ParamValue>,
+	);
+	useEffect(() => {
+		setParamValues((value?.parameters ?? {}) as Record<string, ParamValue>);
+	}, [value]);
+
+	const handleParamChange = (key: string, val: ParamValue) => {
+		const next = { ...paramValues, [key]: val };
+		if (val === undefined) delete next[key];
+		setParamValues(next);
+		// Without any selected KB the middleware isn't installed, so a
+		// parameter edit has nowhere to land. The trigger is disabled in
+		// that state, but guard here as a belt-and-braces check.
+		if (!value || value.knowledge_base_ids.length === 0) return;
+		onChange({
+			knowledge_base_ids: value.knowledge_base_ids,
+			parameters: next as Record<string, unknown>,
+		});
+	};
+
+	const hasSelection = !!value && value.knowledge_base_ids.length > 0;
+	const triggerDisabled = disabled || !schema || !hasSelection;
+
+	const entries = Object.entries(schema?.properties ?? {});
+
+	return (
+		<Popover>
+			<PopoverTrigger asChild>
+				<Button
+					variant="ghost"
+					size="icon-sm"
+					disabled={triggerDisabled}
+					aria-label={t('panel.knowledge.parametersTitle')}
+					title={t('panel.knowledge.parametersTitle')}
+				>
+					<SlidersHorizontal />
+				</Button>
+			</PopoverTrigger>
+			<PopoverContent
+				align="end"
+				className="w-80 max-h-[28rem] overflow-y-auto"
+				// Stop the popover from forwarding pointer/key events back
+				// up to the parent panel header, which would otherwise
+				// dismiss focus mid-edit.
+				onPointerDown={(e) => e.stopPropagation()}
+				onKeyDown={(e) => e.stopPropagation()}
+			>
+				<PopoverHeader>
+					<PopoverTitle>{t('panel.knowledge.parametersTitle')}</PopoverTitle>
+					<PopoverDescription>
+						{t('panel.knowledge.parametersDescription')}
+					</PopoverDescription>
+				</PopoverHeader>
+				{schema && entries.length > 0 ? (
+					<div className="grid grid-cols-[auto_1fr] items-center gap-x-3 gap-y-3">
+						{entries.map(([key, prop]) => {
+							const { type, enumValues } = resolve(prop);
+							const id = `kb-mw-${key}`;
+							const label = prop.title ?? key.replace(/_/g, ' ');
+							const current = paramValues[key];
+
+							let control: React.ReactNode;
+							if (type === 'boolean') {
+								control = (
+									<Switch
+										id={id}
+										checked={current !== undefined ? !!current : !!prop.default}
+										onCheckedChange={(checked) =>
+											handleParamChange(key, !!checked)
+										}
+									/>
+								);
+							} else if (enumValues) {
+								const displayValue =
+									current !== undefined && current !== null
+										? String(current)
+										: prop.default != null
+											? String(prop.default)
+											: '';
+								control = (
+									<DropdownMenu>
+										<DropdownMenuTrigger asChild>
+											<Button
+												id={id}
+												variant="outline"
+												size="sm"
+												className="justify-between gap-1 w-full"
+											>
+												<span className="truncate">{displayValue}</span>
+												<ChevronDown className="size-3.5 opacity-50 shrink-0" />
+											</Button>
+										</DropdownMenuTrigger>
+										<DropdownMenuContent
+											align="start"
+											className="min-w-[var(--radix-dropdown-menu-trigger-width)] max-h-60 overflow-y-auto"
+										>
+											<DropdownMenuRadioGroup
+												value={displayValue}
+												onValueChange={(v) => handleParamChange(key, v)}
+											>
+												{enumValues.map((opt) => (
+													<DropdownMenuRadioItem
+														key={String(opt)}
+														value={String(opt)}
+													>
+														{String(opt)}
+													</DropdownMenuRadioItem>
+												))}
+											</DropdownMenuRadioGroup>
+										</DropdownMenuContent>
+									</DropdownMenu>
+								);
+							} else if (type === 'number' || type === 'integer') {
+								control = (
+									<Input
+										id={id}
+										type="number"
+										value={
+											current === undefined || current === null
+												? ''
+												: String(current)
+										}
+										min={prop.minimum}
+										max={prop.maximum}
+										step={type === 'integer' ? 1 : 'any'}
+										placeholder={
+											prop.default != null ? String(prop.default) : undefined
+										}
+										onChange={(e) => {
+											const raw = e.target.value;
+											if (raw === '') {
+												handleParamChange(key, undefined);
+												return;
+											}
+											const parsed =
+												type === 'integer'
+													? parseInt(raw, 10)
+													: parseFloat(raw);
+											handleParamChange(
+												key,
+												Number.isNaN(parsed) ? raw : parsed,
+											);
+										}}
+									/>
+								);
+							} else {
+								control = (
+									<Input
+										id={id}
+										type="text"
+										value={
+											current === undefined || current === null
+												? ''
+												: String(current)
+										}
+										placeholder={
+											prop.default != null ? String(prop.default) : undefined
+										}
+										onChange={(e) => handleParamChange(key, e.target.value)}
+									/>
+								);
+							}
+
+							return (
+								<Tooltip key={key}>
+									<TooltipTrigger asChild>
+										<div className="col-span-2 grid grid-cols-subgrid items-center">
+											<Label htmlFor={id} className="whitespace-nowrap">
+												{label}
+											</Label>
+											{control}
+										</div>
+									</TooltipTrigger>
+									{prop.description && (
+										<TooltipContent side="left">
+											{prop.description}
+										</TooltipContent>
+									)}
+								</Tooltip>
+							);
+						})}
+					</div>
+				) : null}
+			</PopoverContent>
+		</Popover>
+	);
+}
diff --git a/examples/web_ui/frontend/src/components/popover/ModelParametersPopover.tsx b/examples/web_ui/frontend/src/components/popover/ModelParametersPopover.tsx
new file mode 100644
index 0000000..847317f
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/popover/ModelParametersPopover.tsx
@@ -0,0 +1,616 @@
+import { ChevronDown, SlidersHorizontal } from 'lucide-react';
+import { useCallback, useEffect, useState } from 'react';
+
+import type { ChatModelConfig, ModelCard, TTSModelCard, TTSModelConfig } from '@/api';
+import { Badge } from '@/components/ui/badge';
+import { Button } from '@/components/ui/button';
+import {
+	DropdownMenu,
+	DropdownMenuCheckboxItem,
+	DropdownMenuContent,
+	DropdownMenuLabel,
+	DropdownMenuRadioGroup,
+	DropdownMenuRadioItem,
+	DropdownMenuSeparator,
+	DropdownMenuSub,
+	DropdownMenuSubContent,
+	DropdownMenuSubTrigger,
+	DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu.tsx';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+import { Switch } from '@/components/ui/switch';
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip';
+import { useAvailableModels } from '@/hooks/useAvailableModels';
+import { useAvailableTTSModels } from '@/hooks/useAvailableTTSModels';
+import { useTranslation } from '@/i18n/useI18n';
+
+interface ParameterProperty {
+	type?: string;
+	title?: string;
+	description?: string;
+	default?: unknown;
+	minimum?: number;
+	maximum?: number;
+	exclusiveMinimum?: number;
+	exclusiveMaximum?: number;
+	enum?: unknown[];
+	anyOf?: ParameterProperty[];
+}
+
+interface ParameterSchema {
+	title?: string;
+	description?: string;
+	type?: string;
+	properties?: Record<string, ParameterProperty>;
+	required?: string[];
+}
+
+interface ResolvedType {
+	type: string;
+	enumValues: unknown[] | null;
+}
+
+/** Resolve a property's effective scalar type and enum values, looking
+ *  through ``anyOf`` and ignoring ``null`` variants. */
+function resolveType(prop: ParameterProperty): ResolvedType {
+	if (prop.type) {
+		return { type: prop.type, enumValues: prop.enum ?? null };
+	}
+	for (const variant of prop.anyOf ?? []) {
+		if (variant.type && variant.type !== 'null') {
+			return {
+				type: variant.type,
+				enumValues: variant.enum ?? prop.enum ?? null,
+			};
+		}
+	}
+	return { type: 'string', enumValues: null };
+}
+
+// ---------------------------------------------------------------------------
+// Field components
+// ---------------------------------------------------------------------------
+
+interface FieldProps {
+	id: string;
+	label: string;
+	required: boolean;
+	prop: ParameterProperty;
+	value: unknown;
+	onChange: (next: unknown) => void;
+}
+
+function BooleanField({ id, label, prop, value, onChange }: FieldProps) {
+	return (
+		<>
+			<Label htmlFor={id} className="whitespace-nowrap">
+				{label}
+			</Label>
+			<Switch
+				id={id}
+				checked={value !== undefined ? !!value : !!prop.default}
+				onCheckedChange={(checked) => onChange(!!checked)}
+			/>
+		</>
+	);
+}
+
+function EnumField({ id, label, required, prop, value, onChange }: FieldProps) {
+	const enumValues = resolveType(prop).enumValues ?? [];
+	// TODO: experiment with using prop.description as placeholder text
+	const displayValue = value !== undefined && value !== null ? String(value) : '';
+
+	return (
+		<>
+			<Label htmlFor={id} className="whitespace-nowrap">
+				{label}
+				{required && <span className="text-destructive ml-0.5">*</span>}
+			</Label>
+			<DropdownMenu>
+				<DropdownMenuTrigger asChild>
+					<Button id={id} variant="outline" className="w-full justify-between gap-1">
+						<span className="truncate">{displayValue}</span>
+						<ChevronDown className="size-3.5 opacity-50 shrink-0" />
+					</Button>
+				</DropdownMenuTrigger>
+				<DropdownMenuContent
+					align="start"
+					className="max-h-60 overflow-y-auto"
+					onPointerDown={(e) => e.stopPropagation()}
+				>
+					<DropdownMenuRadioGroup value={displayValue} onValueChange={(v) => onChange(v)}>
+						{enumValues.map((opt) => (
+							<DropdownMenuRadioItem key={String(opt)} value={String(opt)}>
+								{String(opt)}
+							</DropdownMenuRadioItem>
+						))}
+					</DropdownMenuRadioGroup>
+				</DropdownMenuContent>
+			</DropdownMenu>
+		</>
+	);
+}
+
+function NumberField({ id, label, required, prop, value, onChange }: FieldProps) {
+	const { type: effectiveType } = resolveType(prop);
+
+	return (
+		<>
+			<Label htmlFor={id} className="whitespace-nowrap">
+				{label}
+				{required && <span className="text-destructive ml-0.5">*</span>}
+			</Label>
+			<Input
+				id={id}
+				type="number"
+				value={value !== undefined ? String(value) : ''}
+				placeholder={prop.default != null ? String(prop.default) : undefined}
+				min={prop.minimum}
+				max={prop.maximum}
+				step={effectiveType === 'number' ? 'any' : undefined}
+				onChange={(e) => {
+					const raw = e.target.value;
+					onChange(raw === '' ? undefined : Number(raw));
+				}}
+				onBlur={(e) => {
+					if (e.target.value === '') return;
+					let num = Number(e.target.value);
+					if (prop.minimum !== undefined && num < prop.minimum) num = prop.minimum;
+					if (prop.maximum !== undefined && num > prop.maximum) num = prop.maximum;
+					if (prop.exclusiveMinimum !== undefined && num <= prop.exclusiveMinimum)
+						num =
+							prop.exclusiveMinimum +
+							(effectiveType === 'integer' ? 1 : Number.EPSILON);
+					if (prop.exclusiveMaximum !== undefined && num >= prop.exclusiveMaximum)
+						num =
+							prop.exclusiveMaximum -
+							(effectiveType === 'integer' ? 1 : Number.EPSILON);
+					if (num !== Number(e.target.value)) onChange(num);
+				}}
+			/>
+		</>
+	);
+}
+
+function StringField({ id, label, required, prop, value, onChange }: FieldProps) {
+	return (
+		<>
+			<Label htmlFor={id} className="whitespace-nowrap">
+				{label}
+				{required && <span className="text-destructive ml-0.5">*</span>}
+			</Label>
+			<Input
+				id={id}
+				type="text"
+				value={value !== undefined ? String(value) : ''}
+				placeholder={prop.default != null ? String(prop.default) : undefined}
+				onChange={(e) => onChange(e.target.value)}
+			/>
+		</>
+	);
+}
+
+// ---------------------------------------------------------------------------
+// Main component
+// ---------------------------------------------------------------------------
+
+interface Props {
+	/** Currently selected primary model — used to read the parameter schema. */
+	selectedModel: ChatModelConfig | null;
+	/** Model card describing the primary model's parameter schema. */
+	modelCard: ModelCard | null;
+	/** Called when the user edits the primary model's parameters. */
+	onChange: (parameters: Record<string, unknown>) => void;
+	/** Currently selected fallback model. `null` means no fallback configured. */
+	selectedFallbackModel: ChatModelConfig | null;
+	/** Called when the user picks a fallback model or clears the selection. */
+	onFallbackChange: (config: ChatModelConfig | null) => void;
+	/** Currently selected TTS model. `null` means TTS is disabled. */
+	selectedTTSModel: TTSModelConfig | null;
+	/** Called when the user picks a TTS model+voice or disables TTS. */
+	onTTSChange: (config: TTSModelConfig | null) => void;
+}
+
+/**
+ * A unified settings dropdown for the active chat model. Exposes two
+ * sub-menus:
+ *   - "Fallback model": pick a backup model invoked when the primary fails.
+ *   - "Parameters": edit the primary model's inference parameters inline.
+ *
+ * The trigger is disabled until a primary model is selected, since both
+ * sub-menus are meaningless without one.
+ */
+export function ModelParametersPopover({
+	selectedModel,
+	modelCard,
+	onChange,
+	selectedFallbackModel,
+	onFallbackChange,
+	selectedTTSModel,
+	onTTSChange,
+}: Props) {
+	const [values, setValues] = useState<Record<string, unknown>>({});
+	const { t } = useTranslation();
+	const { groups } = useAvailableModels();
+	const { groups: ttsGroups } = useAvailableTTSModels();
+
+	const schema = modelCard?.parameter_schema as ParameterSchema | undefined;
+	const properties = schema?.properties ?? {};
+	const required = schema?.required ?? [];
+	const entries = Object.entries(properties);
+
+	useEffect(() => {
+		setValues(selectedModel?.parameters ?? {});
+	}, [selectedModel?.model]);
+
+	const handleChange = useCallback(
+		(key: string, value: unknown) => {
+			const next = { ...values, [key]: value };
+			if (value === '' || value === undefined) {
+				delete next[key];
+			}
+			setValues(next);
+			onChange(next);
+		},
+		[values, onChange],
+	);
+
+	const handleSelectFallback = (type: string, credentialId: string, model: string) => {
+		onFallbackChange({
+			type,
+			credential_id: credentialId,
+			model,
+			parameters: {},
+		});
+	};
+
+	const disabled = !selectedModel;
+	const hasFallbackOptions = Object.keys(groups).length > 0;
+
+	return (
+		<DropdownMenu>
+			<DropdownMenuTrigger asChild>
+				<Button variant="ghost" size="icon-sm" disabled={disabled}>
+					<SlidersHorizontal />
+				</Button>
+			</DropdownMenuTrigger>
+			<DropdownMenuContent align="start" className="min-w-40">
+				{/* ----- Fallback model selection ----- */}
+				<DropdownMenuSub>
+					<DropdownMenuSubTrigger>
+						<span className="truncate">
+							{selectedFallbackModel
+								? t('model-parameters.fallbackLabelWithModel', {
+										model: selectedFallbackModel.model,
+									})
+								: t('model-parameters.fallbackLabel')}
+						</span>
+					</DropdownMenuSubTrigger>
+					<DropdownMenuSubContent className="max-h-72 overflow-y-auto">
+						{!hasFallbackOptions ? (
+							<div className="px-2 py-3 text-center text-sm text-muted-foreground">
+								<p>{t('llm-select.empty.title')}</p>
+							</div>
+						) : (
+							Object.entries(groups).map(([type, items], idx) => (
+								<div key={type}>
+									{idx > 0 && <DropdownMenuSeparator />}
+									<DropdownMenuLabel>
+										{type.replace(/_credential$/, '')}
+									</DropdownMenuLabel>
+									{items.flatMap(({ credential, models }) =>
+										models.map((m) => {
+											const isSelected =
+												selectedFallbackModel?.credential_id ===
+													credential.id &&
+												selectedFallbackModel?.model === m.name;
+											return (
+												<DropdownMenuCheckboxItem
+													key={`${credential.id}-${m.name}`}
+													checked={isSelected}
+													onCheckedChange={(checked) => {
+														if (checked) {
+															handleSelectFallback(
+																type,
+																credential.id,
+																m.name,
+															);
+														} else {
+															onFallbackChange(null);
+														}
+													}}
+												>
+													{m.label}
+												</DropdownMenuCheckboxItem>
+											);
+										}),
+									)}
+								</div>
+							))
+						)}
+						<DropdownMenuSeparator />
+						<DropdownMenuCheckboxItem
+							checked={!selectedFallbackModel}
+							onCheckedChange={(checked) => {
+								if (checked) onFallbackChange(null);
+							}}
+						>
+							{t('llm-select.noFallback')}
+						</DropdownMenuCheckboxItem>
+					</DropdownMenuSubContent>
+				</DropdownMenuSub>
+
+				{/* ----- Primary model parameters ----- */}
+				<DropdownMenuSub>
+					<DropdownMenuSubTrigger>
+						{t('model-parameters.parametersLabel')}
+					</DropdownMenuSubTrigger>
+					<DropdownMenuSubContent className="w-80 max-h-96 overflow-y-auto p-3">
+						<div className="mb-3">
+							<p className="text-sm font-medium">{t('model-parameters.title')}</p>
+							<p className="text-muted-foreground text-xs">
+								{t('model-parameters.description')}
+							</p>
+						</div>
+						{entries.length === 0 ? (
+							<p className="text-muted-foreground text-xs">
+								{t('model-parameters.empty')}
+							</p>
+						) : (
+							<div
+								className="grid grid-cols-[auto_1fr] items-center gap-x-3 gap-y-3"
+								onPointerDown={(e) => e.stopPropagation()}
+								onKeyDown={(e) => e.stopPropagation()}
+							>
+								{entries.map(([key, prop]) => {
+									const { type: effectiveType, enumValues } = resolveType(prop);
+									const label = prop.title ?? key;
+									const isRequired = required.includes(key);
+									const fieldProps: FieldProps = {
+										id: `param-${key}`,
+										label,
+										required: isRequired,
+										prop,
+										value: values[key],
+										onChange: (v) => handleChange(key, v),
+									};
+
+									let field: React.ReactNode;
+									if (effectiveType === 'boolean') {
+										field = <BooleanField {...fieldProps} />;
+									} else if (enumValues) {
+										field = <EnumField {...fieldProps} />;
+									} else if (
+										effectiveType === 'number' ||
+										effectiveType === 'integer'
+									) {
+										field = <NumberField {...fieldProps} />;
+									} else {
+										field = <StringField {...fieldProps} />;
+									}
+
+									return (
+										<Tooltip key={key}>
+											<TooltipTrigger asChild>
+												<div className="col-span-2 grid grid-cols-subgrid items-center">
+													{field}
+												</div>
+											</TooltipTrigger>
+											{prop.description && (
+												<TooltipContent side="left">
+													{prop.description}
+												</TooltipContent>
+											)}
+										</Tooltip>
+									);
+								})}
+							</div>
+						)}
+					</DropdownMenuSubContent>
+				</DropdownMenuSub>
+
+				{/* ----- TTS ----- */}
+				<DropdownMenuSub>
+					<DropdownMenuSubTrigger>
+						<span className="truncate">{t('model-parameters.ttsLabel')}</span>
+					</DropdownMenuSubTrigger>
+					<DropdownMenuSubContent className="max-h-96 overflow-y-auto">
+						{Object.keys(ttsGroups).length === 0 ? (
+							<div className="px-2 py-3 text-center text-sm text-muted-foreground">
+								<p>{t('model-parameters.ttsEmpty')}</p>
+							</div>
+						) : (
+							Object.entries(ttsGroups).map(([type, items], idx) => (
+								<div key={type}>
+									{idx > 0 && <DropdownMenuSeparator />}
+									<DropdownMenuLabel>
+										{type.replace(/_credential$/, '')}
+									</DropdownMenuLabel>
+									{items.flatMap(({ credential, models }) =>
+										models.map((m) => {
+											const isSelected =
+												selectedTTSModel?.credential_id === credential.id &&
+												selectedTTSModel?.model === m.name;
+											return (
+												<DropdownMenuCheckboxItem
+													key={`${credential.id}-${m.name}`}
+													checked={isSelected}
+													onSelect={(e) => e.preventDefault()}
+													onCheckedChange={(checked) => {
+														if (!checked) return;
+														const schema = m.parameter_schema as
+															| ParameterSchema
+															| undefined;
+														const defaults: Record<string, unknown> =
+															{};
+														if (schema?.properties) {
+															for (const [k, p] of Object.entries(
+																schema.properties,
+															)) {
+																if (p.default !== undefined) {
+																	defaults[k] = p.default;
+																}
+															}
+														}
+														onTTSChange({
+															type,
+															credential_id: credential.id,
+															model: m.name,
+															parameters: defaults,
+														});
+													}}
+												>
+													{m.label}
+													{m.realtime && (
+														<Badge
+															variant="outline"
+															className="ml-1.5 text-[10px] px-1 py-0"
+														>
+															Realtime
+														</Badge>
+													)}
+												</DropdownMenuCheckboxItem>
+											);
+										}),
+									)}
+								</div>
+							))
+						)}
+
+						{/* TTS parameters sub-panel (hover to expand right) */}
+						{selectedTTSModel && (
+							<>
+								<DropdownMenuSeparator />
+								<DropdownMenuSub>
+									<DropdownMenuSubTrigger>
+										{t('model-parameters.ttsParameters')}
+									</DropdownMenuSubTrigger>
+									<DropdownMenuSubContent className="w-72 max-h-96 overflow-y-auto p-3">
+										<div className="mb-3">
+											<p className="text-sm font-medium">
+												{t('model-parameters.title')}
+											</p>
+											<p className="text-muted-foreground text-xs">
+												{t('model-parameters.ttsParametersDescription')}
+											</p>
+										</div>
+										{(() => {
+											if (!selectedTTSModel) return null;
+											const selType = selectedTTSModel.type;
+											const selItems = ttsGroups[selType];
+											if (!selItems) return null;
+											let selModel: TTSModelCard | undefined;
+											for (const { credential, models } of selItems) {
+												if (
+													credential.id !== selectedTTSModel.credential_id
+												)
+													continue;
+												selModel = models.find(
+													(m) => m.name === selectedTTSModel.model,
+												);
+												if (selModel) break;
+											}
+											if (!selModel) return null;
+											const mSchema = selModel.parameter_schema as
+												| ParameterSchema
+												| undefined;
+											const mProps = mSchema?.properties ?? {};
+											const mRequired = mSchema?.required ?? [];
+											const mEntries = Object.entries(mProps);
+											if (mEntries.length === 0) {
+												return (
+													<p className="text-muted-foreground text-xs">
+														{t('model-parameters.empty')}
+													</p>
+												);
+											}
+											const curParams = selectedTTSModel.parameters ?? {};
+
+											return (
+												<div
+													className="grid grid-cols-[auto_1fr] items-center gap-x-3 gap-y-3"
+													onPointerDown={(e) => e.stopPropagation()}
+													onKeyDown={(e) => e.stopPropagation()}
+												>
+													{mEntries.map(([key, prop]) => {
+														const { type: effectiveType, enumValues } =
+															resolveType(prop);
+														const label = prop.title ?? key;
+														const isReq = mRequired.includes(key);
+														const fieldProps: FieldProps = {
+															id: `tts-${selModel!.name}-${key}`,
+															label,
+															required: isReq,
+															prop,
+															value: curParams[key],
+															onChange: (v) => {
+																const next = {
+																	...curParams,
+																	[key]: v,
+																};
+																if (v === '' || v === undefined) {
+																	delete next[key];
+																}
+																onTTSChange({
+																	...selectedTTSModel,
+																	parameters: next,
+																});
+															},
+														};
+
+														let field: React.ReactNode;
+														if (effectiveType === 'boolean') {
+															field = (
+																<BooleanField {...fieldProps} />
+															);
+														} else if (enumValues) {
+															field = <EnumField {...fieldProps} />;
+														} else if (
+															effectiveType === 'number' ||
+															effectiveType === 'integer'
+														) {
+															field = <NumberField {...fieldProps} />;
+														} else {
+															field = <StringField {...fieldProps} />;
+														}
+
+														return (
+															<Tooltip key={key}>
+																<TooltipTrigger asChild>
+																	<div className="col-span-2 grid grid-cols-subgrid items-center">
+																		{field}
+																	</div>
+																</TooltipTrigger>
+																{prop.description && (
+																	<TooltipContent side="left">
+																		{prop.description}
+																	</TooltipContent>
+																)}
+															</Tooltip>
+														);
+													})}
+												</div>
+											);
+										})()}
+									</DropdownMenuSubContent>
+								</DropdownMenuSub>
+							</>
+						)}
+
+						<DropdownMenuSeparator />
+						<DropdownMenuCheckboxItem
+							checked={!selectedTTSModel}
+							onSelect={(e) => e.preventDefault()}
+							onCheckedChange={(checked) => {
+								if (checked) onTTSChange(null);
+							}}
+						>
+							{t('model-parameters.noTts')}
+						</DropdownMenuCheckboxItem>
+					</DropdownMenuSubContent>
+				</DropdownMenuSub>
+			</DropdownMenuContent>
+		</DropdownMenu>
+	);
+}
diff --git a/examples/web_ui/frontend/src/components/select/AgentSelect.tsx b/examples/web_ui/frontend/src/components/select/AgentSelect.tsx
new file mode 100644
index 0000000..2b7321f
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/select/AgentSelect.tsx
@@ -0,0 +1,109 @@
+import { Check, ChevronDown } from 'lucide-react';
+
+import type { AgentView } from '@/api';
+import { Badge } from '@/components/ui/badge';
+import { Button } from '@/components/ui/button';
+import {
+	DropdownMenu,
+	DropdownMenuContent,
+	DropdownMenuGroup,
+	DropdownMenuItem,
+	DropdownMenuLabel,
+	DropdownMenuSeparator,
+	DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+import { useTranslation } from '@/i18n/useI18n.ts';
+
+interface Props {
+	agents: AgentView[];
+	/** Currently selected agent id, or `null` when none is selected. */
+	value?: string | null;
+	onChange?: (agentId: string) => void;
+	/** Override the trigger label shown when no agent is selected. */
+	placeholder?: string;
+}
+
+/**
+ * Agent picker used in the chat sidebar. Rendered on top of the
+ * shadcn dropdown-menu primitives (same base as `LlmSelect`) so
+ * grouping and per-row content (icons, badges) is fully composable.
+ *
+ * Grouping rule: when every visible agent is editable (i.e. no
+ * cross-owner shares in play), the list is rendered flat. As soon
+ * as at least one entry is `editable === false`, the list splits
+ * into "Yours" and "Shared with you" groups so the read-only
+ * origin of the shared entries is unambiguous at a glance.
+ */
+export function AgentSelect({ agents, value, onChange, placeholder }: Props) {
+	const { t } = useTranslation();
+	const selected = agents.find((a) => a.id === value) ?? null;
+	const displayLabel = selected
+		? selected.data.name
+		: (placeholder ?? t('chat.agent.selectPlaceholder'));
+
+	const hasShared = agents.some((a) => !a.editable);
+	const yours = agents.filter((a) => a.editable);
+	const shared = agents.filter((a) => !a.editable);
+
+	const renderItem = (agent: AgentView) => {
+		const isSelected = agent.id === value;
+		return (
+			<DropdownMenuItem key={agent.id} onSelect={() => onChange?.(agent.id)}>
+				<Check
+					className={`size-3.5 shrink-0 ${isSelected ? 'opacity-100' : 'opacity-0'}`}
+				/>
+				<span className="min-w-0 flex-1 truncate">{agent.data.name}</span>
+				{!agent.editable && (
+					<Badge
+						variant="secondary"
+						className="text-[10px] px-1 py-0"
+						title={t('common.readOnlyTooltip')}
+					>
+						{t('common.readOnly')}
+					</Badge>
+				)}
+			</DropdownMenuItem>
+		);
+	};
+
+	return (
+		<DropdownMenu>
+			<DropdownMenuTrigger asChild>
+				<Button
+					variant="outline"
+					size="sm"
+					className="flex-1 min-w-0 justify-between gap-1"
+				>
+					<span className="truncate">{displayLabel}</span>
+					<ChevronDown className="size-3.5 opacity-50" />
+				</Button>
+			</DropdownMenuTrigger>
+			<DropdownMenuContent align="start" className="min-w-56 max-h-72 overflow-y-auto">
+				{agents.length === 0 ? (
+					<div className="px-2 py-3 text-center text-sm text-muted-foreground">
+						<p className="font-medium">{t('chat.agent.emptyTitle')}</p>
+						<p className="text-xs mt-1">{t('chat.agent.emptyDescription')}</p>
+					</div>
+				) : hasShared ? (
+					<>
+						{yours.length > 0 && (
+							<DropdownMenuGroup>
+								<DropdownMenuLabel>{t('chat.agent.groupYours')}</DropdownMenuLabel>
+								{yours.map(renderItem)}
+							</DropdownMenuGroup>
+						)}
+						{yours.length > 0 && shared.length > 0 && <DropdownMenuSeparator />}
+						{shared.length > 0 && (
+							<DropdownMenuGroup>
+								<DropdownMenuLabel>{t('chat.agent.groupShared')}</DropdownMenuLabel>
+								{shared.map(renderItem)}
+							</DropdownMenuGroup>
+						)}
+					</>
+				) : (
+					agents.map(renderItem)
+				)}
+			</DropdownMenuContent>
+		</DropdownMenu>
+	);
+}
diff --git a/examples/web_ui/frontend/src/components/select/DimensionSelect.tsx b/examples/web_ui/frontend/src/components/select/DimensionSelect.tsx
new file mode 100644
index 0000000..787ce3a
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/select/DimensionSelect.tsx
@@ -0,0 +1,74 @@
+import { ChevronDown } from 'lucide-react';
+
+import { Badge } from '@/components/ui/badge';
+import { Button } from '@/components/ui/button';
+import {
+	DropdownMenu,
+	DropdownMenuContent,
+	DropdownMenuItem,
+	DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+import { useTranslation } from '@/i18n/useI18n.ts';
+
+interface Props {
+	/** Currently selected dimension. */
+	value?: number | null;
+	/** Allowed dimensions. ``null`` means no model picked yet. */
+	options: number[] | null;
+	onChange?: (dimension: number) => void;
+	disabled?: boolean;
+}
+
+/**
+ * Dimension picker for embedding models. Renders:
+ *
+ * - a placeholder when no model is selected;
+ * - a read-only badge when only one dimension is allowed
+ *   (fixed-dim model, or matryoshka narrowed by server policy);
+ * - a dropdown when multiple dimensions are allowed (matryoshka
+ *   under an ``ANY`` policy).
+ */
+export function DimensionSelect({ value, options, onChange, disabled }: Props) {
+	const { t } = useTranslation();
+
+	if (options === null || options.length === 0) {
+		return (
+			<span className="text-sm text-muted-foreground">
+				{t('dimension-select.pickModelFirst')}
+			</span>
+		);
+	}
+
+	if (options.length === 1) {
+		return (
+			<Badge variant="secondary" className="font-mono">
+				{options[0]}d
+			</Badge>
+		);
+	}
+
+	const display = value != null ? `${value}d` : t('dimension-select.placeholder');
+
+	return (
+		<DropdownMenu>
+			<DropdownMenuTrigger asChild>
+				<Button
+					variant="outline"
+					size="sm"
+					className="justify-between gap-1"
+					disabled={disabled}
+				>
+					<span className="truncate font-mono">{display}</span>
+					<ChevronDown className="size-3.5 opacity-50" />
+				</Button>
+			</DropdownMenuTrigger>
+			<DropdownMenuContent align="start" className="min-w-32">
+				{options.map((dim) => (
+					<DropdownMenuItem key={dim} onSelect={() => onChange?.(dim)}>
+						<span className="font-mono">{dim}d</span>
+					</DropdownMenuItem>
+				))}
+			</DropdownMenuContent>
+		</DropdownMenu>
+	);
+}
diff --git a/examples/web_ui/frontend/src/components/select/EmbeddingSelect.tsx b/examples/web_ui/frontend/src/components/select/EmbeddingSelect.tsx
new file mode 100644
index 0000000..cf65282
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/select/EmbeddingSelect.tsx
@@ -0,0 +1,146 @@
+import { ChevronDown, PlusCircle } from 'lucide-react';
+
+import type { EmbeddingModelCard, KbEmbeddingProvider } from '@/api';
+import { Button } from '@/components/ui/button';
+import {
+	DropdownMenu,
+	DropdownMenuContent,
+	DropdownMenuGroup,
+	DropdownMenuItem,
+	DropdownMenuLabel,
+	DropdownMenuSeparator,
+	DropdownMenuSub,
+	DropdownMenuSubContent,
+	DropdownMenuSubTrigger,
+	DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+import { useTranslation } from '@/i18n/useI18n.ts';
+
+interface SelectedEmbedding {
+	type: string;
+	credentialId: string;
+	model: string;
+	card: EmbeddingModelCard;
+}
+
+interface Props {
+	value?: { type: string; credential_id: string; model: string } | null;
+	providers: KbEmbeddingProvider[];
+	loading?: boolean;
+	onChange?: (selected: SelectedEmbedding) => void;
+	onAddCredential?: () => void;
+	/** Override the trigger label shown when no model is selected. */
+	placeholder?: string;
+}
+
+/**
+ * Embedding model picker. Consumes a pre-grouped, server-filtered
+ * list of providers (one entry per credential) and emits the chosen
+ * model's full :class:`EmbeddingModelCard` so the caller can derive
+ * the dimension separately.
+ */
+export function EmbeddingSelect({
+	value,
+	providers,
+	loading,
+	onChange,
+	onAddCredential,
+	placeholder,
+}: Props) {
+	const { t } = useTranslation();
+
+	// Group providers by credential type for the existing two-level UI
+	// (provider type → credential → models).
+	const groups: Record<string, KbEmbeddingProvider[]> = {};
+	for (const provider of providers) {
+		const type = (provider.credential.data.type as string) ?? 'unknown';
+		if (!groups[type]) groups[type] = [];
+		groups[type].push(provider);
+	}
+	const hasOptions = Object.keys(groups).length > 0;
+
+	const handleSelect = (type: string, credentialId: string, card: EmbeddingModelCard) => {
+		onChange?.({ type, credentialId, model: card.name, card });
+	};
+
+	const displayLabel = value?.model
+		? value.model
+		: loading
+			? t('embedding-select.loading')
+			: (placeholder ?? t('embedding-select.placeholder'));
+
+	return (
+		<DropdownMenu>
+			<DropdownMenuTrigger asChild>
+				<Button variant="outline" size="sm" className="justify-between gap-1">
+					<span className="truncate">{displayLabel}</span>
+					<ChevronDown className="size-3.5 opacity-50" />
+				</Button>
+			</DropdownMenuTrigger>
+			<DropdownMenuContent align="start" className="min-w-48 max-h-72 overflow-y-auto">
+				{!loading && !hasOptions ? (
+					<div className="px-2 py-3 text-center text-sm text-muted-foreground">
+						<p className="font-medium">{t('embedding-select.empty.title')}</p>
+						<p className="text-xs mt-1">{t('embedding-select.empty.description')}</p>
+					</div>
+				) : (
+					Object.entries(groups).map(([type, items], idx) => {
+						const isSingle = items.length === 1;
+						return (
+							<DropdownMenuGroup key={type}>
+								{idx > 0 && <DropdownMenuSeparator />}
+								<DropdownMenuLabel>
+									{type.replace(/_credential$/, '')}
+								</DropdownMenuLabel>
+								{isSingle
+									? items[0].models.map((m) => (
+											<DropdownMenuItem
+												key={m.name}
+												onSelect={() =>
+													handleSelect(type, items[0].credential.id, m)
+												}
+											>
+												{m.label}
+											</DropdownMenuItem>
+										))
+									: items.map(({ credential, models }) => {
+											const credName =
+												(credential.data.name as string) ||
+												credential.id.slice(0, 8);
+											return (
+												<DropdownMenuSub key={credential.id}>
+													<DropdownMenuSubTrigger>
+														{credName}
+													</DropdownMenuSubTrigger>
+													<DropdownMenuSubContent className="max-h-60 overflow-y-auto">
+														{models.map((m) => (
+															<DropdownMenuItem
+																key={m.name}
+																onSelect={() =>
+																	handleSelect(
+																		type,
+																		credential.id,
+																		m,
+																	)
+																}
+															>
+																{m.label}
+															</DropdownMenuItem>
+														))}
+													</DropdownMenuSubContent>
+												</DropdownMenuSub>
+											);
+										})}
+							</DropdownMenuGroup>
+						);
+					})
+				)}
+				<DropdownMenuSeparator />
+				<DropdownMenuItem onSelect={onAddCredential}>
+					<PlusCircle className="size-4" />
+					<span>{t('embedding-select.addCredential')}</span>
+				</DropdownMenuItem>
+			</DropdownMenuContent>
+		</DropdownMenu>
+	);
+}
diff --git a/examples/web_ui/frontend/src/components/select/LlmSelect.tsx b/examples/web_ui/frontend/src/components/select/LlmSelect.tsx
new file mode 100644
index 0000000..05a2212
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/select/LlmSelect.tsx
@@ -0,0 +1,152 @@
+import { ChevronDown, PlusCircle, Ban } from 'lucide-react';
+import { useEffect } from 'react';
+
+import type { ChatModelConfig } from '@/api';
+import { Button } from '@/components/ui/button';
+import {
+	DropdownMenu,
+	DropdownMenuContent,
+	DropdownMenuGroup,
+	DropdownMenuItem,
+	DropdownMenuLabel,
+	DropdownMenuSeparator,
+	DropdownMenuSub,
+	DropdownMenuSubContent,
+	DropdownMenuSubTrigger,
+	DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+import { useAvailableModels } from '@/hooks/useAvailableModels';
+import { useTranslation } from '@/i18n/useI18n.ts';
+
+interface Props {
+	value?: ChatModelConfig | null;
+	/**
+	 * Called when the user selects a model, or — when `allowClear` is true —
+	 * clears the selection (in which case `null` is emitted).
+	 */
+	onChange?: (value: ChatModelConfig | null) => void;
+	onAddCredential?: () => void;
+	refetchTrigger?: number;
+	/** Override the trigger label shown when no model is selected. */
+	placeholder?: string;
+	/**
+	 * When true, append a "clear selection" item to the dropdown that emits
+	 * `null` via `onChange`. Used by the fallback selector.
+	 */
+	allowClear?: boolean;
+	/** Override the label of the "clear selection" item. */
+	clearLabel?: string;
+}
+
+export function LlmSelect({
+	value,
+	onChange,
+	onAddCredential,
+	refetchTrigger,
+	placeholder,
+	allowClear = false,
+	clearLabel,
+}: Props) {
+	const { groups, loading, refetch } = useAvailableModels();
+	const { t } = useTranslation();
+	const hasOptions = Object.keys(groups).length > 0;
+
+	useEffect(() => {
+		if (refetchTrigger !== undefined && refetchTrigger > 0) refetch();
+	}, [refetchTrigger, refetch]);
+
+	const handleSelect = (type: string, credentialId: string, model: string) => {
+		onChange?.({ type, credential_id: credentialId, model, parameters: {} });
+	};
+
+	const displayLabel = value?.model
+		? value.model
+		: loading
+			? t('llm-select.loading')
+			: (placeholder ?? t('llm-select.placeholder'));
+
+	return (
+		<DropdownMenu>
+			<DropdownMenuTrigger asChild>
+				<Button variant="outline" size="sm" className="justify-between gap-1">
+					<span className="truncate">{displayLabel}</span>
+					<ChevronDown className="size-3.5 opacity-50" />
+				</Button>
+			</DropdownMenuTrigger>
+			<DropdownMenuContent align="start" className="min-w-48 max-h-72 overflow-y-auto">
+				{!loading && !hasOptions ? (
+					<div className="px-2 py-3 text-center text-sm text-muted-foreground">
+						<p className="font-medium">{t('llm-select.empty.title')}</p>
+						<p className="text-xs mt-1">{t('llm-select.empty.description')}</p>
+					</div>
+				) : (
+					Object.entries(groups).map(([type, items], idx) => {
+						const isSingle = items.length === 1;
+						return (
+							<DropdownMenuGroup key={type}>
+								{idx > 0 && <DropdownMenuSeparator />}
+								<DropdownMenuLabel>
+									{type.replace(/_credential$/, '')}
+								</DropdownMenuLabel>
+								{isSingle
+									? items[0].models.map((m) => (
+											<DropdownMenuItem
+												key={m.name}
+												onSelect={() =>
+													handleSelect(
+														type,
+														items[0].credential.id,
+														m.name,
+													)
+												}
+											>
+												{m.label}
+											</DropdownMenuItem>
+										))
+									: items.map(({ credential, models }) => {
+											const credName =
+												(credential.data.name as string) ||
+												credential.id.slice(0, 8);
+											return (
+												<DropdownMenuSub key={credential.id}>
+													<DropdownMenuSubTrigger>
+														{credName}
+													</DropdownMenuSubTrigger>
+													<DropdownMenuSubContent className="max-h-60 overflow-y-auto">
+														{models.map((m) => (
+															<DropdownMenuItem
+																key={m.name}
+																onSelect={() =>
+																	handleSelect(
+																		type,
+																		credential.id,
+																		m.name,
+																	)
+																}
+															>
+																{m.label}
+															</DropdownMenuItem>
+														))}
+													</DropdownMenuSubContent>
+												</DropdownMenuSub>
+											);
+										})}
+							</DropdownMenuGroup>
+						);
+					})
+				)}
+				<DropdownMenuSeparator />
+				{allowClear && (
+					<DropdownMenuItem onSelect={() => onChange?.(null)} disabled={!value}>
+						<Ban className="size-4" />
+						<span>{clearLabel ?? t('llm-select.clear')}</span>
+					</DropdownMenuItem>
+				)}
+				<DropdownMenuItem onSelect={onAddCredential}>
+					<PlusCircle className="size-4" />
+					<span>{t('llm-select.addCredential')}</span>
+				</DropdownMenuItem>
+			</DropdownMenuContent>
+		</DropdownMenu>
+	);
+}
diff --git a/examples/web_ui/frontend/src/components/select/PermissionModeSelect.tsx b/examples/web_ui/frontend/src/components/select/PermissionModeSelect.tsx
new file mode 100644
index 0000000..f2f9fb0
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/select/PermissionModeSelect.tsx
@@ -0,0 +1,75 @@
+import { ChevronDown, UserRoundKey } from 'lucide-react';
+
+import type { PermissionMode } from '@/api/types';
+import { Button } from '@/components/ui/button';
+import {
+	DropdownMenu,
+	DropdownMenuContent,
+	DropdownMenuGroup,
+	DropdownMenuItem,
+	DropdownMenuLabel,
+	DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip';
+import { useTranslation } from '@/i18n/useI18n.ts';
+import { cn } from '@/lib/utils.ts';
+
+const PERMISSION_MODES: { value: PermissionMode; label: string }[] = [
+	{ value: 'default', label: 'Default' },
+	{ value: 'accept_edits', label: 'Accept Edits' },
+	{ value: 'explore', label: 'Explore' },
+	{ value: 'bypass', label: 'Bypass' },
+	{ value: 'dont_ask', label: "Don't Ask" },
+];
+
+interface Props {
+	className?: string;
+	value?: PermissionMode;
+	disabled?: boolean;
+	onChange?: (value: PermissionMode) => void;
+}
+
+export function PermissionModeSelect({ className, value, disabled, onChange }: Props) {
+	const { t } = useTranslation();
+
+	const displayLabel = value
+		? (PERMISSION_MODES.find((m) => m.value === value)?.label ?? value)
+		: t('permission-mode.placeholder');
+
+	return (
+		<DropdownMenu>
+			<DropdownMenuTrigger asChild>
+				<Button
+					variant="outline"
+					size="sm"
+					className={cn('justify-between gap-1', className)}
+					disabled={disabled}
+					tooltip={t('permission-mode.trigger-tooltip')}
+				>
+					<div className="flex flex-row items-center gap-x-2">
+						<UserRoundKey />
+						<span className="truncate">{displayLabel}</span>
+					</div>
+					<ChevronDown className="size-3.5 opacity-50" />
+				</Button>
+			</DropdownMenuTrigger>
+			<DropdownMenuContent align="start" className="min-w-48">
+				<DropdownMenuGroup>
+					<DropdownMenuLabel>{t('permission-mode.label')}</DropdownMenuLabel>
+					{PERMISSION_MODES.map((mode) => (
+						<Tooltip key={mode.value}>
+							<TooltipTrigger asChild>
+								<DropdownMenuItem onSelect={() => onChange?.(mode.value)}>
+									{mode.label}
+								</DropdownMenuItem>
+							</TooltipTrigger>
+							<TooltipContent side="right">
+								{t(`permission-mode.${mode.value}-tooltip`)}
+							</TooltipContent>
+						</Tooltip>
+					))}
+				</DropdownMenuGroup>
+			</DropdownMenuContent>
+		</DropdownMenu>
+	);
+}
diff --git a/examples/web_ui/frontend/src/components/select/TimezoneSelect.tsx b/examples/web_ui/frontend/src/components/select/TimezoneSelect.tsx
new file mode 100644
index 0000000..4e532f2
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/select/TimezoneSelect.tsx
@@ -0,0 +1,89 @@
+import { ChevronDown, Globe, Search } from 'lucide-react';
+import * as React from 'react';
+
+import { Button } from '@/components/ui/button';
+import {
+	DropdownMenu,
+	DropdownMenuContent,
+	DropdownMenuItem,
+	DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+import { Input } from '@/components/ui/input';
+import { cn } from '@/lib/utils.ts';
+
+const LOCAL_TIMEZONE = Intl.DateTimeFormat().resolvedOptions().timeZone;
+
+const ALL_TIMEZONES: string[] = Intl.supportedValuesOf('timeZone');
+
+interface Props {
+	className?: string;
+	value?: string;
+	onChange?: (value: string) => void;
+	disabled?: boolean;
+}
+
+export function TimezoneSelect({ className, value, onChange, disabled }: Props) {
+	const [search, setSearch] = React.useState('');
+	const inputRef = React.useRef<HTMLInputElement>(null);
+
+	const filtered = React.useMemo(() => {
+		if (!search.trim()) return ALL_TIMEZONES;
+		const q = search.toLowerCase();
+		return ALL_TIMEZONES.filter((tz) => tz.toLowerCase().includes(q));
+	}, [search]);
+
+	const displayLabel = value || LOCAL_TIMEZONE;
+
+	return (
+		<DropdownMenu
+			onOpenChange={(open) => {
+				if (open) setSearch('');
+			}}
+		>
+			<DropdownMenuTrigger asChild>
+				<Button
+					variant="outline"
+					size="sm"
+					className={cn('justify-between gap-1', className)}
+					disabled={disabled}
+				>
+					<div className="flex flex-row items-center gap-x-2">
+						<Globe className="size-3.5" />
+						<span className="truncate text-xs">{displayLabel}</span>
+					</div>
+					<ChevronDown className="size-3.5 opacity-50" />
+				</Button>
+			</DropdownMenuTrigger>
+			<DropdownMenuContent align="start" className="w-64">
+				<div className="flex items-center gap-2 px-2 py-1.5 border-b">
+					<Search className="size-3.5 opacity-50" />
+					<Input
+						ref={inputRef}
+						value={search}
+						onChange={(e) => setSearch(e.target.value)}
+						placeholder="Search timezone..."
+						className="h-6 border-0 shadow-none focus-visible:ring-0 text-xs px-0"
+						onKeyDown={(e) => e.stopPropagation()}
+					/>
+				</div>
+				<div className="max-h-60 overflow-y-auto">
+					{filtered.length === 0 ? (
+						<div className="px-2 py-4 text-center text-xs text-muted-foreground">
+							No timezone found
+						</div>
+					) : (
+						filtered.map((tz) => (
+							<DropdownMenuItem
+								key={tz}
+								onSelect={() => onChange?.(tz)}
+								className="text-xs"
+							>
+								{tz}
+							</DropdownMenuItem>
+						))
+					)}
+				</div>
+			</DropdownMenuContent>
+		</DropdownMenu>
+	);
+}
diff --git a/examples/web_ui/frontend/src/components/team/TeamSidebar.tsx b/examples/web_ui/frontend/src/components/team/TeamSidebar.tsx
new file mode 100644
index 0000000..eb6ee48
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/team/TeamSidebar.tsx
@@ -0,0 +1,131 @@
+import { Bot, Crown } from 'lucide-react';
+import { useNavigate } from 'react-router-dom';
+
+import type { TeamDetailResponse, TeamMemberInfo, AgentView } from '@/api';
+import {
+	Sidebar,
+	SidebarContent,
+	SidebarFooter,
+	SidebarGroup,
+	SidebarGroupContent,
+	SidebarGroupLabel,
+	SidebarHeader,
+	SidebarMenu,
+	SidebarMenuButton,
+	SidebarMenuItem,
+} from '@/components/ui/sidebar';
+import { useTranslation } from '@/i18n/useI18n';
+
+interface TeamSidebarProps {
+	/** Resolved team detail (leader + members) — drives all rendering. */
+	team: TeamDetailResponse;
+	/**
+	 * The session id currently shown in the chat area. Used both for
+	 * highlighting the active row and for deciding whether the row
+	 * being clicked is already the current one.
+	 */
+	currentSessionId: string;
+}
+
+/**
+ * Secondary sidebar shown next to the chat area whenever the open
+ * session participates in a team.
+ *
+ * Built on the shared shadcn `Sidebar` primitives so it visually
+ * matches the main page sidebar (same paddings, item heights,
+ * active-row treatment, etc.). Renders the leader at the top
+ * followed by every member; all rows are clickable.
+ *
+ * Clicking the leader row navigates to
+ * `/chat/<leaderAgentId>/<leaderSessionId>` (drops the URL's
+ * optional `:memberId` slot so the chat area falls back to the
+ * leader session). Clicking a member row navigates to
+ * `/chat/<leaderAgentId>/<leaderSessionId>/<memberAgentId>` — the
+ * outer URL slots stay the same so the main page sidebar does not
+ * collapse; only the chat area reroutes to the member's session.
+ *
+ * Both `leaderAgentId` and `leaderSessionId` are derived from the
+ * passed `team` prop, so the parent only needs to know which
+ * session is currently active.
+ *
+ * @param team - Resolved team detail.
+ * @param currentSessionId - Session id currently shown in the chat
+ *   area; used to drive row highlighting.
+ * @returns A vertical sidebar element.
+ */
+export function TeamSidebar({ team, currentSessionId }: TeamSidebarProps) {
+	const { t } = useTranslation();
+	const navigate = useNavigate();
+
+	const leaderAgentId = team.leader_agent?.id ?? null;
+	const leaderSessionId = team.team.session_id;
+
+	const goToLeader = () => {
+		if (!leaderAgentId) return;
+		navigate(`/chat/${leaderAgentId}/${leaderSessionId}`);
+	};
+
+	const goToMember = (memberAgentId: string) => {
+		if (!leaderAgentId) return;
+		navigate(`/chat/${leaderAgentId}/${leaderSessionId}/${memberAgentId}`);
+	};
+
+	const renderLeader = (leader: AgentView) => (
+		<SidebarMenuItem>
+			<SidebarMenuButton isActive={currentSessionId === leaderSessionId} onClick={goToLeader}>
+				<Crown />
+				<span className="truncate">{leader.data.name}</span>
+			</SidebarMenuButton>
+		</SidebarMenuItem>
+	);
+
+	const renderMember = (member: TeamMemberInfo) => (
+		<SidebarMenuItem key={member.agent.id}>
+			<SidebarMenuButton
+				isActive={member.session_id === currentSessionId}
+				disabled={member.session_id === null}
+				onClick={() => goToMember(member.agent.id)}
+			>
+				<Bot />
+				<span className="truncate">{member.agent.data.name}</span>
+			</SidebarMenuButton>
+		</SidebarMenuItem>
+	);
+
+	return (
+		<Sidebar collapsible="none" className="w-56 border-r">
+			<SidebarHeader>
+				<div className="flex flex-col gap-y-1 px-2 py-1">
+					<span className="text-muted-foreground text-xs uppercase tracking-wide">
+						{t('common.team')}
+					</span>
+					<span className="truncate text-sm font-medium">{team.team.data.name}</span>
+				</div>
+			</SidebarHeader>
+			<SidebarContent>
+				{team.leader_agent && (
+					<SidebarGroup>
+						<SidebarGroupLabel>{t('common.leader')}</SidebarGroupLabel>
+						<SidebarGroupContent>
+							<SidebarMenu>{renderLeader(team.leader_agent)}</SidebarMenu>
+						</SidebarGroupContent>
+					</SidebarGroup>
+				)}
+
+				<SidebarGroup>
+					<SidebarGroupLabel>{t('team-sidebar.membersHeading')}</SidebarGroupLabel>
+					<SidebarGroupContent>
+						{team.members.length === 0 ? (
+							<p className="px-3 py-2 text-xs text-muted-foreground">
+								{t('team-sidebar.noMembers')}
+							</p>
+						) : (
+							<SidebarMenu>{team.members.map(renderMember)}</SidebarMenu>
+						)}
+					</SidebarGroupContent>
+				</SidebarGroup>
+			</SidebarContent>
+			<SidebarFooter />
+		</Sidebar>
+	);
+}
diff --git a/examples/web_ui/frontend/src/components/tour/ChatTourController.tsx b/examples/web_ui/frontend/src/components/tour/ChatTourController.tsx
new file mode 100644
index 0000000..1df22e3
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/tour/ChatTourController.tsx
@@ -0,0 +1,61 @@
+import { useOnborda } from 'onborda';
+import { useEffect, useRef } from 'react';
+
+import { CHAT_TOUR_NAME } from './chatTourSteps';
+
+interface Props {
+	agentsCount: number;
+	sessionsCount: number;
+	/** Force-open the sidebar so #tour-create-session exists in the DOM. */
+	onEnsureSidebarOpen?: () => void;
+}
+
+const TOUR_DONE_KEY = 'chat_tour_done';
+const FORCE_TOUR_KEY = 'force_tour';
+
+export const ChatTourController = ({ agentsCount, sessionsCount, onEnsureSidebarOpen }: Props) => {
+	const { currentStep, currentTour, setCurrentStep, startOnborda } = useOnborda();
+	const startCountsRef = useRef({ agents: agentsCount, sessions: sessionsCount });
+	const startedRef = useRef(false);
+
+	// Auto-start on mount: first-time visitors, or manual trigger via sessionStorage.
+	useEffect(() => {
+		if (startedRef.current) return;
+		const force = sessionStorage.getItem(FORCE_TOUR_KEY) === '1';
+		const done = localStorage.getItem(TOUR_DONE_KEY) === '1';
+		if (force) sessionStorage.removeItem(FORCE_TOUR_KEY);
+		if (!force && done) return;
+		startedRef.current = true;
+		onEnsureSidebarOpen?.();
+		// Defer one tick so target elements are mounted.
+		const id = window.setTimeout(() => startOnborda(CHAT_TOUR_NAME), 300);
+		return () => window.clearTimeout(id);
+	}, [onEnsureSidebarOpen, startOnborda]);
+
+	// Snapshot the agents/sessions count when entering each step so we can
+	// detect "user just created one" rather than "they already had some."
+	useEffect(() => {
+		if (currentTour !== CHAT_TOUR_NAME) return;
+		if (currentStep === 0) startCountsRef.current.agents = agentsCount;
+		if (currentStep === 1) startCountsRef.current.sessions = sessionsCount;
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [currentStep, currentTour]);
+
+	// Step 0 → 1: agent created
+	useEffect(() => {
+		if (currentTour !== CHAT_TOUR_NAME || currentStep !== 0) return;
+		if (agentsCount > startCountsRef.current.agents) setCurrentStep(1);
+	}, [agentsCount, currentStep, currentTour, setCurrentStep]);
+
+	// Step 1 → 2: session created
+	useEffect(() => {
+		if (currentTour !== CHAT_TOUR_NAME || currentStep !== 1) return;
+		if (sessionsCount > startCountsRef.current.sessions) setCurrentStep(2);
+	}, [sessionsCount, currentStep, currentTour, setCurrentStep]);
+
+	// Mark tour as done when finished — triggered when the user reaches the last step
+	// and the cards's Finish button calls closeOnborda (which sets the flag inside TourCard).
+	// Nothing else to do here.
+
+	return null;
+};
diff --git a/examples/web_ui/frontend/src/components/tour/TourCard.tsx b/examples/web_ui/frontend/src/components/tour/TourCard.tsx
new file mode 100644
index 0000000..322b154
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/tour/TourCard.tsx
@@ -0,0 +1,73 @@
+import { X } from 'lucide-react';
+import { useOnborda, type CardComponentProps } from 'onborda';
+
+import { Button } from '@/components/ui/button';
+import { Card, CardContent, CardFooter, CardHeader, CardTitle } from '@/components/ui/card';
+import { useTranslation } from '@/i18n/useI18n';
+
+export const TourCard = ({
+	step,
+	currentStep,
+	totalSteps,
+	nextStep,
+	prevStep,
+	arrow,
+}: CardComponentProps) => {
+	const { t } = useTranslation();
+	const { closeOnborda } = useOnborda();
+
+	const isFirst = currentStep === 0;
+	const isLast = currentStep === totalSteps - 1;
+
+	const handleClose = () => {
+		localStorage.setItem('chat_tour_done', '1');
+		closeOnborda();
+	};
+
+	const handleNext = () => {
+		if (isLast) {
+			handleClose();
+			return;
+		}
+		nextStep();
+	};
+
+	return (
+		<>
+			{/* Arrow inherits color via `currentColor`; force it to the card's
+			    background so the triangle visually merges with the card. */}
+			<span style={{ color: 'var(--card)' }}>{arrow}</span>
+
+			<Card size="sm" className="w-80 shadow-lg">
+				<CardHeader className="flex flex-row items-start justify-between gap-2">
+					<CardTitle>{step.title}</CardTitle>
+					<button
+						onClick={handleClose}
+						className="text-muted-foreground hover:text-foreground -mt-1"
+						aria-label={t('tour.skip')}
+					>
+						<X className="size-4" />
+					</button>
+				</CardHeader>
+				<CardContent className="text-muted-foreground text-sm leading-relaxed">
+					{step.content}
+				</CardContent>
+				<CardFooter className="flex items-center justify-between">
+					<span className="text-muted-foreground text-xs">
+						{t('tour.step', { current: currentStep + 1, total: totalSteps })}
+					</span>
+					<div className="flex items-center gap-2">
+						{!isFirst && (
+							<Button size="sm" variant="ghost" onClick={prevStep}>
+								{t('tour.prev')}
+							</Button>
+						)}
+						<Button size="sm" onClick={handleNext}>
+							{isLast ? t('tour.finish') : t('tour.next')}
+						</Button>
+					</div>
+				</CardFooter>
+			</Card>
+		</>
+	);
+};
diff --git a/examples/web_ui/frontend/src/components/tour/chatTourSteps.ts b/examples/web_ui/frontend/src/components/tour/chatTourSteps.ts
new file mode 100644
index 0000000..dcb772b
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/tour/chatTourSteps.ts
@@ -0,0 +1,60 @@
+import type { TFunction } from 'i18next';
+import type { Tour } from 'onborda/dist/types';
+
+export const CHAT_TOUR_NAME = 'chat-onboarding';
+
+export const buildChatTour = (t: TFunction): Tour => ({
+	tour: CHAT_TOUR_NAME,
+	steps: [
+		{
+			icon: null,
+			title: t('tour.createAgent.title'),
+			content: t('tour.createAgent.content'),
+			selector: '#tour-create-agent',
+			side: 'bottom',
+			showControls: false,
+			pointerPadding: 8,
+			pointerRadius: 8,
+		},
+		{
+			icon: null,
+			title: t('tour.createSession.title'),
+			content: t('tour.createSession.content'),
+			selector: '#tour-create-session',
+			side: 'right',
+			showControls: false,
+			pointerPadding: 6,
+			pointerRadius: 6,
+		},
+		{
+			icon: null,
+			title: t('tour.llmSelect.title'),
+			content: t('tour.llmSelect.content'),
+			selector: '#tour-llm-select',
+			side: 'bottom',
+			showControls: false,
+			pointerPadding: 6,
+			pointerRadius: 8,
+		},
+		{
+			icon: null,
+			title: t('tour.permissionMode.title'),
+			content: t('tour.permissionMode.content'),
+			selector: '#tour-permission-mode',
+			side: 'bottom-right',
+			showControls: false,
+			pointerPadding: 6,
+			pointerRadius: 8,
+		},
+		{
+			icon: null,
+			title: t('tour.chatInput.title'),
+			content: t('tour.chatInput.content'),
+			selector: '#tour-chat-input',
+			side: 'top',
+			showControls: false,
+			pointerPadding: 6,
+			pointerRadius: 16,
+		},
+	],
+});
diff --git a/examples/web_ui/frontend/src/components/ui/alert.tsx b/examples/web_ui/frontend/src/components/ui/alert.tsx
new file mode 100644
index 0000000..929a85c
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/ui/alert.tsx
@@ -0,0 +1,73 @@
+import * as React from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+
+import { cn } from '@/lib/utils';
+
+const alertVariants = cva(
+	"group/alert relative grid w-full gap-0.5 rounded-lg border px-2.5 py-2 text-left text-sm has-data-[slot=alert-action]:relative has-data-[slot=alert-action]:pr-18 has-[>svg]:grid-cols-[auto_1fr] has-[>svg]:gap-x-2 *:[svg]:row-span-2 *:[svg]:translate-y-0.5 *:[svg]:text-current *:[svg:not([class*='size-'])]:size-4",
+	{
+		variants: {
+			variant: {
+				default: 'bg-card text-card-foreground',
+				destructive:
+					'bg-card text-destructive *:data-[slot=alert-description]:text-destructive/90 *:[svg]:text-current',
+			},
+		},
+		defaultVariants: {
+			variant: 'default',
+		},
+	},
+);
+
+function Alert({
+	className,
+	variant,
+	...props
+}: React.ComponentProps<'div'> & VariantProps<typeof alertVariants>) {
+	return (
+		<div
+			data-slot="alert"
+			role="alert"
+			className={cn(alertVariants({ variant }), className)}
+			{...props}
+		/>
+	);
+}
+
+function AlertTitle({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="alert-title"
+			className={cn(
+				'font-medium group-has-[>svg]/alert:col-start-2 [&_a]:underline [&_a]:underline-offset-3 [&_a]:hover:text-foreground',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+function AlertDescription({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="alert-description"
+			className={cn(
+				'text-sm text-balance text-muted-foreground md:text-pretty [&_a]:underline [&_a]:underline-offset-3 [&_a]:hover:text-foreground [&_p:not(:last-child)]:mb-4',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+function AlertAction({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="alert-action"
+			className={cn('absolute top-2 right-2', className)}
+			{...props}
+		/>
+	);
+}
+
+export { Alert, AlertTitle, AlertDescription, AlertAction };
diff --git a/examples/web_ui/frontend/src/components/ui/badge.tsx b/examples/web_ui/frontend/src/components/ui/badge.tsx
new file mode 100644
index 0000000..44d4582
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/ui/badge.tsx
@@ -0,0 +1,46 @@
+import * as React from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { Slot } from 'radix-ui';
+
+import { cn } from '@/lib/utils';
+
+const badgeVariants = cva(
+	'group/badge inline-flex h-5 w-fit shrink-0 items-center justify-center gap-1 overflow-hidden rounded-4xl border border-transparent px-2 py-0.5 text-xs font-medium whitespace-nowrap transition-all focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 aria-invalid:border-destructive aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 [&>svg]:pointer-events-none [&>svg]:size-3!',
+	{
+		variants: {
+			variant: {
+				default: 'bg-primary text-primary-foreground [a]:hover:bg-primary/80',
+				secondary: 'bg-secondary text-secondary-foreground [a]:hover:bg-secondary/80',
+				destructive:
+					'bg-destructive/10 text-destructive focus-visible:ring-destructive/20 dark:bg-destructive/20 dark:focus-visible:ring-destructive/40 [a]:hover:bg-destructive/20',
+				outline:
+					'border-border text-foreground [a]:hover:bg-muted [a]:hover:text-muted-foreground',
+				ghost: 'hover:bg-muted hover:text-muted-foreground dark:hover:bg-muted/50',
+				link: 'text-primary underline-offset-4 hover:underline',
+			},
+		},
+		defaultVariants: {
+			variant: 'default',
+		},
+	},
+);
+
+function Badge({
+	className,
+	variant = 'default',
+	asChild = false,
+	...props
+}: React.ComponentProps<'span'> & VariantProps<typeof badgeVariants> & { asChild?: boolean }) {
+	const Comp = asChild ? Slot.Root : 'span';
+
+	return (
+		<Comp
+			data-slot="badge"
+			data-variant={variant}
+			className={cn(badgeVariants({ variant }), className)}
+			{...props}
+		/>
+	);
+}
+
+export { Badge, badgeVariants };
diff --git a/examples/web_ui/frontend/src/components/ui/button-group.tsx b/examples/web_ui/frontend/src/components/ui/button-group.tsx
new file mode 100644
index 0000000..99b7888
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/ui/button-group.tsx
@@ -0,0 +1,78 @@
+import { cva, type VariantProps } from 'class-variance-authority';
+import { Slot } from 'radix-ui';
+
+import { cn } from '@/lib/utils';
+import { Separator } from '@/components/ui/separator';
+
+const buttonGroupVariants = cva(
+	"group/button-group flex w-fit items-stretch *:focus-visible:relative *:focus-visible:z-10 has-[>[data-slot=button-group]]:gap-2 has-[select[aria-hidden=true]:last-child]:[&>[data-slot=select-trigger]:last-of-type]:rounded-r-lg [&>[data-slot=select-trigger]:not([class*='w-'])]:w-fit [&>input]:flex-1",
+	{
+		variants: {
+			orientation: {
+				horizontal:
+					'[&>*:not(:first-child)]:rounded-l-none [&>*:not(:first-child)]:border-l-0 [&>*:not(:last-child)]:rounded-r-none [&>[data-slot]:not(:has(~[data-slot]))]:rounded-r-lg!',
+				vertical:
+					'flex-col [&>*:not(:first-child)]:rounded-t-none [&>*:not(:first-child)]:border-t-0 [&>*:not(:last-child)]:rounded-b-none [&>[data-slot]:not(:has(~[data-slot]))]:rounded-b-lg!',
+			},
+		},
+		defaultVariants: {
+			orientation: 'horizontal',
+		},
+	},
+);
+
+function ButtonGroup({
+	className,
+	orientation,
+	...props
+}: React.ComponentProps<'div'> & VariantProps<typeof buttonGroupVariants>) {
+	return (
+		<div
+			role="group"
+			data-slot="button-group"
+			data-orientation={orientation}
+			className={cn(buttonGroupVariants({ orientation }), className)}
+			{...props}
+		/>
+	);
+}
+
+function ButtonGroupText({
+	className,
+	asChild = false,
+	...props
+}: React.ComponentProps<'div'> & {
+	asChild?: boolean;
+}) {
+	const Comp = asChild ? Slot.Root : 'div';
+
+	return (
+		<Comp
+			className={cn(
+				"flex items-center gap-2 rounded-lg border bg-muted px-2.5 text-sm font-medium [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4",
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+function ButtonGroupSeparator({
+	className,
+	orientation = 'vertical',
+	...props
+}: React.ComponentProps<typeof Separator>) {
+	return (
+		<Separator
+			data-slot="button-group-separator"
+			orientation={orientation}
+			className={cn(
+				'relative self-stretch bg-input data-horizontal:mx-px data-horizontal:w-auto data-vertical:my-px data-vertical:h-auto',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+export { ButtonGroup, ButtonGroupSeparator, ButtonGroupText, buttonGroupVariants };
diff --git a/examples/web_ui/frontend/src/components/ui/button.tsx b/examples/web_ui/frontend/src/components/ui/button.tsx
new file mode 100644
index 0000000..8a215c4
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/ui/button.tsx
@@ -0,0 +1,86 @@
+import * as React from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { Slot } from 'radix-ui';
+
+import { cn } from '@/lib/utils';
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip.tsx';
+
+const buttonVariants = cva(
+	"group/button inline-flex shrink-0 items-center justify-center rounded-lg border border-transparent bg-clip-padding text-sm font-medium whitespace-nowrap transition-all outline-none select-none focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 active:not-aria-[haspopup]:translate-y-px disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+	{
+		variants: {
+			variant: {
+				default: 'bg-primary text-primary-foreground [a]:hover:bg-primary/80',
+				outline:
+					'border-border bg-background hover:bg-muted hover:text-foreground aria-expanded:bg-muted aria-expanded:text-foreground dark:border-input dark:bg-input/30 dark:hover:bg-input/50',
+				secondary:
+					'bg-secondary text-secondary-foreground hover:bg-secondary/80 aria-expanded:bg-secondary aria-expanded:text-secondary-foreground',
+				ghost: 'hover:bg-muted hover:text-foreground aria-expanded:bg-muted aria-expanded:text-foreground dark:hover:bg-muted/50',
+				destructive:
+					'bg-destructive/10 text-destructive hover:bg-destructive/20 focus-visible:border-destructive/40 focus-visible:ring-destructive/20 dark:bg-destructive/20 dark:hover:bg-destructive/30 dark:focus-visible:ring-destructive/40',
+				link: 'text-primary underline-offset-4 hover:underline',
+			},
+			size: {
+				default:
+					'h-8 gap-1.5 px-2.5 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2',
+				xs: "h-6 gap-1 rounded-[min(var(--radius-md),10px)] px-2 text-xs in-data-[slot=button-group]:rounded-lg has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 [&_svg:not([class*='size-'])]:size-3",
+				sm: "h-7 gap-1 rounded-[min(var(--radius-md),12px)] px-2.5 text-[0.8rem] in-data-[slot=button-group]:rounded-lg has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 [&_svg:not([class*='size-'])]:size-3.5",
+				lg: 'h-9 gap-1.5 px-2.5 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2',
+				icon: 'size-8',
+				'icon-xs':
+					"size-6 rounded-[min(var(--radius-md),10px)] in-data-[slot=button-group]:rounded-lg [&_svg:not([class*='size-'])]:size-3",
+				'icon-sm':
+					"size-7 rounded-[min(var(--radius-md),12px)] in-data-[slot=button-group]:rounded-lg [&_svg:not([class*='size-'])]:size-3.5",
+				'icon-lg': 'size-9',
+			},
+		},
+		defaultVariants: {
+			variant: 'default',
+			size: 'default',
+		},
+	},
+);
+
+function Button({
+	className,
+	variant = 'default',
+	size = 'default',
+	asChild = false,
+	tooltip = undefined,
+	...props
+}: React.ComponentProps<'button'> &
+	VariantProps<typeof buttonVariants> & {
+		asChild?: boolean;
+		tooltip?: string;
+	}) {
+	const Comp = asChild ? Slot.Root : 'button';
+
+	if (tooltip === undefined) {
+		return (
+			<Comp
+				data-slot="button"
+				data-variant={variant}
+				data-size={size}
+				className={cn(buttonVariants({ variant, size, className }))}
+				{...props}
+			/>
+		);
+	}
+
+	return (
+		<Tooltip>
+			<TooltipTrigger asChild>
+				<Comp
+					data-slot="button"
+					data-variant={variant}
+					data-size={size}
+					className={cn(buttonVariants({ variant, size, className }))}
+					{...props}
+				/>
+			</TooltipTrigger>
+			<TooltipContent>{tooltip}</TooltipContent>
+		</Tooltip>
+	);
+}
+
+export { Button, buttonVariants };
diff --git a/examples/web_ui/frontend/src/components/ui/calendar.tsx b/examples/web_ui/frontend/src/components/ui/calendar.tsx
new file mode 100644
index 0000000..392c724
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/ui/calendar.tsx
@@ -0,0 +1,198 @@
+import * as React from 'react';
+import { DayPicker, getDefaultClassNames, type DayButton, type Locale } from 'react-day-picker';
+
+import { cn } from '@/lib/utils';
+import { Button, buttonVariants } from '@/components/ui/button';
+import { ChevronLeftIcon, ChevronRightIcon, ChevronDownIcon } from 'lucide-react';
+
+function Calendar({
+	className,
+	classNames,
+	showOutsideDays = true,
+	captionLayout = 'label',
+	buttonVariant = 'ghost',
+	locale,
+	formatters,
+	components,
+	...props
+}: React.ComponentProps<typeof DayPicker> & {
+	buttonVariant?: React.ComponentProps<typeof Button>['variant'];
+}) {
+	const defaultClassNames = getDefaultClassNames();
+
+	return (
+		<DayPicker
+			showOutsideDays={showOutsideDays}
+			className={cn(
+				'group/calendar bg-background p-2 [--cell-radius:var(--radius-md)] [--cell-size:--spacing(7)] in-data-[slot=card-content]:bg-transparent in-data-[slot=popover-content]:bg-transparent',
+				String.raw`rtl:**:[.rdp-button\_next>svg]:rotate-180`,
+				String.raw`rtl:**:[.rdp-button\_previous>svg]:rotate-180`,
+				className,
+			)}
+			captionLayout={captionLayout}
+			locale={locale}
+			formatters={{
+				formatMonthDropdown: (date) =>
+					date.toLocaleString(locale?.code, { month: 'short' }),
+				...formatters,
+			}}
+			classNames={{
+				root: cn('w-fit', defaultClassNames.root),
+				months: cn('relative flex flex-col gap-4 md:flex-row', defaultClassNames.months),
+				month: cn('flex w-full flex-col gap-4', defaultClassNames.month),
+				nav: cn(
+					'absolute inset-x-0 top-0 flex w-full items-center justify-between gap-1',
+					defaultClassNames.nav,
+				),
+				button_previous: cn(
+					buttonVariants({ variant: buttonVariant }),
+					'size-(--cell-size) p-0 select-none aria-disabled:opacity-50',
+					defaultClassNames.button_previous,
+				),
+				button_next: cn(
+					buttonVariants({ variant: buttonVariant }),
+					'size-(--cell-size) p-0 select-none aria-disabled:opacity-50',
+					defaultClassNames.button_next,
+				),
+				month_caption: cn(
+					'flex h-(--cell-size) w-full items-center justify-center px-(--cell-size)',
+					defaultClassNames.month_caption,
+				),
+				dropdowns: cn(
+					'flex h-(--cell-size) w-full items-center justify-center gap-1.5 text-sm font-medium',
+					defaultClassNames.dropdowns,
+				),
+				dropdown_root: cn(
+					'relative rounded-(--cell-radius)',
+					defaultClassNames.dropdown_root,
+				),
+				dropdown: cn('absolute inset-0 bg-popover opacity-0', defaultClassNames.dropdown),
+				caption_label: cn(
+					'font-medium select-none',
+					captionLayout === 'label'
+						? 'text-sm'
+						: 'flex items-center gap-1 rounded-(--cell-radius) text-sm [&>svg]:size-3.5 [&>svg]:text-muted-foreground',
+					defaultClassNames.caption_label,
+				),
+				month_grid: cn('w-full border-collapse', defaultClassNames.month_grid),
+				weekdays: cn('flex', defaultClassNames.weekdays),
+				weekday: cn(
+					'flex-1 rounded-(--cell-radius) text-[0.8rem] font-normal text-muted-foreground select-none',
+					defaultClassNames.weekday,
+				),
+				week: cn('mt-2 flex w-full', defaultClassNames.week),
+				week_number_header: cn(
+					'w-(--cell-size) select-none',
+					defaultClassNames.week_number_header,
+				),
+				week_number: cn(
+					'text-[0.8rem] text-muted-foreground select-none',
+					defaultClassNames.week_number,
+				),
+				day: cn(
+					'group/day relative aspect-square h-full w-full rounded-(--cell-radius) p-0 text-center select-none [&:last-child[data-selected=true]_button]:rounded-r-(--cell-radius)',
+					props.showWeekNumber
+						? '[&:nth-child(2)[data-selected=true]_button]:rounded-l-(--cell-radius)'
+						: '[&:first-child[data-selected=true]_button]:rounded-l-(--cell-radius)',
+					defaultClassNames.day,
+				),
+				range_start: cn(
+					'relative isolate z-0 rounded-l-(--cell-radius) bg-muted after:absolute after:inset-y-0 after:right-0 after:w-4 after:bg-muted',
+					defaultClassNames.range_start,
+				),
+				range_middle: cn('rounded-none', defaultClassNames.range_middle),
+				range_end: cn(
+					'relative isolate z-0 rounded-r-(--cell-radius) bg-muted after:absolute after:inset-y-0 after:left-0 after:w-4 after:bg-muted',
+					defaultClassNames.range_end,
+				),
+				today: cn(
+					'rounded-(--cell-radius) bg-muted text-foreground data-[selected=true]:rounded-none',
+					defaultClassNames.today,
+				),
+				outside: cn(
+					'text-muted-foreground aria-selected:text-muted-foreground',
+					defaultClassNames.outside,
+				),
+				disabled: cn('text-muted-foreground opacity-50', defaultClassNames.disabled),
+				hidden: cn('invisible', defaultClassNames.hidden),
+				...classNames,
+			}}
+			components={{
+				Root: ({ className, rootRef, ...props }) => {
+					return (
+						<div
+							data-slot="calendar"
+							ref={rootRef}
+							className={cn(className)}
+							{...props}
+						/>
+					);
+				},
+				Chevron: ({ className, orientation, ...props }) => {
+					if (orientation === 'left') {
+						return <ChevronLeftIcon className={cn('size-4', className)} {...props} />;
+					}
+
+					if (orientation === 'right') {
+						return <ChevronRightIcon className={cn('size-4', className)} {...props} />;
+					}
+
+					return <ChevronDownIcon className={cn('size-4', className)} {...props} />;
+				},
+				DayButton: ({ ...props }) => <CalendarDayButton locale={locale} {...props} />,
+				WeekNumber: ({ children, ...props }) => {
+					return (
+						<td {...props}>
+							<div className="flex size-(--cell-size) items-center justify-center text-center">
+								{children}
+							</div>
+						</td>
+					);
+				},
+				...components,
+			}}
+			{...props}
+		/>
+	);
+}
+
+function CalendarDayButton({
+	className,
+	day,
+	modifiers,
+	locale,
+	...props
+}: React.ComponentProps<typeof DayButton> & { locale?: Partial<Locale> }) {
+	const defaultClassNames = getDefaultClassNames();
+
+	const ref = React.useRef<HTMLButtonElement>(null);
+	React.useEffect(() => {
+		if (modifiers.focused) ref.current?.focus();
+	}, [modifiers.focused]);
+
+	return (
+		<Button
+			ref={ref}
+			variant="ghost"
+			size="icon"
+			data-day={day.date.toLocaleDateString(locale?.code)}
+			data-selected-single={
+				modifiers.selected &&
+				!modifiers.range_start &&
+				!modifiers.range_end &&
+				!modifiers.range_middle
+			}
+			data-range-start={modifiers.range_start}
+			data-range-end={modifiers.range_end}
+			data-range-middle={modifiers.range_middle}
+			className={cn(
+				'relative isolate z-10 flex aspect-square size-auto w-full min-w-(--cell-size) flex-col gap-1 border-0 leading-none font-normal group-data-[focused=true]/day:relative group-data-[focused=true]/day:z-10 group-data-[focused=true]/day:border-ring group-data-[focused=true]/day:ring-[3px] group-data-[focused=true]/day:ring-ring/50 data-[range-end=true]:rounded-(--cell-radius) data-[range-end=true]:rounded-r-(--cell-radius) data-[range-end=true]:bg-primary data-[range-end=true]:text-primary-foreground data-[range-middle=true]:rounded-none data-[range-middle=true]:bg-muted data-[range-middle=true]:text-foreground data-[range-start=true]:rounded-(--cell-radius) data-[range-start=true]:rounded-l-(--cell-radius) data-[range-start=true]:bg-primary data-[range-start=true]:text-primary-foreground data-[selected-single=true]:bg-primary data-[selected-single=true]:text-primary-foreground dark:hover:text-foreground [&>span]:text-xs [&>span]:opacity-70',
+				defaultClassNames.day,
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+export { Calendar, CalendarDayButton };
diff --git a/examples/web_ui/frontend/src/components/ui/card.tsx b/examples/web_ui/frontend/src/components/ui/card.tsx
new file mode 100644
index 0000000..464f215
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/ui/card.tsx
@@ -0,0 +1,95 @@
+import * as React from 'react';
+
+import { cn } from '@/lib/utils';
+
+function Card({
+	className,
+	size = 'default',
+	...props
+}: React.ComponentProps<'div'> & { size?: 'default' | 'sm' }) {
+	return (
+		<div
+			data-slot="card"
+			data-size={size}
+			className={cn(
+				'group/card flex flex-col gap-4 overflow-hidden rounded-xl bg-card py-4 text-sm text-card-foreground ring-1 ring-foreground/10 has-data-[slot=card-footer]:pb-0 has-[>img:first-child]:pt-0 data-[size=sm]:gap-3 data-[size=sm]:py-3 data-[size=sm]:has-data-[slot=card-footer]:pb-0 *:[img:first-child]:rounded-t-xl *:[img:last-child]:rounded-b-xl',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+function CardHeader({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="card-header"
+			className={cn(
+				'group/card-header @container/card-header grid auto-rows-min items-start gap-1 rounded-t-xl px-4 group-data-[size=sm]/card:px-3 has-data-[slot=card-action]:grid-cols-[1fr_auto] has-data-[slot=card-description]:grid-rows-[auto_auto] [.border-b]:pb-4 group-data-[size=sm]/card:[.border-b]:pb-3',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+function CardTitle({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="card-title"
+			className={cn(
+				'font-heading text-base leading-snug font-medium group-data-[size=sm]/card:text-sm',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+function CardDescription({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="card-description"
+			className={cn('text-sm text-muted-foreground', className)}
+			{...props}
+		/>
+	);
+}
+
+function CardAction({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="card-action"
+			className={cn(
+				'col-start-2 row-span-2 row-start-1 self-start justify-self-end',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+function CardContent({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="card-content"
+			className={cn('px-4 group-data-[size=sm]/card:px-3', className)}
+			{...props}
+		/>
+	);
+}
+
+function CardFooter({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="card-footer"
+			className={cn(
+				'flex items-center rounded-b-xl border-t bg-muted/50 p-4 group-data-[size=sm]/card:p-3',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+export { Card, CardHeader, CardFooter, CardTitle, CardAction, CardDescription, CardContent };
diff --git a/examples/web_ui/frontend/src/components/ui/checkbox.tsx b/examples/web_ui/frontend/src/components/ui/checkbox.tsx
new file mode 100644
index 0000000..95be4ae
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/ui/checkbox.tsx
@@ -0,0 +1,27 @@
+import * as React from 'react';
+import { Checkbox as CheckboxPrimitive } from 'radix-ui';
+
+import { cn } from '@/lib/utils';
+import { CheckIcon } from 'lucide-react';
+
+function Checkbox({ className, ...props }: React.ComponentProps<typeof CheckboxPrimitive.Root>) {
+	return (
+		<CheckboxPrimitive.Root
+			data-slot="checkbox"
+			className={cn(
+				'peer relative flex size-4 shrink-0 items-center justify-center rounded-[4px] border border-input transition-colors outline-none group-has-disabled/field:opacity-50 after:absolute after:-inset-x-3 after:-inset-y-2 focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 aria-invalid:aria-checked:border-primary dark:bg-input/30 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 data-checked:border-primary data-checked:bg-primary data-checked:text-primary-foreground dark:data-checked:bg-primary',
+				className,
+			)}
+			{...props}
+		>
+			<CheckboxPrimitive.Indicator
+				data-slot="checkbox-indicator"
+				className="grid place-content-center text-current transition-none [&>svg]:size-3.5"
+			>
+				<CheckIcon />
+			</CheckboxPrimitive.Indicator>
+		</CheckboxPrimitive.Root>
+	);
+}
+
+export { Checkbox };
diff --git a/examples/web_ui/frontend/src/components/ui/collapsible.tsx b/examples/web_ui/frontend/src/components/ui/collapsible.tsx
new file mode 100644
index 0000000..4db5fc6
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/ui/collapsible.tsx
@@ -0,0 +1,19 @@
+import { Collapsible as CollapsiblePrimitive } from 'radix-ui';
+
+function Collapsible({ ...props }: React.ComponentProps<typeof CollapsiblePrimitive.Root>) {
+	return <CollapsiblePrimitive.Root data-slot="collapsible" {...props} />;
+}
+
+function CollapsibleTrigger({
+	...props
+}: React.ComponentProps<typeof CollapsiblePrimitive.CollapsibleTrigger>) {
+	return <CollapsiblePrimitive.CollapsibleTrigger data-slot="collapsible-trigger" {...props} />;
+}
+
+function CollapsibleContent({
+	...props
+}: React.ComponentProps<typeof CollapsiblePrimitive.CollapsibleContent>) {
+	return <CollapsiblePrimitive.CollapsibleContent data-slot="collapsible-content" {...props} />;
+}
+
+export { Collapsible, CollapsibleTrigger, CollapsibleContent };
diff --git a/examples/web_ui/frontend/src/components/ui/dialog.tsx b/examples/web_ui/frontend/src/components/ui/dialog.tsx
new file mode 100644
index 0000000..7cde926
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/ui/dialog.tsx
@@ -0,0 +1,147 @@
+import * as React from 'react';
+import { Dialog as DialogPrimitive } from 'radix-ui';
+
+import { cn } from '@/lib/utils';
+import { Button } from '@/components/ui/button';
+import { XIcon } from 'lucide-react';
+
+function Dialog({ ...props }: React.ComponentProps<typeof DialogPrimitive.Root>) {
+	return <DialogPrimitive.Root data-slot="dialog" {...props} />;
+}
+
+function DialogTrigger({ ...props }: React.ComponentProps<typeof DialogPrimitive.Trigger>) {
+	return <DialogPrimitive.Trigger data-slot="dialog-trigger" {...props} />;
+}
+
+function DialogPortal({ ...props }: React.ComponentProps<typeof DialogPrimitive.Portal>) {
+	return <DialogPrimitive.Portal data-slot="dialog-portal" {...props} />;
+}
+
+function DialogClose({ ...props }: React.ComponentProps<typeof DialogPrimitive.Close>) {
+	return <DialogPrimitive.Close data-slot="dialog-close" {...props} />;
+}
+
+function DialogOverlay({
+	className,
+	...props
+}: React.ComponentProps<typeof DialogPrimitive.Overlay>) {
+	return (
+		<DialogPrimitive.Overlay
+			data-slot="dialog-overlay"
+			className={cn(
+				'fixed inset-0 isolate z-50 bg-black/10 duration-100 supports-backdrop-filter:backdrop-blur-xs data-open:animate-in data-open:fade-in-0 data-closed:animate-out data-closed:fade-out-0',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+function DialogContent({
+	className,
+	children,
+	showCloseButton = true,
+	...props
+}: React.ComponentProps<typeof DialogPrimitive.Content> & {
+	showCloseButton?: boolean;
+}) {
+	return (
+		<DialogPortal>
+			<DialogOverlay />
+			<DialogPrimitive.Content
+				data-slot="dialog-content"
+				className={cn(
+					'fixed top-1/2 left-1/2 z-50 grid w-full max-w-[calc(100%-2rem)] -translate-x-1/2 -translate-y-1/2 gap-4 rounded-xl bg-popover p-4 text-sm text-popover-foreground ring-1 ring-foreground/10 duration-100 outline-none sm:max-w-sm data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95',
+					className,
+				)}
+				{...props}
+			>
+				{children}
+				{showCloseButton && (
+					<DialogPrimitive.Close data-slot="dialog-close" asChild>
+						<Button variant="ghost" className="absolute top-2 right-2" size="icon-sm">
+							<XIcon />
+							<span className="sr-only">Close</span>
+						</Button>
+					</DialogPrimitive.Close>
+				)}
+			</DialogPrimitive.Content>
+		</DialogPortal>
+	);
+}
+
+function DialogHeader({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="dialog-header"
+			className={cn('flex flex-col gap-2', className)}
+			{...props}
+		/>
+	);
+}
+
+function DialogFooter({
+	className,
+	showCloseButton = false,
+	children,
+	...props
+}: React.ComponentProps<'div'> & {
+	showCloseButton?: boolean;
+}) {
+	return (
+		<div
+			data-slot="dialog-footer"
+			className={cn(
+				'-mx-4 -mb-4 flex flex-col-reverse gap-2 rounded-b-xl border-t bg-muted/50 p-4 sm:flex-row sm:justify-end',
+				className,
+			)}
+			{...props}
+		>
+			{children}
+			{showCloseButton && (
+				<DialogPrimitive.Close asChild>
+					<Button variant="outline">Close</Button>
+				</DialogPrimitive.Close>
+			)}
+		</div>
+	);
+}
+
+function DialogTitle({ className, ...props }: React.ComponentProps<typeof DialogPrimitive.Title>) {
+	return (
+		<DialogPrimitive.Title
+			data-slot="dialog-title"
+			className={cn('font-heading text-base leading-none font-medium', className)}
+			{...props}
+		/>
+	);
+}
+
+function DialogDescription({
+	className,
+	...props
+}: React.ComponentProps<typeof DialogPrimitive.Description>) {
+	return (
+		<DialogPrimitive.Description
+			data-slot="dialog-description"
+			className={cn(
+				'text-sm text-muted-foreground *:[a]:underline *:[a]:underline-offset-3 *:[a]:hover:text-foreground',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+export {
+	Dialog,
+	DialogClose,
+	DialogContent,
+	DialogDescription,
+	DialogFooter,
+	DialogHeader,
+	DialogOverlay,
+	DialogPortal,
+	DialogTitle,
+	DialogTrigger,
+};
diff --git a/examples/web_ui/frontend/src/components/ui/drawer.tsx b/examples/web_ui/frontend/src/components/ui/drawer.tsx
new file mode 100644
index 0000000..d84d975
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/ui/drawer.tsx
@@ -0,0 +1,120 @@
+'use client';
+
+import * as React from 'react';
+import { Drawer as DrawerPrimitive } from 'vaul';
+
+import { cn } from '@/lib/utils';
+
+function Drawer({ ...props }: React.ComponentProps<typeof DrawerPrimitive.Root>) {
+	return <DrawerPrimitive.Root data-slot="drawer" {...props} />;
+}
+
+function DrawerTrigger({ ...props }: React.ComponentProps<typeof DrawerPrimitive.Trigger>) {
+	return <DrawerPrimitive.Trigger data-slot="drawer-trigger" {...props} />;
+}
+
+function DrawerPortal({ ...props }: React.ComponentProps<typeof DrawerPrimitive.Portal>) {
+	return <DrawerPrimitive.Portal data-slot="drawer-portal" {...props} />;
+}
+
+function DrawerClose({ ...props }: React.ComponentProps<typeof DrawerPrimitive.Close>) {
+	return <DrawerPrimitive.Close data-slot="drawer-close" {...props} />;
+}
+
+function DrawerOverlay({
+	className,
+	...props
+}: React.ComponentProps<typeof DrawerPrimitive.Overlay>) {
+	return (
+		<DrawerPrimitive.Overlay
+			data-slot="drawer-overlay"
+			className={cn(
+				'fixed inset-0 z-50 bg-black/10 supports-backdrop-filter:backdrop-blur-xs data-open:animate-in data-open:fade-in-0 data-closed:animate-out data-closed:fade-out-0',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+function DrawerContent({
+	className,
+	children,
+	...props
+}: React.ComponentProps<typeof DrawerPrimitive.Content>) {
+	return (
+		<DrawerPortal data-slot="drawer-portal">
+			<DrawerOverlay />
+			<DrawerPrimitive.Content
+				data-slot="drawer-content"
+				className={cn(
+					'group/drawer-content fixed z-50 flex h-auto flex-col bg-popover text-sm text-popover-foreground data-[vaul-drawer-direction=bottom]:inset-x-0 data-[vaul-drawer-direction=bottom]:bottom-0 data-[vaul-drawer-direction=bottom]:mt-24 data-[vaul-drawer-direction=bottom]:max-h-[80vh] data-[vaul-drawer-direction=bottom]:rounded-t-xl data-[vaul-drawer-direction=bottom]:border-t data-[vaul-drawer-direction=left]:inset-y-0 data-[vaul-drawer-direction=left]:left-0 data-[vaul-drawer-direction=left]:w-3/4 data-[vaul-drawer-direction=left]:rounded-r-xl data-[vaul-drawer-direction=left]:border-r data-[vaul-drawer-direction=right]:inset-y-0 data-[vaul-drawer-direction=right]:right-0 data-[vaul-drawer-direction=right]:w-3/4 data-[vaul-drawer-direction=right]:rounded-l-xl data-[vaul-drawer-direction=right]:border-l data-[vaul-drawer-direction=top]:inset-x-0 data-[vaul-drawer-direction=top]:top-0 data-[vaul-drawer-direction=top]:mb-24 data-[vaul-drawer-direction=top]:max-h-[80vh] data-[vaul-drawer-direction=top]:rounded-b-xl data-[vaul-drawer-direction=top]:border-b data-[vaul-drawer-direction=left]:sm:max-w-sm data-[vaul-drawer-direction=right]:sm:max-w-sm',
+					className,
+				)}
+				{...props}
+			>
+				<div className="mx-auto mt-4 hidden h-1 w-[100px] shrink-0 rounded-full bg-muted group-data-[vaul-drawer-direction=bottom]/drawer-content:block" />
+				{children}
+			</DrawerPrimitive.Content>
+		</DrawerPortal>
+	);
+}
+
+function DrawerHeader({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="drawer-header"
+			className={cn(
+				'flex flex-col gap-0.5 p-4 group-data-[vaul-drawer-direction=bottom]/drawer-content:text-center group-data-[vaul-drawer-direction=top]/drawer-content:text-center md:gap-0.5 md:text-left',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+function DrawerFooter({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="drawer-footer"
+			className={cn('mt-auto flex flex-col gap-2 p-4', className)}
+			{...props}
+		/>
+	);
+}
+
+function DrawerTitle({ className, ...props }: React.ComponentProps<typeof DrawerPrimitive.Title>) {
+	return (
+		<DrawerPrimitive.Title
+			data-slot="drawer-title"
+			className={cn('font-heading text-base font-medium text-foreground', className)}
+			{...props}
+		/>
+	);
+}
+
+function DrawerDescription({
+	className,
+	...props
+}: React.ComponentProps<typeof DrawerPrimitive.Description>) {
+	return (
+		<DrawerPrimitive.Description
+			data-slot="drawer-description"
+			className={cn('text-sm text-muted-foreground', className)}
+			{...props}
+		/>
+	);
+}
+
+export {
+	Drawer,
+	DrawerPortal,
+	DrawerOverlay,
+	DrawerTrigger,
+	DrawerClose,
+	DrawerContent,
+	DrawerHeader,
+	DrawerFooter,
+	DrawerTitle,
+	DrawerDescription,
+};
diff --git a/examples/web_ui/frontend/src/components/ui/dropdown-menu.tsx b/examples/web_ui/frontend/src/components/ui/dropdown-menu.tsx
new file mode 100644
index 0000000..be72735
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/ui/dropdown-menu.tsx
@@ -0,0 +1,248 @@
+import * as React from 'react';
+import { DropdownMenu as DropdownMenuPrimitive } from 'radix-ui';
+
+import { cn } from '@/lib/utils';
+import { CheckIcon, ChevronRightIcon } from 'lucide-react';
+
+function DropdownMenu({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Root>) {
+	return <DropdownMenuPrimitive.Root data-slot="dropdown-menu" {...props} />;
+}
+
+function DropdownMenuPortal({
+	...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Portal>) {
+	return <DropdownMenuPrimitive.Portal data-slot="dropdown-menu-portal" {...props} />;
+}
+
+function DropdownMenuTrigger({
+	...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Trigger>) {
+	return <DropdownMenuPrimitive.Trigger data-slot="dropdown-menu-trigger" {...props} />;
+}
+
+function DropdownMenuContent({
+	className,
+	align = 'start',
+	sideOffset = 4,
+	...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Content>) {
+	return (
+		<DropdownMenuPrimitive.Portal>
+			<DropdownMenuPrimitive.Content
+				data-slot="dropdown-menu-content"
+				sideOffset={sideOffset}
+				align={align}
+				className={cn(
+					'z-50 max-h-(--radix-dropdown-menu-content-available-height) w-(--radix-dropdown-menu-trigger-width) min-w-32 origin-(--radix-dropdown-menu-content-transform-origin) overflow-x-hidden overflow-y-auto rounded-lg bg-popover p-1 text-popover-foreground shadow-md ring-1 ring-foreground/10 duration-100 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-[state=closed]:overflow-hidden data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95',
+					className,
+				)}
+				{...props}
+			/>
+		</DropdownMenuPrimitive.Portal>
+	);
+}
+
+function DropdownMenuGroup({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Group>) {
+	return <DropdownMenuPrimitive.Group data-slot="dropdown-menu-group" {...props} />;
+}
+
+function DropdownMenuItem({
+	className,
+	inset,
+	variant = 'default',
+	...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Item> & {
+	inset?: boolean;
+	variant?: 'default' | 'destructive';
+}) {
+	return (
+		<DropdownMenuPrimitive.Item
+			data-slot="dropdown-menu-item"
+			data-inset={inset}
+			data-variant={variant}
+			className={cn(
+				"group/dropdown-menu-item relative flex cursor-default items-center gap-1.5 rounded-md px-1.5 py-1 text-sm outline-hidden select-none focus:bg-accent focus:text-accent-foreground not-data-[variant=destructive]:focus:**:text-accent-foreground data-inset:pl-7 data-[variant=destructive]:text-destructive data-[variant=destructive]:focus:bg-destructive/10 data-[variant=destructive]:focus:text-destructive dark:data-[variant=destructive]:focus:bg-destructive/20 data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 data-[variant=destructive]:*:[svg]:text-destructive",
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+function DropdownMenuCheckboxItem({
+	className,
+	children,
+	checked,
+	inset,
+	...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.CheckboxItem> & {
+	inset?: boolean;
+}) {
+	return (
+		<DropdownMenuPrimitive.CheckboxItem
+			data-slot="dropdown-menu-checkbox-item"
+			data-inset={inset}
+			className={cn(
+				"relative flex cursor-default items-center gap-1.5 rounded-md py-1 pr-8 pl-1.5 text-sm outline-hidden select-none focus:bg-accent focus:text-accent-foreground focus:**:text-accent-foreground data-inset:pl-7 data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+				className,
+			)}
+			checked={checked}
+			{...props}
+		>
+			<span
+				className="pointer-events-none absolute right-2 flex items-center justify-center"
+				data-slot="dropdown-menu-checkbox-item-indicator"
+			>
+				<DropdownMenuPrimitive.ItemIndicator>
+					<CheckIcon />
+				</DropdownMenuPrimitive.ItemIndicator>
+			</span>
+			{children}
+		</DropdownMenuPrimitive.CheckboxItem>
+	);
+}
+
+function DropdownMenuRadioGroup({
+	...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.RadioGroup>) {
+	return <DropdownMenuPrimitive.RadioGroup data-slot="dropdown-menu-radio-group" {...props} />;
+}
+
+function DropdownMenuRadioItem({
+	className,
+	children,
+	inset,
+	...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.RadioItem> & {
+	inset?: boolean;
+}) {
+	return (
+		<DropdownMenuPrimitive.RadioItem
+			data-slot="dropdown-menu-radio-item"
+			data-inset={inset}
+			className={cn(
+				"relative flex cursor-default items-center gap-1.5 rounded-md py-1 pr-8 pl-1.5 text-sm outline-hidden select-none focus:bg-accent focus:text-accent-foreground focus:**:text-accent-foreground data-inset:pl-7 data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+				className,
+			)}
+			{...props}
+		>
+			<span
+				className="pointer-events-none absolute right-2 flex items-center justify-center"
+				data-slot="dropdown-menu-radio-item-indicator"
+			>
+				<DropdownMenuPrimitive.ItemIndicator>
+					<CheckIcon />
+				</DropdownMenuPrimitive.ItemIndicator>
+			</span>
+			{children}
+		</DropdownMenuPrimitive.RadioItem>
+	);
+}
+
+function DropdownMenuLabel({
+	className,
+	inset,
+	...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Label> & {
+	inset?: boolean;
+}) {
+	return (
+		<DropdownMenuPrimitive.Label
+			data-slot="dropdown-menu-label"
+			data-inset={inset}
+			className={cn(
+				'px-1.5 py-1 text-xs font-medium text-muted-foreground data-inset:pl-7',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+function DropdownMenuSeparator({
+	className,
+	...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Separator>) {
+	return (
+		<DropdownMenuPrimitive.Separator
+			data-slot="dropdown-menu-separator"
+			className={cn('-mx-1 my-1 h-px bg-border', className)}
+			{...props}
+		/>
+	);
+}
+
+function DropdownMenuShortcut({ className, ...props }: React.ComponentProps<'span'>) {
+	return (
+		<span
+			data-slot="dropdown-menu-shortcut"
+			className={cn(
+				'ml-auto text-xs tracking-widest text-muted-foreground group-focus/dropdown-menu-item:text-accent-foreground',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+function DropdownMenuSub({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Sub>) {
+	return <DropdownMenuPrimitive.Sub data-slot="dropdown-menu-sub" {...props} />;
+}
+
+function DropdownMenuSubTrigger({
+	className,
+	inset,
+	children,
+	...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.SubTrigger> & {
+	inset?: boolean;
+}) {
+	return (
+		<DropdownMenuPrimitive.SubTrigger
+			data-slot="dropdown-menu-sub-trigger"
+			data-inset={inset}
+			className={cn(
+				"flex cursor-default items-center gap-1.5 rounded-md px-1.5 py-1 text-sm outline-hidden select-none focus:bg-accent focus:text-accent-foreground not-data-[variant=destructive]:focus:**:text-accent-foreground data-inset:pl-7 data-open:bg-accent data-open:text-accent-foreground [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+				className,
+			)}
+			{...props}
+		>
+			{children}
+			<ChevronRightIcon className="ml-auto" />
+		</DropdownMenuPrimitive.SubTrigger>
+	);
+}
+
+function DropdownMenuSubContent({
+	className,
+	...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.SubContent>) {
+	return (
+		<DropdownMenuPrimitive.SubContent
+			data-slot="dropdown-menu-sub-content"
+			className={cn(
+				'z-50 min-w-[96px] origin-(--radix-dropdown-menu-content-transform-origin) overflow-hidden rounded-lg bg-popover p-1 text-popover-foreground shadow-lg ring-1 ring-foreground/10 duration-100 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+export {
+	DropdownMenu,
+	DropdownMenuPortal,
+	DropdownMenuTrigger,
+	DropdownMenuContent,
+	DropdownMenuGroup,
+	DropdownMenuLabel,
+	DropdownMenuItem,
+	DropdownMenuCheckboxItem,
+	DropdownMenuRadioGroup,
+	DropdownMenuRadioItem,
+	DropdownMenuSeparator,
+	DropdownMenuShortcut,
+	DropdownMenuSub,
+	DropdownMenuSubTrigger,
+	DropdownMenuSubContent,
+};
diff --git a/examples/web_ui/frontend/src/components/ui/empty.tsx b/examples/web_ui/frontend/src/components/ui/empty.tsx
new file mode 100644
index 0000000..13df5f2
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/ui/empty.tsx
@@ -0,0 +1,94 @@
+import { cva, type VariantProps } from 'class-variance-authority';
+
+import { cn } from '@/lib/utils';
+
+function Empty({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="empty"
+			className={cn(
+				'flex w-full min-w-0 flex-1 flex-col items-center justify-center gap-4 rounded-xl border-dashed p-6 text-center text-balance',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+function EmptyHeader({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="empty-header"
+			className={cn('flex max-w-sm flex-col items-center gap-2', className)}
+			{...props}
+		/>
+	);
+}
+
+const emptyMediaVariants = cva(
+	'mb-2 flex shrink-0 items-center justify-center [&_svg]:pointer-events-none [&_svg]:shrink-0',
+	{
+		variants: {
+			variant: {
+				default: 'bg-transparent',
+				icon: "flex size-8 shrink-0 items-center justify-center rounded-lg bg-muted text-foreground [&_svg:not([class*='size-'])]:size-4",
+			},
+		},
+		defaultVariants: {
+			variant: 'default',
+		},
+	},
+);
+
+function EmptyMedia({
+	className,
+	variant = 'default',
+	...props
+}: React.ComponentProps<'div'> & VariantProps<typeof emptyMediaVariants>) {
+	return (
+		<div
+			data-slot="empty-icon"
+			data-variant={variant}
+			className={cn(emptyMediaVariants({ variant, className }))}
+			{...props}
+		/>
+	);
+}
+
+function EmptyTitle({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="empty-title"
+			className={cn('font-heading text-sm font-medium tracking-tight', className)}
+			{...props}
+		/>
+	);
+}
+
+function EmptyDescription({ className, ...props }: React.ComponentProps<'p'>) {
+	return (
+		<div
+			data-slot="empty-description"
+			className={cn(
+				'text-sm/relaxed text-muted-foreground [&>a]:underline [&>a]:underline-offset-4 [&>a:hover]:text-primary',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+function EmptyContent({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="empty-content"
+			className={cn(
+				'flex w-full max-w-sm min-w-0 flex-col items-center gap-2.5 text-sm text-balance',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+export { Empty, EmptyHeader, EmptyTitle, EmptyDescription, EmptyContent, EmptyMedia };
diff --git a/examples/web_ui/frontend/src/components/ui/field.tsx b/examples/web_ui/frontend/src/components/ui/field.tsx
new file mode 100644
index 0000000..67fb9ef
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/ui/field.tsx
@@ -0,0 +1,227 @@
+import { useMemo } from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+
+import { cn } from '@/lib/utils';
+import { Label } from '@/components/ui/label';
+import { Separator } from '@/components/ui/separator';
+
+function FieldSet({ className, ...props }: React.ComponentProps<'fieldset'>) {
+	return (
+		<fieldset
+			data-slot="field-set"
+			className={cn(
+				'flex flex-col gap-4 has-[>[data-slot=checkbox-group]]:gap-3 has-[>[data-slot=radio-group]]:gap-3',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+function FieldLegend({
+	className,
+	variant = 'legend',
+	...props
+}: React.ComponentProps<'legend'> & { variant?: 'legend' | 'label' }) {
+	return (
+		<legend
+			data-slot="field-legend"
+			data-variant={variant}
+			className={cn(
+				'mb-1.5 font-medium data-[variant=label]:text-sm data-[variant=legend]:text-base',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+function FieldGroup({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="field-group"
+			className={cn(
+				'group/field-group @container/field-group flex w-full flex-col gap-5 data-[slot=checkbox-group]:gap-3 *:data-[slot=field-group]:gap-4',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+const fieldVariants = cva('group/field flex w-full gap-2 data-[invalid=true]:text-destructive', {
+	variants: {
+		orientation: {
+			vertical: 'flex-col *:w-full [&>.sr-only]:w-auto',
+			horizontal:
+				'flex-row items-center has-[>[data-slot=field-content]]:items-start *:data-[slot=field-label]:flex-auto has-[>[data-slot=field-content]]:[&>[role=checkbox],[role=radio]]:mt-px',
+			responsive:
+				'flex-col *:w-full @md/field-group:flex-row @md/field-group:items-center @md/field-group:*:w-auto @md/field-group:has-[>[data-slot=field-content]]:items-start @md/field-group:*:data-[slot=field-label]:flex-auto [&>.sr-only]:w-auto @md/field-group:has-[>[data-slot=field-content]]:[&>[role=checkbox],[role=radio]]:mt-px',
+		},
+	},
+	defaultVariants: {
+		orientation: 'vertical',
+	},
+});
+
+function Field({
+	className,
+	orientation = 'vertical',
+	...props
+}: React.ComponentProps<'div'> & VariantProps<typeof fieldVariants>) {
+	return (
+		<div
+			role="group"
+			data-slot="field"
+			data-orientation={orientation}
+			className={cn(fieldVariants({ orientation }), className)}
+			{...props}
+		/>
+	);
+}
+
+function FieldContent({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="field-content"
+			className={cn(
+				'group/field-content flex flex-1 flex-col gap-0.5 leading-snug',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+function FieldLabel({ className, ...props }: React.ComponentProps<typeof Label>) {
+	return (
+		<Label
+			data-slot="field-label"
+			className={cn(
+				'group/field-label peer/field-label flex w-fit gap-2 leading-snug group-data-[disabled=true]/field:opacity-50 has-data-checked:border-primary/30 has-data-checked:bg-primary/5 has-[>[data-slot=field]]:rounded-lg has-[>[data-slot=field]]:border *:data-[slot=field]:p-2.5 dark:has-data-checked:border-primary/20 dark:has-data-checked:bg-primary/10',
+				'has-[>[data-slot=field]]:w-full has-[>[data-slot=field]]:flex-col',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+function FieldTitle({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="field-label"
+			className={cn(
+				'flex w-fit items-center gap-2 text-sm font-medium group-data-[disabled=true]/field:opacity-50',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+function FieldDescription({ className, ...props }: React.ComponentProps<'p'>) {
+	return (
+		<p
+			data-slot="field-description"
+			className={cn(
+				'text-left text-sm leading-normal font-normal text-muted-foreground group-has-data-horizontal/field:text-balance [[data-variant=legend]+&]:-mt-1.5',
+				'last:mt-0 nth-last-2:-mt-1',
+				'[&>a]:underline [&>a]:underline-offset-4 [&>a:hover]:text-primary',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+function FieldSeparator({
+	children,
+	className,
+	...props
+}: React.ComponentProps<'div'> & {
+	children?: React.ReactNode;
+}) {
+	return (
+		<div
+			data-slot="field-separator"
+			data-content={!!children}
+			className={cn(
+				'relative -my-2 h-5 text-sm group-data-[variant=outline]/field-group:-mb-2',
+				className,
+			)}
+			{...props}
+		>
+			<Separator className="absolute inset-0 top-1/2" />
+			{children && (
+				<span
+					className="relative mx-auto block w-fit bg-background px-2 text-muted-foreground"
+					data-slot="field-separator-content"
+				>
+					{children}
+				</span>
+			)}
+		</div>
+	);
+}
+
+function FieldError({
+	className,
+	children,
+	errors,
+	...props
+}: React.ComponentProps<'div'> & {
+	errors?: Array<{ message?: string } | undefined>;
+}) {
+	const content = useMemo(() => {
+		if (children) {
+			return children;
+		}
+
+		if (!errors?.length) {
+			return null;
+		}
+
+		const uniqueErrors = [...new Map(errors.map((error) => [error?.message, error])).values()];
+
+		if (uniqueErrors?.length == 1) {
+			return uniqueErrors[0]?.message;
+		}
+
+		return (
+			<ul className="ml-4 flex list-disc flex-col gap-1">
+				{uniqueErrors.map(
+					(error, index) => error?.message && <li key={index}>{error.message}</li>,
+				)}
+			</ul>
+		);
+	}, [children, errors]);
+
+	if (!content) {
+		return null;
+	}
+
+	return (
+		<div
+			role="alert"
+			data-slot="field-error"
+			className={cn('text-sm font-normal text-destructive', className)}
+			{...props}
+		>
+			{content}
+		</div>
+	);
+}
+
+export {
+	Field,
+	FieldLabel,
+	FieldDescription,
+	FieldError,
+	FieldGroup,
+	FieldLegend,
+	FieldSeparator,
+	FieldSet,
+	FieldContent,
+	FieldTitle,
+};
diff --git a/examples/web_ui/frontend/src/components/ui/input-group.tsx b/examples/web_ui/frontend/src/components/ui/input-group.tsx
new file mode 100644
index 0000000..c34d8c6
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/ui/input-group.tsx
@@ -0,0 +1,143 @@
+import * as React from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+
+import { cn } from '@/lib/utils';
+import { Button } from '@/components/ui/button';
+import { Input } from '@/components/ui/input';
+import { Textarea } from '@/components/ui/textarea';
+
+function InputGroup({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="input-group"
+			role="group"
+			className={cn(
+				'group/input-group relative flex h-8 w-full min-w-0 items-center rounded-lg border border-input transition-colors outline-none in-data-[slot=combobox-content]:focus-within:border-inherit in-data-[slot=combobox-content]:focus-within:ring-0 has-disabled:bg-input/50 has-disabled:opacity-50 has-[[data-slot=input-group-control]:focus-visible]:border-ring has-[[data-slot=input-group-control]:focus-visible]:ring-3 has-[[data-slot=input-group-control]:focus-visible]:ring-ring/50 has-[[data-slot][aria-invalid=true]]:border-destructive has-[[data-slot][aria-invalid=true]]:ring-3 has-[[data-slot][aria-invalid=true]]:ring-destructive/20 has-[>[data-align=block-end]]:h-auto has-[>[data-align=block-end]]:flex-col has-[>[data-align=block-start]]:h-auto has-[>[data-align=block-start]]:flex-col has-[>textarea]:h-auto dark:bg-input/30 dark:has-disabled:bg-input/80 dark:has-[[data-slot][aria-invalid=true]]:ring-destructive/40 has-[>[data-align=block-end]]:[&>input]:pt-3 has-[>[data-align=block-start]]:[&>input]:pb-3 has-[>[data-align=inline-end]]:[&>input]:pr-1.5 has-[>[data-align=inline-start]]:[&>input]:pl-1.5',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+const inputGroupAddonVariants = cva(
+	"flex h-auto cursor-text items-center justify-center gap-2 py-1.5 text-sm font-medium text-muted-foreground select-none group-data-[disabled=true]/input-group:opacity-50 [&>kbd]:rounded-[calc(var(--radius)-5px)] [&>svg:not([class*='size-'])]:size-4",
+	{
+		variants: {
+			align: {
+				'inline-start':
+					'order-first pl-2 has-[>button]:ml-[-0.3rem] has-[>kbd]:ml-[-0.15rem]',
+				'inline-end': 'order-last pr-2 has-[>button]:mr-[-0.3rem] has-[>kbd]:mr-[-0.15rem]',
+				'block-start':
+					'order-first w-full justify-start px-2.5 pt-2 group-has-[>input]/input-group:pt-2 [.border-b]:pb-2',
+				'block-end':
+					'order-last w-full justify-start px-2.5 pb-2 group-has-[>input]/input-group:pb-2 [.border-t]:pt-2',
+			},
+		},
+		defaultVariants: {
+			align: 'inline-start',
+		},
+	},
+);
+
+function InputGroupAddon({
+	className,
+	align = 'inline-start',
+	...props
+}: React.ComponentProps<'div'> & VariantProps<typeof inputGroupAddonVariants>) {
+	return (
+		<div
+			role="group"
+			data-slot="input-group-addon"
+			data-align={align}
+			className={cn(inputGroupAddonVariants({ align }), className)}
+			onClick={(e) => {
+				if ((e.target as HTMLElement).closest('button')) {
+					return;
+				}
+				e.currentTarget.parentElement?.querySelector('input')?.focus();
+			}}
+			{...props}
+		/>
+	);
+}
+
+const inputGroupButtonVariants = cva('flex items-center gap-2 text-sm shadow-none', {
+	variants: {
+		size: {
+			xs: "h-6 gap-1 rounded-[calc(var(--radius)-3px)] px-1.5 [&>svg:not([class*='size-'])]:size-3.5",
+			sm: '',
+			'icon-xs': 'size-6 rounded-[calc(var(--radius)-3px)] p-0 has-[>svg]:p-0',
+			'icon-sm': 'size-8 p-0 has-[>svg]:p-0',
+		},
+	},
+	defaultVariants: {
+		size: 'xs',
+	},
+});
+
+function InputGroupButton({
+	className,
+	type = 'button',
+	variant = 'ghost',
+	size = 'xs',
+	...props
+}: Omit<React.ComponentProps<typeof Button>, 'size'> &
+	VariantProps<typeof inputGroupButtonVariants>) {
+	return (
+		<Button
+			type={type}
+			data-size={size}
+			variant={variant}
+			className={cn(inputGroupButtonVariants({ size }), className)}
+			{...props}
+		/>
+	);
+}
+
+function InputGroupText({ className, ...props }: React.ComponentProps<'span'>) {
+	return (
+		<span
+			className={cn(
+				"flex items-center gap-2 text-sm text-muted-foreground [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4",
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+function InputGroupInput({ className, ...props }: React.ComponentProps<'input'>) {
+	return (
+		<Input
+			data-slot="input-group-control"
+			className={cn(
+				'flex-1 rounded-none border-0 bg-transparent shadow-none ring-0 focus-visible:ring-0 disabled:bg-transparent aria-invalid:ring-0 dark:bg-transparent dark:disabled:bg-transparent',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+function InputGroupTextarea({ className, ...props }: React.ComponentProps<'textarea'>) {
+	return (
+		<Textarea
+			data-slot="input-group-control"
+			className={cn(
+				'flex-1 resize-none rounded-none border-0 bg-transparent py-2 shadow-none ring-0 focus-visible:ring-0 disabled:bg-transparent aria-invalid:ring-0 dark:bg-transparent dark:disabled:bg-transparent',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+export {
+	InputGroup,
+	InputGroupAddon,
+	InputGroupButton,
+	InputGroupText,
+	InputGroupInput,
+	InputGroupTextarea,
+};
diff --git a/examples/web_ui/frontend/src/components/ui/input.tsx b/examples/web_ui/frontend/src/components/ui/input.tsx
new file mode 100644
index 0000000..a7378ae
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/ui/input.tsx
@@ -0,0 +1,19 @@
+import * as React from 'react';
+
+import { cn } from '@/lib/utils';
+
+function Input({ className, type, ...props }: React.ComponentProps<'input'>) {
+	return (
+		<input
+			type={type}
+			data-slot="input"
+			className={cn(
+				'h-8 w-full min-w-0 rounded-lg border border-input bg-transparent px-2.5 py-1 text-base transition-colors outline-none file:inline-flex file:h-6 file:border-0 file:bg-transparent file:text-sm file:font-medium file:text-foreground placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 disabled:pointer-events-none disabled:cursor-not-allowed disabled:bg-input/50 disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 md:text-sm dark:bg-input/30 dark:disabled:bg-input/80 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+export { Input };
diff --git a/examples/web_ui/frontend/src/components/ui/item.tsx b/examples/web_ui/frontend/src/components/ui/item.tsx
new file mode 100644
index 0000000..335cf61
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/ui/item.tsx
@@ -0,0 +1,185 @@
+import * as React from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { Slot } from 'radix-ui';
+
+import { cn } from '@/lib/utils';
+import { Separator } from '@/components/ui/separator';
+
+function ItemGroup({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			role="list"
+			data-slot="item-group"
+			className={cn(
+				'group/item-group flex w-full flex-col gap-4 has-data-[size=sm]:gap-2.5 has-data-[size=xs]:gap-2',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+function ItemSeparator({ className, ...props }: React.ComponentProps<typeof Separator>) {
+	return (
+		<Separator
+			data-slot="item-separator"
+			orientation="horizontal"
+			className={cn('my-2', className)}
+			{...props}
+		/>
+	);
+}
+
+const itemVariants = cva(
+	'group/item flex w-full flex-wrap items-center rounded-lg border text-sm transition-colors duration-100 outline-none focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 [a]:transition-colors [a]:hover:bg-muted',
+	{
+		variants: {
+			variant: {
+				default: 'border-transparent',
+				outline: 'border-border',
+				muted: 'border-transparent bg-muted/50',
+			},
+			size: {
+				default: 'gap-2.5 px-3 py-2.5',
+				sm: 'gap-2.5 px-3 py-2.5',
+				xs: 'gap-2 px-2.5 py-2 in-data-[slot=dropdown-menu-content]:p-0',
+			},
+		},
+		defaultVariants: {
+			variant: 'default',
+			size: 'default',
+		},
+	},
+);
+
+function Item({
+	className,
+	variant = 'default',
+	size = 'default',
+	asChild = false,
+	...props
+}: React.ComponentProps<'div'> & VariantProps<typeof itemVariants> & { asChild?: boolean }) {
+	const Comp = asChild ? Slot.Root : 'div';
+	return (
+		<Comp
+			data-slot="item"
+			data-variant={variant}
+			data-size={size}
+			className={cn(itemVariants({ variant, size, className }))}
+			{...props}
+		/>
+	);
+}
+
+const itemMediaVariants = cva(
+	'flex shrink-0 items-center justify-center gap-2 group-has-data-[slot=item-description]/item:translate-y-0.5 group-has-data-[slot=item-description]/item:self-start [&_svg]:pointer-events-none',
+	{
+		variants: {
+			variant: {
+				default: 'bg-transparent',
+				icon: "[&_svg:not([class*='size-'])]:size-4",
+				image: 'size-10 overflow-hidden rounded-sm group-data-[size=sm]/item:size-8 group-data-[size=xs]/item:size-6 [&_img]:size-full [&_img]:object-cover',
+			},
+		},
+		defaultVariants: {
+			variant: 'default',
+		},
+	},
+);
+
+function ItemMedia({
+	className,
+	variant = 'default',
+	...props
+}: React.ComponentProps<'div'> & VariantProps<typeof itemMediaVariants>) {
+	return (
+		<div
+			data-slot="item-media"
+			data-variant={variant}
+			className={cn(itemMediaVariants({ variant, className }))}
+			{...props}
+		/>
+	);
+}
+
+function ItemContent({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="item-content"
+			className={cn(
+				'flex flex-1 flex-col gap-1 group-data-[size=xs]/item:gap-0 [&+[data-slot=item-content]]:flex-none',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+function ItemTitle({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="item-title"
+			className={cn(
+				'line-clamp-1 flex w-fit items-center gap-2 text-sm leading-snug font-medium underline-offset-4',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+function ItemDescription({ className, ...props }: React.ComponentProps<'p'>) {
+	return (
+		<p
+			data-slot="item-description"
+			className={cn(
+				'line-clamp-2 text-left text-sm leading-normal font-normal text-muted-foreground group-data-[size=xs]/item:text-xs [&>a]:underline [&>a]:underline-offset-4 [&>a:hover]:text-primary',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+function ItemActions({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="item-actions"
+			className={cn('flex items-center gap-2', className)}
+			{...props}
+		/>
+	);
+}
+
+function ItemHeader({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="item-header"
+			className={cn('flex basis-full items-center justify-between gap-2', className)}
+			{...props}
+		/>
+	);
+}
+
+function ItemFooter({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="item-footer"
+			className={cn('flex basis-full items-center justify-between gap-2', className)}
+			{...props}
+		/>
+	);
+}
+
+export {
+	Item,
+	ItemMedia,
+	ItemContent,
+	ItemActions,
+	ItemGroup,
+	ItemSeparator,
+	ItemTitle,
+	ItemDescription,
+	ItemHeader,
+	ItemFooter,
+};
diff --git a/examples/web_ui/frontend/src/components/ui/kbd.tsx b/examples/web_ui/frontend/src/components/ui/kbd.tsx
new file mode 100644
index 0000000..2d871e6
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/ui/kbd.tsx
@@ -0,0 +1,26 @@
+import { cn } from '@/lib/utils';
+
+function Kbd({ className, ...props }: React.ComponentProps<'kbd'>) {
+	return (
+		<kbd
+			data-slot="kbd"
+			className={cn(
+				"pointer-events-none inline-flex h-5 w-fit min-w-5 items-center justify-center gap-1 rounded-sm bg-muted px-1 font-sans text-xs font-medium text-muted-foreground select-none in-data-[slot=tooltip-content]:bg-background/20 in-data-[slot=tooltip-content]:text-background dark:in-data-[slot=tooltip-content]:bg-background/10 [&_svg:not([class*='size-'])]:size-3",
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+function KbdGroup({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<kbd
+			data-slot="kbd-group"
+			className={cn('inline-flex items-center gap-1', className)}
+			{...props}
+		/>
+	);
+}
+
+export { Kbd, KbdGroup };
diff --git a/examples/web_ui/frontend/src/components/ui/label.tsx b/examples/web_ui/frontend/src/components/ui/label.tsx
new file mode 100644
index 0000000..52311de
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/ui/label.tsx
@@ -0,0 +1,19 @@
+import * as React from 'react';
+import { Label as LabelPrimitive } from 'radix-ui';
+
+import { cn } from '@/lib/utils';
+
+function Label({ className, ...props }: React.ComponentProps<typeof LabelPrimitive.Root>) {
+	return (
+		<LabelPrimitive.Root
+			data-slot="label"
+			className={cn(
+				'flex items-center gap-2 text-sm leading-none font-medium select-none group-data-[disabled=true]:pointer-events-none group-data-[disabled=true]:opacity-50 peer-disabled:cursor-not-allowed peer-disabled:opacity-50',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+export { Label };
diff --git a/examples/web_ui/frontend/src/components/ui/popover.tsx b/examples/web_ui/frontend/src/components/ui/popover.tsx
new file mode 100644
index 0000000..2808454
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/ui/popover.tsx
@@ -0,0 +1,72 @@
+import * as React from 'react';
+import { Popover as PopoverPrimitive } from 'radix-ui';
+
+import { cn } from '@/lib/utils';
+
+function Popover({ ...props }: React.ComponentProps<typeof PopoverPrimitive.Root>) {
+	return <PopoverPrimitive.Root data-slot="popover" {...props} />;
+}
+
+function PopoverTrigger({ ...props }: React.ComponentProps<typeof PopoverPrimitive.Trigger>) {
+	return <PopoverPrimitive.Trigger data-slot="popover-trigger" {...props} />;
+}
+
+function PopoverContent({
+	className,
+	align = 'center',
+	sideOffset = 4,
+	...props
+}: React.ComponentProps<typeof PopoverPrimitive.Content>) {
+	return (
+		<PopoverPrimitive.Portal>
+			<PopoverPrimitive.Content
+				data-slot="popover-content"
+				align={align}
+				sideOffset={sideOffset}
+				className={cn(
+					'z-50 flex w-72 origin-(--radix-popover-content-transform-origin) flex-col gap-2.5 rounded-lg bg-popover p-2.5 text-sm text-popover-foreground shadow-md ring-1 ring-foreground/10 outline-hidden duration-100 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95',
+					className,
+				)}
+				{...props}
+			/>
+		</PopoverPrimitive.Portal>
+	);
+}
+
+function PopoverAnchor({ ...props }: React.ComponentProps<typeof PopoverPrimitive.Anchor>) {
+	return <PopoverPrimitive.Anchor data-slot="popover-anchor" {...props} />;
+}
+
+function PopoverHeader({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="popover-header"
+			className={cn('flex flex-col gap-0.5 text-sm', className)}
+			{...props}
+		/>
+	);
+}
+
+function PopoverTitle({ className, ...props }: React.ComponentProps<'h2'>) {
+	return <div data-slot="popover-title" className={cn('font-medium', className)} {...props} />;
+}
+
+function PopoverDescription({ className, ...props }: React.ComponentProps<'p'>) {
+	return (
+		<p
+			data-slot="popover-description"
+			className={cn('text-muted-foreground', className)}
+			{...props}
+		/>
+	);
+}
+
+export {
+	Popover,
+	PopoverAnchor,
+	PopoverContent,
+	PopoverDescription,
+	PopoverHeader,
+	PopoverTitle,
+	PopoverTrigger,
+};
diff --git a/examples/web_ui/frontend/src/components/ui/resizable.tsx b/examples/web_ui/frontend/src/components/ui/resizable.tsx
new file mode 100644
index 0000000..f69f4a1
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/ui/resizable.tsx
@@ -0,0 +1,42 @@
+import * as ResizablePrimitive from 'react-resizable-panels';
+
+import { cn } from '@/lib/utils';
+
+function ResizablePanelGroup({ className, ...props }: ResizablePrimitive.GroupProps) {
+	return (
+		<ResizablePrimitive.Group
+			data-slot="resizable-panel-group"
+			className={cn('flex h-full w-full aria-[orientation=vertical]:flex-col', className)}
+			{...props}
+		/>
+	);
+}
+
+function ResizablePanel({ ...props }: ResizablePrimitive.PanelProps) {
+	return <ResizablePrimitive.Panel data-slot="resizable-panel" {...props} />;
+}
+
+function ResizableHandle({
+	withHandle,
+	className,
+	...props
+}: ResizablePrimitive.SeparatorProps & {
+	withHandle?: boolean;
+}) {
+	return (
+		<ResizablePrimitive.Separator
+			data-slot="resizable-handle"
+			className={cn(
+				'group relative flex w-px items-center justify-center bg-border ring-offset-background after:absolute after:inset-y-0 after:left-1/2 after:w-1 after:-translate-x-1/2 focus-visible:ring-1 focus-visible:ring-ring focus-visible:outline-hidden aria-[orientation=horizontal]:h-px aria-[orientation=horizontal]:w-full aria-[orientation=horizontal]:after:left-0 aria-[orientation=horizontal]:after:h-1 aria-[orientation=horizontal]:after:w-full aria-[orientation=horizontal]:after:translate-x-0 aria-[orientation=horizontal]:after:-translate-y-1/2 [&[aria-orientation=horizontal]>div]:rotate-90',
+				className,
+			)}
+			{...props}
+		>
+			{withHandle && (
+				<div className="z-10 flex h-6 w-1 shrink-0 rounded-lg bg-border opacity-0 transition-opacity duration-150 group-hover:opacity-100" />
+			)}
+		</ResizablePrimitive.Separator>
+	);
+}
+
+export { ResizableHandle, ResizablePanel, ResizablePanelGroup };
diff --git a/examples/web_ui/frontend/src/components/ui/select.tsx b/examples/web_ui/frontend/src/components/ui/select.tsx
new file mode 100644
index 0000000..4d8d80c
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/ui/select.tsx
@@ -0,0 +1,183 @@
+import * as React from 'react';
+import { Select as SelectPrimitive } from 'radix-ui';
+
+import { cn } from '@/lib/utils';
+import { ChevronDownIcon, CheckIcon, ChevronUpIcon } from 'lucide-react';
+
+function Select({ ...props }: React.ComponentProps<typeof SelectPrimitive.Root>) {
+	return <SelectPrimitive.Root data-slot="select" {...props} />;
+}
+
+function SelectGroup({ className, ...props }: React.ComponentProps<typeof SelectPrimitive.Group>) {
+	return (
+		<SelectPrimitive.Group
+			data-slot="select-group"
+			className={cn('scroll-my-1 p-1', className)}
+			{...props}
+		/>
+	);
+}
+
+function SelectValue({ ...props }: React.ComponentProps<typeof SelectPrimitive.Value>) {
+	return <SelectPrimitive.Value data-slot="select-value" {...props} />;
+}
+
+function SelectTrigger({
+	className,
+	size = 'default',
+	children,
+	...props
+}: React.ComponentProps<typeof SelectPrimitive.Trigger> & {
+	size?: 'sm' | 'default';
+}) {
+	return (
+		<SelectPrimitive.Trigger
+			data-slot="select-trigger"
+			data-size={size}
+			className={cn(
+				"flex w-fit items-center justify-between gap-1.5 rounded-lg border border-input bg-transparent py-2 pr-2 pl-2.5 text-sm whitespace-nowrap transition-colors outline-none select-none focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 data-placeholder:text-muted-foreground data-[size=default]:h-8 data-[size=sm]:h-7 data-[size=sm]:rounded-[min(var(--radius-md),10px)] *:data-[slot=select-value]:line-clamp-1 *:data-[slot=select-value]:flex *:data-[slot=select-value]:items-center *:data-[slot=select-value]:gap-1.5 dark:bg-input/30 dark:hover:bg-input/50 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+				className,
+			)}
+			{...props}
+		>
+			{children}
+			<SelectPrimitive.Icon asChild>
+				<ChevronDownIcon className="pointer-events-none size-4 text-muted-foreground" />
+			</SelectPrimitive.Icon>
+		</SelectPrimitive.Trigger>
+	);
+}
+
+function SelectContent({
+	className,
+	children,
+	position = 'item-aligned',
+	align = 'center',
+	...props
+}: React.ComponentProps<typeof SelectPrimitive.Content>) {
+	return (
+		<SelectPrimitive.Portal>
+			<SelectPrimitive.Content
+				data-slot="select-content"
+				data-align-trigger={position === 'item-aligned'}
+				className={cn(
+					'relative z-50 max-h-(--radix-select-content-available-height) min-w-36 origin-(--radix-select-content-transform-origin) overflow-x-hidden overflow-y-auto rounded-lg bg-popover text-popover-foreground shadow-md ring-1 ring-foreground/10 duration-100 data-[align-trigger=true]:animate-none data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95',
+					position === 'popper' &&
+						'data-[side=bottom]:translate-y-1 data-[side=left]:-translate-x-1 data-[side=right]:translate-x-1 data-[side=top]:-translate-y-1',
+					className,
+				)}
+				position={position}
+				align={align}
+				{...props}
+			>
+				<SelectScrollUpButton />
+				<SelectPrimitive.Viewport
+					data-position={position}
+					className={cn(
+						'data-[position=popper]:h-(--radix-select-trigger-height) data-[position=popper]:w-full data-[position=popper]:min-w-(--radix-select-trigger-width)',
+						position === 'popper' && '',
+					)}
+				>
+					{children}
+				</SelectPrimitive.Viewport>
+				<SelectScrollDownButton />
+			</SelectPrimitive.Content>
+		</SelectPrimitive.Portal>
+	);
+}
+
+function SelectLabel({ className, ...props }: React.ComponentProps<typeof SelectPrimitive.Label>) {
+	return (
+		<SelectPrimitive.Label
+			data-slot="select-label"
+			className={cn('px-1.5 py-1 text-xs text-muted-foreground', className)}
+			{...props}
+		/>
+	);
+}
+
+function SelectItem({
+	className,
+	children,
+	...props
+}: React.ComponentProps<typeof SelectPrimitive.Item>) {
+	return (
+		<SelectPrimitive.Item
+			data-slot="select-item"
+			className={cn(
+				"relative flex w-full cursor-default items-center gap-1.5 rounded-md py-1 pr-8 pl-1.5 text-sm outline-hidden select-none focus:bg-accent focus:text-accent-foreground not-data-[variant=destructive]:focus:**:text-accent-foreground data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 *:[span]:last:flex *:[span]:last:items-center *:[span]:last:gap-2",
+				className,
+			)}
+			{...props}
+		>
+			<span className="pointer-events-none absolute right-2 flex size-4 items-center justify-center">
+				<SelectPrimitive.ItemIndicator>
+					<CheckIcon className="pointer-events-none" />
+				</SelectPrimitive.ItemIndicator>
+			</span>
+			<SelectPrimitive.ItemText>{children}</SelectPrimitive.ItemText>
+		</SelectPrimitive.Item>
+	);
+}
+
+function SelectSeparator({
+	className,
+	...props
+}: React.ComponentProps<typeof SelectPrimitive.Separator>) {
+	return (
+		<SelectPrimitive.Separator
+			data-slot="select-separator"
+			className={cn('pointer-events-none -mx-1 my-1 h-px bg-border', className)}
+			{...props}
+		/>
+	);
+}
+
+function SelectScrollUpButton({
+	className,
+	...props
+}: React.ComponentProps<typeof SelectPrimitive.ScrollUpButton>) {
+	return (
+		<SelectPrimitive.ScrollUpButton
+			data-slot="select-scroll-up-button"
+			className={cn(
+				"z-10 flex cursor-default items-center justify-center bg-popover py-1 [&_svg:not([class*='size-'])]:size-4",
+				className,
+			)}
+			{...props}
+		>
+			<ChevronUpIcon />
+		</SelectPrimitive.ScrollUpButton>
+	);
+}
+
+function SelectScrollDownButton({
+	className,
+	...props
+}: React.ComponentProps<typeof SelectPrimitive.ScrollDownButton>) {
+	return (
+		<SelectPrimitive.ScrollDownButton
+			data-slot="select-scroll-down-button"
+			className={cn(
+				"z-10 flex cursor-default items-center justify-center bg-popover py-1 [&_svg:not([class*='size-'])]:size-4",
+				className,
+			)}
+			{...props}
+		>
+			<ChevronDownIcon />
+		</SelectPrimitive.ScrollDownButton>
+	);
+}
+
+export {
+	Select,
+	SelectContent,
+	SelectGroup,
+	SelectItem,
+	SelectLabel,
+	SelectScrollDownButton,
+	SelectScrollUpButton,
+	SelectSeparator,
+	SelectTrigger,
+	SelectValue,
+};
diff --git a/examples/web_ui/frontend/src/components/ui/separator.tsx b/examples/web_ui/frontend/src/components/ui/separator.tsx
new file mode 100644
index 0000000..c36614f
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/ui/separator.tsx
@@ -0,0 +1,28 @@
+'use client';
+
+import * as React from 'react';
+import { Separator as SeparatorPrimitive } from 'radix-ui';
+
+import { cn } from '@/lib/utils';
+
+function Separator({
+	className,
+	orientation = 'horizontal',
+	decorative = true,
+	...props
+}: React.ComponentProps<typeof SeparatorPrimitive.Root>) {
+	return (
+		<SeparatorPrimitive.Root
+			data-slot="separator"
+			decorative={decorative}
+			orientation={orientation}
+			className={cn(
+				'shrink-0 bg-border data-horizontal:h-px data-horizontal:w-full data-vertical:w-px data-vertical:self-stretch',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+export { Separator };
diff --git a/examples/web_ui/frontend/src/components/ui/sheet.tsx b/examples/web_ui/frontend/src/components/ui/sheet.tsx
new file mode 100644
index 0000000..9d019da
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/ui/sheet.tsx
@@ -0,0 +1,128 @@
+import * as React from 'react';
+import { Dialog as SheetPrimitive } from 'radix-ui';
+
+import { cn } from '@/lib/utils';
+import { Button } from '@/components/ui/button';
+import { XIcon } from 'lucide-react';
+
+function Sheet({ ...props }: React.ComponentProps<typeof SheetPrimitive.Root>) {
+	return <SheetPrimitive.Root data-slot="sheet" {...props} />;
+}
+
+function SheetTrigger({ ...props }: React.ComponentProps<typeof SheetPrimitive.Trigger>) {
+	return <SheetPrimitive.Trigger data-slot="sheet-trigger" {...props} />;
+}
+
+function SheetClose({ ...props }: React.ComponentProps<typeof SheetPrimitive.Close>) {
+	return <SheetPrimitive.Close data-slot="sheet-close" {...props} />;
+}
+
+function SheetPortal({ ...props }: React.ComponentProps<typeof SheetPrimitive.Portal>) {
+	return <SheetPrimitive.Portal data-slot="sheet-portal" {...props} />;
+}
+
+function SheetOverlay({
+	className,
+	...props
+}: React.ComponentProps<typeof SheetPrimitive.Overlay>) {
+	return (
+		<SheetPrimitive.Overlay
+			data-slot="sheet-overlay"
+			className={cn(
+				'fixed inset-0 z-50 bg-black/10 duration-100 supports-backdrop-filter:backdrop-blur-xs data-open:animate-in data-open:fade-in-0 data-closed:animate-out data-closed:fade-out-0',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+function SheetContent({
+	className,
+	children,
+	side = 'right',
+	showCloseButton = true,
+	...props
+}: React.ComponentProps<typeof SheetPrimitive.Content> & {
+	side?: 'top' | 'right' | 'bottom' | 'left';
+	showCloseButton?: boolean;
+}) {
+	return (
+		<SheetPortal>
+			<SheetOverlay />
+			<SheetPrimitive.Content
+				data-slot="sheet-content"
+				data-side={side}
+				className={cn(
+					'fixed z-50 flex flex-col gap-4 bg-popover bg-clip-padding text-sm text-popover-foreground shadow-lg transition duration-200 ease-in-out data-[side=bottom]:inset-x-0 data-[side=bottom]:bottom-0 data-[side=bottom]:h-auto data-[side=bottom]:border-t data-[side=left]:inset-y-0 data-[side=left]:left-0 data-[side=left]:h-full data-[side=left]:w-3/4 data-[side=left]:border-r data-[side=right]:inset-y-0 data-[side=right]:right-0 data-[side=right]:h-full data-[side=right]:w-3/4 data-[side=right]:border-l data-[side=top]:inset-x-0 data-[side=top]:top-0 data-[side=top]:h-auto data-[side=top]:border-b data-[side=left]:sm:max-w-sm data-[side=right]:sm:max-w-sm data-open:animate-in data-open:fade-in-0 data-[side=bottom]:data-open:slide-in-from-bottom-10 data-[side=left]:data-open:slide-in-from-left-10 data-[side=right]:data-open:slide-in-from-right-10 data-[side=top]:data-open:slide-in-from-top-10 data-closed:animate-out data-closed:fade-out-0 data-[side=bottom]:data-closed:slide-out-to-bottom-10 data-[side=left]:data-closed:slide-out-to-left-10 data-[side=right]:data-closed:slide-out-to-right-10 data-[side=top]:data-closed:slide-out-to-top-10',
+					className,
+				)}
+				{...props}
+			>
+				{children}
+				{showCloseButton && (
+					<SheetPrimitive.Close data-slot="sheet-close" asChild>
+						<Button variant="ghost" className="absolute top-3 right-3" size="icon-sm">
+							<XIcon />
+							<span className="sr-only">Close</span>
+						</Button>
+					</SheetPrimitive.Close>
+				)}
+			</SheetPrimitive.Content>
+		</SheetPortal>
+	);
+}
+
+function SheetHeader({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="sheet-header"
+			className={cn('flex flex-col gap-0.5 p-4', className)}
+			{...props}
+		/>
+	);
+}
+
+function SheetFooter({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="sheet-footer"
+			className={cn('mt-auto flex flex-col gap-2 p-4', className)}
+			{...props}
+		/>
+	);
+}
+
+function SheetTitle({ className, ...props }: React.ComponentProps<typeof SheetPrimitive.Title>) {
+	return (
+		<SheetPrimitive.Title
+			data-slot="sheet-title"
+			className={cn('font-heading text-base font-medium text-foreground', className)}
+			{...props}
+		/>
+	);
+}
+
+function SheetDescription({
+	className,
+	...props
+}: React.ComponentProps<typeof SheetPrimitive.Description>) {
+	return (
+		<SheetPrimitive.Description
+			data-slot="sheet-description"
+			className={cn('text-sm text-muted-foreground', className)}
+			{...props}
+		/>
+	);
+}
+
+export {
+	Sheet,
+	SheetTrigger,
+	SheetClose,
+	SheetContent,
+	SheetHeader,
+	SheetFooter,
+	SheetTitle,
+	SheetDescription,
+};
diff --git a/examples/web_ui/frontend/src/components/ui/sidebar.tsx b/examples/web_ui/frontend/src/components/ui/sidebar.tsx
new file mode 100644
index 0000000..13415de
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/ui/sidebar.tsx
@@ -0,0 +1,673 @@
+'use client';
+
+import * as React from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { Slot } from 'radix-ui';
+
+import { useIsMobile } from '@/hooks/use-mobile';
+import { cn } from '@/lib/utils';
+import { Button } from '@/components/ui/button';
+import { Input } from '@/components/ui/input';
+import { Separator } from '@/components/ui/separator';
+import {
+	Sheet,
+	SheetContent,
+	SheetDescription,
+	SheetHeader,
+	SheetTitle,
+} from '@/components/ui/sheet';
+import { Skeleton } from '@/components/ui/skeleton';
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip';
+import { PanelLeftIcon } from 'lucide-react';
+
+const SIDEBAR_COOKIE_NAME = 'sidebar_state';
+const SIDEBAR_COOKIE_MAX_AGE = 60 * 60 * 24 * 7;
+const SIDEBAR_WIDTH = '16rem';
+const SIDEBAR_WIDTH_MOBILE = '18rem';
+const SIDEBAR_WIDTH_ICON = '3rem';
+const SIDEBAR_KEYBOARD_SHORTCUT = 'b';
+
+type SidebarContextProps = {
+	state: 'expanded' | 'collapsed';
+	open: boolean;
+	setOpen: (open: boolean) => void;
+	openMobile: boolean;
+	setOpenMobile: (open: boolean) => void;
+	isMobile: boolean;
+	toggleSidebar: () => void;
+};
+
+const SidebarContext = React.createContext<SidebarContextProps | null>(null);
+
+function useSidebar() {
+	const context = React.useContext(SidebarContext);
+	if (!context) {
+		throw new Error('useSidebar must be used within a SidebarProvider.');
+	}
+
+	return context;
+}
+
+function SidebarProvider({
+	defaultOpen = true,
+	open: openProp,
+	onOpenChange: setOpenProp,
+	className,
+	style,
+	children,
+	...props
+}: React.ComponentProps<'div'> & {
+	defaultOpen?: boolean;
+	open?: boolean;
+	onOpenChange?: (open: boolean) => void;
+}) {
+	const isMobile = useIsMobile();
+	const [openMobile, setOpenMobile] = React.useState(false);
+
+	// This is the internal state of the sidebar.
+	// We use openProp and setOpenProp for control from outside the component.
+	const [_open, _setOpen] = React.useState(defaultOpen);
+	const open = openProp ?? _open;
+	const setOpen = React.useCallback(
+		(value: boolean | ((value: boolean) => boolean)) => {
+			const openState = typeof value === 'function' ? value(open) : value;
+			if (setOpenProp) {
+				setOpenProp(openState);
+			} else {
+				_setOpen(openState);
+			}
+
+			// This sets the cookie to keep the sidebar state.
+			document.cookie = `${SIDEBAR_COOKIE_NAME}=${openState}; path=/; max-age=${SIDEBAR_COOKIE_MAX_AGE}`;
+		},
+		[setOpenProp, open],
+	);
+
+	// Helper to toggle the sidebar.
+	const toggleSidebar = React.useCallback(() => {
+		return isMobile ? setOpenMobile((open) => !open) : setOpen((open) => !open);
+	}, [isMobile, setOpen, setOpenMobile]);
+
+	// Adds a keyboard shortcut to toggle the sidebar.
+	React.useEffect(() => {
+		const handleKeyDown = (event: KeyboardEvent) => {
+			if (event.key === SIDEBAR_KEYBOARD_SHORTCUT && (event.metaKey || event.ctrlKey)) {
+				event.preventDefault();
+				toggleSidebar();
+			}
+		};
+
+		window.addEventListener('keydown', handleKeyDown);
+		return () => window.removeEventListener('keydown', handleKeyDown);
+	}, [toggleSidebar]);
+
+	// We add a state so that we can do data-state="expanded" or "collapsed".
+	// This makes it easier to style the sidebar with Tailwind classes.
+	const state = open ? 'expanded' : 'collapsed';
+
+	const contextValue = React.useMemo<SidebarContextProps>(
+		() => ({
+			state,
+			open,
+			setOpen,
+			isMobile,
+			openMobile,
+			setOpenMobile,
+			toggleSidebar,
+		}),
+		[state, open, setOpen, isMobile, openMobile, setOpenMobile, toggleSidebar],
+	);
+
+	return (
+		<SidebarContext.Provider value={contextValue}>
+			<div
+				data-slot="sidebar-wrapper"
+				style={
+					{
+						'--sidebar-width': SIDEBAR_WIDTH,
+						'--sidebar-width-icon': SIDEBAR_WIDTH_ICON,
+						...style,
+					} as React.CSSProperties
+				}
+				className={cn(
+					'group/sidebar-wrapper flex min-h-svh w-full has-data-[variant=inset]:bg-sidebar',
+					className,
+				)}
+				{...props}
+			>
+				{children}
+			</div>
+		</SidebarContext.Provider>
+	);
+}
+
+function Sidebar({
+	side = 'left',
+	variant = 'sidebar',
+	collapsible = 'offcanvas',
+	className,
+	children,
+	dir,
+	...props
+}: React.ComponentProps<'div'> & {
+	side?: 'left' | 'right';
+	variant?: 'sidebar' | 'floating' | 'inset';
+	collapsible?: 'offcanvas' | 'icon' | 'none';
+}) {
+	const { isMobile, state, openMobile, setOpenMobile } = useSidebar();
+
+	if (collapsible === 'none') {
+		return (
+			<div
+				data-slot="sidebar"
+				className={cn(
+					'flex h-full w-(--sidebar-width) flex-col bg-sidebar text-sidebar-foreground',
+					className,
+				)}
+				{...props}
+			>
+				{children}
+			</div>
+		);
+	}
+
+	if (isMobile) {
+		return (
+			<Sheet open={openMobile} onOpenChange={setOpenMobile} {...props}>
+				<SheetContent
+					dir={dir}
+					data-sidebar="sidebar"
+					data-slot="sidebar"
+					data-mobile="true"
+					className="w-(--sidebar-width) bg-sidebar p-0 text-sidebar-foreground [&>button]:hidden"
+					style={
+						{
+							'--sidebar-width': SIDEBAR_WIDTH_MOBILE,
+						} as React.CSSProperties
+					}
+					side={side}
+				>
+					<SheetHeader className="sr-only">
+						<SheetTitle>Sidebar</SheetTitle>
+						<SheetDescription>Displays the mobile sidebar.</SheetDescription>
+					</SheetHeader>
+					<div className="flex h-full w-full flex-col">{children}</div>
+				</SheetContent>
+			</Sheet>
+		);
+	}
+
+	return (
+		<div
+			className="group peer hidden text-sidebar-foreground md:block"
+			data-state={state}
+			data-collapsible={state === 'collapsed' ? collapsible : ''}
+			data-variant={variant}
+			data-side={side}
+			data-slot="sidebar"
+		>
+			{/* This is what handles the sidebar gap on desktop */}
+			<div
+				data-slot="sidebar-gap"
+				className={cn(
+					'relative w-(--sidebar-width) bg-transparent transition-[width] duration-200 ease-linear',
+					'group-data-[collapsible=offcanvas]:w-0',
+					'group-data-[side=right]:rotate-180',
+					variant === 'floating' || variant === 'inset'
+						? 'group-data-[collapsible=icon]:w-[calc(var(--sidebar-width-icon)+(--spacing(4)))]'
+						: 'group-data-[collapsible=icon]:w-(--sidebar-width-icon)',
+				)}
+			/>
+			<div
+				data-slot="sidebar-container"
+				data-side={side}
+				className={cn(
+					'fixed inset-y-0 z-10 hidden h-svh w-(--sidebar-width) transition-[left,right,width] duration-200 ease-linear data-[side=left]:left-0 data-[side=left]:group-data-[collapsible=offcanvas]:left-[calc(var(--sidebar-width)*-1)] data-[side=right]:right-0 data-[side=right]:group-data-[collapsible=offcanvas]:right-[calc(var(--sidebar-width)*-1)] md:flex',
+					// Adjust the padding for floating and inset variants.
+					variant === 'floating' || variant === 'inset'
+						? 'p-2 group-data-[collapsible=icon]:w-[calc(var(--sidebar-width-icon)+(--spacing(4))+2px)]'
+						: 'group-data-[collapsible=icon]:w-(--sidebar-width-icon) group-data-[side=left]:border-r group-data-[side=right]:border-l',
+					className,
+				)}
+				{...props}
+			>
+				<div
+					data-sidebar="sidebar"
+					data-slot="sidebar-inner"
+					className="flex size-full flex-col bg-sidebar group-data-[variant=floating]:rounded-lg group-data-[variant=floating]:shadow-sm group-data-[variant=floating]:ring-1 group-data-[variant=floating]:ring-sidebar-border"
+				>
+					{children}
+				</div>
+			</div>
+		</div>
+	);
+}
+
+function SidebarTrigger({ className, onClick, ...props }: React.ComponentProps<typeof Button>) {
+	const { toggleSidebar } = useSidebar();
+
+	return (
+		<Button
+			data-sidebar="trigger"
+			data-slot="sidebar-trigger"
+			variant="ghost"
+			size="icon-sm"
+			className={cn(className)}
+			onClick={(event) => {
+				onClick?.(event);
+				toggleSidebar();
+			}}
+			{...props}
+		>
+			<PanelLeftIcon />
+			<span className="sr-only">Toggle Sidebar</span>
+		</Button>
+	);
+}
+
+function SidebarRail({ className, ...props }: React.ComponentProps<'button'>) {
+	const { toggleSidebar } = useSidebar();
+
+	return (
+		<button
+			data-sidebar="rail"
+			data-slot="sidebar-rail"
+			aria-label="Toggle Sidebar"
+			tabIndex={-1}
+			onClick={toggleSidebar}
+			title="Toggle Sidebar"
+			className={cn(
+				'absolute inset-y-0 z-20 hidden w-4 transition-all ease-linear group-data-[side=left]:-right-4 group-data-[side=right]:left-0 after:absolute after:inset-y-0 after:start-1/2 after:w-[2px] hover:after:bg-sidebar-border sm:flex ltr:-translate-x-1/2 rtl:-translate-x-1/2',
+				'in-data-[side=left]:cursor-w-resize in-data-[side=right]:cursor-e-resize',
+				'[[data-side=left][data-state=collapsed]_&]:cursor-e-resize [[data-side=right][data-state=collapsed]_&]:cursor-w-resize',
+				'group-data-[collapsible=offcanvas]:translate-x-0 group-data-[collapsible=offcanvas]:after:left-full hover:group-data-[collapsible=offcanvas]:bg-sidebar',
+				'[[data-side=left][data-collapsible=offcanvas]_&]:-right-2',
+				'[[data-side=right][data-collapsible=offcanvas]_&]:-left-2',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+function SidebarInset({ className, ...props }: React.ComponentProps<'main'>) {
+	return (
+		<main
+			data-slot="sidebar-inset"
+			className={cn(
+				'relative flex w-full flex-1 flex-col bg-background md:peer-data-[variant=inset]:m-2 md:peer-data-[variant=inset]:ml-0 md:peer-data-[variant=inset]:rounded-xl md:peer-data-[variant=inset]:shadow-sm md:peer-data-[variant=inset]:peer-data-[state=collapsed]:ml-2',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+function SidebarInput({ className, ...props }: React.ComponentProps<typeof Input>) {
+	return (
+		<Input
+			data-slot="sidebar-input"
+			data-sidebar="input"
+			className={cn('h-8 w-full bg-background shadow-none', className)}
+			{...props}
+		/>
+	);
+}
+
+function SidebarHeader({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="sidebar-header"
+			data-sidebar="header"
+			className={cn('flex flex-col gap-2 p-2', className)}
+			{...props}
+		/>
+	);
+}
+
+function SidebarFooter({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="sidebar-footer"
+			data-sidebar="footer"
+			className={cn('flex flex-col gap-2 p-2', className)}
+			{...props}
+		/>
+	);
+}
+
+function SidebarSeparator({ className, ...props }: React.ComponentProps<typeof Separator>) {
+	return (
+		<Separator
+			data-slot="sidebar-separator"
+			data-sidebar="separator"
+			className={cn('mx-2 w-auto bg-sidebar-border', className)}
+			{...props}
+		/>
+	);
+}
+
+function SidebarContent({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="sidebar-content"
+			data-sidebar="content"
+			className={cn(
+				'no-scrollbar flex min-h-0 flex-1 flex-col gap-0 overflow-auto group-data-[collapsible=icon]:overflow-hidden',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+function SidebarGroup({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="sidebar-group"
+			data-sidebar="group"
+			className={cn('relative flex w-full min-w-0 flex-col p-2', className)}
+			{...props}
+		/>
+	);
+}
+
+function SidebarGroupLabel({
+	className,
+	asChild = false,
+	...props
+}: React.ComponentProps<'div'> & { asChild?: boolean }) {
+	const Comp = asChild ? Slot.Root : 'div';
+
+	return (
+		<Comp
+			data-slot="sidebar-group-label"
+			data-sidebar="group-label"
+			className={cn(
+				'flex h-8 shrink-0 items-center rounded-md px-2 text-xs font-medium text-sidebar-foreground/70 ring-sidebar-ring outline-hidden transition-[margin,opacity] duration-200 ease-linear group-data-[collapsible=icon]:-mt-8 group-data-[collapsible=icon]:opacity-0 focus-visible:ring-2 [&>svg]:size-4 [&>svg]:shrink-0',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+function SidebarGroupAction({
+	className,
+	asChild = false,
+	...props
+}: React.ComponentProps<'button'> & { asChild?: boolean }) {
+	const Comp = asChild ? Slot.Root : 'button';
+
+	return (
+		<Comp
+			data-slot="sidebar-group-action"
+			data-sidebar="group-action"
+			className={cn(
+				'absolute top-3.5 right-3 flex aspect-square w-5 items-center justify-center rounded-md p-0 text-sidebar-foreground ring-sidebar-ring outline-hidden transition-transform group-data-[collapsible=icon]:hidden after:absolute after:-inset-2 hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2 md:after:hidden [&>svg]:size-4 [&>svg]:shrink-0',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+function SidebarGroupContent({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="sidebar-group-content"
+			data-sidebar="group-content"
+			className={cn('w-full text-sm', className)}
+			{...props}
+		/>
+	);
+}
+
+function SidebarMenu({ className, ...props }: React.ComponentProps<'ul'>) {
+	return (
+		<ul
+			data-slot="sidebar-menu"
+			data-sidebar="menu"
+			className={cn('flex w-full min-w-0 flex-col gap-y-1', className)}
+			{...props}
+		/>
+	);
+}
+
+function SidebarMenuItem({ className, ...props }: React.ComponentProps<'li'>) {
+	return (
+		<li
+			data-slot="sidebar-menu-item"
+			data-sidebar="menu-item"
+			className={cn('group/menu-item relative', className)}
+			{...props}
+		/>
+	);
+}
+
+const sidebarMenuButtonVariants = cva(
+	'peer/menu-button group/menu-button flex w-full items-center gap-2 overflow-hidden rounded-md p-2 text-left text-sm ring-sidebar-ring outline-hidden transition-[width,height,padding] group-has-data-[sidebar=menu-action]/menu-item:pr-8 group-data-[collapsible=icon]:size-8! group-data-[collapsible=icon]:p-2! hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2 active:bg-sidebar-accent active:text-sidebar-accent-foreground disabled:pointer-events-none disabled:opacity-50 aria-disabled:pointer-events-none aria-disabled:opacity-50 data-open:hover:bg-sidebar-accent data-open:hover:text-sidebar-accent-foreground data-active:bg-sidebar-accent data-active:font-medium data-active:text-sidebar-accent-foreground [&_svg]:size-4 [&_svg]:shrink-0 [&>span:last-child]:truncate',
+	{
+		variants: {
+			variant: {
+				default: 'hover:bg-sidebar-accent hover:text-sidebar-accent-foreground',
+				outline:
+					'bg-background shadow-[0_0_0_1px_var(--sidebar-border)] hover:bg-sidebar-accent hover:text-sidebar-accent-foreground hover:shadow-[0_0_0_1px_var(--sidebar-accent)]',
+			},
+			size: {
+				default: 'h-8 text-sm',
+				sm: 'h-7 text-xs',
+				lg: 'h-12 text-sm group-data-[collapsible=icon]:p-0!',
+			},
+		},
+		defaultVariants: {
+			variant: 'default',
+			size: 'default',
+		},
+	},
+);
+
+function SidebarMenuButton({
+	asChild = false,
+	isActive = false,
+	variant = 'default',
+	size = 'default',
+	tooltip,
+	className,
+	...props
+}: React.ComponentProps<'button'> & {
+	asChild?: boolean;
+	isActive?: boolean;
+	tooltip?: string | React.ComponentProps<typeof TooltipContent>;
+} & VariantProps<typeof sidebarMenuButtonVariants>) {
+	const Comp = asChild ? Slot.Root : 'button';
+	const { isMobile, state } = useSidebar();
+
+	const button = (
+		<Comp
+			data-slot="sidebar-menu-button"
+			data-sidebar="menu-button"
+			data-size={size}
+			data-active={isActive}
+			className={cn(sidebarMenuButtonVariants({ variant, size }), className)}
+			{...props}
+		/>
+	);
+
+	if (!tooltip) {
+		return button;
+	}
+
+	if (typeof tooltip === 'string') {
+		tooltip = {
+			children: tooltip,
+		};
+	}
+
+	return (
+		<Tooltip>
+			<TooltipTrigger asChild>{button}</TooltipTrigger>
+			<TooltipContent
+				side="right"
+				align="center"
+				hidden={state !== 'collapsed' || isMobile}
+				{...tooltip}
+			/>
+		</Tooltip>
+	);
+}
+
+function SidebarMenuAction({
+	className,
+	asChild = false,
+	showOnHover = false,
+	...props
+}: React.ComponentProps<'button'> & {
+	asChild?: boolean;
+	showOnHover?: boolean;
+}) {
+	const Comp = asChild ? Slot.Root : 'button';
+
+	return (
+		<Comp
+			data-slot="sidebar-menu-action"
+			data-sidebar="menu-action"
+			className={cn(
+				'absolute top-1.5 right-1 flex aspect-square w-5 items-center justify-center rounded-md p-0 text-sidebar-foreground ring-sidebar-ring outline-hidden transition-transform group-data-[collapsible=icon]:hidden peer-hover/menu-button:text-sidebar-accent-foreground peer-data-[size=default]/menu-button:top-1.5 peer-data-[size=lg]/menu-button:top-2.5 peer-data-[size=sm]/menu-button:top-1 after:absolute after:-inset-2 hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2 md:after:hidden [&>svg]:size-4 [&>svg]:shrink-0',
+				showOnHover &&
+					'group-focus-within/menu-item:opacity-100 group-hover/menu-item:opacity-100 peer-data-active/menu-button:text-sidebar-accent-foreground aria-expanded:opacity-100 md:opacity-0',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+function SidebarMenuBadge({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="sidebar-menu-badge"
+			data-sidebar="menu-badge"
+			className={cn(
+				'pointer-events-none absolute right-1 flex h-5 min-w-5 items-center justify-center rounded-md px-1 text-xs font-medium text-sidebar-foreground tabular-nums select-none group-data-[collapsible=icon]:hidden peer-hover/menu-button:text-sidebar-accent-foreground peer-data-[size=default]/menu-button:top-1.5 peer-data-[size=lg]/menu-button:top-2.5 peer-data-[size=sm]/menu-button:top-1 peer-data-active/menu-button:text-sidebar-accent-foreground',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+function SidebarMenuSkeleton({
+	className,
+	showIcon = false,
+	...props
+}: React.ComponentProps<'div'> & {
+	showIcon?: boolean;
+}) {
+	// Random width between 50 to 90%.
+	const [width] = React.useState(() => {
+		return `${Math.floor(Math.random() * 40) + 50}%`;
+	});
+
+	return (
+		<div
+			data-slot="sidebar-menu-skeleton"
+			data-sidebar="menu-skeleton"
+			className={cn('flex h-8 items-center gap-2 rounded-md px-2', className)}
+			{...props}
+		>
+			{showIcon && (
+				<Skeleton className="size-4 rounded-md" data-sidebar="menu-skeleton-icon" />
+			)}
+			<Skeleton
+				className="h-4 max-w-(--skeleton-width) flex-1"
+				data-sidebar="menu-skeleton-text"
+				style={
+					{
+						'--skeleton-width': width,
+					} as React.CSSProperties
+				}
+			/>
+		</div>
+	);
+}
+
+function SidebarMenuSub({ className, ...props }: React.ComponentProps<'ul'>) {
+	return (
+		<ul
+			data-slot="sidebar-menu-sub"
+			data-sidebar="menu-sub"
+			className={cn(
+				'mx-3.5 flex min-w-0 translate-x-px flex-col gap-1 border-l border-sidebar-border px-2.5 py-0.5 group-data-[collapsible=icon]:hidden',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+function SidebarMenuSubItem({ className, ...props }: React.ComponentProps<'li'>) {
+	return (
+		<li
+			data-slot="sidebar-menu-sub-item"
+			data-sidebar="menu-sub-item"
+			className={cn('group/menu-sub-item relative', className)}
+			{...props}
+		/>
+	);
+}
+
+function SidebarMenuSubButton({
+	asChild = false,
+	size = 'md',
+	isActive = false,
+	className,
+	...props
+}: React.ComponentProps<'a'> & {
+	asChild?: boolean;
+	size?: 'sm' | 'md';
+	isActive?: boolean;
+}) {
+	const Comp = asChild ? Slot.Root : 'a';
+
+	return (
+		<Comp
+			data-slot="sidebar-menu-sub-button"
+			data-sidebar="menu-sub-button"
+			data-size={size}
+			data-active={isActive}
+			className={cn(
+				'flex h-7 min-w-0 -translate-x-px items-center gap-2 overflow-hidden rounded-md px-2 text-sidebar-foreground ring-sidebar-ring outline-hidden group-data-[collapsible=icon]:hidden hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2 active:bg-sidebar-accent active:text-sidebar-accent-foreground disabled:pointer-events-none disabled:opacity-50 aria-disabled:pointer-events-none aria-disabled:opacity-50 data-[size=md]:text-sm data-[size=sm]:text-xs data-active:bg-sidebar-accent data-active:text-sidebar-accent-foreground [&>span:last-child]:truncate [&>svg]:size-4 [&>svg]:shrink-0 [&>svg]:text-sidebar-accent-foreground',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+export {
+	Sidebar,
+	SidebarContent,
+	SidebarFooter,
+	SidebarGroup,
+	SidebarGroupAction,
+	SidebarGroupContent,
+	SidebarGroupLabel,
+	SidebarHeader,
+	SidebarInput,
+	SidebarInset,
+	SidebarMenu,
+	SidebarMenuAction,
+	SidebarMenuBadge,
+	SidebarMenuButton,
+	SidebarMenuItem,
+	SidebarMenuSkeleton,
+	SidebarMenuSub,
+	SidebarMenuSubButton,
+	SidebarMenuSubItem,
+	SidebarProvider,
+	SidebarRail,
+	SidebarSeparator,
+	SidebarTrigger,
+	useSidebar,
+};
diff --git a/examples/web_ui/frontend/src/components/ui/skeleton.tsx b/examples/web_ui/frontend/src/components/ui/skeleton.tsx
new file mode 100644
index 0000000..08d25b0
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/ui/skeleton.tsx
@@ -0,0 +1,13 @@
+import { cn } from '@/lib/utils';
+
+function Skeleton({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="skeleton"
+			className={cn('animate-pulse rounded-md bg-muted', className)}
+			{...props}
+		/>
+	);
+}
+
+export { Skeleton };
diff --git a/examples/web_ui/frontend/src/components/ui/sonner.tsx b/examples/web_ui/frontend/src/components/ui/sonner.tsx
new file mode 100644
index 0000000..54c6e72
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/ui/sonner.tsx
@@ -0,0 +1,43 @@
+import { useTheme } from 'next-themes';
+import { Toaster as Sonner, type ToasterProps } from 'sonner';
+import {
+	CircleCheckIcon,
+	InfoIcon,
+	TriangleAlertIcon,
+	OctagonXIcon,
+	Loader2Icon,
+} from 'lucide-react';
+
+const Toaster = ({ ...props }: ToasterProps) => {
+	const { theme = 'system' } = useTheme();
+
+	return (
+		<Sonner
+			theme={theme as ToasterProps['theme']}
+			className="toaster group"
+			icons={{
+				success: <CircleCheckIcon className="size-4" />,
+				info: <InfoIcon className="size-4" />,
+				warning: <TriangleAlertIcon className="size-4" />,
+				error: <OctagonXIcon className="size-4" />,
+				loading: <Loader2Icon className="size-4 animate-spin" />,
+			}}
+			style={
+				{
+					'--normal-bg': 'var(--popover)',
+					'--normal-text': 'var(--popover-foreground)',
+					'--normal-border': 'var(--border)',
+					'--border-radius': 'var(--radius)',
+				} as React.CSSProperties
+			}
+			toastOptions={{
+				classNames: {
+					toast: 'cn-toast',
+				},
+			}}
+			{...props}
+		/>
+	);
+};
+
+export { Toaster };
diff --git a/examples/web_ui/frontend/src/components/ui/spinner.tsx b/examples/web_ui/frontend/src/components/ui/spinner.tsx
new file mode 100644
index 0000000..5510dca
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/ui/spinner.tsx
@@ -0,0 +1,15 @@
+import { cn } from '@/lib/utils';
+import { Loader2Icon } from 'lucide-react';
+
+function Spinner({ className, ...props }: React.ComponentProps<'svg'>) {
+	return (
+		<Loader2Icon
+			role="status"
+			aria-label="Loading"
+			className={cn('size-4 animate-spin', className)}
+			{...props}
+		/>
+	);
+}
+
+export { Spinner };
diff --git a/examples/web_ui/frontend/src/components/ui/switch.tsx b/examples/web_ui/frontend/src/components/ui/switch.tsx
new file mode 100644
index 0000000..83412df
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/ui/switch.tsx
@@ -0,0 +1,31 @@
+import * as React from 'react';
+import { Switch as SwitchPrimitive } from 'radix-ui';
+
+import { cn } from '@/lib/utils';
+
+function Switch({
+	className,
+	size = 'default',
+	...props
+}: React.ComponentProps<typeof SwitchPrimitive.Root> & {
+	size?: 'sm' | 'default';
+}) {
+	return (
+		<SwitchPrimitive.Root
+			data-slot="switch"
+			data-size={size}
+			className={cn(
+				'peer group/switch relative inline-flex shrink-0 items-center rounded-full border border-transparent transition-all outline-none after:absolute after:-inset-x-3 after:-inset-y-2 focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 data-[size=default]:h-[18.4px] data-[size=default]:w-[32px] data-[size=sm]:h-[14px] data-[size=sm]:w-[24px] dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 data-checked:bg-primary data-unchecked:bg-input dark:data-unchecked:bg-input/80 data-disabled:cursor-not-allowed data-disabled:opacity-50',
+				className,
+			)}
+			{...props}
+		>
+			<SwitchPrimitive.Thumb
+				data-slot="switch-thumb"
+				className="pointer-events-none block rounded-full bg-background ring-0 transition-transform group-data-[size=default]/switch:size-4 group-data-[size=sm]/switch:size-3 group-data-[size=default]/switch:data-checked:translate-x-[calc(100%-2px)] group-data-[size=sm]/switch:data-checked:translate-x-[calc(100%-2px)] dark:data-checked:bg-primary-foreground group-data-[size=default]/switch:data-unchecked:translate-x-0 group-data-[size=sm]/switch:data-unchecked:translate-x-0 dark:data-unchecked:bg-foreground"
+			/>
+		</SwitchPrimitive.Root>
+	);
+}
+
+export { Switch };
diff --git a/examples/web_ui/frontend/src/components/ui/tabs.tsx b/examples/web_ui/frontend/src/components/ui/tabs.tsx
new file mode 100644
index 0000000..976701b
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/ui/tabs.tsx
@@ -0,0 +1,78 @@
+import * as React from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { Tabs as TabsPrimitive } from 'radix-ui';
+
+import { cn } from '@/lib/utils';
+
+function Tabs({
+	className,
+	orientation = 'horizontal',
+	...props
+}: React.ComponentProps<typeof TabsPrimitive.Root>) {
+	return (
+		<TabsPrimitive.Root
+			data-slot="tabs"
+			data-orientation={orientation}
+			className={cn('group/tabs flex gap-2 data-horizontal:flex-col', className)}
+			{...props}
+		/>
+	);
+}
+
+const tabsListVariants = cva(
+	'group/tabs-list inline-flex w-fit items-center justify-center rounded-lg p-[3px] text-muted-foreground group-data-horizontal/tabs:h-8 group-data-vertical/tabs:h-fit group-data-vertical/tabs:flex-col data-[variant=line]:rounded-none',
+	{
+		variants: {
+			variant: {
+				default: 'bg-muted',
+				line: 'gap-1 bg-transparent',
+			},
+		},
+		defaultVariants: {
+			variant: 'default',
+		},
+	},
+);
+
+function TabsList({
+	className,
+	variant = 'default',
+	...props
+}: React.ComponentProps<typeof TabsPrimitive.List> & VariantProps<typeof tabsListVariants>) {
+	return (
+		<TabsPrimitive.List
+			data-slot="tabs-list"
+			data-variant={variant}
+			className={cn(tabsListVariants({ variant }), className)}
+			{...props}
+		/>
+	);
+}
+
+function TabsTrigger({ className, ...props }: React.ComponentProps<typeof TabsPrimitive.Trigger>) {
+	return (
+		<TabsPrimitive.Trigger
+			data-slot="tabs-trigger"
+			className={cn(
+				"relative inline-flex h-[calc(100%-1px)] flex-1 items-center justify-center gap-1.5 rounded-md border border-transparent px-1.5 py-0.5 text-sm font-medium whitespace-nowrap text-foreground/60 transition-all group-data-vertical/tabs:w-full group-data-vertical/tabs:justify-start hover:text-foreground focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 focus-visible:outline-1 focus-visible:outline-ring disabled:pointer-events-none disabled:opacity-50 has-data-[icon=inline-end]:pr-1 has-data-[icon=inline-start]:pl-1 dark:text-muted-foreground dark:hover:text-foreground group-data-[variant=default]/tabs-list:data-active:shadow-sm group-data-[variant=line]/tabs-list:data-active:shadow-none [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+				'group-data-[variant=line]/tabs-list:bg-transparent group-data-[variant=line]/tabs-list:data-active:bg-transparent dark:group-data-[variant=line]/tabs-list:data-active:border-transparent dark:group-data-[variant=line]/tabs-list:data-active:bg-transparent',
+				'data-active:bg-background data-active:text-foreground dark:data-active:border-input dark:data-active:bg-input/30 dark:data-active:text-foreground',
+				'after:absolute after:bg-foreground after:opacity-0 after:transition-opacity group-data-horizontal/tabs:after:inset-x-0 group-data-horizontal/tabs:after:bottom-[-5px] group-data-horizontal/tabs:after:h-0.5 group-data-vertical/tabs:after:inset-y-0 group-data-vertical/tabs:after:-right-1 group-data-vertical/tabs:after:w-0.5 group-data-[variant=line]/tabs-list:data-active:after:opacity-100',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+function TabsContent({ className, ...props }: React.ComponentProps<typeof TabsPrimitive.Content>) {
+	return (
+		<TabsPrimitive.Content
+			data-slot="tabs-content"
+			className={cn('flex-1 text-sm outline-none', className)}
+			{...props}
+		/>
+	);
+}
+
+export { Tabs, TabsList, TabsTrigger, TabsContent, tabsListVariants };
diff --git a/examples/web_ui/frontend/src/components/ui/textarea.tsx b/examples/web_ui/frontend/src/components/ui/textarea.tsx
new file mode 100644
index 0000000..590c9c8
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/ui/textarea.tsx
@@ -0,0 +1,18 @@
+import * as React from 'react';
+
+import { cn } from '@/lib/utils';
+
+function Textarea({ className, ...props }: React.ComponentProps<'textarea'>) {
+	return (
+		<textarea
+			data-slot="textarea"
+			className={cn(
+				'flex field-sizing-content min-h-16 w-full rounded-lg border border-input bg-transparent px-2.5 py-2 text-base transition-colors outline-none placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:bg-input/50 disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 md:text-sm dark:bg-input/30 dark:disabled:bg-input/80 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40',
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+export { Textarea };
diff --git a/examples/web_ui/frontend/src/components/ui/toggle.tsx b/examples/web_ui/frontend/src/components/ui/toggle.tsx
new file mode 100644
index 0000000..e3ed360
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/ui/toggle.tsx
@@ -0,0 +1,44 @@
+import * as React from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { Toggle as TogglePrimitive } from 'radix-ui';
+
+import { cn } from '@/lib/utils';
+
+const toggleVariants = cva(
+	"group/toggle inline-flex items-center justify-center gap-1 rounded-lg text-sm font-medium whitespace-nowrap transition-all outline-none hover:bg-muted hover:text-foreground focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 aria-pressed:bg-muted data-[state=on]:bg-muted dark:aria-invalid:ring-destructive/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+	{
+		variants: {
+			variant: {
+				default: 'bg-transparent',
+				outline: 'border border-input bg-transparent hover:bg-muted',
+			},
+			size: {
+				default:
+					'h-8 min-w-8 px-2.5 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2',
+				sm: "h-7 min-w-7 rounded-[min(var(--radius-md),12px)] px-2.5 text-[0.8rem] has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 [&_svg:not([class*='size-'])]:size-3.5",
+				lg: 'h-9 min-w-9 px-2.5 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2',
+			},
+		},
+		defaultVariants: {
+			variant: 'default',
+			size: 'default',
+		},
+	},
+);
+
+function Toggle({
+	className,
+	variant = 'default',
+	size = 'default',
+	...props
+}: React.ComponentProps<typeof TogglePrimitive.Root> & VariantProps<typeof toggleVariants>) {
+	return (
+		<TogglePrimitive.Root
+			data-slot="toggle"
+			className={cn(toggleVariants({ variant, size, className }))}
+			{...props}
+		/>
+	);
+}
+
+export { Toggle, toggleVariants };
diff --git a/examples/web_ui/frontend/src/components/ui/tooltip.tsx b/examples/web_ui/frontend/src/components/ui/tooltip.tsx
new file mode 100644
index 0000000..86f7cdb
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/ui/tooltip.tsx
@@ -0,0 +1,53 @@
+'use client';
+
+import * as React from 'react';
+import { Tooltip as TooltipPrimitive } from 'radix-ui';
+
+import { cn } from '@/lib/utils';
+
+function TooltipProvider({
+	delayDuration = 0,
+	...props
+}: React.ComponentProps<typeof TooltipPrimitive.Provider>) {
+	return (
+		<TooltipPrimitive.Provider
+			data-slot="tooltip-provider"
+			delayDuration={delayDuration}
+			{...props}
+		/>
+	);
+}
+
+function Tooltip({ ...props }: React.ComponentProps<typeof TooltipPrimitive.Root>) {
+	return <TooltipPrimitive.Root data-slot="tooltip" {...props} />;
+}
+
+function TooltipTrigger({ ...props }: React.ComponentProps<typeof TooltipPrimitive.Trigger>) {
+	return <TooltipPrimitive.Trigger data-slot="tooltip-trigger" {...props} />;
+}
+
+function TooltipContent({
+	className,
+	sideOffset = 0,
+	children,
+	...props
+}: React.ComponentProps<typeof TooltipPrimitive.Content>) {
+	return (
+		<TooltipPrimitive.Portal>
+			<TooltipPrimitive.Content
+				data-slot="tooltip-content"
+				sideOffset={sideOffset}
+				className={cn(
+					'z-50 inline-flex w-fit max-w-xs origin-(--radix-tooltip-content-transform-origin) items-center gap-1.5 rounded-md bg-foreground px-3 py-1.5 text-xs text-background has-data-[slot=kbd]:pr-1.5 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 **:data-[slot=kbd]:relative **:data-[slot=kbd]:isolate **:data-[slot=kbd]:z-50 **:data-[slot=kbd]:rounded-sm data-[state=delayed-open]:animate-in data-[state=delayed-open]:fade-in-0 data-[state=delayed-open]:zoom-in-95 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95',
+					className,
+				)}
+				{...props}
+			>
+				{children}
+				<TooltipPrimitive.Arrow className="z-50 size-2.5 translate-y-[calc(-50%_-_2px)] rotate-45 rounded-[2px] bg-foreground fill-foreground" />
+			</TooltipPrimitive.Content>
+		</TooltipPrimitive.Portal>
+	);
+}
+
+export { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger };
diff --git a/examples/web_ui/frontend/src/context/AudioContext.tsx b/examples/web_ui/frontend/src/context/AudioContext.tsx
new file mode 100644
index 0000000..6f9036a
--- /dev/null
+++ b/examples/web_ui/frontend/src/context/AudioContext.tsx
@@ -0,0 +1,86 @@
+import { createContext, useContext, useEffect, useMemo, useRef, useSyncExternalStore } from 'react';
+import type { ReactNode } from 'react';
+
+import { StreamingAudioManager } from '@/utils/streamingAudio';
+import type { StreamingAudioState } from '@/utils/streamingAudio';
+
+const AudioContext = createContext<StreamingAudioManager | null>(null);
+
+interface ReplayController {
+	play: (el: HTMLAudioElement) => void;
+	stop: () => void;
+}
+
+const ReplayContext = createContext<ReplayController | null>(null);
+
+/**
+ * Provides a {@link StreamingAudioManager} to the component tree. The manager
+ * collects DATA_BLOCK_* events for audio blocks and exposes per-block state
+ * that ``MessageBubble`` consumes via {@link useAudioBlock}.
+ *
+ * Mount this once around any subtree that renders assistant messages.
+ */
+export function AudioProvider({ children }: { children: ReactNode }) {
+	const manager = useMemo(() => new StreamingAudioManager(), []);
+	useEffect(() => () => manager.disposeAll(), [manager]);
+
+	const currentRef = useRef<HTMLAudioElement | null>(null);
+	const replay: ReplayController = useMemo(
+		() => ({
+			play(el: HTMLAudioElement) {
+				manager.stopLivePlayback();
+				if (currentRef.current && currentRef.current !== el) {
+					currentRef.current.pause();
+					currentRef.current.currentTime = 0;
+				}
+				currentRef.current = el;
+			},
+			stop() {
+				currentRef.current = null;
+			},
+		}),
+		[manager],
+	);
+
+	return (
+		<AudioContext.Provider value={manager}>
+			<ReplayContext.Provider value={replay}>{children}</ReplayContext.Provider>
+		</AudioContext.Provider>
+	);
+}
+
+/**
+ * Access the streaming audio manager. Returns ``null`` outside of an
+ * ``AudioProvider`` — callers must handle that, since audio handling is
+ * an optional feature.
+ */
+export function useAudioManager(): StreamingAudioManager | null {
+	return useContext(AudioContext);
+}
+
+/**
+ * Access the replay controller that ensures only one audio element plays
+ * at a time across all message bubbles.
+ */
+export function useReplayController(): ReplayController | null {
+	return useContext(ReplayContext);
+}
+
+/**
+ * Subscribe to the streaming state for a single audio DataBlock.
+ * Re-renders when the block transitions from ``streaming`` to ``ready``.
+ *
+ * Returns ``null`` if the block isn't being tracked (e.g. a historical
+ * message loaded from the server, where the bytes are already complete).
+ */
+export function useAudioBlock(blockId: string | undefined): StreamingAudioState | null {
+	const manager = useAudioManager();
+	return useSyncExternalStore(
+		(fn) => {
+			if (!manager || !blockId) return () => undefined;
+			return manager.subscribe(blockId, fn);
+		},
+		() => (manager && blockId ? manager.getState(blockId) : null),
+		() => null,
+	);
+}
diff --git a/examples/web_ui/frontend/src/context/UploadContext.tsx b/examples/web_ui/frontend/src/context/UploadContext.tsx
new file mode 100644
index 0000000..db9943d
--- /dev/null
+++ b/examples/web_ui/frontend/src/context/UploadContext.tsx
@@ -0,0 +1,421 @@
+import {
+	createContext,
+	useCallback,
+	useContext,
+	useEffect,
+	useMemo,
+	useReducer,
+	useRef,
+	type ReactNode,
+} from 'react';
+
+import { MAX_CONCURRENT_UPLOADS, isTerminal, type UploadTask } from './uploadTypes';
+import { knowledgeBaseApi } from '@/api';
+import type { KnowledgeDocumentStatus } from '@/api';
+
+/**
+ * Public contract the surrounding app sees. Exposed via the React
+ * context value.
+ */
+interface UploadContextValue {
+	tasks: UploadTask[];
+	/** Enqueue one or more files against a knowledge base. */
+	enqueue: (knowledgeBaseId: string, files: File[]) => UploadTask[];
+	/**
+	 * Abort an upload task. Effects depend on the current phase:
+	 *
+	 * - `queued` — removed from the queue.
+	 * - `uploading` — XHR is aborted, then the task transitions to
+	 *   `cancelled`.
+	 * - server-side phases — no-op (the worker has already taken over;
+	 *   route through the regular document-delete flow instead).
+	 * - terminal phases — equivalent to `dismiss`.
+	 */
+	cancel: (taskId: string) => void;
+	/** Drop a terminal task from the list (UI dismissal). */
+	dismiss: (taskId: string) => void;
+	/** Drop every terminal task for a knowledge base. */
+	clearFinishedForKb: (knowledgeBaseId: string) => void;
+	/**
+	 * Filtered tasks for a knowledge base id. Cached by reference per
+	 * (knowledgeBaseId, tasks-list-identity) so consumers can pass it
+	 * straight into React dependency arrays.
+	 */
+	tasksForKb: (knowledgeBaseId: string) => UploadTask[];
+	/**
+	 * Apply server-side status snapshots from the polling hook.
+	 * Lookup is keyed by `documentId`; tasks without a documentId
+	 * (still uploading) are skipped.
+	 */
+	applyServerStatuses: (
+		knowledgeBaseId: string,
+		items: Array<{
+			id: string;
+			status: KnowledgeDocumentStatus;
+			error: string | null;
+		}>,
+	) => void;
+	/**
+	 * Document ids the consumer should be polling. Filtered to tasks
+	 * that have a documentId AND a non-terminal server-side phase.
+	 */
+	pollableDocumentIds: (knowledgeBaseId: string) => string[];
+}
+
+const UploadContext = createContext<UploadContextValue | null>(null);
+
+// ───────── Reducer ────────────────────────────────────────────────────
+
+type Action =
+	| { type: 'ADD'; tasks: UploadTask[] }
+	| { type: 'START_UPLOAD'; taskId: string }
+	| { type: 'PROGRESS'; taskId: string; loaded: number; total: number }
+	| {
+			type: 'UPLOAD_DONE';
+			taskId: string;
+			documentId: string;
+			status: KnowledgeDocumentStatus;
+	  }
+	| { type: 'UPLOAD_FAILED'; taskId: string; error: string }
+	| { type: 'CANCEL'; taskId: string }
+	| { type: 'REMOVE'; taskId: string }
+	| {
+			type: 'SERVER_STATUS';
+			knowledgeBaseId: string;
+			items: Array<{
+				id: string;
+				status: KnowledgeDocumentStatus;
+				error: string | null;
+			}>;
+	  }
+	| { type: 'CLEAR_FINISHED'; knowledgeBaseId: string };
+
+function reducer(state: UploadTask[], action: Action): UploadTask[] {
+	switch (action.type) {
+		case 'ADD':
+			return [...state, ...action.tasks];
+		case 'START_UPLOAD':
+			return state.map((t) =>
+				t.taskId === action.taskId ? { ...t, phase: 'uploading', loaded: 0 } : t,
+			);
+		case 'PROGRESS':
+			return state.map((t) =>
+				t.taskId === action.taskId
+					? {
+							...t,
+							loaded: action.loaded,
+							// Allow upload progress to refine an unknown size
+							// (browser couldn't compute it at enqueue time).
+							size: t.size || action.total,
+						}
+					: t,
+			);
+		case 'UPLOAD_DONE':
+			return state.map((t) =>
+				t.taskId === action.taskId
+					? {
+							...t,
+							documentId: action.documentId,
+							phase: action.status,
+							loaded: t.size,
+						}
+					: t,
+			);
+		case 'UPLOAD_FAILED':
+			return state.map((t) =>
+				t.taskId === action.taskId ? { ...t, phase: 'error', error: action.error } : t,
+			);
+		case 'CANCEL':
+			return state.map((t) =>
+				t.taskId === action.taskId ? { ...t, phase: 'cancelled' } : t,
+			);
+		case 'REMOVE':
+			return state.filter((t) => t.taskId !== action.taskId);
+		case 'SERVER_STATUS': {
+			const byId = new Map(action.items.map((i) => [i.id, i]));
+			return state.map((t) => {
+				if (t.knowledgeBaseId !== action.knowledgeBaseId) return t;
+				if (!t.documentId) return t;
+				const match = byId.get(t.documentId);
+				if (!match) return t;
+				// Client-side terminal phases (`cancelled`) win — the
+				// server might still drive the doc to `ready`, but the
+				// user has signalled they no longer care.
+				if (t.phase === 'cancelled') return t;
+				if (t.phase === match.status && t.error === match.error) {
+					return t;
+				}
+				return {
+					...t,
+					phase: match.status,
+					error: match.error,
+				};
+			});
+		}
+		case 'CLEAR_FINISHED':
+			return state.filter(
+				(t) => t.knowledgeBaseId !== action.knowledgeBaseId || !isTerminal(t.phase),
+			);
+	}
+}
+
+function newTaskId(): string {
+	if (typeof crypto !== 'undefined' && 'randomUUID' in crypto) {
+		return crypto.randomUUID();
+	}
+	return `upload-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+interface UploadProviderProps {
+	children: ReactNode;
+}
+
+/**
+ * Mutable side-state for XHR controllers and scheduling flags.
+ *
+ * Lazy-initialised inside `useRef` (the factory form) so we never read
+ * `.current` during the initial render — and because the structure is
+ * a fixed shape of mutable maps, we can stash everything in a single
+ * `useRef` without violating the "no reading refs during render" rule:
+ * the reducer is the source of truth for render-relevant state, and
+ * these maps hold only opaque side-effects (Files, AbortControllers).
+ */
+interface UploadProviderRefs {
+	/** Map of taskId → File payload (kept off state; not serialisable). */
+	files: Map<string, File>;
+	/** Map of taskId → AbortController to cancel the in-flight XHR. */
+	controllers: Map<string, AbortController>;
+	/** Tasks the scheduler has already kicked off this lifetime. */
+	started: Set<string>;
+}
+
+export function UploadProvider({ children }: UploadProviderProps) {
+	const [tasks, dispatch] = useReducer(reducer, [] as UploadTask[]);
+	const refsRef = useRef<UploadProviderRefs | null>(null);
+	if (refsRef.current === null) {
+		refsRef.current = {
+			files: new Map(),
+			controllers: new Map(),
+			started: new Set(),
+		};
+	}
+
+	const startUpload = useCallback((task: UploadTask) => {
+		const refs = refsRef.current!;
+		const file = refs.files.get(task.taskId);
+		if (!file) {
+			dispatch({
+				type: 'UPLOAD_FAILED',
+				taskId: task.taskId,
+				error: 'Internal error: missing file payload.',
+			});
+			return;
+		}
+		const controller = new AbortController();
+		refs.controllers.set(task.taskId, controller);
+		dispatch({ type: 'START_UPLOAD', taskId: task.taskId });
+
+		knowledgeBaseApi
+			.uploadDocument(task.knowledgeBaseId, file, {
+				signal: controller.signal,
+				onProgress: ({ loaded, total }) => {
+					dispatch({
+						type: 'PROGRESS',
+						taskId: task.taskId,
+						loaded,
+						total,
+					});
+				},
+			})
+			.then((response) => {
+				dispatch({
+					type: 'UPLOAD_DONE',
+					taskId: task.taskId,
+					documentId: response.document_id,
+					status: response.status,
+				});
+			})
+			.catch((err: unknown) => {
+				if (err instanceof DOMException && err.name === 'AbortError') {
+					// Already handled by the cancel() path.
+					return;
+				}
+				const message = err instanceof Error ? err.message : 'Upload failed.';
+				dispatch({
+					type: 'UPLOAD_FAILED',
+					taskId: task.taskId,
+					error: message,
+				});
+			})
+			.finally(() => {
+				refs.controllers.delete(task.taskId);
+				refs.files.delete(task.taskId);
+			});
+	}, []);
+
+	// Scheduler — fires after every state change. Idempotent thanks to
+	// `refs.started`, so StrictMode's double-effect is harmless.
+	useEffect(() => {
+		const refs = refsRef.current!;
+		const running = tasks.filter((t) => t.phase === 'uploading').length;
+		const queued = tasks.filter((t) => t.phase === 'queued');
+		const slots = MAX_CONCURRENT_UPLOADS - running;
+		if (slots <= 0 || queued.length === 0) return;
+		for (const task of queued.slice(0, slots)) {
+			if (refs.started.has(task.taskId)) continue;
+			refs.started.add(task.taskId);
+			startUpload(task);
+		}
+	}, [tasks, startUpload]);
+
+	const enqueue = useCallback((knowledgeBaseId: string, files: File[]): UploadTask[] => {
+		const refs = refsRef.current!;
+		const now = Date.now();
+		const newTasks = files.map((file): UploadTask => {
+			const taskId = newTaskId();
+			refs.files.set(taskId, file);
+			return {
+				taskId,
+				knowledgeBaseId,
+				filename: file.name,
+				size: file.size,
+				documentId: null,
+				phase: 'queued',
+				loaded: 0,
+				error: null,
+				createdAt: now,
+			};
+		});
+		dispatch({ type: 'ADD', tasks: newTasks });
+		return newTasks;
+	}, []);
+
+	const cancel = useCallback(
+		(taskId: string) => {
+			const refs = refsRef.current!;
+			const task = tasks.find((t) => t.taskId === taskId);
+			if (!task) return;
+			if (task.phase === 'queued') {
+				refs.files.delete(taskId);
+				dispatch({ type: 'REMOVE', taskId });
+				return;
+			}
+			if (task.phase === 'uploading') {
+				refs.controllers.get(taskId)?.abort();
+				dispatch({ type: 'CANCEL', taskId });
+				return;
+			}
+			if (isTerminal(task.phase)) {
+				dispatch({ type: 'REMOVE', taskId });
+			}
+			// Server-side phases are not cancellable here; the caller
+			// should use the regular document-delete API instead.
+		},
+		[tasks],
+	);
+
+	const dismiss = useCallback((taskId: string) => {
+		dispatch({ type: 'REMOVE', taskId });
+	}, []);
+
+	const clearFinishedForKb = useCallback((knowledgeBaseId: string) => {
+		dispatch({ type: 'CLEAR_FINISHED', knowledgeBaseId });
+	}, []);
+
+	const applyServerStatuses = useCallback<UploadContextValue['applyServerStatuses']>(
+		(knowledgeBaseId, items) => {
+			dispatch({ type: 'SERVER_STATUS', knowledgeBaseId, items });
+		},
+		[],
+	);
+
+	// `tasksForKb` and `pollableDocumentIds` need stable references per
+	// (knowledgeBaseId, tasks) tuple so downstream effects don't churn.
+	const byKb = useMemo(() => {
+		const out = new Map<string, UploadTask[]>();
+		for (const t of tasks) {
+			const list = out.get(t.knowledgeBaseId);
+			if (list) list.push(t);
+			else out.set(t.knowledgeBaseId, [t]);
+		}
+		return out;
+	}, [tasks]);
+
+	const tasksForKb = useCallback(
+		(knowledgeBaseId: string): UploadTask[] => byKb.get(knowledgeBaseId) ?? [],
+		[byKb],
+	);
+
+	const pollableDocumentIds = useCallback(
+		(knowledgeBaseId: string): string[] => {
+			const list = byKb.get(knowledgeBaseId);
+			if (!list) return [];
+			const out: string[] = [];
+			for (const t of list) {
+				if (!t.documentId) continue;
+				// `uploading` / `queued` have no documentId yet; only
+				// server-side non-terminal phases are pollable.
+				if (
+					t.phase === 'pending' ||
+					t.phase === 'parsing' ||
+					t.phase === 'chunking' ||
+					t.phase === 'indexing'
+				) {
+					out.push(t.documentId);
+				}
+			}
+			return out;
+		},
+		[byKb],
+	);
+
+	// Warn before navigation when in-flight tasks would be lost.
+	// `uploading` tasks die with the page; server-side phases survive,
+	// so they do not trigger the warning.
+	useEffect(() => {
+		const hasInFlightUpload = tasks.some(
+			(t) => t.phase === 'queued' || t.phase === 'uploading',
+		);
+		if (!hasInFlightUpload) return;
+		const handler = (e: BeforeUnloadEvent) => {
+			e.preventDefault();
+			// Chrome / Edge require returnValue to be set.
+			e.returnValue = '';
+		};
+		window.addEventListener('beforeunload', handler);
+		return () => window.removeEventListener('beforeunload', handler);
+	}, [tasks]);
+
+	const value = useMemo<UploadContextValue>(
+		() => ({
+			tasks,
+			enqueue,
+			cancel,
+			dismiss,
+			clearFinishedForKb,
+			tasksForKb,
+			applyServerStatuses,
+			pollableDocumentIds,
+		}),
+		[
+			tasks,
+			enqueue,
+			cancel,
+			dismiss,
+			clearFinishedForKb,
+			tasksForKb,
+			applyServerStatuses,
+			pollableDocumentIds,
+		],
+	);
+
+	return <UploadContext.Provider value={value}>{children}</UploadContext.Provider>;
+}
+
+export function useUploadContext(): UploadContextValue {
+	const ctx = useContext(UploadContext);
+	if (!ctx) {
+		throw new Error('useUploadContext must be used inside <UploadProvider>');
+	}
+	return ctx;
+}
diff --git a/examples/web_ui/frontend/src/context/uploadTypes.ts b/examples/web_ui/frontend/src/context/uploadTypes.ts
new file mode 100644
index 0000000..5dd3681
--- /dev/null
+++ b/examples/web_ui/frontend/src/context/uploadTypes.ts
@@ -0,0 +1,44 @@
+import type { KnowledgeDocumentStatus } from '@/api';
+
+/**
+ * Lifecycle states a client-visible upload task can be in.
+ *
+ * The first two (`queued`, `uploading`) are pure client states. After
+ * the upload endpoint returns we mirror the server's
+ * :type:`KnowledgeDocumentStatus`. `cancelled` is also a client-side
+ * terminal — set when the user aborts before the upload completes.
+ */
+export type UploadPhase = 'queued' | 'uploading' | KnowledgeDocumentStatus | 'cancelled';
+
+export interface UploadTask {
+	/** Stable client-side id; survives across React renders. */
+	taskId: string;
+	knowledgeBaseId: string;
+	filename: string;
+	/** Total bytes; `0` only when the browser cannot compute it. */
+	size: number;
+	/** Server-assigned document id — `null` until upload returns 201. */
+	documentId: string | null;
+	phase: UploadPhase;
+	/** Bytes uploaded so far; meaningful only during `uploading`. */
+	loaded: number;
+	/** Human-readable failure reason; non-null only when `phase === 'error'`. */
+	error: string | null;
+	createdAt: number;
+}
+
+export function isTerminal(phase: UploadPhase): boolean {
+	return phase === 'ready' || phase === 'error' || phase === 'cancelled';
+}
+
+export function isInFlight(phase: UploadPhase): boolean {
+	return !isTerminal(phase);
+}
+
+/**
+ * Maximum number of upload tasks transferring bytes at once. Queued
+ * tasks above this cap wait until a slot frees up. Server-side phases
+ * (`pending`/`parsing`/…) do not count against the cap — they finish
+ * out of band.
+ */
+export const MAX_CONCURRENT_UPLOADS = 3;
diff --git a/examples/web_ui/frontend/src/hooks/use-mobile.ts b/examples/web_ui/frontend/src/hooks/use-mobile.ts
new file mode 100644
index 0000000..bcebea3
--- /dev/null
+++ b/examples/web_ui/frontend/src/hooks/use-mobile.ts
@@ -0,0 +1,19 @@
+import * as React from 'react';
+
+const MOBILE_BREAKPOINT = 768;
+
+export function useIsMobile() {
+	const [isMobile, setIsMobile] = React.useState<boolean | undefined>(undefined);
+
+	React.useEffect(() => {
+		const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`);
+		const onChange = () => {
+			setIsMobile(window.innerWidth < MOBILE_BREAKPOINT);
+		};
+		mql.addEventListener('change', onChange);
+		setIsMobile(window.innerWidth < MOBILE_BREAKPOINT);
+		return () => mql.removeEventListener('change', onChange);
+	}, []);
+
+	return !!isMobile;
+}
diff --git a/examples/web_ui/frontend/src/hooks/useAgentSchema.ts b/examples/web_ui/frontend/src/hooks/useAgentSchema.ts
new file mode 100644
index 0000000..4a20bb9
--- /dev/null
+++ b/examples/web_ui/frontend/src/hooks/useAgentSchema.ts
@@ -0,0 +1,38 @@
+import { useEffect, useState } from 'react';
+
+import { agentApi } from '@/api';
+import type { AgentSchemaV2Response } from '@/api';
+
+/**
+ * Module-level cache. The agent schema is derived from Pydantic models
+ * on the backend and never changes at runtime, so a single in-flight fetch
+ * is enough for the whole session.
+ */
+let cached: AgentSchemaV2Response | null = null;
+let inflight: Promise<AgentSchemaV2Response> | null = null;
+
+async function loadSchema(): Promise<AgentSchemaV2Response> {
+	if (cached) return cached;
+	if (!inflight) {
+		inflight = agentApi.getSchema().then((res) => {
+			cached = res;
+			return res;
+		});
+	}
+	return inflight;
+}
+
+/** Fetch (and cache) the full `AgentData` JSON Schema for the agent form. */
+export function useAgentSchema() {
+	const [schema, setSchema] = useState<AgentSchemaV2Response | null>(cached);
+	const [error, setError] = useState<Error | null>(null);
+
+	useEffect(() => {
+		if (cached) return;
+		loadSchema()
+			.then(setSchema)
+			.catch((e: Error) => setError(e));
+	}, []);
+
+	return { schema, loading: schema === null && error === null, error };
+}
diff --git a/examples/web_ui/frontend/src/hooks/useAgents.ts b/examples/web_ui/frontend/src/hooks/useAgents.ts
new file mode 100644
index 0000000..1c69340
--- /dev/null
+++ b/examples/web_ui/frontend/src/hooks/useAgents.ts
@@ -0,0 +1,62 @@
+import { useState, useEffect, useCallback } from 'react';
+
+import { agentApi } from '../api';
+import type { AgentView, CreateAgentRequest, UpdateAgentRequest } from '../api';
+
+/**
+ * Manages the full agent list with CRUD operations.
+ * Fetches on mount and automatically re-fetches after each mutation.
+ */
+export function useAgents() {
+	const [agents, setAgents] = useState<AgentView[]>([]);
+	const [loading, setLoading] = useState(false);
+	const [error, setError] = useState<Error | null>(null);
+
+	const refetch = useCallback(async () => {
+		setLoading(true);
+		setError(null);
+		try {
+			const res = await agentApi.list();
+			setAgents(res.agents);
+		} catch (e) {
+			setError(e as Error);
+		} finally {
+			setLoading(false);
+		}
+	}, []);
+
+	useEffect(() => {
+		refetch();
+	}, [refetch]);
+
+	/** Creates a new agent and refreshes the list. */
+	const create = useCallback(
+		async (body: CreateAgentRequest, options?: { silent?: boolean }) => {
+			const res = await agentApi.create(body, options);
+			await refetch();
+			return res;
+		},
+		[refetch],
+	);
+
+	/** Partially updates an agent and refreshes the list. */
+	const update = useCallback(
+		async (agentId: string, body: UpdateAgentRequest, options?: { silent?: boolean }) => {
+			const res = await agentApi.update(agentId, body, options);
+			await refetch();
+			return res;
+		},
+		[refetch],
+	);
+
+	/** Deletes an agent and refreshes the list. */
+	const remove = useCallback(
+		async (agentId: string) => {
+			await agentApi.delete(agentId);
+			await refetch();
+		},
+		[refetch],
+	);
+
+	return { agents, loading, error, refetch, create, update, remove };
+}
diff --git a/examples/web_ui/frontend/src/hooks/useAvailableModels.ts b/examples/web_ui/frontend/src/hooks/useAvailableModels.ts
new file mode 100644
index 0000000..cae10a0
--- /dev/null
+++ b/examples/web_ui/frontend/src/hooks/useAvailableModels.ts
@@ -0,0 +1,55 @@
+import { useState, useEffect, useCallback } from 'react';
+
+import { credentialApi, modelApi } from '@/api';
+import type { CredentialView, ModelCard } from '@/api';
+
+export interface CredentialWithModels {
+	credential: CredentialView;
+	models: ModelCard[];
+}
+
+/**
+ * Fetches all credentials and their available models, grouped by provider type.
+ * Provider type is read from `credential.data.type`.
+ * Credentials without a `type` field or whose model fetch fails are silently skipped.
+ */
+export function useAvailableModels() {
+	const [groups, setGroups] = useState<Record<string, CredentialWithModels[]>>({});
+	const [loading, setLoading] = useState(false);
+	const [error, setError] = useState<Error | null>(null);
+
+	const refetch = useCallback(async () => {
+		setLoading(true);
+		setError(null);
+		try {
+			const { credentials } = await credentialApi.list();
+			const result: Record<string, CredentialWithModels[]> = {};
+
+			await Promise.all(
+				credentials.map(async (credential) => {
+					const type = credential.data.type as string | undefined;
+					if (!type) return;
+					if (!result[type]) result[type] = [];
+					try {
+						const { models } = await modelApi.list(type);
+						result[type].push({ credential, models });
+					} catch {
+						result[type].push({ credential, models: [] });
+					}
+				}),
+			);
+
+			setGroups(result);
+		} catch (e) {
+			setError(e as Error);
+		} finally {
+			setLoading(false);
+		}
+	}, []);
+
+	useEffect(() => {
+		refetch();
+	}, [refetch]);
+
+	return { groups, loading, error, refetch };
+}
diff --git a/examples/web_ui/frontend/src/hooks/useAvailableTTSModels.ts b/examples/web_ui/frontend/src/hooks/useAvailableTTSModels.ts
new file mode 100644
index 0000000..9f1dca6
--- /dev/null
+++ b/examples/web_ui/frontend/src/hooks/useAvailableTTSModels.ts
@@ -0,0 +1,61 @@
+import { useState, useEffect, useCallback } from 'react';
+
+import { credentialApi, ttsModelApi } from '@/api';
+import type { CredentialView, TTSModelCard } from '@/api';
+
+export interface CredentialWithTTSModels {
+	credential: CredentialView;
+	models: TTSModelCard[];
+}
+
+/**
+ * Fetches all credentials and their available TTS models, grouped by provider type.
+ * Credentials/providers that expose no TTS models are omitted.
+ */
+export function useAvailableTTSModels() {
+	const [groups, setGroups] = useState<Record<string, CredentialWithTTSModels[]>>({});
+	const [loading, setLoading] = useState(false);
+	const [error, setError] = useState<Error | null>(null);
+
+	const refetch = useCallback(async () => {
+		setLoading(true);
+		setError(null);
+		try {
+			const { credentials } = await credentialApi.list();
+			const result: Record<string, CredentialWithTTSModels[]> = {};
+
+			await Promise.all(
+				credentials.map(async (credential) => {
+					const type = credential.data.type as string | undefined;
+					if (!type) return;
+					if (!result[type]) result[type] = [];
+					try {
+						const { models } = await ttsModelApi.list(type);
+						if (models.length > 0) {
+							result[type].push({ credential, models });
+						}
+					} catch {
+						// Provider doesn't support TTS — skip silently
+					}
+				}),
+			);
+
+			// Remove provider groups with no TTS models
+			for (const key of Object.keys(result)) {
+				if (result[key].length === 0) delete result[key];
+			}
+
+			setGroups(result);
+		} catch (e) {
+			setError(e as Error);
+		} finally {
+			setLoading(false);
+		}
+	}, []);
+
+	useEffect(() => {
+		refetch();
+	}, [refetch]);
+
+	return { groups, loading, error, refetch };
+}
diff --git a/examples/web_ui/frontend/src/hooks/useChat.ts b/examples/web_ui/frontend/src/hooks/useChat.ts
new file mode 100644
index 0000000..d39b812
--- /dev/null
+++ b/examples/web_ui/frontend/src/hooks/useChat.ts
@@ -0,0 +1,41 @@
+import { useState, useCallback } from 'react';
+
+import { chatApi } from '@/api';
+import type { ChatRequest } from '@/api';
+
+/**
+ * Fire-and-forget chat trigger.
+ *
+ * Sends a ``POST /chat/`` request that kicks off a chat run on the
+ * backend. Events are **not** returned here — they arrive via the
+ * session's SSE stream (``GET /sessions/{sid}/stream``), consumed by
+ * :func:`useMessages`.
+ *
+ * This hook is a thin wrapper around ``chatApi.trigger``; it mainly
+ * exists for parity with the previous ``useChat`` API shape.
+ */
+export function useChat() {
+	const [streaming, setStreaming] = useState(false);
+	const [error, setError] = useState<Error | null>(null);
+
+	/**
+	 * Trigger a chat run. Returns when the POST completes (not when
+	 * the run finishes).
+	 *
+	 * @param body - The chat request payload.
+	 */
+	const send = useCallback(async (body: ChatRequest) => {
+		setStreaming(true);
+		setError(null);
+
+		try {
+			await chatApi.trigger(body);
+		} catch (e) {
+			if ((e as Error).name !== 'AbortError') setError(e as Error);
+		} finally {
+			setStreaming(false);
+		}
+	}, []);
+
+	return { streaming, error, send };
+}
diff --git a/examples/web_ui/frontend/src/hooks/useCredentials.ts b/examples/web_ui/frontend/src/hooks/useCredentials.ts
new file mode 100644
index 0000000..29d1511
--- /dev/null
+++ b/examples/web_ui/frontend/src/hooks/useCredentials.ts
@@ -0,0 +1,62 @@
+import { useState, useEffect, useCallback } from 'react';
+
+import { credentialApi } from '../api';
+import type { CredentialView, CreateCredentialRequest, UpdateCredentialRequest } from '../api';
+
+/**
+ * Manages API key credentials with CRUD operations.
+ * Fetches on mount and automatically re-fetches after each mutation.
+ */
+export function useCredentials() {
+	const [credentials, setCredentials] = useState<CredentialView[]>([]);
+	const [loading, setLoading] = useState(false);
+	const [error, setError] = useState<Error | null>(null);
+
+	const refetch = useCallback(async () => {
+		setLoading(true);
+		setError(null);
+		try {
+			const res = await credentialApi.list();
+			setCredentials(res.credentials);
+		} catch (e) {
+			setError(e as Error);
+		} finally {
+			setLoading(false);
+		}
+	}, []);
+
+	useEffect(() => {
+		refetch();
+	}, [refetch]);
+
+	/** Stores a new credential and refreshes the list. */
+	const create = useCallback(
+		async (body: CreateCredentialRequest) => {
+			const res = await credentialApi.create(body);
+			await refetch();
+			return res;
+		},
+		[refetch],
+	);
+
+	/** Replaces a credential's payload and refreshes the list. */
+	const update = useCallback(
+		async (credentialId: string, body: UpdateCredentialRequest) => {
+			const res = await credentialApi.update(credentialId, body);
+			await refetch();
+			return res;
+		},
+		[refetch],
+	);
+
+	/** Permanently deletes a credential and refreshes the list. */
+	const remove = useCallback(
+		async (credentialId: string) => {
+			await credentialApi.delete(credentialId);
+			await refetch();
+		},
+		[refetch],
+	);
+
+	return { credentials, loading, error, refetch, create, update, remove };
+}
diff --git a/examples/web_ui/frontend/src/hooks/useDocumentStatusPolling.ts b/examples/web_ui/frontend/src/hooks/useDocumentStatusPolling.ts
new file mode 100644
index 0000000..9c6b020
--- /dev/null
+++ b/examples/web_ui/frontend/src/hooks/useDocumentStatusPolling.ts
@@ -0,0 +1,136 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+
+import { knowledgeBaseApi } from '@/api';
+import type { KnowledgeDocumentView } from '@/api';
+import { useUploadContext } from '@/context/UploadContext';
+
+const POLL_INTERVAL_MS = 1500;
+
+/**
+ * Document ids the polling loop should track each tick. Combines:
+ *
+ * - documents the local `UploadProvider` is still expecting transitions
+ *   for (so a freshly-uploaded file polls without waiting for the next
+ *   list refresh);
+ * - documents the caller knows are non-terminal from a server list
+ *   (so a page reload mid-indexing keeps polling without lifting the
+ *   upload through the provider).
+ *
+ * Ids that resolve to a terminal state (`ready` / `error`) drop out
+ * automatically — the polling loop stops as soon as the union becomes
+ * empty.
+ */
+interface PollingInput {
+	knowledgeBaseId: string | null;
+	/** Currently-listed server documents. */
+	documents: KnowledgeDocumentView[];
+}
+
+interface PollingResult {
+	/** Most-recent status views, keyed by document id. */
+	statuses: Record<string, KnowledgeDocumentView>;
+	/** True while the loop is actively scheduling refreshes. */
+	polling: boolean;
+}
+
+/**
+ * Conditional polling — only schedules a request when there is at least
+ * one non-terminal document id to watch. The loop self-stops as soon as
+ * every tracked id reaches `ready` / `error`, and rewires automatically
+ * when new ids enter the set (a fresh upload, a re-mount, etc.).
+ *
+ * Single source of truth for the `UploadProvider`'s server-side phase
+ * mirror: every tick that returns items is fanned out through
+ * `applyServerStatuses`, so the in-flight upload cards reflect the
+ * worker's progress without any extra wiring at the call site.
+ */
+export function useDocumentStatusPolling({
+	knowledgeBaseId,
+	documents,
+}: PollingInput): PollingResult {
+	const { pollableDocumentIds, applyServerStatuses } = useUploadContext();
+
+	// Server-side non-terminal docs from the list (catches reload state).
+	const docIds = useMemo(() => {
+		const out: string[] = [];
+		for (const d of documents) {
+			if (d.status !== 'ready' && d.status !== 'error') {
+				out.push(d.id);
+			}
+		}
+		return out;
+	}, [documents]);
+
+	// Stable, sorted union of server-side non-terminal docs (catches
+	// reload state) and locally-tracked in-flight docs from the upload
+	// provider. Used both as the request payload and as the effect
+	// dependency key so dropping/adding a single id triggers exactly
+	// one effect re-run.
+	const watchIdsKey = useMemo(() => {
+		const set = new Set<string>(docIds);
+		if (knowledgeBaseId) {
+			for (const id of pollableDocumentIds(knowledgeBaseId)) {
+				set.add(id);
+			}
+		}
+		return Array.from(set).sort().join(',');
+	}, [docIds, knowledgeBaseId, pollableDocumentIds]);
+
+	const [statuses, setStatuses] = useState<Record<string, KnowledgeDocumentView>>({});
+
+	// Mutable refs keep the running interval alive across re-renders
+	// without forcing the effect to restart on every state change.
+	const inflightRef = useRef<AbortController | null>(null);
+
+	useEffect(() => {
+		if (!knowledgeBaseId) return;
+		const ids = watchIdsKey ? watchIdsKey.split(',') : [];
+		if (ids.length === 0) return;
+
+		let cancelled = false;
+
+		const tick = async () => {
+			if (cancelled) return;
+			inflightRef.current?.abort();
+			const controller = new AbortController();
+			inflightRef.current = controller;
+			try {
+				const { items } = await knowledgeBaseApi.getDocumentStatus(knowledgeBaseId, ids);
+				if (cancelled) return;
+				setStatuses((prev) => {
+					const next = { ...prev };
+					for (const item of items) next[item.id] = item;
+					return next;
+				});
+				applyServerStatuses(
+					knowledgeBaseId,
+					items.map((i) => ({
+						id: i.id,
+						status: i.status,
+						error: i.error,
+					})),
+				);
+			} catch {
+				// Swallow transient errors — the next tick will retry.
+				// We deliberately don't surface a toast: a flaky network
+				// shouldn't spam the user while indexing is in the
+				// background.
+			}
+		};
+
+		// Fire immediately so the first reading lands without waiting a
+		// full poll interval (important right after an upload).
+		void tick();
+		const handle = window.setInterval(tick, POLL_INTERVAL_MS);
+		return () => {
+			cancelled = true;
+			inflightRef.current?.abort();
+			window.clearInterval(handle);
+		};
+	}, [knowledgeBaseId, watchIdsKey, applyServerStatuses]);
+
+	return {
+		statuses,
+		polling: watchIdsKey.length > 0,
+	};
+}
diff --git a/examples/web_ui/frontend/src/hooks/useKbEmbeddingModels.ts b/examples/web_ui/frontend/src/hooks/useKbEmbeddingModels.ts
new file mode 100644
index 0000000..da91872
--- /dev/null
+++ b/examples/web_ui/frontend/src/hooks/useKbEmbeddingModels.ts
@@ -0,0 +1,39 @@
+import { useCallback, useEffect, useState } from 'react';
+
+import { knowledgeBaseApi } from '@/api';
+import type { DimensionPolicy, KbEmbeddingProvider } from '@/api';
+
+/**
+ * Fetches the list of embedding models a user can pick at KB-creation
+ * time. Server-side already filtered by the manager's
+ * :class:`DimensionPolicy`; the UI just renders.
+ *
+ * Refetches when ``refetchTrigger`` changes (e.g. after a credential
+ * was created), mirroring the contract used by other selectors.
+ */
+export function useKbEmbeddingModels(refetchTrigger?: number) {
+	const [providers, setProviders] = useState<KbEmbeddingProvider[]>([]);
+	const [policy, setPolicy] = useState<DimensionPolicy | null>(null);
+	const [loading, setLoading] = useState(false);
+	const [error, setError] = useState<Error | null>(null);
+
+	const refetch = useCallback(async () => {
+		setLoading(true);
+		setError(null);
+		try {
+			const res = await knowledgeBaseApi.listEmbeddingModels();
+			setProviders(res.providers);
+			setPolicy(res.policy);
+		} catch (e) {
+			setError(e as Error);
+		} finally {
+			setLoading(false);
+		}
+	}, []);
+
+	useEffect(() => {
+		refetch();
+	}, [refetch, refetchTrigger]);
+
+	return { providers, policy, loading, error, refetch };
+}
diff --git a/examples/web_ui/frontend/src/hooks/useKnowledgeBaseMiddlewareSchema.ts b/examples/web_ui/frontend/src/hooks/useKnowledgeBaseMiddlewareSchema.ts
new file mode 100644
index 0000000..8446032
--- /dev/null
+++ b/examples/web_ui/frontend/src/hooks/useKnowledgeBaseMiddlewareSchema.ts
@@ -0,0 +1,72 @@
+import { useEffect, useState } from 'react';
+
+import { knowledgeBaseApi } from '@/api';
+import type { JSONSchema } from '@/api';
+
+/**
+ * Module-level cache for the KB middleware parameter schema.
+ *
+ * The schema is class-static on the backend (derived from
+ * :class:`KnowledgeBaseMiddleware.Parameters.model_json_schema()`),
+ * so a single fetch per page load is enough.  Several mounted
+ * `KnowledgeBasePanel`s would otherwise each fire the request — the
+ * cache de-duplicates concurrent callers, too.
+ */
+let cached: JSONSchema | null = null;
+let inflight: Promise<JSONSchema> | null = null;
+
+async function fetchSchema(): Promise<JSONSchema> {
+	if (cached) return cached;
+	if (inflight) return inflight;
+	inflight = knowledgeBaseApi
+		.middlewareParametersSchema()
+		.then((res) => {
+			cached = res.parameter_schema as unknown as JSONSchema;
+			return cached;
+		})
+		.finally(() => {
+			inflight = null;
+		});
+	return inflight;
+}
+
+/**
+ * Fetch the parameter schema for the session-level
+ * `KnowledgeBaseMiddleware`.
+ *
+ * Returns the schema once available; `null` while loading. The schema
+ * is shared across all callers via a module-level cache.
+ */
+export function useKnowledgeBaseMiddlewareSchema(): {
+	schema: JSONSchema | null;
+	loading: boolean;
+	error: Error | null;
+} {
+	const [schema, setSchema] = useState<JSONSchema | null>(cached);
+	const [loading, setLoading] = useState(cached === null);
+	const [error, setError] = useState<Error | null>(null);
+
+	useEffect(() => {
+		if (cached) {
+			setSchema(cached);
+			return;
+		}
+		let cancelled = false;
+		setLoading(true);
+		fetchSchema()
+			.then((s) => {
+				if (!cancelled) setSchema(s);
+			})
+			.catch((e) => {
+				if (!cancelled) setError(e as Error);
+			})
+			.finally(() => {
+				if (!cancelled) setLoading(false);
+			});
+		return () => {
+			cancelled = true;
+		};
+	}, []);
+
+	return { schema, loading, error };
+}
diff --git a/examples/web_ui/frontend/src/hooks/useKnowledgeBases.ts b/examples/web_ui/frontend/src/hooks/useKnowledgeBases.ts
new file mode 100644
index 0000000..b66631e
--- /dev/null
+++ b/examples/web_ui/frontend/src/hooks/useKnowledgeBases.ts
@@ -0,0 +1,116 @@
+import { useCallback, useEffect, useState } from 'react';
+
+import { knowledgeBaseApi } from '@/api';
+import type {
+	CreateKnowledgeBaseRequest,
+	KnowledgeBaseView,
+	SearchKnowledgeBaseRequest,
+	UpdateKnowledgeBaseRequest,
+} from '@/api';
+
+/**
+ * Knowledge base CRUD + search wrapper.
+ *
+ * Loads the caller's knowledge bases from `/knowledge_bases/` on mount
+ * and refetches after every mutation, so the UI stays consistent with
+ * the server-side state.
+ */
+export function useKnowledgeBases() {
+	const [knowledgeBases, setKnowledgeBases] = useState<KnowledgeBaseView[]>([]);
+	const [loading, setLoading] = useState(false);
+	const [creating, setCreating] = useState(false);
+	const [error, setError] = useState<Error | null>(null);
+
+	const refetch = useCallback(async () => {
+		setLoading(true);
+		setError(null);
+		try {
+			const { knowledge_bases } = await knowledgeBaseApi.list();
+			setKnowledgeBases(knowledge_bases);
+		} catch (e) {
+			setError(e as Error);
+		} finally {
+			setLoading(false);
+		}
+	}, []);
+
+	useEffect(() => {
+		refetch();
+	}, [refetch]);
+
+	/** Create a new knowledge base and refresh the list. */
+	const create = useCallback(
+		async (body: CreateKnowledgeBaseRequest): Promise<string> => {
+			setCreating(true);
+			setError(null);
+			try {
+				const { knowledge_base_id } = await knowledgeBaseApi.create(body);
+				await refetch();
+				return knowledge_base_id;
+			} catch (e) {
+				setError(e as Error);
+				throw e;
+			} finally {
+				setCreating(false);
+			}
+		},
+		[refetch],
+	);
+
+	/** Permanently delete a knowledge base and refresh the list. */
+	const remove = useCallback(
+		async (knowledgeBaseId: string) => {
+			await knowledgeBaseApi.delete(knowledgeBaseId);
+			await refetch();
+		},
+		[refetch],
+	);
+
+	/** Update mutable fields on a knowledge base and refresh the list. */
+	const update = useCallback(
+		async (
+			knowledgeBaseId: string,
+			body: UpdateKnowledgeBaseRequest,
+		): Promise<KnowledgeBaseView> => {
+			const view = await knowledgeBaseApi.update(knowledgeBaseId, body);
+			await refetch();
+			return view;
+		},
+		[refetch],
+	);
+
+	/** Upload a document into a knowledge base. */
+	const uploadDocument = useCallback(
+		(knowledgeBaseId: string, file: File) =>
+			knowledgeBaseApi.uploadDocument(knowledgeBaseId, file),
+		[],
+	);
+
+	/** Delete a document from a knowledge base. */
+	const deleteDocument = useCallback(
+		(knowledgeBaseId: string, documentId: string) =>
+			knowledgeBaseApi.deleteDocument(knowledgeBaseId, documentId),
+		[],
+	);
+
+	/** Search a knowledge base by natural-language query. */
+	const search = useCallback(
+		(knowledgeBaseId: string, body: SearchKnowledgeBaseRequest) =>
+			knowledgeBaseApi.search(knowledgeBaseId, body),
+		[],
+	);
+
+	return {
+		knowledgeBases,
+		loading,
+		creating,
+		error,
+		refetch,
+		create,
+		remove,
+		update,
+		uploadDocument,
+		deleteDocument,
+		search,
+	};
+}
diff --git a/examples/web_ui/frontend/src/hooks/useKnowledgeDocuments.ts b/examples/web_ui/frontend/src/hooks/useKnowledgeDocuments.ts
new file mode 100644
index 0000000..115f5cd
--- /dev/null
+++ b/examples/web_ui/frontend/src/hooks/useKnowledgeDocuments.ts
@@ -0,0 +1,47 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import { knowledgeBaseApi } from '@/api';
+import type { KnowledgeDocumentView } from '@/api';
+
+/**
+ * Owns the document list for a single knowledge base.
+ *
+ * Re-fetches on mount, when `knowledgeBaseId` changes, and via the
+ * caller-driven `refetch`. The upload page should call `refetch` after
+ * a successful upload (so the new `pending` row appears) and again
+ * whenever a polling tick lifts a row to a terminal state (so
+ * `chunk_count` reflects the worker's final commit).
+ */
+export function useKnowledgeDocuments(knowledgeBaseId: string | null) {
+	const [documents, setDocuments] = useState<KnowledgeDocumentView[]>([]);
+	const [loading, setLoading] = useState(false);
+	const [error, setError] = useState<Error | null>(null);
+	// Discards stale responses if the user switches KBs mid-flight.
+	const requestSeq = useRef(0);
+
+	const refetch = useCallback(async () => {
+		if (!knowledgeBaseId) {
+			setDocuments([]);
+			return;
+		}
+		const seq = ++requestSeq.current;
+		setLoading(true);
+		setError(null);
+		try {
+			const { documents: list } = await knowledgeBaseApi.listDocuments(knowledgeBaseId);
+			if (seq !== requestSeq.current) return;
+			setDocuments(list);
+		} catch (e) {
+			if (seq !== requestSeq.current) return;
+			setError(e as Error);
+		} finally {
+			if (seq === requestSeq.current) setLoading(false);
+		}
+	}, [knowledgeBaseId]);
+
+	useEffect(() => {
+		void refetch();
+	}, [refetch]);
+
+	return { documents, loading, error, refetch, setDocuments };
+}
diff --git a/examples/web_ui/frontend/src/hooks/useKnowledgeSupportedContentTypes.ts b/examples/web_ui/frontend/src/hooks/useKnowledgeSupportedContentTypes.ts
new file mode 100644
index 0000000..254516a
--- /dev/null
+++ b/examples/web_ui/frontend/src/hooks/useKnowledgeSupportedContentTypes.ts
@@ -0,0 +1,78 @@
+import { useEffect, useState } from 'react';
+
+import { knowledgeBaseApi } from '@/api';
+import type { ListSupportedContentTypesResponse } from '@/api';
+
+/**
+ * Module-level cache for the KB-parser capability list.
+ *
+ * The set of supported media types / extensions is fixed at app
+ * startup — it is derived from the parser registry handed to
+ * `create_app()`, which never changes for the lifetime of the process.
+ * One fetch per page load is enough, and several mounted document
+ * panels share the same cached value.
+ */
+let cached: ListSupportedContentTypesResponse | null = null;
+let inflight: Promise<ListSupportedContentTypesResponse> | null = null;
+
+async function fetchSupported(): Promise<ListSupportedContentTypesResponse> {
+	if (cached) return cached;
+	if (inflight) return inflight;
+	inflight = knowledgeBaseApi
+		.supportedContentTypes()
+		.then((res) => {
+			cached = res;
+			return res;
+		})
+		.finally(() => {
+			inflight = null;
+		});
+	return inflight;
+}
+
+/**
+ * Fetch the parser-supported upload types.
+ *
+ * Returns the union of media types and extensions once available; an
+ * empty placeholder while loading.  The result is shared across all
+ * callers via a module-level cache.
+ */
+export function useKnowledgeSupportedContentTypes(): {
+	mediaTypes: string[];
+	extensions: string[];
+	loading: boolean;
+	error: Error | null;
+} {
+	const [data, setData] = useState<ListSupportedContentTypesResponse | null>(cached);
+	const [loading, setLoading] = useState(cached === null);
+	const [error, setError] = useState<Error | null>(null);
+
+	useEffect(() => {
+		if (cached) {
+			setData(cached);
+			return;
+		}
+		let cancelled = false;
+		setLoading(true);
+		fetchSupported()
+			.then((res) => {
+				if (!cancelled) setData(res);
+			})
+			.catch((e) => {
+				if (!cancelled) setError(e as Error);
+			})
+			.finally(() => {
+				if (!cancelled) setLoading(false);
+			});
+		return () => {
+			cancelled = true;
+		};
+	}, []);
+
+	return {
+		mediaTypes: data?.media_types ?? [],
+		extensions: data?.extensions ?? [],
+		loading,
+		error,
+	};
+}
diff --git a/examples/web_ui/frontend/src/hooks/useMessages.ts b/examples/web_ui/frontend/src/hooks/useMessages.ts
new file mode 100644
index 0000000..2946731
--- /dev/null
+++ b/examples/web_ui/frontend/src/hooks/useMessages.ts
@@ -0,0 +1,491 @@
+import { EventType } from '@agentscope-ai/agentscope/event';
+import type {
+	AgentEvent,
+	CustomEvent,
+	DataBlockStartEvent,
+	DataBlockDeltaEvent,
+	DataBlockEndEvent,
+	ReplyStartEvent,
+	UserConfirmResultEvent,
+} from '@agentscope-ai/agentscope/event';
+import { appendEvent, AssistantMsg, UserMsg } from '@agentscope-ai/agentscope/message';
+import type { Msg, ContentBlock } from '@agentscope-ai/agentscope/message';
+import type { ToolCallBlock } from '@agentscope-ai/agentscope/message';
+import { useState, useCallback, useRef, useEffect } from 'react';
+
+import { sessionApi } from '@/api';
+import { chatApi } from '@/api';
+import { useAudioManager } from '@/context/AudioContext';
+
+/**
+ * One pending subagent HITL request, projected from a team *member*
+ * session onto its *leader* session so the leader UI can render and
+ * resolve it. Mirrors the Python payload written by
+ * ``SubagentHitlProjector`` and pushed/replayed as a ``CustomEvent``
+ * (``name="subagent_require_user_confirm"``).
+ */
+export type SubagentHitlEntry = {
+	worker_session_id: string;
+	worker_agent_id: string;
+	worker_agent_name: string;
+	reply_id: string;
+	event_type: 'require_user_confirm' | 'require_external_execution';
+	/** The original ``RequireUserConfirmEvent`` payload (serialized). */
+	event: { tool_calls?: ToolCallBlock[] } & Record<string, unknown>;
+	created_at: string;
+};
+
+/**
+ * Return true if ``msg`` is an assistant reply currently parked on a
+ * pending tool_call (awaiting user confirmation or an external
+ * execution result). Used both to detect the "in-flight reply on page
+ * load" case and as the SDK-gap workaround that hides the confirm
+ * card once the paired tool_result lands.
+ */
+const hasPendingToolCall = (msg: Msg | undefined): boolean => {
+	if (!msg || msg.role !== 'assistant') return false;
+	for (const block of msg.content) {
+		if (block.type !== 'tool_call') continue;
+		const state = (block as ToolCallBlock).state;
+		if (state === 'asking' || state === 'submitted') return true;
+	}
+	return false;
+};
+
+const hitlKey = (e: { worker_session_id: string; reply_id: string }) =>
+	`${e.worker_session_id}:${e.reply_id}`;
+
+/**
+ * Lifecycle phase of the reply currently owned by this session.
+ *
+ * - ``idle`` — no in-flight reply; the send button is enabled.
+ * - ``streaming`` — a reply is in progress (either actively producing
+ *   events or parked awaiting HITL). The send button is replaced by a
+ *   Stop button. The parked-vs-generating distinction is not tracked
+ *   here; HITL cards render themselves from message content when a
+ *   ``RequireUserConfirmEvent`` block is present.
+ * - ``interrupting`` — the user has requested a stop and we are
+ *   waiting for the backend's terminating ``ReplyEndEvent``. Stop
+ *   button is shown but disabled so users cannot spam it. Falls back
+ *   to ``idle`` after a 10s safety timeout in case the terminating
+ *   event never arrives (dropped SSE frame, backend bug, etc.).
+ */
+export type ReplyPhase = 'idle' | 'streaming' | 'interrupting';
+
+/** Safety fallback: force phase back to idle if REPLY_END is not seen. */
+const INTERRUPT_TIMEOUT_MS = 10_000;
+
+/**
+ * Manages messages for a single ``(agentId, sessionId)`` pair.
+ *
+ * Event delivery has two independent channels:
+ *
+ * - **History** — ``GET /sessions/{sid}/messages`` fetches persisted
+ *   ``Msg`` objects (each a complete reply).
+ * - **Live stream** — ``GET /sessions/{sid}/stream`` is a long-lived
+ *   SSE connection that pushes ``AgentEvent`` deltas as they are
+ *   produced by any chat run on this session (user-triggered,
+ *   background retrigger, team member message, …).
+ *
+ * The hook opens the SSE connection immediately after fetching
+ * history. User input and human-in-the-loop confirmations are sent
+ * via ``POST /chat/`` (fire-and-forget); the resulting events arrive
+ * through the already-open SSE connection.
+ *
+ * ``phase`` is driven by event content, not HTTP lifecycle: it moves
+ * to ``streaming`` on ``ReplyStartEvent`` and back to ``idle`` on
+ * ``ReplyEndEvent``. Calling ``interrupt()`` moves it to
+ * ``interrupting`` until the terminating ``ReplyEndEvent`` arrives (or
+ * a 10s safety timeout fires).
+ *
+ * @param agentId - The agent whose session to subscribe. ``null`` to
+ *   skip.
+ * @param sessionId - The session to subscribe. ``null`` to skip.
+ * @returns Object with ``msgs``, ``loading``, ``phase``, ``error``,
+ *   ``send``, ``onUserConfirm``, and ``abort``.
+ */
+export function useMessages(
+	agentId: string | null,
+	sessionId: string | null,
+	options?: {
+		/**
+		 * Called when a ``CUSTOM`` event with ``name="team_updated"``
+		 * arrives — the team membership has changed (TeamCreate /
+		 * AgentCreate / TeamDelete ran). The typical response is to
+		 * refetch the session list so the team sidebar updates.
+		 */
+		onTeamUpdated?: () => void;
+		/**
+		 * Called when a ``CUSTOM`` event with ``name="state_updated"``
+		 * arrives — agent state (tasks / permission) changed during a
+		 * tool call. The ``value`` payload contains the latest
+		 * ``tasks_context`` and ``permission_context``.
+		 */
+		onStateUpdated?: (value: Record<string, unknown>) => void;
+	},
+) {
+	const [msgs, setMsgs] = useState<Msg[]>([]);
+	const [loading, setLoading] = useState(false);
+	const [phase, setPhase] = useState<ReplyPhase>('idle');
+	const [error, setError] = useState<Error | null>(null);
+	// Pending subagent HITL cards projected onto this (leader) session.
+	const [subagentHitl, setSubagentHitl] = useState<SubagentHitlEntry[]>([]);
+
+	const msgsRef = useRef<Msg[]>([]);
+	const currentReplyRef = useRef<Msg | null>(null);
+	const abortRef = useRef<AbortController | null>(null);
+	const rafRef = useRef<number | null>(null);
+	// Timer that reverts ``interrupting`` back to ``idle`` if the
+	// terminating REPLY_END never arrives (dropped SSE frame, etc.).
+	const interruptTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+	const clearInterruptTimer = useCallback(() => {
+		if (interruptTimerRef.current !== null) {
+			clearTimeout(interruptTimerRef.current);
+			interruptTimerRef.current = null;
+		}
+	}, []);
+
+	const audioManager = useAudioManager();
+
+	const optionsRef = useRef(options);
+	useEffect(() => {
+		optionsRef.current = options;
+	}, [options]);
+	const scheduleUpdate = useCallback(() => {
+		if (rafRef.current !== null) return;
+		rafRef.current = requestAnimationFrame(() => {
+			rafRef.current = null;
+			setMsgs([...msgsRef.current]);
+		});
+	}, []);
+
+	/** Apply a single AgentEvent to the in-progress reply. */
+	const processEvent = useCallback(
+		(event: AgentEvent) => {
+			// Custom events are service-layer notifications, not agent
+			// reply content — route them to callbacks and skip appendEvent.
+			if (event.type === EventType.CUSTOM) {
+				const custom = event as CustomEvent;
+				if (custom.name === 'team_updated') {
+					optionsRef.current?.onTeamUpdated?.();
+				} else if (custom.name === 'state_updated' && custom.value) {
+					optionsRef.current?.onStateUpdated?.(custom.value as Record<string, unknown>);
+				} else if (custom.name === 'subagent_require_user_confirm') {
+					// A team member is asking for confirmation; show (or
+					// refresh) its card on this leader view. Dedup by
+					// (worker_session_id, reply_id).
+					const e = custom.value as unknown as SubagentHitlEntry;
+					setSubagentHitl((prev) => [
+						...prev.filter((x) => hitlKey(x) !== hitlKey(e)),
+						e,
+					]);
+				} else if (custom.name === 'subagent_user_confirm_result') {
+					// The member resolved (or its run ended); clear the card.
+					const v = custom.value as { worker_session_id: string; reply_id: string };
+					setSubagentHitl((prev) => prev.filter((x) => hitlKey(x) !== hitlKey(v)));
+				}
+				return;
+			}
+			if (event.type === EventType.REPLY_START) {
+				audioManager?.stopAllPlayback();
+				const e = event as ReplyStartEvent;
+				const msg = AssistantMsg({ id: e.reply_id, name: e.name, content: [] });
+				msgsRef.current = [...msgsRef.current, msg];
+				currentReplyRef.current = msg;
+				clearInterruptTimer();
+				setPhase('streaming');
+			} else if (event.type === EventType.REPLY_END) {
+				if (currentReplyRef.current) {
+					appendEvent(currentReplyRef.current, event);
+				}
+				clearInterruptTimer();
+				setPhase('idle');
+				currentReplyRef.current = null;
+			} else if (currentReplyRef.current) {
+				appendEvent(currentReplyRef.current, event);
+			}
+
+			// Route streaming audio DataBlocks to the audio manager. They still
+			// flow through `appendEvent` above (which builds up `source.data`
+			// in the Msg), but MessageBubble reads playback state from the
+			// manager so it can show progress and autoplay on completion.
+			if (audioManager) {
+				if (event.type === EventType.DATA_BLOCK_START) {
+					const e = event as DataBlockStartEvent;
+					if (e.media_type.startsWith('audio/')) {
+						audioManager.start(e.block_id, e.media_type);
+					}
+				} else if (event.type === EventType.DATA_BLOCK_DELTA) {
+					const e = event as DataBlockDeltaEvent;
+					if (e.media_type.startsWith('audio/')) {
+						audioManager.append(e.block_id, e.data);
+					}
+				} else if (event.type === EventType.DATA_BLOCK_END) {
+					const e = event as DataBlockEndEvent;
+					// `end` is a no-op when the block isn't being tracked, so
+					// we can call it unconditionally.
+					audioManager.end(e.block_id);
+				}
+			}
+
+			scheduleUpdate();
+		},
+		[scheduleUpdate, audioManager, clearInterruptTimer],
+	);
+
+	// ── Lifecycle: fetch history + open SSE stream ──────────────────
+	useEffect(() => {
+		msgsRef.current = [];
+		currentReplyRef.current = null;
+		setMsgs([]);
+		setError(null);
+		clearInterruptTimer();
+		setPhase('idle');
+		setSubagentHitl([]);
+		audioManager?.disposeAll();
+
+		if (!agentId || !sessionId) return;
+
+		const controller = new AbortController();
+		abortRef.current = controller;
+		let cancelled = false;
+
+		(async () => {
+			// 1. Fetch persisted history
+			setLoading(true);
+			try {
+				const { messages, is_running } = await sessionApi.messages(sessionId, agentId);
+				if (cancelled) return;
+				msgsRef.current = messages;
+				// If a reply is in flight (running on a worker) OR the
+				// tail msg is parked on a pending tool_call (awaiting
+				// user confirmation / external execution), initialise the
+				// phase to ``streaming`` so the interrupt button is
+				// available immediately — otherwise a fresh page load
+				// while parked leaves the UI stuck on ``idle`` with no
+				// way to abort.
+				const tail = messages[messages.length - 1];
+				if (is_running || hasPendingToolCall(tail)) {
+					setPhase('streaming');
+					if (hasPendingToolCall(tail)) {
+						// Prime the ref so continuation events (which
+						// arrive without a fresh REPLY_START) apply to
+						// the right msg.
+						currentReplyRef.current = tail ?? null;
+					}
+				}
+				scheduleUpdate();
+			} catch (e) {
+				if (!cancelled) setError(e as Error);
+				return;
+			} finally {
+				if (!cancelled) setLoading(false);
+			}
+
+			// 2. Open SSE long connection for live events
+			try {
+				for await (const event of sessionApi.streamEvents(
+					sessionId,
+					agentId,
+					controller.signal,
+				)) {
+					if (cancelled) break;
+					processEvent(event);
+				}
+			} catch (e) {
+				if ((e as Error).name !== 'AbortError' && !cancelled) {
+					setError(e as Error);
+				}
+			}
+		})();
+
+		return () => {
+			cancelled = true;
+			controller.abort();
+			abortRef.current = null;
+			clearInterruptTimer();
+		};
+	}, [agentId, sessionId, scheduleUpdate, processEvent, audioManager, clearInterruptTimer]);
+
+	/**
+	 * Send a user message. Appends the message to the local list
+	 * optimistically, then fires a ``POST /chat/`` trigger. Events
+	 * arrive via the already-open SSE connection.
+	 *
+	 * @param content - The message content blocks.
+	 */
+	const send = useCallback(
+		async (content: ContentBlock[]) => {
+			if (!agentId || !sessionId) return;
+
+			const userMsg = UserMsg({ name: 'user', content });
+			msgsRef.current = [...msgsRef.current, userMsg];
+			scheduleUpdate();
+
+			try {
+				await chatApi.trigger({
+					agent_id: agentId,
+					session_id: sessionId,
+					input: userMsg,
+				});
+			} catch (e) {
+				setError(e as Error);
+			}
+		},
+		[agentId, sessionId, scheduleUpdate],
+	);
+
+	/**
+	 * Confirm or deny a tool call (human-in-the-loop). Fires a
+	 * ``POST /chat/`` with a ``UserConfirmResultEvent``; events
+	 * arrive via SSE.
+	 *
+	 * @param toolCall - The tool call block to confirm/deny.
+	 * @param confirm - Whether the user confirmed.
+	 * @param replyId - The reply id the tool call belongs to.
+	 * @param rules - Optional permission rules to attach.
+	 */
+	const onUserConfirm = useCallback(
+		async (
+			toolCall: ToolCallBlock,
+			confirm: boolean,
+			replyId: string,
+			rules?: ToolCallBlock['suggested_rules'],
+		) => {
+			if (!agentId || !sessionId) return;
+
+			// Restore the ref so continuation events (no REPLY_START)
+			// have a target.
+			currentReplyRef.current = msgsRef.current.find((m) => m.id === replyId) ?? null;
+
+			const event: UserConfirmResultEvent = {
+				type: EventType.USER_CONFIRM_RESULT,
+				id: crypto.randomUUID(),
+				created_at: new Date().toISOString(),
+				reply_id: replyId,
+				confirm_results: [
+					{ confirmed: confirm, tool_call: toolCall, rules: rules ?? null },
+				],
+			};
+
+			try {
+				await chatApi.trigger({
+					agent_id: agentId,
+					session_id: sessionId,
+					input: event,
+				});
+			} catch (e) {
+				setError(e as Error);
+			}
+		},
+		[agentId, sessionId],
+	);
+
+	/** Abort the current SSE connection. */
+	const abort = useCallback(() => {
+		abortRef.current?.abort();
+	}, []);
+
+	/**
+	 * Request interruption of the in-progress reply (running or parked
+	 * on HITL). Optimistically moves ``phase`` to ``interrupting`` so
+	 * the UI can disable the Stop button; the phase reverts to
+	 * ``idle`` when the backend's terminating ``ReplyEndEvent``
+	 * arrives via SSE (or after a 10s safety timeout, in case that
+	 * event is lost).
+	 *
+	 * Backend contract:
+	 * - 202: interrupt was accepted (cancel signal broadcast for a
+	 *   running reply, or wakeup enqueued for a parked one). The
+	 *   resulting ``ReplyEndEvent`` arrives through the SSE stream and
+	 *   drives the phase transition.
+	 * - Idle sessions are a silent no-op at the agent layer, so
+	 *   spamming this callback is safe.
+	 */
+	const interrupt = useCallback(async () => {
+		if (!agentId || !sessionId) return;
+		// Only escalate to ``interrupting`` if a reply is actually in
+		// flight; if we're already idle (SSE completed just before the
+		// click) leave the phase alone.
+		setPhase((prev) => (prev === 'streaming' ? 'interrupting' : prev));
+		clearInterruptTimer();
+		interruptTimerRef.current = setTimeout(() => {
+			interruptTimerRef.current = null;
+			setPhase((prev) => (prev === 'interrupting' ? 'idle' : prev));
+		}, INTERRUPT_TIMEOUT_MS);
+		try {
+			await sessionApi.interrupt(sessionId, agentId);
+		} catch (e) {
+			clearInterruptTimer();
+			setPhase((prev) => (prev === 'interrupting' ? 'idle' : prev));
+			setError(e as Error);
+		}
+	}, [agentId, sessionId, clearInterruptTimer]);
+
+	/**
+	 * Confirm or deny a tool call that a *team member* is awaiting,
+	 * from this leader view (design §3.6 — backend routing).
+	 *
+	 * The result is POSTed to the **leader** session (the
+	 * ``(agentId, sessionId)`` this hook is bound to), NOT the worker.
+	 * The backend resolves ``reply_id`` → worker session via the
+	 * leader's pending hash and forwards the event to the worker's
+	 * continuation. The client never addresses the worker directly —
+	 * ``entry.worker_*`` ids are used only for local dedup / clearing.
+	 *
+	 * @param entry - The pending subagent HITL entry being resolved.
+	 * @param toolCall - The tool call block to confirm/deny.
+	 * @param confirm - Whether the user confirmed.
+	 * @param rules - Optional permission rules to attach.
+	 */
+	const onSubagentConfirm = useCallback(
+		async (
+			entry: SubagentHitlEntry,
+			toolCall: ToolCallBlock,
+			confirm: boolean,
+			rules?: ToolCallBlock['suggested_rules'],
+		) => {
+			if (!agentId || !sessionId) return;
+
+			const event: UserConfirmResultEvent = {
+				type: EventType.USER_CONFIRM_RESULT,
+				id: crypto.randomUUID(),
+				created_at: new Date().toISOString(),
+				reply_id: entry.reply_id, // worker's reply_id; backend maps it
+				confirm_results: [
+					{ confirmed: confirm, tool_call: toolCall, rules: rules ?? null },
+				],
+			};
+
+			// Optimistically clear; the backend's clear event re-confirms.
+			setSubagentHitl((prev) => prev.filter((x) => hitlKey(x) !== hitlKey(entry)));
+
+			try {
+				// Post to the leader front door — backend routes to the
+				// worker session (§3.6). Do NOT address the worker here.
+				await chatApi.trigger({
+					agent_id: agentId,
+					session_id: sessionId,
+					input: event,
+				});
+			} catch (e) {
+				setError(e as Error);
+			}
+		},
+		[agentId, sessionId],
+	);
+
+	return {
+		msgs,
+		loading,
+		phase,
+		error,
+		send,
+		onUserConfirm,
+		onSubagentConfirm,
+		subagentHitl,
+		abort,
+		interrupt,
+	};
+}
diff --git a/examples/web_ui/frontend/src/hooks/useModels.ts b/examples/web_ui/frontend/src/hooks/useModels.ts
new file mode 100644
index 0000000..fd83acb
--- /dev/null
+++ b/examples/web_ui/frontend/src/hooks/useModels.ts
@@ -0,0 +1,33 @@
+import { useState, useCallback } from 'react';
+
+import { modelApi } from '../api';
+import type { ModelCard } from '../api';
+
+/**
+ * Fetches candidate models for a given provider on demand.
+ * Does not auto-fetch — call `fetch(provider)` explicitly.
+ */
+export function useModels() {
+	const [models, setModels] = useState<ModelCard[]>([]);
+	const [loading, setLoading] = useState(false);
+	const [error, setError] = useState<Error | null>(null);
+
+	/**
+	 * Loads the model list for the specified provider type.
+	 * @param provider - e.g. "openai", "dashscope"
+	 */
+	const fetch = useCallback(async (provider: string) => {
+		setLoading(true);
+		setError(null);
+		try {
+			const res = await modelApi.list(provider);
+			setModels(res.models);
+		} catch (e) {
+			setError(e as Error);
+		} finally {
+			setLoading(false);
+		}
+	}, []);
+
+	return { models, loading, error, fetch };
+}
diff --git a/examples/web_ui/frontend/src/hooks/useSchedules.ts b/examples/web_ui/frontend/src/hooks/useSchedules.ts
new file mode 100644
index 0000000..8ce529b
--- /dev/null
+++ b/examples/web_ui/frontend/src/hooks/useSchedules.ts
@@ -0,0 +1,62 @@
+import { useState, useEffect, useCallback } from 'react';
+
+import { scheduleApi } from '../api';
+import type { ScheduleRecord, CreateScheduleRequest, UpdateScheduleRequest } from '../api';
+
+/**
+ * Manages scheduled agent tasks with CRUD operations.
+ * Fetches on mount and automatically re-fetches after each mutation.
+ */
+export function useSchedules() {
+	const [schedules, setSchedules] = useState<ScheduleRecord[]>([]);
+	const [loading, setLoading] = useState(false);
+	const [error, setError] = useState<Error | null>(null);
+
+	const refetch = useCallback(async () => {
+		setLoading(true);
+		setError(null);
+		try {
+			const res = await scheduleApi.list();
+			setSchedules(res.schedules);
+		} catch (e) {
+			setError(e as Error);
+		} finally {
+			setLoading(false);
+		}
+	}, []);
+
+	useEffect(() => {
+		refetch();
+	}, [refetch]);
+
+	/** Creates a new schedule, registers it with the scheduler, and refreshes the list. */
+	const create = useCallback(
+		async (body: CreateScheduleRequest) => {
+			const res = await scheduleApi.create(body);
+			await refetch();
+			return res;
+		},
+		[refetch],
+	);
+
+	/** Updates a schedule's config, reschedules the job, and refreshes the list. */
+	const update = useCallback(
+		async (scheduleId: string, body: UpdateScheduleRequest) => {
+			const res = await scheduleApi.update(scheduleId, body);
+			await refetch();
+			return res;
+		},
+		[refetch],
+	);
+
+	/** Deletes a schedule, removes the job from the scheduler, and refreshes the list. */
+	const remove = useCallback(
+		async (scheduleId: string) => {
+			await scheduleApi.delete(scheduleId);
+			await refetch();
+		},
+		[refetch],
+	);
+
+	return { schedules, loading, error, refetch, create, update, remove };
+}
diff --git a/examples/web_ui/frontend/src/hooks/useSessions.ts b/examples/web_ui/frontend/src/hooks/useSessions.ts
new file mode 100644
index 0000000..e7b7881
--- /dev/null
+++ b/examples/web_ui/frontend/src/hooks/useSessions.ts
@@ -0,0 +1,76 @@
+import { useState, useEffect, useCallback } from 'react';
+
+import { sessionApi } from '../api';
+import type { SessionView, CreateSessionRequest, UpdateSessionRequest } from '../api';
+
+/**
+ * Manages session views for a given agent.
+ *
+ * Each entry is a `SessionView` (record + is_running + optional team
+ * detail) — the same shape the backend returns. The hook clears and
+ * re-fetches whenever agentId changes.
+ *
+ * @param agentId - The agent whose sessions to load. Pass null to skip fetching.
+ * @returns Object with the loaded `sessions` array plus `loading` /
+ *   `error` flags and `refetch` / `create` / `update` / `remove`
+ *   helpers that all keep the local list in sync.
+ */
+export function useSessions(agentId: string | null) {
+	const [sessions, setSessions] = useState<SessionView[]>([]);
+	const [loading, setLoading] = useState(false);
+	const [error, setError] = useState<Error | null>(null);
+
+	const refetch = useCallback(async () => {
+		if (!agentId) {
+			setSessions([]);
+			return;
+		}
+		setLoading(true);
+		setError(null);
+		try {
+			const res = await sessionApi.list(agentId);
+			setSessions(res.sessions);
+		} catch (e) {
+			setError(e as Error);
+		} finally {
+			setLoading(false);
+		}
+	}, [agentId]);
+
+	useEffect(() => {
+		refetch();
+	}, [refetch]);
+
+	/** Creates a new session and refreshes the list. */
+	const create = useCallback(
+		async (body: CreateSessionRequest) => {
+			const res = await sessionApi.create(body);
+			await refetch();
+			return res;
+		},
+		[refetch],
+	);
+
+	/** Updates a session's model config and refreshes the list. */
+	const update = useCallback(
+		async (sessionId: string, body: UpdateSessionRequest) => {
+			if (!agentId) throw new Error('No agent selected');
+			const res = await sessionApi.update(sessionId, agentId, body);
+			await refetch();
+			return res;
+		},
+		[agentId, refetch],
+	);
+
+	/** Deletes a session and refreshes the list. */
+	const remove = useCallback(
+		async (sessionId: string) => {
+			if (!agentId) throw new Error('No agent selected');
+			await sessionApi.delete(sessionId, agentId);
+			await refetch();
+		},
+		[agentId, refetch],
+	);
+
+	return { sessions, loading, error, refetch, create, update, remove };
+}
diff --git a/examples/web_ui/frontend/src/hooks/useSkills.ts b/examples/web_ui/frontend/src/hooks/useSkills.ts
new file mode 100644
index 0000000..25ed59f
--- /dev/null
+++ b/examples/web_ui/frontend/src/hooks/useSkills.ts
@@ -0,0 +1,59 @@
+import { useState, useEffect, useCallback } from 'react';
+
+import { workspaceApi } from '../api';
+import type { Skill } from '../api';
+
+/**
+ * Manages skills available in a session's workspace.
+ * Re-fetches whenever agentId or sessionId changes.
+ *
+ * @param agentId   - The owning agent. Pass null to skip fetching.
+ * @param sessionId - The target session. Pass null to skip fetching.
+ */
+export function useSkills(agentId: string | null, sessionId: string | null) {
+	const [skills, setSkills] = useState<Skill[]>([]);
+	const [loading, setLoading] = useState(false);
+	const [error, setError] = useState<Error | null>(null);
+
+	const refetch = useCallback(async () => {
+		if (!agentId || !sessionId) {
+			setSkills([]);
+			return;
+		}
+		setLoading(true);
+		setError(null);
+		try {
+			setSkills(await workspaceApi.skill.list(agentId, sessionId));
+		} catch (e) {
+			setError(e as Error);
+		} finally {
+			setLoading(false);
+		}
+	}, [agentId, sessionId]);
+
+	useEffect(() => {
+		refetch();
+	}, [refetch]);
+
+	/** Adds a skill from the given path and refreshes the list. */
+	const add = useCallback(
+		async (skillPath: string) => {
+			if (!agentId || !sessionId) throw new Error('No agent/session selected');
+			await workspaceApi.skill.add(agentId, sessionId, { skill_path: skillPath });
+			await refetch();
+		},
+		[agentId, sessionId, refetch],
+	);
+
+	/** Removes a skill by name and refreshes the list. */
+	const remove = useCallback(
+		async (skillName: string) => {
+			if (!agentId || !sessionId) throw new Error('No agent/session selected');
+			await workspaceApi.skill.remove(skillName, agentId, sessionId);
+			await refetch();
+		},
+		[agentId, sessionId, refetch],
+	);
+
+	return { skills, loading, error, refetch, add, remove };
+}
diff --git a/examples/web_ui/frontend/src/hooks/useWorkspace.ts b/examples/web_ui/frontend/src/hooks/useWorkspace.ts
new file mode 100644
index 0000000..0dd8bfc
--- /dev/null
+++ b/examples/web_ui/frontend/src/hooks/useWorkspace.ts
@@ -0,0 +1,114 @@
+import { useState, useEffect, useCallback } from 'react';
+
+import { workspaceApi } from '@/api';
+import type { MCPClient, MCPClientStatus, Skill } from '@/api';
+
+export function useWorkspace(agentId: string | null, sessionId: string | null) {
+	const [mcps, setMcps] = useState<MCPClientStatus[]>([]);
+	const [skills, setSkills] = useState<Skill[]>([]);
+	const [loading, setLoading] = useState(false);
+	const [skillsLoading, setSkillsLoading] = useState(false);
+	const [error, setError] = useState<Error | null>(null);
+
+	const refetch = useCallback(async () => {
+		if (!agentId || !sessionId) {
+			setMcps([]);
+			return;
+		}
+		setLoading(true);
+		setError(null);
+		try {
+			setMcps(await workspaceApi.mcp.list(agentId, sessionId));
+		} catch (e) {
+			setError(e as Error);
+		} finally {
+			setLoading(false);
+		}
+	}, [agentId, sessionId]);
+
+	const refetchSkills = useCallback(async () => {
+		if (!agentId || !sessionId) {
+			setSkills([]);
+			return;
+		}
+		setSkillsLoading(true);
+		try {
+			setSkills(await workspaceApi.skill.list(agentId, sessionId));
+		} catch (e) {
+			setError(e as Error);
+		} finally {
+			setSkillsLoading(false);
+		}
+	}, [agentId, sessionId]);
+
+	useEffect(() => {
+		refetch();
+	}, [refetch]);
+	useEffect(() => {
+		refetchSkills();
+	}, [refetchSkills]);
+
+	const addMcps = useCallback(
+		async (clients: MCPClient[]) => {
+			if (!agentId || !sessionId) throw new Error('No agent/session selected');
+			const existingNames = new Set(mcps.map((m) => m.name));
+			for (const mcp of clients) {
+				if (existingNames.has(mcp.name)) {
+					throw new Error(`MCP server "${mcp.name}" already exists in this workspace.`);
+				}
+			}
+			const batchNames = new Set<string>();
+			for (const mcp of clients) {
+				if (batchNames.has(mcp.name)) {
+					throw new Error(`Duplicate MCP server name "${mcp.name}" in configuration.`);
+				}
+				batchNames.add(mcp.name);
+			}
+			for (const mcp of clients) {
+				await workspaceApi.mcp.add(agentId, sessionId, mcp);
+			}
+			await refetch();
+		},
+		[agentId, sessionId, mcps, refetch],
+	);
+
+	const removeMcp = useCallback(
+		async (mcpName: string) => {
+			if (!agentId || !sessionId) throw new Error('No agent/session selected');
+			await workspaceApi.mcp.remove(mcpName, agentId, sessionId);
+			await refetch();
+		},
+		[agentId, sessionId, refetch],
+	);
+
+	const addSkill = useCallback(
+		async (skillPath: string) => {
+			if (!agentId || !sessionId) throw new Error('No agent/session selected');
+			await workspaceApi.skill.add(agentId, sessionId, { skill_path: skillPath });
+			await refetchSkills();
+		},
+		[agentId, sessionId, refetchSkills],
+	);
+
+	const removeSkill = useCallback(
+		async (skillName: string) => {
+			if (!agentId || !sessionId) throw new Error('No agent/session selected');
+			await workspaceApi.skill.remove(skillName, agentId, sessionId);
+			await refetchSkills();
+		},
+		[agentId, sessionId, refetchSkills],
+	);
+
+	return {
+		mcps,
+		loading,
+		error,
+		refetch,
+		addMcps,
+		removeMcp,
+		skills,
+		skillsLoading,
+		addSkill,
+		removeSkill,
+	};
+}
diff --git a/examples/web_ui/frontend/src/i18n/index.ts b/examples/web_ui/frontend/src/i18n/index.ts
new file mode 100644
index 0000000..a6750f4
--- /dev/null
+++ b/examples/web_ui/frontend/src/i18n/index.ts
@@ -0,0 +1,25 @@
+import i18n from 'i18next';
+import LanguageDetector from 'i18next-browser-languagedetector';
+import { initReactI18next } from 'react-i18next';
+
+import enTranslations from './locales/en.json';
+import zhTranslations from './locales/zh.json';
+
+i18n.use(LanguageDetector)
+	.use(initReactI18next)
+	.init({
+		resources: {
+			en: { translation: enTranslations },
+			zh: { translation: zhTranslations },
+		},
+		fallbackLng: 'en',
+		interpolation: {
+			escapeValue: false,
+		},
+		detection: {
+			order: ['localStorage', 'navigator'],
+			caches: ['localStorage'],
+		},
+	});
+
+export default i18n;
diff --git a/examples/web_ui/frontend/src/i18n/locales/en.json b/examples/web_ui/frontend/src/i18n/locales/en.json
new file mode 100644
index 0000000..0578bd1
--- /dev/null
+++ b/examples/web_ui/frontend/src/i18n/locales/en.json
@@ -0,0 +1,556 @@
+{
+	"common": {
+		"add": "Add",
+		"agent": "Agent",
+		"cancel": "Cancel",
+		"chat": "Chat",
+		"close": "Close",
+		"confirm": "Confirm",
+		"create": "Create",
+		"creating": "Creating…",
+		"credential": "Credentials",
+		"date": "Date",
+		"delete": "Delete",
+		"deleting": "Deleting…",
+		"disabled": "Disabled",
+		"edit": "Edit",
+		"error": "Something went wrong",
+		"information": "Information",
+		"interrupted": "Interrupted",
+		"knowledge": "Knowledge Bases",
+		"loading": "Loading...",
+		"model": "Model",
+		"name": "Name",
+		"no": "No",
+		"noData": "No data",
+		"readOnly": "Read-only",
+		"readOnlyTooltip": "Shared with you as read-only; editing and deletion are disabled.",
+		"completed": "Completed",
+		"failed": "Failed",
+		"running": "Running",
+		"save": "Save",
+		"saving": "Saving…",
+		"schedule": "Schedule",
+		"selectAgent": "Select an agent",
+		"settings": "Settings",
+		"switchToZh": "切换为中文",
+		"switchToEn": "Switch to English",
+		"success": "Success",
+		"team": "Team",
+		"leader": "Leader",
+		"worker": "Worker",
+		"time": "Time",
+		"yes": "Yes",
+		"deleteTitle": "Delete {{entity}} \"{{name}}\"?",
+		"deleteDescription": "This action cannot be undone."
+	},
+	"error": {
+		"description": "The page hit an unexpected error. You can retry or go back home.",
+		"retry": "Retry",
+		"home": "Back to home"
+	},
+	"tool": {
+		"moreLines": "... {{count}} more lines",
+		"read": {
+			"name": "Read",
+			"fileCount_one": "{{count}} file",
+			"fileCount_other": "{{count}} files",
+			"lineCount_one": "Read {{formatted}} line",
+			"lineCount_other": "Read {{formatted}} lines"
+		},
+		"glob": {
+			"name": "Glob"
+		},
+		"taskCreate": {
+			"name": "TaskCreate",
+			"label": "Create",
+			"count_one": "{{count}} task",
+			"count_other": "{{count}} tasks"
+		},
+		"grep": {
+			"name": "Grep"
+		}
+	},
+	"textInput": {
+		"toComplete": "to complete",
+		"newLine": "new line",
+		"attach": "Attach file",
+		"attachNotSupported": "This model does not support file attachments",
+		"send": "Send",
+		"stop": "Stop generating",
+		"stopping": "Stopping ..."
+	},
+	"confirmCard": {
+		"toConfirm": "to confirm",
+		"yesWithRule": "Yes, and allow {{toolName}} to execute {{ruleContent}} for this session"
+	},
+	"messageBubble": {
+		"thinking": "Thinking",
+		"audioGenerating": "Generating audio…",
+		"playAudio": "Play audio",
+		"pauseAudio": "Pause audio",
+		"running": "Running...",
+		"hintSource": {
+			"tool_output": "Tool Output",
+			"team_message": "Team Message",
+			"schedule": "Schedule"
+		}
+	},
+	"chat": {
+		"inputPlaceholder": "Type a message...",
+		"placeholder": "Type a message...",
+		"send": "Send",
+		"confirmToolCall": "Allow this action?",
+		"subagentConfirmTitle": "{{name}} requests confirmation",
+		"newSession": "New Session",
+		"noSessions": "No sessions yet",
+		"noMessages": "No Messages Yet",
+		"noMessagesDesc": "Start your conversation by sending a message",
+		"agent": {
+			"selectPlaceholder": "Select an agent",
+			"emptyTitle": "No agents",
+			"emptyDescription": "Create an agent to get started.",
+			"groupYours": "Yours",
+			"groupShared": "Shared with you"
+		},
+		"session": {
+			"label": "Session",
+			"emptyTitle": "No sessions",
+			"emptyNoAgent": "Select an agent first.",
+			"emptyHasAgent": "Create a session to start chatting."
+		}
+	},
+	"dialog-agent-create": {
+		"title": "Create agent",
+		"description": "Define a new agent's identity and behaviour.",
+		"trigger": "Create agent"
+	},
+	"agent-form": {
+		"identity": {
+			"legend": "Agent Identity",
+			"description": "Name and instructions that define this agent's behaviour.",
+			"name": { "label": "Name", "placeholder": "My agent" },
+			"system-prompt": { "label": "System prompt" }
+		},
+		"context-config": {
+			"legend": "Context Config",
+			"description": "Controls how the context window is managed and compressed.",
+			"trigger-ratio": { "label": "Trigger ratio" },
+			"reserve-ratio": { "label": "Reserve ratio" },
+			"tool-result-limit": { "label": "Tool result limit" },
+			"compression-prompt": { "label": "Compression prompt" },
+			"summary-template": { "label": "Summary template" }
+		},
+		"react-config": {
+			"legend": "ReAct Config",
+			"description": "Controls the reasoning and action loop behaviour.",
+			"max-iters": { "label": "Max iterations" },
+			"stop-on-reject": { "label": "Stop on reject" }
+		},
+		"invite-config": {
+			"legend": "Invite Config",
+			"description": "Controls whether other agents can borrow this one via AgentInvite.",
+			"invitable": { "label": "Invitable" },
+			"invite-description": {
+				"label": "Invite description",
+				"placeholder": "Briefly describe this agent's expertise; required when invitable is on."
+			}
+		}
+	},
+	"dialog-agent-edit": {
+		"title": "Edit agent",
+		"description": "Update this agent's configuration."
+	},
+	"dialog-agent-delete": {
+		"entity": "agent",
+		"confirm": "Delete"
+	},
+	"dialog-session-delete": {
+		"entity": "session",
+		"confirm": "Delete"
+	},
+	"dialog-session-rename": {
+		"title": "Rename session",
+		"description": "Give this session a new name.",
+		"label": "Name",
+		"placeholder": "Session name"
+	},
+	"session-menu": {
+		"rename": "Rename",
+		"delete": "Delete"
+	},
+	"dialog-credential-create": {
+		"title": "Add credential",
+		"description": "Add credentials for a model provider.",
+		"selectType": "Provider",
+		"selectTypePlaceholder": "Select a provider"
+	},
+	"dialog-credential-edit": {
+		"title": "Edit Credential",
+		"description": "Update the saved credential for this provider."
+	},
+	"dialog-knowledge-base-create": {
+		"title": "Create knowledge base",
+		"description": "Create a new knowledge base using an embedding model.",
+		"name": {
+			"label": "Name",
+			"placeholder": "My knowledge base"
+		},
+		"descriptionField": {
+			"label": "Description",
+			"placeholder": "Describe what this knowledge base is for."
+		},
+		"embeddingModel": {
+			"label": "Embedding model"
+		},
+		"dimension": {
+			"label": "Dimension"
+		},
+		"policy": {
+			"lockedTitle": "Dimension is locked to {{dimension}}d",
+			"lockedDescription": "This server already pins all knowledge bases to {{dimension}}-dim embeddings. Only compatible models are listed below.",
+			"noCompatibleTitle": "No compatible embedding models",
+			"noCompatibleAny": "None of your credentials expose an embedding model. Add a credential first.",
+			"noCompatibleLocked": "None of your credentials expose a model that can produce {{dimension}}-dim embeddings."
+		},
+		"errors": {
+			"nameRequired": "Please give the knowledge base a name.",
+			"embeddingRequired": "Please pick an embedding model.",
+			"dimensionRequired": "Please pick a dimension."
+		}
+	},
+	"dialog-knowledge-base-edit": {
+		"title": "Edit knowledge base",
+		"description": "Update the knowledge base name and description.",
+		"name": {
+			"label": "Name",
+			"placeholder": "My knowledge base"
+		},
+		"descriptionField": {
+			"label": "Description",
+			"placeholder": "Describe what this knowledge base is for."
+		},
+		"embeddingModel": {
+			"label": "Embedding model"
+		},
+		"errors": {
+			"nameRequired": "Please give the knowledge base a name."
+		}
+	},
+	"dialog-knowledge-base-delete": {
+		"title": "Delete knowledge base",
+		"description": "This will permanently delete the knowledge base \"{{name}}\" and all of its indexed documents. This action cannot be undone."
+	},
+	"credential": {
+		"noProviders": "No providers available",
+		"noConfigs": "No configurations",
+		"selectHint": "No credential selected",
+		"selectHintDescription": "Select a credential from the sidebar to view its details.",
+		"availableModels": "Available Models",
+		"noModels": "No models available",
+		"noModelsDescription": "This provider returned no models.",
+		"deleteEntity": "credential",
+		"subtitle": "Model API credential configuration",
+		"configured": "Configured",
+		"addProvider": "Add credential",
+		"reasoning": "Reasoning",
+		"maxContext": "Max. Context",
+		"maxOutput": "Max. Output",
+		"inputTypes": "Input",
+		"outputTypes": "Output",
+		"availableTTSModels": "TTS Models"
+	},
+	"knowledge": {
+		"subtitle": "Manage knowledge bases used by your agents",
+		"selectHint": "No knowledge base selected",
+		"selectHintDescription": "Select a knowledge base from the sidebar to view its details.",
+		"deleteEntity": "knowledge base",
+		"list": {
+			"label": "Knowledge bases",
+			"emptyTitle": "No knowledge bases",
+			"emptyDescription": "Create a knowledge base to start indexing documents.",
+			"createButton": "Create knowledge base"
+		},
+		"document": {
+			"label": "Documents",
+			"emptyTitle": "No documents",
+			"emptyDescription": "Upload a document to index it into this knowledge base.",
+			"uploadButton": "Upload document",
+			"uploadButtonShort": "Upload",
+			"countLabel": "Documents ({{count}})",
+			"size": "Size",
+			"chunks": "Chunks",
+			"chunkCount_one": "{{count}} chunk",
+			"chunkCount_other": "{{count}} chunks",
+			"uploadedAt": "Uploaded {{when}}",
+			"deleteEntity": "document",
+			"deleteConfirmTitle": "Delete document",
+			"deleteConfirmDescription": "Delete \"{{name}}\"? This removes the document and every indexed chunk. This action cannot be undone.",
+			"deleteError": "Could not delete document.",
+			"dropHint": "Drop files here to upload",
+			"dropHintIdle": "or drop files here",
+			"invalidFile": "\"{{name}}\" could not be added.",
+			"unsupportedExtension": "\"{{name}}\" was skipped — file type not supported.",
+			"status": {
+				"queued": "Queued",
+				"uploading": "Uploading",
+				"pending": "Awaiting worker",
+				"parsing": "Parsing",
+				"chunking": "Chunking",
+				"indexing": "Indexing",
+				"ready": "Ready",
+				"error": "Error",
+				"cancelled": "Cancelled"
+			},
+			"actions": {
+				"cancel": "Cancel",
+				"retry": "Retry",
+				"dismiss": "Dismiss",
+				"remove": "Remove",
+				"clearFinished": "Clear finished"
+			}
+		},
+		"test": {
+			"button": "Test",
+			"title": "Test retrieval",
+			"description": "Probe \"{{name}}\" with an ad-hoc query.",
+			"queryLabel": "Query",
+			"queryPlaceholder": "Type a natural-language question…",
+			"topKLabel": "Top K",
+			"searchButton": "Search",
+			"score": "score",
+			"chunkPosition": "Chunk {{index}} of {{total}}",
+			"emptyTitle": "No matches",
+			"emptyDescription": "No chunks scored above the threshold for this query."
+		}
+	},
+	"llm-select": {
+		"placeholder": "Select a model",
+		"fallbackPlaceholder": "Fallback model",
+		"loading": "Loading…",
+		"empty": {
+			"title": "No models available",
+			"description": "Add a credential to get started.",
+			"addButton": "Add credential"
+		},
+		"addCredential": "Add Credential",
+		"clear": "Clear selection",
+		"noFallback": "No fallback"
+	},
+	"embedding-select": {
+		"placeholder": "Select an embedding model",
+		"loading": "Loading…",
+		"empty": {
+			"title": "No embedding models available",
+			"description": "Add a credential that supports embedding to get started."
+		},
+		"addCredential": "Add Credential",
+		"clear": "Clear selection"
+	},
+	"dimension-select": {
+		"placeholder": "Select a dimension",
+		"pickModelFirst": "Pick a model first"
+	},
+	"permission-mode": {
+		"placeholder": "Select permission mode",
+		"trigger-tooltip": "Permission Mode",
+		"label": "Permission Mode",
+		"default-tooltip": "Default mode: all operations require explicit permission (most secure)",
+		"accept_edits-tooltip": "Auto-allow file reads/writes in working directories and filesystem commands; other operations follow normal rules",
+		"explore-tooltip": "Read-only mode: allow read/grep/glob tools, deny write/edit/bash modification tools",
+		"bypass-tooltip": "All operations automatically allowed without any permission checks (use in trusted/sandbox environments)",
+		"dont_ask-tooltip": "Convert all ASK decisions to DENY; suitable for scheduled tasks or background execution when user is unavailable"
+	},
+	"dialog-mcp-create": {
+		"title": "Add MCP Servers",
+		"description": "Add new MCP server(s) by configuration.",
+		"configLabel": "MCP Configuration",
+		"keepAlive": "Keep Alive",
+		"keepAliveDesc": "Maintain state across interactions. Enable for browser-use or other long-running MCPs.",
+		"adding": "Adding…",
+		"added": "Added",
+		"parseError": "Invalid JSON configuration: {{message}}",
+		"missingMcpServers": "Configuration must contain a \"mcpServers\" object.",
+		"emptyMcpServers": "No MCP servers found in configuration."
+	},
+	"dialog-mcp-delete": {
+		"entity": "MCP server",
+		"skillEntity": "skill",
+		"skillDescription": "Are you sure you want to remove this skill from the workspace?"
+	},
+	"dialog-skill-add": {
+		"title": "Add skill",
+		"description": "Enter the path to a skill directory to add it to the workspace.",
+		"pathLabel": "Skill path",
+		"pathPlaceholder": "/path/to/skill"
+	},
+	"schedule": {
+		"calendar": "Calendar",
+		"createSchedule": {
+			"description": "Set up a recurring or one-time scheduled task for an agent.",
+			"descriptionLabel": "Description",
+			"descriptionPlaceholder": "Describe what this schedule should do...",
+			"namePlaceholder": "e.g. Daily Report",
+			"title": "Create Schedule"
+		},
+		"deleteSchedule": {
+			"entity": "schedule",
+			"successToast": "Schedule deleted successfully."
+		},
+		"endAt": "End Date",
+		"end_at": "End At",
+		"executionHistory": "Execution History",
+		"freqDaily": "Daily",
+		"freqMonthly": "Monthly",
+		"freqOnce": "Once",
+		"freqWeekly": "Weekly",
+		"frequency": "Frequency",
+		"friday": "Fri",
+		"list": "List",
+		"monday": "Mon",
+		"more": "more",
+		"nextMonth": "Next Month",
+		"nextYear": "Next Year",
+		"noExecutions": "No executions yet",
+		"noExecutionsDescription": "This schedule has not been executed yet.",
+		"noSchedules": "No schedules",
+		"noSchedulesDescription": "Create a schedule to automate agent tasks.",
+		"pickDate": "Pick a date",
+		"permissionMode": "Permission Mode",
+		"timezone": "Timezone",
+		"triggerTime": "Trigger Time",
+		"createdAt": "Created At",
+		"dayOfMonthSuffix": "",
+		"stateful": "Stateful",
+		"statefulDesc": "Reuse one session across all fires to accumulate context. Disabled: every fire creates a fresh session.",
+		"previousMonth": "Previous Month",
+		"previousYear": "Previous Year",
+		"saturday": "Sat",
+		"startAt": "Start At",
+		"sunday": "Sun",
+		"thursday": "Thu",
+		"today": "Today",
+		"tuesday": "Tue",
+		"wednesday": "Wed"
+	},
+	"model-parameters": {
+		"title": "Model Parameters",
+		"description": "Adjust inference parameters for the selected model.",
+		"empty": "No configurable parameters.",
+		"fallbackLabel": "Fallback model",
+		"fallbackLabelWithModel": "Fallback model ({{model}})",
+		"parametersLabel": "Parameters",
+		"ttsLabel": "TTS",
+		"ttsEmpty": "No TTS models available.",
+		"ttsParameters": "Parameters",
+		"ttsParametersDescription": "Adjust parameters for the selected TTS model.",
+		"noTts": "No TTS"
+	},
+	"setup": {
+		"title": "Connect to Service",
+		"description": "Enter your server URL and username to get started.",
+		"serverUrl": "Server URL",
+		"serverUrlPlaceholder": "https://...",
+		"username": "Username",
+		"usernamePlaceholder": "Your username",
+		"submit": "Get Started",
+		"hint": "This is a frontend-only application, and all data are served from the Server URL above. The username is used solely for server-side authentication."
+	},
+	"tour": {
+		"trigger": "Take a tour",
+		"prev": "Back",
+		"next": "Next",
+		"finish": "Finish",
+		"skip": "Skip",
+		"step": "Step {{current}} / {{total}}",
+		"createAgent": {
+			"title": "Create an agent",
+			"content": "Start by creating an agent — your chat partner."
+		},
+		"createSession": {
+			"title": "Create a session",
+			"content": "Click + to start a new session."
+		},
+		"llmSelect": {
+			"title": "Pick a model",
+			"content": "Choose a model; add a credential from the dropdown if needed."
+		},
+		"permissionMode": {
+			"title": "Permission mode",
+			"content": "Decide whether tool calls need confirmation."
+		},
+		"chatInput": {
+			"title": "Start chatting",
+			"content": "Type a message and press Enter. Paperclip attaches files."
+		}
+	},
+	"task-panel": {
+		"heading": "Tasks",
+		"noTasks": "No tasks yet.",
+		"pending": "Pending",
+		"inProgress": "In Progress",
+		"completed": "Completed",
+		"blockedBy": "blocked by"
+	},
+	"panel": {
+		"plan": {
+			"title": "Plan",
+			"completed": "Completed: {{count}}",
+			"total": "Total: {{count}}",
+			"emptyTitle": "No tasks yet",
+			"emptyDescription": "Tasks the agent plans will show up here."
+		},
+		"mcp": {
+			"title": "MCP",
+			"description": "The MCP servers equipped in the workspace.",
+			"searchPlaceholder": "Search MCP in the workspace",
+			"add": "Add MCP",
+			"tools": "{{count}} tools",
+			"emptyTitle": "No MCP servers",
+			"emptyDescription": "Add an MCP server to equip the workspace with tools."
+		},
+		"skill": {
+			"title": "Skills",
+			"description": "The skills equipped in the workspace.",
+			"searchPlaceholder": "Search skills in the workspace",
+			"add": "Add Skill",
+			"emptyTitle": "No skills",
+			"emptyDescription": "Add a skill to equip the workspace."
+		},
+		"knowledge": {
+			"title": "Knowledge Bases",
+			"description": "Knowledge bases the agent can retrieve from.",
+			"searchPlaceholder": "Search knowledge bases",
+			"emptyTitle": "No knowledge bases",
+			"emptyDescription": "Create one on the Knowledge Bases page first.",
+			"parametersTitle": "Retrieval settings",
+			"parametersDescription": "Knowledge base retrieval settings.",
+			"selectedCount": "{{count}} attached"
+		},
+		"permission": {
+			"title": "Permissions",
+			"description": "The permissions applied in this session.",
+			"mode": "Mode: {{mode}}",
+			"workingDirectories": "Working Directories",
+			"noWorkingDirectories": "No working directories.",
+			"allow": "Allow",
+			"deny": "Deny",
+			"ask": "Ask",
+			"anyInvocation": "any invocation",
+			"emptyTitle": "No rules configured",
+			"emptyDescription": "Allow / deny / ask rules will appear here as they are added."
+		},
+		"search": {
+			"emptyTitle": "No results",
+			"emptyDescription": "Nothing matches “{{query}}”."
+		},
+		"loading": "Loading…"
+	},
+	"team-sidebar": {
+		"membersHeading": "Members",
+		"noMembers": "No members yet — ask the leader to spawn one with AgentCreate.",
+		"running": "Running",
+		"idle": "Idle",
+		"missingSession": "(no session)"
+	}
+}
diff --git a/examples/web_ui/frontend/src/i18n/locales/zh.json b/examples/web_ui/frontend/src/i18n/locales/zh.json
new file mode 100644
index 0000000..27e8c39
--- /dev/null
+++ b/examples/web_ui/frontend/src/i18n/locales/zh.json
@@ -0,0 +1,556 @@
+{
+	"common": {
+		"add": "添加",
+		"agent": "Agent",
+		"cancel": "取消",
+		"chat": "聊天",
+		"close": "关闭",
+		"confirm": "确认",
+		"create": "创建",
+		"creating": "创建中…",
+		"credential": "凭证",
+		"date": "日期",
+		"delete": "删除",
+		"deleting": "删除中…",
+		"disabled": "已禁用",
+		"edit": "编辑",
+		"error": "出错了",
+		"information": "信息",
+		"interrupted": "已中断",
+		"knowledge": "知识库",
+		"loading": "加载中...",
+		"model": "模型",
+		"name": "名称",
+		"no": "否",
+		"noData": "暂无数据",
+		"readOnly": "只读",
+		"readOnlyTooltip": "该资源以只读方式共享给你，编辑和删除均被禁用。",
+		"completed": "已完成",
+		"failed": "已失败",
+		"running": "运行中",
+		"save": "保存",
+		"saving": "保存中…",
+		"schedule": "日程",
+		"selectAgent": "选择 Agent",
+		"settings": "设置",
+		"switchToZh": "切换为中文",
+		"switchToEn": "Switch to English",
+		"success": "成功",
+		"team": "团队",
+		"leader": "队长",
+		"worker": "成员",
+		"time": "时间",
+		"yes": "是",
+		"deleteTitle": "删除{{entity}} \"{{name}}\"？",
+		"deleteDescription": "此操作无法撤销。"
+	},
+	"error": {
+		"description": "页面遇到意外错误。你可以重试或返回首页。",
+		"retry": "重试",
+		"home": "返回首页"
+	},
+	"tool": {
+		"moreLines": "... 还有 {{count}} 行",
+		"read": {
+			"name": "读取",
+			"fileCount_one": "{{count}} 个文件",
+			"fileCount_other": "{{count}} 个文件",
+			"lineCount_one": "读取 {{formatted}} 行",
+			"lineCount_other": "读取 {{formatted}} 行"
+		},
+		"glob": {
+			"name": "Glob"
+		},
+		"taskCreate": {
+			"name": "TaskCreate",
+			"label": "创建",
+			"count_one": "{{count}} 个任务",
+			"count_other": "{{count}} 个任务"
+		},
+		"grep": {
+			"name": "Grep"
+		}
+	},
+	"textInput": {
+		"toComplete": "补全",
+		"newLine": "换行",
+		"attach": "添加附件",
+		"attachNotSupported": "当前模型不支持文件附件",
+		"send": "发送",
+		"stop": "停止生成",
+		"stopping": "停止中 ..."
+	},
+	"confirmCard": {
+		"toConfirm": "确认",
+		"yesWithRule": "是，且该次对话中都允许 {{toolName}} 执行 {{ruleContent}}"
+	},
+	"messageBubble": {
+		"thinking": "思考中",
+		"audioGenerating": "正在生成音频…",
+		"playAudio": "播放音频",
+		"pauseAudio": "暂停音频",
+		"running": "运行中...",
+		"hintSource": {
+			"tool_output": "工具输出",
+			"team_message": "团队消息",
+			"schedule": "定时任务"
+		}
+	},
+	"chat": {
+		"inputPlaceholder": "输入消息...",
+		"placeholder": "输入消息...",
+		"send": "发送",
+		"confirmToolCall": "允许此操作？",
+		"subagentConfirmTitle": "{{name}} 请求确认",
+		"newSession": "新会话",
+		"noSessions": "暂无会话",
+		"noMessages": "暂无消息",
+		"noMessagesDesc": "发送一条消息开始新的对话",
+		"agent": {
+			"selectPlaceholder": "选择 Agent",
+			"emptyTitle": "暂无 Agent",
+			"emptyDescription": "创建一个 Agent 开始使用。",
+			"groupYours": "我的",
+			"groupShared": "共享给我"
+		},
+		"session": {
+			"label": "会话",
+			"emptyTitle": "暂无会话",
+			"emptyNoAgent": "请先选择一个 Agent。",
+			"emptyHasAgent": "创建会话开始对话。"
+		}
+	},
+	"dialog-agent-create": {
+		"title": "创建 Agent",
+		"description": "定义新 Agent 的身份与行为。",
+		"trigger": "创建 Agent"
+	},
+	"agent-form": {
+		"identity": {
+			"legend": "Agent 身份",
+			"description": "定义此 Agent 行为的名称和指令。",
+			"name": { "label": "名称", "placeholder": "我的 Agent" },
+			"system-prompt": { "label": "系统提示词" }
+		},
+		"context-config": {
+			"legend": "上下文配置",
+			"description": "控制上下文窗口的管理和压缩方式。",
+			"trigger-ratio": { "label": "触发比例" },
+			"reserve-ratio": { "label": "保留比例" },
+			"tool-result-limit": { "label": "工具结果限制" },
+			"compression-prompt": { "label": "压缩提示词" },
+			"summary-template": { "label": "摘要模板" }
+		},
+		"react-config": {
+			"legend": "ReAct 配置",
+			"description": "控制推理和行动循环的行为。",
+			"max-iters": { "label": "最大迭代次数" },
+			"stop-on-reject": { "label": "拒绝时停止" }
+		},
+		"invite-config": {
+			"legend": "邀请配置",
+			"description": "控制此 Agent 是否可被其他 Agent 通过 AgentInvite 邀请。",
+			"invitable": { "label": "允许被邀请" },
+			"invite-description": {
+				"label": "邀请说明",
+				"placeholder": "简要描述此 Agent 的专长；允许被邀请时必填。"
+			}
+		}
+	},
+	"dialog-agent-edit": {
+		"title": "编辑 Agent",
+		"description": "更新此 Agent 的配置。"
+	},
+	"dialog-agent-delete": {
+		"entity": "Agent",
+		"confirm": "删除"
+	},
+	"dialog-session-delete": {
+		"entity": "会话",
+		"confirm": "删除"
+	},
+	"dialog-session-rename": {
+		"title": "重命名会话",
+		"description": "为该会话设置新名称。",
+		"label": "名称",
+		"placeholder": "会话名称"
+	},
+	"session-menu": {
+		"rename": "重命名",
+		"delete": "删除"
+	},
+	"dialog-credential-create": {
+		"title": "添加凭证",
+		"description": "为模型提供商添加凭证。",
+		"selectType": "提供商",
+		"selectTypePlaceholder": "选择提供商"
+	},
+	"dialog-credential-edit": {
+		"title": "编辑凭证",
+		"description": "更新该提供商已保存的凭证。"
+	},
+	"dialog-knowledge-base-create": {
+		"title": "创建知识库",
+		"description": "使用 Embedding 模型创建新的知识库。",
+		"name": {
+			"label": "名称",
+			"placeholder": "我的知识库"
+		},
+		"descriptionField": {
+			"label": "描述",
+			"placeholder": "描述知识库用途"
+		},
+		"embeddingModel": {
+			"label": "Embedding 模型"
+		},
+		"dimension": {
+			"label": "维度"
+		},
+		"policy": {
+			"lockedTitle": "维度已锁定为 {{dimension}}d",
+			"lockedDescription": "当前实例已要求所有知识库使用 {{dimension}} 维 embedding，下面仅展示兼容的模型。",
+			"noCompatibleTitle": "暂无可用 Embedding 模型",
+			"noCompatibleAny": "你的凭证中没有任何可用的 Embedding 模型，请先添加凭证。",
+			"noCompatibleLocked": "你的凭证中没有任何模型支持 {{dimension}} 维 embedding。"
+		},
+		"errors": {
+			"nameRequired": "请填写知识库名称。",
+			"embeddingRequired": "请选择 Embedding 模型。",
+			"dimensionRequired": "请选择 Embedding 维度。"
+		}
+	},
+	"dialog-knowledge-base-edit": {
+		"title": "编辑知识库",
+		"description": "修改知识库的名称与描述。",
+		"name": {
+			"label": "名称",
+			"placeholder": "我的知识库"
+		},
+		"descriptionField": {
+			"label": "描述",
+			"placeholder": "描述知识库用途"
+		},
+		"embeddingModel": {
+			"label": "Embedding 模型"
+		},
+		"errors": {
+			"nameRequired": "请填写知识库名称。"
+		}
+	},
+	"dialog-knowledge-base-delete": {
+		"title": "删除知识库",
+		"description": "此操作将永久删除知识库 \"{{name}}\" 及其所有已索引文档，且无法撤销。"
+	},
+	"credential": {
+		"noProviders": "暂无可用提供商",
+		"noConfigs": "暂无配置",
+		"selectHint": "未选择凭证",
+		"selectHintDescription": "从左侧选择一个凭证以查看详情。",
+		"availableModels": "可用模型",
+		"noModels": "暂无可用模型",
+		"noModelsDescription": "该提供商未返回任何模型。",
+		"deleteEntity": "凭证",
+		"subtitle": "模型 API 授权配置",
+		"configured": "已配置",
+		"addProvider": "添加凭证",
+		"reasoning": "推理模型",
+		"maxContext": "最大上下文",
+		"maxOutput": "最大输出",
+		"inputTypes": "输入模态",
+		"outputTypes": "输出模态",
+		"availableTTSModels": "语音合成模型"
+	},
+	"knowledge": {
+		"subtitle": "管理 Agent 使用的知识库",
+		"selectHint": "未选择知识库",
+		"selectHintDescription": "从左侧选择一个知识库以查看详情。",
+		"deleteEntity": "知识库",
+		"list": {
+			"label": "知识库",
+			"emptyTitle": "暂无知识库",
+			"emptyDescription": "创建知识库以开始索引文档。",
+			"createButton": "创建知识库"
+		},
+		"document": {
+			"label": "文档",
+			"emptyTitle": "暂无文档",
+			"emptyDescription": "上传文档以索引到该知识库中。",
+			"uploadButton": "上传文档",
+			"uploadButtonShort": "上传",
+			"countLabel": "文档（{{count}}）",
+			"size": "大小",
+			"chunks": "分块",
+			"chunkCount_one": "{{count}} 个分块",
+			"chunkCount_other": "{{count}} 个分块",
+			"uploadedAt": "{{when}} 上传",
+			"deleteEntity": "文档",
+			"deleteConfirmTitle": "删除文档",
+			"deleteConfirmDescription": "确认删除 \"{{name}}\"？该操作将一并移除文档及其全部已索引分块，且不可撤销。",
+			"deleteError": "删除文档失败。",
+			"dropHint": "拖拽文件到此处上传",
+			"dropHintIdle": "或拖拽文件到此处",
+			"invalidFile": "\"{{name}}\" 添加失败。",
+			"unsupportedExtension": "\"{{name}}\" 已跳过——不支持该文件类型。",
+			"status": {
+				"queued": "排队中",
+				"uploading": "上传中",
+				"pending": "等待处理",
+				"parsing": "解析中",
+				"chunking": "分块中",
+				"indexing": "建立索引",
+				"ready": "已就绪",
+				"error": "失败",
+				"cancelled": "已取消"
+			},
+			"actions": {
+				"cancel": "取消",
+				"retry": "重试",
+				"dismiss": "关闭",
+				"remove": "删除",
+				"clearFinished": "清除已完成"
+			}
+		},
+		"test": {
+			"button": "测试",
+			"title": "检索测试",
+			"description": "在 \"{{name}}\" 上发起一次临时检索。",
+			"queryLabel": "查询",
+			"queryPlaceholder": "输入自然语言问题…",
+			"topKLabel": "Top K",
+			"searchButton": "搜索",
+			"score": "分值",
+			"chunkPosition": "第 {{index}} / {{total}} 段",
+			"emptyTitle": "无匹配",
+			"emptyDescription": "本次查询没有返回任何分块。"
+		}
+	},
+	"llm-select": {
+		"placeholder": "选择模型",
+		"fallbackPlaceholder": "兜底模型",
+		"loading": "加载中…",
+		"empty": {
+			"title": "暂无可用模型",
+			"description": "请先添加凭证。",
+			"addButton": "添加凭证"
+		},
+		"addCredential": "添加凭证",
+		"clear": "清除选择",
+		"noFallback": "无兜底模型"
+	},
+	"embedding-select": {
+		"placeholder": "选择 Embedding 模型",
+		"loading": "加载中…",
+		"empty": {
+			"title": "暂无可用的 Embedding 模型",
+			"description": "请先添加支持 Embedding 的凭证。"
+		},
+		"addCredential": "添加凭证",
+		"clear": "清除选择"
+	},
+	"dimension-select": {
+		"placeholder": "选择维度",
+		"pickModelFirst": "请先选择 Embedding 模型"
+	},
+	"permission-mode": {
+		"placeholder": "选择权限模式",
+		"trigger-tooltip": "权限模式",
+		"label": "权限模式",
+		"default-tooltip": "默认模式：所有操作需要明确授权（最安全）",
+		"accept_edits-tooltip": "自动允许工作目录内的文件读写及文件系统命令（mkdir、rm、mv 等），其他操作按正常规则处理",
+		"explore-tooltip": "只读模式：允许读取/Grep/Glob 工具，禁止写入/编辑/Bash 等修改操作",
+		"bypass-tooltip": "所有操作自动允许，无需权限检查（适用于可信/沙箱环境）",
+		"dont_ask-tooltip": "将所有 ASK 决策转为 DENY，适合定时任务或用户不在场时的后台执行"
+	},
+	"dialog-mcp-create": {
+		"title": "添加 MCP 服务器",
+		"description": "通过配置添加新的 MCP 服务器。",
+		"configLabel": "MCP 配置",
+		"keepAlive": "保持连接",
+		"keepAliveDesc": "在交互间保持状态。适用于浏览器操作或其他长时间运行的 MCP。",
+		"adding": "添加中…",
+		"added": "已添加",
+		"parseError": "JSON 配置无效：{{message}}",
+		"missingMcpServers": "配置中必须包含 \"mcpServers\" 对象。",
+		"emptyMcpServers": "配置中未找到 MCP 服务器。"
+	},
+	"dialog-mcp-delete": {
+		"entity": "MCP 服务器",
+		"skillEntity": "技能",
+		"skillDescription": "确定要将该技能从工作区中移除吗？"
+	},
+	"dialog-skill-add": {
+		"title": "添加技能",
+		"description": "输入技能目录的路径以添加到工作区。",
+		"pathLabel": "技能路径",
+		"pathPlaceholder": "/path/to/skill"
+	},
+	"schedule": {
+		"calendar": "日历",
+		"createSchedule": {
+			"description": "为 Agent 设置定时或一次性的计划任务。",
+			"descriptionLabel": "描述",
+			"descriptionPlaceholder": "描述这个计划任务的用途...",
+			"namePlaceholder": "例如：每日报告",
+			"title": "创建日程"
+		},
+		"deleteSchedule": {
+			"entity": "日程",
+			"successToast": "日程已删除。"
+		},
+		"endAt": "结束日期",
+		"end_at": "结束时间",
+		"executionHistory": "执行历史",
+		"freqDaily": "每天",
+		"freqMonthly": "每月",
+		"freqOnce": "一次",
+		"freqWeekly": "每周",
+		"frequency": "频率",
+		"friday": "周五",
+		"list": "列表",
+		"monday": "周一",
+		"more": "更多",
+		"nextMonth": "下个月",
+		"nextYear": "下一年",
+		"noExecutions": "暂无执行记录",
+		"noExecutionsDescription": "该日程尚未执行过。",
+		"noSchedules": "暂无日程",
+		"noSchedulesDescription": "创建日程以自动化 Agent 任务。",
+		"pickDate": "选择日期",
+		"permissionMode": "权限模式",
+		"timezone": "时区",
+		"triggerTime": "触发时间",
+		"createdAt": "创建时间",
+		"dayOfMonthSuffix": "日",
+		"stateful": "有状态",
+		"statefulDesc": "开启后，每次触发复用同一个会话以累积上下文；关闭则每次触发都创建新会话。",
+		"previousMonth": "上个月",
+		"previousYear": "上一年",
+		"saturday": "周六",
+		"startAt": "开始时间",
+		"sunday": "周日",
+		"thursday": "周四",
+		"today": "今天",
+		"tuesday": "周二",
+		"wednesday": "周三"
+	},
+	"model-parameters": {
+		"title": "模型参数",
+		"description": "调整所选模型的推理参数。",
+		"empty": "暂无可配置参数。",
+		"fallbackLabel": "兜底模型",
+		"fallbackLabelWithModel": "兜底模型（{{model}}）",
+		"parametersLabel": "参数",
+		"ttsLabel": "语音合成",
+		"ttsEmpty": "暂无可用的语音合成模型。",
+		"ttsParameters": "参数",
+		"ttsParametersDescription": "调整所选语音合成模型的参数。",
+		"noTts": "不使用语音合成"
+	},
+	"setup": {
+		"title": "连接到服务器",
+		"description": "请输入服务器地址和用户名以开始使用。",
+		"serverUrl": "服务器地址",
+		"serverUrlPlaceholder": "https://...",
+		"username": "用户名",
+		"usernamePlaceholder": "请输入用户名",
+		"submit": "开始使用",
+		"hint": "此应用仅提供前端服务，所有数据均来自填写的服务器地址，用户名仅用于服务端鉴权。"
+	},
+	"tour": {
+		"trigger": "新手引导",
+		"prev": "上一步",
+		"next": "下一步",
+		"finish": "完成",
+		"skip": "跳过",
+		"step": "第 {{current}} / {{total}} 步",
+		"createAgent": {
+			"title": "创建 Agent",
+			"content": "先创建一个 Agent —— 与你对话的智能体。"
+		},
+		"createSession": {
+			"title": "创建会话",
+			"content": "点 + 新建会话，开始对话。"
+		},
+		"llmSelect": {
+			"title": "选择模型",
+			"content": "为本次对话选一个模型；没有凭证可在下拉中添加。"
+		},
+		"permissionMode": {
+			"title": "权限模式",
+			"content": "决定工具调用是否需要确认。"
+		},
+		"chatInput": {
+			"title": "开始对话",
+			"content": "输入消息回车发送，回形针可附加文件。"
+		}
+	},
+	"task-panel": {
+		"heading": "任务",
+		"noTasks": "暂无任务。",
+		"pending": "待处理",
+		"inProgress": "进行中",
+		"completed": "已完成",
+		"blockedBy": "依赖"
+	},
+	"panel": {
+		"plan": {
+			"title": "计划",
+			"completed": "已完成：{{count}}",
+			"total": "总计：{{count}}",
+			"emptyTitle": "暂无任务",
+			"emptyDescription": "智能体规划的任务会显示在这里。"
+		},
+		"mcp": {
+			"title": "MCP",
+			"description": "工作区中配置的 MCP 服务器。",
+			"searchPlaceholder": "在工作区中搜索 MCP",
+			"add": "添加 MCP",
+			"tools": "{{count}} 个工具",
+			"emptyTitle": "暂无 MCP 服务器",
+			"emptyDescription": "添加 MCP 服务器为工作区配备工具。"
+		},
+		"skill": {
+			"title": "技能",
+			"description": "工作区中配置的技能。",
+			"searchPlaceholder": "在工作区中搜索技能",
+			"add": "添加技能",
+			"emptyTitle": "暂无技能",
+			"emptyDescription": "添加技能为工作区配备能力。"
+		},
+		"knowledge": {
+			"title": "知识库",
+			"description": "智能体可检索的知识库。",
+			"searchPlaceholder": "搜索知识库",
+			"emptyTitle": "暂无知识库",
+			"emptyDescription": "请先在「知识库」页面创建一个。",
+			"parametersTitle": "检索配置",
+			"parametersDescription": "知识库检索参数设置",
+			"selectedCount": "已挂载 {{count}} 个"
+		},
+		"permission": {
+			"title": "权限",
+			"description": "本会话应用的权限。",
+			"mode": "模式：{{mode}}",
+			"workingDirectories": "工作目录",
+			"noWorkingDirectories": "暂无工作目录。",
+			"allow": "允许",
+			"deny": "拒绝",
+			"ask": "询问",
+			"anyInvocation": "任意调用",
+			"emptyTitle": "暂无规则",
+			"emptyDescription": "允许 / 拒绝 / 询问规则会在添加后显示在这里。"
+		},
+		"search": {
+			"emptyTitle": "无结果",
+			"emptyDescription": "没有匹配 “{{query}}” 的结果。"
+		},
+		"loading": "加载中…"
+	},
+	"team-sidebar": {
+		"membersHeading": "成员",
+		"noMembers": "还没有成员——让队长用 AgentCreate 添加一个。",
+		"running": "运行中",
+		"idle": "空闲",
+		"missingSession": "（无会话）"
+	}
+}
diff --git a/examples/web_ui/frontend/src/i18n/useI18n.ts b/examples/web_ui/frontend/src/i18n/useI18n.ts
new file mode 100644
index 0000000..3809460
--- /dev/null
+++ b/examples/web_ui/frontend/src/i18n/useI18n.ts
@@ -0,0 +1,5 @@
+import { useTranslation as useI18nextTranslation } from 'react-i18next';
+
+export const useTranslation = () => {
+	return useI18nextTranslation('translation');
+};
diff --git a/examples/web_ui/frontend/src/index.css b/examples/web_ui/frontend/src/index.css
new file mode 100644
index 0000000..5e95957
--- /dev/null
+++ b/examples/web_ui/frontend/src/index.css
@@ -0,0 +1,214 @@
+@import 'tailwindcss';
+@import 'tw-animate-css';
+@import 'shadcn/tailwind.css';
+@import '@fontsource-variable/geist';
+
+@plugin '@tailwindcss/typography';
+
+html,
+body,
+#root {
+	height: 100%;
+	width: 100%;
+}
+
+@custom-variant dark (&:is(.dark *));
+
+:root {
+	--text: #6b6375;
+	--text-h: #08060d;
+	--bg: #fff;
+	--border: oklch(0.922 0 0);
+	--code-bg: #f4f3ec;
+	--accent: oklch(0.97 0 0);
+	--accent-bg: rgba(170, 59, 255, 0.1);
+	--accent-border: rgba(170, 59, 255, 0.5);
+	--social-bg: rgba(244, 243, 236, 0.5);
+	--shadow: rgba(0, 0, 0, 0.1) 0 10px 15px -3px, rgba(0, 0, 0, 0.05) 0 4px 6px -2px;
+
+	--sans: system-ui, 'Segoe UI', Roboto, sans-serif;
+	--heading: system-ui, 'Segoe UI', Roboto, sans-serif;
+	--mono: ui-monospace, Consolas, monospace;
+
+	/*font: 18px/145% var(--sans);*/
+	letter-spacing: 0.18px;
+	color-scheme: light dark;
+	color: var(--text);
+	background: var(--bg);
+	font-synthesis: none;
+	text-rendering: optimizeLegibility;
+	-webkit-font-smoothing: antialiased;
+	-moz-osx-font-smoothing: grayscale;
+
+	@media (max-width: 1024px) {
+		font-size: 16px;
+	}
+
+	--background: oklch(1 0 0);
+
+	--foreground: oklch(0.145 0 0);
+
+	--card: oklch(1 0 0);
+
+	--card-foreground: oklch(0.145 0 0);
+
+	--popover: oklch(1 0 0);
+
+	--popover-foreground: oklch(0.145 0 0);
+
+	--primary: oklch(0.205 0 0);
+
+	--primary-foreground: oklch(0.985 0 0);
+
+	--secondary: oklch(0.97 0 0);
+
+	--secondary-foreground: oklch(0.205 0 0);
+
+	--muted: oklch(0.97 0 0);
+
+	--muted-foreground: oklch(0.556 0 0);
+
+	--accent-foreground: oklch(0.205 0 0);
+
+	--destructive: oklch(0.577 0.245 27.325);
+
+	--input: oklch(0.922 0 0);
+
+	--ring: oklch(0.708 0 0);
+
+	--chart-1: oklch(0.87 0 0);
+
+	--chart-2: oklch(0.556 0 0);
+
+	--chart-3: oklch(0.439 0 0);
+
+	--chart-4: oklch(0.371 0 0);
+
+	--chart-5: oklch(0.269 0 0);
+
+	--radius: 0.625rem;
+
+	--sidebar: oklch(0.985 0 0);
+
+	--sidebar-foreground: oklch(0.145 0 0);
+
+	--sidebar-primary: oklch(0.205 0 0);
+
+	--sidebar-primary-foreground: oklch(0.985 0 0);
+
+	--sidebar-accent: oklch(0.97 0 0);
+
+	--sidebar-accent-foreground: oklch(0.205 0 0);
+
+	--sidebar-border: oklch(0.922 0 0);
+
+	--sidebar-ring: oklch(0.708 0 0);
+}
+
+@media (prefers-color-scheme: dark) {
+	:root {
+		--text: #9ca3af;
+		--text-h: #f3f4f6;
+		--bg: #16171d;
+		--border: #2e303a;
+		--code-bg: #1f2028;
+		--accent: #c084fc;
+		--accent-bg: rgba(192, 132, 252, 0.15);
+		--accent-border: rgba(192, 132, 252, 0.5);
+		--social-bg: rgba(47, 48, 58, 0.5);
+		--shadow: rgba(0, 0, 0, 0.4) 0 10px 15px -3px, rgba(0, 0, 0, 0.25) 0 4px 6px -2px;
+	}
+
+	#social .button-icon {
+		filter: invert(1) brightness(2);
+	}
+}
+
+@theme inline {
+	--font-heading: var(--font-sans);
+	--font-sans: 'Geist Variable', sans-serif;
+	--color-sidebar-ring: var(--sidebar-ring);
+	--color-sidebar-border: var(--sidebar-border);
+	--color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+	--color-sidebar-accent: var(--sidebar-accent);
+	--color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+	--color-sidebar-primary: var(--sidebar-primary);
+	--color-sidebar-foreground: var(--sidebar-foreground);
+	--color-sidebar: var(--sidebar);
+	--color-chart-5: var(--chart-5);
+	--color-chart-4: var(--chart-4);
+	--color-chart-3: var(--chart-3);
+	--color-chart-2: var(--chart-2);
+	--color-chart-1: var(--chart-1);
+	--color-ring: var(--ring);
+	--color-input: var(--input);
+	--color-border: var(--border);
+	--color-destructive: var(--destructive);
+	--color-accent-foreground: var(--accent-foreground);
+	--color-accent: var(--accent);
+	--color-muted-foreground: var(--muted-foreground);
+	--color-muted: var(--muted);
+	--color-secondary-foreground: var(--secondary-foreground);
+	--color-secondary: var(--secondary);
+	--color-primary-foreground: var(--primary-foreground);
+	--color-primary: var(--primary);
+	--color-popover-foreground: var(--popover-foreground);
+	--color-popover: var(--popover);
+	--color-card-foreground: var(--card-foreground);
+	--color-card: var(--card);
+	--color-foreground: var(--foreground);
+	--color-background: var(--background);
+	--radius-sm: calc(var(--radius) * 0.6);
+	--radius-md: calc(var(--radius) * 0.8);
+	--radius-lg: var(--radius);
+	--radius-xl: calc(var(--radius) * 1.4);
+	--radius-2xl: calc(var(--radius) * 1.8);
+	--radius-3xl: calc(var(--radius) * 2.2);
+	--radius-4xl: calc(var(--radius) * 2.6);
+}
+
+.dark {
+	--background: oklch(0.145 0 0);
+	--foreground: oklch(0.985 0 0);
+	--card: oklch(0.205 0 0);
+	--card-foreground: oklch(0.985 0 0);
+	--popover: oklch(0.205 0 0);
+	--popover-foreground: oklch(0.985 0 0);
+	--primary: oklch(0.922 0 0);
+	--primary-foreground: oklch(0.205 0 0);
+	--secondary: oklch(0.269 0 0);
+	--secondary-foreground: oklch(0.985 0 0);
+	--muted: oklch(0.269 0 0);
+	--muted-foreground: oklch(0.708 0 0);
+	--accent: oklch(0.269 0 0);
+	--accent-foreground: oklch(0.985 0 0);
+	--destructive: oklch(0.704 0.191 22.216);
+	--border: oklch(1 0 0 / 10%);
+	--input: oklch(1 0 0 / 15%);
+	--ring: oklch(0.556 0 0);
+	--chart-1: oklch(0.87 0 0);
+	--chart-2: oklch(0.556 0 0);
+	--chart-3: oklch(0.439 0 0);
+	--chart-4: oklch(0.371 0 0);
+	--chart-5: oklch(0.269 0 0);
+	--sidebar: oklch(0.205 0 0);
+	--sidebar-foreground: oklch(0.985 0 0);
+	--sidebar-primary: oklch(0.488 0.243 264.376);
+	--sidebar-primary-foreground: oklch(0.985 0 0);
+	--sidebar-accent: oklch(0.269 0 0);
+	--sidebar-accent-foreground: oklch(0.985 0 0);
+	--sidebar-border: oklch(1 0 0 / 10%);
+	--sidebar-ring: oklch(0.556 0 0);
+}
+
+@layer base {
+	* {
+		@apply border-border outline-ring/50;
+	}
+	body {
+		@apply bg-background text-foreground;
+	}
+	html {
+		@apply font-sans;
+	}
+}
diff --git a/examples/web_ui/frontend/src/lib/api-error.ts b/examples/web_ui/frontend/src/lib/api-error.ts
new file mode 100644
index 0000000..ed2b3e3
--- /dev/null
+++ b/examples/web_ui/frontend/src/lib/api-error.ts
@@ -0,0 +1,32 @@
+import { ApiError } from '@/api/client';
+
+/**
+ * FastAPI 422 responses put a pydantic ``.errors()`` array in ``detail``.
+ * `client.ts` stringifies that array, so what we get here is a JSON string
+ * like ``[{"type":"value_error","loc":[...],"msg":"..."}]``. Show only the
+ * ``msg`` fields — that's the human-readable part; ``type`` / ``loc`` /
+ * ``input`` are noise for end users.
+ */
+export function formatApiErrorForAlert(err: unknown): string {
+	if (err instanceof ApiError) {
+		const { detail } = err;
+		try {
+			const parsed = JSON.parse(detail) as unknown;
+			if (Array.isArray(parsed)) {
+				const msgs = parsed
+					.map((item) =>
+						item && typeof item === 'object' && 'msg' in item
+							? String((item as { msg: unknown }).msg)
+							: null,
+					)
+					.filter((m): m is string => !!m);
+				if (msgs.length > 0) return msgs.join('\n');
+			}
+		} catch {
+			// not JSON — fall through to raw detail
+		}
+		return detail;
+	}
+	if (err instanceof Error) return err.message;
+	return String(err);
+}
diff --git a/examples/web_ui/frontend/src/lib/next-navigation-shim.ts b/examples/web_ui/frontend/src/lib/next-navigation-shim.ts
new file mode 100644
index 0000000..83c63f2
--- /dev/null
+++ b/examples/web_ui/frontend/src/lib/next-navigation-shim.ts
@@ -0,0 +1,22 @@
+// Shim for `next/navigation` so libraries written for Next.js (e.g. `onborda`)
+// can run inside this Vite + react-router-dom app. Onborda only calls
+// `router.push(route)` when a step has `nextRoute`/`prevRoute` set; we don't use
+// those, so this no-op router is sufficient. If we ever need real navigation
+// from inside a tour step, swap this for a wrapper that uses `react-router`.
+export const useRouter = () => ({
+	push: async (path: string) => {
+		window.history.pushState({}, '', path);
+		window.dispatchEvent(new PopStateEvent('popstate'));
+	},
+	replace: async (path: string) => {
+		window.history.replaceState({}, '', path);
+		window.dispatchEvent(new PopStateEvent('popstate'));
+	},
+	back: () => window.history.back(),
+	forward: () => window.history.forward(),
+	refresh: () => {},
+	prefetch: async () => {},
+});
+
+export const usePathname = () => window.location.pathname;
+export const useSearchParams = () => new URLSearchParams(window.location.search);
diff --git a/examples/web_ui/frontend/src/lib/utils.ts b/examples/web_ui/frontend/src/lib/utils.ts
new file mode 100644
index 0000000..7637fb9
--- /dev/null
+++ b/examples/web_ui/frontend/src/lib/utils.ts
@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+export function cn(...inputs: ClassValue[]) {
+	return twMerge(clsx(inputs));
+}
diff --git a/examples/web_ui/frontend/src/main.tsx b/examples/web_ui/frontend/src/main.tsx
new file mode 100644
index 0000000..e75b417
--- /dev/null
+++ b/examples/web_ui/frontend/src/main.tsx
@@ -0,0 +1,15 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+
+import './index.css';
+import './i18n';
+import App from './App.tsx';
+import { TooltipProvider } from '@/components/ui/tooltip.tsx';
+
+createRoot(document.getElementById('root')!).render(
+	<StrictMode>
+		<TooltipProvider>
+			<App />
+		</TooltipProvider>
+	</StrictMode>,
+);
diff --git a/examples/web_ui/frontend/src/pages/chat/ChatViewport.tsx b/examples/web_ui/frontend/src/pages/chat/ChatViewport.tsx
new file mode 100644
index 0000000..56f7763
--- /dev/null
+++ b/examples/web_ui/frontend/src/pages/chat/ChatViewport.tsx
@@ -0,0 +1,711 @@
+import type { PermissionContext } from '@agentscope-ai/agentscope/permission';
+import type { TaskContext } from '@agentscope-ai/agentscope/state';
+import { BookText, ChevronDown, Database, ListTodo, PanelRight, ShieldCheck } from 'lucide-react';
+import { useCallback, useEffect, useMemo, useState } from 'react';
+
+import type { ChatModelConfig, SessionKnowledgeConfig, TTSModelConfig } from '@/api';
+import { sessionApi } from '@/api';
+import MCPSvg from '@/assets/images/mcp.svg?react';
+import { ChatContent } from '@/components/chat/ChatContent.tsx';
+import { SubagentHitlCard } from '@/components/chat/SubagentHitlCard';
+import { CreateCredentialDialog } from '@/components/dialog/CreateCredentialDialog';
+import { KnowledgeBasePanel } from '@/components/panel/KnowledgeBasePanel';
+import { McpPanel } from '@/components/panel/McpPanel';
+import { PanelDock, type PanelDescriptor, type PanelKey } from '@/components/panel/PanelDock.tsx';
+import { PermissionPanel } from '@/components/panel/PermissionPanel';
+import { SkillPanel } from '@/components/panel/SkillPanel';
+import { TaskPanel } from '@/components/panel/TaskPanel';
+import { KnowledgeBaseParametersPopover } from '@/components/popover/KnowledgeBaseParametersPopover';
+import { ModelParametersPopover } from '@/components/popover/ModelParametersPopover';
+import { LlmSelect } from '@/components/select/LlmSelect';
+import { PermissionModeSelect } from '@/components/select/PermissionModeSelect.tsx';
+import { Badge } from '@/components/ui/badge';
+import { Button } from '@/components/ui/button';
+import {
+	DropdownMenu,
+	DropdownMenuCheckboxItem,
+	DropdownMenuContent,
+	DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+import {
+	ResizableHandle,
+	ResizablePanel,
+	ResizablePanelGroup,
+} from '@/components/ui/resizable.tsx';
+import { SidebarTrigger } from '@/components/ui/sidebar';
+import { useAvailableModels } from '@/hooks/useAvailableModels';
+import { useKnowledgeBaseMiddlewareSchema } from '@/hooks/useKnowledgeBaseMiddlewareSchema';
+import { useKnowledgeBases } from '@/hooks/useKnowledgeBases';
+import { useMessages } from '@/hooks/useMessages';
+import { useSessions } from '@/hooks/useSessions';
+import { useWorkspace } from '@/hooks/useWorkspace.ts';
+import { useTranslation } from '@/i18n/useI18n';
+
+interface ChatViewportProps {
+	/**
+	 * The agent that owns the session being viewed. May be the
+	 * user-facing leader agent or — when drilled into a team member
+	 * via the URL's `:memberId` slot — a worker agent.
+	 */
+	agentId: string | null;
+	/**
+	 * The session whose messages, model config, permission mode, and
+	 * workspace drive every control rendered here.
+	 */
+	sessionId: string | null;
+	/**
+	 * Optional hook invoked when a team membership change arrives on
+	 * this viewport's SSE stream. The outer page owns the session list
+	 * that backs the team sidebar, so it must be told to refetch too;
+	 * passing this callback wires that signal up.
+	 */
+	onTeamUpdated?: () => void;
+}
+
+/** Maximum number of panels stacked in a single dock column. */
+const MAX_PANELS_PER_COLUMN = 2;
+
+/**
+ * Insert a panel into the dock layout. Scans columns left to right and
+ * appends to the first one with spare room; if every column is full a
+ * new rightmost column is created. No-op when the panel is already
+ * open.
+ *
+ * @param layout - The current column/panel arrangement.
+ * @param key - The panel to open.
+ * @returns A new layout array (the input is never mutated).
+ */
+function openPanelInLayout(layout: PanelKey[][], key: PanelKey): PanelKey[][] {
+	if (layout.some((column) => column.includes(key))) return layout;
+	const targetIndex = layout.findIndex((column) => column.length < MAX_PANELS_PER_COLUMN);
+	if (targetIndex === -1) return [...layout, [key]];
+	return layout.map((column, index) => (index === targetIndex ? [...column, key] : column));
+}
+
+/**
+ * Remove a panel from the dock layout, dropping its column entirely if
+ * it becomes empty.
+ *
+ * @param layout - The current column/panel arrangement.
+ * @param key - The panel to close.
+ * @returns A new layout array (the input is never mutated).
+ */
+function closePanelInLayout(layout: PanelKey[][], key: PanelKey): PanelKey[][] {
+	return layout
+		.map((column) => column.filter((panelKey) => panelKey !== key))
+		.filter((column) => column.length > 0);
+}
+
+/**
+ * The right-hand main panel of the chat page — every UI element that
+ * operates on a single `(agentId, sessionId)` pair lives here:
+ * model selector, permission mode select, message stream, workspace
+ * drawer, and the team sidebar.
+ *
+ * Self-contained by design. The outer page passes in the
+ * `(agentId, sessionId)` it wants displayed (which may be the leader
+ * session or a focused team member's session) and this component
+ * does the rest — fetching the session view, syncing local UI state
+ * with it, and writing changes back to the same session. Switching
+ * between leader and member is just a prop change; no internal
+ * branching is needed.
+ *
+ * @param agentId - The agent to operate on. `null` while no agent is
+ *   selected yet (renders an empty / disabled state).
+ * @param sessionId - The session to operate on. `null` while no
+ *   session is selected yet.
+ * @returns The right-side main JSX of the chat page.
+ */
+export function ChatViewport({ agentId, sessionId, onTeamUpdated }: ChatViewportProps) {
+	const { t } = useTranslation();
+	const { sessions, refetch: refetchSessions } = useSessions(agentId);
+	const { groups } = useAvailableModels();
+
+	// When the viewport agent differs from the outer page's selected
+	// agent (i.e. user drilled into a team member), `refetchSessions`
+	// only refreshes the member's session list. The team sidebar is
+	// driven by the leader's session list owned by the outer page, so
+	// we also fire the parent's refetch to keep that in sync.
+	const handleTeamUpdated = useCallback(() => {
+		refetchSessions();
+		onTeamUpdated?.();
+	}, [refetchSessions, onTeamUpdated]);
+
+	const [selectedModel, setSelectedModel] = useState<ChatModelConfig | null>(null);
+	const [selectedFallbackModel, setSelectedFallbackModel] = useState<ChatModelConfig | null>(
+		null,
+	);
+	const [selectedTTSModel, setSelectedTTSModel] = useState<TTSModelConfig | null>(null);
+	const [selectedKnowledgeConfig, setSelectedKnowledgeConfig] =
+		useState<SessionKnowledgeConfig | null>(null);
+	const [selectedPermissionMode, setSelectedPermissionMode] = useState<string>('default');
+	const [credentialOpen, setCredentialOpen] = useState(false);
+	const [credentialRefetchTrigger, setCredentialRefetchTrigger] = useState(0);
+	const [tasksContext, setTasksContext] = useState<TaskContext | null>(null);
+	const [permissionContext, setPermissionContext] = useState<PermissionContext | null>(null);
+	// Dock layout: columns laid out left→right, each holding up to 2
+	// panels stacked top→bottom. Open order determines placement.
+	const [panelLayout, setPanelLayout] = useState<PanelKey[][]>([]);
+
+	const handleStateUpdated = useCallback((value: Record<string, unknown>) => {
+		if (value.tasks_context) {
+			setTasksContext(value.tasks_context as TaskContext);
+		}
+		if (value.permission_context) {
+			setPermissionContext(value.permission_context as PermissionContext);
+		}
+	}, []);
+
+	const { msgs, phase, send, onUserConfirm, onSubagentConfirm, subagentHitl, interrupt } =
+		useMessages(agentId, sessionId, {
+			onTeamUpdated: handleTeamUpdated,
+			onStateUpdated: handleStateUpdated,
+		});
+	const {
+		mcps,
+		loading: mcpsLoading,
+		addMcps,
+		removeMcp,
+		skills,
+		skillsLoading,
+		addSkill,
+		removeSkill,
+	} = useWorkspace(agentId, sessionId);
+	const { knowledgeBases, loading: knowledgeBasesLoading } = useKnowledgeBases();
+	const { schema: kbMiddlewareSchema } = useKnowledgeBaseMiddlewareSchema();
+
+	// Toggle a panel open/closed from the top-bar buttons.
+	const togglePanel = useCallback((key: PanelKey) => {
+		setPanelLayout((layout) =>
+			layout.some((column) => column.includes(key))
+				? closePanelInLayout(layout, key)
+				: openPanelInLayout(layout, key),
+		);
+	}, []);
+
+	// Close a panel (driven by the panel's own close button).
+	const closePanel = useCallback((key: PanelKey) => {
+		setPanelLayout((layout) => closePanelInLayout(layout, key));
+	}, []);
+
+	const isPanelOpen = useCallback(
+		(key: PanelKey) => panelLayout.some((column) => column.includes(key)),
+		[panelLayout],
+	);
+
+	/**
+	 * Persist a knowledge-base attachment change. `null` detaches every
+	 * knowledge base from this session, removing the `RAGMiddleware`.
+	 *
+	 * Declared above `panels` (rather than alongside the other model
+	 * handlers below) because `panels` is built inside `useMemo` and
+	 * references this handler eagerly — a later `const` would still be
+	 * in the temporal dead zone when the memo factory runs on first
+	 * render.
+	 *
+	 * @param config - New attachment, or `null` to detach all.
+	 */
+	const handleKnowledgeConfigChange = useCallback(
+		async (config: SessionKnowledgeConfig | null) => {
+			if (!sessionId || !agentId) return;
+			setSelectedKnowledgeConfig(config);
+			await sessionApi.update(sessionId, agentId, { knowledge_config: config });
+			await refetchSessions();
+		},
+		[sessionId, agentId, refetchSessions],
+	);
+
+	// Build the panel descriptors with live data. Rebuilt on every
+	// data change so the dock always renders the latest state — the
+	// dock itself stays free of any data dependency.
+	const panels = useMemo<Record<PanelKey, PanelDescriptor>>(
+		() => ({
+			plan: {
+				title: t('panel.plan.title'),
+				icon: <ListTodo className="size-4" />,
+				content: <TaskPanel tasksContext={tasksContext} />,
+			},
+			mcp: {
+				title: 'MCP',
+				icon: <MCPSvg className="size-4" />,
+				content: (
+					<McpPanel
+						mcps={mcps}
+						loading={mcpsLoading}
+						onAdd={addMcps}
+						onRemove={removeMcp}
+					/>
+				),
+			},
+			skill: {
+				title: t('panel.skill.title'),
+				icon: <BookText className="size-4" />,
+				content: (
+					<SkillPanel
+						skills={skills}
+						loading={skillsLoading}
+						onAdd={addSkill}
+						onRemove={removeSkill}
+					/>
+				),
+			},
+			permission: {
+				title: (
+					<span className="flex items-center gap-x-2">
+						{t('panel.permission.title')}
+						{permissionContext?.mode ? (
+							<Badge variant="outline" className="capitalize">
+								{t('panel.permission.mode', { mode: permissionContext.mode })}
+							</Badge>
+						) : null}
+					</span>
+				),
+				icon: <ShieldCheck className="size-4" />,
+				content: <PermissionPanel permissionContext={permissionContext} />,
+			},
+			knowledge: {
+				title: (
+					<span className="flex items-center gap-x-2">
+						{t('panel.knowledge.title')}
+						{selectedKnowledgeConfig?.knowledge_base_ids.length ? (
+							<Badge variant="outline">
+								{selectedKnowledgeConfig.knowledge_base_ids.length}
+							</Badge>
+						) : null}
+					</span>
+				),
+				icon: <Database className="size-4" />,
+				actions: (
+					<KnowledgeBaseParametersPopover
+						value={selectedKnowledgeConfig}
+						schema={kbMiddlewareSchema}
+						onChange={handleKnowledgeConfigChange}
+						disabled={!sessionId}
+					/>
+				),
+				content: (
+					<KnowledgeBasePanel
+						knowledgeBases={knowledgeBases}
+						loading={knowledgeBasesLoading}
+						value={selectedKnowledgeConfig}
+						onChange={handleKnowledgeConfigChange}
+						disabled={!sessionId}
+					/>
+				),
+			},
+		}),
+		[
+			t,
+			tasksContext,
+			mcps,
+			mcpsLoading,
+			addMcps,
+			removeMcp,
+			skills,
+			skillsLoading,
+			addSkill,
+			removeSkill,
+			permissionContext,
+			knowledgeBases,
+			knowledgeBasesLoading,
+			selectedKnowledgeConfig,
+			kbMiddlewareSchema,
+			handleKnowledgeConfigChange,
+			sessionId,
+		],
+	);
+
+	const view = sessions.find((v) => v.session.id === sessionId) ?? null;
+
+	// ChatViewport keeps its own `useSessions(agentId)` instance (the
+	// outer page has a separate one). Its built-in fetch only fires on
+	// `agentId` change, so when the outer page creates a new session
+	// under the same agent, this list doesn't auto-refresh. Without
+	// this refetch, `view` would stay `null` for the brand-new session
+	// id and every effect below would early-return on `!view`,
+	// leaving the model select and friends pinned to whatever the
+	// previously-viewed session had configured.
+	useEffect(() => {
+		if (!sessionId) return;
+		if (view) return;
+		refetchSessions();
+	}, [sessionId, view, refetchSessions]);
+
+	// Reset local UI state when the target session changes. Otherwise
+	// the model select (and disabled-state guards on `send`) would
+	// show the previous session's model during the in-flight window
+	// before `view` repopulates — and an immediate send would post to
+	// a session whose backend config doesn't actually have that model.
+	useEffect(() => {
+		setSelectedModel(null);
+		setSelectedFallbackModel(null);
+		setSelectedTTSModel(null);
+		setSelectedKnowledgeConfig(null);
+	}, [sessionId]);
+
+	const selectedModelCard = useMemo(() => {
+		if (!selectedModel) return null;
+		const items = groups[selectedModel.type];
+		if (!items) return null;
+		for (const { models } of items) {
+			const card = models.find((m) => m.name === selectedModel.model);
+			if (card) return card;
+		}
+		return null;
+	}, [groups, selectedModel?.type, selectedModel?.model]);
+
+	/**
+	 * Pick the first model the available-models endpoint surfaces, used
+	 * as a sensible default when the current session has no model
+	 * configured yet.
+	 *
+	 * @returns The first available `ChatModelConfig`, or `null` when
+	 *   no credentials / models are configured.
+	 */
+	const getFirstAvailableModel = (): ChatModelConfig | null => {
+		const firstType = Object.keys(groups)[0];
+		if (!firstType) return null;
+		const items = groups[firstType];
+		if (!items || items.length === 0) return null;
+		const firstItem = items[0];
+		const firstModel = (firstItem.models as { name?: string; id?: string }[])[0];
+		if (!firstModel) return null;
+		const modelName = firstModel.name ?? firstModel.id ?? null;
+		if (!modelName) return null;
+		return {
+			type: firstType,
+			credential_id: firstItem.credential.id,
+			model: modelName,
+			parameters: {},
+		};
+	};
+
+	// Sync tasksContext from the session snapshot. Real-time updates
+	// arrive via the CustomEvent(name="state_updated") → the
+	// onStateUpdated callback above. We always mirror the snapshot
+	// (including clearing to null when the session is gone or has no
+	// tasks yet) so that switching sessions doesn't leak stale tasks
+	// from the previous one.
+	useEffect(() => {
+		if (!view) {
+			setTasksContext(null);
+			return;
+		}
+		const tc = (view.session.state as Record<string, unknown>)?.tasks_context as
+			| TaskContext
+			| undefined;
+		setTasksContext(tc ?? null);
+	}, [view]);
+
+	// Sync permissionContext from the session snapshot, mirroring the
+	// tasksContext approach above. Real-time updates arrive via the
+	// state_updated event → handleStateUpdated. Clearing to null when
+	// the session is gone avoids leaking stale rules across sessions.
+	useEffect(() => {
+		if (!view) {
+			setPermissionContext(null);
+			return;
+		}
+		const pc = (view.session.state as Record<string, unknown>)?.permission_context as
+			| PermissionContext
+			| undefined;
+		setPermissionContext(pc ?? null);
+	}, [view]);
+
+	// Sync selectedModel + selectedFallbackModel from the session
+	// record. If the session has no model configured yet, auto-pick
+	// the first available one and persist it back so subsequent
+	// reasoning has a model to call.
+	//
+	// Important: skip while `view` is still loading. Otherwise the
+	// in-flight window between "agentId changed" and "useSessions
+	// returned the new list" looks like "session has no model" and
+	// we would racily auto-select + persist the first available
+	// model, clobbering whatever the user had configured.
+	useEffect(() => {
+		if (!view) return;
+		const sessionModel = view.session.config.chat_model_config;
+
+		if (sessionModel) {
+			setSelectedModel(sessionModel);
+		} else {
+			const firstModel = getFirstAvailableModel();
+			if (firstModel) {
+				setSelectedModel(firstModel);
+				if (sessionId && agentId) {
+					sessionApi
+						.update(sessionId, agentId, { chat_model_config: firstModel })
+						.then(() => refetchSessions())
+						.catch(() => {});
+				}
+			} else {
+				setSelectedModel(null);
+			}
+		}
+
+		setSelectedFallbackModel(view.session.config.fallback_chat_model_config ?? null);
+		setSelectedTTSModel(view.session.config.tts_model_config ?? null);
+		setSelectedKnowledgeConfig(view.session.config.knowledge_config ?? null);
+	}, [view, groups, sessionId, agentId]);
+
+	// Sync selectedPermissionMode when the session changes. Same
+	// loading-window guard as above — don't reset the displayed mode
+	// to "default" while the new session view is still on the wire.
+	useEffect(() => {
+		if (!view) return;
+		const mode = (view.session.state?.permission_context as Record<string, unknown>)
+			?.mode as string;
+		setSelectedPermissionMode(mode ?? 'default');
+	}, [sessionId, view]);
+
+	/**
+	 * Persist a model change to the session and refetch so the local
+	 * view picks up the new value.
+	 *
+	 * @param config - New chat model config; `null` is ignored
+	 *   because the primary selector does not allow clearing.
+	 */
+	const handleLlmChange = async (config: ChatModelConfig | null) => {
+		if (!config || !sessionId || !agentId) return;
+		setSelectedModel(config);
+		await sessionApi.update(sessionId, agentId, { chat_model_config: config });
+		await refetchSessions();
+	};
+
+	/**
+	 * Persist a parameter change on the currently selected model.
+	 *
+	 * @param parameters - New parameter map (model-provider specific).
+	 */
+	const handleParametersChange = async (parameters: Record<string, unknown>) => {
+		if (!selectedModel || !sessionId || !agentId) return;
+		const updated = { ...selectedModel, parameters };
+		setSelectedModel(updated);
+		await sessionApi.update(sessionId, agentId, { chat_model_config: updated });
+		await refetchSessions();
+	};
+
+	/**
+	 * Persist a fallback-model change. `null` clears the fallback.
+	 *
+	 * @param config - New fallback config or `null` to clear.
+	 */
+	const handleFallbackChange = async (config: ChatModelConfig | null) => {
+		if (!sessionId || !agentId) return;
+		setSelectedFallbackModel(config);
+		await sessionApi.update(sessionId, agentId, { fallback_chat_model_config: config });
+		await refetchSessions();
+	};
+
+	/**
+	 * Persist a TTS model change. `null` disables TTS.
+	 *
+	 * @param config - New TTS config or `null` to disable.
+	 */
+	const handleTTSChange = async (config: TTSModelConfig | null) => {
+		if (!sessionId || !agentId) return;
+		setSelectedTTSModel(config);
+		await sessionApi.update(sessionId, agentId, { tts_model_config: config });
+		await refetchSessions();
+	};
+
+	/**
+	 * Persist a permission-mode change.
+	 *
+	 * @param mode - New permission mode (e.g. `default`, `explore`).
+	 */
+	const handlePermissionModeChange = async (mode: string) => {
+		setSelectedPermissionMode(mode);
+		if (!sessionId || !agentId) return;
+		await sessionApi.update(sessionId, agentId, { permission_mode: mode });
+		await refetchSessions();
+	};
+
+	return (
+		<>
+			<main className="flex size-full">
+				<ResizablePanelGroup orientation="horizontal">
+					<ResizablePanel className="flex flex-1" minSize="24rem">
+						<div className="flex flex-col flex-1 min-h-0 min-w-0 overflow-x-hidden p-2">
+							<div className="flex flex-row gap-x-2 justify-between">
+								<div
+									id="tour-llm-select"
+									className="flex flex-row items-center gap-x-1"
+								>
+									<SidebarTrigger className="md:hidden" />
+									<LlmSelect
+										value={selectedModel}
+										onChange={handleLlmChange}
+										onAddCredential={() => setCredentialOpen(true)}
+										refetchTrigger={credentialRefetchTrigger}
+									/>
+									<ModelParametersPopover
+										selectedModel={selectedModel}
+										modelCard={selectedModelCard}
+										onChange={handleParametersChange}
+										selectedFallbackModel={selectedFallbackModel}
+										onFallbackChange={handleFallbackChange}
+										selectedTTSModel={selectedTTSModel}
+										onTTSChange={handleTTSChange}
+									/>
+								</div>
+								<div id="tour-permission-mode" className="flex flex-row gap-x-1">
+									<PermissionModeSelect
+										value={selectedPermissionMode}
+										disabled={!sessionId}
+										onChange={handlePermissionModeChange}
+									/>
+									<DropdownMenu>
+										<DropdownMenuTrigger asChild>
+											<Button
+												variant="ghost"
+												size="sm"
+												className="gap-1 px-2"
+											>
+												<PanelRight />
+												<ChevronDown className="size-3 text-muted-foreground" />
+											</Button>
+										</DropdownMenuTrigger>
+										<DropdownMenuContent align="end" className="w-auto">
+											<DropdownMenuCheckboxItem
+												checked={isPanelOpen('plan')}
+												onCheckedChange={() => togglePanel('plan')}
+												onSelect={(e) => e.preventDefault()}
+											>
+												<ListTodo />
+												{t('panel.plan.title')}
+											</DropdownMenuCheckboxItem>
+											<DropdownMenuCheckboxItem
+												checked={isPanelOpen('mcp')}
+												onCheckedChange={() => togglePanel('mcp')}
+												onSelect={(e) => e.preventDefault()}
+											>
+												<MCPSvg className="size-4" />
+												MCP
+											</DropdownMenuCheckboxItem>
+											<DropdownMenuCheckboxItem
+												checked={isPanelOpen('skill')}
+												onCheckedChange={() => togglePanel('skill')}
+												onSelect={(e) => e.preventDefault()}
+											>
+												<BookText />
+												{t('panel.skill.title')}
+											</DropdownMenuCheckboxItem>
+											<DropdownMenuCheckboxItem
+												checked={isPanelOpen('permission')}
+												onCheckedChange={() => togglePanel('permission')}
+												onSelect={(e) => e.preventDefault()}
+											>
+												<ShieldCheck />
+												{t('panel.permission.title')}
+											</DropdownMenuCheckboxItem>
+											<DropdownMenuCheckboxItem
+												checked={isPanelOpen('knowledge')}
+												onCheckedChange={() => togglePanel('knowledge')}
+												onSelect={(e) => e.preventDefault()}
+											>
+												<Database />
+												{t('panel.knowledge.title')}
+											</DropdownMenuCheckboxItem>
+										</DropdownMenuContent>
+									</DropdownMenu>
+								</div>
+							</div>
+							<div className="flex flex-1 justify-center min-h-0 overflow-hidden relative [--chat-content-w:48rem]">
+								<ChatContent
+									className={'max-w-[var(--chat-content-w)] w-full'}
+									msgs={msgs}
+									phase={phase}
+									disabled={selectedModel === null}
+									onSend={send}
+									onUserConfirm={onUserConfirm}
+									onInterrupt={interrupt}
+									footerSlot={
+										subagentHitl.length > 0 ? (
+											<div className="space-y-2 pb-2">
+												{subagentHitl.map((entry) => (
+													<SubagentHitlCard
+														key={`${entry.worker_session_id}:${entry.reply_id}`}
+														entry={entry}
+														onConfirm={(toolCall, confirm, rules) =>
+															onSubagentConfirm(
+																entry,
+																toolCall,
+																confirm,
+																rules,
+															)
+														}
+													/>
+												))}
+											</div>
+										) : null
+									}
+									allowedInputTypes={(
+										selectedModelCard?.input_types ?? []
+									).filter(
+										(t) =>
+											/^(image|video|audio|text)\/.+/.test(t) ||
+											t === 'application/pdf' ||
+											t.startsWith('application/vnd.') ||
+											t.startsWith('application/msword') ||
+											t.startsWith('application/vnd.openxmlformats'),
+									)}
+									fileProcessor={async (file) => {
+										const filePath = (file as File & { path?: string }).path;
+										if (filePath) {
+											return {
+												id: crypto.randomUUID(),
+												type: 'data' as const,
+												source: {
+													type: 'url' as const,
+													url: `file://${filePath}`,
+													media_type:
+														file.type || 'application/octet-stream',
+												},
+												name: file.name,
+											};
+										}
+										if (file.type === 'text/plain') {
+											const text = await file.text();
+											return {
+												id: crypto.randomUUID(),
+												type: 'text' as const,
+												text: `[File: ${file.name}]\n${text}`,
+											};
+										}
+										const buffer = await file.arrayBuffer();
+										const bytes = new Uint8Array(buffer);
+										let binary = '';
+										for (let i = 0; i < bytes.byteLength; i++) {
+											binary += String.fromCharCode(bytes[i]);
+										}
+										const base64 = btoa(binary);
+										return {
+											id: crypto.randomUUID(),
+											type: 'data' as const,
+											source: {
+												type: 'base64' as const,
+												media_type: file.type || 'application/octet-stream',
+												data: base64,
+											},
+											name: file.name,
+										};
+									}}
+								/>
+							</div>
+						</div>
+					</ResizablePanel>
+					{panelLayout.length > 0 && (
+						<ResizableHandle withHandle className="bg-transparent" />
+					)}
+					<PanelDock layout={panelLayout} panels={panels} onClosePanel={closePanel} />
+				</ResizablePanelGroup>
+			</main>
+			<CreateCredentialDialog
+				open={credentialOpen}
+				onOpenChange={setCredentialOpen}
+				onCreated={() => setCredentialRefetchTrigger((n) => n + 1)}
+			/>
+		</>
+	);
+}
diff --git a/examples/web_ui/frontend/src/pages/chat/index.tsx b/examples/web_ui/frontend/src/pages/chat/index.tsx
new file mode 100644
index 0000000..c1c8566
--- /dev/null
+++ b/examples/web_ui/frontend/src/pages/chat/index.tsx
@@ -0,0 +1,434 @@
+import {
+	BotMessageSquare,
+	CalendarClock,
+	Ellipsis,
+	MessageSquareDashed,
+	Pencil,
+	Plus,
+	Settings2,
+	Trash2,
+} from 'lucide-react';
+import { useEffect, useState } from 'react';
+import { useNavigate, useParams } from 'react-router-dom';
+
+import { ChatViewport } from './ChatViewport';
+import type { SessionRecord } from '@/api';
+import { AgentDialog } from '@/components/dialog/AgentDialog';
+import { DeleteDialog } from '@/components/dialog/DeleteDialog';
+import { EditAgentDialog } from '@/components/dialog/EditAgentDialog';
+import { RenameSessionDialog } from '@/components/dialog/RenameSessionDialog';
+import { AgentSelect } from '@/components/select/AgentSelect';
+import { TeamSidebar } from '@/components/team/TeamSidebar';
+import { ChatTourController } from '@/components/tour/ChatTourController';
+import { Button } from '@/components/ui/button';
+import {
+	DropdownMenu,
+	DropdownMenuContent,
+	DropdownMenuItem,
+	DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+import {
+	Empty,
+	EmptyHeader,
+	EmptyTitle,
+	EmptyDescription,
+	EmptyContent,
+	EmptyMedia,
+} from '@/components/ui/empty';
+import {
+	Sidebar,
+	SidebarContent,
+	SidebarFooter,
+	SidebarGroup,
+	SidebarGroupAction,
+	SidebarGroupContent,
+	SidebarGroupLabel,
+	SidebarHeader,
+	SidebarMenu,
+	SidebarMenuAction,
+	SidebarMenuButton,
+	SidebarMenuItem,
+	SidebarProvider,
+	useSidebar,
+} from '@/components/ui/sidebar';
+import { AudioProvider } from '@/context/AudioContext';
+import { useAgents } from '@/hooks/useAgents';
+import { useSessions } from '@/hooks/useSessions';
+import { useTranslation } from '@/i18n/useI18n.ts';
+
+/**
+ * The chat page's outer shell. Responsibilities split cleanly:
+ *
+ * - **This component** owns *which* `(agent, session)` is being
+ *   viewed. The URL is the single source of truth: every selection
+ *   (agent dropdown, session row, team member, new session) is a
+ *   ``navigate(...)`` call. State is derived from ``useParams``,
+ *   never duplicated in React state. Renders the main left sidebar
+ *   (agent picker + session list + create/rename/delete actions) and
+ *   computes the ``effective`` ids to feed the chat viewport.
+ * - **`ChatViewport`** owns *what* to render for that pair: messages,
+ *   model selector, permission mode, workspace drawer, team sidebar.
+ *
+ * Splitting along this seam means switching between the leader's
+ * session and a focused team member is just a prop change for the
+ * viewport — the leader's session list stays anchored in this outer
+ * sidebar. Driving everything off URL also gets us browser back /
+ * forward, shareable links, and refresh-preserving state for free.
+ *
+ * @returns The chat page JSX.
+ */
+const ChatPageInner = () => {
+	const navigate = useNavigate();
+	const {
+		agentId: urlAgentId,
+		sessionId: urlSessionId,
+		memberId: urlMemberId,
+	} = useParams<{
+		agentId?: string;
+		sessionId?: string;
+		memberId?: string;
+	}>();
+	const { t } = useTranslation();
+	const { agents, refetch: refetchAgents, remove: removeAgent } = useAgents();
+	const {
+		sessions,
+		refetch: refetchSessions,
+		create: createSession,
+		update: updateSession,
+		remove: removeSession,
+	} = useSessions(urlAgentId ?? null);
+
+	const { isMobile, setOpen, setOpenMobile } = useSidebar();
+	const [editOpen, setEditOpen] = useState(false);
+	const [deleteOpen, setDeleteOpen] = useState(false);
+	const [renameOpen, setRenameOpen] = useState(false);
+	const [renameSession, setRenameSession] = useState<SessionRecord | null>(null);
+	const [deleteSessionOpen, setDeleteSessionOpen] = useState(false);
+	const [sessionToDelete, setSessionToDelete] = useState<SessionRecord | null>(null);
+
+	const selectedAgent = agents.find((a) => a.id === urlAgentId) ?? null;
+	const currentView = sessions.find((v) => v.session.id === urlSessionId) ?? null;
+	const hasScheduleSessions = sessions.some((v) => v.session.source === 'schedule');
+
+	// "Inner focus" — when the URL carries a third `:memberId` segment
+	// the user is drilling into a team member's chat. The main sidebar
+	// stays anchored on the outer (leader) session; only the chat
+	// viewport follows this inner focus. When `urlMemberId` is
+	// undefined or doesn't resolve to a known team member, the inner
+	// focus collapses back to the outer (leader) session.
+	const focusedMember = urlMemberId
+		? (currentView?.team?.members.find((m) => m.agent.id === urlMemberId) ?? null)
+		: null;
+	const effectiveAgentId =
+		focusedMember && focusedMember.session_id ? focusedMember.agent.id : (urlAgentId ?? null);
+	const effectiveSessionId =
+		focusedMember && focusedMember.session_id
+			? focusedMember.session_id
+			: (urlSessionId ?? null);
+
+	// Redirect: URL is missing an agent → pick the first one and rewrite
+	// the URL in-place (replace so we don't pollute history).
+	useEffect(() => {
+		if (!urlAgentId && agents.length > 0) {
+			navigate(`/chat/${agents[0].id}`, { replace: true });
+		}
+	}, [agents, urlAgentId, navigate]);
+
+	// Redirect: URL has an agent but no session, or its sessionId no
+	// longer exists for this agent → pick the first available session.
+	useEffect(() => {
+		if (!urlAgentId || sessions.length === 0) return;
+		const matches = urlSessionId && sessions.some((v) => v.session.id === urlSessionId);
+		if (matches) return;
+		navigate(`/chat/${urlAgentId}/${sessions[0].session.id}`, { replace: true });
+	}, [urlAgentId, urlSessionId, sessions, navigate]);
+
+	/**
+	 * Create a new session under the currently selected agent and
+	 * pre-fill it with the model + fallback the currently open session
+	 * is using (so "new chat" inherits whatever the user just had
+	 * configured). Falls back to any other session under this agent
+	 * when there is no current one — keeps the model choice sticky
+	 * across "delete last → create new" instead of dropping back to
+	 * whatever ChatViewport's auto-pick happens to land on. Navigates
+	 * to the freshly created session.
+	 */
+	const handleCreateSession = async () => {
+		if (!urlAgentId) return;
+		const seedConfig = currentView?.session.config ?? sessions[0]?.session.config;
+		const res = await createSession({
+			agent_id: urlAgentId,
+			...(seedConfig?.chat_model_config
+				? { chat_model_config: seedConfig.chat_model_config }
+				: {}),
+			...(seedConfig?.fallback_chat_model_config
+				? { fallback_chat_model_config: seedConfig.fallback_chat_model_config }
+				: {}),
+		});
+		navigate(`/chat/${urlAgentId}/${res.session_id}`);
+	};
+
+	const handleAgentDeleted = async () => {
+		navigate('/chat', { replace: true });
+		await refetchAgents();
+	};
+
+	const handleDeleteSession = async (sessionId: string) => {
+		await removeSession(sessionId);
+		// If we just removed the session the URL is pointing at, fall
+		// back to the parent /chat/:agentId path; the redirect effect
+		// will then pick the next available session.
+		if (sessionId === urlSessionId && urlAgentId) {
+			navigate(`/chat/${urlAgentId}`, { replace: true });
+		}
+	};
+
+	const requestDeleteSession = (session: SessionRecord) => {
+		setSessionToDelete(session);
+		setDeleteSessionOpen(true);
+	};
+
+	const handleRenameConfirm = async (name: string) => {
+		if (!renameSession) return;
+		await updateSession(renameSession.id, { name });
+	};
+
+	return (
+		<div className="flex h-full w-full">
+			{/*
+			 * Desktop stays `collapsible="none"` so the session list sits in
+			 * normal flow beside the app rail (AppSidebar). Mobile switches to
+			 * `offcanvas`, which makes shadcn's Sidebar render its Sheet overlay
+			 * (the drawer we want) — instead of the desktop `fixed left-0`
+			 * container, which would otherwise cover the app rail.
+			 */}
+			<Sidebar collapsible={isMobile ? 'offcanvas' : 'none'} className="border-r">
+				<SidebarHeader>
+					<div className="flex flex-col gap-y-2">
+						<span className="text-muted-foreground text-xs">
+							{localStorage.getItem('server_url')}
+						</span>
+						<div className="flex flex-row gap-x-2 items-center">
+							<AgentSelect
+								agents={agents}
+								value={urlAgentId ?? null}
+								onChange={(id) => navigate(`/chat/${id}`)}
+							/>
+							<Button
+								size="icon"
+								variant="ghost"
+								disabled={!urlAgentId || !selectedAgent?.editable}
+								tooltip={
+									selectedAgent && !selectedAgent.editable
+										? t('common.readOnlyTooltip')
+										: undefined
+								}
+								onClick={() => setEditOpen(true)}
+							>
+								<Settings2 />
+							</Button>
+							<Button
+								size="icon"
+								variant="ghost"
+								disabled={!urlAgentId || !selectedAgent?.editable}
+								tooltip={
+									selectedAgent && !selectedAgent.editable
+										? t('common.readOnlyTooltip')
+										: undefined
+								}
+								onClick={() => setDeleteOpen(true)}
+							>
+								<Trash2 className="text-destructive" />
+							</Button>
+						</div>
+						<AgentDialog onCreated={refetchAgents} triggerId="tour-create-agent" />
+					</div>
+				</SidebarHeader>
+				<SidebarContent className="my-5">
+					<SidebarGroup>
+						<SidebarGroupLabel>{t('chat.session.label')}</SidebarGroupLabel>
+						<SidebarGroupAction asChild>
+							<div>
+								<Button
+									id="tour-create-session"
+									size="icon-xs"
+									variant="default"
+									disabled={!urlAgentId}
+									onClick={handleCreateSession}
+								>
+									<Plus />
+								</Button>
+							</div>
+						</SidebarGroupAction>
+						<SidebarGroupContent>
+							{sessions.length === 0 ? (
+								<Empty className="border-none py-4 min-h-50">
+									<EmptyHeader>
+										<EmptyMedia variant="icon">
+											<MessageSquareDashed />
+										</EmptyMedia>
+										<EmptyTitle>{t('chat.session.emptyTitle')}</EmptyTitle>
+										<EmptyDescription>
+											{urlAgentId
+												? t('chat.session.emptyHasAgent')
+												: t('chat.session.emptyNoAgent')}
+										</EmptyDescription>
+									</EmptyHeader>
+									<EmptyContent>
+										<Button
+											variant="outline"
+											size="sm"
+											disabled={!urlAgentId}
+											onClick={handleCreateSession}
+										>
+											Create Session
+										</Button>
+									</EmptyContent>
+								</Empty>
+							) : (
+								<SidebarMenu>
+									{sessions.map((view) => {
+										const session = view.session;
+										return (
+											<SidebarMenuItem key={session.id}>
+												<SidebarMenuButton
+													isActive={urlSessionId === session.id}
+													onClick={() => {
+														navigate(
+															`/chat/${urlAgentId}/${session.id}`,
+														);
+														setOpenMobile(false);
+													}}
+												>
+													{hasScheduleSessions &&
+														(session.source === 'schedule' ? (
+															<CalendarClock />
+														) : (
+															<BotMessageSquare />
+														))}
+													<span className="truncate">
+														{session.config.name || session.id}
+													</span>
+												</SidebarMenuButton>
+												<SidebarMenuAction showOnHover>
+													<DropdownMenu>
+														<DropdownMenuTrigger asChild>
+															<Ellipsis />
+														</DropdownMenuTrigger>
+														<DropdownMenuContent
+															side="right"
+															align="start"
+														>
+															<DropdownMenuItem
+																onClick={() => {
+																	setRenameSession(session);
+																	setRenameOpen(true);
+																}}
+															>
+																<Pencil />
+																{t('session-menu.rename')}
+															</DropdownMenuItem>
+															<DropdownMenuItem
+																variant="destructive"
+																onClick={() =>
+																	requestDeleteSession(session)
+																}
+															>
+																<Trash2 />
+																{t('session-menu.delete')}
+															</DropdownMenuItem>
+														</DropdownMenuContent>
+													</DropdownMenu>
+												</SidebarMenuAction>
+											</SidebarMenuItem>
+										);
+									})}
+								</SidebarMenu>
+							)}
+						</SidebarGroupContent>
+					</SidebarGroup>
+				</SidebarContent>
+				<SidebarFooter />
+			</Sidebar>
+			{/*
+			 * Team sidebar lives at the outer page level (not inside
+			 * ChatViewport) so navigating between leader and member
+			 * sessions does NOT unmount it. The team data comes from
+			 * the leader's session view, which is stable across that
+			 * navigation; only `currentSessionId` changes to drive
+			 * row highlighting.
+			 */}
+			{currentView?.team && effectiveSessionId && (
+				<TeamSidebar team={currentView.team} currentSessionId={effectiveSessionId} />
+			)}
+			<div className="flex flex-1 min-w-0">
+				<ChatViewport
+					agentId={effectiveAgentId}
+					sessionId={effectiveSessionId}
+					onTeamUpdated={refetchSessions}
+				/>
+			</div>
+			{selectedAgent && (
+				<>
+					<EditAgentDialog
+						open={editOpen}
+						onOpenChange={setEditOpen}
+						agent={selectedAgent}
+						onUpdated={refetchAgents}
+					/>
+					<DeleteDialog
+						open={deleteOpen}
+						onOpenChange={setDeleteOpen}
+						title={t('common.deleteTitle', {
+							entity: t('dialog-agent-delete.entity'),
+							name: selectedAgent.data.name,
+						})}
+						description={t('common.deleteDescription')}
+						confirmLabel={t('dialog-agent-delete.confirm')}
+						onConfirm={async () => {
+							await removeAgent(selectedAgent.id);
+							await handleAgentDeleted();
+						}}
+					/>
+				</>
+			)}
+			<RenameSessionDialog
+				open={renameOpen}
+				onOpenChange={setRenameOpen}
+				currentName={renameSession?.config.name ?? renameSession?.id ?? ''}
+				onConfirm={handleRenameConfirm}
+			/>
+			<DeleteDialog
+				open={deleteSessionOpen}
+				onOpenChange={setDeleteSessionOpen}
+				title={t('common.deleteTitle', {
+					entity: t('dialog-session-delete.entity'),
+					name: sessionToDelete?.config.name || sessionToDelete?.id || '',
+				})}
+				description={t('common.deleteDescription')}
+				confirmLabel={t('dialog-session-delete.confirm')}
+				onConfirm={async () => {
+					if (sessionToDelete) {
+						await handleDeleteSession(sessionToDelete.id);
+					}
+				}}
+			/>
+			<ChatTourController
+				agentsCount={agents.length}
+				sessionsCount={sessions.length}
+				onEnsureSidebarOpen={() => {
+					setOpen(true);
+					setOpenMobile(true);
+				}}
+			/>
+		</div>
+	);
+};
+
+export const ChatPage = () => (
+	<AudioProvider>
+		<SidebarProvider defaultOpen>
+			<ChatPageInner />
+		</SidebarProvider>
+	</AudioProvider>
+);
diff --git a/examples/web_ui/frontend/src/pages/credential/index.tsx b/examples/web_ui/frontend/src/pages/credential/index.tsx
new file mode 100644
index 0000000..96c66e7
--- /dev/null
+++ b/examples/web_ui/frontend/src/pages/credential/index.tsx
@@ -0,0 +1,533 @@
+import { Eye, EyeOff, Plus, Pencil, Trash2 } from 'lucide-react';
+import { useState, useEffect, useCallback } from 'react';
+
+import { credentialApi, modelApi, ttsModelApi } from '@/api';
+import type { CredentialView, CredentialSchema, ModelCard, TTSModelCard } from '@/api';
+import { InputTypeBadges } from '@/components/badge/InputTypeBadges';
+import { CreateCredentialDialog } from '@/components/dialog/CreateCredentialDialog';
+import { DeleteDialog } from '@/components/dialog/DeleteDialog';
+import { EditCredentialDialog } from '@/components/dialog/EditCredentialDialog';
+import { Badge } from '@/components/ui/badge';
+import { Button } from '@/components/ui/button';
+import { Card, CardAction, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
+import { Empty, EmptyDescription, EmptyHeader, EmptyTitle } from '@/components/ui/empty';
+import { Separator } from '@/components/ui/separator';
+import {
+	Sidebar,
+	SidebarContent,
+	SidebarGroup,
+	SidebarGroupContent,
+	SidebarGroupLabel,
+	SidebarHeader,
+	SidebarMenu,
+	SidebarMenuButton,
+	SidebarMenuItem,
+} from '@/components/ui/sidebar';
+import { Skeleton } from '@/components/ui/skeleton';
+import { useCredentials } from '@/hooks/useCredentials';
+import { useTranslation } from '@/i18n/useI18n';
+import { formatNumber } from '@/utils/common.ts';
+
+// ─── Masked value ─────────────────────────────────────────────────────────────
+
+function MaskedValue({ value }: { value: string }) {
+	const [visible, setVisible] = useState(false);
+	const masked = value.length > 8 ? value.slice(0, 4) + '••••••••' + value.slice(-4) : '••••••••';
+	return (
+		<span className="flex items-center gap-x-1.5 font-mono text-sm">
+			{visible ? value : masked}
+			<Button size={'icon-sm'} variant={'ghost'} onClick={() => setVisible((v) => !v)}>
+				{visible ? <EyeOff /> : <Eye />}
+			</Button>
+		</span>
+	);
+}
+
+// ─── Model Card ───────────────────────────────────────────────────────────────
+
+function ModelCardItem({ model }: { model: ModelCard }) {
+	const { t } = useTranslation();
+	const ctx = model.context_size ? formatNumber(model.context_size) : null;
+
+	const output = model.output_size ? formatNumber(model.output_size) : null;
+
+	const statusVariant =
+		model.status === 'active'
+			? 'default'
+			: model.status === 'deprecated'
+				? 'secondary'
+				: 'outline';
+
+	const reasoning = model.input_types.includes('application/x-thinking');
+
+	return (
+		<Card className="shadow">
+			<CardHeader>
+				<CardTitle
+					className="text-sm font-semibold leading-tight truncate"
+					title={model.name}
+				>
+					{model.label || model.name}
+				</CardTitle>
+				{reasoning ? (
+					<CardAction>
+						<Badge variant={'outline'}>{t('credential.reasoning')}</Badge>
+					</CardAction>
+				) : null}
+			</CardHeader>
+			<CardContent className="flex flex-col">
+				{model.status !== 'active' && (
+					<Badge variant={statusVariant} className="text-xs">
+						{model.status}
+					</Badge>
+				)}
+
+				<div className="flex justify-between items-center text-[14px]">
+					<span className="text-muted-foreground">{t('credential.maxContext')}</span>
+					<span>{ctx}</span>
+				</div>
+				<div className="flex justify-between items-center text-[14px]">
+					<span className="text-muted-foreground">{t('credential.maxOutput')}</span>
+					<span>{output}</span>
+				</div>
+				<div className="flex justify-between items-center text-[14px]">
+					<span className="text-muted-foreground">{t('credential.inputTypes')}</span>
+					<InputTypeBadges inputTypes={model.input_types} />
+				</div>
+				<div className="flex justify-between items-center text-[14px]">
+					<span className="text-muted-foreground">{t('credential.outputTypes')}</span>
+					<InputTypeBadges inputTypes={model.output_types} />
+				</div>
+			</CardContent>
+		</Card>
+	);
+}
+
+// ─── TTS Model Card ──────────────────────────────────────────────────────────
+
+function TTSModelCardItem({ model }: { model: TTSModelCard }) {
+	const { t } = useTranslation();
+
+	const statusVariant =
+		model.status === 'active'
+			? 'default'
+			: model.status === 'deprecated'
+				? 'secondary'
+				: 'outline';
+
+	return (
+		<Card className="shadow">
+			<CardHeader>
+				<CardTitle
+					className="text-sm font-semibold leading-tight truncate"
+					title={model.name}
+				>
+					{model.label || model.name}
+				</CardTitle>
+				{model.realtime && (
+					<CardAction>
+						<Badge variant="outline">Realtime</Badge>
+					</CardAction>
+				)}
+			</CardHeader>
+			<CardContent className="flex flex-col">
+				{model.status !== 'active' && (
+					<Badge variant={statusVariant} className="text-xs">
+						{model.status}
+					</Badge>
+				)}
+				<div className="flex justify-between items-center text-[14px]">
+					<span className="text-muted-foreground">{t('credential.inputTypes')}</span>
+					<InputTypeBadges inputTypes={model.input_types} />
+				</div>
+				<div className="flex justify-between items-center text-[14px]">
+					<span className="text-muted-foreground">{t('credential.outputTypes')}</span>
+					<InputTypeBadges inputTypes={model.output_types} />
+				</div>
+			</CardContent>
+		</Card>
+	);
+}
+
+// ─── Detail panel ─────────────────────────────────────────────────────────────
+
+interface DetailPanelProps {
+	credential: CredentialView;
+	schema: CredentialSchema | null;
+	onEdit: () => void;
+	onDelete: () => void;
+}
+
+function DetailPanel({ credential, schema, onEdit, onDelete }: DetailPanelProps) {
+	const { t } = useTranslation();
+	const [models, setModels] = useState<ModelCard[]>([]);
+	const [ttsModels, setTtsModels] = useState<TTSModelCard[]>([]);
+	const [modelsLoading, setModelsLoading] = useState(false);
+
+	const type = credential.data.type as string | undefined;
+
+	useEffect(() => {
+		if (!type) return;
+		setModelsLoading(true);
+		Promise.all([
+			modelApi
+				.list(type)
+				.then((res) => res.models)
+				.catch(() => [] as ModelCard[]),
+			ttsModelApi
+				.list(type)
+				.then((res) => res.models)
+				.catch(() => [] as TTSModelCard[]),
+		])
+			.then(([chatModels, tts]) => {
+				setModels(chatModels);
+				setTtsModels(tts);
+			})
+			.finally(() => setModelsLoading(false));
+	}, [credential.id, type]);
+
+	// Fields to display: use schema properties order, skip id/type/const fields
+	const displayFields = schema
+		? Object.entries(schema.properties).filter(
+				([key, prop]) => key !== 'id' && key !== 'type' && prop.const === undefined,
+			)
+		: Object.entries(credential.data)
+				.filter(([key]) => key !== 'id' && key !== 'type')
+				.map(
+					([key]) =>
+						[key, { title: key, writeOnly: false }] as [
+							string,
+							{ title: string; writeOnly: boolean },
+						],
+				);
+
+	const name = (credential.data.name as string | undefined) ?? credential.id;
+
+	return (
+		<div className="flex flex-col gap-y-6 p-6 overflow-y-auto h-full">
+			{/* Header */}
+			<div className="flex items-start justify-between gap-x-4">
+				<div className="flex flex-col gap-y-1">
+					<h2 className="text-lg font-semibold">{name}</h2>
+					<p className="text-muted-foreground text-sm">{type}</p>
+					{!credential.editable && (
+						<Badge variant="secondary" title={t('common.readOnlyTooltip')}>
+							{t('common.readOnly')}
+						</Badge>
+					)}
+				</div>
+				<div className="flex items-center gap-x-2 shrink-0">
+					<Button
+						size="icon-sm"
+						variant="outline"
+						onClick={onEdit}
+						disabled={!credential.editable}
+						tooltip={credential.editable ? undefined : t('common.readOnlyTooltip')}
+					>
+						<Pencil />
+					</Button>
+					<Button
+						size="icon-sm"
+						variant="destructive"
+						onClick={onDelete}
+						disabled={!credential.editable}
+						tooltip={credential.editable ? undefined : t('common.readOnlyTooltip')}
+					>
+						<Trash2 />
+					</Button>
+				</div>
+			</div>
+
+			{/* Fields */}
+			<div className="flex flex-col gap-y-3">
+				{displayFields.map(([key, prop]) => {
+					const schemaProp = prop as {
+						title?: string;
+						writeOnly?: boolean;
+						format?: string;
+					};
+					const label = schemaProp.title ?? key.replace(/_/g, ' ');
+					const isSecret = schemaProp.writeOnly || schemaProp.format === 'password';
+					const val = credential.data[key];
+					if (val === undefined || val === null) return null;
+					const strVal = String(val);
+					return (
+						<div key={key} className="flex flex-col gap-y-0.5">
+							<span className="text-muted-foreground text-xs uppercase tracking-wide">
+								{label}
+							</span>
+							{isSecret ? (
+								<MaskedValue value={strVal} />
+							) : (
+								<span className="text-sm font-mono break-all">{strVal}</span>
+							)}
+						</div>
+					);
+				})}
+			</div>
+
+			<Separator />
+
+			{/* Available Models */}
+			<div className="flex flex-col gap-y-4">
+				<h3 className="text-sm font-semibold">
+					{t('credential.availableModels')}({models.length})
+				</h3>
+				{modelsLoading ? (
+					<div className="grid grid-cols-2 xl:grid-cols-3 gap-3">
+						{Array.from({ length: 4 }).map((_, i) => (
+							<Skeleton key={i} className="h-20 rounded-lg" />
+						))}
+					</div>
+				) : models.length === 0 ? (
+					<Empty className="border-none py-6">
+						<EmptyHeader>
+							<EmptyTitle>{t('credential.noModels')}</EmptyTitle>
+							<EmptyDescription>
+								{t('credential.noModelsDescription')}
+							</EmptyDescription>
+						</EmptyHeader>
+					</Empty>
+				) : (
+					<div className="grid grid-cols-2 xl:grid-cols-3 gap-3">
+						{models.map((m) => (
+							<ModelCardItem key={m.name} model={m} />
+						))}
+					</div>
+				)}
+			</div>
+
+			{/* Available TTS Models */}
+			{ttsModels.length > 0 && (
+				<>
+					<Separator />
+					<div className="flex flex-col gap-y-4">
+						<h3 className="text-sm font-semibold">
+							{t('credential.availableTTSModels')}({ttsModels.length})
+						</h3>
+						<div className="grid grid-cols-2 xl:grid-cols-3 gap-3">
+							{ttsModels.map((m) => (
+								<TTSModelCardItem key={m.name} model={m} />
+							))}
+						</div>
+					</div>
+				</>
+			)}
+		</div>
+	);
+}
+
+// ─── Page ─────────────────────────────────────────────────────────────────────
+
+export const CredentialPage = () => {
+	const { t } = useTranslation();
+	const { credentials, loading, remove, refetch } = useCredentials();
+	const [schemas, setSchemas] = useState<CredentialSchema[]>([]);
+	const [selectedId, setSelectedId] = useState<string | null>(null);
+	const [createOpen, setCreateOpen] = useState(false);
+	const [createDefaultType, setCreateDefaultType] = useState<string | undefined>();
+	const [editOpen, setEditOpen] = useState(false);
+	const [deleteOpen, setDeleteOpen] = useState(false);
+
+	useEffect(() => {
+		credentialApi.schemas().then((res) => setSchemas(res.schemas));
+	}, []);
+
+	// Auto-select first credential
+	useEffect(() => {
+		if (!selectedId && credentials.length > 0) {
+			setSelectedId(credentials[0].id);
+		}
+	}, [credentials, selectedId]);
+
+	const selectedCredential = credentials.find((c) => c.id === selectedId) ?? null;
+	const selectedSchema = selectedCredential
+		? (schemas.find(
+				(s) =>
+					(s.properties.type?.const as string) ===
+					(selectedCredential.data.type as string),
+			) ?? null)
+		: null;
+
+	// Group credentials by type, then list all schema types (even empty ones)
+	const groupedByType: Array<{ type: string; title: string; records: CredentialView[] }> =
+		schemas.map((s) => {
+			const type = s.properties.type?.const as string;
+			return {
+				type,
+				title: s.title,
+				records: credentials.filter((c) => c.data.type === type),
+			};
+		});
+
+	// Split providers so the user's actual configuration leads, and the
+	// (mostly empty) "add a provider" entries don't drown it out.
+	const configuredGroups = groupedByType.filter((g) => g.records.length > 0);
+	const totalConfigured = configuredGroups.reduce((n, g) => n + g.records.length, 0);
+
+	const handleOpenCreate = useCallback((type?: string) => {
+		setCreateDefaultType(type);
+		setCreateOpen(true);
+	}, []);
+
+	const handleDelete = useCallback(async () => {
+		if (!selectedCredential) return;
+		await remove(selectedCredential.id);
+		setSelectedId(null);
+	}, [selectedCredential, remove]);
+
+	return (
+		<div className="flex h-full w-full">
+			{/* Left sidebar */}
+			<Sidebar collapsible="none" className="border-r">
+				<SidebarHeader className={'flex flex-col mt-5 gap-y-1'}>
+					<div className="text-lg font-semibold">{t('common.credential')}</div>
+					<div className="text-muted-foreground text-xs">{t('credential.subtitle')}</div>
+				</SidebarHeader>
+				{/*<Separator />*/}
+				<SidebarContent>
+					{loading ? (
+						<div className="flex flex-col gap-y-2 p-4">
+							{Array.from({ length: 3 }).map((_, i) => (
+								<Skeleton key={i} className="h-8 rounded" />
+							))}
+						</div>
+					) : groupedByType.length === 0 ? (
+						<Empty className="border-none py-8">
+							<EmptyHeader>
+								<EmptyTitle>{t('credential.noProviders')}</EmptyTitle>
+							</EmptyHeader>
+						</Empty>
+					) : (
+						<>
+							{/* Configured credentials lead — this is what the user actually set up. */}
+							{configuredGroups.length > 0 && (
+								<SidebarGroup>
+									<SidebarGroupLabel>
+										{t('credential.configured')} ({totalConfigured})
+									</SidebarGroupLabel>
+									<SidebarGroupContent className="flex flex-col gap-y-4">
+										{configuredGroups.map(({ type, title, records }) => (
+											<div key={type}>
+												<div className="px-2 pb-1.5 text-xs font-semibold text-foreground/70">
+													{title}
+												</div>
+												<SidebarMenu className="pl-4">
+													{records.map((rec) => {
+														const name =
+															(rec.data.name as string | undefined) ??
+															rec.id;
+														return (
+															<SidebarMenuItem key={rec.id}>
+																<SidebarMenuButton
+																	isActive={selectedId === rec.id}
+																	onClick={() =>
+																		setSelectedId(rec.id)
+																	}
+																>
+																	<span className="min-w-0 flex-1 truncate">
+																		{name}
+																	</span>
+																	{!rec.editable && (
+																		<Badge
+																			variant="secondary"
+																			className="text-[10px] px-1 py-0"
+																			title={t(
+																				'common.readOnlyTooltip',
+																			)}
+																		>
+																			{t('common.readOnly')}
+																		</Badge>
+																	)}
+																</SidebarMenuButton>
+															</SidebarMenuItem>
+														);
+													})}
+												</SidebarMenu>
+											</div>
+										))}
+									</SidebarGroupContent>
+								</SidebarGroup>
+							)}
+
+							{/* Add credential — every provider is an entry point (including
+							    configured ones, to add more under the same provider). */}
+							<SidebarGroup>
+								<SidebarGroupLabel>{t('credential.addProvider')}</SidebarGroupLabel>
+								<SidebarGroupContent>
+									<SidebarMenu>
+										{groupedByType.map(({ type, title }) => (
+											<SidebarMenuItem key={type}>
+												<SidebarMenuButton
+													onClick={() => handleOpenCreate(type)}
+												>
+													<Plus />
+													<span className="min-w-0 flex-1 truncate">
+														{title}
+													</span>
+												</SidebarMenuButton>
+											</SidebarMenuItem>
+										))}
+									</SidebarMenu>
+								</SidebarGroupContent>
+							</SidebarGroup>
+						</>
+					)}
+				</SidebarContent>
+			</Sidebar>
+
+			{/* Right detail */}
+			<main className="flex-1 min-h-0 overflow-hidden">
+				{selectedCredential ? (
+					<DetailPanel
+						credential={selectedCredential}
+						schema={selectedSchema}
+						onEdit={() => setEditOpen(true)}
+						onDelete={() => setDeleteOpen(true)}
+					/>
+				) : (
+					<div className="flex h-full items-center justify-center">
+						<Empty className="border-none">
+							<EmptyHeader>
+								<EmptyTitle>{t('credential.selectHint')}</EmptyTitle>
+								<EmptyDescription>
+									{t('credential.selectHintDescription')}
+								</EmptyDescription>
+							</EmptyHeader>
+						</Empty>
+					</div>
+				)}
+			</main>
+
+			{/* Dialogs */}
+			<CreateCredentialDialog
+				open={createOpen}
+				onOpenChange={setCreateOpen}
+				defaultType={createDefaultType}
+				onCreated={() => refetch()}
+			/>
+			{selectedCredential && (
+				<>
+					<EditCredentialDialog
+						open={editOpen}
+						onOpenChange={setEditOpen}
+						credential={selectedCredential}
+						onUpdated={() => refetch()}
+					/>
+					<DeleteDialog
+						open={deleteOpen}
+						onOpenChange={setDeleteOpen}
+						title={t('common.deleteTitle', {
+							entity: t('credential.deleteEntity'),
+							name:
+								(selectedCredential.data.name as string | undefined) ??
+								selectedCredential.id,
+						})}
+						description={t('common.deleteDescription')}
+						onConfirm={handleDelete}
+					/>
+				</>
+			)}
+		</div>
+	);
+};
diff --git a/examples/web_ui/frontend/src/pages/knowledge/index.tsx b/examples/web_ui/frontend/src/pages/knowledge/index.tsx
new file mode 100644
index 0000000..4e6734f
--- /dev/null
+++ b/examples/web_ui/frontend/src/pages/knowledge/index.tsx
@@ -0,0 +1,284 @@
+import { Ellipsis, Files, FlaskConical, Pencil, Plus, Trash2 } from 'lucide-react';
+import { useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import { useNavigate, useParams } from 'react-router-dom';
+
+import type { KnowledgeBaseView } from '@/api';
+import { CreateCredentialDialog } from '@/components/dialog/CreateCredentialDialog.tsx';
+import { CreateKnowledgeBaseDialog } from '@/components/dialog/CreateKnowledgeBaseDialog.tsx';
+import { DeleteDialog } from '@/components/dialog/DeleteDialog.tsx';
+import { EditKnowledgeBaseDialog } from '@/components/dialog/EditKnowledgeBaseDialog.tsx';
+import { KnowledgeSearchDrawer } from '@/components/drawer/KnowledgeSearchDrawer.tsx';
+import { KnowledgeDocumentsPanel } from '@/components/knowledge/KnowledgeDocumentsPanel.tsx';
+import { Badge } from '@/components/ui/badge.tsx';
+import { Button } from '@/components/ui/button.tsx';
+import {
+	DropdownMenu,
+	DropdownMenuContent,
+	DropdownMenuItem,
+	DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu.tsx';
+import {
+	Empty,
+	EmptyContent,
+	EmptyDescription,
+	EmptyHeader,
+	EmptyMedia,
+	EmptyTitle,
+} from '@/components/ui/empty.tsx';
+import { Separator } from '@/components/ui/separator.tsx';
+import {
+	Sidebar,
+	SidebarContent,
+	SidebarFooter,
+	SidebarGroup,
+	SidebarGroupAction,
+	SidebarGroupContent,
+	SidebarGroupLabel,
+	SidebarHeader,
+	SidebarMenu,
+	SidebarMenuAction,
+	SidebarMenuButton,
+	SidebarMenuItem,
+} from '@/components/ui/sidebar.tsx';
+import { useKnowledgeBases } from '@/hooks/useKnowledgeBases.ts';
+
+interface DetailPanelProps {
+	knowledgeBase?: KnowledgeBaseView;
+	onTest?: () => void;
+}
+
+function DetailPanel({ knowledgeBase, onTest }: DetailPanelProps) {
+	const { t } = useTranslation();
+
+	if (!knowledgeBase) {
+		return (
+			<div className="flex h-full items-center justify-center">
+				<Empty className="border-none">
+					<EmptyHeader>
+						<EmptyTitle>{t('knowledge.selectHint')}</EmptyTitle>
+						<EmptyDescription>{t('knowledge.selectHintDescription')}</EmptyDescription>
+					</EmptyHeader>
+				</Empty>
+			</div>
+		);
+	}
+
+	return (
+		<div className="flex flex-col gap-y-6 p-6 overflow-y-auto h-full">
+			{/* Header */}
+			<div className="flex items-start justify-between gap-x-4">
+				<div className="flex flex-col gap-y-1 min-w-0">
+					<div className="flex items-center gap-x-2">
+						<h2 className="text-lg font-semibold truncate">{knowledgeBase.name}</h2>
+						{!knowledgeBase.editable && (
+							<Badge variant="secondary" title={t('common.readOnlyTooltip')}>
+								{t('common.readOnly')}
+							</Badge>
+						)}
+					</div>
+					{knowledgeBase.description ? (
+						<p className="text-sm text-muted-foreground">{knowledgeBase.description}</p>
+					) : null}
+				</div>
+				<div className="flex items-center gap-x-2 shrink-0">
+					<Button size="sm" variant="outline" onClick={onTest}>
+						<FlaskConical className="size-3.5" />
+						{t('knowledge.test.button')}
+					</Button>
+				</div>
+			</div>
+
+			<Separator />
+
+			{/* Documents */}
+			<KnowledgeDocumentsPanel knowledgeBaseId={knowledgeBase.id} />
+		</div>
+	);
+}
+
+export const KnowledgePage = () => {
+	const navigate = useNavigate();
+	const { kbId: urlKbId } = useParams<{ kbId?: string }>();
+	const { t } = useTranslation();
+
+	const { knowledgeBases, remove, refetch } = useKnowledgeBases();
+	const [selectedKbId, setSelectedKbId] = useState<string | undefined>(urlKbId);
+	const [createDialogOpen, setCreateDialogOpen] = useState(false);
+	const [credentialOpen, setCredentialOpen] = useState(false);
+	const [credentialRefetchTrigger, setCredentialRefetchTrigger] = useState(0);
+
+	const [editTarget, setEditTarget] = useState<KnowledgeBaseView | null>(null);
+	const [deleteTarget, setDeleteTarget] = useState<KnowledgeBaseView | null>(null);
+	const [testOpen, setTestOpen] = useState(false);
+
+	const selectedKb = knowledgeBases.find((kb) => kb.id === selectedKbId);
+
+	const handleCreated = async (knowledgeBaseId: string) => {
+		await refetch();
+		setSelectedKbId(knowledgeBaseId);
+		navigate(`/knowledge/${knowledgeBaseId}`);
+	};
+
+	const handleConfirmDelete = async () => {
+		if (!deleteTarget) return;
+		const id = deleteTarget.id;
+		await remove(id);
+		await refetch();
+		if (selectedKbId === id) {
+			setSelectedKbId(undefined);
+			navigate('/knowledge');
+		}
+	};
+
+	return (
+		<div className="flex size-full">
+			<Sidebar collapsible="none" className="border-r">
+				<SidebarHeader className={'flex flex-col mt-5 gap-y-1'}>
+					<div className="text-lg font-semibold">{t('common.knowledge')}</div>
+					<div className="text-muted-foreground text-xs">{t('knowledge.subtitle')}</div>
+				</SidebarHeader>
+				<SidebarContent className="my-5">
+					<SidebarGroup>
+						<SidebarGroupLabel>{t('knowledge.list.label')}</SidebarGroupLabel>
+						<SidebarGroupAction>
+							<Button
+								size="icon-xs"
+								variant="default"
+								onClick={() => setCreateDialogOpen(true)}
+							>
+								<Plus />
+							</Button>
+						</SidebarGroupAction>
+						<SidebarGroupContent>
+							{knowledgeBases.length === 0 ? (
+								<Empty className="border-none py-4 min-h-50">
+									<EmptyHeader>
+										<EmptyMedia variant="icon">
+											<Files />
+										</EmptyMedia>
+										<EmptyTitle>{t('knowledge.list.emptyTitle')}</EmptyTitle>
+										<EmptyDescription>
+											{t('knowledge.list.emptyDescription')}
+										</EmptyDescription>
+									</EmptyHeader>
+									<EmptyContent>
+										<Button
+											variant="outline"
+											size="sm"
+											onClick={() => setCreateDialogOpen(true)}
+										>
+											<Plus />
+											{t('knowledge.list.createButton')}
+										</Button>
+									</EmptyContent>
+								</Empty>
+							) : (
+								<SidebarMenu>
+									{knowledgeBases.map((kb) => {
+										return (
+											<SidebarMenuItem key={kb.id}>
+												<SidebarMenuButton
+													isActive={urlKbId === kb.id}
+													onClick={() => {
+														setSelectedKbId(kb.id);
+														navigate(`/knowledge/${kb.id}`);
+													}}
+												>
+													<span className="truncate">{kb.name}</span>
+													{!kb.editable && (
+														<Badge
+															variant="secondary"
+															className="text-[10px] px-1 py-0"
+															title={t('common.readOnlyTooltip')}
+														>
+															{t('common.readOnly')}
+														</Badge>
+													)}
+												</SidebarMenuButton>
+												{kb.editable && (
+													<SidebarMenuAction showOnHover>
+														<DropdownMenu>
+															<DropdownMenuTrigger asChild>
+																<Ellipsis />
+															</DropdownMenuTrigger>
+															<DropdownMenuContent
+																side="right"
+																align="start"
+															>
+																<DropdownMenuItem
+																	onClick={() =>
+																		setEditTarget(kb)
+																	}
+																>
+																	<Pencil />
+																	{t('common.edit')}
+																</DropdownMenuItem>
+																<DropdownMenuItem
+																	variant="destructive"
+																	onClick={() =>
+																		setDeleteTarget(kb)
+																	}
+																>
+																	<Trash2 />
+																	{t('common.delete')}
+																</DropdownMenuItem>
+															</DropdownMenuContent>
+														</DropdownMenu>
+													</SidebarMenuAction>
+												)}
+											</SidebarMenuItem>
+										);
+									})}
+								</SidebarMenu>
+							)}
+						</SidebarGroupContent>
+					</SidebarGroup>
+				</SidebarContent>
+				<SidebarFooter />
+			</Sidebar>
+			<main className="flex-1 min-h-0 overflow-hidden">
+				<DetailPanel knowledgeBase={selectedKb} onTest={() => setTestOpen(true)} />
+			</main>
+			<CreateKnowledgeBaseDialog
+				open={createDialogOpen}
+				onOpenChange={setCreateDialogOpen}
+				onCreated={handleCreated}
+				onAddCredential={() => setCredentialOpen(true)}
+				credentialRefetchTrigger={credentialRefetchTrigger}
+			/>
+			<CreateCredentialDialog
+				open={credentialOpen}
+				onOpenChange={setCredentialOpen}
+				onCreated={() => setCredentialRefetchTrigger((n) => n + 1)}
+			/>
+			<EditKnowledgeBaseDialog
+				open={editTarget !== null}
+				onOpenChange={(open) => {
+					if (!open) setEditTarget(null);
+				}}
+				knowledgeBase={editTarget}
+				onUpdated={() => refetch()}
+			/>
+			<DeleteDialog
+				open={deleteTarget !== null}
+				onOpenChange={(open) => {
+					if (!open) setDeleteTarget(null);
+				}}
+				title={t('dialog-knowledge-base-delete.title')}
+				description={t('dialog-knowledge-base-delete.description', {
+					name: deleteTarget?.name ?? '',
+				})}
+				onConfirm={handleConfirmDelete}
+			/>
+			{selectedKb && (
+				<KnowledgeSearchDrawer
+					open={testOpen}
+					onOpenChange={setTestOpen}
+					knowledgeBaseId={selectedKb.id}
+					knowledgeBaseName={selectedKb.name}
+				/>
+			)}
+		</div>
+	);
+};
diff --git a/examples/web_ui/frontend/src/pages/schedule/calendar-tab-page.tsx b/examples/web_ui/frontend/src/pages/schedule/calendar-tab-page.tsx
new file mode 100644
index 0000000..4cd8f59
--- /dev/null
+++ b/examples/web_ui/frontend/src/pages/schedule/calendar-tab-page.tsx
@@ -0,0 +1,340 @@
+import { ChevronLeft, ChevronRight, ChevronsLeft, ChevronsRight } from 'lucide-react';
+import { useEffect, useRef, useState } from 'react';
+
+import type { ScheduleEvent } from './event';
+import { Button } from '@/components/ui/button';
+import {
+	DropdownMenu,
+	DropdownMenuContent,
+	DropdownMenuItem,
+	DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@/components/ui/tooltip';
+import { useTranslation } from '@/i18n/useI18n';
+
+interface DateCellProps {
+	day: number;
+	isToday: boolean;
+	events: ScheduleEvent[];
+	onEventClick: (event: ScheduleEvent) => void;
+	moreText: string;
+}
+
+/**
+ * DateCell component that dynamically adjusts the number of visible events based on cell height.
+ * @param root0
+ * @param root0.day
+ * @param root0.isToday
+ * @param root0.events
+ * @param root0.onEventClick
+ * @param root0.moreText
+ * @returns A calendar date cell element.
+ */
+function DateCell({ day, isToday, events, onEventClick, moreText }: DateCellProps) {
+	const cellRef = useRef<HTMLDivElement>(null);
+	const [maxVisibleEvents, setMaxVisibleEvents] = useState(3);
+
+	useEffect(() => {
+		if (!cellRef.current) return;
+
+		const resizeObserver = new ResizeObserver((entries) => {
+			for (const entry of entries) {
+				const cellHeight = entry.contentRect.height;
+				// Calculate available height for events
+				// Cell padding: 8px (p-2)
+				// Date header: ~28px (w-6 h-6 + mb-1)
+				// Event item height: ~24px (text-xs + py-0.5 + space-y-1)
+				// More indicator: ~20px
+				const padding = 8;
+				const headerHeight = 28;
+				const eventHeight = 24;
+				const moreIndicatorHeight = 20;
+
+				const availableHeight = cellHeight - padding - headerHeight - moreIndicatorHeight;
+				const maxEvents = Math.max(0, Math.floor(availableHeight / eventHeight));
+				setMaxVisibleEvents(maxEvents);
+			}
+		});
+
+		resizeObserver.observe(cellRef.current);
+
+		return () => {
+			resizeObserver.disconnect();
+		};
+	}, []);
+
+	return (
+		<div
+			ref={cellRef}
+			className="border-border! border-r border-b p-2 hover:bg-accent cursor-pointer overflow-hidden"
+		>
+			<div className="flex items-start justify-between mb-1">
+				<div className="w-6 h-6 flex items-center justify-center">
+					<div
+						className={`text-sm ${
+							isToday
+								? 'bg-primary text-primary-foreground rounded-full w-6 h-6 flex items-center justify-center'
+								: ''
+						}`}
+					>
+						{day}
+					</div>
+				</div>
+			</div>
+			{/* Event indicators */}
+			<div className="space-y-1">
+				{events.slice(0, maxVisibleEvents).map((event) => (
+					<div
+						key={event.id}
+						className="flex flex-row justify-between text-xs py-0.5 px-1 text-secondary-foreground rounded-sm cursor-pointer hover:bg-primary/20"
+						title={`${event.time} - ${event.title}`}
+						onClick={(e) => {
+							e.stopPropagation();
+							onEventClick(event);
+						}}
+					>
+						<div className="flex flex-row flex-1 items-center gap-x-1 overflow-hidden">
+							<div className="w-1 min-w-1 max-w-1 bg-primary border-primary h-full rounded" />
+							<span className="truncate">{event.title}</span>
+						</div>
+						<span>{event.time}</span>
+					</div>
+				))}
+				{events.length > maxVisibleEvents && (
+					<DropdownMenu>
+						<DropdownMenuTrigger asChild>
+							<div className="text-xs text-muted-foreground px-1 cursor-pointer hover:text-foreground hover:underline">
+								+{events.length - maxVisibleEvents} {moreText}
+							</div>
+						</DropdownMenuTrigger>
+						<DropdownMenuContent align="start" className="max-w-64">
+							{events.slice(maxVisibleEvents).map((event) => (
+								<DropdownMenuItem
+									key={event.id}
+									onClick={() => onEventClick(event)}
+									className="text-xs"
+								>
+									<span className="font-medium">{event.time}</span>
+									<span className="truncate ml-2">{event.title}</span>
+								</DropdownMenuItem>
+							))}
+						</DropdownMenuContent>
+					</DropdownMenu>
+				)}
+			</div>
+		</div>
+	);
+}
+
+interface Props {
+	events: ScheduleEvent[];
+	onEventClick: (event: ScheduleEvent) => void;
+	currentDate: Date;
+	onMonthChange: (date: Date) => void;
+}
+
+/**
+ * The calendar tab page component that displays events in a monthly calendar view.
+ *
+ * @param root0 - The component props.
+ * @param root0.events - Array of schedule events to display.
+ * @param root0.onEventClick - Callback when an event is clicked.
+ * @param root0.currentDate - The currently displayed date.
+ * @param root0.onMonthChange - Callback when the month is changed.
+ * @returns A CalendarTabPage component.
+ */
+export function CalendarTabPage({ events, onEventClick, currentDate, onMonthChange }: Props) {
+	const { t } = useTranslation();
+	const goToPrevMonth = () => {
+		onMonthChange(new Date(year, month - 1, 1));
+	};
+
+	const goToNextMonth = () => {
+		onMonthChange(new Date(year, month + 1, 1));
+	};
+
+	const goToPrevYear = () => {
+		onMonthChange(new Date(year - 1, month, 1));
+	};
+
+	const goToNextYear = () => {
+		onMonthChange(new Date(year + 1, month, 1));
+	};
+
+	const goToToday = () => {
+		onMonthChange(new Date());
+	};
+
+	const year = currentDate.getFullYear();
+	const month = currentDate.getMonth();
+
+	// Get the first and last day of the current month
+	const firstDay = new Date(year, month, 1);
+	const lastDay = new Date(year, month + 1, 0);
+
+	// Get the day of the week for the first day of the month (0-6, 0 is Sunday)
+	const firstDayOfWeek = firstDay.getDay();
+
+	// Get the last few days of the previous month
+	const prevMonthLastDay = new Date(year, month, 0).getDate();
+	const prevMonthDays = Array.from(
+		{ length: firstDayOfWeek },
+		(_, i) => prevMonthLastDay - firstDayOfWeek + i + 1,
+	);
+
+	// Get all days of the current month
+	const currentMonthDays = Array.from({ length: lastDay.getDate() }, (_, i) => i + 1);
+
+	// Calculate the actual number of weeks needed for this month
+	const totalDaysNeeded = prevMonthDays.length + currentMonthDays.length;
+	const weeksNeeded = Math.ceil(totalDaysNeeded / 7);
+	const totalCells = weeksNeeded * 7;
+	const remainingCells = totalCells - prevMonthDays.length - currentMonthDays.length;
+	const nextMonthDays = Array.from({ length: remainingCells }, (_, i) => i + 1);
+
+	const weekDays = [
+		t('schedule.sunday'),
+		t('schedule.monday'),
+		t('schedule.tuesday'),
+		t('schedule.wednesday'),
+		t('schedule.thursday'),
+		t('schedule.friday'),
+		t('schedule.saturday'),
+	];
+
+	// Get events for a specific date
+	const getEventsForDate = (date: Date) => {
+		const y = date.getFullYear();
+		const m = String(date.getMonth() + 1).padStart(2, '0');
+		const d = String(date.getDate()).padStart(2, '0');
+		const dateStr = `${y}-${m}-${d}`;
+		return events.filter((event) => event.date === dateStr);
+	};
+
+	return (
+		<div className="flex flex-col size-full">
+			<div className="flex items-center justify-between p-4">
+				<h2 className="text-xl font-semibold">
+					{new Date(year, month).toLocaleDateString('en-US', {
+						year: 'numeric',
+						month: 'long',
+					})}
+				</h2>
+				<div className="flex items-center gap-2">
+					<Button variant="outline" size="sm" onClick={goToToday}>
+						{t('schedule.today')}
+					</Button>
+					<TooltipProvider>
+						<Tooltip>
+							<TooltipTrigger asChild>
+								<Button variant="outline" size="icon-sm" onClick={goToPrevYear}>
+									<ChevronsLeft className="h-4 w-4" />
+								</Button>
+							</TooltipTrigger>
+							<TooltipContent>
+								<p>{t('schedule.previousYear')}</p>
+							</TooltipContent>
+						</Tooltip>
+					</TooltipProvider>
+					<TooltipProvider>
+						<Tooltip>
+							<TooltipTrigger asChild>
+								<Button variant="outline" size="icon-sm" onClick={goToPrevMonth}>
+									<ChevronLeft className="h-4 w-4" />
+								</Button>
+							</TooltipTrigger>
+							<TooltipContent>
+								<p>{t('schedule.previousMonth')}</p>
+							</TooltipContent>
+						</Tooltip>
+					</TooltipProvider>
+					<TooltipProvider>
+						<Tooltip>
+							<TooltipTrigger asChild>
+								<Button variant="outline" size="icon-sm" onClick={goToNextMonth}>
+									<ChevronRight className="h-4 w-4" />
+								</Button>
+							</TooltipTrigger>
+							<TooltipContent>
+								<p>{t('schedule.nextMonth')}</p>
+							</TooltipContent>
+						</Tooltip>
+					</TooltipProvider>
+					<TooltipProvider>
+						<Tooltip>
+							<TooltipTrigger asChild>
+								<Button variant="outline" size="icon-sm" onClick={goToNextYear}>
+									<ChevronsRight className="h-4 w-4" />
+								</Button>
+							</TooltipTrigger>
+							<TooltipContent>
+								<p>{t('schedule.nextYear')}</p>
+							</TooltipContent>
+						</Tooltip>
+					</TooltipProvider>
+				</div>
+			</div>
+
+			<div className="flex-1 flex flex-col">
+				{/* Week day headers */}
+				<div className="grid grid-cols-7 border-b border-border!">
+					{weekDays.map((day) => (
+						<div
+							key={day}
+							className="text-center py-2 text-sm font-medium text-muted-foreground"
+						>
+							{day}
+						</div>
+					))}
+				</div>
+
+				{/* Date grid */}
+				<div
+					className={`flex-1 grid grid-cols-7`}
+					style={{ gridTemplateRows: `repeat(${weeksNeeded}, minmax(0, 1fr))` }}
+				>
+					{/* Previous month dates */}
+					{prevMonthDays.map((day, index) => (
+						<div
+							key={`prev-${index}`}
+							className="border-r border-b border-border! p-2 text-muted-foreground/50"
+						>
+							<div className="text-sm">{day}</div>
+						</div>
+					))}
+
+					{/* Current month dates */}
+					{currentMonthDays.map((day) => {
+						const date = new Date(year, month, day);
+						const isToday =
+							date.getDate() === new Date().getDate() &&
+							date.getMonth() === new Date().getMonth() &&
+							date.getFullYear() === new Date().getFullYear();
+						const dayEvents = getEventsForDate(date);
+
+						return (
+							<DateCell
+								key={`current-${day}`}
+								day={day}
+								isToday={isToday}
+								events={dayEvents}
+								onEventClick={onEventClick}
+								moreText={t('schedule.more')}
+							/>
+						);
+					})}
+
+					{/* Next month dates */}
+					{nextMonthDays.map((day, index) => (
+						<div
+							key={`next-${index}`}
+							className="border-border! border-r border-b p-2 text-muted-foreground/50"
+						>
+							<div className="text-sm">{day}</div>
+						</div>
+					))}
+				</div>
+			</div>
+		</div>
+	);
+}
diff --git a/examples/web_ui/frontend/src/pages/schedule/create-schedule-dialog.tsx b/examples/web_ui/frontend/src/pages/schedule/create-schedule-dialog.tsx
new file mode 100644
index 0000000..679a224
--- /dev/null
+++ b/examples/web_ui/frontend/src/pages/schedule/create-schedule-dialog.tsx
@@ -0,0 +1,348 @@
+import { format } from 'date-fns';
+import { ChevronDownIcon, CircleAlert, Loader2, PlusCircle } from 'lucide-react';
+import * as React from 'react';
+
+import type { ChatModelConfig, PermissionMode } from '@/api';
+import { LlmSelect } from '@/components/select/LlmSelect';
+import { PermissionModeSelect } from '@/components/select/PermissionModeSelect';
+import { TimezoneSelect } from '@/components/select/TimezoneSelect';
+import { Button } from '@/components/ui/button';
+import { Calendar } from '@/components/ui/calendar';
+import {
+	Dialog,
+	DialogContent,
+	DialogDescription,
+	DialogFooter,
+	DialogHeader,
+	DialogTitle,
+} from '@/components/ui/dialog';
+import { Field, FieldGroup, FieldLabel } from '@/components/ui/field';
+import { Input } from '@/components/ui/input';
+import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover';
+import {
+	Select,
+	SelectContent,
+	SelectItem,
+	SelectTrigger,
+	SelectValue,
+} from '@/components/ui/select';
+import { Switch } from '@/components/ui/switch';
+import { Textarea } from '@/components/ui/textarea';
+import { useAgents } from '@/hooks/useAgents';
+import { useSchedules } from '@/hooks/useSchedules';
+import { useTranslation } from '@/i18n/useI18n';
+
+interface Props {
+	open: boolean;
+	onOpenChange: (open: boolean) => void;
+	onCreated?: () => void;
+}
+
+type FreqType = 'once' | 'daily' | 'weekly' | 'monthly';
+
+function getDefaultForm() {
+	const now = new Date();
+	const hh = String(now.getHours()).padStart(2, '0');
+	const mm = String(now.getMinutes()).padStart(2, '0');
+	return {
+		name: '',
+		description: '',
+		freq: 'daily' as FreqType,
+		date: now,
+		time: `${hh}:${mm}`,
+		endDate: undefined as Date | undefined,
+		agentId: '',
+		chatModelConfig: null as ChatModelConfig | null,
+		permissionMode: 'dont_ask' as PermissionMode,
+		timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+		stateful: false,
+	};
+}
+
+function buildCronExpr(freq: FreqType, time: string, date: Date | undefined): string {
+	const [h, m] = time.split(':').map(Number);
+	switch (freq) {
+		case 'daily':
+			return `${m} ${h} * * *`;
+		case 'weekly': {
+			const weekday = date ? date.getDay() : 1;
+			return `${m} ${h} * * ${weekday}`;
+		}
+		case 'monthly': {
+			const monthDay = date ? date.getDate() : 1;
+			return `${m} ${h} ${monthDay} * *`;
+		}
+		default:
+			return '';
+	}
+}
+
+function DatePickerButton({
+	date,
+	onSelect,
+	placeholder,
+	disabled,
+}: {
+	date: Date | undefined;
+	onSelect: (d: Date | undefined) => void;
+	placeholder: string;
+	disabled?: boolean;
+}) {
+	return (
+		<Popover>
+			<PopoverTrigger asChild>
+				<Button
+					variant="outline"
+					disabled={disabled}
+					size="sm"
+					className="w-32 justify-between font-normal"
+				>
+					{date ? format(date, 'PPP') : placeholder}
+					<ChevronDownIcon className="text-muted-foreground opacity-50" />
+				</Button>
+			</PopoverTrigger>
+			<PopoverContent className="w-auto p-0" align="start">
+				<Calendar
+					mode="single"
+					selected={date}
+					onSelect={onSelect}
+					captionLayout="dropdown"
+				/>
+			</PopoverContent>
+		</Popover>
+	);
+}
+
+export function CreateScheduleDialog({ open, onOpenChange, onCreated }: Props) {
+	const { t } = useTranslation();
+	const { create } = useSchedules();
+	const { agents } = useAgents();
+	const [form, setForm] = React.useState(getDefaultForm);
+	const [loading, setLoading] = React.useState(false);
+	const [error, setError] = React.useState('');
+
+	React.useEffect(() => {
+		if (open) {
+			setForm(getDefaultForm());
+			setError('');
+		}
+	}, [open]);
+
+	React.useEffect(() => {
+		if (agents.length > 0 && !form.agentId) {
+			setForm((prev) => ({ ...prev, agentId: agents[0].id }));
+		}
+	}, [agents, form.agentId]);
+
+	const set = <K extends keyof ReturnType<typeof getDefaultForm>>(
+		key: K,
+		value: ReturnType<typeof getDefaultForm>[K],
+	) => setForm((prev) => ({ ...prev, [key]: value }));
+
+	const isValid =
+		form.name.trim() && !!form.date && !!form.time && !!form.agentId && !!form.chatModelConfig;
+
+	const handleSubmit = async () => {
+		setError('');
+		if (!isValid) return;
+		setLoading(true);
+		try {
+			let cronExpression: string;
+
+			const d = new Date(form.date!);
+			const [h, m] = form.time.split(':').map(Number);
+			d.setHours(h, m, 0, 0);
+
+			if (form.freq === 'once') {
+				cronExpression = `${m} ${h} ${d.getDate()} ${d.getMonth() + 1} *`;
+			} else {
+				cronExpression = buildCronExpr(form.freq, form.time, form.date);
+			}
+
+			await create({
+				name: form.name.trim(),
+				description: form.description.trim(),
+				cron_expression: cronExpression,
+				timezone: form.timezone,
+				agent_id: form.agentId,
+				chat_model_config: form.chatModelConfig!,
+				enabled: true,
+				stateful: form.stateful,
+				permission_mode: form.permissionMode,
+			});
+			onCreated?.();
+			onOpenChange(false);
+		} catch (e) {
+			setError(String(e));
+		} finally {
+			setLoading(false);
+		}
+	};
+
+	return (
+		<Dialog open={open} onOpenChange={onOpenChange}>
+			<DialogContent className="!w-[500px] !max-w-[500px]">
+				<DialogHeader>
+					<DialogTitle>{t('schedule.createSchedule.title')}</DialogTitle>
+					<DialogDescription className="tracking-tight">
+						{t('schedule.createSchedule.description')}
+					</DialogDescription>
+				</DialogHeader>
+
+				<div className="no-scrollbar -mx-4 max-h-[75vh] overflow-y-auto px-4">
+					<FieldGroup className="[&>[data-orientation=horizontal]>:last-child]:w-48">
+						<Field>
+							<FieldLabel>{t('common.name')}</FieldLabel>
+							<Input
+								className="text-sm h-8"
+								value={form.name}
+								onChange={(e) => set('name', e.target.value)}
+								placeholder={t('schedule.createSchedule.namePlaceholder')}
+							/>
+						</Field>
+
+						<Field>
+							<FieldLabel>{t('schedule.createSchedule.descriptionLabel')}</FieldLabel>
+							<Textarea
+								value={form.description}
+								onChange={(e) => set('description', e.target.value)}
+								placeholder={t('schedule.createSchedule.descriptionPlaceholder')}
+								className="min-h-[150px]"
+							/>
+						</Field>
+
+						<div className="flex gap-3">
+							<Field className="flex-1">
+								<FieldLabel>{t('common.date')}</FieldLabel>
+								<DatePickerButton
+									date={form.date}
+									onSelect={(d) => d && set('date', d)}
+									placeholder={t('schedule.pickDate')}
+								/>
+							</Field>
+							<Field className="w-48">
+								<FieldLabel>{t('common.time')}</FieldLabel>
+								<Input
+									type="time"
+									value={form.time}
+									onChange={(e) => set('time', e.target.value)}
+									className="max-h-7 h-7 text-sm appearance-none [&::-webkit-calendar-picker-indicator]:hidden [&::-webkit-calendar-picker-indicator]:appearance-none"
+								/>
+							</Field>
+						</div>
+
+						<Field orientation={'horizontal'}>
+							<FieldLabel>{t('schedule.timezone')}</FieldLabel>
+							<TimezoneSelect
+								className={''}
+								value={form.timezone}
+								onChange={(v) => set('timezone', v)}
+							/>
+						</Field>
+
+						<Field orientation={'horizontal'}>
+							<FieldLabel>{t('schedule.frequency')}</FieldLabel>
+							<Select
+								value={form.freq}
+								onValueChange={(v) => set('freq', v as FreqType)}
+							>
+								<SelectTrigger size="sm">
+									<SelectValue />
+								</SelectTrigger>
+								<SelectContent>
+									<SelectItem value="once">{t('schedule.freqOnce')}</SelectItem>
+									<SelectItem value="daily">{t('schedule.freqDaily')}</SelectItem>
+									<SelectItem value="weekly">
+										{t('schedule.freqWeekly')}
+									</SelectItem>
+									<SelectItem value="monthly">
+										{t('schedule.freqMonthly')}
+									</SelectItem>
+								</SelectContent>
+							</Select>
+						</Field>
+
+						<Field orientation={'horizontal'}>
+							<FieldLabel
+								className={form.freq === 'once' ? 'text-muted-foreground' : ''}
+							>
+								{t('schedule.endAt')}
+							</FieldLabel>
+							<DatePickerButton
+								date={form.freq === 'once' ? undefined : form.endDate}
+								onSelect={(d) => set('endDate', d)}
+								placeholder={t('schedule.pickDate')}
+								disabled={form.freq === 'once'}
+							/>
+						</Field>
+
+						<Field orientation={'horizontal'}>
+							<FieldLabel>{t('common.agent')}</FieldLabel>
+							<Select value={form.agentId} onValueChange={(v) => set('agentId', v)}>
+								<SelectTrigger className="w-full" size="sm">
+									<SelectValue placeholder={t('common.selectAgent')} />
+								</SelectTrigger>
+								<SelectContent>
+									{agents.map((agent) => (
+										<SelectItem key={agent.id} value={agent.id}>
+											{agent.data.name}
+										</SelectItem>
+									))}
+								</SelectContent>
+							</Select>
+						</Field>
+
+						<Field orientation={'horizontal'}>
+							<FieldLabel>{t('common.model')}</FieldLabel>
+							<LlmSelect
+								value={form.chatModelConfig}
+								onChange={(v) => set('chatModelConfig', v)}
+							/>
+						</Field>
+
+						<Field orientation={'horizontal'}>
+							<FieldLabel>{t('schedule.permissionMode')}</FieldLabel>
+							<PermissionModeSelect
+								className="w-full"
+								value={form.permissionMode}
+								onChange={(v) => set('permissionMode', v)}
+							/>
+						</Field>
+
+						<Field>
+							<div className="flex flex-row items-center justify-between">
+								<div className="flex flex-col gap-y-0.5">
+									<FieldLabel>{t('schedule.stateful')}</FieldLabel>
+									<span className="text-xs text-muted-foreground">
+										{t('schedule.statefulDesc')}
+									</span>
+								</div>
+								<Switch
+									checked={form.stateful}
+									onCheckedChange={(v) => set('stateful', v)}
+								/>
+							</div>
+						</Field>
+
+						{error && <p className="text-sm text-destructive">{error}</p>}
+					</FieldGroup>
+				</div>
+
+				<DialogFooter>
+					<Button variant="ghost" onClick={() => onOpenChange(false)} disabled={loading}>
+						<CircleAlert className="size-3.5" />
+						{t('common.cancel')}
+					</Button>
+					<Button onClick={handleSubmit} disabled={loading || !isValid}>
+						{loading ? (
+							<Loader2 className="size-3.5 animate-spin" />
+						) : (
+							<PlusCircle className="size-3.5" />
+						)}
+						{loading ? t('common.creating') : t('common.create')}
+					</Button>
+				</DialogFooter>
+			</DialogContent>
+		</Dialog>
+	);
+}
diff --git a/examples/web_ui/frontend/src/pages/schedule/empty-state.tsx b/examples/web_ui/frontend/src/pages/schedule/empty-state.tsx
new file mode 100644
index 0000000..7a65576
--- /dev/null
+++ b/examples/web_ui/frontend/src/pages/schedule/empty-state.tsx
@@ -0,0 +1,46 @@
+import { Calendar } from 'lucide-react';
+import type { ReactNode } from 'react';
+
+import {
+	Empty,
+	EmptyContent,
+	EmptyDescription,
+	EmptyHeader,
+	EmptyMedia,
+	EmptyTitle,
+} from '@/components/ui/empty';
+import { useTranslation } from '@/i18n/useI18n';
+
+interface EmptyStateProps {
+	title?: string;
+	description?: string;
+	action?: ReactNode;
+}
+
+/**
+ * Empty state component for schedule page
+ *
+ * @param root0 - Component props
+ * @param root0.title - Title text
+ * @param root0.description - Description text
+ * @param root0.action - Action element (e.g., button)
+ * @returns EmptyState component
+ */
+export function EmptyState({ title, description, action }: EmptyStateProps) {
+	const { t } = useTranslation();
+
+	return (
+		<Empty className="size-full">
+			<EmptyHeader>
+				<EmptyMedia variant="icon">
+					<Calendar />
+				</EmptyMedia>
+				<EmptyTitle>{title || t('schedule.noSchedules')}</EmptyTitle>
+				<EmptyDescription>
+					{description || t('schedule.noSchedulesDescription')}
+				</EmptyDescription>
+			</EmptyHeader>
+			<EmptyContent>{action}</EmptyContent>
+		</Empty>
+	);
+}
diff --git a/examples/web_ui/frontend/src/pages/schedule/event.tsx b/examples/web_ui/frontend/src/pages/schedule/event.tsx
new file mode 100644
index 0000000..9a3083a
--- /dev/null
+++ b/examples/web_ui/frontend/src/pages/schedule/event.tsx
@@ -0,0 +1,9 @@
+export interface ScheduleEvent {
+	id: string;
+	title: string;
+	date: string; // ISO format: YYYY-MM-DD
+	time: string; // 24-hour format: HH:mm
+	content: string;
+	location?: string;
+	attendees?: string[];
+}
diff --git a/examples/web_ui/frontend/src/pages/schedule/index.tsx b/examples/web_ui/frontend/src/pages/schedule/index.tsx
new file mode 100644
index 0000000..78d8faf
--- /dev/null
+++ b/examples/web_ui/frontend/src/pages/schedule/index.tsx
@@ -0,0 +1,132 @@
+import { CronExpressionParser } from 'cron-parser';
+import { Calendar, List, Plus } from 'lucide-react';
+import * as React from 'react';
+
+import type { ScheduleEvent } from './event';
+import type { ScheduleRecord } from '@/api';
+import { Button } from '@/components/ui/button';
+import { Tabs, TabsList, TabsTrigger } from '@/components/ui/tabs';
+import { useSchedules } from '@/hooks/useSchedules';
+import { useTranslation } from '@/i18n/useI18n';
+import { CalendarTabPage } from '@/pages/schedule/calendar-tab-page';
+import { CreateScheduleDialog } from '@/pages/schedule/create-schedule-dialog';
+import { ListTabPage } from '@/pages/schedule/list-tab-page';
+import { ScheduleDetailDrawer } from '@/pages/schedule/schedule-detail-drawer';
+
+function expandScheduleToEvents(
+	schedule: ScheduleRecord,
+	rangeStart: Date,
+	rangeEnd: Date,
+): ScheduleEvent[] {
+	const events: ScheduleEvent[] = [];
+	const { data } = schedule;
+	try {
+		const interval = CronExpressionParser.parse(data.cron_expression, {
+			currentDate: rangeStart,
+			endDate: rangeEnd,
+		});
+		const startTs = new Date(data.started_at).getTime();
+		const endTs = data.ended_at ? new Date(data.ended_at).getTime() : null;
+		while (interval.hasNext()) {
+			const date = interval.next().toDate();
+			const ts = date.getTime();
+			if (ts < startTs) continue;
+			if (endTs && ts > endTs) break;
+			const localDate = `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`;
+			const localTime = `${String(date.getHours()).padStart(2, '0')}:${String(date.getMinutes()).padStart(2, '0')}`;
+			events.push({
+				id: `${schedule.id}:${ts}`,
+				title: data.name,
+				date: localDate,
+				time: localTime,
+				content: data.description,
+			});
+		}
+	} catch {
+		// invalid cron expr — skip
+	}
+	return events;
+}
+
+export function SchedulePage() {
+	const { t } = useTranslation();
+	const { schedules, remove, refetch } = useSchedules();
+	const [viewMode, setViewMode] = React.useState<'calendar' | 'list'>('calendar');
+	const [currentDate, setCurrentDate] = React.useState(new Date());
+	const [selectedSchedule, setSelectedSchedule] = React.useState<ScheduleRecord | null>(null);
+	const [isCreateOpen, setIsCreateOpen] = React.useState(false);
+
+	const rangeStart = React.useMemo(
+		() => new Date(currentDate.getFullYear(), currentDate.getMonth(), 1),
+		[currentDate],
+	);
+	const rangeEnd = React.useMemo(
+		() => new Date(currentDate.getFullYear(), currentDate.getMonth() + 1, 0, 23, 59, 59),
+		[currentDate],
+	);
+
+	const events = React.useMemo(() => {
+		return schedules
+			.filter((s) => s.data.enabled)
+			.flatMap((s) => expandScheduleToEvents(s, rangeStart, rangeEnd));
+	}, [schedules, rangeStart, rangeEnd]);
+
+	const handleEventClick = (event: ScheduleEvent) => {
+		const scheduleId = event.id.split(':')[0];
+		const schedule = schedules.find((s) => s.id === scheduleId);
+		if (schedule) setSelectedSchedule(schedule);
+	};
+
+	return (
+		<div className="w-full h-full flex flex-col bg-sidebar overflow-hidden">
+			<div className="flex items-center justify-between p-4 flex-shrink-0">
+				<span className="text-2xl font-semibold">{t('common.schedule')}</span>
+				<div className="flex items-center gap-2">
+					<Button size="icon-sm" onClick={() => setIsCreateOpen(true)}>
+						<Plus />
+					</Button>
+					<Tabs
+						value={viewMode}
+						onValueChange={(value) => setViewMode(value as 'calendar' | 'list')}
+					>
+						<TabsList>
+							<TabsTrigger value="calendar" className="border-none w-[100px]">
+								<Calendar className="h-4 w-4" />
+								<span>{t('schedule.calendar')}</span>
+							</TabsTrigger>
+							<TabsTrigger value="list" className="border-none w-[100px]">
+								<List className="h-4 w-4" />
+								<span>{t('schedule.list')}</span>
+							</TabsTrigger>
+						</TabsList>
+					</Tabs>
+				</div>
+			</div>
+
+			<div className="flex-1 overflow-hidden rounded-t-3xl bg-white">
+				{viewMode === 'calendar' && (
+					<CalendarTabPage
+						events={events}
+						onEventClick={handleEventClick}
+						currentDate={currentDate}
+						onMonthChange={setCurrentDate}
+					/>
+				)}
+				{viewMode === 'list' && <ListTabPage />}
+			</div>
+
+			<ScheduleDetailDrawer
+				schedule={selectedSchedule}
+				open={!!selectedSchedule}
+				onOpenChange={(open) => !open && setSelectedSchedule(null)}
+				onDelete={remove}
+			/>
+
+			<CreateScheduleDialog
+				open={isCreateOpen}
+				onOpenChange={setIsCreateOpen}
+				onCreated={refetch}
+			/>
+		</div>
+	);
+}
diff --git a/examples/web_ui/frontend/src/pages/schedule/list-tab-page.tsx b/examples/web_ui/frontend/src/pages/schedule/list-tab-page.tsx
new file mode 100644
index 0000000..1d0aad3
--- /dev/null
+++ b/examples/web_ui/frontend/src/pages/schedule/list-tab-page.tsx
@@ -0,0 +1,141 @@
+import { CronExpressionParser } from 'cron-parser';
+import { format } from 'date-fns';
+import { CalendarIcon } from 'lucide-react';
+import * as React from 'react';
+import { type DateRange } from 'react-day-picker';
+
+import type { ScheduleRecord } from '@/api';
+import { Button } from '@/components/ui/button';
+import { Calendar } from '@/components/ui/calendar';
+import { Field } from '@/components/ui/field';
+import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover';
+import { useSchedules } from '@/hooks/useSchedules';
+import { useTranslation } from '@/i18n/useI18n';
+import { EmptyState } from '@/pages/schedule/empty-state';
+import { ScheduleCard } from '@/pages/schedule/schedule-card';
+import { ScheduleDetailDrawer } from '@/pages/schedule/schedule-detail-drawer';
+
+function scheduleHasOccurrencesInRange(
+	schedule: ScheduleRecord,
+	rangeStart: Date,
+	rangeEnd: Date,
+): boolean {
+	const { data } = schedule;
+	try {
+		const interval = CronExpressionParser.parse(data.cron_expression, {
+			currentDate: rangeStart,
+			endDate: rangeEnd,
+		});
+
+		const startTs = new Date(data.started_at).getTime();
+		const endTs = data.ended_at ? new Date(data.ended_at).getTime() : null;
+
+		while (interval.hasNext()) {
+			const date = interval.next().toDate();
+			const ts = date.getTime();
+
+			if (ts < startTs) continue;
+			if (endTs && ts > endTs) break;
+
+			return true;
+		}
+
+		return false;
+	} catch {
+		return true;
+	}
+}
+
+export function ListTabPage() {
+	const { t } = useTranslation();
+	const { schedules, loading, remove } = useSchedules();
+	const [selectedSchedule, setSelectedSchedule] = React.useState<ScheduleRecord | null>(null);
+	const [dateRange, setDateRange] = React.useState<DateRange | undefined>(undefined);
+
+	const filteredSchedules = React.useMemo(() => {
+		if (!dateRange?.from) {
+			return schedules;
+		}
+
+		const rangeStart = dateRange.from;
+		const rangeEnd = dateRange.to || dateRange.from;
+
+		return schedules.filter((schedule) =>
+			scheduleHasOccurrencesInRange(schedule, rangeStart, rangeEnd),
+		);
+	}, [schedules, dateRange]);
+
+	if (loading) {
+		return (
+			<div className="flex items-center justify-center h-full">
+				<div className="text-muted-foreground">{t('common.loading')}</div>
+			</div>
+		);
+	}
+
+	return (
+		<div className="flex flex-col size-full">
+			<div className="flex flex-row w-full p-4 justify-between">
+				<Field className="flex flex-row w-fit">
+					<Popover>
+						<PopoverTrigger asChild>
+							<Button
+								variant="outline"
+								id="date-picker-range"
+								className="justify-start px-2.5 font-normal"
+								size="sm"
+							>
+								<CalendarIcon />
+								{dateRange?.from ? (
+									dateRange.to ? (
+										<>
+											{format(dateRange.from, 'LLL dd, y')} -{' '}
+											{format(dateRange.to, 'LLL dd, y')}
+										</>
+									) : (
+										format(dateRange.from, 'LLL dd, y')
+									)
+								) : (
+									<span className="text-muted-foreground">
+										{t('schedule.pickDate')}
+									</span>
+								)}
+							</Button>
+						</PopoverTrigger>
+						<PopoverContent className="w-auto p-0" align="start">
+							<Calendar
+								mode="range"
+								defaultMonth={dateRange?.from}
+								selected={dateRange}
+								onSelect={setDateRange}
+								numberOfMonths={2}
+							/>
+						</PopoverContent>
+					</Popover>
+				</Field>
+			</div>
+			<div className="size-full overflow-y-auto p-4">
+				{filteredSchedules.length === 0 ? (
+					<EmptyState />
+				) : (
+					<div className="space-y-3">
+						{filteredSchedules.map((schedule) => (
+							<ScheduleCard
+								key={schedule.id}
+								schedule={schedule}
+								onClick={() => setSelectedSchedule(schedule)}
+							/>
+						))}
+					</div>
+				)}
+			</div>
+
+			<ScheduleDetailDrawer
+				schedule={selectedSchedule}
+				open={!!selectedSchedule}
+				onOpenChange={(open) => !open && setSelectedSchedule(null)}
+				onDelete={remove}
+			/>
+		</div>
+	);
+}
diff --git a/examples/web_ui/frontend/src/pages/schedule/schedule-card.tsx b/examples/web_ui/frontend/src/pages/schedule/schedule-card.tsx
new file mode 100644
index 0000000..c47b1a4
--- /dev/null
+++ b/examples/web_ui/frontend/src/pages/schedule/schedule-card.tsx
@@ -0,0 +1,50 @@
+import { Pause, Calendar, ArrowRight, Bot, ClipboardClock, BotOff } from 'lucide-react';
+
+import { parseCronExpression, getFrequencyLabel } from './schedule-utils';
+import type { ScheduleRecord } from '@/api';
+import { Badge } from '@/components/ui/badge';
+import { Item, ItemContent, ItemDescription, ItemMedia, ItemTitle } from '@/components/ui/item';
+import { useTranslation } from '@/i18n/useI18n';
+
+interface ScheduleCardProps {
+	schedule: ScheduleRecord;
+	onClick: () => void;
+}
+
+export function ScheduleCard({ schedule, onClick }: ScheduleCardProps) {
+	const { t } = useTranslation();
+	const { data } = schedule;
+	const parsed = parseCronExpression(data.cron_expression, data.started_at);
+
+	return (
+		<Item className="cursor-pointer hover:shadow-md" variant="outline" onClick={onClick}>
+			<ItemMedia variant="icon">{data.enabled ? <Bot /> : <BotOff />}</ItemMedia>
+			<ItemContent>
+				<ItemTitle className="font-[550] truncate max-w-full">{data.name}</ItemTitle>
+				<ItemDescription className="flex gap-x-2 items-center text-xs truncate overflow-hidden">
+					{!data.enabled && (
+						<Badge variant="secondary" className="gap-1">
+							<Pause className="h-3 w-3" />
+							{t('common.disabled')}
+						</Badge>
+					)}
+					<Badge variant="link" className="pl-0">
+						<Calendar data-icon="inline-start" />
+						{new Date(data.started_at).toLocaleDateString()}
+						{data.ended_at && (
+							<div className="flex items-center gap-1">
+								<ArrowRight className="size-3 text-muted-foreground" />
+								{new Date(data.ended_at).toLocaleDateString()}
+							</div>
+						)}
+						<div>{parsed.time}</div>
+					</Badge>
+					<Badge variant="link">
+						<ClipboardClock data-icon="inline-start" />
+						{getFrequencyLabel(parsed, t)}
+					</Badge>
+				</ItemDescription>
+			</ItemContent>
+		</Item>
+	);
+}
diff --git a/examples/web_ui/frontend/src/pages/schedule/schedule-detail-drawer.tsx b/examples/web_ui/frontend/src/pages/schedule/schedule-detail-drawer.tsx
new file mode 100644
index 0000000..e102b18
--- /dev/null
+++ b/examples/web_ui/frontend/src/pages/schedule/schedule-detail-drawer.tsx
@@ -0,0 +1,220 @@
+import { Trash2 } from 'lucide-react';
+import * as React from 'react';
+import { useNavigate } from 'react-router-dom';
+
+import { parseCronExpression, getFrequencyLabel } from './schedule-utils';
+import type { ScheduleRecord, SessionRecord } from '@/api';
+import { scheduleApi } from '@/api';
+import { StatusBadge } from '@/components/badge/StatusBadge';
+import { DeleteDialog } from '@/components/dialog/DeleteDialog';
+import { Button } from '@/components/ui/button';
+import {
+	Drawer,
+	DrawerContent,
+	DrawerDescription,
+	DrawerFooter,
+	DrawerHeader,
+	DrawerTitle,
+} from '@/components/ui/drawer';
+import { Separator } from '@/components/ui/separator';
+import { useAgents } from '@/hooks/useAgents';
+import { useTranslation } from '@/i18n/useI18n';
+
+interface ScheduleDetailDrawerProps {
+	schedule: ScheduleRecord | null;
+	open: boolean;
+	onOpenChange: (open: boolean) => void;
+	onDelete: (scheduleId: string) => Promise<void>;
+}
+
+export function ScheduleDetailDrawer({
+	schedule,
+	open,
+	onOpenChange,
+	onDelete,
+}: ScheduleDetailDrawerProps) {
+	const { t } = useTranslation();
+	const { agents } = useAgents();
+	const navigate = useNavigate();
+	const [openDeleteDialog, setOpenDeleteDialog] = React.useState(false);
+	const [sessions, setSessions] = React.useState<SessionRecord[]>([]);
+	const [sessionsLoading, setSessionsLoading] = React.useState(false);
+
+	React.useEffect(() => {
+		if (!schedule || !open) {
+			setSessions([]);
+			return;
+		}
+		setSessionsLoading(true);
+		scheduleApi
+			.listSessions(schedule.id)
+			.then((res) => setSessions(res.sessions))
+			.catch(() => setSessions([]))
+			.finally(() => setSessionsLoading(false));
+	}, [schedule, open]);
+
+	const handleDelete = async () => {
+		if (!schedule) return;
+		await onDelete(schedule.id);
+		onOpenChange(false);
+	};
+
+	if (!schedule) return null;
+
+	const { data } = schedule;
+	const parsed = parseCronExpression(data.cron_expression, data.started_at);
+	const agentName =
+		agents.find((a) => a.id === schedule.agent_id)?.data.name ?? schedule.agent_id;
+
+	const weekdayNames = [
+		t('schedule.sunday'),
+		t('schedule.monday'),
+		t('schedule.tuesday'),
+		t('schedule.wednesday'),
+		t('schedule.thursday'),
+		t('schedule.friday'),
+		t('schedule.saturday'),
+	];
+
+	let triggerTimeDisplay = parsed.time;
+	switch (parsed.frequency) {
+		case 'weekly':
+			triggerTimeDisplay = `${weekdayNames[parsed.weekday ?? 0]} ${parsed.time}`;
+			break;
+		case 'monthly':
+			triggerTimeDisplay = `${parsed.dayOfMonth ?? 1}${t('schedule.dayOfMonthSuffix')} ${parsed.time}`;
+			break;
+		case 'once':
+			triggerTimeDisplay = parsed.date
+				? `${parsed.date.toLocaleDateString()} ${parsed.time}`
+				: parsed.time;
+			break;
+	}
+	triggerTimeDisplay += ` (${data.timezone})`;
+
+	const scheduleInfoItems = [
+		{
+			title: t('schedule.frequency'),
+			content: getFrequencyLabel(parsed, t),
+		},
+		{
+			title: t('schedule.triggerTime'),
+			content: triggerTimeDisplay,
+		},
+		{
+			title: t('schedule.createdAt'),
+			content: new Date(schedule.created_at).toLocaleString(),
+		},
+		{
+			title: t('schedule.end_at'),
+			content: data.ended_at ? new Date(data.ended_at).toLocaleString() : t('common.noData'),
+		},
+		{
+			title: t('common.agent'),
+			content: agentName,
+		},
+		{
+			title: t('schedule.permissionMode'),
+			content: data.permission_mode,
+		},
+		{
+			title: t('schedule.stateful'),
+			content: data.stateful ? t('common.yes') : t('common.no'),
+		},
+	];
+
+	return (
+		<>
+			<Drawer open={open} onOpenChange={onOpenChange} direction="right">
+				<DrawerContent className="max-h-full h-full min-w-[30rem] ml-auto border-none ring-none! shadow-none!">
+					<DrawerHeader>
+						<DrawerTitle>{data.name}</DrawerTitle>
+						<DrawerDescription>{data.description}</DrawerDescription>
+					</DrawerHeader>
+					<div className="flex flex-1 flex-col overflow-hidden gap-y-4 p-4">
+						<div className="flex flex-col space-y-2">
+							<h3 className="text-sm font-semibold text-secondary-foreground">
+								{t('common.information')}
+							</h3>
+							<div className="flex flex-col gap-2">
+								{scheduleInfoItems.map((item) => (
+									<div
+										key={item.title}
+										className="flex flex-row justify-between text-xs px-2.5 py-2 font-mono rounded-md ring ring-border items-center"
+									>
+										<span className="font-medium">
+											{item.title.toUpperCase()}
+										</span>
+										<span className="ml-auto text-muted-foreground">
+											{item.content}
+										</span>
+									</div>
+								))}
+							</div>
+						</div>
+						<Separator />
+						<div className="space-y-2 flex flex-col flex-1 overflow-hidden">
+							<h3 className="text-sm font-semibold">
+								{t('schedule.executionHistory')}
+							</h3>
+							<div className="flex-1 overflow-y-auto space-y-1">
+								{sessionsLoading && (
+									<div className="text-center py-4 text-muted-foreground text-sm">
+										{t('common.loading')}
+									</div>
+								)}
+								{!sessionsLoading && sessions.length === 0 && (
+									<div className="text-center py-4 text-muted-foreground text-sm">
+										{t('common.noData')}
+									</div>
+								)}
+								{!sessionsLoading &&
+									sessions.map((session) => (
+										<div
+											key={session.id}
+											className="flex flex-row justify-between text-xs px-2.5 py-2 font-mono rounded-md ring ring-border items-center cursor-pointer hover:bg-muted/50 transition-colors"
+											onClick={() => {
+												navigate(
+													`/chat/${schedule.agent_id}/${session.id}`,
+												);
+												onOpenChange(false);
+											}}
+										>
+											<span className="text-muted-foreground">
+												{new Date(session.created_at).toLocaleString()}
+											</span>
+											<StatusBadge status="completed" />
+										</div>
+									))}
+							</div>
+						</div>
+					</div>
+					<DrawerFooter>
+						<Button
+							variant="destructive"
+							size="sm"
+							onClick={(e) => {
+								e.preventDefault();
+								setOpenDeleteDialog(true);
+							}}
+						>
+							<Trash2 className="size-3" />
+							{t('common.delete')}
+						</Button>
+					</DrawerFooter>
+				</DrawerContent>
+			</Drawer>
+
+			<DeleteDialog
+				open={openDeleteDialog}
+				onOpenChange={setOpenDeleteDialog}
+				title={t('common.deleteTitle', {
+					entity: t('schedule.deleteSchedule.entity'),
+					name: data.name,
+				})}
+				description={t('common.deleteDescription')}
+				onConfirm={handleDelete}
+			/>
+		</>
+	);
+}
diff --git a/examples/web_ui/frontend/src/pages/schedule/schedule-utils.ts b/examples/web_ui/frontend/src/pages/schedule/schedule-utils.ts
new file mode 100644
index 0000000..db9155e
--- /dev/null
+++ b/examples/web_ui/frontend/src/pages/schedule/schedule-utils.ts
@@ -0,0 +1,50 @@
+export interface ParsedSchedule {
+	frequency: 'daily' | 'weekly' | 'monthly' | 'once' | 'custom';
+	time: string; // HH:mm format
+	weekday?: number; // 0-6 for weekly
+	dayOfMonth?: number; // 1-31 for monthly
+	date?: Date; // for once
+}
+
+export function parseCronExpression(cronExpression: string, startedAt: string): ParsedSchedule {
+	const parts = cronExpression.trim().split(/\s+/);
+	if (parts.length !== 5) {
+		return { frequency: 'custom', time: '00:00' };
+	}
+
+	const [minute, hour, day, month, weekday] = parts;
+	const time = `${hour.padStart(2, '0')}:${minute.padStart(2, '0')}`;
+
+	if (day === '*' && month === '*' && weekday === '*') {
+		return { frequency: 'daily', time };
+	}
+
+	if (day === '*' && month === '*' && weekday !== '*') {
+		return { frequency: 'weekly', time, weekday: parseInt(weekday) };
+	}
+
+	if (day !== '*' && month === '*' && weekday === '*') {
+		return { frequency: 'monthly', time, dayOfMonth: parseInt(day) };
+	}
+
+	if (day !== '*' && month !== '*') {
+		return { frequency: 'once', time, date: new Date(startedAt) };
+	}
+
+	return { frequency: 'custom', time };
+}
+
+export function getFrequencyLabel(parsed: ParsedSchedule, t: (key: string) => string): string {
+	switch (parsed.frequency) {
+		case 'daily':
+			return t('schedule.freqDaily');
+		case 'weekly':
+			return t('schedule.freqWeekly');
+		case 'monthly':
+			return t('schedule.freqMonthly');
+		case 'once':
+			return t('schedule.freqOnce');
+		default:
+			return 'Custom';
+	}
+}
diff --git a/examples/web_ui/frontend/src/pages/setup/index.tsx b/examples/web_ui/frontend/src/pages/setup/index.tsx
new file mode 100644
index 0000000..6997409
--- /dev/null
+++ b/examples/web_ui/frontend/src/pages/setup/index.tsx
@@ -0,0 +1,83 @@
+import { useState } from 'react';
+
+import { Button } from '@/components/ui/button.tsx';
+import {
+	Card,
+	CardContent,
+	CardDescription,
+	CardHeader,
+	CardTitle,
+} from '@/components/ui/card.tsx';
+import { Field, FieldDescription, FieldGroup, FieldLabel } from '@/components/ui/field.tsx';
+import { Input } from '@/components/ui/input.tsx';
+import { useTranslation } from '@/i18n/useI18n.ts';
+import { cn } from '@/lib/utils.ts';
+
+interface Props {
+	onComplete: () => void;
+	className?: string;
+}
+
+export const SetupPage = ({ onComplete, className }: Props) => {
+	const { t } = useTranslation();
+	const [url, setUrl] = useState(() => localStorage.getItem('server_url') ?? '');
+	const [username, setUsername] = useState(() => localStorage.getItem('username') ?? '');
+
+	const handleSubmit = (e: React.FormEvent) => {
+		e.preventDefault();
+		localStorage.setItem('server_url', url);
+		localStorage.setItem('username', username);
+		onComplete();
+	};
+
+	return (
+		<div className="flex items-center justify-center h-full">
+			<div className={cn('flex flex-col gap-6 w-full max-w-sm', className)}>
+				<Card>
+					<CardHeader>
+						<CardTitle>{t('setup.title')}</CardTitle>
+						<CardDescription>{t('setup.description')}</CardDescription>
+					</CardHeader>
+					<CardContent>
+						<form onSubmit={handleSubmit}>
+							<FieldGroup>
+								<Field>
+									<FieldLabel htmlFor="server-url-input">
+										{t('setup.serverUrl')}
+									</FieldLabel>
+									<Input
+										id="server-url-input"
+										type="url"
+										placeholder={t('setup.serverUrlPlaceholder')}
+										value={url}
+										onChange={(e) => setUrl(e.target.value)}
+										required
+									/>
+								</Field>
+								<Field>
+									<FieldLabel htmlFor="username-input">
+										{t('setup.username')}
+									</FieldLabel>
+									<Input
+										id="username-input"
+										type="text"
+										placeholder={t('setup.usernamePlaceholder')}
+										value={username}
+										onChange={(e) => setUsername(e.target.value)}
+										required
+									/>
+								</Field>
+								<Field>
+									<Button type="submit" className="w-full">
+										{t('setup.submit')}
+									</Button>
+								</Field>
+							</FieldGroup>
+						</form>
+					</CardContent>
+				</Card>
+				<FieldDescription className="px-6 text-center">{t('setup.hint')}</FieldDescription>
+			</div>
+		</div>
+	);
+};
diff --git a/examples/web_ui/frontend/src/types/unidiff.d.ts b/examples/web_ui/frontend/src/types/unidiff.d.ts
new file mode 100644
index 0000000..d273a81
--- /dev/null
+++ b/examples/web_ui/frontend/src/types/unidiff.d.ts
@@ -0,0 +1,20 @@
+declare module 'unidiff' {
+	interface DiffOptions {
+		aname?: string;
+		bname?: string;
+		context?: number;
+		pre_context?: number;
+		post_context?: number;
+		format?: 'unified';
+	}
+
+	const unidiff: {
+		diffAsText: (
+			oldText: string | string[],
+			newText: string | string[],
+			options?: DiffOptions,
+		) => string;
+	};
+
+	export default unidiff;
+}
diff --git a/examples/web_ui/frontend/src/utils/common.ts b/examples/web_ui/frontend/src/utils/common.ts
new file mode 100644
index 0000000..5ad509a
--- /dev/null
+++ b/examples/web_ui/frontend/src/utils/common.ts
@@ -0,0 +1,96 @@
+/**
+ * Copy a string to the system clipboard.
+ *
+ * @param text The text content to copy.
+ * @returns A promise that resolves to true if the copy succeeds; false otherwise.
+ */
+export const copyToClipboard = async (text: string): Promise<boolean> => {
+	try {
+		await navigator.clipboard.writeText(text);
+		return true;
+	} catch (err) {
+		console.error('Failed to copy text: ', err);
+		return false;
+	}
+};
+
+/**
+ * Format a number to a human-readable string with commas and suffixes
+ * @param num - The number to format
+ * @returns Formatted string (e.g., "1,000", "10.2k", "1.5M")
+ */
+export function formatNumber(num: number): string {
+	if (num < 1000) {
+		return num.toLocaleString();
+	}
+
+	const units = [
+		{ value: 1e9, suffix: 'B' },
+		{ value: 1e6, suffix: 'M' },
+		{ value: 1e3, suffix: 'k' },
+	];
+
+	for (const { value, suffix } of units) {
+		if (num >= value) {
+			const formatted = num / value;
+			// Keep 1-2 decimal places, remove trailing zeros
+			const decimals = formatted >= 10 ? 1 : 2;
+			return formatted.toFixed(decimals).replace(/\.0+$/, '') + suffix;
+		}
+	}
+
+	return num.toLocaleString();
+}
+
+/**
+ * Format a duration in seconds into a human-readable string with appropriate units.
+ * Converts seconds to milliseconds for values less than 1 second.
+ *
+ * @param seconds - The duration in seconds to format
+ * @returns Formatted string with unit (e.g., "500.00ms" or "2.50s")
+ */
+export const formatDurationWithUnit = (seconds: number): string => {
+	if (seconds < 1) {
+		return `${(seconds * 1000).toFixed(2)}ms`;
+	}
+	return `${seconds.toFixed(2)}s`;
+};
+
+/**
+ * Format a duration in seconds into a numeric value with appropriate scaling.
+ * Converts seconds to milliseconds for values less than 1 second.
+ *
+ * @param seconds - The duration in seconds to format
+ * @returns Formatted number (in milliseconds if < 1 second, otherwise in seconds)
+ */
+export const formatDuration = (seconds: number): number => {
+	if (seconds < 1) {
+		return parseFloat((seconds * 1000).toFixed(2));
+	}
+	return parseFloat(seconds.toFixed(2));
+};
+
+/**
+ * Format a duration in seconds into a human-readable, compact string.
+ *
+ * - Integer-only output (e.g. `45s`, `2min30s`, `3h`); no decimals.
+ * - Adjacent unit segments are concatenated without spaces.
+ * - Once the leading unit is hours, only whole hours are shown — minute and
+ *   second precision is not useful at that scale and would only widen the
+ *   badge when, e.g., a tool call sits awaiting user confirmation for hours.
+ *
+ * @param seconds - The duration in seconds to format
+ * @returns Formatted string (e.g., "45s", "2min30s", "3h")
+ */
+export const formatTime = (seconds: number): string => {
+	const total = Math.floor(seconds);
+	if (total < 60) {
+		return `${total}s`;
+	}
+	if (total < 3600) {
+		const minutes = Math.floor(total / 60);
+		const remaining = total % 60;
+		return remaining === 0 ? `${minutes}m` : `${minutes}m${remaining}s`;
+	}
+	return `${Math.floor(total / 3600)}h`;
+};
diff --git a/examples/web_ui/frontend/src/utils/platform.ts b/examples/web_ui/frontend/src/utils/platform.ts
new file mode 100644
index 0000000..419c329
--- /dev/null
+++ b/examples/web_ui/frontend/src/utils/platform.ts
@@ -0,0 +1,33 @@
+export type Platform = 'darwin' | 'win32' | 'linux';
+
+/**
+ * Gets the current platform (darwin, win32, or linux).
+ *
+ * @returns The platform identifier.
+ */
+export function getPlatform(): Platform {
+	// Use modern userAgentData API if available
+	const uaData = (navigator as Navigator & { userAgentData?: { platform: string } })
+		.userAgentData;
+	if (uaData?.platform) {
+		const platform = uaData.platform.toLowerCase();
+		if (platform.includes('mac')) return 'darwin';
+		if (platform.includes('win')) return 'win32';
+		return 'linux';
+	}
+
+	// Fallback to userAgent string
+	const userAgent = navigator.userAgent.toLowerCase();
+	if (userAgent.includes('mac')) return 'darwin';
+	if (userAgent.includes('win')) return 'win32';
+	return 'linux';
+}
+
+/**
+ * Checks if the current platform is macOS.
+ *
+ * @returns True if the platform is macOS, false otherwise.
+ */
+export function isMac(): boolean {
+	return getPlatform() === 'darwin';
+}
diff --git a/examples/web_ui/frontend/src/utils/streamingAudio.ts b/examples/web_ui/frontend/src/utils/streamingAudio.ts
new file mode 100644
index 0000000..f27b038
--- /dev/null
+++ b/examples/web_ui/frontend/src/utils/streamingAudio.ts
@@ -0,0 +1,387 @@
+/**
+ * Streaming audio playback support for assistant DataBlocks.
+ *
+ * Omni-style models (e.g. qwen3.5-omni-plus) deliver speech as a stream of
+ * DATA_BLOCK_DELTA events carrying base64 audio bytes for one logical
+ * DataBlock. This module routes those chunks to two playback paths:
+ *
+ *   1. **Live chunked playback** — only for audio/wav. We parse the RIFF
+ *      header from the first chunk and schedule subsequent PCM bytes onto a
+ *      Web Audio timeline as they arrive, so the assistant starts speaking
+ *      the moment the first chunk arrives — without waiting for
+ *      DATA_BLOCK_END, which the agent only emits after the *entire* model
+ *      stream (including text) finishes.
+ *
+ *   2. **Buffered final playback** — for non-wav formats (mp3/opus/etc.) we
+ *      accumulate bytes and, on DATA_BLOCK_END, build a Blob URL that backs
+ *      autoplay + an ``<audio controls>`` element for replay/scrubbing.
+ *
+ * For wav, the controls element built on DATA_BLOCK_END is replay-only —
+ * we intentionally skip the second autoplay there to avoid colliding with
+ * the live player. ``WavStreamPlayer.finalize`` defers AudioContext
+ * teardown until queued PCM has finished playing, so live audio is never
+ * cut short by the end event arriving mid-playback.
+ */
+
+/** Status of a streaming audio block. */
+export type StreamingAudioStatus = 'streaming' | 'ready' | 'error';
+
+/** Per-block state surfaced to React. */
+export interface StreamingAudioState {
+	status: StreamingAudioStatus;
+	mediaType: string;
+	/** Object URL for ``<audio>`` once playback-ready. */
+	url: string | null;
+	/** Cause for ``status === 'error'``. */
+	error?: string;
+	/** Incremented each time a newer reply interrupts this block. */
+	interruptCount: number;
+}
+
+type Listener = () => void;
+
+type Bytes = Uint8Array<ArrayBufferLike>;
+
+function base64ToBytes(b64: string): Bytes {
+	const binary = atob(b64);
+	const bytes = new Uint8Array(binary.length);
+	for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+	return bytes;
+}
+
+function concatBytes(a: Bytes, b: Bytes): Bytes {
+	const out = new Uint8Array(a.length + b.length);
+	out.set(a, 0);
+	out.set(b, a.length);
+	return out;
+}
+
+interface WavHeader {
+	sampleRate: number;
+	channels: number;
+	bitsPerSample: number;
+	/** Byte offset where PCM samples begin (right after the ``data`` chunk header). */
+	dataOffset: number;
+}
+
+/**
+ * Parse a minimal RIFF/WAVE header. Returns ``null`` if the buffer doesn't
+ * yet contain enough bytes to locate the ``fmt `` and ``data`` chunks.
+ */
+function parseWavHeader(bytes: Bytes): WavHeader | null {
+	if (bytes.length < 44) return null;
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	// "RIFF"...."WAVE"
+	if (view.getUint32(0, false) !== 0x52494646 || view.getUint32(8, false) !== 0x57415645) {
+		return null;
+	}
+
+	let offset = 12;
+	let sampleRate = 0;
+	let channels = 0;
+	let bitsPerSample = 0;
+	let dataOffset = -1;
+
+	while (offset + 8 <= bytes.length) {
+		const chunkId = view.getUint32(offset, false);
+		const chunkSize = view.getUint32(offset + 4, true);
+		const chunkBody = offset + 8;
+
+		if (chunkId === 0x666d7420 /* "fmt " */) {
+			if (chunkBody + 16 > bytes.length) return null;
+			channels = view.getUint16(chunkBody + 2, true);
+			sampleRate = view.getUint32(chunkBody + 4, true);
+			bitsPerSample = view.getUint16(chunkBody + 14, true);
+		} else if (chunkId === 0x64617461 /* "data" */) {
+			dataOffset = chunkBody;
+			break;
+		}
+		offset = chunkBody + chunkSize;
+	}
+
+	if (!sampleRate || !channels || !bitsPerSample || dataOffset < 0) return null;
+	return { sampleRate, channels, bitsPerSample, dataOffset };
+}
+
+/**
+ * Convert raw little-endian PCM into a Float32 AudioBuffer.
+ * Supports 16-bit and 8-bit; falls back to silence for other depths.
+ */
+function pcmToAudioBuffer(ctx: AudioContext, pcm: Bytes, header: WavHeader): AudioBuffer | null {
+	const { channels, bitsPerSample, sampleRate } = header;
+	const bytesPerSample = bitsPerSample / 8;
+	const frameSize = bytesPerSample * channels;
+	const frameCount = Math.floor(pcm.length / frameSize);
+	if (frameCount === 0) return null;
+
+	const buffer = ctx.createBuffer(channels, frameCount, sampleRate);
+	const view = new DataView(pcm.buffer, pcm.byteOffset, pcm.byteLength);
+
+	for (let ch = 0; ch < channels; ch++) {
+		const channelData = buffer.getChannelData(ch);
+		for (let i = 0; i < frameCount; i++) {
+			const sampleOffset = i * frameSize + ch * bytesPerSample;
+			if (bitsPerSample === 16) {
+				channelData[i] = view.getInt16(sampleOffset, true) / 0x8000;
+			} else if (bitsPerSample === 8) {
+				channelData[i] = (view.getUint8(sampleOffset) - 128) / 128;
+			} else {
+				channelData[i] = 0;
+			}
+		}
+	}
+	return buffer;
+}
+
+/** Live PCM playback for an in-progress WAV stream. */
+class WavStreamPlayer {
+	private ctx: AudioContext | null = null;
+	private header: WavHeader | null = null;
+	private pending: Bytes = new Uint8Array(0);
+	private nextStartTime = 0;
+	private failed = false;
+	private deferredCloseTimer: ReturnType<typeof setTimeout> | null = null;
+
+	append(chunk: Bytes): void {
+		if (this.failed) return;
+		this.pending = concatBytes(this.pending, chunk);
+
+		if (!this.header) {
+			const header = parseWavHeader(this.pending);
+			if (!header) return;
+			this.header = header;
+			try {
+				this.ctx = new AudioContext({ sampleRate: header.sampleRate });
+				if (this.ctx.state === 'suspended') {
+					void this.ctx.resume();
+				}
+				this.nextStartTime = this.ctx.currentTime;
+			} catch {
+				this.failed = true;
+				return;
+			}
+			this.pending = this.pending.slice(header.dataOffset);
+		}
+
+		if (!this.ctx || !this.header) return;
+
+		const frameSize = (this.header.bitsPerSample / 8) * this.header.channels;
+		const playableBytes = Math.floor(this.pending.length / frameSize) * frameSize;
+		if (playableBytes === 0) return;
+
+		const toPlay = this.pending.slice(0, playableBytes);
+		this.pending = this.pending.slice(playableBytes);
+
+		const audioBuffer = pcmToAudioBuffer(this.ctx, toPlay, this.header);
+		if (!audioBuffer) return;
+
+		const source = this.ctx.createBufferSource();
+		source.buffer = audioBuffer;
+		source.connect(this.ctx.destination);
+		const startAt = Math.max(this.nextStartTime, this.ctx.currentTime);
+		source.start(startAt);
+		this.nextStartTime = startAt + audioBuffer.duration;
+	}
+
+	/**
+	 * Graceful end-of-stream: stop accepting more bytes, then close the
+	 * AudioContext only after the last queued buffer has finished playing.
+	 * Without this, ``end()`` calling ``dispose()`` would cut live playback
+	 * short by closing the context while sources are still scheduled.
+	 *
+	 * The AudioContext reference is kept on ``this.ctx`` so that
+	 * ``dispose()`` can still close it immediately if a newer reply
+	 * interrupts playback before the timer fires.
+	 */
+	finalize(): void {
+		if (!this.ctx || this.failed) {
+			this.dispose();
+			return;
+		}
+		const remainingMs = Math.max(0, this.nextStartTime - this.ctx.currentTime) * 1000;
+		this.deferredCloseTimer = setTimeout(() => {
+			this.dispose();
+		}, remainingMs + 200);
+		this.header = null;
+		this.pending = new Uint8Array(0);
+	}
+
+	dispose(): void {
+		if (this.deferredCloseTimer) {
+			clearTimeout(this.deferredCloseTimer);
+			this.deferredCloseTimer = null;
+		}
+		if (this.ctx) {
+			void this.ctx.close().catch(() => undefined);
+			this.ctx = null;
+		}
+		this.pending = new Uint8Array(0);
+		this.header = null;
+	}
+}
+
+interface Session {
+	mediaType: string;
+	chunks: Bytes[];
+	totalBytes: number;
+	livePlayer: WavStreamPlayer | null;
+	/** True if a live player was created at start — survives dispose. */
+	hadLivePlayer: boolean;
+	state: StreamingAudioState;
+}
+
+/**
+ * Manages the lifecycle of streaming audio DataBlocks for one chat session.
+ * React components subscribe via {@link subscribe} to re-render when a block's
+ * state changes.
+ */
+export class StreamingAudioManager {
+	private sessions = new Map<string, Session>();
+	private listeners = new Map<string, Set<Listener>>();
+
+	private emit(blockId: string): void {
+		this.listeners.get(blockId)?.forEach((fn) => fn());
+	}
+
+	subscribe(blockId: string, fn: Listener): () => void {
+		let set = this.listeners.get(blockId);
+		if (!set) {
+			set = new Set();
+			this.listeners.set(blockId, set);
+		}
+		set.add(fn);
+		return () => {
+			set?.delete(fn);
+			if (set && set.size === 0) this.listeners.delete(blockId);
+		};
+	}
+
+	getState(blockId: string): StreamingAudioState | null {
+		return this.sessions.get(blockId)?.state ?? null;
+	}
+
+	/** Called on DATA_BLOCK_START for an audio block. */
+	start(blockId: string, mediaType: string): void {
+		if (this.sessions.has(blockId)) return;
+		const livePlayer = mediaType === 'audio/wav' ? new WavStreamPlayer() : null;
+		this.sessions.set(blockId, {
+			mediaType,
+			chunks: [],
+			totalBytes: 0,
+			livePlayer,
+			hadLivePlayer: livePlayer !== null,
+			state: { status: 'streaming', mediaType, url: null, interruptCount: 0 },
+		});
+		this.emit(blockId);
+	}
+
+	/** Called on DATA_BLOCK_DELTA. ``data`` is the base64 chunk payload. */
+	append(blockId: string, data: string): void {
+		const session = this.sessions.get(blockId);
+		if (!session || !data) return;
+		let bytes: Uint8Array;
+		try {
+			bytes = base64ToBytes(data);
+		} catch {
+			return;
+		}
+		session.chunks.push(bytes);
+		session.totalBytes += bytes.length;
+		session.livePlayer?.append(bytes);
+		// No emit — partial bytes don't change the rendered UI yet.
+	}
+
+	/**
+	 * Called on DATA_BLOCK_END. Builds the replay URL and (for non-wav)
+	 * autoplays. For wav we skip autoplay because ``WavStreamPlayer`` has
+	 * already been playing the bytes as they arrived; a second ``Audio``
+	 * playback here would either double up or — given ``end`` fires only
+	 * after the whole model stream (text included) finishes — make the
+	 * user perceive audio as starting only after text streaming completes.
+	 */
+	end(blockId: string): void {
+		const session = this.sessions.get(blockId);
+		if (!session) return;
+
+		const hadLivePlayback = session.hadLivePlayer;
+		if (session.livePlayer) {
+			// Let queued PCM finish playing; AudioContext closes via a
+			// deferred timer. The livePlayer reference is kept so that
+			// stopAllPlayback() can dispose() it immediately if a newer
+			// reply starts before the timer fires.
+			session.livePlayer.finalize();
+		}
+
+		const blob = new Blob(session.chunks as BlobPart[], { type: session.mediaType });
+		const url = URL.createObjectURL(blob);
+
+		// Free the per-chunk buffers; the Blob owns the bytes from here on.
+		session.chunks = [];
+
+		session.state = {
+			status: 'ready',
+			mediaType: session.mediaType,
+			url,
+			interruptCount: session.state.interruptCount,
+		};
+		this.emit(blockId);
+
+		if (!hadLivePlayback) {
+			// Non-wav: no live playback path, so kick off autoplay now. Some
+			// browsers gate this behind a user gesture; if blocked, the user
+			// can still hit play on the <audio controls> element.
+			const el = new Audio(url);
+			void el.play().catch(() => undefined);
+		}
+	}
+
+	/**
+	 * Stop live streaming playback only (WavStreamPlayers). Does not
+	 * touch replay ``<audio>`` elements or bump ``interruptCount``.
+	 * Called by the replay controller so that clicking play on a past
+	 * audio block silences any in-progress streaming audio without
+	 * interfering with the element that's about to start playing.
+	 */
+	stopLivePlayback(): void {
+		for (const session of this.sessions.values()) {
+			if (session.livePlayer) {
+				session.livePlayer.dispose();
+				session.livePlayer = null;
+			}
+		}
+	}
+
+	/**
+	 * Stop all in-progress and replay audio. Called when a new reply
+	 * starts so previous audio doesn't overlap with the new one.
+	 * Blob URLs are preserved so the user can still manually replay.
+	 */
+	stopAllPlayback(): void {
+		for (const [blockId, session] of this.sessions) {
+			if (session.livePlayer) {
+				session.livePlayer.dispose();
+				session.livePlayer = null;
+			}
+			session.state = {
+				...session.state,
+				interruptCount: session.state.interruptCount + 1,
+			};
+			this.emit(blockId);
+		}
+	}
+
+	/** Release a single block's resources (Object URL etc.). */
+	dispose(blockId: string): void {
+		const session = this.sessions.get(blockId);
+		if (!session) return;
+		session.livePlayer?.dispose();
+		if (session.state.url) URL.revokeObjectURL(session.state.url);
+		this.sessions.delete(blockId);
+		this.listeners.delete(blockId);
+	}
+
+	/** Release every block — call on unmount or session switch. */
+	disposeAll(): void {
+		for (const id of [...this.sessions.keys()]) this.dispose(id);
+	}
+}
diff --git a/examples/web_ui/frontend/src/vite-env.d.ts b/examples/web_ui/frontend/src/vite-env.d.ts
new file mode 100644
index 0000000..b1f45c7
--- /dev/null
+++ b/examples/web_ui/frontend/src/vite-env.d.ts
@@ -0,0 +1,2 @@
+/// <reference types="vite/client" />
+/// <reference types="vite-plugin-svgr/client" />
diff --git a/examples/web_ui/frontend/tsconfig.app.json b/examples/web_ui/frontend/tsconfig.app.json
new file mode 100644
index 0000000..05fe9fa
--- /dev/null
+++ b/examples/web_ui/frontend/tsconfig.app.json
@@ -0,0 +1,32 @@
+{
+	"compilerOptions": {
+		"tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+		"target": "es2023",
+		"lib": ["ES2023", "DOM"],
+		"module": "esnext",
+		"types": ["vite/client", "vite-plugin-svgr/client"],
+		"skipLibCheck": true,
+		"ignoreDeprecations": "6.0",
+
+		/* Bundler mode */
+		"moduleResolution": "bundler",
+		"allowImportingTsExtensions": true,
+		"verbatimModuleSyntax": true,
+		"moduleDetection": "force",
+		"noEmit": true,
+		"jsx": "react-jsx",
+
+		/* Linting */
+		"noUnusedLocals": true,
+		"noUnusedParameters": true,
+		"erasableSyntaxOnly": true,
+		"noFallthroughCasesInSwitch": true,
+
+		/* Shadcn UI */
+		"baseUrl": ".",
+		"paths": {
+			"@/*": ["./src/*"]
+		}
+	},
+	"include": ["src"]
+}
diff --git a/examples/web_ui/frontend/tsconfig.json b/examples/web_ui/frontend/tsconfig.json
new file mode 100644
index 0000000..6c4e12b
--- /dev/null
+++ b/examples/web_ui/frontend/tsconfig.json
@@ -0,0 +1,10 @@
+{
+	"files": [],
+	"references": [{ "path": "./tsconfig.app.json" }, { "path": "./tsconfig.node.json" }],
+	"compilerOptions": {
+		"baseUrl": ".",
+		"paths": {
+			"@/*": ["./src/*"]
+		}
+	}
+}
diff --git a/examples/web_ui/frontend/tsconfig.node.json b/examples/web_ui/frontend/tsconfig.node.json
new file mode 100644
index 0000000..6a12664
--- /dev/null
+++ b/examples/web_ui/frontend/tsconfig.node.json
@@ -0,0 +1,24 @@
+{
+	"compilerOptions": {
+		"tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
+		"target": "es2023",
+		"lib": ["ES2023"],
+		"module": "esnext",
+		"types": ["node"],
+		"skipLibCheck": true,
+
+		/* Bundler mode */
+		"moduleResolution": "bundler",
+		"allowImportingTsExtensions": true,
+		"verbatimModuleSyntax": true,
+		"moduleDetection": "force",
+		"noEmit": true,
+
+		/* Linting */
+		"noUnusedLocals": true,
+		"noUnusedParameters": true,
+		"erasableSyntaxOnly": true,
+		"noFallthroughCasesInSwitch": true
+	},
+	"include": ["vite.config.ts"]
+}
diff --git a/examples/web_ui/frontend/vite.config.ts b/examples/web_ui/frontend/vite.config.ts
new file mode 100644
index 0000000..1b61890
--- /dev/null
+++ b/examples/web_ui/frontend/vite.config.ts
@@ -0,0 +1,24 @@
+import path from 'path';
+
+import tailwindcss from '@tailwindcss/vite';
+import react from '@vitejs/plugin-react';
+import { defineConfig } from 'vite';
+import svgr from 'vite-plugin-svgr';
+
+export default defineConfig({
+	plugins: [react(), tailwindcss(), svgr()],
+	server: {
+		proxy: {
+			'/api': 'http://localhost:3000',
+		},
+	},
+	resolve: {
+		alias: {
+			'@': path.resolve(__dirname, './src'),
+			'next/navigation': path.resolve(__dirname, './src/lib/next-navigation-shim.ts'),
+		},
+	},
+	optimizeDeps: {
+		include: ['mime-types'],
+	},
+});
diff --git a/examples/web_ui/package.json b/examples/web_ui/package.json
new file mode 100644
index 0000000..7342841
--- /dev/null
+++ b/examples/web_ui/package.json
@@ -0,0 +1,36 @@
+{
+	"name": "agentscope-web-ui",
+	"version": "1.0.0",
+	"private": true,
+	"scripts": {
+		"dev:frontend": "pnpm --filter frontend dev",
+		"dev:backend": "pnpm --filter backend dev",
+		"dev": "concurrently \"pnpm dev:frontend\" \"pnpm dev:backend\"",
+		"build:frontend": "pnpm --filter frontend build",
+		"build:backend": "pnpm --filter backend build",
+		"build": "pnpm build:frontend && pnpm build:backend",
+		"format": "prettier --write . && pnpm --filter frontend lint:fix",
+		"format:check": "prettier --check . && pnpm --filter frontend lint",
+		"prepare": "husky"
+	},
+	"lint-staged": {
+		"frontend/**/*.{ts,tsx}": [
+			"prettier --write",
+			"cd frontend && pnpm eslint --fix"
+		],
+		"backend/**/*.{ts,js}": [
+			"prettier --write"
+		],
+		"*.{json,css,md,html,yaml,yml}": [
+			"prettier --write"
+		]
+	},
+	"devDependencies": {
+		"concurrently": "^8.2.2",
+		"eslint-config-prettier": "^10.1.8",
+		"eslint-plugin-prettier": "^5.5.5",
+		"husky": "^9.1.7",
+		"lint-staged": "^17.0.5",
+		"prettier": "^3.8.3"
+	}
+}
diff --git a/examples/web_ui/pnpm-lock.yaml b/examples/web_ui/pnpm-lock.yaml
new file mode 100644
index 0000000..ceffa97
--- /dev/null
+++ b/examples/web_ui/pnpm-lock.yaml
@@ -0,0 +1,9340 @@
+lockfileVersion: '9.0'
+
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false
+
+importers:
+
+  .:
+    devDependencies:
+      concurrently:
+        specifier: ^8.2.2
+        version: 8.2.2
+      eslint-config-prettier:
+        specifier: ^10.1.8
+        version: 10.1.8(eslint@10.3.0(jiti@2.7.0))
+      eslint-plugin-prettier:
+        specifier: ^5.5.5
+        version: 5.5.5(eslint-config-prettier@10.1.8(eslint@10.3.0(jiti@2.7.0)))(eslint@10.3.0(jiti@2.7.0))(prettier@3.8.3)
+      husky:
+        specifier: ^9.1.7
+        version: 9.1.7
+      lint-staged:
+        specifier: ^17.0.5
+        version: 17.0.5
+      prettier:
+        specifier: ^3.8.3
+        version: 3.8.3
+
+  backend:
+    dependencies:
+      cors:
+        specifier: ^2.8.5
+        version: 2.8.6
+      express:
+        specifier: ^4.19.2
+        version: 4.22.2
+    devDependencies:
+      '@types/cors':
+        specifier: ^2.8.17
+        version: 2.8.19
+      '@types/express':
+        specifier: ^4.17.21
+        version: 4.17.25
+      '@types/node':
+        specifier: ^20.14.0
+        version: 20.19.41
+      nodemon:
+        specifier: ^3.1.4
+        version: 3.1.14
+      ts-node:
+        specifier: ^10.9.2
+        version: 10.9.2(@types/node@20.19.41)(typescript@5.9.3)
+      typescript:
+        specifier: ^5.5.2
+        version: 5.9.3
+
+  frontend:
+    dependencies:
+      '@agentscope-ai/agentscope':
+        specifier: ^0.0.13
+        version: 0.0.13
+      '@fontsource-variable/geist':
+        specifier: ^5.2.8
+        version: 5.2.8
+      '@tailwindcss/vite':
+        specifier: ^4.3.0
+        version: 4.3.0(vite@8.0.13(@types/node@24.12.4)(jiti@2.7.0)(yaml@2.9.0))
+      class-variance-authority:
+        specifier: ^0.7.1
+        version: 0.7.1
+      clsx:
+        specifier: ^2.1.1
+        version: 2.1.1
+      cron-parser:
+        specifier: ^5.5.0
+        version: 5.5.0
+      date-fns:
+        specifier: ^4.1.0
+        version: 4.1.0
+      framer-motion:
+        specifier: ^12.40.0
+        version: 12.40.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      i18next:
+        specifier: ^26.2.0
+        version: 26.2.0(typescript@6.0.3)
+      i18next-browser-languagedetector:
+        specifier: ^8.2.1
+        version: 8.2.1
+      lucide:
+        specifier: ^1.3.0
+        version: 1.3.0
+      lucide-react:
+        specifier: ^1.16.0
+        version: 1.16.0(react@19.2.6)
+      mime-types:
+        specifier: ^3.0.2
+        version: 3.0.2
+      next-themes:
+        specifier: ^0.4.6
+        version: 0.4.6(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      onborda:
+        specifier: ^1.2.5
+        version: 1.2.5(@radix-ui/react-portal@1.1.9(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(framer-motion@12.40.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(next@16.2.6(@babel/core@7.29.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      radix-ui:
+        specifier: ^1.4.3
+        version: 1.4.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react:
+        specifier: ^19.2.6
+        version: 19.2.6
+      react-day-picker:
+        specifier: ^10.0.1
+        version: 10.0.1(@types/react@19.2.14)(react@19.2.6)
+      react-diff-view:
+        specifier: ^3.3.3
+        version: 3.3.3(react@19.2.6)
+      react-dom:
+        specifier: ^19.2.6
+        version: 19.2.6(react@19.2.6)
+      react-i18next:
+        specifier: ^17.0.8
+        version: 17.0.8(i18next@26.2.0(typescript@6.0.3))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(typescript@6.0.3)
+      react-markdown:
+        specifier: ^10.1.0
+        version: 10.1.0(@types/react@19.2.14)(react@19.2.6)
+      react-resizable-panels:
+        specifier: ^4.11.2
+        version: 4.11.2(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react-router-dom:
+        specifier: ^7.15.1
+        version: 7.15.1(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      remark-gfm:
+        specifier: ^4.0.1
+        version: 4.0.1
+      shadcn:
+        specifier: ^4.7.0
+        version: 4.7.0(@cfworker/json-schema@4.1.1)(@types/node@24.12.4)(typescript@6.0.3)
+      shadcn-prose:
+        specifier: ^1.2.1
+        version: 1.2.1
+      sonner:
+        specifier: ^2.0.7
+        version: 2.0.7(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      tailwind-merge:
+        specifier: ^3.6.0
+        version: 3.6.0
+      tailwindcss:
+        specifier: ^4.3.0
+        version: 4.3.0
+      tw-animate-css:
+        specifier: ^1.4.0
+        version: 1.4.0
+      unidiff:
+        specifier: ^1.0.4
+        version: 1.0.4
+      vaul:
+        specifier: ^1.1.2
+        version: 1.1.2(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+    devDependencies:
+      '@eslint/js':
+        specifier: ^10.0.1
+        version: 10.0.1(eslint@10.3.0(jiti@2.7.0))
+      '@tailwindcss/typography':
+        specifier: ^0.5.19
+        version: 0.5.19(tailwindcss@4.3.0)
+      '@types/mime-types':
+        specifier: ^3.0.1
+        version: 3.0.1
+      '@types/node':
+        specifier: ^24.12.3
+        version: 24.12.4
+      '@types/react':
+        specifier: ^19.2.14
+        version: 19.2.14
+      '@types/react-dom':
+        specifier: ^19.2.3
+        version: 19.2.3(@types/react@19.2.14)
+      '@vitejs/plugin-react':
+        specifier: ^6.0.1
+        version: 6.0.1(vite@8.0.13(@types/node@24.12.4)(jiti@2.7.0)(yaml@2.9.0))
+      eslint:
+        specifier: ^10.3.0
+        version: 10.3.0(jiti@2.7.0)
+      eslint-plugin-import-x:
+        specifier: ^4.16.2
+        version: 4.16.2(@typescript-eslint/utils@8.59.3(eslint@10.3.0(jiti@2.7.0))(typescript@6.0.3))(eslint@10.3.0(jiti@2.7.0))
+      eslint-plugin-react-hooks:
+        specifier: ^7.1.1
+        version: 7.1.1(eslint@10.3.0(jiti@2.7.0))
+      eslint-plugin-react-refresh:
+        specifier: ^0.5.2
+        version: 0.5.2(eslint@10.3.0(jiti@2.7.0))
+      globals:
+        specifier: ^17.6.0
+        version: 17.6.0
+      typescript:
+        specifier: ~6.0.2
+        version: 6.0.3
+      typescript-eslint:
+        specifier: ^8.59.2
+        version: 8.59.3(eslint@10.3.0(jiti@2.7.0))(typescript@6.0.3)
+      vite:
+        specifier: ^8.0.12
+        version: 8.0.13(@types/node@24.12.4)(jiti@2.7.0)(yaml@2.9.0)
+      vite-plugin-svgr:
+        specifier: ^5.2.0
+        version: 5.2.0(typescript@6.0.3)(vite@8.0.13(@types/node@24.12.4)(jiti@2.7.0)(yaml@2.9.0))
+
+packages:
+
+  '@agentscope-ai/agentscope@0.0.13':
+    resolution: {integrity: sha512-SUNKypyVR8ANu6mSiQ0cPaD2GuFzTJmTxj0FqFjjGR+gIy0J44L+46dOxbwfOoZS/2Cl60gMqV33A/K+XPcJVw==}
+
+  '@babel/code-frame@7.29.0':
+    resolution: {integrity: sha512-9NhCeYjq9+3uxgdtp20LSiJXJvN0FeCtNGpJxuMFZ1Kv3cWUNb6DOhJwUvcVCzKGR66cw4njwM6hrJLqgOwbcw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/compat-data@7.29.3':
+    resolution: {integrity: sha512-LIVqM46zQWZhj17qA8wb4nW/ixr2y1Nw+r1etiAWgRM6U1IqP+LNhL1yg440jYZR72jCWcWbLWzIosH+uP1fqg==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/core@7.29.0':
+    resolution: {integrity: sha512-CGOfOJqWjg2qW/Mb6zNsDm+u5vFQ8DxXfbM09z69p5Z6+mE1ikP2jUXw+j42Pf1XTYED2Rni5f95npYeuwMDQA==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/generator@7.29.1':
+    resolution: {integrity: sha512-qsaF+9Qcm2Qv8SRIMMscAvG4O3lJ0F1GuMo5HR/Bp02LopNgnZBC/EkbevHFeGs4ls/oPz9v+Bsmzbkbe+0dUw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-annotate-as-pure@7.27.3':
+    resolution: {integrity: sha512-fXSwMQqitTGeHLBC08Eq5yXz2m37E4pJX1qAU1+2cNedz/ifv/bVXft90VeSav5nFO61EcNgwr0aJxbyPaWBPg==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-compilation-targets@7.28.6':
+    resolution: {integrity: sha512-JYtls3hqi15fcx5GaSNL7SCTJ2MNmjrkHXg4FSpOA/grxK8KwyZ5bubHsCq8FXCkua6xhuaaBit+3b7+VZRfcA==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-create-class-features-plugin@7.29.3':
+    resolution: {integrity: sha512-RpLYy2sb51oNLjuu1iD3bwBqCBWUzjO0ocp+iaCP/lJtb2CPLcnC2Fftw+4sAzaMELGeWTgExSKADbdo0GFVzA==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0
+
+  '@babel/helper-globals@7.28.0':
+    resolution: {integrity: sha512-+W6cISkXFa1jXsDEdYA8HeevQT/FULhxzR99pxphltZcVaugps53THCeiWA8SguxxpSp3gKPiuYfSWopkLQ4hw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-member-expression-to-functions@7.28.5':
+    resolution: {integrity: sha512-cwM7SBRZcPCLgl8a7cY0soT1SptSzAlMH39vwiRpOQkJlh53r5hdHwLSCZpQdVLT39sZt+CRpNwYG4Y2v77atg==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-module-imports@7.28.6':
+    resolution: {integrity: sha512-l5XkZK7r7wa9LucGw9LwZyyCUscb4x37JWTPz7swwFE/0FMQAGpiWUZn8u9DzkSBWEcK25jmvubfpw2dnAMdbw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-module-transforms@7.28.6':
+    resolution: {integrity: sha512-67oXFAYr2cDLDVGLXTEABjdBJZ6drElUSI7WKp70NrpyISso3plG9SAGEF6y7zbha/wOzUByWWTJvEDVNIUGcA==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0
+
+  '@babel/helper-optimise-call-expression@7.27.1':
+    resolution: {integrity: sha512-URMGH08NzYFhubNSGJrpUEphGKQwMQYBySzat5cAByY1/YgIRkULnIy3tAMeszlL/so2HbeilYloUmSpd7GdVw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-plugin-utils@7.28.6':
+    resolution: {integrity: sha512-S9gzZ/bz83GRysI7gAD4wPT/AI3uCnY+9xn+Mx/KPs2JwHJIz1W8PZkg2cqyt3RNOBM8ejcXhV6y8Og7ly/Dug==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-replace-supers@7.28.6':
+    resolution: {integrity: sha512-mq8e+laIk94/yFec3DxSjCRD2Z0TAjhVbEJY3UQrlwVo15Lmt7C2wAUbK4bjnTs4APkwsYLTahXRraQXhb1WCg==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0
+
+  '@babel/helper-skip-transparent-expression-wrappers@7.27.1':
+    resolution: {integrity: sha512-Tub4ZKEXqbPjXgWLl2+3JpQAYBJ8+ikpQ2Ocj/q/r0LwE3UhENh7EUabyHjz2kCEsrRY83ew2DQdHluuiDQFzg==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-string-parser@7.27.1':
+    resolution: {integrity: sha512-qMlSxKbpRlAridDExk92nSobyDdpPijUq2DW6oDnUqd0iOGxmQjyqhMIihI9+zv4LPyZdRje2cavWPbCbWm3eA==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-validator-identifier@7.28.5':
+    resolution: {integrity: sha512-qSs4ifwzKJSV39ucNjsvc6WVHs6b7S03sOh2OcHF9UHfVPqWWALUsNUVzhSBiItjRZoLHx7nIarVjqKVusUZ1Q==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-validator-option@7.27.1':
+    resolution: {integrity: sha512-YvjJow9FxbhFFKDSuFnVCe2WxXk1zWc22fFePVNEaWJEu8IrZVlda6N0uHwzZrUM1il7NC9Mlp4MaJYbYd9JSg==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helpers@7.29.2':
+    resolution: {integrity: sha512-HoGuUs4sCZNezVEKdVcwqmZN8GoHirLUcLaYVNBK2J0DadGtdcqgr3BCbvH8+XUo4NGjNl3VOtSjEKNzqfFgKw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/parser@7.29.3':
+    resolution: {integrity: sha512-b3ctpQwp+PROvU/cttc4OYl4MzfJUWy6FZg+PMXfzmt/+39iHVF0sDfqay8TQM3JA2EUOyKcFZt75jWriQijsA==}
+    engines: {node: '>=6.0.0'}
+    hasBin: true
+
+  '@babel/plugin-syntax-jsx@7.28.6':
+    resolution: {integrity: sha512-wgEmr06G6sIpqr8YDwA2dSRTE3bJ+V0IfpzfSY3Lfgd7YWOaAdlykvJi13ZKBt8cZHfgH1IXN+CL656W3uUa4w==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0-0
+
+  '@babel/plugin-syntax-typescript@7.28.6':
+    resolution: {integrity: sha512-+nDNmQye7nlnuuHDboPbGm00Vqg3oO8niRRL27/4LYHUsHYh0zJ1xWOz0uRwNFmM1Avzk8wZbc6rdiYhomzv/A==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0-0
+
+  '@babel/plugin-transform-modules-commonjs@7.28.6':
+    resolution: {integrity: sha512-jppVbf8IV9iWWwWTQIxJMAJCWBuuKx71475wHwYytrRGQ2CWiDvYlADQno3tcYpS/T2UUWFQp3nVtYfK/YBQrA==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0-0
+
+  '@babel/plugin-transform-typescript@7.28.6':
+    resolution: {integrity: sha512-0YWL2RFxOqEm9Efk5PvreamxPME8OyY0wM5wh5lHjF+VtVhdneCWGzZeSqzOfiobVqQaNCd2z0tQvnI9DaPWPw==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0-0
+
+  '@babel/preset-typescript@7.28.5':
+    resolution: {integrity: sha512-+bQy5WOI2V6LJZpPVxY+yp66XdZ2yifu0Mc1aP5CQKgjn4QM5IN2i5fAZ4xKop47pr8rpVhiAeu+nDQa12C8+g==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0-0
+
+  '@babel/runtime@7.29.2':
+    resolution: {integrity: sha512-JiDShH45zKHWyGe4ZNVRrCjBz8Nh9TMmZG1kh4QTK8hCBTWBi8Da+i7s1fJw7/lYpM4ccepSNfqzZ/QvABBi5g==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/template@7.28.6':
+    resolution: {integrity: sha512-YA6Ma2KsCdGb+WC6UpBVFJGXL58MDA6oyONbjyF/+5sBgxY/dwkhLogbMT2GXXyU84/IhRw/2D1Os1B/giz+BQ==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/traverse@7.29.0':
+    resolution: {integrity: sha512-4HPiQr0X7+waHfyXPZpWPfWL/J7dcN1mx9gL6WdQVMbPnF3+ZhSMs8tCxN7oHddJE9fhNE7+lxdnlyemKfJRuA==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/types@7.29.0':
+    resolution: {integrity: sha512-LwdZHpScM4Qz8Xw2iKSzS+cfglZzJGvofQICy7W7v4caru4EaAmyUuO6BGrbyQ2mYV11W0U8j5mBhd14dd3B0A==}
+    engines: {node: '>=6.9.0'}
+
+  '@cfworker/json-schema@4.1.1':
+    resolution: {integrity: sha512-gAmrUZSGtKc3AiBL71iNWxDsyUC5uMaKKGdvzYsBoTW/xi42JQHl7eKV2OYzCUqvc+D2RCcf7EXY2iCyFIk6og==}
+
+  '@cspotcode/source-map-support@0.8.1':
+    resolution: {integrity: sha512-IchNf6dN4tHoMFIn/7OE8LWZ19Y6q/67Bmf6vnGREv8RSbBVb9LPJxEcnwrcwX6ixSvaiGoomAUvu4YSxXrVgw==}
+    engines: {node: '>=12'}
+
+  '@date-fns/tz@1.4.1':
+    resolution: {integrity: sha512-P5LUNhtbj6YfI3iJjw5EL9eUAG6OitD0W3fWQcpQjDRc/QIsL0tRNuO1PcDvPccWL1fSTXXdE1ds+l95DV/OFA==}
+
+  '@dotenvx/dotenvx@1.66.0':
+    resolution: {integrity: sha512-qlQFhHUjhRDybrinqLAD0MClVZDOrsq80O8eD5iSjz3Qa/4f3Jg7SQrOaSobrRyP1QaWIYLGtGpj2c7H0D8NUw==}
+    hasBin: true
+
+  '@ecies/ciphers@0.2.6':
+    resolution: {integrity: sha512-patgsRPKGkhhoBjETV4XxD0En4ui5fbX0hzayqI3M8tvNMGUoUvmyYAIWwlxBc1KX5cturfqByYdj5bYGRpN9g==}
+    engines: {bun: '>=1', deno: '>=2.7.10', node: '>=16'}
+    peerDependencies:
+      '@noble/ciphers': ^1.0.0
+
+  '@emnapi/core@1.10.0':
+    resolution: {integrity: sha512-yq6OkJ4p82CAfPl0u9mQebQHKPJkY7WrIuk205cTYnYe+k2Z8YBh11FrbRG/H6ihirqcacOgl2BIO8oyMQLeXw==}
+
+  '@emnapi/runtime@1.10.0':
+    resolution: {integrity: sha512-ewvYlk86xUoGI0zQRNq/mC+16R1QeDlKQy21Ki3oSYXNgLb45GV1P6A0M+/s6nyCuNDqe5VpaY84BzXGwVbwFA==}
+
+  '@emnapi/wasi-threads@1.2.1':
+    resolution: {integrity: sha512-uTII7OYF+/Mes/MrcIOYp5yOtSMLBWSIoLPpcgwipoiKbli6k322tcoFsxoIIxPDqW01SQGAgko4EzZi2BNv2w==}
+
+  '@eslint-community/eslint-utils@4.9.1':
+    resolution: {integrity: sha512-phrYmNiYppR7znFEdqgfWHXR6NCkZEK7hwWDHZUjit/2/U0r6XvkDl0SYnoM51Hq7FhCGdLDT6zxCCOY1hexsQ==}
+    engines: {node: ^12.22.0 || ^14.17.0 || >=16.0.0}
+    peerDependencies:
+      eslint: ^6.0.0 || ^7.0.0 || >=8.0.0
+
+  '@eslint-community/regexpp@4.12.2':
+    resolution: {integrity: sha512-EriSTlt5OC9/7SXkRSCAhfSxxoSUgBm33OH+IkwbdpgoqsSsUg7y3uh+IICI/Qg4BBWr3U2i39RpmycbxMq4ew==}
+    engines: {node: ^12.0.0 || ^14.0.0 || >=16.0.0}
+
+  '@eslint/config-array@0.23.5':
+    resolution: {integrity: sha512-Y3kKLvC1dvTOT+oGlqNQ1XLqK6D1HU2YXPc52NmAlJZbMMWDzGYXMiPRJ8TYD39muD/OTjlZmNJ4ib7dvSrMBA==}
+    engines: {node: ^20.19.0 || ^22.13.0 || >=24}
+
+  '@eslint/config-helpers@0.5.5':
+    resolution: {integrity: sha512-eIJYKTCECbP/nsKaaruF6LW967mtbQbsw4JTtSVkUQc9MneSkbrgPJAbKl9nWr0ZeowV8BfsarBmPpBzGelA2w==}
+    engines: {node: ^20.19.0 || ^22.13.0 || >=24}
+
+  '@eslint/core@1.2.1':
+    resolution: {integrity: sha512-MwcE1P+AZ4C6DWlpin/OmOA54mmIZ/+xZuJiQd4SyB29oAJjN30UW9wkKNptW2ctp4cEsvhlLY/CsQ1uoHDloQ==}
+    engines: {node: ^20.19.0 || ^22.13.0 || >=24}
+
+  '@eslint/js@10.0.1':
+    resolution: {integrity: sha512-zeR9k5pd4gxjZ0abRoIaxdc7I3nDktoXZk2qOv9gCNWx3mVwEn32VRhyLaRsDiJjTs0xq/T8mfPtyuXu7GWBcA==}
+    engines: {node: ^20.19.0 || ^22.13.0 || >=24}
+    peerDependencies:
+      eslint: ^10.0.0
+    peerDependenciesMeta:
+      eslint:
+        optional: true
+
+  '@eslint/object-schema@3.0.5':
+    resolution: {integrity: sha512-vqTaUEgxzm+YDSdElad6PiRoX4t8VGDjCtt05zn4nU810UIx/uNEV7/lZJ6KwFThKZOzOxzXy48da+No7HZaMw==}
+    engines: {node: ^20.19.0 || ^22.13.0 || >=24}
+
+  '@eslint/plugin-kit@0.7.1':
+    resolution: {integrity: sha512-rZAP3aVgB9ds9KOeUSL+zZ21hPmo8dh6fnIFwRQj5EAZl9gzR7wxYbYXYysAM8CTqGmUGyp2S4kUdV17MnGuWQ==}
+    engines: {node: ^20.19.0 || ^22.13.0 || >=24}
+
+  '@floating-ui/core@1.7.5':
+    resolution: {integrity: sha512-1Ih4WTWyw0+lKyFMcBHGbb5U5FtuHJuujoyyr5zTaWS5EYMeT6Jb2AuDeftsCsEuchO+mM2ij5+q9crhydzLhQ==}
+
+  '@floating-ui/dom@1.7.6':
+    resolution: {integrity: sha512-9gZSAI5XM36880PPMm//9dfiEngYoC6Am2izES1FF406YFsjvyBMmeJ2g4SAju3xWwtuynNRFL2s9hgxpLI5SQ==}
+
+  '@floating-ui/react-dom@2.1.8':
+    resolution: {integrity: sha512-cC52bHwM/n/CxS87FH0yWdngEZrjdtLW/qVruo68qg+prK7ZQ4YGdut2GyDVpoGeAYe/h899rVeOVm6Oi40k2A==}
+    peerDependencies:
+      react: '>=16.8.0'
+      react-dom: '>=16.8.0'
+
+  '@floating-ui/utils@0.2.11':
+    resolution: {integrity: sha512-RiB/yIh78pcIxl6lLMG0CgBXAZ2Y0eVHqMPYugu+9U0AeT6YBeiJpf7lbdJNIugFP5SIjwNRgo4DhR1Qxi26Gg==}
+
+  '@fontsource-variable/geist@5.2.8':
+    resolution: {integrity: sha512-cJ6m9e+8MQ5dCYJsLylfZrgBh6KkG4bOLckB35Tr9J/EqdkEM6QllH5PxqP1dhTvFup+HtMRPuz9xOjxXJggxw==}
+
+  '@hono/node-server@1.19.14':
+    resolution: {integrity: sha512-GwtvgtXxnWsucXvbQXkRgqksiH2Qed37H9xHZocE5sA3N8O8O8/8FA3uclQXxXVzc9XBZuEOMK7+r02FmSpHtw==}
+    engines: {node: '>=18.14.1'}
+    peerDependencies:
+      hono: ^4
+
+  '@humanfs/core@0.19.2':
+    resolution: {integrity: sha512-UhXNm+CFMWcbChXywFwkmhqjs3PRCmcSa/hfBgLIb7oQ5HNb1wS0icWsGtSAUNgefHeI+eBrA8I1fxmbHsGdvA==}
+    engines: {node: '>=18.18.0'}
+
+  '@humanfs/node@0.16.8':
+    resolution: {integrity: sha512-gE1eQNZ3R++kTzFUpdGlpmy8kDZD/MLyHqDwqjkVQI0JMdI1D51sy1H958PNXYkM2rAac7e5/CnIKZrHtPh3BQ==}
+    engines: {node: '>=18.18.0'}
+
+  '@humanfs/types@0.15.0':
+    resolution: {integrity: sha512-ZZ1w0aoQkwuUuC7Yf+7sdeaNfqQiiLcSRbfI08oAxqLtpXQr9AIVX7Ay7HLDuiLYAaFPu8oBYNq/QIi9URHJ3Q==}
+    engines: {node: '>=18.18.0'}
+
+  '@humanwhocodes/module-importer@1.0.1':
+    resolution: {integrity: sha512-bxveV4V8v5Yb4ncFTT3rPSgZBOpCkjfK0y4oVVVJwIuDVBRMDXrPyXRL988i5ap9m9bnyEEjWfm5WkBmtffLfA==}
+    engines: {node: '>=12.22'}
+
+  '@humanwhocodes/retry@0.4.3':
+    resolution: {integrity: sha512-bV0Tgo9K4hfPCek+aMAn81RppFKv2ySDQeMoSZuvTASywNTnVJCArCZE2FWqpvIatKu7VMRLWlR1EazvVhDyhQ==}
+    engines: {node: '>=18.18'}
+
+  '@img/colour@1.1.0':
+    resolution: {integrity: sha512-Td76q7j57o/tLVdgS746cYARfSyxk8iEfRxewL9h4OMzYhbW4TAcppl0mT4eyqXddh6L/jwoM75mo7ixa/pCeQ==}
+    engines: {node: '>=18'}
+
+  '@img/sharp-darwin-arm64@0.34.5':
+    resolution: {integrity: sha512-imtQ3WMJXbMY4fxb/Ndp6HBTNVtWCUI0WdobyheGf5+ad6xX8VIDO8u2xE4qc/fr08CKG/7dDseFtn6M6g/r3w==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@img/sharp-darwin-x64@0.34.5':
+    resolution: {integrity: sha512-YNEFAF/4KQ/PeW0N+r+aVVsoIY0/qxxikF2SWdp+NRkmMB7y9LBZAVqQ4yhGCm/H3H270OSykqmQMKLBhBJDEw==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [x64]
+    os: [darwin]
+
+  '@img/sharp-libvips-darwin-arm64@1.2.4':
+    resolution: {integrity: sha512-zqjjo7RatFfFoP0MkQ51jfuFZBnVE2pRiaydKJ1G/rHZvnsrHAOcQALIi9sA5co5xenQdTugCvtb1cuf78Vf4g==}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@img/sharp-libvips-darwin-x64@1.2.4':
+    resolution: {integrity: sha512-1IOd5xfVhlGwX+zXv2N93k0yMONvUlANylbJw1eTah8K/Jtpi15KC+WSiaX/nBmbm2HxRM1gZ0nSdjSsrZbGKg==}
+    cpu: [x64]
+    os: [darwin]
+
+  '@img/sharp-libvips-linux-arm64@1.2.4':
+    resolution: {integrity: sha512-excjX8DfsIcJ10x1Kzr4RcWe1edC9PquDRRPx3YVCvQv+U5p7Yin2s32ftzikXojb1PIFc/9Mt28/y+iRklkrw==}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-libvips-linux-arm@1.2.4':
+    resolution: {integrity: sha512-bFI7xcKFELdiNCVov8e44Ia4u2byA+l3XtsAj+Q8tfCwO6BQ8iDojYdvoPMqsKDkuoOo+X6HZA0s0q11ANMQ8A==}
+    cpu: [arm]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-libvips-linux-ppc64@1.2.4':
+    resolution: {integrity: sha512-FMuvGijLDYG6lW+b/UvyilUWu5Ayu+3r2d1S8notiGCIyYU/76eig1UfMmkZ7vwgOrzKzlQbFSuQfgm7GYUPpA==}
+    cpu: [ppc64]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-libvips-linux-riscv64@1.2.4':
+    resolution: {integrity: sha512-oVDbcR4zUC0ce82teubSm+x6ETixtKZBh/qbREIOcI3cULzDyb18Sr/Wcyx7NRQeQzOiHTNbZFF1UwPS2scyGA==}
+    cpu: [riscv64]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-libvips-linux-s390x@1.2.4':
+    resolution: {integrity: sha512-qmp9VrzgPgMoGZyPvrQHqk02uyjA0/QrTO26Tqk6l4ZV0MPWIW6LTkqOIov+J1yEu7MbFQaDpwdwJKhbJvuRxQ==}
+    cpu: [s390x]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-libvips-linux-x64@1.2.4':
+    resolution: {integrity: sha512-tJxiiLsmHc9Ax1bz3oaOYBURTXGIRDODBqhveVHonrHJ9/+k89qbLl0bcJns+e4t4rvaNBxaEZsFtSfAdquPrw==}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-libvips-linuxmusl-arm64@1.2.4':
+    resolution: {integrity: sha512-FVQHuwx1IIuNow9QAbYUzJ+En8KcVm9Lk5+uGUQJHaZmMECZmOlix9HnH7n1TRkXMS0pGxIJokIVB9SuqZGGXw==}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  '@img/sharp-libvips-linuxmusl-x64@1.2.4':
+    resolution: {integrity: sha512-+LpyBk7L44ZIXwz/VYfglaX/okxezESc6UxDSoyo2Ks6Jxc4Y7sGjpgU9s4PMgqgjj1gZCylTieNamqA1MF7Dg==}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  '@img/sharp-linux-arm64@0.34.5':
+    resolution: {integrity: sha512-bKQzaJRY/bkPOXyKx5EVup7qkaojECG6NLYswgktOZjaXecSAeCWiZwwiFf3/Y+O1HrauiE3FVsGxFg8c24rZg==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-linux-arm@0.34.5':
+    resolution: {integrity: sha512-9dLqsvwtg1uuXBGZKsxem9595+ujv0sJ6Vi8wcTANSFpwV/GONat5eCkzQo/1O6zRIkh0m/8+5BjrRr7jDUSZw==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [arm]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-linux-ppc64@0.34.5':
+    resolution: {integrity: sha512-7zznwNaqW6YtsfrGGDA6BRkISKAAE1Jo0QdpNYXNMHu2+0dTrPflTLNkpc8l7MUP5M16ZJcUvysVWWrMefZquA==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [ppc64]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-linux-riscv64@0.34.5':
+    resolution: {integrity: sha512-51gJuLPTKa7piYPaVs8GmByo7/U7/7TZOq+cnXJIHZKavIRHAP77e3N2HEl3dgiqdD/w0yUfiJnII77PuDDFdw==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [riscv64]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-linux-s390x@0.34.5':
+    resolution: {integrity: sha512-nQtCk0PdKfho3eC5MrbQoigJ2gd1CgddUMkabUj+rBevs8tZ2cULOx46E7oyX+04WGfABgIwmMC0VqieTiR4jg==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [s390x]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-linux-x64@0.34.5':
+    resolution: {integrity: sha512-MEzd8HPKxVxVenwAa+JRPwEC7QFjoPWuS5NZnBt6B3pu7EG2Ge0id1oLHZpPJdn3OQK+BQDiw9zStiHBTJQQQQ==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-linuxmusl-arm64@0.34.5':
+    resolution: {integrity: sha512-fprJR6GtRsMt6Kyfq44IsChVZeGN97gTD331weR1ex1c1rypDEABN6Tm2xa1wE6lYb5DdEnk03NZPqA7Id21yg==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  '@img/sharp-linuxmusl-x64@0.34.5':
+    resolution: {integrity: sha512-Jg8wNT1MUzIvhBFxViqrEhWDGzqymo3sV7z7ZsaWbZNDLXRJZoRGrjulp60YYtV4wfY8VIKcWidjojlLcWrd8Q==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  '@img/sharp-wasm32@0.34.5':
+    resolution: {integrity: sha512-OdWTEiVkY2PHwqkbBI8frFxQQFekHaSSkUIJkwzclWZe64O1X4UlUjqqqLaPbUpMOQk6FBu/HtlGXNblIs0huw==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [wasm32]
+
+  '@img/sharp-win32-arm64@0.34.5':
+    resolution: {integrity: sha512-WQ3AgWCWYSb2yt+IG8mnC6Jdk9Whs7O0gxphblsLvdhSpSTtmu69ZG1Gkb6NuvxsNACwiPV6cNSZNzt0KPsw7g==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [arm64]
+    os: [win32]
+
+  '@img/sharp-win32-ia32@0.34.5':
+    resolution: {integrity: sha512-FV9m/7NmeCmSHDD5j4+4pNI8Cp3aW+JvLoXcTUo0IqyjSfAZJ8dIUmijx1qaJsIiU+Hosw6xM5KijAWRJCSgNg==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [ia32]
+    os: [win32]
+
+  '@img/sharp-win32-x64@0.34.5':
+    resolution: {integrity: sha512-+29YMsqY2/9eFEiW93eqWnuLcWcufowXewwSNIT6UwZdUUCrM3oFjMWH/Z6/TMmb4hlFenmfAVbpWeup2jryCw==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [x64]
+    os: [win32]
+
+  '@inquirer/ansi@2.0.5':
+    resolution: {integrity: sha512-doc2sWgJpbFQ64UflSVd17ibMGDuxO1yKgOgLMwavzESnXjFWJqUeG8saYosqKpHp4kWiM5x1nXvEjbpx90gzw==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'}
+
+  '@inquirer/confirm@6.0.13':
+    resolution: {integrity: sha512-wkGPC7yJ5WJk1DJ5SX7fzk+gfj4BM8cf5dDDi71B/551xHrdsZVRJOC0WyikXd0pEsb/9cLniuE4atbsMqmFkw==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@inquirer/core@11.1.10':
+    resolution: {integrity: sha512-a4Q5BXHQAHa9eO202sTaFCHFYVB3x5fauDuThEAdZ9gfn76pSxiKU7wWcEH0N1O0XmQvNfQNU6QXpiRxmYQx+A==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@inquirer/figures@2.0.5':
+    resolution: {integrity: sha512-NsSs4kzfm12lNetHwAn3GEuH317IzpwrMCbOuMIVytpjnJ90YYHNwdRgYGuKmVxwuIqSgqk3M5qqQt1cDk0tGQ==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'}
+
+  '@inquirer/type@4.0.5':
+    resolution: {integrity: sha512-aetVUNeKNc/VriqXlw1NRSW0zhMBB0W4bNbWRJgzRl/3d0QNDQFfk0GO5SDdtjMZVg6o8ZKEiadd7SCCzoOn5Q==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@jridgewell/gen-mapping@0.3.13':
+    resolution: {integrity: sha512-2kkt/7niJ6MgEPxF0bYdQ6etZaA+fQvDcLKckhy1yIQOzaoKjBBjSj63/aLVjYE3qhRt5dvM+uUyfCg6UKCBbA==}
+
+  '@jridgewell/remapping@2.3.5':
+    resolution: {integrity: sha512-LI9u/+laYG4Ds1TDKSJW2YPrIlcVYOwi2fUC6xB43lueCjgxV4lffOCZCtYFiH6TNOX+tQKXx97T4IKHbhyHEQ==}
+
+  '@jridgewell/resolve-uri@3.1.2':
+    resolution: {integrity: sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==}
+    engines: {node: '>=6.0.0'}
+
+  '@jridgewell/sourcemap-codec@1.5.5':
+    resolution: {integrity: sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og==}
+
+  '@jridgewell/trace-mapping@0.3.31':
+    resolution: {integrity: sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==}
+
+  '@jridgewell/trace-mapping@0.3.9':
+    resolution: {integrity: sha512-3Belt6tdc8bPgAtbcmdtNJlirVoTmEb5e2gC94PnkwEW9jI6CAHUeoG85tjWP5WquqfavoMtMwiG4P926ZKKuQ==}
+
+  '@modelcontextprotocol/sdk@1.29.0':
+    resolution: {integrity: sha512-zo37mZA9hJWpULgkRpowewez1y6ML5GsXJPY8FI0tBBCd77HEvza4jDqRKOXgHNn867PVGCyTdzqpz0izu5ZjQ==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      '@cfworker/json-schema': ^4.1.1
+      zod: ^3.25 || ^4.0
+    peerDependenciesMeta:
+      '@cfworker/json-schema':
+        optional: true
+
+  '@mswjs/interceptors@0.41.9':
+    resolution: {integrity: sha512-VVPPgHyQ6ShqnrmDWuxjmUIsO9gWyOZFmuOfLd9LfBGQJwZfy0gvv9pbHSJuoFNIYC7ZDX9aoFwowjcdSC4E8w==}
+    engines: {node: '>=18'}
+
+  '@napi-rs/wasm-runtime@0.2.12':
+    resolution: {integrity: sha512-ZVWUcfwY4E/yPitQJl481FjFo3K22D6qF0DuFH6Y/nbnE11GY5uguDxZMGXPQ8WQ0128MXQD7TnfHyK4oWoIJQ==}
+
+  '@napi-rs/wasm-runtime@1.1.4':
+    resolution: {integrity: sha512-3NQNNgA1YSlJb/kMH1ildASP9HW7/7kYnRI2szWJaofaS1hWmbGI4H+d3+22aGzXXN9IJ+n+GiFVcGipJP18ow==}
+    peerDependencies:
+      '@emnapi/core': ^1.7.1
+      '@emnapi/runtime': ^1.7.1
+
+  '@next/env@16.2.6':
+    resolution: {integrity: sha512-gd8HoHN4ufj73WmR3JmVolrpJR47ILK6LouP5xElPglaVxir6e1a7VzvTvDWkOoPXT9rkkTzyCxBu4yeZfZwcw==}
+
+  '@next/swc-darwin-arm64@16.2.6':
+    resolution: {integrity: sha512-ZJGkkcNfYgrrMkqOdZ7zoLa1TOy0qpcMfk/z4Mh/FKUz40gVO+HNQWqmLxf67Z5WB64DRp0dhEbyHfel+6sJUg==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@next/swc-darwin-x64@16.2.6':
+    resolution: {integrity: sha512-v/YLBHIY132Ced3puBJ7YJKw1lqsCrgcNo2aRJlCEyQrrCeRJlvGlnmxhPxNQI3KE3N1DN5r9TPNPvka3nq5RQ==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@next/swc-linux-arm64-gnu@16.2.6':
+    resolution: {integrity: sha512-RPOvqlYBbcQjkz9VQQDZ2T2bARIjXZV1KFlt+V2Mr6SW/e4I9fcKsaA0hdyf2FHoTlsV2xnBd5Y912rP/1Ce6w==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  '@next/swc-linux-arm64-musl@16.2.6':
+    resolution: {integrity: sha512-URUTu1+dMkxJsPFgm+OeEvq9wf5sujw0EvgYy80TDGHTSLTnIHeqb0Eu8A3sC95IRgjejQL+kC4mw+4yPxiAXA==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  '@next/swc-linux-x64-gnu@16.2.6':
+    resolution: {integrity: sha512-DOj182mPV8G3UkrayLoREM5YEYI+Dk5wv7Ox9xl1fFibAELEsFD0lDPfHIeILlutMMfdyhlzYPELG3peuKaurw==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  '@next/swc-linux-x64-musl@16.2.6':
+    resolution: {integrity: sha512-HKQ5SP/V/ub73UvF7n/zeJlxk2kLmtL7Wzrg4WfmkjmNos5onJ2tKu7yZOPdL18A6Svfn3max29ym+ry7NkK4g==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  '@next/swc-win32-arm64-msvc@16.2.6':
+    resolution: {integrity: sha512-LZXpTlPyS5v7HhSmnvsLGP3iIYgYOBnc8r8ArlT55sGHV89bR2HlDdBjWQ+PY6SJMmk8TuVGFuxalnP3k/0Dwg==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@next/swc-win32-x64-msvc@16.2.6':
+    resolution: {integrity: sha512-F0+4i0h9J6C4eE3EAPWsoCk7UW/dbzOjyzxY0qnDUOYFu6FFmdZ6l97/XdV3/Nz3VYyO7UWjyEJUXkGqcoXfMA==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [win32]
+
+  '@noble/ciphers@1.3.0':
+    resolution: {integrity: sha512-2I0gnIVPtfnMw9ee9h1dJG7tp81+8Ob3OJb3Mv37rx5L40/b0i7djjCVvGOVqc9AEIQyvyu1i6ypKdFw8R8gQw==}
+    engines: {node: ^14.21.3 || >=16}
+
+  '@noble/curves@1.9.7':
+    resolution: {integrity: sha512-gbKGcRUYIjA3/zCCNaWDciTMFI0dCkvou3TL8Zmy5Nc7sJ47a0jtOeZoTaMxkuqRo9cRhjOdZJXegxYE5FN/xw==}
+    engines: {node: ^14.21.3 || >=16}
+
+  '@noble/hashes@1.8.0':
+    resolution: {integrity: sha512-jCs9ldd7NwzpgXDIf6P3+NrHh9/sD6CQdxHyjQI+h/6rDNo88ypBxxz45UDuZHz9r3tNz7N/VInSVoVdtXEI4A==}
+    engines: {node: ^14.21.3 || >=16}
+
+  '@nodelib/fs.scandir@2.1.5':
+    resolution: {integrity: sha512-vq24Bq3ym5HEQm2NKCr3yXDwjc7vTsEThRDnkp2DK9p1uqLR+DHurm/NOTo0KG7HYHU7eppKZj3MyqYuMBf62g==}
+    engines: {node: '>= 8'}
+
+  '@nodelib/fs.stat@2.0.5':
+    resolution: {integrity: sha512-RkhPPp2zrqDAQA/2jNhnztcPAlv64XdhIp7a7454A5ovI7Bukxgt7MX7udwAu3zg1DcpPU0rz3VV1SeaqvY4+A==}
+    engines: {node: '>= 8'}
+
+  '@nodelib/fs.walk@1.2.8':
+    resolution: {integrity: sha512-oGB+UxlgWcgQkgwo8GcEGwemoTFt3FIO9ababBmaGwXIoBKZ+GTy0pP185beGg7Llih/NSHSV2XAs1lnznocSg==}
+    engines: {node: '>= 8'}
+
+  '@open-draft/deferred-promise@2.2.0':
+    resolution: {integrity: sha512-CecwLWx3rhxVQF6V4bAgPS5t+So2sTbPgAzafKkVizyi7tlwpcFpdFqq+wqF2OwNBmqFuu6tOyouTuxgpMfzmA==}
+
+  '@open-draft/deferred-promise@3.0.0':
+    resolution: {integrity: sha512-XW375UK8/9SqUVNVa6M0yEy8+iTi4QN5VZ7aZuRFQmy76LRwI9wy5F4YIBU6T+eTe2/DNDo8tqu8RHlwLHM6RA==}
+
+  '@open-draft/logger@0.3.0':
+    resolution: {integrity: sha512-X2g45fzhxH238HKO4xbSr7+wBS8Fvw6ixhTDuvLd5mqh6bJJCFAPwU9mPDxbcrRtfxv4u5IHCEH77BmxvXmmxQ==}
+
+  '@open-draft/until@2.1.0':
+    resolution: {integrity: sha512-U69T3ItWHvLwGg5eJ0n3I62nWuE6ilHlmz7zM0npLBRvPRd7e6NYmg54vvRtP5mZG7kZqZCFVdsTWo7BPtBujg==}
+
+  '@oxc-project/types@0.130.0':
+    resolution: {integrity: sha512-ibD2usx9JRu7f5pu2tMKMI4cpA4NgXJQoYRP4pQ7Pxmn1l6k/53qWtQWZayhYy3X4QZkt90Ot+mJEaeXouio6Q==}
+
+  '@package-json/types@0.0.12':
+    resolution: {integrity: sha512-uu43FGU34B5VM9mCNjXCwLaGHYjXdNincqKLaraaCW+7S2+SmiBg1Nv8bPnmschrIfZmfKNY9f3fC376MRrObw==}
+
+  '@pkgr/core@0.2.9':
+    resolution: {integrity: sha512-QNqXyfVS2wm9hweSYD2O7F0G06uurj9kZ96TRQE5Y9hU7+tgdZwIkbAKc5Ocy1HxEY2kuDQa6cQ1WRs/O5LFKA==}
+    engines: {node: ^12.20.0 || ^14.18.0 || >=16.0.0}
+
+  '@radix-ui/number@1.1.1':
+    resolution: {integrity: sha512-MkKCwxlXTgz6CFoJx3pCwn07GKp36+aZyu/u2Ln2VrA5DcdyCZkASEDBTd8x5whTQQL5CiYf4prXKLcgQdv29g==}
+
+  '@radix-ui/primitive@1.1.3':
+    resolution: {integrity: sha512-JTF99U/6XIjCBo0wqkU5sK10glYe27MRRsfwoiq5zzOEZLHU3A3KCMa5X/azekYRCJ0HlwI0crAXS/5dEHTzDg==}
+
+  '@radix-ui/react-accessible-icon@1.1.7':
+    resolution: {integrity: sha512-XM+E4WXl0OqUJFovy6GjmxxFyx9opfCAIUku4dlKRd5YEPqt4kALOkQOp0Of6reHuUkJuiPBEc5k0o4z4lTC8A==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-accordion@1.2.12':
+    resolution: {integrity: sha512-T4nygeh9YE9dLRPhAHSeOZi7HBXo+0kYIPJXayZfvWOWA0+n3dESrZbjfDPUABkUNym6Hd+f2IR113To8D2GPA==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-alert-dialog@1.1.15':
+    resolution: {integrity: sha512-oTVLkEw5GpdRe29BqJ0LSDFWI3qu0vR1M0mUkOQWDIUnY/QIkLpgDMWuKxP94c2NAC2LGcgVhG1ImF3jkZ5wXw==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-arrow@1.1.7':
+    resolution: {integrity: sha512-F+M1tLhO+mlQaOWspE8Wstg+z6PwxwRd8oQ8IXceWz92kfAmalTRf0EjrouQeo7QssEPfCn05B4Ihs1K9WQ/7w==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-aspect-ratio@1.1.7':
+    resolution: {integrity: sha512-Yq6lvO9HQyPwev1onK1daHCHqXVLzPhSVjmsNjCa2Zcxy2f7uJD2itDtxknv6FzAKCwD1qQkeVDmX/cev13n/g==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-avatar@1.1.10':
+    resolution: {integrity: sha512-V8piFfWapM5OmNCXTzVQY+E1rDa53zY+MQ4Y7356v4fFz6vqCyUtIz2rUD44ZEdwg78/jKmMJHj07+C/Z/rcog==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-checkbox@1.3.3':
+    resolution: {integrity: sha512-wBbpv+NQftHDdG86Qc0pIyXk5IR3tM8Vd0nWLKDcX8nNn4nXFOFwsKuqw2okA/1D/mpaAkmuyndrPJTYDNZtFw==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-collapsible@1.1.12':
+    resolution: {integrity: sha512-Uu+mSh4agx2ib1uIGPP4/CKNULyajb3p92LsVXmH2EHVMTfZWpll88XJ0j4W0z3f8NK1eYl1+Mf/szHPmcHzyA==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-collection@1.1.7':
+    resolution: {integrity: sha512-Fh9rGN0MoI4ZFUNyfFVNU4y9LUz93u9/0K+yLgA2bwRojxM8JU1DyvvMBabnZPBgMWREAJvU2jjVzq+LrFUglw==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-compose-refs@1.1.2':
+    resolution: {integrity: sha512-z4eqJvfiNnFMHIIvXP3CY57y2WJs5g2v3X0zm9mEJkrkNv4rDxu+sg9Jh8EkXyeqBkB7SOcboo9dMVqhyrACIg==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-context-menu@2.2.16':
+    resolution: {integrity: sha512-O8morBEW+HsVG28gYDZPTrT9UUovQUlJue5YO836tiTJhuIWBm/zQHc7j388sHWtdH/xUZurK9olD2+pcqx5ww==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-context@1.1.2':
+    resolution: {integrity: sha512-jCi/QKUM2r1Ju5a3J64TH2A5SpKAgh0LpknyqdQ4m6DCV0xJ2HG1xARRwNGPQfi1SLdLWZ1OJz6F4OMBBNiGJA==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-dialog@1.1.15':
+    resolution: {integrity: sha512-TCglVRtzlffRNxRMEyR36DGBLJpeusFcgMVD9PZEzAKnUs1lKCgX5u9BmC2Yg+LL9MgZDugFFs1Vl+Jp4t/PGw==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-direction@1.1.1':
+    resolution: {integrity: sha512-1UEWRX6jnOA2y4H5WczZ44gOOjTEmlqv1uNW4GAJEO5+bauCBhv8snY65Iw5/VOS/ghKN9gr2KjnLKxrsvoMVw==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-dismissable-layer@1.1.11':
+    resolution: {integrity: sha512-Nqcp+t5cTB8BinFkZgXiMJniQH0PsUt2k51FUhbdfeKvc4ACcG2uQniY/8+h1Yv6Kza4Q7lD7PQV0z0oicE0Mg==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-dropdown-menu@2.1.16':
+    resolution: {integrity: sha512-1PLGQEynI/3OX/ftV54COn+3Sud/Mn8vALg2rWnBLnRaGtJDduNW/22XjlGgPdpcIbiQxjKtb7BkcjP00nqfJw==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-focus-guards@1.1.3':
+    resolution: {integrity: sha512-0rFg/Rj2Q62NCm62jZw0QX7a3sz6QCQU0LpZdNrJX8byRGaGVTqbrW9jAoIAHyMQqsNpeZ81YgSizOt5WXq0Pw==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-focus-scope@1.1.7':
+    resolution: {integrity: sha512-t2ODlkXBQyn7jkl6TNaw/MtVEVvIGelJDCG41Okq/KwUsJBwQ4XVZsHAVUkK4mBv3ewiAS3PGuUWuY2BoK4ZUw==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-form@0.1.8':
+    resolution: {integrity: sha512-QM70k4Zwjttifr5a4sZFts9fn8FzHYvQ5PiB19O2HsYibaHSVt9fH9rzB0XZo/YcM+b7t/p7lYCT/F5eOeF5yQ==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-hover-card@1.1.15':
+    resolution: {integrity: sha512-qgTkjNT1CfKMoP0rcasmlH2r1DAiYicWsDsufxl940sT2wHNEWWv6FMWIQXWhVdmC1d/HYfbhQx60KYyAtKxjg==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-id@1.1.1':
+    resolution: {integrity: sha512-kGkGegYIdQsOb4XjsfM97rXsiHaBwco+hFI66oO4s9LU+PLAC5oJ7khdOVFxkhsmlbpUqDAvXw11CluXP+jkHg==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-label@2.1.7':
+    resolution: {integrity: sha512-YT1GqPSL8kJn20djelMX7/cTRp/Y9w5IZHvfxQTVHrOqa2yMl7i/UfMqKRU5V7mEyKTrUVgJXhNQPVCG8PBLoQ==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-menu@2.1.16':
+    resolution: {integrity: sha512-72F2T+PLlphrqLcAotYPp0uJMr5SjP5SL01wfEspJbru5Zs5vQaSHb4VB3ZMJPimgHHCHG7gMOeOB9H3Hdmtxg==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-menubar@1.1.16':
+    resolution: {integrity: sha512-EB1FktTz5xRRi2Er974AUQZWg2yVBb1yjip38/lgwtCVRd3a+maUoGHN/xs9Yv8SY8QwbSEb+YrxGadVWbEutA==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-navigation-menu@1.2.14':
+    resolution: {integrity: sha512-YB9mTFQvCOAQMHU+C/jVl96WmuWeltyUEpRJJky51huhds5W2FQr1J8D/16sQlf0ozxkPK8uF3niQMdUwZPv5w==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-one-time-password-field@0.1.8':
+    resolution: {integrity: sha512-ycS4rbwURavDPVjCb5iS3aG4lURFDILi6sKI/WITUMZ13gMmn/xGjpLoqBAalhJaDk8I3UbCM5GzKHrnzwHbvg==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-password-toggle-field@0.1.3':
+    resolution: {integrity: sha512-/UuCrDBWravcaMix4TdT+qlNdVwOM1Nck9kWx/vafXsdfj1ChfhOdfi3cy9SGBpWgTXwYCuboT/oYpJy3clqfw==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-popover@1.1.15':
+    resolution: {integrity: sha512-kr0X2+6Yy/vJzLYJUPCZEc8SfQcf+1COFoAqauJm74umQhta9M7lNJHP7QQS3vkvcGLQUbWpMzwrXYwrYztHKA==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-popper@1.2.8':
+    resolution: {integrity: sha512-0NJQ4LFFUuWkE7Oxf0htBKS6zLkkjBH+hM1uk7Ng705ReR8m/uelduy1DBo0PyBXPKVnBA6YBlU94MBGXrSBCw==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-portal@1.1.9':
+    resolution: {integrity: sha512-bpIxvq03if6UNwXZ+HTK71JLh4APvnXntDc6XOX8UVq4XQOVl7lwok0AvIl+b8zgCw3fSaVTZMpAPPagXbKmHQ==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-presence@1.1.5':
+    resolution: {integrity: sha512-/jfEwNDdQVBCNvjkGit4h6pMOzq8bHkopq458dPt2lMjx+eBQUohZNG9A7DtO/O5ukSbxuaNGXMjHicgwy6rQQ==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-primitive@2.1.3':
+    resolution: {integrity: sha512-m9gTwRkhy2lvCPe6QJp4d3G1TYEUHn/FzJUtq9MjH46an1wJU+GdoGC5VLof8RX8Ft/DlpshApkhswDLZzHIcQ==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-progress@1.1.7':
+    resolution: {integrity: sha512-vPdg/tF6YC/ynuBIJlk1mm7Le0VgW6ub6J2UWnTQ7/D23KXcPI1qy+0vBkgKgd38RCMJavBXpB83HPNFMTb0Fg==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-radio-group@1.3.8':
+    resolution: {integrity: sha512-VBKYIYImA5zsxACdisNQ3BjCBfmbGH3kQlnFVqlWU4tXwjy7cGX8ta80BcrO+WJXIn5iBylEH3K6ZTlee//lgQ==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-roving-focus@1.1.11':
+    resolution: {integrity: sha512-7A6S9jSgm/S+7MdtNDSb+IU859vQqJ/QAtcYQcfFC6W8RS4IxIZDldLR0xqCFZ6DCyrQLjLPsxtTNch5jVA4lA==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-scroll-area@1.2.10':
+    resolution: {integrity: sha512-tAXIa1g3sM5CGpVT0uIbUx/U3Gs5N8T52IICuCtObaos1S8fzsrPXG5WObkQN3S6NVl6wKgPhAIiBGbWnvc97A==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-select@2.2.6':
+    resolution: {integrity: sha512-I30RydO+bnn2PQztvo25tswPH+wFBjehVGtmagkU78yMdwTwVf12wnAOF+AeP8S2N8xD+5UPbGhkUfPyvT+mwQ==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-separator@1.1.7':
+    resolution: {integrity: sha512-0HEb8R9E8A+jZjvmFCy/J4xhbXy3TV+9XSnGJ3KvTtjlIUy/YQ/p6UYZvi7YbeoeXdyU9+Y3scizK6hkY37baA==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-slider@1.3.6':
+    resolution: {integrity: sha512-JPYb1GuM1bxfjMRlNLE+BcmBC8onfCi60Blk7OBqi2MLTFdS+8401U4uFjnwkOr49BLmXxLC6JHkvAsx5OJvHw==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-slot@1.2.3':
+    resolution: {integrity: sha512-aeNmHnBxbi2St0au6VBVC7JXFlhLlOnvIIlePNniyUNAClzmtAUEY8/pBiK3iHjufOlwA+c20/8jngo7xcrg8A==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-switch@1.2.6':
+    resolution: {integrity: sha512-bByzr1+ep1zk4VubeEVViV592vu2lHE2BZY5OnzehZqOOgogN80+mNtCqPkhn2gklJqOpxWgPoYTSnhBCqpOXQ==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-tabs@1.1.13':
+    resolution: {integrity: sha512-7xdcatg7/U+7+Udyoj2zodtI9H/IIopqo+YOIcZOq1nJwXWBZ9p8xiu5llXlekDbZkca79a/fozEYQXIA4sW6A==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-toast@1.2.15':
+    resolution: {integrity: sha512-3OSz3TacUWy4WtOXV38DggwxoqJK4+eDkNMl5Z/MJZaoUPaP4/9lf81xXMe1I2ReTAptverZUpbPY4wWwWyL5g==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-toggle-group@1.1.11':
+    resolution: {integrity: sha512-5umnS0T8JQzQT6HbPyO7Hh9dgd82NmS36DQr+X/YJ9ctFNCiiQd6IJAYYZ33LUwm8M+taCz5t2ui29fHZc4Y6Q==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-toggle@1.1.10':
+    resolution: {integrity: sha512-lS1odchhFTeZv3xwHH31YPObmJn8gOg7Lq12inrr0+BH/l3Tsq32VfjqH1oh80ARM3mlkfMic15n0kg4sD1poQ==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-toolbar@1.1.11':
+    resolution: {integrity: sha512-4ol06/1bLoFu1nwUqzdD4Y5RZ9oDdKeiHIsntug54Hcr1pgaHiPqHFEaXI1IFP/EsOfROQZ8Mig9VTIRza6Tjg==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-tooltip@1.2.8':
+    resolution: {integrity: sha512-tY7sVt1yL9ozIxvmbtN5qtmH2krXcBCfjEiCgKGLqunJHvgvZG2Pcl2oQ3kbcZARb1BGEHdkLzcYGO8ynVlieg==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-use-callback-ref@1.1.1':
+    resolution: {integrity: sha512-FkBMwD+qbGQeMu1cOHnuGB6x4yzPjho8ap5WtbEJ26umhgqVXbhekKUQO+hZEL1vU92a3wHwdp0HAcqAUF5iDg==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-use-controllable-state@1.2.2':
+    resolution: {integrity: sha512-BjasUjixPFdS+NKkypcyyN5Pmg83Olst0+c6vGov0diwTEo6mgdqVR6hxcEgFuh4QrAs7Rc+9KuGJ9TVCj0Zzg==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-use-effect-event@0.0.2':
+    resolution: {integrity: sha512-Qp8WbZOBe+blgpuUT+lw2xheLP8q0oatc9UpmiemEICxGvFLYmHm9QowVZGHtJlGbS6A6yJ3iViad/2cVjnOiA==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-use-escape-keydown@1.1.1':
+    resolution: {integrity: sha512-Il0+boE7w/XebUHyBjroE+DbByORGR9KKmITzbR7MyQ4akpORYP/ZmbhAr0DG7RmmBqoOnZdy2QlvajJ2QA59g==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-use-is-hydrated@0.1.0':
+    resolution: {integrity: sha512-U+UORVEq+cTnRIaostJv9AGdV3G6Y+zbVd+12e18jQ5A3c0xL03IhnHuiU4UV69wolOQp5GfR58NW/EgdQhwOA==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-use-layout-effect@1.1.1':
+    resolution: {integrity: sha512-RbJRS4UWQFkzHTTwVymMTUv8EqYhOp8dOOviLj2ugtTiXRaRQS7GLGxZTLL1jWhMeoSCf5zmcZkqTl9IiYfXcQ==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-use-previous@1.1.1':
+    resolution: {integrity: sha512-2dHfToCj/pzca2Ck724OZ5L0EVrr3eHRNsG/b3xQJLA2hZpVCS99bLAX+hm1IHXDEnzU6by5z/5MIY794/a8NQ==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-use-rect@1.1.1':
+    resolution: {integrity: sha512-QTYuDesS0VtuHNNvMh+CjlKJ4LJickCMUAqjlE3+j8w+RlRpwyX3apEQKGFzbZGdo7XNG1tXa+bQqIE7HIXT2w==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-use-size@1.1.1':
+    resolution: {integrity: sha512-ewrXRDTAqAXlkl6t/fkXWNAhFX9I+CkKlw6zjEwk86RSPKwZr3xpBRso655aqYafwtnbpHLj6toFzmd6xdVptQ==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-visually-hidden@1.2.3':
+    resolution: {integrity: sha512-pzJq12tEaaIhqjbzpCuv/OypJY/BPavOofm+dbab+MHLajy277+1lLm6JFcGgF5eskJ6mquGirhXY2GD/8u8Ug==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/rect@1.1.1':
+    resolution: {integrity: sha512-HPwpGIzkl28mWyZqG52jiqDJ12waP11Pa1lGoiyUkIEuMLBP0oeK/C89esbXrxsky5we7dfd8U58nm0SgAWpVw==}
+
+  '@rolldown/binding-android-arm64@1.0.1':
+    resolution: {integrity: sha512-fJI3I0r3C3Oj/zdBCpaCmBRZYf07xpaq4yCfDDoSFm+beWNzbIl26puW8RraUdugoJw/95zerNOn6jasAhzSmg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [android]
+
+  '@rolldown/binding-darwin-arm64@1.0.1':
+    resolution: {integrity: sha512-cKnAhWEsV7TPcA/5EAteDp6KcJZBQ2G+BqE7zayMMi7kMvwRsbv7WT9aOnn0WNl4SKEIf43vjS31iUPu80nzXg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@rolldown/binding-darwin-x64@1.0.1':
+    resolution: {integrity: sha512-YKrVwQjIRBPo+5G/u03wGjbdy4q7pyzCe93DK9VJ7zkVmeg8LJ7GbgsiHWdR4xSoe4CAXRD7Bcjgbtr64bkXNg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [darwin]
+
+  '@rolldown/binding-freebsd-x64@1.0.1':
+    resolution: {integrity: sha512-z/oBsREo46SsFqBwYtFe0kpJeBijAT48O/WXLI4suiCLBkr03RTtTJMCzSdDd2znlh8VJizL09XVkQgk8IZonw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@rolldown/binding-linux-arm-gnueabihf@1.0.1':
+    resolution: {integrity: sha512-ik8q7GM11zxvYxFc2PeDcT6TBvhCQMaUxfph/M5l9sKuTs/Sjg3L+Byw0F7w0ZVLBZmx30P+gG0ECzzN+MFcmQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm]
+    os: [linux]
+
+  '@rolldown/binding-linux-arm64-gnu@1.0.1':
+    resolution: {integrity: sha512-QoSx2EkyrrdZ6kcyE8stqZ62t0Yra8Fs5ia9lOxJrh6TMQJK7gQKmscdTHf7pOXKREKrVwOtJcQG3qVSfc866A==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  '@rolldown/binding-linux-arm64-musl@1.0.1':
+    resolution: {integrity: sha512-uwNwFpwKeNiZawfAWBgg0VIztPTV3ihhh1vV334h9ivnNLorxnQMU6Fz8wG1Zb4Qh9LC1/MkcyT3YlDXG3Rsgg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  '@rolldown/binding-linux-ppc64-gnu@1.0.1':
+    resolution: {integrity: sha512-zY1bul7OWr7DFBiJ++wofXvnr8B45ce3QsQUhKrIhXsygAh7bTkwyeM1bi1a2g5C/yC/N8TZyGDEoMfm/l9mpg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [ppc64]
+    os: [linux]
+    libc: [glibc]
+
+  '@rolldown/binding-linux-s390x-gnu@1.0.1':
+    resolution: {integrity: sha512-0frlsT/f4Ft6I7SMESTKnF3cZsdicQn1dCMkF/jT9wDLE+gGoiQfv1nmT9e+s7s/fekvvy6tZM2jHvI2tkbJDQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [s390x]
+    os: [linux]
+    libc: [glibc]
+
+  '@rolldown/binding-linux-x64-gnu@1.0.1':
+    resolution: {integrity: sha512-XABVmGp9Tg0WspTVvwduTc4fpqy6JnAUrSQe6OuyqD/03nI7r0O9OWUkMIwFrjKAIqolvqoA4ZrJppgwE0Gxmw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  '@rolldown/binding-linux-x64-musl@1.0.1':
+    resolution: {integrity: sha512-bV4fzswuzVcKD90o/VM6QqKxnxlDq0g2BISDLNVmxrnhpv1DDbyPhCIjYfvzYLV+MvkKKnQt2Q6AO86SEBULUQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  '@rolldown/binding-openharmony-arm64@1.0.1':
+    resolution: {integrity: sha512-/Mh0Zhq3OP7fVs0kcQHZP6lZEthMGTaSf8UBQYSFEZDWGXXlEC+nJ6EqenaK2t4LBXMe3A+K/G2BVXXdtOr4PQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [openharmony]
+
+  '@rolldown/binding-wasm32-wasi@1.0.1':
+    resolution: {integrity: sha512-+1xc9X45l8ufsBAm6Gjvx2qDRIY9lTVt0cgWNcJ+1gdhXvkbxePA60yRTwSTuXL09CMhyJmjpV7E3NoyxbqFQQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [wasm32]
+
+  '@rolldown/binding-win32-arm64-msvc@1.0.1':
+    resolution: {integrity: sha512-1D+UqZdfnuR+Jy1GgMJwi85bD40H21uNmOPRWQhw4oRSuolZ/B5rixZ45DK2KXOTCvmVCecauWgEhbw8bI7tOw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [win32]
+
+  '@rolldown/binding-win32-x64-msvc@1.0.1':
+    resolution: {integrity: sha512-INAycaWuhlOK3wk4mRHGsdgwYWmd9cChdPdE9bwWmy6rn9VqVNYNFGhOdXrofXUxwHIncSiPNb8tNm8knDVIeQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [win32]
+
+  '@rolldown/pluginutils@1.0.0-rc.7':
+    resolution: {integrity: sha512-qujRfC8sFVInYSPPMLQByRh7zhwkGFS4+tyMQ83srV1qrxL4g8E2tyxVVyxd0+8QeBM1mIk9KbWxkegRr76XzA==}
+
+  '@rolldown/pluginutils@1.0.1':
+    resolution: {integrity: sha512-2j9bGt5Jh8hj+vPtgzPtl72j0yRxHAyumoo6TNfAjsLB04UtpSvPbPcDcBMxz7n+9CYB0c1GxQFxYRg2jimqGw==}
+
+  '@rollup/pluginutils@5.3.0':
+    resolution: {integrity: sha512-5EdhGZtnu3V88ces7s53hhfK5KSASnJZv8Lulpc04cWO3REESroJXg73DFsOmgbU2BhwV0E20bu2IDZb3VKW4Q==}
+    engines: {node: '>=14.0.0'}
+    peerDependencies:
+      rollup: ^1.20.0||^2.0.0||^3.0.0||^4.0.0
+    peerDependenciesMeta:
+      rollup:
+        optional: true
+
+  '@sec-ant/readable-stream@0.4.1':
+    resolution: {integrity: sha512-831qok9r2t8AlxLko40y2ebgSDhenenCatLVeW/uBtnHPyhHOvG0C7TvfgecV+wHzIm5KUICgzmVpWS+IMEAeg==}
+
+  '@sindresorhus/merge-streams@4.0.0':
+    resolution: {integrity: sha512-tlqY9xq5ukxTUZBmoOp+m61cqwQD5pHJtFY3Mn8CA8ps6yghLH/Hw8UPdqg4OLmFW3IFlcXnQNmo/dh8HzXYIQ==}
+    engines: {node: '>=18'}
+
+  '@svgr/babel-plugin-add-jsx-attribute@8.0.0':
+    resolution: {integrity: sha512-b9MIk7yhdS1pMCZM8VeNfUlSKVRhsHZNMl5O9SfaX0l0t5wjdgu4IDzGB8bpnGBBOjGST3rRFVsaaEtI4W6f7g==}
+    engines: {node: '>=14'}
+    peerDependencies:
+      '@babel/core': ^7.0.0-0
+
+  '@svgr/babel-plugin-remove-jsx-attribute@8.0.0':
+    resolution: {integrity: sha512-BcCkm/STipKvbCl6b7QFrMh/vx00vIP63k2eM66MfHJzPr6O2U0jYEViXkHJWqXqQYjdeA9cuCl5KWmlwjDvbA==}
+    engines: {node: '>=14'}
+    peerDependencies:
+      '@babel/core': ^7.0.0-0
+
+  '@svgr/babel-plugin-remove-jsx-empty-expression@8.0.0':
+    resolution: {integrity: sha512-5BcGCBfBxB5+XSDSWnhTThfI9jcO5f0Ai2V24gZpG+wXF14BzwxxdDb4g6trdOux0rhibGs385BeFMSmxtS3uA==}
+    engines: {node: '>=14'}
+    peerDependencies:
+      '@babel/core': ^7.0.0-0
+
+  '@svgr/babel-plugin-replace-jsx-attribute-value@8.0.0':
+    resolution: {integrity: sha512-KVQ+PtIjb1BuYT3ht8M5KbzWBhdAjjUPdlMtpuw/VjT8coTrItWX6Qafl9+ji831JaJcu6PJNKCV0bp01lBNzQ==}
+    engines: {node: '>=14'}
+    peerDependencies:
+      '@babel/core': ^7.0.0-0
+
+  '@svgr/babel-plugin-svg-dynamic-title@8.0.0':
+    resolution: {integrity: sha512-omNiKqwjNmOQJ2v6ge4SErBbkooV2aAWwaPFs2vUY7p7GhVkzRkJ00kILXQvRhA6miHnNpXv7MRnnSjdRjK8og==}
+    engines: {node: '>=14'}
+    peerDependencies:
+      '@babel/core': ^7.0.0-0
+
+  '@svgr/babel-plugin-svg-em-dimensions@8.0.0':
+    resolution: {integrity: sha512-mURHYnu6Iw3UBTbhGwE/vsngtCIbHE43xCRK7kCw4t01xyGqb2Pd+WXekRRoFOBIY29ZoOhUCTEweDMdrjfi9g==}
+    engines: {node: '>=14'}
+    peerDependencies:
+      '@babel/core': ^7.0.0-0
+
+  '@svgr/babel-plugin-transform-react-native-svg@8.1.0':
+    resolution: {integrity: sha512-Tx8T58CHo+7nwJ+EhUwx3LfdNSG9R2OKfaIXXs5soiy5HtgoAEkDay9LIimLOcG8dJQH1wPZp/cnAv6S9CrR1Q==}
+    engines: {node: '>=14'}
+    peerDependencies:
+      '@babel/core': ^7.0.0-0
+
+  '@svgr/babel-plugin-transform-svg-component@8.0.0':
+    resolution: {integrity: sha512-DFx8xa3cZXTdb/k3kfPeaixecQLgKh5NVBMwD0AQxOzcZawK4oo1Jh9LbrcACUivsCA7TLG8eeWgrDXjTMhRmw==}
+    engines: {node: '>=12'}
+    peerDependencies:
+      '@babel/core': ^7.0.0-0
+
+  '@svgr/babel-preset@8.1.0':
+    resolution: {integrity: sha512-7EYDbHE7MxHpv4sxvnVPngw5fuR6pw79SkcrILHJ/iMpuKySNCl5W1qcwPEpU+LgyRXOaAFgH0KhwD18wwg6ug==}
+    engines: {node: '>=14'}
+    peerDependencies:
+      '@babel/core': ^7.0.0-0
+
+  '@svgr/core@8.1.0':
+    resolution: {integrity: sha512-8QqtOQT5ACVlmsvKOJNEaWmRPmcojMOzCz4Hs2BGG/toAp/K38LcsMRyLp349glq5AzJbCEeimEoxaX6v/fLrA==}
+    engines: {node: '>=14'}
+
+  '@svgr/hast-util-to-babel-ast@8.0.0':
+    resolution: {integrity: sha512-EbDKwO9GpfWP4jN9sGdYwPBU0kdomaPIL2Eu4YwmgP+sJeXT+L7bMwJUBnhzfH8Q2qMBqZ4fJwpCyYsAN3mt2Q==}
+    engines: {node: '>=14'}
+
+  '@svgr/plugin-jsx@8.1.0':
+    resolution: {integrity: sha512-0xiIyBsLlr8quN+WyuxooNW9RJ0Dpr8uOnH/xrCVO8GLUcwHISwj1AG0k+LFzteTkAA0GbX0kj9q6Dk70PTiPA==}
+    engines: {node: '>=14'}
+    peerDependencies:
+      '@svgr/core': '*'
+
+  '@swc/helpers@0.5.15':
+    resolution: {integrity: sha512-JQ5TuMi45Owi4/BIMAJBoSQoOJu12oOk/gADqlcUL9JEdHB8vyjUSsxqeNXnmXHjYKMi2WcYtezGEEhqUI/E2g==}
+
+  '@tailwindcss/node@4.3.0':
+    resolution: {integrity: sha512-aFb4gUhFOgdh9AXo4IzBEOzBkkAxm9VigwDJnMIYv3lcfXCJVesNfbEaBl4BNgVRyid92AmdviqwBUBRKSeY3g==}
+
+  '@tailwindcss/oxide-android-arm64@4.3.0':
+    resolution: {integrity: sha512-TJPiq67tKlLuObP6RkwvVGDoxCMBVtDgKkLfa/uyj7/FyxvQwHS+UOnVrXXgbEsfUaMgiVvC4KbJnRr26ho4Ng==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [android]
+
+  '@tailwindcss/oxide-darwin-arm64@4.3.0':
+    resolution: {integrity: sha512-oMN/WZRb+SO37BmUElEgeEWuU8E/HXRkiODxJxLe1UTHVXLrdVSgfaJV7pSlhRGMSOiXLuxTIjfsF3wYvz8cgQ==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@tailwindcss/oxide-darwin-x64@4.3.0':
+    resolution: {integrity: sha512-N6CUmu4a6bKVADfw77p+iw6Yd9Q3OBhe0veaDX+QazfuVYlQsHfDgxBrsjQ/IW+zywL8mTrNd0SdJT/zgtvMdA==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@tailwindcss/oxide-freebsd-x64@4.3.0':
+    resolution: {integrity: sha512-zDL5hBkQdH5C6MpqbK3gQAgP80tsMwSI26vjOzjJtNCMUo0lFgOItzHKBIupOZNQxt3ouPH7RPhvNhiTfCe5CQ==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@tailwindcss/oxide-linux-arm-gnueabihf@4.3.0':
+    resolution: {integrity: sha512-R06HdNi7A7OEoMsf6d4tjZ71RCWnZQPHj2mnotSFURjNLdBC+cIgXQ7l81CqeoiQftjf6OOblxXMInMgN2VzMA==}
+    engines: {node: '>= 20'}
+    cpu: [arm]
+    os: [linux]
+
+  '@tailwindcss/oxide-linux-arm64-gnu@4.3.0':
+    resolution: {integrity: sha512-qTJHELX8jetjhRQHCLilkVLmybpzNQAtaI/gaoVoidn/ufbNDbAo8KlK2J+yPoc8wQxvDxCmh/5lr8nC1+lTbg==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  '@tailwindcss/oxide-linux-arm64-musl@4.3.0':
+    resolution: {integrity: sha512-Z6sukiQsngnWO+l39X4pPbiWT81IC+PLKF+PHxIlyZbGNb9MODfYlXEVlFvej5BOZInWX01kVyzeLvHsXhfczQ==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  '@tailwindcss/oxide-linux-x64-gnu@4.3.0':
+    resolution: {integrity: sha512-DRNdQRpSGzRGfARVuVkxvM8Q12nh19l4BF/G7zGA1oe+9wcC6saFBHTISrpIcKzhiXtSrlSrluCfvMuledoCTQ==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  '@tailwindcss/oxide-linux-x64-musl@4.3.0':
+    resolution: {integrity: sha512-Z0IADbDo8bh6I7h2IQMx601AdXBLfFpEdUotft86evd/8ZPflZe9COPO8Q1vw+pfLWIUo9zN/JGZvwuAJqduqg==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  '@tailwindcss/oxide-wasm32-wasi@4.3.0':
+    resolution: {integrity: sha512-HNZGOUxEmElksYR7S6sC5jTeNGpobAsy9u7Gu0AskJ8/20FR9GqebUyB+HBcU/ax6BHuiuJi+Oda4B+YX6H1yA==}
+    engines: {node: '>=14.0.0'}
+    cpu: [wasm32]
+    bundledDependencies:
+      - '@napi-rs/wasm-runtime'
+      - '@emnapi/core'
+      - '@emnapi/runtime'
+      - '@tybys/wasm-util'
+      - '@emnapi/wasi-threads'
+      - tslib
+
+  '@tailwindcss/oxide-win32-arm64-msvc@4.3.0':
+    resolution: {integrity: sha512-Pe+RPVTi1T+qymuuRpcdvwSVZjnll/f7n8gBxMMh3xLTctMDKqpdfGimbMyioqtLhUYZxdJ9wGNhV7MKHvgZsQ==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@tailwindcss/oxide-win32-x64-msvc@4.3.0':
+    resolution: {integrity: sha512-Mvrf2kXW/yeW/OTezZlCGOirXRcUuLIBx/5Y12BaPM7wJoryG6dfS/NJL8aBPqtTEx/Vm4T4vKzFUcKDT+TKUA==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [win32]
+
+  '@tailwindcss/oxide@4.3.0':
+    resolution: {integrity: sha512-F7HZGBeN9I0/AuuJS5PwcD8xayx5ri5GhjYUDBEVYUkexyA/giwbDNjRVrxSezE3T250OU2K/wp/ltWx3UOefg==}
+    engines: {node: '>= 20'}
+
+  '@tailwindcss/typography@0.5.19':
+    resolution: {integrity: sha512-w31dd8HOx3k9vPtcQh5QHP9GwKcgbMp87j58qi6xgiBnFFtKEAgCWnDw4qUT8aHwkCp8bKvb/KGKWWHedP0AAg==}
+    peerDependencies:
+      tailwindcss: '>=3.0.0 || insiders || >=4.0.0-alpha.20 || >=4.0.0-beta.1'
+
+  '@tailwindcss/vite@4.3.0':
+    resolution: {integrity: sha512-t6J3OrB5Fc0ExuhohouH0fWUGMYL6PTLhW+E7zIk/pdbnJARZDCwjBznFnkh5ynRnIRSI4YjtTH0t6USjJISrw==}
+    peerDependencies:
+      vite: ^5.2.0 || ^6 || ^7 || ^8
+
+  '@ts-morph/common@0.27.0':
+    resolution: {integrity: sha512-Wf29UqxWDpc+i61k3oIOzcUfQt79PIT9y/MWfAGlrkjg6lBC1hwDECLXPVJAhWjiGbfBCxZd65F/LIZF3+jeJQ==}
+
+  '@tsconfig/node10@1.0.12':
+    resolution: {integrity: sha512-UCYBaeFvM11aU2y3YPZ//O5Rhj+xKyzy7mvcIoAjASbigy8mHMryP5cK7dgjlz2hWxh1g5pLw084E0a/wlUSFQ==}
+
+  '@tsconfig/node12@1.0.11':
+    resolution: {integrity: sha512-cqefuRsh12pWyGsIoBKJA9luFu3mRxCA+ORZvA4ktLSzIuCUtWVxGIuXigEwO5/ywWFMZ2QEGKWvkZG1zDMTag==}
+
+  '@tsconfig/node14@1.0.3':
+    resolution: {integrity: sha512-ysT8mhdixWK6Hw3i1V2AeRqZ5WfXg1G43mqoYlM2nc6388Fq5jcXyr5mRsqViLx/GJYdoL0bfXD8nmF+Zn/Iow==}
+
+  '@tsconfig/node16@1.0.4':
+    resolution: {integrity: sha512-vxhUy4J8lyeyinH7Azl1pdd43GJhZH/tP2weN8TntQblOY+A0XbT8DJk1/oCPuOOyg/Ja757rG0CgHcWC8OfMA==}
+
+  '@tybys/wasm-util@0.10.2':
+    resolution: {integrity: sha512-RoBvJ2X0wuKlWFIjrwffGw1IqZHKQqzIchKaadZZfnNpsAYp2mM0h36JtPCjNDAHGgYez/15uMBpfGwchhiMgg==}
+
+  '@types/body-parser@1.19.6':
+    resolution: {integrity: sha512-HLFeCYgz89uk22N5Qg3dvGvsv46B8GLvKKo1zKG4NybA8U2DiEO3w9lqGg29t/tfLRJpJ6iQxnVw4OnB7MoM9g==}
+
+  '@types/connect@3.4.38':
+    resolution: {integrity: sha512-K6uROf1LD88uDQqJCktA4yzL1YYAK6NgfsI0v/mTgyPKWsX1CnJ0XPSDhViejru1GcRkLWb8RlzFYJRqGUbaug==}
+
+  '@types/cors@2.8.19':
+    resolution: {integrity: sha512-mFNylyeyqN93lfe/9CSxOGREz8cpzAhH+E93xJ4xWQf62V8sQ/24reV2nyzUWM6H6Xji+GGHpkbLe7pVoUEskg==}
+
+  '@types/debug@4.1.13':
+    resolution: {integrity: sha512-KSVgmQmzMwPlmtljOomayoR89W4FynCAi3E8PPs7vmDVPe84hT+vGPKkJfThkmXs0x0jAaa9U8uW8bbfyS2fWw==}
+
+  '@types/esrecurse@4.3.1':
+    resolution: {integrity: sha512-xJBAbDifo5hpffDBuHl0Y8ywswbiAp/Wi7Y/GtAgSlZyIABppyurxVueOPE8LUQOxdlgi6Zqce7uoEpqNTeiUw==}
+
+  '@types/estree-jsx@1.0.5':
+    resolution: {integrity: sha512-52CcUVNFyfb1A2ALocQw/Dd1BQFNmSdkuC3BkZ6iqhdMfQz7JWOFRuJFloOzjk+6WijU56m9oKXFAXc7o3Towg==}
+
+  '@types/estree@1.0.9':
+    resolution: {integrity: sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg==}
+
+  '@types/express-serve-static-core@4.19.8':
+    resolution: {integrity: sha512-02S5fmqeoKzVZCHPZid4b8JH2eM5HzQLZWN2FohQEy/0eXTq8VXZfSN6Pcr3F6N9R/vNrj7cpgbhjie6m/1tCA==}
+
+  '@types/express@4.17.25':
+    resolution: {integrity: sha512-dVd04UKsfpINUnK0yBoYHDF3xu7xVH4BuDotC/xGuycx4CgbP48X/KF/586bcObxT0HENHXEU8Nqtu6NR+eKhw==}
+
+  '@types/hast@3.0.4':
+    resolution: {integrity: sha512-WPs+bbQw5aCj+x6laNGWLH3wviHtoCv/P3+otBhbOhJgG8qtpdAMlTCxLtsTWA7LH1Oh/bFCHsBn0TPS5m30EQ==}
+
+  '@types/http-errors@2.0.5':
+    resolution: {integrity: sha512-r8Tayk8HJnX0FztbZN7oVqGccWgw98T/0neJphO91KkmOzug1KkofZURD4UaD5uH8AqcFLfdPErnBod0u71/qg==}
+
+  '@types/json-schema@7.0.15':
+    resolution: {integrity: sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA==}
+
+  '@types/mdast@4.0.4':
+    resolution: {integrity: sha512-kGaNbPh1k7AFzgpud/gMdvIm5xuECykRR+JnWKQno9TAXVa6WIVCGTPvYGekIDL4uwCZQSYbUxNBSb1aUo79oA==}
+
+  '@types/mime-types@3.0.1':
+    resolution: {integrity: sha512-xRMsfuQbnRq1Ef+C+RKaENOxXX87Ygl38W1vDfPHRku02TgQr+Qd8iivLtAMcR0KF5/29xlnFihkTlbqFrGOVQ==}
+
+  '@types/mime@1.3.5':
+    resolution: {integrity: sha512-/pyBZWSLD2n0dcHE3hq8s8ZvcETHtEuF+3E7XVt0Ig2nvsVQXdghHVcEkIWjy9A0wKfTn97a/PSDYohKIlnP/w==}
+
+  '@types/ms@2.1.0':
+    resolution: {integrity: sha512-GsCCIZDE/p3i96vtEqx+7dBUGXrc7zeSK3wwPHIaRThS+9OhWIXRqzs4d6k1SVU8g91DrNRWxWUGhp5KXQb2VA==}
+
+  '@types/node@20.19.41':
+    resolution: {integrity: sha512-ECymXOukMnOoVkC2bb1Vc/w/836DXncOg5m8Xj1RH7xSHZJWNYY6Zh7EH477vcnD5egKNNfy2RpNOmuChhFPgQ==}
+
+  '@types/node@24.12.4':
+    resolution: {integrity: sha512-GUUEShf+PBCGW2KaXwcIt3Yk+e3pkKwWKb9GSyM9WQVE+ep2jzmHdGsHzu4wgcZy5fN9FBdVzjpBQsYlpfpgLA==}
+
+  '@types/qs@6.15.1':
+    resolution: {integrity: sha512-GZHUBZR9hckSUhrxmp1nG6NwdpM9fCunJwyThLW1X3AyHgd9IlHb6VANpQQqDr2o/qQp6McZ3y/IA2rVzKzSbw==}
+
+  '@types/range-parser@1.2.7':
+    resolution: {integrity: sha512-hKormJbkJqzQGhziax5PItDUTMAM9uE2XXQmM37dyd4hVM+5aVl7oVxMVUiVQn2oCQFN/LKCZdvSM0pFRqbSmQ==}
+
+  '@types/react-dom@19.2.3':
+    resolution: {integrity: sha512-jp2L/eY6fn+KgVVQAOqYItbF0VY/YApe5Mz2F0aykSO8gx31bYCZyvSeYxCHKvzHG5eZjc+zyaS5BrBWya2+kQ==}
+    peerDependencies:
+      '@types/react': ^19.2.0
+
+  '@types/react@19.2.14':
+    resolution: {integrity: sha512-ilcTH/UniCkMdtexkoCN0bI7pMcJDvmQFPvuPvmEaYA/NSfFTAgdUSLAoVjaRJm7+6PvcM+q1zYOwS4wTYMF9w==}
+
+  '@types/send@0.17.6':
+    resolution: {integrity: sha512-Uqt8rPBE8SY0RK8JB1EzVOIZ32uqy8HwdxCnoCOsYrvnswqmFZ/k+9Ikidlk/ImhsdvBsloHbAlewb2IEBV/Og==}
+
+  '@types/send@1.2.1':
+    resolution: {integrity: sha512-arsCikDvlU99zl1g69TcAB3mzZPpxgw0UQnaHeC1Nwb015xp8bknZv5rIfri9xTOcMuaVgvabfIRA7PSZVuZIQ==}
+
+  '@types/serve-static@1.15.10':
+    resolution: {integrity: sha512-tRs1dB+g8Itk72rlSI2ZrW6vZg0YrLI81iQSTkMmOqnqCaNr/8Ek4VwWcN5vZgCYWbg/JJSGBlUaYGAOP73qBw==}
+
+  '@types/set-cookie-parser@2.4.10':
+    resolution: {integrity: sha512-GGmQVGpQWUe5qglJozEjZV/5dyxbOOZ0LHe/lqyWssB88Y4svNfst0uqBVscdDeIKl5Jy5+aPSvy7mI9tYRguw==}
+
+  '@types/statuses@2.0.6':
+    resolution: {integrity: sha512-xMAgYwceFhRA2zY+XbEA7mxYbA093wdiW8Vu6gZPGWy9cmOyU9XesH1tNcEWsKFd5Vzrqx5T3D38PWx1FIIXkA==}
+
+  '@types/unist@2.0.11':
+    resolution: {integrity: sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA==}
+
+  '@types/unist@3.0.3':
+    resolution: {integrity: sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==}
+
+  '@types/validate-npm-package-name@4.0.2':
+    resolution: {integrity: sha512-lrpDziQipxCEeK5kWxvljWYhUvOiB2A9izZd9B2AFarYAkqZshb4lPbRs7zKEic6eGtH8V/2qJW+dPp9OtF6bw==}
+
+  '@typescript-eslint/eslint-plugin@8.59.3':
+    resolution: {integrity: sha512-PwFvSKsXGShKGW6n5bZOhGHEcCZXM8HofLK9fNsEwZXzFRjoY+XT1Vsf1zgyXdwTr0ZYz1/2tkZ0DBTT9jZjhw==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      '@typescript-eslint/parser': ^8.59.3
+      eslint: ^8.57.0 || ^9.0.0 || ^10.0.0
+      typescript: '>=4.8.4 <6.1.0'
+
+  '@typescript-eslint/parser@8.59.3':
+    resolution: {integrity: sha512-HPwA+hVkfcriajbNvTmZv4VRauibay+cWArYUYq7u7W7PmGShMxbPxLvrwDme55a6d5alG3nrYfhyJ/G28XlLg==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      eslint: ^8.57.0 || ^9.0.0 || ^10.0.0
+      typescript: '>=4.8.4 <6.1.0'
+
+  '@typescript-eslint/project-service@8.59.3':
+    resolution: {integrity: sha512-ECiUWa/KYRGDFUqTNehaRgzDshnJfkTABJxVemHk4ko22gcr0ukloKjWvyQ64g8YCV/UI47kN1dbmjf/GaQYng==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      typescript: '>=4.8.4 <6.1.0'
+
+  '@typescript-eslint/scope-manager@8.59.3':
+    resolution: {integrity: sha512-t2LvZnoEfzKtnPjgeEu41xw5gxq9mQVfYy4OoZ4Vlt0sk3JwxmhCca/AR7DwOiHrjWgjAj6as4AhRLKSDfvZIA==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  '@typescript-eslint/tsconfig-utils@8.59.3':
+    resolution: {integrity: sha512-PcIJHjmaREXLgIAIzLnSY9VucEzz8FKXsRgFa1DmdGCK/5tJpW03TKJF01Q6VZd1lLdz2sIKPWaDUZN9dp//dw==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      typescript: '>=4.8.4 <6.1.0'
+
+  '@typescript-eslint/type-utils@8.59.3':
+    resolution: {integrity: sha512-g71d8QD8UaiHGvrJwyIS1hCX5r63w6Jll+4VEYhEAHXTDIqX1JgxhTAbEHtKntL9kuc4jRo7/GWw5xfCepSccQ==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      eslint: ^8.57.0 || ^9.0.0 || ^10.0.0
+      typescript: '>=4.8.4 <6.1.0'
+
+  '@typescript-eslint/types@8.59.3':
+    resolution: {integrity: sha512-ePFoH0g4ludssdRFqqDxQePCxU4WQyRa9+XVwjm7yLn0FKhMeoetC+qBEEI1Eyb1pGSDveTIT09Bvw2WhlGayg==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  '@typescript-eslint/typescript-estree@8.59.3':
+    resolution: {integrity: sha512-CbRjVRAf7Lr9Kr8RopKcbY45p2VfmmHrm0ygOCYFi7oU8q19m0Fs/6iHS7kNOmwpp+ob07ZVcAqlxUod9lYdmg==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      typescript: '>=4.8.4 <6.1.0'
+
+  '@typescript-eslint/utils@8.59.3':
+    resolution: {integrity: sha512-JAvT14goBzRzzzZyqq3P9BLArIxTtQURUtFgQ/V7FO+eU+Gg6ES+5ymOPP1wRxXcxAYeivCk4uS3jCKWI1K8Zg==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      eslint: ^8.57.0 || ^9.0.0 || ^10.0.0
+      typescript: '>=4.8.4 <6.1.0'
+
+  '@typescript-eslint/visitor-keys@8.59.3':
+    resolution: {integrity: sha512-f1UQF7ggd42YiwI5wGrRaPsa+P0CINBlrkLPmGfpq/u/I/oVtecoEIfFR9ag/oa1sLOsRNZ6xehf6qMZhQGBDg==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  '@ungap/structured-clone@1.3.1':
+    resolution: {integrity: sha512-mUFwbeTqrVgDQxFveS+df2yfap6iuP20NAKAsBt5jDEoOTDew+zwLAOilHCeQJOVSvmgCX4ogqIrA0mnyr08yQ==}
+
+  '@unrs/resolver-binding-android-arm-eabi@1.11.1':
+    resolution: {integrity: sha512-ppLRUgHVaGRWUx0R0Ut06Mjo9gBaBkg3v/8AxusGLhsIotbBLuRk51rAzqLC8gq6NyyAojEXglNjzf6R948DNw==}
+    cpu: [arm]
+    os: [android]
+
+  '@unrs/resolver-binding-android-arm64@1.11.1':
+    resolution: {integrity: sha512-lCxkVtb4wp1v+EoN+HjIG9cIIzPkX5OtM03pQYkG+U5O/wL53LC4QbIeazgiKqluGeVEeBlZahHalCaBvU1a2g==}
+    cpu: [arm64]
+    os: [android]
+
+  '@unrs/resolver-binding-darwin-arm64@1.11.1':
+    resolution: {integrity: sha512-gPVA1UjRu1Y/IsB/dQEsp2V1pm44Of6+LWvbLc9SDk1c2KhhDRDBUkQCYVWe6f26uJb3fOK8saWMgtX8IrMk3g==}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@unrs/resolver-binding-darwin-x64@1.11.1':
+    resolution: {integrity: sha512-cFzP7rWKd3lZaCsDze07QX1SC24lO8mPty9vdP+YVa3MGdVgPmFc59317b2ioXtgCMKGiCLxJ4HQs62oz6GfRQ==}
+    cpu: [x64]
+    os: [darwin]
+
+  '@unrs/resolver-binding-freebsd-x64@1.11.1':
+    resolution: {integrity: sha512-fqtGgak3zX4DCB6PFpsH5+Kmt/8CIi4Bry4rb1ho6Av2QHTREM+47y282Uqiu3ZRF5IQioJQ5qWRV6jduA+iGw==}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@unrs/resolver-binding-linux-arm-gnueabihf@1.11.1':
+    resolution: {integrity: sha512-u92mvlcYtp9MRKmP+ZvMmtPN34+/3lMHlyMj7wXJDeXxuM0Vgzz0+PPJNsro1m3IZPYChIkn944wW8TYgGKFHw==}
+    cpu: [arm]
+    os: [linux]
+
+  '@unrs/resolver-binding-linux-arm-musleabihf@1.11.1':
+    resolution: {integrity: sha512-cINaoY2z7LVCrfHkIcmvj7osTOtm6VVT16b5oQdS4beibX2SYBwgYLmqhBjA1t51CarSaBuX5YNsWLjsqfW5Cw==}
+    cpu: [arm]
+    os: [linux]
+
+  '@unrs/resolver-binding-linux-arm64-gnu@1.11.1':
+    resolution: {integrity: sha512-34gw7PjDGB9JgePJEmhEqBhWvCiiWCuXsL9hYphDF7crW7UgI05gyBAi6MF58uGcMOiOqSJ2ybEeCvHcq0BCmQ==}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  '@unrs/resolver-binding-linux-arm64-musl@1.11.1':
+    resolution: {integrity: sha512-RyMIx6Uf53hhOtJDIamSbTskA99sPHS96wxVE/bJtePJJtpdKGXO1wY90oRdXuYOGOTuqjT8ACccMc4K6QmT3w==}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  '@unrs/resolver-binding-linux-ppc64-gnu@1.11.1':
+    resolution: {integrity: sha512-D8Vae74A4/a+mZH0FbOkFJL9DSK2R6TFPC9M+jCWYia/q2einCubX10pecpDiTmkJVUH+y8K3BZClycD8nCShA==}
+    cpu: [ppc64]
+    os: [linux]
+    libc: [glibc]
+
+  '@unrs/resolver-binding-linux-riscv64-gnu@1.11.1':
+    resolution: {integrity: sha512-frxL4OrzOWVVsOc96+V3aqTIQl1O2TjgExV4EKgRY09AJ9leZpEg8Ak9phadbuX0BA4k8U5qtvMSQQGGmaJqcQ==}
+    cpu: [riscv64]
+    os: [linux]
+    libc: [glibc]
+
+  '@unrs/resolver-binding-linux-riscv64-musl@1.11.1':
+    resolution: {integrity: sha512-mJ5vuDaIZ+l/acv01sHoXfpnyrNKOk/3aDoEdLO/Xtn9HuZlDD6jKxHlkN8ZhWyLJsRBxfv9GYM2utQ1SChKew==}
+    cpu: [riscv64]
+    os: [linux]
+    libc: [musl]
+
+  '@unrs/resolver-binding-linux-s390x-gnu@1.11.1':
+    resolution: {integrity: sha512-kELo8ebBVtb9sA7rMe1Cph4QHreByhaZ2QEADd9NzIQsYNQpt9UkM9iqr2lhGr5afh885d/cB5QeTXSbZHTYPg==}
+    cpu: [s390x]
+    os: [linux]
+    libc: [glibc]
+
+  '@unrs/resolver-binding-linux-x64-gnu@1.11.1':
+    resolution: {integrity: sha512-C3ZAHugKgovV5YvAMsxhq0gtXuwESUKc5MhEtjBpLoHPLYM+iuwSj3lflFwK3DPm68660rZ7G8BMcwSro7hD5w==}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  '@unrs/resolver-binding-linux-x64-musl@1.11.1':
+    resolution: {integrity: sha512-rV0YSoyhK2nZ4vEswT/QwqzqQXw5I6CjoaYMOX0TqBlWhojUf8P94mvI7nuJTeaCkkds3QE4+zS8Ko+GdXuZtA==}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  '@unrs/resolver-binding-wasm32-wasi@1.11.1':
+    resolution: {integrity: sha512-5u4RkfxJm+Ng7IWgkzi3qrFOvLvQYnPBmjmZQ8+szTK/b31fQCnleNl1GgEt7nIsZRIf5PLhPwT0WM+q45x/UQ==}
+    engines: {node: '>=14.0.0'}
+    cpu: [wasm32]
+
+  '@unrs/resolver-binding-win32-arm64-msvc@1.11.1':
+    resolution: {integrity: sha512-nRcz5Il4ln0kMhfL8S3hLkxI85BXs3o8EYoattsJNdsX4YUU89iOkVn7g0VHSRxFuVMdM4Q1jEpIId1Ihim/Uw==}
+    cpu: [arm64]
+    os: [win32]
+
+  '@unrs/resolver-binding-win32-ia32-msvc@1.11.1':
+    resolution: {integrity: sha512-DCEI6t5i1NmAZp6pFonpD5m7i6aFrpofcp4LA2i8IIq60Jyo28hamKBxNrZcyOwVOZkgsRp9O2sXWBWP8MnvIQ==}
+    cpu: [ia32]
+    os: [win32]
+
+  '@unrs/resolver-binding-win32-x64-msvc@1.11.1':
+    resolution: {integrity: sha512-lrW200hZdbfRtztbygyaq/6jP6AKE8qQN2KvPcJ+x7wiD038YtnYtZ82IMNJ69GJibV7bwL3y9FgK+5w/pYt6g==}
+    cpu: [x64]
+    os: [win32]
+
+  '@vitejs/plugin-react@6.0.1':
+    resolution: {integrity: sha512-l9X/E3cDb+xY3SWzlG1MOGt2usfEHGMNIaegaUGFsLkb3RCn/k8/TOXBcab+OndDI4TBtktT8/9BwwW8Vi9KUQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    peerDependencies:
+      '@rolldown/plugin-babel': ^0.1.7 || ^0.2.0
+      babel-plugin-react-compiler: ^1.0.0
+      vite: ^8.0.0
+    peerDependenciesMeta:
+      '@rolldown/plugin-babel':
+        optional: true
+      babel-plugin-react-compiler:
+        optional: true
+
+  accepts@1.3.8:
+    resolution: {integrity: sha512-PYAthTa2m2VKxuvSD3DPC/Gy+U+sOA1LAuT8mkmRuvw+NACSaeXEQ+NHcVF7rONl6qcaxV3Uuemwawk+7+SJLw==}
+    engines: {node: '>= 0.6'}
+
+  accepts@2.0.0:
+    resolution: {integrity: sha512-5cvg6CtKwfgdmVqY1WIiXKc3Q1bkRqGLi+2W/6ao+6Y7gu/RCwRuAhGEzh5B4KlszSuTLgZYuqFqo5bImjNKng==}
+    engines: {node: '>= 0.6'}
+
+  acorn-jsx@5.3.2:
+    resolution: {integrity: sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ==}
+    peerDependencies:
+      acorn: ^6.0.0 || ^7.0.0 || ^8.0.0
+
+  acorn-walk@8.3.5:
+    resolution: {integrity: sha512-HEHNfbars9v4pgpW6SO1KSPkfoS0xVOM/9UzkJltjlsHZmJasxg8aXkuZa7SMf8vKGIBhpUsPluQSqhJFCqebw==}
+    engines: {node: '>=0.4.0'}
+
+  acorn@8.16.0:
+    resolution: {integrity: sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw==}
+    engines: {node: '>=0.4.0'}
+    hasBin: true
+
+  agent-base@7.1.4:
+    resolution: {integrity: sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ==}
+    engines: {node: '>= 14'}
+
+  ajv-formats@3.0.1:
+    resolution: {integrity: sha512-8iUql50EUR+uUcdRQ3HDqa6EVyo3docL8g5WJ3FNcWmu62IbkGUue/pEyLBW8VGKKucTPgqeks4fIU1DA4yowQ==}
+    peerDependencies:
+      ajv: ^8.0.0
+    peerDependenciesMeta:
+      ajv:
+        optional: true
+
+  ajv@6.15.0:
+    resolution: {integrity: sha512-fgFx7Hfoq60ytK2c7DhnF8jIvzYgOMxfugjLOSMHjLIPgenqa7S7oaagATUq99mV6IYvN2tRmC0wnTYX6iPbMw==}
+
+  ajv@8.20.0:
+    resolution: {integrity: sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA==}
+
+  ansi-escapes@7.3.0:
+    resolution: {integrity: sha512-BvU8nYgGQBxcmMuEeUEmNTvrMVjJNSH7RgW24vXexN4Ven6qCvy4TntnvlnwnMLTVlcRQQdbRY8NKnaIoeWDNg==}
+    engines: {node: '>=18'}
+
+  ansi-regex@5.0.1:
+    resolution: {integrity: sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==}
+    engines: {node: '>=8'}
+
+  ansi-regex@6.2.2:
+    resolution: {integrity: sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg==}
+    engines: {node: '>=12'}
+
+  ansi-styles@4.3.0:
+    resolution: {integrity: sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==}
+    engines: {node: '>=8'}
+
+  ansi-styles@6.2.3:
+    resolution: {integrity: sha512-4Dj6M28JB+oAH8kFkTLUo+a2jwOFkuqb3yucU0CANcRRUbxS0cP0nZYCGjcc3BNXwRIsUVmDGgzawme7zvJHvg==}
+    engines: {node: '>=12'}
+
+  anymatch@3.1.3:
+    resolution: {integrity: sha512-KMReFUr0B4t+D+OBkjR3KYqvocp2XaSzO55UcB6mgQMd3KbcE+mWTyvVV7D/zsdEbNnV6acZUutkiHQXvTr1Rw==}
+    engines: {node: '>= 8'}
+
+  arg@4.1.3:
+    resolution: {integrity: sha512-58S9QDqG0Xx27YwPSt9fJxivjYl432YCwfDMfZ+71RAqUrZef7LrKQZ3LHLOwCS4FLNBplP533Zx895SeOCHvA==}
+
+  argparse@1.0.10:
+    resolution: {integrity: sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==}
+
+  argparse@2.0.1:
+    resolution: {integrity: sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==}
+
+  aria-hidden@1.2.6:
+    resolution: {integrity: sha512-ik3ZgC9dY/lYVVM++OISsaYDeg1tb0VtP5uL3ouh1koGOaUMDPpbFIei4JkFimWUFPn90sbMNMXQAIVOlnYKJA==}
+    engines: {node: '>=10'}
+
+  array-flatten@1.1.1:
+    resolution: {integrity: sha512-PCVAQswWemu6UdxsDFFX/+gVeYqKAod3D3UVm91jHwynguOwAvYPhx8nNlM++NqRcK6CxxpUafjmhIdKiHibqg==}
+
+  ast-types@0.16.1:
+    resolution: {integrity: sha512-6t10qk83GOG8p0vKmaCr8eiilZwO171AvbROMtvvNiwrTly62t+7XkA8RdIIVbpMhCASAsxgAzdRSwh6nw/5Dg==}
+    engines: {node: '>=4'}
+
+  bail@2.0.2:
+    resolution: {integrity: sha512-0xO6mYd7JB2YesxDKplafRpsiOzPt9V02ddPCLbY1xYGPOX24NTyN50qnUxgCPcSoYMhKpAuBTjQoRZCAkUDRw==}
+
+  balanced-match@4.0.4:
+    resolution: {integrity: sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==}
+    engines: {node: 18 || 20 || >=22}
+
+  baseline-browser-mapping@2.10.29:
+    resolution: {integrity: sha512-Asa2krT+XTPZINCS+2QcyS8WTkObE77RwkydwF7h6DmnKqbvlalz93m/dnphUyCa6SWSP51VgtEUf2FN+gelFQ==}
+    engines: {node: '>=6.0.0'}
+    hasBin: true
+
+  baseline-browser-mapping@2.10.33:
+    resolution: {integrity: sha512-bA6+tcSLpz2tIEdDXZPpPTIuxBcC4+w6SieaYyfigIa4h8GlFxbA17v22Vx3JUtuZQj9SgOsnbK+aTBzyDyEuw==}
+    engines: {node: '>=6.0.0'}
+    hasBin: true
+
+  binary-extensions@2.3.0:
+    resolution: {integrity: sha512-Ceh+7ox5qe7LJuLHoY0feh3pHuUDHAcRUeyL2VYghZwfpkNIy/+8Ocg0a3UuSoYzavmylwuLWQOf3hl0jjMMIw==}
+    engines: {node: '>=8'}
+
+  body-parser@1.20.5:
+    resolution: {integrity: sha512-3grm+/2tUOvu2cjJkvsIxrv/wVpfXQW4PsQHYm7yk4vfpu7Ekl6nEsYBoJUL6qDwZUx8wUhQ8tR2qz+ad9c9OA==}
+    engines: {node: '>= 0.8', npm: 1.2.8000 || >= 1.4.16}
+
+  body-parser@2.2.2:
+    resolution: {integrity: sha512-oP5VkATKlNwcgvxi0vM0p/D3n2C3EReYVX+DNYs5TjZFn/oQt2j+4sVJtSMr18pdRr8wjTcBl6LoV+FUwzPmNA==}
+    engines: {node: '>=18'}
+
+  brace-expansion@5.0.6:
+    resolution: {integrity: sha512-kLpxurY4Z4r9sgMsyG0Z9uzsBlgiU/EFKhj/h91/8yHu0edo7XuixOIH3VcJ8kkxs6/jPzoI6U9Vj3WqbMQ94g==}
+    engines: {node: 18 || 20 || >=22}
+
+  braces@3.0.3:
+    resolution: {integrity: sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA==}
+    engines: {node: '>=8'}
+
+  browserslist@4.28.2:
+    resolution: {integrity: sha512-48xSriZYYg+8qXna9kwqjIVzuQxi+KYWp2+5nCYnYKPTr0LvD89Jqk2Or5ogxz0NUMfIjhh2lIUX/LyX9B4oIg==}
+    engines: {node: ^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7}
+    hasBin: true
+
+  bundle-name@4.1.0:
+    resolution: {integrity: sha512-tjwM5exMg6BGRI+kNmTntNsvdZS1X8BFYS6tnJ2hdH0kVxM6/eVZ2xy+FqStSWvYmtfFMDLIxurorHwDKfDz5Q==}
+    engines: {node: '>=18'}
+
+  bytes@3.1.2:
+    resolution: {integrity: sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg==}
+    engines: {node: '>= 0.8'}
+
+  call-bind-apply-helpers@1.0.2:
+    resolution: {integrity: sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ==}
+    engines: {node: '>= 0.4'}
+
+  call-bound@1.0.4:
+    resolution: {integrity: sha512-+ys997U96po4Kx/ABpBCqhA9EuxJaQWDQg7295H4hBphv3IZg0boBKuwYpt4YXp6MZ5AmZQnU/tyMTlRpaSejg==}
+    engines: {node: '>= 0.4'}
+
+  callsites@3.1.0:
+    resolution: {integrity: sha512-P8BjAsXvZS+VIDUI11hHCQEv74YT67YUi5JJFNWIqL235sBmjX4+qx9Muvls5ivyNENctx46xQLQ3aTuE7ssaQ==}
+    engines: {node: '>=6'}
+
+  camelcase@6.3.0:
+    resolution: {integrity: sha512-Gmy6FhYlCY7uOElZUSbxo2UCDH8owEk996gkbrpsgGtrJLM3J7jGxl9Ic7Qwwj4ivOE5AWZWRMecDdF7hqGjFA==}
+    engines: {node: '>=10'}
+
+  caniuse-lite@1.0.30001792:
+    resolution: {integrity: sha512-hVLMUZFgR4JJ6ACt1uEESvQN1/dBVqPAKY0hgrV70eN3391K6juAfTjKZLKvOMsx8PxA7gsY1/tLMMTcfFLLpw==}
+
+  caniuse-lite@1.0.30001793:
+    resolution: {integrity: sha512-iwSsYWaCOoh26cV8NwNRViHlrfUvYsHDfRVcbtmw0Kg6PJIZZXwMkj1442FYLBGkeUf1juAsU3DTfxW579mrPA==}
+
+  ccount@2.0.1:
+    resolution: {integrity: sha512-eyrF0jiFpY+3drT6383f1qhkbGsLSifNAjA61IUjZjmLCWjItY6LB9ft9YhoDgwfmclB2zhu51Lc7+95b8NRAg==}
+
+  chalk@4.1.2:
+    resolution: {integrity: sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==}
+    engines: {node: '>=10'}
+
+  chalk@5.6.2:
+    resolution: {integrity: sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA==}
+    engines: {node: ^12.17.0 || ^14.13 || >=16.0.0}
+
+  character-entities-html4@2.1.0:
+    resolution: {integrity: sha512-1v7fgQRj6hnSwFpq1Eu0ynr/CDEw0rXo2B61qXrLNdHZmPKgb7fqS1a2JwF0rISo9q77jDI8VMEHoApn8qDoZA==}
+
+  character-entities-legacy@3.0.0:
+    resolution: {integrity: sha512-RpPp0asT/6ufRm//AJVwpViZbGM/MkjQFxJccQRHmISF/22NBtsHqAWmL+/pmkPWoIUJdWyeVleTl1wydHATVQ==}
+
+  character-entities@2.0.2:
+    resolution: {integrity: sha512-shx7oQ0Awen/BRIdkjkvz54PnEEI/EjwXDSIZp86/KKdbafHh1Df/RYGBhn4hbe2+uKC9FnT5UCEdyPz3ai9hQ==}
+
+  character-reference-invalid@2.0.1:
+    resolution: {integrity: sha512-iBZ4F4wRbyORVsu0jPV7gXkOsGYjGHPmAyv+HiHG8gi5PtC9KI2j1+v8/tlibRvjoWX027ypmG/n0HtO5t7unw==}
+
+  chokidar@3.6.0:
+    resolution: {integrity: sha512-7VT13fmjotKpGipCW9JEQAusEPE+Ei8nl6/g4FBAmIm0GOOLMua9NDDo/DWp0ZAxCr3cPq5ZpBqmPAQgDda2Pw==}
+    engines: {node: '>= 8.10.0'}
+
+  class-variance-authority@0.7.1:
+    resolution: {integrity: sha512-Ka+9Trutv7G8M6WT6SeiRWz792K5qEqIGEGzXKhAE6xOWAY6pPH8U+9IY3oCMv6kqTmLsv7Xh/2w2RigkePMsg==}
+
+  classnames@2.5.1:
+    resolution: {integrity: sha512-saHYOzhIQs6wy2sVxTM6bUDsQO4F50V9RQ22qBpEdCW+I+/Wmke2HOl6lS6dTpdxVhb88/I6+Hs+438c3lfUow==}
+
+  cli-cursor@5.0.0:
+    resolution: {integrity: sha512-aCj4O5wKyszjMmDT4tZj93kxyydN/K5zPWSCe6/0AV/AA1pqe5ZBIw0a2ZfPQV7lL5/yb5HsUreJ6UFAF1tEQw==}
+    engines: {node: '>=18'}
+
+  cli-spinners@2.9.2:
+    resolution: {integrity: sha512-ywqV+5MmyL4E7ybXgKys4DugZbX0FC6LnwrhjuykIjnK9k8OQacQ7axGKnjDXWNhns0xot3bZI5h55H8yo9cJg==}
+    engines: {node: '>=6'}
+
+  cli-truncate@5.2.0:
+    resolution: {integrity: sha512-xRwvIOMGrfOAnM1JYtqQImuaNtDEv9v6oIYAs4LIHwTiKee8uwvIi363igssOC0O5U04i4AlENs79LQLu9tEMw==}
+    engines: {node: '>=20'}
+
+  cli-width@4.1.0:
+    resolution: {integrity: sha512-ouuZd4/dm2Sw5Gmqy6bGyNNNe1qt9RpmxveLSO7KcgsTnU7RXfsw+/bukWGo1abgBiMAic068rclZsO4IWmmxQ==}
+    engines: {node: '>= 12'}
+
+  client-only@0.0.1:
+    resolution: {integrity: sha512-IV3Ou0jSMzZrd3pZ48nLkT9DA7Ag1pnPzaiQhpW7c3RbcqqzvzzVu+L8gfqMp/8IM2MQtSiqaCxrrcfu8I8rMA==}
+
+  cliui@8.0.1:
+    resolution: {integrity: sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ==}
+    engines: {node: '>=12'}
+
+  clsx@2.1.1:
+    resolution: {integrity: sha512-eYm0QWBtUrBWZWG0d386OGAw16Z995PiOVo2B7bjWSbHedGl5e0ZWaq65kOGgUSNesEIDkB9ISbTg/JK9dhCZA==}
+    engines: {node: '>=6'}
+
+  code-block-writer@13.0.3:
+    resolution: {integrity: sha512-Oofo0pq3IKnsFtuHqSF7TqBfr71aeyZDVJ0HpmqB7FBM2qEigL0iPONSCZSO9pE9dZTAxANe5XHG9Uy0YMv8cg==}
+
+  color-convert@2.0.1:
+    resolution: {integrity: sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==}
+    engines: {node: '>=7.0.0'}
+
+  color-name@1.1.4:
+    resolution: {integrity: sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==}
+
+  comma-separated-tokens@2.0.3:
+    resolution: {integrity: sha512-Fu4hJdvzeylCfQPp9SGWidpzrMs7tTrlu6Vb8XGaRGck8QSNZJJp538Wrb60Lax4fPwR64ViY468OIUTbRlGZg==}
+
+  commander@11.1.0:
+    resolution: {integrity: sha512-yPVavfyCcRhmorC7rWlkHn15b4wDVgVmBA7kV4QVBsF7kv/9TKJAbAXVTxvTnwP8HHKjRCJDClKbciiYS7p0DQ==}
+    engines: {node: '>=16'}
+
+  commander@14.0.3:
+    resolution: {integrity: sha512-H+y0Jo/T1RZ9qPP4Eh1pkcQcLRglraJaSLoyOtHxu6AapkjWVCy2Sit1QQ4x3Dng8qDlSsZEet7g5Pq06MvTgw==}
+    engines: {node: '>=20'}
+
+  comment-parser@1.4.6:
+    resolution: {integrity: sha512-ObxuY6vnbWTN6Od72xfwN9DbzC7Y2vv8u1Soi9ahRKL37gb6y1qk6/dgjs+3JWuXJHWvsg3BXIwzd/rkmAwavg==}
+    engines: {node: '>= 12.0.0'}
+
+  concurrently@8.2.2:
+    resolution: {integrity: sha512-1dP4gpXFhei8IOtlXRE/T/4H88ElHgTiUzh71YUmtjTEHMSRS2Z/fgOxHSxxusGHogsRfxNq1vyAwxSC+EVyDg==}
+    engines: {node: ^14.13.0 || >=16.0.0}
+    hasBin: true
+
+  content-disposition@0.5.4:
+    resolution: {integrity: sha512-FveZTNuGw04cxlAiWbzi6zTAL/lhehaWbTtgluJh4/E95DqMwTmha3KZN1aAWA8cFIhHzMZUvLevkw5Rqk+tSQ==}
+    engines: {node: '>= 0.6'}
+
+  content-disposition@1.1.0:
+    resolution: {integrity: sha512-5jRCH9Z/+DRP7rkvY83B+yGIGX96OYdJmzngqnw2SBSxqCFPd0w2km3s5iawpGX8krnwSGmF0FW5Nhr0Hfai3g==}
+    engines: {node: '>=18'}
+
+  content-type@1.0.5:
+    resolution: {integrity: sha512-nTjqfcBFEipKdXCv4YDQWCfmcLZKm81ldF0pAopTvyrFGVbcR6P/VAAd5G7N+0tTr8QqiU0tFadD6FK4NtJwOA==}
+    engines: {node: '>= 0.6'}
+
+  content-type@2.0.0:
+    resolution: {integrity: sha512-j/O/d7GcZCyNl7/hwZAb606rzqkyvaDctLmckbxLzHvFBzTJHuGEdodATcP3yIRoDrLHkIATJuvzbFlp/ki2cQ==}
+    engines: {node: '>=18'}
+
+  convert-source-map@2.0.0:
+    resolution: {integrity: sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==}
+
+  cookie-signature@1.0.7:
+    resolution: {integrity: sha512-NXdYc3dLr47pBkpUCHtKSwIOQXLVn8dZEuywboCOJY/osA0wFSLlSawr3KN8qXJEyX66FcONTH8EIlVuK0yyFA==}
+
+  cookie-signature@1.2.2:
+    resolution: {integrity: sha512-D76uU73ulSXrD1UXF4KE2TMxVVwhsnCgfAyTg9k8P6KGZjlXKrOLe4dJQKI3Bxi5wjesZoFXJWElNWBjPZMbhg==}
+    engines: {node: '>=6.6.0'}
+
+  cookie@0.7.2:
+    resolution: {integrity: sha512-yki5XnKuf750l50uGTllt6kKILY4nQ1eNIQatoXEByZ5dWgnKqbnqmTrBE5B4N7lrMJKQ2ytWMiTO2o0v6Ew/w==}
+    engines: {node: '>= 0.6'}
+
+  cookie@1.1.1:
+    resolution: {integrity: sha512-ei8Aos7ja0weRpFzJnEA9UHJ/7XQmqglbRwnf2ATjcB9Wq874VKH9kfjjirM6UhU2/E5fFYadylyhFldcqSidQ==}
+    engines: {node: '>=18'}
+
+  cors@2.8.6:
+    resolution: {integrity: sha512-tJtZBBHA6vjIAaF6EnIaq6laBBP9aq/Y3ouVJjEfoHbRBcHBAHYcMh/w8LDrk2PvIMMq8gmopa5D4V8RmbrxGw==}
+    engines: {node: '>= 0.10'}
+
+  cosmiconfig@8.3.6:
+    resolution: {integrity: sha512-kcZ6+W5QzcJ3P1Mt+83OUv/oHFqZHIx8DuxG6eZ5RGMERoLqp4BuGjhHLYGK+Kf5XVkQvqBSmAy/nGWN3qDgEA==}
+    engines: {node: '>=14'}
+    peerDependencies:
+      typescript: '>=4.9.5'
+    peerDependenciesMeta:
+      typescript:
+        optional: true
+
+  cosmiconfig@9.0.1:
+    resolution: {integrity: sha512-hr4ihw+DBqcvrsEDioRO31Z17x71pUYoNe/4h6Z0wB72p7MU7/9gH8Q3s12NFhHPfYBBOV3qyfUxmr/Yn3shnQ==}
+    engines: {node: '>=14'}
+    peerDependencies:
+      typescript: '>=4.9.5'
+    peerDependenciesMeta:
+      typescript:
+        optional: true
+
+  create-require@1.1.1:
+    resolution: {integrity: sha512-dcKFX3jn0MpIaXjisoRvexIJVEKzaq7z2rZKxf+MSr9TkdmHmsU4m2lcLojrj/FHl8mk5VxMmYA+ftRkP/3oKQ==}
+
+  cron-parser@5.5.0:
+    resolution: {integrity: sha512-oML4lKUXxizYswqmxuOCpgFS8BNUJpIu6k/2HVHyaL8Ynnf3wdf9tkns0yRdJLSIjkJ+b0DXHMZEHGpMwjnPww==}
+    engines: {node: '>=18'}
+
+  cross-spawn@7.0.6:
+    resolution: {integrity: sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==}
+    engines: {node: '>= 8'}
+
+  cssesc@3.0.0:
+    resolution: {integrity: sha512-/Tb/JcjK111nNScGob5MNtsntNM1aCNUDipB/TkwZFhyDrrE47SOx/18wF2bbjgc3ZzCSKW1T5nt5EbFoAz/Vg==}
+    engines: {node: '>=4'}
+    hasBin: true
+
+  csstype@3.2.3:
+    resolution: {integrity: sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==}
+
+  data-uri-to-buffer@4.0.1:
+    resolution: {integrity: sha512-0R9ikRb668HB7QDxT1vkpuUBtqc53YyAwMwGeUFKRojY/NWKvdZ+9UYtRfGmhqNbRkTSVpMbmyhXipFFv2cb/A==}
+    engines: {node: '>= 12'}
+
+  date-fns@2.30.0:
+    resolution: {integrity: sha512-fnULvOpxnC5/Vg3NCiWelDsLiUc9bRwAPs/+LfTLNvetFCtCTN+yQz15C/fs4AwX1R9K5GLtLfn8QW+dWisaAw==}
+    engines: {node: '>=0.11'}
+
+  date-fns@4.1.0:
+    resolution: {integrity: sha512-Ukq0owbQXxa/U3EGtsdVBkR1w7KOQ5gIBqdH2hkvknzZPYvBxb/aa6E8L7tmjFtkwZBu3UXBbjIgPo/Ez4xaNg==}
+
+  debug@2.6.9:
+    resolution: {integrity: sha512-bC7ElrdJaJnPbAP+1EotYvqZsb3ecl5wi6Bfi6BJTUcNowp6cvspg0jXznRTKDjm/E7AdgFBVeAPVMNcKGsHMA==}
+    peerDependencies:
+      supports-color: '*'
+    peerDependenciesMeta:
+      supports-color:
+        optional: true
+
+  debug@4.4.3:
+    resolution: {integrity: sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==}
+    engines: {node: '>=6.0'}
+    peerDependencies:
+      supports-color: '*'
+    peerDependenciesMeta:
+      supports-color:
+        optional: true
+
+  decode-named-character-reference@1.3.0:
+    resolution: {integrity: sha512-GtpQYB283KrPp6nRw50q3U9/VfOutZOe103qlN7BPP6Ad27xYnOIWv4lPzo8HCAL+mMZofJ9KEy30fq6MfaK6Q==}
+
+  dedent@1.7.2:
+    resolution: {integrity: sha512-WzMx3mW98SN+zn3hgemf4OzdmyNhhhKz5Ay0pUfQiMQ3e1g+xmTJWp/pKdwKVXhdSkAEGIIzqeuWrL3mV/AXbA==}
+    peerDependencies:
+      babel-plugin-macros: ^3.1.0
+    peerDependenciesMeta:
+      babel-plugin-macros:
+        optional: true
+
+  deep-is@0.1.4:
+    resolution: {integrity: sha512-oIPzksmTg4/MriiaYGO+okXDT7ztn/w3Eptv/+gSIdMdKsJo0u4CfYNFJPy+4SKMuCqGw2wxnA+URMg3t8a/bQ==}
+
+  deepmerge@4.3.1:
+    resolution: {integrity: sha512-3sUqbMEc77XqpdNO7FRyRog+eW3ph+GYCbj+rK+uYyRMuwsVy0rMiVtPn+QJlKFvWP/1PYpapqYn0Me2knFn+A==}
+    engines: {node: '>=0.10.0'}
+
+  default-browser-id@5.0.1:
+    resolution: {integrity: sha512-x1VCxdX4t+8wVfd1so/9w+vQ4vx7lKd2Qp5tDRutErwmR85OgmfX7RlLRMWafRMY7hbEiXIbudNrjOAPa/hL8Q==}
+    engines: {node: '>=18'}
+
+  default-browser@5.5.0:
+    resolution: {integrity: sha512-H9LMLr5zwIbSxrmvikGuI/5KGhZ8E2zH3stkMgM5LpOWDutGM2JZaj460Udnf1a+946zc7YBgrqEWwbk7zHvGw==}
+    engines: {node: '>=18'}
+
+  define-lazy-prop@3.0.0:
+    resolution: {integrity: sha512-N+MeXYoqr3pOgn8xfyRPREN7gHakLYjhsHhWGT3fWAiL4IkAt0iDw14QiiEm2bE30c5XX5q0FtAA3CK5f9/BUg==}
+    engines: {node: '>=12'}
+
+  depd@2.0.0:
+    resolution: {integrity: sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw==}
+    engines: {node: '>= 0.8'}
+
+  dequal@2.0.3:
+    resolution: {integrity: sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA==}
+    engines: {node: '>=6'}
+
+  destroy@1.2.0:
+    resolution: {integrity: sha512-2sJGJTaXIIaR1w4iJSNoN0hnMY7Gpc/n8D4qSCJw8QqFWXf7cuAgnEHxBpweaVcPevC2l3KpjYCx3NypQQgaJg==}
+    engines: {node: '>= 0.8', npm: 1.2.8000 || >= 1.4.16}
+
+  detect-libc@2.1.2:
+    resolution: {integrity: sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==}
+    engines: {node: '>=8'}
+
+  detect-node-es@1.1.0:
+    resolution: {integrity: sha512-ypdmJU/TbBby2Dxibuv7ZLW3Bs1QEmM7nHjEANfohJLvE0XVujisn1qPJcZxg+qDucsr+bP6fLD1rPS3AhJ7EQ==}
+
+  devlop@1.1.0:
+    resolution: {integrity: sha512-RWmIqhcFf1lRYBvNmr7qTNuyCt/7/ns2jbpp1+PalgE/rDQcBT0fioSMUpJ93irlUhC5hrg4cYqe6U+0ImW0rA==}
+
+  diff-match-patch@1.0.5:
+    resolution: {integrity: sha512-IayShXAgj/QMXgB0IWmKx+rOPuGMhqm5w6jvFxmVenXKIzRqTAAsbBPT3kWQeGANj3jGgvcvv4yK6SxqYmikgw==}
+
+  diff@4.0.4:
+    resolution: {integrity: sha512-X07nttJQkwkfKfvTPG/KSnE2OMdcUCao6+eXF3wmnIQRn2aPAHH3VxDbDOdegkd6JbPsXqShpvEOHfAT+nCNwQ==}
+    engines: {node: '>=0.3.1'}
+
+  diff@5.2.2:
+    resolution: {integrity: sha512-vtcDfH3TOjP8UekytvnHH1o1P4FcUdt4eQ1Y+Abap1tk/OB2MWQvcwS2ClCd1zuIhc3JKOx6p3kod8Vfys3E+A==}
+    engines: {node: '>=0.3.1'}
+
+  diff@8.0.4:
+    resolution: {integrity: sha512-DPi0FmjiSU5EvQV0++GFDOJ9ASQUVFh5kD+OzOnYdi7n3Wpm9hWWGfB/O2blfHcMVTL5WkQXSnRiK9makhrcnw==}
+    engines: {node: '>=0.3.1'}
+
+  dot-case@3.0.4:
+    resolution: {integrity: sha512-Kv5nKlh6yRrdrGvxeJ2e5y2eRUpkUosIW4A2AS38zwSz27zu7ufDwQPi5Jhs3XAlGNetl3bmnGhQsMtkKJnj3w==}
+
+  dotenv@17.4.2:
+    resolution: {integrity: sha512-nI4U3TottKAcAD9LLud4Cb7b2QztQMUEfHbvhTH09bqXTxnSie8WnjPALV/WMCrJZ6UV/qHJ6L03OqO3LcdYZw==}
+    engines: {node: '>=12'}
+
+  dunder-proto@1.0.1:
+    resolution: {integrity: sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==}
+    engines: {node: '>= 0.4'}
+
+  eciesjs@0.4.18:
+    resolution: {integrity: sha512-wG99Zcfcys9fZux7Cft8BAX/YrOJLJSZ3jyYPfhZHqN2E+Ffx+QXBDsv3gubEgPtV6dTzJMSQUwk1H98/t/0wQ==}
+    engines: {bun: '>=1', deno: '>=2', node: '>=16'}
+
+  ee-first@1.1.1:
+    resolution: {integrity: sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow==}
+
+  electron-to-chromium@1.5.355:
+    resolution: {integrity: sha512-LUPZhKzZPYSPme1jEYohpkA+ybYCJztr1quAdBd7E7h3+VOBVcKkwwtBJu41nrjawrRzfb8mtMfzWozoaK0ZIQ==}
+
+  emoji-regex@10.6.0:
+    resolution: {integrity: sha512-toUI84YS5YmxW219erniWD0CIVOo46xGKColeNQRgOzDorgBi1v4D71/OFzgD9GO2UGKIv1C3Sp8DAn0+j5w7A==}
+
+  emoji-regex@8.0.0:
+    resolution: {integrity: sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==}
+
+  encodeurl@2.0.0:
+    resolution: {integrity: sha512-Q0n9HRi4m6JuGIV1eFlmvJB7ZEVxu93IrMyiMsGC0lrMJMWzRgx6WGquyfQgZVb31vhGgXnfmPNNXmxnOkRBrg==}
+    engines: {node: '>= 0.8'}
+
+  enhanced-resolve@5.21.3:
+    resolution: {integrity: sha512-QyL119InA+XXEkNLNTPCXPugSvOfhwv0JOlGNzvxs0hZaiHLNvXSpudUWsOlsXGWJh8G6ckCScEkVHfX3kw/2Q==}
+    engines: {node: '>=10.13.0'}
+
+  entities@4.5.0:
+    resolution: {integrity: sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==}
+    engines: {node: '>=0.12'}
+
+  env-paths@2.2.1:
+    resolution: {integrity: sha512-+h1lkLKhZMTYjog1VEpJNG7NZJWcuc2DDk/qsqSTRRCOXiLjeQ1d1/udrUGhqMxUgAlwKNZ0cf2uqan5GLuS2A==}
+    engines: {node: '>=6'}
+
+  environment@1.1.0:
+    resolution: {integrity: sha512-xUtoPkMggbz0MPyPiIWr1Kp4aeWJjDZ6SMvURhimjdZgsRuDplF5/s9hcgGhyXMhs+6vpnuoiZ2kFiu3FMnS8Q==}
+    engines: {node: '>=18'}
+
+  error-ex@1.3.4:
+    resolution: {integrity: sha512-sqQamAnR14VgCr1A618A3sGrygcpK+HEbenA/HiEAkkUwcZIIB/tgWqHFxWgOyDh4nB4JCRimh79dR5Ywc9MDQ==}
+
+  es-define-property@1.0.1:
+    resolution: {integrity: sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g==}
+    engines: {node: '>= 0.4'}
+
+  es-errors@1.3.0:
+    resolution: {integrity: sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw==}
+    engines: {node: '>= 0.4'}
+
+  es-object-atoms@1.1.1:
+    resolution: {integrity: sha512-FGgH2h8zKNim9ljj7dankFPcICIK9Cp5bm+c2gQSYePhpaG5+esrLODihIorn+Pe6FGJzWhXQotPv73jTaldXA==}
+    engines: {node: '>= 0.4'}
+
+  escalade@3.2.0:
+    resolution: {integrity: sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==}
+    engines: {node: '>=6'}
+
+  escape-html@1.0.3:
+    resolution: {integrity: sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow==}
+
+  escape-string-regexp@4.0.0:
+    resolution: {integrity: sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA==}
+    engines: {node: '>=10'}
+
+  escape-string-regexp@5.0.0:
+    resolution: {integrity: sha512-/veY75JbMK4j1yjvuUxuVsiS/hr/4iHs9FTT6cgTexxdE0Ly/glccBAkloH/DofkjRbZU3bnoj38mOmhkZ0lHw==}
+    engines: {node: '>=12'}
+
+  eslint-config-prettier@10.1.8:
+    resolution: {integrity: sha512-82GZUjRS0p/jganf6q1rEO25VSoHH0hKPCTrgillPjdI/3bgBhAE1QzHrHTizjpRvy6pGAvKjDJtk2pF9NDq8w==}
+    hasBin: true
+    peerDependencies:
+      eslint: '>=7.0.0'
+
+  eslint-import-context@0.1.9:
+    resolution: {integrity: sha512-K9Hb+yRaGAGUbwjhFNHvSmmkZs9+zbuoe3kFQ4V1wYjrepUFYM2dZAfNtjbbj3qsPfUfsA68Bx/ICWQMi+C8Eg==}
+    engines: {node: ^12.20.0 || ^14.18.0 || >=16.0.0}
+    peerDependencies:
+      unrs-resolver: ^1.0.0
+    peerDependenciesMeta:
+      unrs-resolver:
+        optional: true
+
+  eslint-plugin-import-x@4.16.2:
+    resolution: {integrity: sha512-rM9K8UBHcWKpzQzStn1YRN2T5NvdeIfSVoKu/lKF41znQXHAUcBbYXe5wd6GNjZjTrP7viQ49n1D83x/2gYgIw==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      '@typescript-eslint/utils': ^8.56.0
+      eslint: ^8.57.0 || ^9.0.0 || ^10.0.0
+      eslint-import-resolver-node: '*'
+    peerDependenciesMeta:
+      '@typescript-eslint/utils':
+        optional: true
+      eslint-import-resolver-node:
+        optional: true
+
+  eslint-plugin-prettier@5.5.5:
+    resolution: {integrity: sha512-hscXkbqUZ2sPithAuLm5MXL+Wph+U7wHngPBv9OMWwlP8iaflyxpjTYZkmdgB4/vPIhemRlBEoLrH7UC1n7aUw==}
+    engines: {node: ^14.18.0 || >=16.0.0}
+    peerDependencies:
+      '@types/eslint': '>=8.0.0'
+      eslint: '>=8.0.0'
+      eslint-config-prettier: '>= 7.0.0 <10.0.0 || >=10.1.0'
+      prettier: '>=3.0.0'
+    peerDependenciesMeta:
+      '@types/eslint':
+        optional: true
+      eslint-config-prettier:
+        optional: true
+
+  eslint-plugin-react-hooks@7.1.1:
+    resolution: {integrity: sha512-f2I7Gw6JbvCexzIInuSbZpfdQ44D7iqdWX01FKLvrPgqxoE7oMj8clOfto8U6vYiz4yd5oKu39rRSVOe1zRu0g==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      eslint: ^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0-0 || ^9.0.0 || ^10.0.0
+
+  eslint-plugin-react-refresh@0.5.2:
+    resolution: {integrity: sha512-hmgTH57GfzoTFjVN0yBwTggnsVUF2tcqi7RJZHqi9lIezSs4eFyAMktA68YD4r5kNw1mxyY4dmkyoFDb3FIqrA==}
+    peerDependencies:
+      eslint: ^9 || ^10
+
+  eslint-scope@9.1.2:
+    resolution: {integrity: sha512-xS90H51cKw0jltxmvmHy2Iai1LIqrfbw57b79w/J7MfvDfkIkFZ+kj6zC3BjtUwh150HsSSdxXZcsuv72miDFQ==}
+    engines: {node: ^20.19.0 || ^22.13.0 || >=24}
+
+  eslint-visitor-keys@3.4.3:
+    resolution: {integrity: sha512-wpc+LXeiyiisxPlEkUzU6svyS1frIO3Mgxj1fdy7Pm8Ygzguax2N3Fa/D/ag1WqbOprdI+uY6wMUl8/a2G+iag==}
+    engines: {node: ^12.22.0 || ^14.17.0 || >=16.0.0}
+
+  eslint-visitor-keys@5.0.1:
+    resolution: {integrity: sha512-tD40eHxA35h0PEIZNeIjkHoDR4YjjJp34biM0mDvplBe//mB+IHCqHDGV7pxF+7MklTvighcCPPZC7ynWyjdTA==}
+    engines: {node: ^20.19.0 || ^22.13.0 || >=24}
+
+  eslint@10.3.0:
+    resolution: {integrity: sha512-XbEXaRva5cF0ZQB8w6MluHA0kZZfV2DuCMJ3ozyEOHLwDpZX2Lmm/7Pp0xdJmI0GL1W05VH5VwIFHEm1Vcw2gw==}
+    engines: {node: ^20.19.0 || ^22.13.0 || >=24}
+    hasBin: true
+    peerDependencies:
+      jiti: '*'
+    peerDependenciesMeta:
+      jiti:
+        optional: true
+
+  espree@11.2.0:
+    resolution: {integrity: sha512-7p3DrVEIopW1B1avAGLuCSh1jubc01H2JHc8B4qqGblmg5gI9yumBgACjWo4JlIc04ufug4xJ3SQI8HkS/Rgzw==}
+    engines: {node: ^20.19.0 || ^22.13.0 || >=24}
+
+  esprima@4.0.1:
+    resolution: {integrity: sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==}
+    engines: {node: '>=4'}
+    hasBin: true
+
+  esquery@1.7.0:
+    resolution: {integrity: sha512-Ap6G0WQwcU/LHsvLwON1fAQX9Zp0A2Y6Y/cJBl9r/JbW90Zyg4/zbG6zzKa2OTALELarYHmKu0GhpM5EO+7T0g==}
+    engines: {node: '>=0.10'}
+
+  esrecurse@4.3.0:
+    resolution: {integrity: sha512-KmfKL3b6G+RXvP8N1vr3Tq1kL/oCFgn2NYXEtqP8/L3pKapUA4G8cFVaoF3SU323CD4XypR/ffioHmkti6/Tag==}
+    engines: {node: '>=4.0'}
+
+  estraverse@5.3.0:
+    resolution: {integrity: sha512-MMdARuVEQziNTeJD8DgMqmhwR11BRQ/cBP+pLtYdSTnf3MIO8fFeiINEbX36ZdNlfU/7A9f3gUw49B3oQsvwBA==}
+    engines: {node: '>=4.0'}
+
+  estree-util-is-identifier-name@3.0.0:
+    resolution: {integrity: sha512-hFtqIDZTIUZ9BXLb8y4pYGyk6+wekIivNVTcmvk8NoOh+VeRn5y6cEHzbURrWbfp1fIqdVipilzj+lfaadNZmg==}
+
+  estree-walker@2.0.2:
+    resolution: {integrity: sha512-Rfkk/Mp/DL7JVje3u18FxFujQlTNR2q6QfMSMB7AvCBx91NGj/ba3kCfza0f6dVDbw7YlRf/nDrn7pQrCCyQ/w==}
+
+  esutils@2.0.3:
+    resolution: {integrity: sha512-kVscqXk4OCp68SZ0dkgEKVi6/8ij300KBWTJq32P/dYeWTSwK41WyTxalN1eRmA5Z9UU/LX9D7FWSmV9SAYx6g==}
+    engines: {node: '>=0.10.0'}
+
+  etag@1.8.1:
+    resolution: {integrity: sha512-aIL5Fx7mawVa300al2BnEE4iNvo1qETxLrPI/o05L7z6go7fCw1J6EQmbK4FmJ2AS7kgVF/KEZWufBfdClMcPg==}
+    engines: {node: '>= 0.6'}
+
+  eventemitter3@5.0.4:
+    resolution: {integrity: sha512-mlsTRyGaPBjPedk6Bvw+aqbsXDtoAyAzm5MO7JgU+yVRyMQ5O8bD4Kcci7BS85f93veegeCPkL8R4GLClnjLFw==}
+
+  eventsource-parser@3.0.8:
+    resolution: {integrity: sha512-70QWGkr4snxr0OXLRWsFLeRBIRPuQOvt4s8QYjmUlmlkyTZkRqS7EDVRZtzU3TiyDbXSzaOeF0XUKy8PchzukQ==}
+    engines: {node: '>=18.0.0'}
+
+  eventsource@3.0.7:
+    resolution: {integrity: sha512-CRT1WTyuQoD771GW56XEZFQ/ZoSfWid1alKGDYMmkt2yl8UXrVR4pspqWNEcqKvVIzg6PAltWjxcSSPrboA4iA==}
+    engines: {node: '>=18.0.0'}
+
+  execa@5.1.1:
+    resolution: {integrity: sha512-8uSpZZocAZRBAPIEINJj3Lo9HyGitllczc27Eh5YYojjMFMn8yHMDMaUHE2Jqfq05D/wucwI4JGURyXt1vchyg==}
+    engines: {node: '>=10'}
+
+  execa@9.6.1:
+    resolution: {integrity: sha512-9Be3ZoN4LmYR90tUoVu2te2BsbzHfhJyfEiAVfz7N5/zv+jduIfLrV2xdQXOHbaD6KgpGdO9PRPM1Y4Q9QkPkA==}
+    engines: {node: ^18.19.0 || >=20.5.0}
+
+  express-rate-limit@8.5.2:
+    resolution: {integrity: sha512-5Kb34ipNX694DH48vN9irak1Qx30nb0PLYHXfJgw4YEjiC3ZEmZJhwOp+VfiCYwFzvFTdB9QkArYS5kXa2cx2A==}
+    engines: {node: '>= 16'}
+    peerDependencies:
+      express: '>= 4.11'
+
+  express@4.22.2:
+    resolution: {integrity: sha512-IuL+Elrou2ZvCFHs18/CIzy2Nzvo25nZ1/D2eIZlz7c+QUayAcYoiM2BthCjs+EBHVpjYjcuLDAiCWgeIX3X1Q==}
+    engines: {node: '>= 0.10.0'}
+
+  express@5.2.1:
+    resolution: {integrity: sha512-hIS4idWWai69NezIdRt2xFVofaF4j+6INOpJlVOLDO8zXGpUVEVzIYk12UUi2JzjEzWL3IOAxcTubgz9Po0yXw==}
+    engines: {node: '>= 18'}
+
+  extend-shallow@2.0.1:
+    resolution: {integrity: sha512-zCnTtlxNoAiDc3gqY2aYAWFx7XWWiasuF2K8Me5WbN8otHKTUKBwjPtNpRs/rbUZm7KxWAaNj7P1a/p52GbVug==}
+    engines: {node: '>=0.10.0'}
+
+  extend@3.0.2:
+    resolution: {integrity: sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g==}
+
+  fast-deep-equal@3.1.3:
+    resolution: {integrity: sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==}
+
+  fast-diff@1.3.0:
+    resolution: {integrity: sha512-VxPP4NqbUjj6MaAOafWeUn2cXWLcCtljklUtZf0Ind4XQ+QPtmA0b18zZy0jIQx+ExRVCR/ZQpBmik5lXshNsw==}
+
+  fast-glob@3.3.3:
+    resolution: {integrity: sha512-7MptL8U0cqcFdzIzwOTHoilX9x5BrNqye7Z/LuC7kCMRio1EMSyqRK3BEAUD7sXRq4iT4AzTVuZdhgQ2TCvYLg==}
+    engines: {node: '>=8.6.0'}
+
+  fast-json-stable-stringify@2.1.0:
+    resolution: {integrity: sha512-lhd/wF+Lk98HZoTCtlVraHtfh5XYijIjalXck7saUtuanSDyLMxnHhSXEDJqHxD7msR8D0uCmqlkwjCV8xvwHw==}
+
+  fast-levenshtein@2.0.6:
+    resolution: {integrity: sha512-DCXu6Ifhqcks7TZKY3Hxp3y6qphY5SJZmrWMDrKcERSOXWQdMhU9Ig/PYrzyw/ul9jOIyh0N4M0tbC5hodg8dw==}
+
+  fast-string-truncated-width@3.0.3:
+    resolution: {integrity: sha512-0jjjIEL6+0jag3l2XWWizO64/aZVtpiGE3t0Zgqxv0DPuxiMjvB3M24fCyhZUO4KomJQPj3LTSUnDP3GpdwC0g==}
+
+  fast-string-width@3.0.2:
+    resolution: {integrity: sha512-gX8LrtNEI5hq8DVUfRQMbr5lpaS4nMIWV+7XEbXk2b8kiQIizgnlr12B4dA3ZEx3308ze0O4Q1R+cHts8kyUJg==}
+
+  fast-uri@3.1.2:
+    resolution: {integrity: sha512-rVjf7ArG3LTk+FS6Yw81V1DLuZl1bRbNrev6Tmd/9RaroeeRRJhAt7jg/6YFxbvAQXUCavSoZhPPj6oOx+5KjQ==}
+
+  fast-wrap-ansi@0.2.0:
+    resolution: {integrity: sha512-rLV8JHxTyhVmFYhBJuMujcrHqOT2cnO5Zxj37qROj23CP39GXubJRBUFF0z8KFK77Uc0SukZUf7JZhsVEQ6n8w==}
+
+  fastq@1.20.1:
+    resolution: {integrity: sha512-GGToxJ/w1x32s/D2EKND7kTil4n8OVk/9mycTc4VDza13lOvpUZTGX3mFSCtV9ksdGBVzvsyAVLM6mHFThxXxw==}
+
+  fdir@6.5.0:
+    resolution: {integrity: sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==}
+    engines: {node: '>=12.0.0'}
+    peerDependencies:
+      picomatch: ^3 || ^4
+    peerDependenciesMeta:
+      picomatch:
+        optional: true
+
+  fetch-blob@3.2.0:
+    resolution: {integrity: sha512-7yAQpD2UMJzLi1Dqv7qFYnPbaPx7ZfFK6PiIxQ4PfkGPyNyl2Ugx+a/umUonmKqjhM4DnfbMvdX6otXq83soQQ==}
+    engines: {node: ^12.20 || >= 14.13}
+
+  figures@6.1.0:
+    resolution: {integrity: sha512-d+l3qxjSesT4V7v2fh+QnmFnUWv9lSpjarhShNTgBOfA0ttejbQUAlHLitbjkoRiDulW0OPoQPYIGhIC8ohejg==}
+    engines: {node: '>=18'}
+
+  file-entry-cache@8.0.0:
+    resolution: {integrity: sha512-XXTUwCvisa5oacNGRP9SfNtYBNAMi+RPwBFmblZEF7N7swHYQS6/Zfk7SRwx4D5j3CH211YNRco1DEMNVfZCnQ==}
+    engines: {node: '>=16.0.0'}
+
+  fill-range@7.1.1:
+    resolution: {integrity: sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg==}
+    engines: {node: '>=8'}
+
+  finalhandler@1.3.2:
+    resolution: {integrity: sha512-aA4RyPcd3badbdABGDuTXCMTtOneUCAYH/gxoYRTZlIJdF0YPWuGqiAsIrhNnnqdXGswYk6dGujem4w80UJFhg==}
+    engines: {node: '>= 0.8'}
+
+  finalhandler@2.1.1:
+    resolution: {integrity: sha512-S8KoZgRZN+a5rNwqTxlZZePjT/4cnm0ROV70LedRHZ0p8u9fRID0hJUZQpkKLzro8LfmC8sx23bY6tVNxv8pQA==}
+    engines: {node: '>= 18.0.0'}
+
+  find-up@5.0.0:
+    resolution: {integrity: sha512-78/PXT1wlLLDgTzDs7sjq9hzz0vXD+zn+7wypEe4fXQxCmdmqfGsEPQxmiCSQI3ajFV91bVSsvNtrJRiW6nGng==}
+    engines: {node: '>=10'}
+
+  flat-cache@4.0.1:
+    resolution: {integrity: sha512-f7ccFPK3SXFHpx15UIGyRJ/FJQctuKZ0zVuN3frBo4HnK3cay9VEW0R6yPYFHC0AgqhukPzKjq22t5DmAyqGyw==}
+    engines: {node: '>=16'}
+
+  flatted@3.4.2:
+    resolution: {integrity: sha512-PjDse7RzhcPkIJwy5t7KPWQSZ9cAbzQXcafsetQoD7sOJRQlGikNbx7yZp2OotDnJyrDcbyRq3Ttb18iYOqkxA==}
+
+  formdata-polyfill@4.0.10:
+    resolution: {integrity: sha512-buewHzMvYL29jdeQTVILecSaZKnt/RJWjoZCF5OW60Z67/GmSLBkOFM7qh1PI3zFNtJbaZL5eQu1vLfazOwj4g==}
+    engines: {node: '>=12.20.0'}
+
+  forwarded@0.2.0:
+    resolution: {integrity: sha512-buRG0fpBtRHSTCOASe6hD258tEubFoRLb4ZNA6NxMVHNw2gOcwHo9wyablzMzOA5z9xA9L1KNjk/Nt6MT9aYow==}
+    engines: {node: '>= 0.6'}
+
+  framer-motion@12.40.0:
+    resolution: {integrity: sha512-uaBd3qC1v3KQqBEjwTUd183K6PbS+j0yR9w9VmEOLWA/tnUcSn8Xa3uck7t4dgpDoUss8xQTcj8W2L07lrnLFg==}
+    peerDependencies:
+      '@emotion/is-prop-valid': '*'
+      react: ^18.0.0 || ^19.0.0
+      react-dom: ^18.0.0 || ^19.0.0
+    peerDependenciesMeta:
+      '@emotion/is-prop-valid':
+        optional: true
+      react:
+        optional: true
+      react-dom:
+        optional: true
+
+  fresh@0.5.2:
+    resolution: {integrity: sha512-zJ2mQYM18rEFOudeV4GShTGIQ7RbzA7ozbU9I/XBpm7kqgMywgmylMwXHxZJmkVoYkna9d2pVXVXPdYTP9ej8Q==}
+    engines: {node: '>= 0.6'}
+
+  fresh@2.0.0:
+    resolution: {integrity: sha512-Rx/WycZ60HOaqLKAi6cHRKKI7zxWbJ31MhntmtwMoaTeF7XFH9hhBp8vITaMidfljRQ6eYWCKkaTK+ykVJHP2A==}
+    engines: {node: '>= 0.8'}
+
+  fs-extra@11.3.5:
+    resolution: {integrity: sha512-eKpRKAovdpZtR1WopLHxlBWvAgPny3c4gX1G5Jhwmmw4XJj0ifSD5qB5TOo8hmA0wlRKDAOAhEE1yVPgs6Fgcg==}
+    engines: {node: '>=14.14'}
+
+  fsevents@2.3.3:
+    resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==}
+    engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
+    os: [darwin]
+
+  function-bind@1.1.2:
+    resolution: {integrity: sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA==}
+
+  fuzzysort@3.1.0:
+    resolution: {integrity: sha512-sR9BNCjBg6LNgwvxlBd0sBABvQitkLzoVY9MYYROQVX/FvfJ4Mai9LsGhDgd8qYdds0bY77VzYd5iuB+v5rwQQ==}
+
+  gensync@1.0.0-beta.2:
+    resolution: {integrity: sha512-3hN7NaskYvMDLQY55gnW3NQ+mesEAepTqlg+VEbj7zzqEMBVNhzcGYYeqFo/TlYz6eQiFcp1HcsCZO+nGgS8zg==}
+    engines: {node: '>=6.9.0'}
+
+  get-caller-file@2.0.5:
+    resolution: {integrity: sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==}
+    engines: {node: 6.* || 8.* || >= 10.*}
+
+  get-east-asian-width@1.6.0:
+    resolution: {integrity: sha512-QRbvDIbx6YklUe6RxeTeleMR0yv3cYH6PsPZHcnVn7xv7zO1BHN8r0XETu8n6Ye3Q+ahtSarc3WgtNWmehIBfA==}
+    engines: {node: '>=18'}
+
+  get-intrinsic@1.3.0:
+    resolution: {integrity: sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ==}
+    engines: {node: '>= 0.4'}
+
+  get-nonce@1.0.1:
+    resolution: {integrity: sha512-FJhYRoDaiatfEkUK8HKlicmu/3SGFD51q3itKDGoSTysQJBnfOcxU5GxnhE1E6soB76MbT0MBtnKJuXyAx+96Q==}
+    engines: {node: '>=6'}
+
+  get-own-enumerable-keys@1.0.0:
+    resolution: {integrity: sha512-PKsK2FSrQCyxcGHsGrLDcK0lx+0Ke+6e8KFFozA9/fIQLhQzPaRvJFdcz7+Axg3jUH/Mq+NI4xa5u/UT2tQskA==}
+    engines: {node: '>=14.16'}
+
+  get-proto@1.0.1:
+    resolution: {integrity: sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g==}
+    engines: {node: '>= 0.4'}
+
+  get-stream@6.0.1:
+    resolution: {integrity: sha512-ts6Wi+2j3jQjqi70w5AlN8DFnkSwC+MqmxEzdEALB2qXZYV3X/b1CTfgPLGJNMeAWxdPfU8FO1ms3NUfaHCPYg==}
+    engines: {node: '>=10'}
+
+  get-stream@9.0.1:
+    resolution: {integrity: sha512-kVCxPF3vQM/N0B1PmoqVUqgHP+EeVjmZSQn+1oCRPxd2P21P2F19lIgbR3HBosbB1PUhOAoctJnfEn2GbN2eZA==}
+    engines: {node: '>=18'}
+
+  get-tsconfig@4.14.0:
+    resolution: {integrity: sha512-yTb+8DXzDREzgvYmh6s9vHsSVCHeC0G3PI5bEXNBHtmshPnO+S5O7qgLEOn0I5QvMy6kpZN8K1NKGyilLb93wA==}
+
+  gitdiff-parser@0.3.1:
+    resolution: {integrity: sha512-YQJnY8aew65id8okGxKCksH3efDCJ9HzV7M9rsvd65habf39Pkh4cgYJ27AaoDMqo1X98pgNJhNMrm/kpV7UVQ==}
+
+  glob-parent@5.1.2:
+    resolution: {integrity: sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==}
+    engines: {node: '>= 6'}
+
+  glob-parent@6.0.2:
+    resolution: {integrity: sha512-XxwI8EOhVQgWp6iDL+3b0r86f4d6AX6zSU55HfB4ydCEuXLXc5FcYeOu+nnGftS4TEju/11rt4KJPTMgbfmv4A==}
+    engines: {node: '>=10.13.0'}
+
+  globals@17.6.0:
+    resolution: {integrity: sha512-sepffkT8stwnIYbsMBpoCHJuJM5l98FUF2AnE07hfvE0m/qp3R586hw4jF4uadbhvg1ooIdzuu7CsfD2jzCaNA==}
+    engines: {node: '>=18'}
+
+  gopd@1.2.0:
+    resolution: {integrity: sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg==}
+    engines: {node: '>= 0.4'}
+
+  graceful-fs@4.2.11:
+    resolution: {integrity: sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==}
+
+  graphql@16.14.0:
+    resolution: {integrity: sha512-BBvQ/406p+4CZbTpCbVPSxfzrZrbnuWSP1ELYgyS6B+hNeKzgrdB4JczCa5VZUBQrDa9hUngm0KnexY6pJRN5Q==}
+    engines: {node: ^12.22.0 || ^14.16.0 || ^16.0.0 || >=17.0.0}
+
+  gray-matter@4.0.3:
+    resolution: {integrity: sha512-5v6yZd4JK3eMI3FqqCouswVqwugaA9r4dNZB1wwcmrD02QkV5H0y7XBQW8QwQqEaZY1pM9aqORSORhJRdNK44Q==}
+    engines: {node: '>=6.0'}
+
+  has-flag@3.0.0:
+    resolution: {integrity: sha512-sKJf1+ceQBr4SMkvQnBDNDtf4TXpVhVGateu0t918bl30FnbE2m4vNLX+VWe/dpjlb+HugGYzW7uQXH98HPEYw==}
+    engines: {node: '>=4'}
+
+  has-flag@4.0.0:
+    resolution: {integrity: sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==}
+    engines: {node: '>=8'}
+
+  has-symbols@1.1.0:
+    resolution: {integrity: sha512-1cDNdwJ2Jaohmb3sg4OmKaMBwuC48sYni5HUw2DvsC8LjGTLK9h+eb1X6RyuOHe4hT0ULCW68iomhjUoKUqlPQ==}
+    engines: {node: '>= 0.4'}
+
+  hasown@2.0.3:
+    resolution: {integrity: sha512-ej4AhfhfL2Q2zpMmLo7U1Uv9+PyhIZpgQLGT1F9miIGmiCJIoCgSmczFdrc97mWT4kVY72KA+WnnhJ5pghSvSg==}
+    engines: {node: '>= 0.4'}
+
+  hast-util-to-jsx-runtime@2.3.6:
+    resolution: {integrity: sha512-zl6s8LwNyo1P9uw+XJGvZtdFF1GdAkOg8ujOw+4Pyb76874fLps4ueHXDhXWdk6YHQ6OgUtinliG7RsYvCbbBg==}
+
+  hast-util-whitespace@3.0.0:
+    resolution: {integrity: sha512-88JUN06ipLwsnv+dVn+OIYOvAuvBMy/Qoi6O7mQHxdPXpjy+Cd6xRkWwux7DKO+4sYILtLBRIKgsdpS2gQc7qw==}
+
+  headers-polyfill@5.0.1:
+    resolution: {integrity: sha512-1TJ6Fih/b8h5TIcv+1+Hw0PDQWJTKDKzFZzcKOiW1wJza3XoAQlkCuXLbymPYB8+ZQyw8mHvdw560e8zVFIWyA==}
+
+  hermes-estree@0.25.1:
+    resolution: {integrity: sha512-0wUoCcLp+5Ev5pDW2OriHC2MJCbwLwuRx+gAqMTOkGKJJiBCLjtrvy4PWUGn6MIVefecRpzoOZ/UV6iGdOr+Cw==}
+
+  hermes-parser@0.25.1:
+    resolution: {integrity: sha512-6pEjquH3rqaI6cYAXYPcz9MS4rY6R4ngRgrgfDshRptUZIc3lw0MCIJIGDj9++mfySOuPTHB4nrSW99BCvOPIA==}
+
+  hono@4.12.18:
+    resolution: {integrity: sha512-RWzP96k/yv0PQfyXnWjs6zot20TqfpfsNXhOnev8d1InAxubW93L11/oNUc3tQqn2G0bSdAOBpX+2uDFHV7kdQ==}
+    engines: {node: '>=16.9.0'}
+
+  html-parse-stringify@3.0.1:
+    resolution: {integrity: sha512-KknJ50kTInJ7qIScF3jeaFRpMpE8/lfiTdzf/twXyPBLAGrLRTmkz3AdTnKeh40X8k9L2fdYwEp/42WGXIRGcg==}
+
+  html-url-attributes@3.0.1:
+    resolution: {integrity: sha512-ol6UPyBWqsrO6EJySPz2O7ZSr856WDrEzM5zMqp+FJJLGMW35cLYmmZnl0vztAZxRUoNZJFTCohfjuIJ8I4QBQ==}
+
+  http-errors@2.0.1:
+    resolution: {integrity: sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ==}
+    engines: {node: '>= 0.8'}
+
+  https-proxy-agent@7.0.6:
+    resolution: {integrity: sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw==}
+    engines: {node: '>= 14'}
+
+  human-signals@2.1.0:
+    resolution: {integrity: sha512-B4FFZ6q/T2jhhksgkbEW3HBvWIfDW85snkQgawt07S7J5QXTk6BkNV+0yAeZrM5QpMAdYlocGoljn0sJ/WQkFw==}
+    engines: {node: '>=10.17.0'}
+
+  human-signals@8.0.1:
+    resolution: {integrity: sha512-eKCa6bwnJhvxj14kZk5NCPc6Hb6BdsU9DZcOnmQKSnO1VKrfV0zCvtttPZUsBvjmNDn8rpcJfpwSYnHBjc95MQ==}
+    engines: {node: '>=18.18.0'}
+
+  husky@9.1.7:
+    resolution: {integrity: sha512-5gs5ytaNjBrh5Ow3zrvdUUY+0VxIuWVL4i9irt6friV+BqdCfmV11CQTWMiBYWHbXhco+J1kHfTOUkePhCDvMA==}
+    engines: {node: '>=18'}
+    hasBin: true
+
+  i18next-browser-languagedetector@8.2.1:
+    resolution: {integrity: sha512-bZg8+4bdmaOiApD7N7BPT9W8MLZG+nPTOFlLiJiT8uzKXFjhxw4v2ierCXOwB5sFDMtuA5G4kgYZ0AznZxQ/cw==}
+
+  i18next@26.2.0:
+    resolution: {integrity: sha512-zwBHldHdTmwN7r6UNc7lC6GWNN+YYg3DrRSeHR5PRRBf5QnJZcYHrQc0uaU26qZeYxR7iFZD+Y315dPnKP47wA==}
+    peerDependencies:
+      typescript: ^5 || ^6
+    peerDependenciesMeta:
+      typescript:
+        optional: true
+
+  iconv-lite@0.4.24:
+    resolution: {integrity: sha512-v3MXnZAcvnywkTUEZomIActle7RXXeedOR31wwl7VlyoXO4Qi9arvSenNQWne1TcRwhCL1HwLI21bEqdpj8/rA==}
+    engines: {node: '>=0.10.0'}
+
+  iconv-lite@0.7.2:
+    resolution: {integrity: sha512-im9DjEDQ55s9fL4EYzOAv0yMqmMBSZp6G0VvFyTMPKWxiSBHUj9NW/qqLmXUwXrrM7AvqSlTCfvqRb0cM8yYqw==}
+    engines: {node: '>=0.10.0'}
+
+  ignore-by-default@1.0.1:
+    resolution: {integrity: sha512-Ius2VYcGNk7T90CppJqcIkS5ooHUZyIQK+ClZfMfMNFEF9VSE73Fq+906u/CWu92x4gzZMWOwfFYckPObzdEbA==}
+
+  ignore@5.3.2:
+    resolution: {integrity: sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g==}
+    engines: {node: '>= 4'}
+
+  ignore@7.0.5:
+    resolution: {integrity: sha512-Hs59xBNfUIunMFgWAbGX5cq6893IbWg4KnrjbYwX3tx0ztorVgTDA6B2sxf8ejHJ4wz8BqGUMYlnzNBer5NvGg==}
+    engines: {node: '>= 4'}
+
+  import-fresh@3.3.1:
+    resolution: {integrity: sha512-TR3KfrTZTYLPB6jUjfx6MF9WcWrHL9su5TObK4ZkYgBdWKPOFoSoQIdEuTuR82pmtxH2spWG9h6etwfr1pLBqQ==}
+    engines: {node: '>=6'}
+
+  imurmurhash@0.1.4:
+    resolution: {integrity: sha512-JmXMZ6wuvDmLiHEml9ykzqO6lwFbof0GG4IkcGaENdCRDDmMVnny7s5HsIgHCbaq0w2MyPhDqkhTUgS2LU2PHA==}
+    engines: {node: '>=0.8.19'}
+
+  inherits@2.0.4:
+    resolution: {integrity: sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==}
+
+  inline-style-parser@0.2.7:
+    resolution: {integrity: sha512-Nb2ctOyNR8DqQoR0OwRG95uNWIC0C1lCgf5Naz5H6Ji72KZ8OcFZLz2P5sNgwlyoJ8Yif11oMuYs5pBQa86csA==}
+
+  ip-address@10.2.0:
+    resolution: {integrity: sha512-/+S6j4E9AHvW9SWMSEY9Xfy66O5PWvVEJ08O0y5JGyEKQpojb0K0GKpz/v5HJ/G0vi3D2sjGK78119oXZeE0qA==}
+    engines: {node: '>= 12'}
+
+  ipaddr.js@1.9.1:
+    resolution: {integrity: sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g==}
+    engines: {node: '>= 0.10'}
+
+  is-alphabetical@2.0.1:
+    resolution: {integrity: sha512-FWyyY60MeTNyeSRpkM2Iry0G9hpr7/9kD40mD/cGQEuilcZYS4okz8SN2Q6rLCJ8gbCt6fN+rC+6tMGS99LaxQ==}
+
+  is-alphanumerical@2.0.1:
+    resolution: {integrity: sha512-hmbYhX/9MUMF5uh7tOXyK/n0ZvWpad5caBA17GsC6vyuCqaWliRG5K1qS9inmUhEMaOBIW7/whAnSwveW/LtZw==}
+
+  is-arrayish@0.2.1:
+    resolution: {integrity: sha512-zz06S8t0ozoDXMG+ube26zeCTNXcKIPJZJi8hBrF4idCLms4CG9QtK7qBl1boi5ODzFpjswb5JPmHCbMpjaYzg==}
+
+  is-binary-path@2.1.0:
+    resolution: {integrity: sha512-ZMERYes6pDydyuGidse7OsHxtbI7WVeUEozgR/g7rd0xUimYNlvZRE/K2MgZTjWy725IfelLeVcEM97mmtRGXw==}
+    engines: {node: '>=8'}
+
+  is-decimal@2.0.1:
+    resolution: {integrity: sha512-AAB9hiomQs5DXWcRB1rqsxGUstbRroFOPPVAomNk/3XHR5JyEZChOyTWe2oayKnsSsr/kcGqF+z6yuH6HHpN0A==}
+
+  is-docker@3.0.0:
+    resolution: {integrity: sha512-eljcgEDlEns/7AXFosB5K/2nCM4P7FQPkGc/DWLy5rmFEWvZayGrik1d9/QIY5nJ4f9YsVvBkA6kJpHn9rISdQ==}
+    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
+    hasBin: true
+
+  is-extendable@0.1.1:
+    resolution: {integrity: sha512-5BMULNob1vgFX6EjQw5izWDxrecWK9AM72rugNr0TFldMOi0fj6Jk+zeKIt0xGj4cEfQIJth4w3OKWOJ4f+AFw==}
+    engines: {node: '>=0.10.0'}
+
+  is-extglob@2.1.1:
+    resolution: {integrity: sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ==}
+    engines: {node: '>=0.10.0'}
+
+  is-fullwidth-code-point@3.0.0:
+    resolution: {integrity: sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==}
+    engines: {node: '>=8'}
+
+  is-fullwidth-code-point@5.1.0:
+    resolution: {integrity: sha512-5XHYaSyiqADb4RnZ1Bdad6cPp8Toise4TzEjcOYDHZkTCbKgiUl7WTUCpNWHuxmDt91wnsZBc9xinNzopv3JMQ==}
+    engines: {node: '>=18'}
+
+  is-glob@4.0.3:
+    resolution: {integrity: sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==}
+    engines: {node: '>=0.10.0'}
+
+  is-hexadecimal@2.0.1:
+    resolution: {integrity: sha512-DgZQp241c8oO6cA1SbTEWiXeoxV42vlcJxgH+B3hi1AiqqKruZR3ZGF8In3fj4+/y/7rHvlOZLZtgJ/4ttYGZg==}
+
+  is-in-ssh@1.0.0:
+    resolution: {integrity: sha512-jYa6Q9rH90kR1vKB6NM7qqd1mge3Fx4Dhw5TVlK1MUBqhEOuCagrEHMevNuCcbECmXZ0ThXkRm+Ymr51HwEPAw==}
+    engines: {node: '>=20'}
+
+  is-inside-container@1.0.0:
+    resolution: {integrity: sha512-KIYLCCJghfHZxqjYBE7rEy0OBuTd5xCHS7tHVgvCLkx7StIoaxwNW3hCALgEUjFfeRk+MG/Qxmp/vtETEF3tRA==}
+    engines: {node: '>=14.16'}
+    hasBin: true
+
+  is-interactive@2.0.0:
+    resolution: {integrity: sha512-qP1vozQRI+BMOPcjFzrjXuQvdak2pHNUMZoeG2eRbiSqyvbEf/wQtEOTOX1guk6E3t36RkaqiSt8A/6YElNxLQ==}
+    engines: {node: '>=12'}
+
+  is-node-process@1.2.0:
+    resolution: {integrity: sha512-Vg4o6/fqPxIjtxgUH5QLJhwZ7gW5diGCVlXpuUfELC62CuxM1iHcRe51f2W1FDy04Ai4KJkagKjx3XaqyfRKXw==}
+
+  is-number@7.0.0:
+    resolution: {integrity: sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng==}
+    engines: {node: '>=0.12.0'}
+
+  is-obj@3.0.0:
+    resolution: {integrity: sha512-IlsXEHOjtKhpN8r/tRFj2nDyTmHvcfNeu/nrRIcXE17ROeatXchkojffa1SpdqW4cr/Fj6QkEf/Gn4zf6KKvEQ==}
+    engines: {node: '>=12'}
+
+  is-plain-obj@4.1.0:
+    resolution: {integrity: sha512-+Pgi+vMuUNkJyExiMBt5IlFoMyKnr5zhJ4Uspz58WOhBF5QoIZkFyNHIbBAtHwzVAgk5RtndVNsDRN61/mmDqg==}
+    engines: {node: '>=12'}
+
+  is-promise@4.0.0:
+    resolution: {integrity: sha512-hvpoI6korhJMnej285dSg6nu1+e6uxs7zG3BYAm5byqDsgJNWwxzM6z6iZiAgQR4TJ30JmBTOwqZUw3WlyH3AQ==}
+
+  is-regexp@3.1.0:
+    resolution: {integrity: sha512-rbku49cWloU5bSMI+zaRaXdQHXnthP6DZ/vLnfdSKyL4zUzuWnomtOEiZZOd+ioQ+avFo/qau3KPTc7Fjy1uPA==}
+    engines: {node: '>=12'}
+
+  is-stream@2.0.1:
+    resolution: {integrity: sha512-hFoiJiTl63nn+kstHGBtewWSKnQLpyb155KHheA1l39uvtO9nWIop1p3udqPcUd/xbF1VLMO4n7OI6p7RbngDg==}
+    engines: {node: '>=8'}
+
+  is-stream@4.0.1:
+    resolution: {integrity: sha512-Dnz92NInDqYckGEUJv689RbRiTSEHCQ7wOVeALbkOz999YpqT46yMRIGtSNl2iCL1waAZSx40+h59NV/EwzV/A==}
+    engines: {node: '>=18'}
+
+  is-unicode-supported@1.3.0:
+    resolution: {integrity: sha512-43r2mRvz+8JRIKnWJ+3j8JtjRKZ6GmjzfaE/qiBJnikNnYv/6bagRJ1kUhNk8R5EX/GkobD+r+sfxCPJsiKBLQ==}
+    engines: {node: '>=12'}
+
+  is-unicode-supported@2.1.0:
+    resolution: {integrity: sha512-mE00Gnza5EEB3Ds0HfMyllZzbBrmLOX3vfWoj9A9PEnTfratQ/BcaJOuMhnkhjXvb2+FkY3VuHqtAGpTPmglFQ==}
+    engines: {node: '>=18'}
+
+  is-wsl@3.1.1:
+    resolution: {integrity: sha512-e6rvdUCiQCAuumZslxRJWR/Doq4VpPR82kqclvcS0efgt430SlGIk05vdCN58+VrzgtIcfNODjozVielycD4Sw==}
+    engines: {node: '>=16'}
+
+  isexe@2.0.0:
+    resolution: {integrity: sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==}
+
+  isexe@3.1.5:
+    resolution: {integrity: sha512-6B3tLtFqtQS4ekarvLVMZ+X+VlvQekbe4taUkf/rhVO3d/h0M2rfARm/pXLcPEsjjMsFgrFgSrhQIxcSVrBz8w==}
+    engines: {node: '>=18'}
+
+  jiti@2.7.0:
+    resolution: {integrity: sha512-AC/7JofJvZGrrneWNaEnJeOLUx+JlGt7tNa0wZiRPT4MY1wmfKjt2+6O2p2uz2+skll8OZZmJMNqeke7kKbNgQ==}
+    hasBin: true
+
+  jose@6.2.3:
+    resolution: {integrity: sha512-YYVDInQKFJfR/xa3ojUTl8c2KoTwiL1R5Wg9YCydwH0x0B9grbzlg5HC7mMjCtUJjbQ/YnGEZIhI5tCgfTb4Hw==}
+
+  js-tokens@4.0.0:
+    resolution: {integrity: sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==}
+
+  js-yaml@3.14.2:
+    resolution: {integrity: sha512-PMSmkqxr106Xa156c2M265Z+FTrPl+oxd/rgOQy2tijQeK5TxQ43psO1ZCwhVOSdnn+RzkzlRz/eY4BgJBYVpg==}
+    hasBin: true
+
+  js-yaml@4.1.1:
+    resolution: {integrity: sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA==}
+    hasBin: true
+
+  jsesc@3.1.0:
+    resolution: {integrity: sha512-/sM3dO2FOzXjKQhJuo0Q173wf2KOo8t4I8vHy6lF9poUp7bKT0/NHE8fPX23PwfhnykfqnC2xRxOnVw5XuGIaA==}
+    engines: {node: '>=6'}
+    hasBin: true
+
+  json-buffer@3.0.1:
+    resolution: {integrity: sha512-4bV5BfR2mqfQTJm+V5tPPdf+ZpuhiIvTuAB5g8kcrXOZpTT/QwwVRWBywX1ozr6lEuPdbHxwaJlm9G6mI2sfSQ==}
+
+  json-parse-even-better-errors@2.3.1:
+    resolution: {integrity: sha512-xyFwyhro/JEof6Ghe2iz2NcXoj2sloNsWr/XsERDK/oiPCfaNhl5ONfp+jQdAZRQQ0IJWNzH9zIZF7li91kh2w==}
+
+  json-schema-traverse@0.4.1:
+    resolution: {integrity: sha512-xbbCH5dCYU5T8LcEhhuh7HJ88HXuW3qsI3Y0zOZFKfZEHcpWiHU/Jxzk629Brsab/mMiHQti9wMP+845RPe3Vg==}
+
+  json-schema-traverse@1.0.0:
+    resolution: {integrity: sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==}
+
+  json-schema-typed@8.0.2:
+    resolution: {integrity: sha512-fQhoXdcvc3V28x7C7BMs4P5+kNlgUURe2jmUT1T//oBRMDrqy1QPelJimwZGo7Hg9VPV3EQV5Bnq4hbFy2vetA==}
+
+  json-stable-stringify-without-jsonify@1.0.1:
+    resolution: {integrity: sha512-Bdboy+l7tA3OGW6FjyFHWkP5LuByj1Tk33Ljyq0axyzdk9//JSi2u3fP1QSmd1KNwq6VOKYGlAu87CisVir6Pw==}
+
+  json5@2.2.3:
+    resolution: {integrity: sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg==}
+    engines: {node: '>=6'}
+    hasBin: true
+
+  jsonfile@6.2.1:
+    resolution: {integrity: sha512-zwOTdL3rFQ/lRdBnntKVOX6k5cKJwEc1HdilT71BWEu7J41gXIB2MRp+vxduPSwZJPWBxEzv4yH1wYLJGUHX4Q==}
+
+  jsonrepair@3.14.0:
+    resolution: {integrity: sha512-tWPGKMZf/8UPim+fcW2EfcQ/d/7aKUrP6IECz9G3Tu6Q5dX0orSleqJ9z6sSw7qrQkjF8/Edo4DvsWBZ8H+HNg==}
+    hasBin: true
+
+  keyv@4.5.4:
+    resolution: {integrity: sha512-oxVHkHR/EJf2CNXnWxRLW6mg7JyCCUcG0DtEGmL2ctUo1PNTin1PUil+r/+4r5MpVgC/fn1kjsx7mjSujKqIpw==}
+
+  kind-of@6.0.3:
+    resolution: {integrity: sha512-dcS1ul+9tmeD95T+x28/ehLgd9mENa3LsvDTtzm3vyBEO7RPptvAD+t44WVXaUjTBRcrpFeFlC8WCruUR456hw==}
+    engines: {node: '>=0.10.0'}
+
+  kleur@3.0.3:
+    resolution: {integrity: sha512-eTIzlVOSUR+JxdDFepEYcBMtZ9Qqdef+rnzWdRZuMbOywu5tO2w2N7rqjoANZ5k9vywhL6Br1VRjUIgTQx4E8w==}
+    engines: {node: '>=6'}
+
+  kleur@4.1.5:
+    resolution: {integrity: sha512-o+NO+8WrRiQEE4/7nwRJhN1HWpVmJm511pBHUxPLtp0BUISzlBplORYSmTclCnJvQq2tKu/sgl3xVpkc7ZWuQQ==}
+    engines: {node: '>=6'}
+
+  levn@0.4.1:
+    resolution: {integrity: sha512-+bT2uH4E5LGE7h/n3evcS/sQlJXCpIp6ym8OWJ5eV6+67Dsql/LaaT7qJBAt2rzfoa/5QBGBhxDix1dMt2kQKQ==}
+    engines: {node: '>= 0.8.0'}
+
+  lightningcss-android-arm64@1.32.0:
+    resolution: {integrity: sha512-YK7/ClTt4kAK0vo6w3X+Pnm0D2cf2vPHbhOXdoNti1Ga0al1P4TBZhwjATvjNwLEBCnKvjJc2jQgHXH0NEwlAg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [android]
+
+  lightningcss-darwin-arm64@1.32.0:
+    resolution: {integrity: sha512-RzeG9Ju5bag2Bv1/lwlVJvBE3q6TtXskdZLLCyfg5pt+HLz9BqlICO7LZM7VHNTTn/5PRhHFBSjk5lc4cmscPQ==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [darwin]
+
+  lightningcss-darwin-x64@1.32.0:
+    resolution: {integrity: sha512-U+QsBp2m/s2wqpUYT/6wnlagdZbtZdndSmut/NJqlCcMLTWp5muCrID+K5UJ6jqD2BFshejCYXniPDbNh73V8w==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [darwin]
+
+  lightningcss-freebsd-x64@1.32.0:
+    resolution: {integrity: sha512-JCTigedEksZk3tHTTthnMdVfGf61Fky8Ji2E4YjUTEQX14xiy/lTzXnu1vwiZe3bYe0q+SpsSH/CTeDXK6WHig==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [freebsd]
+
+  lightningcss-linux-arm-gnueabihf@1.32.0:
+    resolution: {integrity: sha512-x6rnnpRa2GL0zQOkt6rts3YDPzduLpWvwAF6EMhXFVZXD4tPrBkEFqzGowzCsIWsPjqSK+tyNEODUBXeeVHSkw==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm]
+    os: [linux]
+
+  lightningcss-linux-arm64-gnu@1.32.0:
+    resolution: {integrity: sha512-0nnMyoyOLRJXfbMOilaSRcLH3Jw5z9HDNGfT/gwCPgaDjnx0i8w7vBzFLFR1f6CMLKF8gVbebmkUN3fa/kQJpQ==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  lightningcss-linux-arm64-musl@1.32.0:
+    resolution: {integrity: sha512-UpQkoenr4UJEzgVIYpI80lDFvRmPVg6oqboNHfoH4CQIfNA+HOrZ7Mo7KZP02dC6LjghPQJeBsvXhJod/wnIBg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  lightningcss-linux-x64-gnu@1.32.0:
+    resolution: {integrity: sha512-V7Qr52IhZmdKPVr+Vtw8o+WLsQJYCTd8loIfpDaMRWGUZfBOYEJeyJIkqGIDMZPwPx24pUMfwSxxI8phr/MbOA==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  lightningcss-linux-x64-musl@1.32.0:
+    resolution: {integrity: sha512-bYcLp+Vb0awsiXg/80uCRezCYHNg1/l3mt0gzHnWV9XP1W5sKa5/TCdGWaR/zBM2PeF/HbsQv/j2URNOiVuxWg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  lightningcss-win32-arm64-msvc@1.32.0:
+    resolution: {integrity: sha512-8SbC8BR40pS6baCM8sbtYDSwEVQd4JlFTOlaD3gWGHfThTcABnNDBda6eTZeqbofalIJhFx0qKzgHJmcPTnGdw==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [win32]
+
+  lightningcss-win32-x64-msvc@1.32.0:
+    resolution: {integrity: sha512-Amq9B/SoZYdDi1kFrojnoqPLxYhQ4Wo5XiL8EVJrVsB8ARoC1PWW6VGtT0WKCemjy8aC+louJnjS7U18x3b06Q==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [win32]
+
+  lightningcss@1.32.0:
+    resolution: {integrity: sha512-NXYBzinNrblfraPGyrbPoD19C1h9lfI/1mzgWYvXUTe414Gz/X1FD2XBZSZM7rRTrMA8JL3OtAaGifrIKhQ5yQ==}
+    engines: {node: '>= 12.0.0'}
+
+  lines-and-columns@1.2.4:
+    resolution: {integrity: sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg==}
+
+  lint-staged@17.0.5:
+    resolution: {integrity: sha512-d12yC+/e8RhBjZtaxZn71FyrgU/P5e+uAPifhCLwdosQZP/zamSdKRWDC30ocVIbzDKiFG1McHc/LUgB92GIPw==}
+    engines: {node: '>=22.22.1'}
+    hasBin: true
+
+  listr2@10.2.1:
+    resolution: {integrity: sha512-7I5knELsJKTUjXG+A6BkKAiGkW1i25fNa/xlUl9hFtk15WbE9jndA89xu5FzQKrY5llajE1hfZZFMILXkDHk/Q==}
+    engines: {node: '>=22.13.0'}
+
+  locate-path@6.0.0:
+    resolution: {integrity: sha512-iPZK6eYjbxRu3uB4/WZ3EsEIMJFMqAoopl3R+zuq0UjcAm/MO6KCweDgPfP3elTztoKP3KtnVHxTn2NHBSDVUw==}
+    engines: {node: '>=10'}
+
+  lodash@4.18.1:
+    resolution: {integrity: sha512-dMInicTPVE8d1e5otfwmmjlxkZoUpiVLwyeTdUsi/Caj/gfzzblBcCE5sRHV/AsjuCmxWrte2TNGSYuCeCq+0Q==}
+
+  log-symbols@6.0.0:
+    resolution: {integrity: sha512-i24m8rpwhmPIS4zscNzK6MSEhk0DUWa/8iYQWxhffV8jkI4Phvs3F+quL5xvS0gdQR0FyTCMMH33Y78dDTzzIw==}
+    engines: {node: '>=18'}
+
+  log-update@6.1.0:
+    resolution: {integrity: sha512-9ie8ItPR6tjY5uYJh8K/Zrv/RMZ5VOlOWvtZdEHYSTFKZfIBPQa9tOAEeAWhd+AnIneLJ22w5fjOYtoutpWq5w==}
+    engines: {node: '>=18'}
+
+  longest-streak@3.1.0:
+    resolution: {integrity: sha512-9Ri+o0JYgehTaVBBDoMqIl8GXtbWg711O3srftcHhZ0dqnETqLaoIK0x17fUw9rFSlK/0NlsKe0Ahhyl5pXE2g==}
+
+  loose-envify@1.4.0:
+    resolution: {integrity: sha512-lyuxPGr/Wfhrlem2CL/UcnUc1zcqKAImBDzukY7Y5F/yQiNdko6+fRLevlw1HgMySw7f611UIY408EtxRSoK3Q==}
+    hasBin: true
+
+  lower-case@2.0.2:
+    resolution: {integrity: sha512-7fm3l3NAF9WfN6W3JOmf5drwpVqX78JtoGJ3A6W0a6ZnldM41w2fV5D490psKFTpMds8TJse/eHLFFsNHHjHgg==}
+
+  lru-cache@5.1.1:
+    resolution: {integrity: sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w==}
+
+  lucide-react@1.16.0:
+    resolution: {integrity: sha512-dYwyPzb4MEKpGUmNYk3WKWPnMrHs3FKM+q94kAnJrcDIqqn1hq2xY8scaS2ovsOCM5D51ey2gaRG3PBb1vgoYQ==}
+    peerDependencies:
+      react: ^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0
+
+  lucide@1.3.0:
+    resolution: {integrity: sha512-8/98ZCQjNDdfOjSycUujwqxKNrq97WPzdlNBR6tG7BqZgiOFQqzJuFapIpjPceW57sJv3zGIBg0L3SWR7c4fqA==}
+
+  luxon@3.7.2:
+    resolution: {integrity: sha512-vtEhXh/gNjI9Yg1u4jX/0YVPMvxzHuGgCm6tC5kZyb08yjGWGnqAjGJvcXbqQR2P3MyMEFnRbpcdFS6PBcLqew==}
+    engines: {node: '>=12'}
+
+  magic-string@0.30.21:
+    resolution: {integrity: sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==}
+
+  make-error@1.3.6:
+    resolution: {integrity: sha512-s8UhlNe7vPKomQhC1qFelMokr/Sc3AgNbso3n74mVPA5LTZwkB9NlXf4XPamLxJE8h0gh73rM94xvwRT2CVInw==}
+
+  markdown-table@3.0.4:
+    resolution: {integrity: sha512-wiYz4+JrLyb/DqW2hkFJxP7Vd7JuTDm77fvbM8VfEQdmSMqcImWeeRbHwZjBjIFki/VaMK2BhFi7oUUZeM5bqw==}
+
+  math-intrinsics@1.1.0:
+    resolution: {integrity: sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==}
+    engines: {node: '>= 0.4'}
+
+  mdast-util-find-and-replace@3.0.2:
+    resolution: {integrity: sha512-Tmd1Vg/m3Xz43afeNxDIhWRtFZgM2VLyaf4vSTYwudTyeuTneoL3qtWMA5jeLyz/O1vDJmmV4QuScFCA2tBPwg==}
+
+  mdast-util-from-markdown@2.0.3:
+    resolution: {integrity: sha512-W4mAWTvSlKvf8L6J+VN9yLSqQ9AOAAvHuoDAmPkz4dHf553m5gVj2ejadHJhoJmcmxEnOv6Pa8XJhpxE93kb8Q==}
+
+  mdast-util-gfm-autolink-literal@2.0.1:
+    resolution: {integrity: sha512-5HVP2MKaP6L+G6YaxPNjuL0BPrq9orG3TsrZ9YXbA3vDw/ACI4MEsnoDpn6ZNm7GnZgtAcONJyPhOP8tNJQavQ==}
+
+  mdast-util-gfm-footnote@2.1.0:
+    resolution: {integrity: sha512-sqpDWlsHn7Ac9GNZQMeUzPQSMzR6Wv0WKRNvQRg0KqHh02fpTz69Qc1QSseNX29bhz1ROIyNyxExfawVKTm1GQ==}
+
+  mdast-util-gfm-strikethrough@2.0.0:
+    resolution: {integrity: sha512-mKKb915TF+OC5ptj5bJ7WFRPdYtuHv0yTRxK2tJvi+BDqbkiG7h7u/9SI89nRAYcmap2xHQL9D+QG/6wSrTtXg==}
+
+  mdast-util-gfm-table@2.0.0:
+    resolution: {integrity: sha512-78UEvebzz/rJIxLvE7ZtDd/vIQ0RHv+3Mh5DR96p7cS7HsBhYIICDBCu8csTNWNO6tBWfqXPWekRuj2FNOGOZg==}
+
+  mdast-util-gfm-task-list-item@2.0.0:
+    resolution: {integrity: sha512-IrtvNvjxC1o06taBAVJznEnkiHxLFTzgonUdy8hzFVeDun0uTjxxrRGVaNFqkU1wJR3RBPEfsxmU6jDWPofrTQ==}
+
+  mdast-util-gfm@3.1.0:
+    resolution: {integrity: sha512-0ulfdQOM3ysHhCJ1p06l0b0VKlhU0wuQs3thxZQagjcjPrlFRqY215uZGHHJan9GEAXd9MbfPjFJz+qMkVR6zQ==}
+
+  mdast-util-mdx-expression@2.0.1:
+    resolution: {integrity: sha512-J6f+9hUp+ldTZqKRSg7Vw5V6MqjATc+3E4gf3CFNcuZNWD8XdyI6zQ8GqH7f8169MM6P7hMBRDVGnn7oHB9kXQ==}
+
+  mdast-util-mdx-jsx@3.2.0:
+    resolution: {integrity: sha512-lj/z8v0r6ZtsN/cGNNtemmmfoLAFZnjMbNyLzBafjzikOM+glrjNHPlf6lQDOTccj9n5b0PPihEBbhneMyGs1Q==}
+
+  mdast-util-mdxjs-esm@2.0.1:
+    resolution: {integrity: sha512-EcmOpxsZ96CvlP03NghtH1EsLtr0n9Tm4lPUJUBccV9RwUOneqSycg19n5HGzCf+10LozMRSObtVr3ee1WoHtg==}
+
+  mdast-util-phrasing@4.1.0:
+    resolution: {integrity: sha512-TqICwyvJJpBwvGAMZjj4J2n0X8QWp21b9l0o7eXyVJ25YNWYbJDVIyD1bZXE6WtV6RmKJVYmQAKWa0zWOABz2w==}
+
+  mdast-util-to-hast@13.2.1:
+    resolution: {integrity: sha512-cctsq2wp5vTsLIcaymblUriiTcZd0CwWtCbLvrOzYCDZoWyMNV8sZ7krj09FSnsiJi3WVsHLM4k6Dq/yaPyCXA==}
+
+  mdast-util-to-markdown@2.1.2:
+    resolution: {integrity: sha512-xj68wMTvGXVOKonmog6LwyJKrYXZPvlwabaryTjLh9LuvovB/KAH+kvi8Gjj+7rJjsFi23nkUxRQv1KqSroMqA==}
+
+  mdast-util-to-string@4.0.0:
+    resolution: {integrity: sha512-0H44vDimn51F0YwvxSJSm0eCDOJTRlmN0R1yBh4HLj9wiV1Dn0QoXGbvFAWj2hSItVTlCmBF1hqKlIyUBVFLPg==}
+
+  media-typer@0.3.0:
+    resolution: {integrity: sha512-dq+qelQ9akHpcOl/gUVRTxVIOkAJ1wR3QAvb4RsVjS8oVoFjDGTc679wJYmUmknUF5HwMLOgb5O+a3KxfWapPQ==}
+    engines: {node: '>= 0.6'}
+
+  media-typer@1.1.0:
+    resolution: {integrity: sha512-aisnrDP4GNe06UcKFnV5bfMNPBUw4jsLGaWwWfnH3v02GnBuXX2MCVn5RbrWo0j3pczUilYblq7fQ7Nw2t5XKw==}
+    engines: {node: '>= 0.8'}
+
+  merge-descriptors@1.0.3:
+    resolution: {integrity: sha512-gaNvAS7TZ897/rVaZ0nMtAyxNyi/pdbjbAwUpFQpN70GqnVfOiXpeUUMKRBmzXaSQ8DdTX4/0ms62r2K+hE6mQ==}
+
+  merge-descriptors@2.0.0:
+    resolution: {integrity: sha512-Snk314V5ayFLhp3fkUREub6WtjBfPdCPY1Ln8/8munuLuiYhsABgBVWsozAG+MWMbVEvcdcpbi9R7ww22l9Q3g==}
+    engines: {node: '>=18'}
+
+  merge-stream@2.0.0:
+    resolution: {integrity: sha512-abv/qOcuPfk3URPfDzmZU1LKmuw8kT+0nIHvKrKgFrwifol/doWcdA4ZqsWQ8ENrFKkd67Mfpo/LovbIUsbt3w==}
+
+  merge2@1.4.1:
+    resolution: {integrity: sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg==}
+    engines: {node: '>= 8'}
+
+  methods@1.1.2:
+    resolution: {integrity: sha512-iclAHeNqNm68zFtnZ0e+1L2yUIdvzNoauKU4WBA3VvH/vPFieF7qfRlwUZU+DA9P9bPXIS90ulxoUoCH23sV2w==}
+    engines: {node: '>= 0.6'}
+
+  micromark-core-commonmark@2.0.3:
+    resolution: {integrity: sha512-RDBrHEMSxVFLg6xvnXmb1Ayr2WzLAWjeSATAoxwKYJV94TeNavgoIdA0a9ytzDSVzBy2YKFK+emCPOEibLeCrg==}
+
+  micromark-extension-gfm-autolink-literal@2.1.0:
+    resolution: {integrity: sha512-oOg7knzhicgQ3t4QCjCWgTmfNhvQbDDnJeVu9v81r7NltNCVmhPy1fJRX27pISafdjL+SVc4d3l48Gb6pbRypw==}
+
+  micromark-extension-gfm-footnote@2.1.0:
+    resolution: {integrity: sha512-/yPhxI1ntnDNsiHtzLKYnE3vf9JZ6cAisqVDauhp4CEHxlb4uoOTxOCJ+9s51bIB8U1N1FJ1RXOKTIlD5B/gqw==}
+
+  micromark-extension-gfm-strikethrough@2.1.0:
+    resolution: {integrity: sha512-ADVjpOOkjz1hhkZLlBiYA9cR2Anf8F4HqZUO6e5eDcPQd0Txw5fxLzzxnEkSkfnD0wziSGiv7sYhk/ktvbf1uw==}
+
+  micromark-extension-gfm-table@2.1.1:
+    resolution: {integrity: sha512-t2OU/dXXioARrC6yWfJ4hqB7rct14e8f7m0cbI5hUmDyyIlwv5vEtooptH8INkbLzOatzKuVbQmAYcbWoyz6Dg==}
+
+  micromark-extension-gfm-tagfilter@2.0.0:
+    resolution: {integrity: sha512-xHlTOmuCSotIA8TW1mDIM6X2O1SiX5P9IuDtqGonFhEK0qgRI4yeC6vMxEV2dgyr2TiD+2PQ10o+cOhdVAcwfg==}
+
+  micromark-extension-gfm-task-list-item@2.1.0:
+    resolution: {integrity: sha512-qIBZhqxqI6fjLDYFTBIa4eivDMnP+OZqsNwmQ3xNLE4Cxwc+zfQEfbs6tzAo2Hjq+bh6q5F+Z8/cksrLFYWQQw==}
+
+  micromark-extension-gfm@3.0.0:
+    resolution: {integrity: sha512-vsKArQsicm7t0z2GugkCKtZehqUm31oeGBV/KVSorWSy8ZlNAv7ytjFhvaryUiCUJYqs+NoE6AFhpQvBTM6Q4w==}
+
+  micromark-factory-destination@2.0.1:
+    resolution: {integrity: sha512-Xe6rDdJlkmbFRExpTOmRj9N3MaWmbAgdpSrBQvCFqhezUn4AHqJHbaEnfbVYYiexVSs//tqOdY/DxhjdCiJnIA==}
+
+  micromark-factory-label@2.0.1:
+    resolution: {integrity: sha512-VFMekyQExqIW7xIChcXn4ok29YE3rnuyveW3wZQWWqF4Nv9Wk5rgJ99KzPvHjkmPXF93FXIbBp6YdW3t71/7Vg==}
+
+  micromark-factory-space@2.0.1:
+    resolution: {integrity: sha512-zRkxjtBxxLd2Sc0d+fbnEunsTj46SWXgXciZmHq0kDYGnck/ZSGj9/wULTV95uoeYiK5hRXP2mJ98Uo4cq/LQg==}
+
+  micromark-factory-title@2.0.1:
+    resolution: {integrity: sha512-5bZ+3CjhAd9eChYTHsjy6TGxpOFSKgKKJPJxr293jTbfry2KDoWkhBb6TcPVB4NmzaPhMs1Frm9AZH7OD4Cjzw==}
+
+  micromark-factory-whitespace@2.0.1:
+    resolution: {integrity: sha512-Ob0nuZ3PKt/n0hORHyvoD9uZhr+Za8sFoP+OnMcnWK5lngSzALgQYKMr9RJVOWLqQYuyn6ulqGWSXdwf6F80lQ==}
+
+  micromark-util-character@2.1.1:
+    resolution: {integrity: sha512-wv8tdUTJ3thSFFFJKtpYKOYiGP2+v96Hvk4Tu8KpCAsTMs6yi+nVmGh1syvSCsaxz45J6Jbw+9DD6g97+NV67Q==}
+
+  micromark-util-chunked@2.0.1:
+    resolution: {integrity: sha512-QUNFEOPELfmvv+4xiNg2sRYeS/P84pTW0TCgP5zc9FpXetHY0ab7SxKyAQCNCc1eK0459uoLI1y5oO5Vc1dbhA==}
+
+  micromark-util-classify-character@2.0.1:
+    resolution: {integrity: sha512-K0kHzM6afW/MbeWYWLjoHQv1sgg2Q9EccHEDzSkxiP/EaagNzCm7T/WMKZ3rjMbvIpvBiZgwR3dKMygtA4mG1Q==}
+
+  micromark-util-combine-extensions@2.0.1:
+    resolution: {integrity: sha512-OnAnH8Ujmy59JcyZw8JSbK9cGpdVY44NKgSM7E9Eh7DiLS2E9RNQf0dONaGDzEG9yjEl5hcqeIsj4hfRkLH/Bg==}
+
+  micromark-util-decode-numeric-character-reference@2.0.2:
+    resolution: {integrity: sha512-ccUbYk6CwVdkmCQMyr64dXz42EfHGkPQlBj5p7YVGzq8I7CtjXZJrubAYezf7Rp+bjPseiROqe7G6foFd+lEuw==}
+
+  micromark-util-decode-string@2.0.1:
+    resolution: {integrity: sha512-nDV/77Fj6eH1ynwscYTOsbK7rR//Uj0bZXBwJZRfaLEJ1iGBR6kIfNmlNqaqJf649EP0F3NWNdeJi03elllNUQ==}
+
+  micromark-util-encode@2.0.1:
+    resolution: {integrity: sha512-c3cVx2y4KqUnwopcO9b/SCdo2O67LwJJ/UyqGfbigahfegL9myoEFoDYZgkT7f36T0bLrM9hZTAaAyH+PCAXjw==}
+
+  micromark-util-html-tag-name@2.0.1:
+    resolution: {integrity: sha512-2cNEiYDhCWKI+Gs9T0Tiysk136SnR13hhO8yW6BGNyhOC4qYFnwF1nKfD3HFAIXA5c45RrIG1ub11GiXeYd1xA==}
+
+  micromark-util-normalize-identifier@2.0.1:
+    resolution: {integrity: sha512-sxPqmo70LyARJs0w2UclACPUUEqltCkJ6PhKdMIDuJ3gSf/Q+/GIe3WKl0Ijb/GyH9lOpUkRAO2wp0GVkLvS9Q==}
+
+  micromark-util-resolve-all@2.0.1:
+    resolution: {integrity: sha512-VdQyxFWFT2/FGJgwQnJYbe1jjQoNTS4RjglmSjTUlpUMa95Htx9NHeYW4rGDJzbjvCsl9eLjMQwGeElsqmzcHg==}
+
+  micromark-util-sanitize-uri@2.0.1:
+    resolution: {integrity: sha512-9N9IomZ/YuGGZZmQec1MbgxtlgougxTodVwDzzEouPKo3qFWvymFHWcnDi2vzV1ff6kas9ucW+o3yzJK9YB1AQ==}
+
+  micromark-util-subtokenize@2.1.0:
+    resolution: {integrity: sha512-XQLu552iSctvnEcgXw6+Sx75GflAPNED1qx7eBJ+wydBb2KCbRZe+NwvIEEMM83uml1+2WSXpBAcp9IUCgCYWA==}
+
+  micromark-util-symbol@2.0.1:
+    resolution: {integrity: sha512-vs5t8Apaud9N28kgCrRUdEed4UJ+wWNvicHLPxCa9ENlYuAY31M0ETy5y1vA33YoNPDFTghEbnh6efaE8h4x0Q==}
+
+  micromark-util-types@2.0.2:
+    resolution: {integrity: sha512-Yw0ECSpJoViF1qTU4DC6NwtC4aWGt1EkzaQB8KPPyCRR8z9TWeV0HbEFGTO+ZY1wB22zmxnJqhPyTpOVCpeHTA==}
+
+  micromark@4.0.2:
+    resolution: {integrity: sha512-zpe98Q6kvavpCr1NPVSCMebCKfD7CA2NqZ+rykeNhONIJBpc1tFKt9hucLGwha3jNTNI8lHpctWJWoimVF4PfA==}
+
+  micromatch@4.0.8:
+    resolution: {integrity: sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA==}
+    engines: {node: '>=8.6'}
+
+  mime-db@1.52.0:
+    resolution: {integrity: sha512-sPU4uV7dYlvtWJxwwxHD0PuihVNiE7TyAbQ5SWxDCB9mUYvOgroQOwYQQOKPJ8CIbE+1ETVlOoK1UC2nU3gYvg==}
+    engines: {node: '>= 0.6'}
+
+  mime-db@1.54.0:
+    resolution: {integrity: sha512-aU5EJuIN2WDemCcAp2vFBfp/m4EAhWJnUNSSw0ixs7/kXbd6Pg64EmwJkNdFhB8aWt1sH2CTXrLxo/iAGV3oPQ==}
+    engines: {node: '>= 0.6'}
+
+  mime-types@2.1.35:
+    resolution: {integrity: sha512-ZDY+bPm5zTTF+YpCrAU9nK0UgICYPT0QtT1NZWFv4s++TNkcgVaT0g6+4R2uI4MjQjzysHB1zxuWL50hzaeXiw==}
+    engines: {node: '>= 0.6'}
+
+  mime-types@3.0.2:
+    resolution: {integrity: sha512-Lbgzdk0h4juoQ9fCKXW4by0UJqj+nOOrI9MJ1sSj4nI8aI2eo1qmvQEie4VD1glsS250n15LsWsYtCugiStS5A==}
+    engines: {node: '>=18'}
+
+  mime@1.6.0:
+    resolution: {integrity: sha512-x0Vn8spI+wuJ1O6S7gnbaQg8Pxh4NNHb7KSINmEWKiPE4RKOplvijn+NkmYmmRgP68mc70j2EbeTFRsrswaQeg==}
+    engines: {node: '>=4'}
+    hasBin: true
+
+  mimic-fn@2.1.0:
+    resolution: {integrity: sha512-OqbOk5oEQeAZ8WXWydlu9HJjz9WVdEIvamMCcXmuqUYjTknH/sqsWvhQ3vgwKFRR1HpjvNBKQ37nbJgYzGqGcg==}
+    engines: {node: '>=6'}
+
+  mimic-function@5.0.1:
+    resolution: {integrity: sha512-VP79XUPxV2CigYP3jWwAUFSku2aKqBH7uTAapFWCBqutsbmDo96KY5o8uh6U+/YSIn5OxJnXp73beVkpqMIGhA==}
+    engines: {node: '>=18'}
+
+  minimatch@10.2.5:
+    resolution: {integrity: sha512-MULkVLfKGYDFYejP07QOurDLLQpcjk7Fw+7jXS2R2czRQzR56yHRveU5NDJEOviH+hETZKSkIk5c+T23GjFUMg==}
+    engines: {node: 18 || 20 || >=22}
+
+  minimist@1.2.8:
+    resolution: {integrity: sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA==}
+
+  motion-dom@12.40.0:
+    resolution: {integrity: sha512-HxU3ZaBwNPVQUBQf1xxgq+7JrPNZvjLVxgbpEZL7RrWJnsxOf0/OM+yrHG9ogLQ31Do/r57Oz2gQWPK+6q62mg==}
+
+  motion-utils@12.39.0:
+    resolution: {integrity: sha512-8nadJAJjTtqRkmRF36FoJTrywK9nnFmnPwnSMyxaOCU7GDjN9RTMJIxx9De8ErM+vpPhMccr/6fo5WciyQLnMQ==}
+
+  ms@2.0.0:
+    resolution: {integrity: sha512-Tpp60P6IUJDTuOq/5Z8cdskzJujfwqfOTkrwIwj7IRISpnkJnT6SyJ4PCPnGMoFjC9ddhal5KVIYtAt97ix05A==}
+
+  ms@2.1.3:
+    resolution: {integrity: sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==}
+
+  msw@2.14.6:
+    resolution: {integrity: sha512-ALe+N10S72cyx94cMcy3Zs4HhXCj35sgeAL4c+WTvKi0zWnbd8/h0lcFqv0mb2P+aSgAdD7p9HzvA0DiUPxsyg==}
+    engines: {node: '>=18'}
+    hasBin: true
+    peerDependencies:
+      typescript: '>= 4.8.x'
+    peerDependenciesMeta:
+      typescript:
+        optional: true
+
+  mute-stream@3.0.0:
+    resolution: {integrity: sha512-dkEJPVvun4FryqBmZ5KhDo0K9iDXAwn08tMLDinNdRBNPcYEDiWYysLcc6k3mjTMlbP9KyylvRpd4wFtwrT9rw==}
+    engines: {node: ^20.17.0 || >=22.9.0}
+
+  nanoid@3.3.12:
+    resolution: {integrity: sha512-ZB9RH/39qpq5Vu6Y+NmUaFhQR6pp+M2Xt76XBnEwDaGcVAqhlvxrl3B2bKS5D3NH3QR76v3aSrKaF/Kiy7lEtQ==}
+    engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1}
+    hasBin: true
+
+  napi-postinstall@0.3.4:
+    resolution: {integrity: sha512-PHI5f1O0EP5xJ9gQmFGMS6IZcrVvTjpXjz7Na41gTE7eE2hK11lg04CECCYEEjdc17EV4DO+fkGEtt7TpTaTiQ==}
+    engines: {node: ^12.20.0 || ^14.18.0 || >=16.0.0}
+    hasBin: true
+
+  natural-compare@1.4.0:
+    resolution: {integrity: sha512-OWND8ei3VtNC9h7V60qff3SVobHr996CTwgxubgyQYEpg290h9J0buyECNNJexkFm5sOajh5G116RYA1c8ZMSw==}
+
+  negotiator@0.6.3:
+    resolution: {integrity: sha512-+EUsqGPLsM+j/zdChZjsnX51g4XrHFOIXwfnCVPGlQk/k5giakcKsuxCObBRu6DSm9opw/O6slWbJdghQM4bBg==}
+    engines: {node: '>= 0.6'}
+
+  negotiator@1.0.0:
+    resolution: {integrity: sha512-8Ofs/AUQh8MaEcrlq5xOX0CQ9ypTF5dl78mjlMNfOK08fzpgTHQRQPBxcPlEtIw0yRpws+Zo/3r+5WRby7u3Gg==}
+    engines: {node: '>= 0.6'}
+
+  next-themes@0.4.6:
+    resolution: {integrity: sha512-pZvgD5L0IEvX5/9GWyHMf3m8BKiVQwsCMHfoFosXtXBMnaS0ZnIJ9ST4b4NqLVKDEm8QBxoNNGNaBv2JNF6XNA==}
+    peerDependencies:
+      react: ^16.8 || ^17 || ^18 || ^19 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17 || ^18 || ^19 || ^19.0.0-rc
+
+  next@16.2.6:
+    resolution: {integrity: sha512-qOVgKJg1+At15NpeUP+eJgCHvTCgXsogweq87Ri/Ix7PkqQHg4sdaXmSFqKlgaIXE4kW0g25LE68W87UANlHtw==}
+    engines: {node: '>=20.9.0'}
+    hasBin: true
+    peerDependencies:
+      '@opentelemetry/api': ^1.1.0
+      '@playwright/test': ^1.51.1
+      babel-plugin-react-compiler: '*'
+      react: ^18.2.0 || 19.0.0-rc-de68d2f4-20241204 || ^19.0.0
+      react-dom: ^18.2.0 || 19.0.0-rc-de68d2f4-20241204 || ^19.0.0
+      sass: ^1.3.0
+    peerDependenciesMeta:
+      '@opentelemetry/api':
+        optional: true
+      '@playwright/test':
+        optional: true
+      babel-plugin-react-compiler:
+        optional: true
+      sass:
+        optional: true
+
+  no-case@3.0.4:
+    resolution: {integrity: sha512-fgAN3jGAh+RoxUGZHTSOLJIqUc2wmoBwGR4tbpNAKmmovFoWq0OdRkb0VkldReO2a2iBT/OEulG9XSUc10r3zg==}
+
+  node-domexception@1.0.0:
+    resolution: {integrity: sha512-/jKZoMpw0F8GRwl4/eLROPA3cfcXtLApP0QzLmUT/HuPCZWyB7IY9ZrMeKw2O/nFIqPQB3PVM9aYm0F312AXDQ==}
+    engines: {node: '>=10.5.0'}
+    deprecated: Use your platform's native DOMException instead
+
+  node-fetch@3.3.2:
+    resolution: {integrity: sha512-dRB78srN/l6gqWulah9SrxeYnxeddIG30+GOqK/9OlLVyLg3HPnr6SqOWTWOXKRwC2eGYCkZ59NNuSgvSrpgOA==}
+    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
+
+  node-releases@2.0.44:
+    resolution: {integrity: sha512-5WUyunoPMsvvEhS8AxHtRzP+oA8UCkJ7YRxatWKjngndhDGLiqEVAQKWjFAiAiuL8zMRGzGSJxFnLetoa43qGQ==}
+
+  nodemon@3.1.14:
+    resolution: {integrity: sha512-jakjZi93UtB3jHMWsXL68FXSAosbLfY0In5gtKq3niLSkrWznrVBzXFNOEMJUfc9+Ke7SHWoAZsiMkNP3vq6Jw==}
+    engines: {node: '>=10'}
+    hasBin: true
+
+  normalize-path@3.0.0:
+    resolution: {integrity: sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA==}
+    engines: {node: '>=0.10.0'}
+
+  npm-run-path@4.0.1:
+    resolution: {integrity: sha512-S48WzZW777zhNIrn7gxOlISNAqi9ZC/uQFnRdbeIHhZhCA6UqpkOT8T1G7BvfdgP4Er8gF4sUbaS0i7QvIfCWw==}
+    engines: {node: '>=8'}
+
+  npm-run-path@6.0.0:
+    resolution: {integrity: sha512-9qny7Z9DsQU8Ou39ERsPU4OZQlSTP47ShQzuKZ6PRXpYLtIFgl/DEBYEXKlvcEa+9tHVcK8CF81Y2V72qaZhWA==}
+    engines: {node: '>=18'}
+
+  object-assign@4.1.1:
+    resolution: {integrity: sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==}
+    engines: {node: '>=0.10.0'}
+
+  object-inspect@1.13.4:
+    resolution: {integrity: sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew==}
+    engines: {node: '>= 0.4'}
+
+  object-treeify@1.1.33:
+    resolution: {integrity: sha512-EFVjAYfzWqWsBMRHPMAXLCDIJnpMhdWAqR7xG6M6a2cs6PMFpl/+Z20w9zDW4vkxOFfddegBKq9Rehd0bxWE7A==}
+    engines: {node: '>= 10'}
+
+  ollama@0.6.3:
+    resolution: {integrity: sha512-KEWEhIqE5wtfzEIZbDCLH51VFZ6Z3ZSa6sIOg/E/tBV8S51flyqBOXi+bRxlOYKDf8i327zG9eSTb8IJxvm3Zg==}
+
+  on-finished@2.4.1:
+    resolution: {integrity: sha512-oVlzkg3ENAhCk2zdv7IJwd/QUD4z2RxRwpkcGY8psCVcCYZNq4wYnVWALHM+brtuJjePWiYF/ClmuDr8Ch5+kg==}
+    engines: {node: '>= 0.8'}
+
+  onborda@1.2.5:
+    resolution: {integrity: sha512-S9EtQpKr8oYz7j0Bmr0w7BdG4Q4ud6QuNxBsSShzcf9khhuLEEjkbhYYMmdMlVa56QK/rXW/9pc8JJvBXUhOeA==}
+    peerDependencies:
+      '@radix-ui/react-portal': '>=1.1.1'
+      framer-motion: '>=11'
+      next: '>=13'
+      react: '>=18'
+      react-dom: '>=18'
+
+  once@1.4.0:
+    resolution: {integrity: sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==}
+
+  onetime@5.1.2:
+    resolution: {integrity: sha512-kbpaSSGJTWdAY5KPVeMOKXSrPtr8C8C7wodJbcsd51jRnmD+GZu8Y0VoU6Dm5Z4vWr0Ig/1NKuWRKf7j5aaYSg==}
+    engines: {node: '>=6'}
+
+  onetime@7.0.0:
+    resolution: {integrity: sha512-VXJjc87FScF88uafS3JllDgvAm+c/Slfz06lorj2uAY34rlUu0Nt+v8wreiImcrgAjjIHp1rXpTDlLOGw29WwQ==}
+    engines: {node: '>=18'}
+
+  open@11.0.0:
+    resolution: {integrity: sha512-smsWv2LzFjP03xmvFoJ331ss6h+jixfA4UUV/Bsiyuu4YJPfN+FIQGOIiv4w9/+MoHkfkJ22UIaQWRVFRfH6Vw==}
+    engines: {node: '>=20'}
+
+  openai@6.44.0:
+    resolution: {integrity: sha512-09/gH+8jH0RgUwsgWHAaxsKGRT5zVZ95IaJUnqAWj6XejIBmnFRwq2WUIF37VtDEsmGrtPmvCs5+yBSeZGWvkA==}
+    peerDependencies:
+      ws: ^8.18.0
+      zod: ^3.25 || ^4.0
+    peerDependenciesMeta:
+      ws:
+        optional: true
+      zod:
+        optional: true
+
+  optionator@0.9.4:
+    resolution: {integrity: sha512-6IpQ7mKUxRcZNLIObR0hz7lxsapSSIYNZJwXPGeF0mTVqGKFIXj1DQcMoT22S3ROcLyY/rz0PWaWZ9ayWmad9g==}
+    engines: {node: '>= 0.8.0'}
+
+  ora@8.2.0:
+    resolution: {integrity: sha512-weP+BZ8MVNnlCm8c0Qdc1WSWq4Qn7I+9CJGm7Qali6g44e/PUzbjNqJX5NJ9ljlNMosfJvg1fKEGILklK9cwnw==}
+    engines: {node: '>=18'}
+
+  outvariant@1.4.3:
+    resolution: {integrity: sha512-+Sl2UErvtsoajRDKCE5/dBz4DIvHXQQnAxtQTF04OJxY0+DyZXSo5P5Bb7XYWOh81syohlYL24hbDwxedPUJCA==}
+
+  p-limit@3.1.0:
+    resolution: {integrity: sha512-TYOanM3wGwNGsZN2cVTYPArw454xnXj5qmWF1bEoAc4+cU/ol7GVh7odevjp1FNHduHc3KZMcFduxU5Xc6uJRQ==}
+    engines: {node: '>=10'}
+
+  p-locate@5.0.0:
+    resolution: {integrity: sha512-LaNjtRWUBY++zB5nE/NwcaoMylSPk+S+ZHNB1TzdbMJMny6dynpAGt7X/tl/QYq3TIeE6nxHppbo2LGymrG5Pw==}
+    engines: {node: '>=10'}
+
+  parent-module@1.0.1:
+    resolution: {integrity: sha512-GQ2EWRpQV8/o+Aw8YqtfZZPfNRWZYkbidE9k5rpl/hC3vtHHBfGm2Ifi6qWV+coDGkrUKZAxE3Lot5kcsRlh+g==}
+    engines: {node: '>=6'}
+
+  parse-entities@4.0.2:
+    resolution: {integrity: sha512-GG2AQYWoLgL877gQIKeRPGO1xF9+eG1ujIb5soS5gPvLQ1y2o8FL90w2QWNdf9I361Mpp7726c+lj3U0qK1uGw==}
+
+  parse-json@5.2.0:
+    resolution: {integrity: sha512-ayCKvm/phCGxOkYRSCM82iDwct8/EonSEgCSxWxD7ve6jHggsFl4fZVQBPRNgQoKiuV/odhFrGzQXZwbifC8Rg==}
+    engines: {node: '>=8'}
+
+  parse-ms@4.0.0:
+    resolution: {integrity: sha512-TXfryirbmq34y8QBwgqCVLi+8oA3oWx2eAnSn62ITyEhEYaWRlVZ2DvMM9eZbMs/RfxPu/PK/aBLyGj4IrqMHw==}
+    engines: {node: '>=18'}
+
+  parseurl@1.3.3:
+    resolution: {integrity: sha512-CiyeOxFT/JZyN5m0z9PfXw4SCBJ6Sygz1Dpl0wqjlhDEGGBP1GnsUVEL0p63hoG1fcj3fHynXi9NYO4nWOL+qQ==}
+    engines: {node: '>= 0.8'}
+
+  path-browserify@1.0.1:
+    resolution: {integrity: sha512-b7uo2UCUOYZcnF/3ID0lulOJi/bafxa1xPe7ZPsammBSpjSWQkjNxlt635YGS2MiR9GjvuXCtz2emr3jbsz98g==}
+
+  path-exists@4.0.0:
+    resolution: {integrity: sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w==}
+    engines: {node: '>=8'}
+
+  path-key@3.1.1:
+    resolution: {integrity: sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==}
+    engines: {node: '>=8'}
+
+  path-key@4.0.0:
+    resolution: {integrity: sha512-haREypq7xkM7ErfgIyA0z+Bj4AGKlMSdlQE2jvJo6huWD1EdkKYV+G/T4nq0YEF2vgTT8kqMFKo1uHn950r4SQ==}
+    engines: {node: '>=12'}
+
+  path-to-regexp@0.1.13:
+    resolution: {integrity: sha512-A/AGNMFN3c8bOlvV9RreMdrv7jsmF9XIfDeCd87+I8RNg6s78BhJxMu69NEMHBSJFxKidViTEdruRwEk/WIKqA==}
+
+  path-to-regexp@6.3.0:
+    resolution: {integrity: sha512-Yhpw4T9C6hPpgPeA28us07OJeqZ5EzQTkbfwuhsUg0c237RomFoETJgmp2sa3F/41gfLE6G5cqcYwznmeEeOlQ==}
+
+  path-to-regexp@8.4.2:
+    resolution: {integrity: sha512-qRcuIdP69NPm4qbACK+aDogI5CBDMi1jKe0ry5rSQJz8JVLsC7jV8XpiJjGRLLol3N+R5ihGYcrPLTno6pAdBA==}
+
+  path-type@4.0.0:
+    resolution: {integrity: sha512-gDKb8aZMDeD/tZWs9P6+q0J9Mwkdl6xMV8TjnGP3qJVJ06bdMgkbBlLU8IdfOsIsFz2BW1rNVT3XuNEl8zPAvw==}
+    engines: {node: '>=8'}
+
+  picocolors@1.1.1:
+    resolution: {integrity: sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==}
+
+  picomatch@2.3.2:
+    resolution: {integrity: sha512-V7+vQEJ06Z+c5tSye8S+nHUfI51xoXIXjHQ99cQtKUkQqqO1kO/KCJUfZXuB47h/YBlDhah2H3hdUGXn8ie0oA==}
+    engines: {node: '>=8.6'}
+
+  picomatch@4.0.4:
+    resolution: {integrity: sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==}
+    engines: {node: '>=12'}
+
+  pkce-challenge@5.0.1:
+    resolution: {integrity: sha512-wQ0b/W4Fr01qtpHlqSqspcj3EhBvimsdh0KlHhH8HRZnMsEa0ea2fTULOXOS9ccQr3om+GcGRk4e+isrZWV8qQ==}
+    engines: {node: '>=16.20.0'}
+
+  postcss-selector-parser@6.0.10:
+    resolution: {integrity: sha512-IQ7TZdoaqbT+LCpShg46jnZVlhWD2w6iQYAcYXfHARZ7X1t/UGhhceQDs5X0cGqKvYlHNOuv7Oa1xmb0oQuA3w==}
+    engines: {node: '>=4'}
+
+  postcss-selector-parser@7.1.1:
+    resolution: {integrity: sha512-orRsuYpJVw8LdAwqqLykBj9ecS5/cRHlI5+nvTo8LcCKmzDmqVORXtOIYEEQuL9D4BxtA1lm5isAqzQZCoQ6Eg==}
+    engines: {node: '>=4'}
+
+  postcss@8.4.31:
+    resolution: {integrity: sha512-PS08Iboia9mts/2ygV3eLpY5ghnUcfLV/EXTOW1E2qYxJKGGBUtNjN76FYHnMs36RmARn41bC0AZmn+rR0OVpQ==}
+    engines: {node: ^10 || ^12 || >=14}
+
+  postcss@8.5.14:
+    resolution: {integrity: sha512-SoSL4+OSEtR99LHFZQiJLkT59C5B1amGO1NzTwj7TT1qCUgUO6hxOvzkOYxD+vMrXBM3XJIKzokoERdqQq/Zmg==}
+    engines: {node: ^10 || ^12 || >=14}
+
+  powershell-utils@0.1.0:
+    resolution: {integrity: sha512-dM0jVuXJPsDN6DvRpea484tCUaMiXWjuCn++HGTqUWzGDjv5tZkEZldAJ/UMlqRYGFrD/etByo4/xOuC/snX2A==}
+    engines: {node: '>=20'}
+
+  prelude-ls@1.2.1:
+    resolution: {integrity: sha512-vkcDPrRZo1QZLbn5RLGPpg/WmIQ65qoWWhcGKf/b5eplkkarX0m9z8ppCat4mlOqUsWpyNuYgO3VRyrYHSzX5g==}
+    engines: {node: '>= 0.8.0'}
+
+  prettier-linter-helpers@1.0.1:
+    resolution: {integrity: sha512-SxToR7P8Y2lWmv/kTzVLC1t/GDI2WGjMwNhLLE9qtH8Q13C+aEmuRlzDst4Up4s0Wc8sF2M+J57iB3cMLqftfg==}
+    engines: {node: '>=6.0.0'}
+
+  prettier@3.8.3:
+    resolution: {integrity: sha512-7igPTM53cGHMW8xWuVTydi2KO233VFiTNyF5hLJqpilHfmn8C8gPf+PS7dUT64YcXFbiMGZxS9pCSxL/Dxm/Jw==}
+    engines: {node: '>=14'}
+    hasBin: true
+
+  pretty-ms@9.3.0:
+    resolution: {integrity: sha512-gjVS5hOP+M3wMm5nmNOucbIrqudzs9v/57bWRHQWLYklXqoXKrVfYW2W9+glfGsqtPgpiz5WwyEEB+ksXIx3gQ==}
+    engines: {node: '>=18'}
+
+  prompts@2.4.2:
+    resolution: {integrity: sha512-NxNv/kLguCA7p3jE8oL2aEBsrJWgAakBpgmgK6lpPWV+WuOmY6r2/zbAVnP+T8bQlA0nzHXSJSJW0Hq7ylaD2Q==}
+    engines: {node: '>= 6'}
+
+  property-information@7.1.0:
+    resolution: {integrity: sha512-TwEZ+X+yCJmYfL7TPUOcvBZ4QfoT5YenQiJuX//0th53DE6w0xxLEtfK3iyryQFddXuvkIk51EEgrJQ0WJkOmQ==}
+
+  proxy-addr@2.0.7:
+    resolution: {integrity: sha512-llQsMLSUDUPT44jdrU/O37qlnifitDP+ZwrmmZcoSKyLKvtZxpyV0n2/bD/N4tBAAZ/gJEdZU7KMraoK1+XYAg==}
+    engines: {node: '>= 0.10'}
+
+  pstree.remy@1.1.8:
+    resolution: {integrity: sha512-77DZwxQmxKnu3aR542U+X8FypNzbfJ+C5XQDk3uWjWxn6151aIMGthWYRXTqT1E5oJvg+ljaa2OJi+VfvCOQ8w==}
+
+  punycode@2.3.1:
+    resolution: {integrity: sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==}
+    engines: {node: '>=6'}
+
+  qs@6.15.1:
+    resolution: {integrity: sha512-6YHEFRL9mfgcAvql/XhwTvf5jKcOiiupt2FiJxHkiX1z4j7WL8J/jRHYLluORvc1XxB5rV20KoeK00gVJamspg==}
+    engines: {node: '>=0.6'}
+
+  queue-microtask@1.2.3:
+    resolution: {integrity: sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A==}
+
+  radix-ui@1.4.3:
+    resolution: {integrity: sha512-aWizCQiyeAenIdUbqEpXgRA1ya65P13NKn/W8rWkcN0OPkRDxdBVLWnIEDsS2RpwCK2nobI7oMUSmexzTDyAmA==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  range-parser@1.2.1:
+    resolution: {integrity: sha512-Hrgsx+orqoygnmhFbKaHE6c296J+HTAQXoxEF6gNupROmmGJRoyzfG3ccAveqCBrwr/2yxQ5BVd/GTl5agOwSg==}
+    engines: {node: '>= 0.6'}
+
+  raw-body@2.5.3:
+    resolution: {integrity: sha512-s4VSOf6yN0rvbRZGxs8Om5CWj6seneMwK3oDb4lWDH0UPhWcxwOWw5+qk24bxq87szX1ydrwylIOp2uG1ojUpA==}
+    engines: {node: '>= 0.8'}
+
+  raw-body@3.0.2:
+    resolution: {integrity: sha512-K5zQjDllxWkf7Z5xJdV0/B0WTNqx6vxG70zJE4N0kBs4LovmEYWJzQGxC9bS9RAKu3bgM40lrd5zoLJ12MQ5BA==}
+    engines: {node: '>= 0.10'}
+
+  react-day-picker@10.0.1:
+    resolution: {integrity: sha512-eNh6BlwcYInWaJtRv18mXQ06Ys/H6rdTZAnTaSdOYJuTpwP1JMCHNd1FDRadA+gbeinq+psdULN5Xnowy9mV8w==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      '@types/react': '>=16.8.0'
+      react: '>=16.8.0'
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  react-diff-view@3.3.3:
+    resolution: {integrity: sha512-CPveApk6n7ZbkW7T6PoptR7LWAvD9hohTHZ7WnKnu3GZkTfUB5rvg486apPo94iYVi4fZd3Nt+rtBZ5877exoQ==}
+    peerDependencies:
+      react: '>=16.14.0'
+
+  react-dom@19.2.6:
+    resolution: {integrity: sha512-0prMI+hvBbPjsWnxDLxlCGyM8PN6UuWjEUCYmZhO67xIV9Xasa/r/vDnq+Xyq4Lo27g8QSbO5YzARu0D1Sps3g==}
+    peerDependencies:
+      react: ^19.2.6
+
+  react-i18next@17.0.8:
+    resolution: {integrity: sha512-0ooKbGLU8JXhe1zwpQUWIeXSgLPOfwJmgheWRIUpcoA0CpyabpGhayjdG+/eA5esC1AQ8h2jWpXjJfzQzeDOCw==}
+    peerDependencies:
+      i18next: '>= 26.2.0'
+      react: '>= 16.8.0'
+      react-dom: '*'
+      react-native: '*'
+      typescript: ^5 || ^6
+    peerDependenciesMeta:
+      react-dom:
+        optional: true
+      react-native:
+        optional: true
+      typescript:
+        optional: true
+
+  react-markdown@10.1.0:
+    resolution: {integrity: sha512-qKxVopLT/TyA6BX3Ue5NwabOsAzm0Q7kAPwq6L+wWDwisYs7R8vZ0nRXqq6rkueboxpkjvLGU9fWifiX/ZZFxQ==}
+    peerDependencies:
+      '@types/react': '>=18'
+      react: '>=18'
+
+  react-remove-scroll-bar@2.3.8:
+    resolution: {integrity: sha512-9r+yi9+mgU33AKcj6IbT9oRCO78WriSj6t/cF8DWBZJ9aOGPOTEDvdUDz1FwKim7QXWwmHqtdHnRJfhAxEG46Q==}
+    engines: {node: '>=10'}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  react-remove-scroll@2.7.2:
+    resolution: {integrity: sha512-Iqb9NjCCTt6Hf+vOdNIZGdTiH1QSqr27H/Ek9sv/a97gfueI/5h1s3yRi1nngzMUaOOToin5dI1dXKdXiF+u0Q==}
+    engines: {node: '>=10'}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  react-resizable-panels@4.11.2:
+    resolution: {integrity: sha512-+kfFbDZ8mygc7g0vxOcDzCVGuwiIUOnILqPoUHo6/uP+Mmyx6HzZU+kj1aOPDlktXuobYbr6BtQekvJwHRX4Eg==}
+    peerDependencies:
+      react: ^18.0.0 || ^19.0.0
+      react-dom: ^18.0.0 || ^19.0.0
+
+  react-router-dom@7.15.1:
+    resolution: {integrity: sha512-AzF62gjY6U9rkMq4RfP/r2EVtQ7DMfNMjyOp/flLTCrtRylLiK4wT4pSq6O8rOXZ2eXdZYJPEYe+ifomiv+Igg==}
+    engines: {node: '>=20.0.0'}
+    peerDependencies:
+      react: '>=18'
+      react-dom: '>=18'
+
+  react-router@7.15.1:
+    resolution: {integrity: sha512-R8rl9HhgikFYoPJymnUtPXWbnDb3oget6lQnfIoupbt61aT9aOhRkDsY2XRhZRyX1Z/8a5sL74fXmFNm3NRK5A==}
+    engines: {node: '>=20.0.0'}
+    peerDependencies:
+      react: '>=18'
+      react-dom: '>=18'
+    peerDependenciesMeta:
+      react-dom:
+        optional: true
+
+  react-style-singleton@2.2.3:
+    resolution: {integrity: sha512-b6jSvxvVnyptAiLjbkWLE/lOnR4lfTtDAl+eUC7RZy+QQWc6wRzIV2CE6xBuMmDxc2qIihtDCZD5NPOFl7fRBQ==}
+    engines: {node: '>=10'}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  react@19.2.6:
+    resolution: {integrity: sha512-sfWGGfavi0xr8Pg0sVsyHMAOziVYKgPLNrS7ig+ivMNb3wbCBw3KxtflsGBAwD3gYQlE/AEZsTLgToRrSCjb0Q==}
+    engines: {node: '>=0.10.0'}
+
+  readdirp@3.6.0:
+    resolution: {integrity: sha512-hOS089on8RduqdbhvQ5Z37A0ESjsqz6qnRcffsMU3495FuTdqSm+7bhJ29JvIOsBDEEnan5DPu9t3To9VRlMzA==}
+    engines: {node: '>=8.10.0'}
+
+  recast@0.23.11:
+    resolution: {integrity: sha512-YTUo+Flmw4ZXiWfQKGcwwc11KnoRAYgzAE2E7mXKCjSviTKShtxBsN6YUUBB2gtaBzKzeKunxhUwNHQuRryhWA==}
+    engines: {node: '>= 4'}
+
+  remark-gfm@4.0.1:
+    resolution: {integrity: sha512-1quofZ2RQ9EWdeN34S79+KExV1764+wCUGop5CPL1WGdD0ocPpu91lzPGbwWMECpEpd42kJGQwzRfyov9j4yNg==}
+
+  remark-parse@11.0.0:
+    resolution: {integrity: sha512-FCxlKLNGknS5ba/1lmpYijMUzX2esxW5xQqjWxw2eHFfS2MSdaHVINFmhjo+qN1WhZhNimq0dZATN9pH0IDrpA==}
+
+  remark-rehype@11.1.2:
+    resolution: {integrity: sha512-Dh7l57ianaEoIpzbp0PC9UKAdCSVklD8E5Rpw7ETfbTl3FqcOOgq5q2LVDhgGCkaBv7p24JXikPdvhhmHvKMsw==}
+
+  remark-stringify@11.0.0:
+    resolution: {integrity: sha512-1OSmLd3awB/t8qdoEOMazZkNsfVTeY4fTsgzcQFdXNq8ToTN4ZGwrMnlda4K6smTFKD+GRV6O48i6Z4iKgPPpw==}
+
+  require-directory@2.1.1:
+    resolution: {integrity: sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==}
+    engines: {node: '>=0.10.0'}
+
+  require-from-string@2.0.2:
+    resolution: {integrity: sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==}
+    engines: {node: '>=0.10.0'}
+
+  resolve-from@4.0.0:
+    resolution: {integrity: sha512-pb/MYmXstAkysRFx8piNI1tGFNQIFA3vkE3Gq4EuA1dF6gHp/+vgZqsCGJapvy8N3Q+4o7FwvquPJcnZ7RYy4g==}
+    engines: {node: '>=4'}
+
+  resolve-pkg-maps@1.0.0:
+    resolution: {integrity: sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw==}
+
+  restore-cursor@5.1.0:
+    resolution: {integrity: sha512-oMA2dcrw6u0YfxJQXm342bFKX/E4sG9rbTzO9ptUcR/e8A33cHuvStiYOwH7fszkZlZ1z/ta9AAoPk2F4qIOHA==}
+    engines: {node: '>=18'}
+
+  rettime@0.11.11:
+    resolution: {integrity: sha512-ILJRqVWBCTlg9r42fFgwVZx1gnFAcQF8mRoMkbgQfIrjEDf9nbBFDFx00oloOa+Q869FUtaYDXZvEfnecQSCoQ==}
+
+  reusify@1.1.0:
+    resolution: {integrity: sha512-g6QUff04oZpHs0eG5p83rFLhHeV00ug/Yf9nZM6fLeUrPguBTkTQOdpAWWspMh55TZfVQDPaN3NQJfbVRAxdIw==}
+    engines: {iojs: '>=1.0.0', node: '>=0.10.0'}
+
+  rfdc@1.4.1:
+    resolution: {integrity: sha512-q1b3N5QkRUWUl7iyylaaj3kOpIT0N2i9MqIEQXP73GVsN9cw3fdx8X63cEmWhJGi2PPCF23Ijp7ktmd39rawIA==}
+
+  rolldown@1.0.1:
+    resolution: {integrity: sha512-X0KQHljNnEkWNqqiz9zJrGunh1B0HgOxLXvnFpCOcadzcy5qohZ3tqMEUg00vncoRovXuK3ZqCT9KnnKzoInFQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    hasBin: true
+
+  router@2.2.0:
+    resolution: {integrity: sha512-nLTrUKm2UyiL7rlhapu/Zl45FwNgkZGaCpZbIHajDYgwlJCOzLSk+cIPAnsEqV955GjILJnKbdQC1nVPz+gAYQ==}
+    engines: {node: '>= 18'}
+
+  run-applescript@7.1.0:
+    resolution: {integrity: sha512-DPe5pVFaAsinSaV6QjQ6gdiedWDcRCbUuiQfQa2wmWV7+xC9bGulGI8+TdRmoFkAPaBXk8CrAbnlY2ISniJ47Q==}
+    engines: {node: '>=18'}
+
+  run-parallel@1.2.0:
+    resolution: {integrity: sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA==}
+
+  rxjs@7.8.2:
+    resolution: {integrity: sha512-dhKf903U/PQZY6boNNtAGdWbG85WAbjT/1xYoZIC7FAY0yWapOBQVsVrDl58W86//e1VpMNBtRV4MaXfdMySFA==}
+
+  safe-buffer@5.2.1:
+    resolution: {integrity: sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ==}
+
+  safer-buffer@2.1.2:
+    resolution: {integrity: sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==}
+
+  scheduler@0.27.0:
+    resolution: {integrity: sha512-eNv+WrVbKu1f3vbYJT/xtiF5syA5HPIMtf9IgY/nKg0sWqzAUEvqY/xm7OcZc/qafLx/iO9FgOmeSAp4v5ti/Q==}
+
+  section-matter@1.0.0:
+    resolution: {integrity: sha512-vfD3pmTzGpufjScBh50YHKzEu2lxBWhVEHsNGoEXmCmn2hKGfeNLYMzCJpe8cD7gqX7TJluOVpBkAequ6dgMmA==}
+    engines: {node: '>=4'}
+
+  semver@6.3.1:
+    resolution: {integrity: sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==}
+    hasBin: true
+
+  semver@7.8.0:
+    resolution: {integrity: sha512-AcM7dV/5ul4EekoQ29Agm5vri8JNqRyj39o0qpX6vDF2GZrtutZl5RwgD1XnZjiTAfncsJhMI48QQH3sN87YNA==}
+    engines: {node: '>=10'}
+    hasBin: true
+
+  semver@7.8.1:
+    resolution: {integrity: sha512-rkVq3IXh+4FDGch+KwzX3aV9W3kO54GyEgpvBzSyctDA6Xtd7RJQV1xmXbeQp5v7+VzLOfVqiutSE6GICgPFvg==}
+    engines: {node: '>=10'}
+    hasBin: true
+
+  send@0.19.2:
+    resolution: {integrity: sha512-VMbMxbDeehAxpOtWJXlcUS5E8iXh6QmN+BkRX1GARS3wRaXEEgzCcB10gTQazO42tpNIya8xIyNx8fll1OFPrg==}
+    engines: {node: '>= 0.8.0'}
+
+  send@1.2.1:
+    resolution: {integrity: sha512-1gnZf7DFcoIcajTjTwjwuDjzuz4PPcY2StKPlsGAQ1+YH20IRVrBaXSWmdjowTJ6u8Rc01PoYOGHXfP1mYcZNQ==}
+    engines: {node: '>= 18'}
+
+  serve-static@1.16.3:
+    resolution: {integrity: sha512-x0RTqQel6g5SY7Lg6ZreMmsOzncHFU7nhnRWkKgWuMTu5NN0DR5oruckMqRvacAN9d5w6ARnRBXl9xhDCgfMeA==}
+    engines: {node: '>= 0.8.0'}
+
+  serve-static@2.2.1:
+    resolution: {integrity: sha512-xRXBn0pPqQTVQiC8wyQrKs2MOlX24zQ0POGaj0kultvoOCstBQM5yvOhAVSUwOMjQtTvsPWoNCHfPGwaaQJhTw==}
+    engines: {node: '>= 18'}
+
+  set-cookie-parser@2.7.2:
+    resolution: {integrity: sha512-oeM1lpU/UvhTxw+g3cIfxXHyJRc/uidd3yK1P242gzHds0udQBYzs3y8j4gCCW+ZJ7ad0yctld8RYO+bdurlvw==}
+
+  set-cookie-parser@3.1.0:
+    resolution: {integrity: sha512-kjnC1DXBHcxaOaOXBHBeRtltsDG2nUiUni+jP92M9gYdW12rsmx92UsfpH7o5tDRs7I1ZZPSQJQGv3UaRfCiuw==}
+
+  setprototypeof@1.2.0:
+    resolution: {integrity: sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw==}
+
+  shadcn-prose@1.2.1:
+    resolution: {integrity: sha512-WKYSb3lZ4/iC7YPrZP8HeO1ywQJE94iuBrTaUmPm0C3tPrM+ymWVmKyuzabCTtAkqWQAPOO7SOB40UcDuzsxyw==}
+    deprecated: 'You can now install this as a shadcn component with: npx kibo-ui add typography'
+
+  shadcn@4.7.0:
+    resolution: {integrity: sha512-70fwnesNrY1GgeD7Kdzn+3SsYeyfibm8immsA5L68+OusoPTvYF01oWExl8/latKpMpvVXcbgdbbE6VFBJQ38w==}
+    hasBin: true
+
+  shallow-equal@3.1.0:
+    resolution: {integrity: sha512-pfVOw8QZIXpMbhBWvzBISicvToTiM5WBF1EeAUZDDSb5Dt29yl4AYbyywbJFSEsRUMr7gJaxqCdr4L3tQf9wVg==}
+
+  sharp@0.34.5:
+    resolution: {integrity: sha512-Ou9I5Ft9WNcCbXrU9cMgPBcCK8LiwLqcbywW3t4oDV37n1pzpuNLsYiAV8eODnjbtQlSDwZ2cUEeQz4E54Hltg==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+
+  shebang-command@2.0.0:
+    resolution: {integrity: sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==}
+    engines: {node: '>=8'}
+
+  shebang-regex@3.0.0:
+    resolution: {integrity: sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==}
+    engines: {node: '>=8'}
+
+  shell-quote@1.8.3:
+    resolution: {integrity: sha512-ObmnIF4hXNg1BqhnHmgbDETF8dLPCggZWBjkQfhZpbszZnYur5DUljTcCHii5LC3J5E0yeO/1LIMyH+UvHQgyw==}
+    engines: {node: '>= 0.4'}
+
+  side-channel-list@1.0.1:
+    resolution: {integrity: sha512-mjn/0bi/oUURjc5Xl7IaWi/OJJJumuoJFQJfDDyO46+hBWsfaVM65TBHq2eoZBhzl9EchxOijpkbRC8SVBQU0w==}
+    engines: {node: '>= 0.4'}
+
+  side-channel-map@1.0.1:
+    resolution: {integrity: sha512-VCjCNfgMsby3tTdo02nbjtM/ewra6jPHmpThenkTYh8pG9ucZ/1P8So4u4FGBek/BjpOVsDCMoLA/iuBKIFXRA==}
+    engines: {node: '>= 0.4'}
+
+  side-channel-weakmap@1.0.2:
+    resolution: {integrity: sha512-WPS/HvHQTYnHisLo9McqBHOJk2FkHO/tlpvldyrnem4aeQp4hai3gythswg6p01oSoTl58rcpiFAjF2br2Ak2A==}
+    engines: {node: '>= 0.4'}
+
+  side-channel@1.1.0:
+    resolution: {integrity: sha512-ZX99e6tRweoUXqR+VBrslhda51Nh5MTQwou5tnUDgbtyM0dBgmhEDtWGP/xbKn6hqfPRHujUNwz5fy/wbbhnpw==}
+    engines: {node: '>= 0.4'}
+
+  signal-exit@3.0.7:
+    resolution: {integrity: sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ==}
+
+  signal-exit@4.1.0:
+    resolution: {integrity: sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw==}
+    engines: {node: '>=14'}
+
+  simple-update-notifier@2.0.0:
+    resolution: {integrity: sha512-a2B9Y0KlNXl9u/vsW6sTIu9vGEpfKu2wRV6l1H3XEas/0gUIzGzBoP/IouTcUQbm9JWZLH3COxyn03TYlFax6w==}
+    engines: {node: '>=10'}
+
+  sisteransi@1.0.5:
+    resolution: {integrity: sha512-bLGGlR1QxBcynn2d5YmDX4MGjlZvy2MRBDRNHLJ8VI6l6+9FUiyTFNJ0IveOSP0bcXgVDPRcfGqA0pjaqUpfVg==}
+
+  slice-ansi@7.1.2:
+    resolution: {integrity: sha512-iOBWFgUX7caIZiuutICxVgX1SdxwAVFFKwt1EvMYYec/NWO5meOJ6K5uQxhrYBdQJne4KxiqZc+KptFOWFSI9w==}
+    engines: {node: '>=18'}
+
+  slice-ansi@8.0.0:
+    resolution: {integrity: sha512-stxByr12oeeOyY2BlviTNQlYV5xOj47GirPr4yA1hE9JCtxfQN0+tVbkxwCtYDQWhEKWFHsEK48ORg5jrouCAg==}
+    engines: {node: '>=20'}
+
+  snake-case@3.0.4:
+    resolution: {integrity: sha512-LAOh4z89bGQvl9pFfNF8V146i7o7/CqFPbqzYgP+yYzDIDeS9HaNFtXABamRW+AQzEVODcvE79ljJ+8a9YSdMg==}
+
+  sonner@2.0.7:
+    resolution: {integrity: sha512-W6ZN4p58k8aDKA4XPcx2hpIQXBRAgyiWVkYhT7CvK6D3iAu7xjvVyhQHg2/iaKJZ1XVJ4r7XuwGL+WGEK37i9w==}
+    peerDependencies:
+      react: ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+      react-dom: ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+
+  source-map-js@1.2.1:
+    resolution: {integrity: sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==}
+    engines: {node: '>=0.10.0'}
+
+  source-map@0.6.1:
+    resolution: {integrity: sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==}
+    engines: {node: '>=0.10.0'}
+
+  space-separated-tokens@2.0.2:
+    resolution: {integrity: sha512-PEGlAwrG8yXGXRjW32fGbg66JAlOAwbObuqVoJpv/mRgoWDQfgH1wDPvtzWyUSNAXBGSk8h755YDbbcEy3SH2Q==}
+
+  spawn-command@0.0.2:
+    resolution: {integrity: sha512-zC8zGoGkmc8J9ndvml8Xksr1Amk9qBujgbF0JAIWO7kXr43w0h/0GJNM/Vustixu+YE8N/MTrQ7N31FvHUACxQ==}
+
+  sprintf-js@1.0.3:
+    resolution: {integrity: sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g==}
+
+  stable-hash-x@0.2.0:
+    resolution: {integrity: sha512-o3yWv49B/o4QZk5ZcsALc6t0+eCelPc44zZsLtCQnZPDwFpDYSWcDnrv2TtMmMbQ7uKo3J0HTURCqckw23czNQ==}
+    engines: {node: '>=12.0.0'}
+
+  statuses@2.0.2:
+    resolution: {integrity: sha512-DvEy55V3DB7uknRo+4iOGT5fP1slR8wQohVdknigZPMpMstaKJQWhwiYBACJE3Ul2pTnATihhBYnRhZQHGBiRw==}
+    engines: {node: '>= 0.8'}
+
+  stdin-discarder@0.2.2:
+    resolution: {integrity: sha512-UhDfHmA92YAlNnCfhmq0VeNL5bDbiZGg7sZ2IvPsXubGkiNa9EC+tUTsjBRsYUAz87btI6/1wf4XoVvQ3uRnmQ==}
+    engines: {node: '>=18'}
+
+  strict-event-emitter@0.5.1:
+    resolution: {integrity: sha512-vMgjE/GGEPEFnhFub6pa4FmJBRBVOLpIII2hvCZ8Kzb7K0hlHo7mQv6xYrBvCL2LtAIBwFUK8wvuJgTVSQ5MFQ==}
+
+  string-argv@0.3.2:
+    resolution: {integrity: sha512-aqD2Q0144Z+/RqG52NeHEkZauTAUWJO8c6yTftGJKO3Tja5tUgIfmIl6kExvhtxSDP7fXB6DvzkfMpCd/F3G+Q==}
+    engines: {node: '>=0.6.19'}
+
+  string-format@2.0.0:
+    resolution: {integrity: sha512-bbEs3scLeYNXLecRRuk6uJxdXUSj6le/8rNPHChIJTn2V79aXVTR1EH2OH5zLKKoz0V02fOUKZZcw01pLUShZA==}
+
+  string-width@4.2.3:
+    resolution: {integrity: sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==}
+    engines: {node: '>=8'}
+
+  string-width@7.2.0:
+    resolution: {integrity: sha512-tsaTIkKW9b4N+AEj+SVA+WhJzV7/zMhcSu78mLKWSk7cXMOSHsBKFWUs0fWwq8QyK3MgJBQRX6Gbi4kYbdvGkQ==}
+    engines: {node: '>=18'}
+
+  string-width@8.2.1:
+    resolution: {integrity: sha512-IIaP0g3iy9Cyy18w3M9YcaDudujEAVHKt3a3QJg1+sr/oX96TbaGUubG0hJyCjCBThFH+tFpcIyoUHUn1ogaLA==}
+    engines: {node: '>=20'}
+
+  stringify-entities@4.0.4:
+    resolution: {integrity: sha512-IwfBptatlO+QCJUo19AqvrPNqlVMpW9YEL2LIVY+Rpv2qsjCGxaDLNRgeGsQWJhfItebuJhsGSLjaBbNSQ+ieg==}
+
+  stringify-object@5.0.0:
+    resolution: {integrity: sha512-zaJYxz2FtcMb4f+g60KsRNFOpVMUyuJgA51Zi5Z1DOTC3S59+OQiVOzE9GZt0x72uBGWKsQIuBKeF9iusmKFsg==}
+    engines: {node: '>=14.16'}
+
+  strip-ansi@6.0.1:
+    resolution: {integrity: sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==}
+    engines: {node: '>=8'}
+
+  strip-ansi@7.2.0:
+    resolution: {integrity: sha512-yDPMNjp4WyfYBkHnjIRLfca1i6KMyGCtsVgoKe/z1+6vukgaENdgGBZt+ZmKPc4gavvEZ5OgHfHdrazhgNyG7w==}
+    engines: {node: '>=12'}
+
+  strip-bom-string@1.0.0:
+    resolution: {integrity: sha512-uCC2VHvQRYu+lMh4My/sFNmF2klFymLX1wHJeXnbEJERpV/ZsVuonzerjfrGpIGF7LBVa1O7i9kjiWvJiFck8g==}
+    engines: {node: '>=0.10.0'}
+
+  strip-bom@3.0.0:
+    resolution: {integrity: sha512-vavAMRXOgBVNF6nyEEmL3DBK19iRpDcoIwW+swQ+CbGiu7lju6t+JklA1MHweoWtadgt4ISVUsXLyDq34ddcwA==}
+    engines: {node: '>=4'}
+
+  strip-final-newline@2.0.0:
+    resolution: {integrity: sha512-BrpvfNAE3dcvq7ll3xVumzjKjZQ5tI1sEUIKr3Uoks0XUl45St3FlatVqef9prk4jRDzhW6WZg+3bk93y6pLjA==}
+    engines: {node: '>=6'}
+
+  strip-final-newline@4.0.0:
+    resolution: {integrity: sha512-aulFJcD6YK8V1G7iRB5tigAP4TsHBZZrOV8pjV++zdUwmeV8uzbY7yn6h9MswN62adStNZFuCIx4haBnRuMDaw==}
+    engines: {node: '>=18'}
+
+  style-to-js@1.1.21:
+    resolution: {integrity: sha512-RjQetxJrrUJLQPHbLku6U/ocGtzyjbJMP9lCNK7Ag0CNh690nSH8woqWH9u16nMjYBAok+i7JO1NP2pOy8IsPQ==}
+
+  style-to-object@1.0.14:
+    resolution: {integrity: sha512-LIN7rULI0jBscWQYaSswptyderlarFkjQ+t79nzty8tcIAceVomEVlLzH5VP4Cmsv6MtKhs7qaAiwlcp+Mgaxw==}
+
+  styled-jsx@5.1.6:
+    resolution: {integrity: sha512-qSVyDTeMotdvQYoHWLNGwRFJHC+i+ZvdBRYosOFgC+Wg1vx4frN2/RG/NA7SYqqvKNLf39P2LSRA2pu6n0XYZA==}
+    engines: {node: '>= 12.0.0'}
+    peerDependencies:
+      '@babel/core': '*'
+      babel-plugin-macros: '*'
+      react: '>= 16.8.0 || 17.x.x || ^18.0.0-0 || ^19.0.0-0'
+    peerDependenciesMeta:
+      '@babel/core':
+        optional: true
+      babel-plugin-macros:
+        optional: true
+
+  supports-color@5.5.0:
+    resolution: {integrity: sha512-QjVjwdXIt408MIiAqCX4oUKsgU2EqAGzs2Ppkm4aQYbjm+ZEWEcW4SfFNTr4uMNZma0ey4f5lgLrkB0aX0QMow==}
+    engines: {node: '>=4'}
+
+  supports-color@7.2.0:
+    resolution: {integrity: sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==}
+    engines: {node: '>=8'}
+
+  supports-color@8.1.1:
+    resolution: {integrity: sha512-MpUEN2OodtUzxvKQl72cUF7RQ5EiHsGvSsVG0ia9c5RbWGL2CI4C7EpPS8UTBIplnlzZiNuV56w+FuNxy3ty2Q==}
+    engines: {node: '>=10'}
+
+  svg-parser@2.0.4:
+    resolution: {integrity: sha512-e4hG1hRwoOdRb37cIMSgzNsxyzKfayW6VOflrwvR+/bzrkyxY/31WkbgnQpgtrNp1SdpJvpUAGTa/ZoiPNDuRQ==}
+
+  synckit@0.11.12:
+    resolution: {integrity: sha512-Bh7QjT8/SuKUIfObSXNHNSK6WHo6J1tHCqJsuaFDP7gP0fkzSfTxI8y85JrppZ0h8l0maIgc2tfuZQ6/t3GtnQ==}
+    engines: {node: ^14.18.0 || >=16.0.0}
+
+  tagged-tag@1.0.0:
+    resolution: {integrity: sha512-yEFYrVhod+hdNyx7g5Bnkkb0G6si8HJurOoOEgC8B/O0uXLHlaey/65KRv6cuWBNhBgHKAROVpc7QyYqE5gFng==}
+    engines: {node: '>=20'}
+
+  tailwind-merge@3.6.0:
+    resolution: {integrity: sha512-uxL7qAVQriqRQPAyK3pj66VqskWqoZ37PW94jwOTwNfq/z9oyu1V+eqrZqtR2+fCiXdYOZe/Modt8GtvqNzu+w==}
+
+  tailwindcss@4.3.0:
+    resolution: {integrity: sha512-y6nxMGB1nMW9R6k96e5gdIFzcfL/gTJRNaqGes1YvkLnPVXzWgbqFF2yLC0T8G774n24cx3Pe8XrKoniCOAH+Q==}
+
+  tapable@2.3.3:
+    resolution: {integrity: sha512-uxc/zpqFg6x7C8vOE7lh6Lbda8eEL9zmVm/PLeTPBRhh1xCgdWaQ+J1CUieGpIfm2HdtsUpRv+HshiasBMcc6A==}
+    engines: {node: '>=6'}
+
+  tiny-invariant@1.3.3:
+    resolution: {integrity: sha512-+FbBPE1o9QAYvviau/qC5SE3caw21q3xkvWKBtja5vgqOWIHHJ3ioaq1VPfn/Szqctz2bU/oYeKd9/z5BL+PVg==}
+
+  tinyexec@1.1.2:
+    resolution: {integrity: sha512-dAqSqE/RabpBKI8+h26GfLq6Vb3JVXs30XYQjdMjaj/c2tS8IYYMbIzP599KtRj7c57/wYApb3QjgRgXmrCukA==}
+    engines: {node: '>=18'}
+
+  tinyglobby@0.2.16:
+    resolution: {integrity: sha512-pn99VhoACYR8nFHhxqix+uvsbXineAasWm5ojXoN8xEwK5Kd3/TrhNn1wByuD52UxWRLy8pu+kRMniEi6Eq9Zg==}
+    engines: {node: '>=12.0.0'}
+
+  tldts-core@7.0.30:
+    resolution: {integrity: sha512-uiHN8PIB1VmWyS98eZYja4xzlYqeFZVjb4OuYlJQnZAuJhMw4PbKQOKgHKhBdJR3FE/t5mUQ1Kd80++B+qhD1Q==}
+
+  tldts@7.0.30:
+    resolution: {integrity: sha512-ELrFxuqsDdHUwoh0XxDbxuLD3Wnz49Z57IFvTtvWy1hJdcMZjXLIuonjilCiWHlT2GbE4Wlv1wKVTzDFnXH1aw==}
+    hasBin: true
+
+  to-regex-range@5.0.1:
+    resolution: {integrity: sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ==}
+    engines: {node: '>=8.0'}
+
+  toidentifier@1.0.1:
+    resolution: {integrity: sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA==}
+    engines: {node: '>=0.6'}
+
+  touch@3.1.1:
+    resolution: {integrity: sha512-r0eojU4bI8MnHr8c5bNo7lJDdI2qXlWWJk6a9EAFG7vbhTjElYhBVS3/miuE0uOuoLdb8Mc/rVfsmm6eo5o9GA==}
+    hasBin: true
+
+  tough-cookie@6.0.1:
+    resolution: {integrity: sha512-LktZQb3IeoUWB9lqR5EWTHgW/VTITCXg4D21M+lvybRVdylLrRMnqaIONLVb5mav8vM19m44HIcGq4qASeu2Qw==}
+    engines: {node: '>=16'}
+
+  tree-kill@1.2.2:
+    resolution: {integrity: sha512-L0Orpi8qGpRG//Nd+H90vFB+3iHnue1zSSGmNOOCh1GLJ7rUKVwV2HvijphGQS2UmhUZewS9VgvxYIdgr+fG1A==}
+    hasBin: true
+
+  trim-lines@3.0.1:
+    resolution: {integrity: sha512-kRj8B+YHZCc9kQYdWfJB2/oUl9rA99qbowYYBtr4ui4mZyAQ2JpvVBd/6U2YloATfqBhBTSMhTpgBHtU0Mf3Rg==}
+
+  trough@2.2.0:
+    resolution: {integrity: sha512-tmMpK00BjZiUyVyvrBK7knerNgmgvcV/KLVyuma/SC+TQN167GrMRciANTz09+k3zW8L8t60jWO1GpfkZdjTaw==}
+
+  ts-api-utils@2.5.0:
+    resolution: {integrity: sha512-OJ/ibxhPlqrMM0UiNHJ/0CKQkoKF243/AEmplt3qpRgkW8VG7IfOS41h7V8TjITqdByHzrjcS/2si+y4lIh8NA==}
+    engines: {node: '>=18.12'}
+    peerDependencies:
+      typescript: '>=4.8.4'
+
+  ts-morph@26.0.0:
+    resolution: {integrity: sha512-ztMO++owQnz8c/gIENcM9XfCEzgoGphTv+nKpYNM1bgsdOVC/jRZuEBf6N+mLLDNg68Kl+GgUZfOySaRiG1/Ug==}
+
+  ts-node@10.9.2:
+    resolution: {integrity: sha512-f0FFpIdcHgn8zcPSbf1dRevwt047YMnaiJM3u2w2RewrB+fob/zePZcrOyQoLMMO7aBIddLcQIEK5dYjkLnGrQ==}
+    hasBin: true
+    peerDependencies:
+      '@swc/core': '>=1.2.50'
+      '@swc/wasm': '>=1.2.50'
+      '@types/node': '*'
+      typescript: '>=2.7'
+    peerDependenciesMeta:
+      '@swc/core':
+        optional: true
+      '@swc/wasm':
+        optional: true
+
+  tsconfig-paths@4.2.0:
+    resolution: {integrity: sha512-NoZ4roiN7LnbKn9QqE1amc9DJfzvZXxF4xDavcOWt1BPkdx+m+0gJuPM+S0vCe7zTJMYUP0R8pO2XMr+Y8oLIg==}
+    engines: {node: '>=6'}
+
+  tslib@2.8.1:
+    resolution: {integrity: sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==}
+
+  tw-animate-css@1.4.0:
+    resolution: {integrity: sha512-7bziOlRqH0hJx80h/3mbicLW7o8qLsH5+RaLR2t+OHM3D0JlWGODQKQ4cxbK7WlvmUxpcj6Kgu6EKqjrGFe3QQ==}
+
+  type-check@0.4.0:
+    resolution: {integrity: sha512-XleUoc9uwGXqjWwXaUTZAmzMcFZ5858QA2vvx1Ur5xIcixXIP+8LnFDgRplU30us6teqdlskFfu+ae4K79Ooew==}
+    engines: {node: '>= 0.8.0'}
+
+  type-fest@5.6.0:
+    resolution: {integrity: sha512-8ZiHFm91orbSAe2PSAiSVBVko18pbhbiB3U9GglSzF/zCGkR+rxpHx6sEMCUm4kxY4LjDIUGgCfUMtwfZfjfUA==}
+    engines: {node: '>=20'}
+
+  type-is@1.6.18:
+    resolution: {integrity: sha512-TkRKr9sUTxEH8MdfuCSP7VizJyzRNMjj2J2do2Jr3Kym598JVdEksuzPQCnlFPW4ky9Q+iA+ma9BGm06XQBy8g==}
+    engines: {node: '>= 0.6'}
+
+  type-is@2.1.0:
+    resolution: {integrity: sha512-faYHw0anBbc/kWF3zFTEnxSFOAGUX9GFbOBthvDdLsIlEoWOFOtS0zgCiQYwIskL9iGXZL3kAXD8OoZ4GmMATA==}
+    engines: {node: '>= 18'}
+
+  typescript-eslint@8.59.3:
+    resolution: {integrity: sha512-KgusgyDgG4LI8Ih/sWaCtZ06tckLAS5CvT5A4D1Q7bYVoAAyzwiZvE4BmwDHkhRVkvhRBepKeASoFzQetha7Fg==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      eslint: ^8.57.0 || ^9.0.0 || ^10.0.0
+      typescript: '>=4.8.4 <6.1.0'
+
+  typescript@5.9.3:
+    resolution: {integrity: sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==}
+    engines: {node: '>=14.17'}
+    hasBin: true
+
+  typescript@6.0.3:
+    resolution: {integrity: sha512-y2TvuxSZPDyQakkFRPZHKFm+KKVqIisdg9/CZwm9ftvKXLP8NRWj38/ODjNbr43SsoXqNuAisEf1GdCxqWcdBw==}
+    engines: {node: '>=14.17'}
+    hasBin: true
+
+  undefsafe@2.0.5:
+    resolution: {integrity: sha512-WxONCrssBM8TSPRqN5EmsjVrsv4A8X12J4ArBiiayv3DyyG3ZlIg6yysuuSYdZsVz3TKcTg2fd//Ujd4CHV1iA==}
+
+  undici-types@6.21.0:
+    resolution: {integrity: sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==}
+
+  undici-types@7.16.0:
+    resolution: {integrity: sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw==}
+
+  unicorn-magic@0.3.0:
+    resolution: {integrity: sha512-+QBBXBCvifc56fsbuxZQ6Sic3wqqc3WWaqxs58gvJrcOuN83HGTCwz3oS5phzU9LthRNE9VrJCFCLUgHeeFnfA==}
+    engines: {node: '>=18'}
+
+  unidiff@1.0.4:
+    resolution: {integrity: sha512-ynU0vsAXw0ir8roa+xPCUHmnJ5goc5BTM2Kuc3IJd8UwgaeRs7VSD5+eeaQL+xp1JtB92hu/Zy/Lgy7RZcr1pQ==}
+
+  unified@11.0.5:
+    resolution: {integrity: sha512-xKvGhPWw3k84Qjh8bI3ZeJjqnyadK+GEFtazSfZv/rKeTkTjOJho6mFqh2SM96iIcZokxiOpg78GazTSg8+KHA==}
+
+  unist-util-is@6.0.1:
+    resolution: {integrity: sha512-LsiILbtBETkDz8I9p1dQ0uyRUWuaQzd/cuEeS1hoRSyW5E5XGmTzlwY1OrNzzakGowI9Dr/I8HVaw4hTtnxy8g==}
+
+  unist-util-position@5.0.0:
+    resolution: {integrity: sha512-fucsC7HjXvkB5R3kTCO7kUjRdrS0BJt3M/FPxmHMBOm8JQi2BsHAHFsy27E0EolP8rp0NzXsJ+jNPyDWvOJZPA==}
+
+  unist-util-stringify-position@4.0.0:
+    resolution: {integrity: sha512-0ASV06AAoKCDkS2+xw5RXJywruurpbC4JZSm7nr7MOt1ojAzvyyaO+UxZf18j8FCF6kmzCZKcAgN/yu2gm2XgQ==}
+
+  unist-util-visit-parents@6.0.2:
+    resolution: {integrity: sha512-goh1s1TBrqSqukSc8wrjwWhL0hiJxgA8m4kFxGlQ+8FYQ3C/m11FcTs4YYem7V664AhHVvgoQLk890Ssdsr2IQ==}
+
+  unist-util-visit@5.1.0:
+    resolution: {integrity: sha512-m+vIdyeCOpdr/QeQCu2EzxX/ohgS8KbnPDgFni4dQsfSCtpz8UqDyY5GjRru8PDKuYn7Fq19j1CQ+nJSsGKOzg==}
+
+  universalify@2.0.1:
+    resolution: {integrity: sha512-gptHNQghINnc/vTGIk0SOFGFNXw7JVrlRUtConJRlvaw6DuX0wO5Jeko9sWrMBhh+PsYAZ7oXAiOnf/UKogyiw==}
+    engines: {node: '>= 10.0.0'}
+
+  unpipe@1.0.0:
+    resolution: {integrity: sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ==}
+    engines: {node: '>= 0.8'}
+
+  unrs-resolver@1.11.1:
+    resolution: {integrity: sha512-bSjt9pjaEBnNiGgc9rUiHGKv5l4/TGzDmYw3RhnkJGtLhbnnA/5qJj7x3dNDCRx/PJxu774LlH8lCOlB4hEfKg==}
+
+  until-async@3.0.2:
+    resolution: {integrity: sha512-IiSk4HlzAMqTUseHHe3VhIGyuFmN90zMTpD3Z3y8jeQbzLIq500MVM7Jq2vUAnTKAFPJrqwkzr6PoTcPhGcOiw==}
+
+  update-browserslist-db@1.2.3:
+    resolution: {integrity: sha512-Js0m9cx+qOgDxo0eMiFGEueWztz+d4+M3rGlmKPT+T4IS/jP4ylw3Nwpu6cpTTP8R1MAC1kF4VbdLt3ARf209w==}
+    hasBin: true
+    peerDependencies:
+      browserslist: '>= 4.21.0'
+
+  uri-js@4.4.1:
+    resolution: {integrity: sha512-7rKUyy33Q1yc98pQ1DAmLtwX109F7TIfWlW1Ydo8Wl1ii1SeHieeh0HHfPeL2fMXK6z0s8ecKs9frCuLJvndBg==}
+
+  use-callback-ref@1.3.3:
+    resolution: {integrity: sha512-jQL3lRnocaFtu3V00JToYz/4QkNWswxijDaCVNZRiRTO3HQDLsdu1ZtmIUvV4yPp+rvWm5j0y0TG/S61cuijTg==}
+    engines: {node: '>=10'}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  use-sidecar@1.1.3:
+    resolution: {integrity: sha512-Fedw0aZvkhynoPYlA5WXrMCAMm+nSWdZt6lzJQ7Ok8S6Q+VsHmHpRWndVRJ8Be0ZbkfPc5LRYH+5XrzXcEeLRQ==}
+    engines: {node: '>=10'}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  use-sync-external-store@1.6.0:
+    resolution: {integrity: sha512-Pp6GSwGP/NrPIrxVFAIkOQeyw8lFenOHijQWkUTrDvrF4ALqylP2C/KCkeS9dpUM3KvYRQhna5vt7IL95+ZQ9w==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+
+  util-deprecate@1.0.2:
+    resolution: {integrity: sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==}
+
+  utils-merge@1.0.1:
+    resolution: {integrity: sha512-pMZTvIkT1d+TFGvDOqodOclx0QWkkgi6Tdoa8gC8ffGAAqz9pzPTZWAybbsHHoED/ztMtkv/VoYTYyShUn81hA==}
+    engines: {node: '>= 0.4.0'}
+
+  uuid@13.0.2:
+    resolution: {integrity: sha512-vzi9uRZ926x4XV73S/4qQaTwPXM2JBj6/6lI/byHH1jOpCzb0zDbfytgA9LcN/hzb2l7WQSQnxITOVx5un/wGw==}
+    hasBin: true
+
+  v8-compile-cache-lib@3.0.1:
+    resolution: {integrity: sha512-wa7YjyUGfNZngI/vtK0UHAN+lgDCxBPCylVXGp0zu59Fz5aiGtNXaq3DhIov063MorB+VfufLh3JlF2KdTK3xg==}
+
+  validate-npm-package-name@7.0.2:
+    resolution: {integrity: sha512-hVDIBwsRruT73PbK7uP5ebUt+ezEtCmzZz3F59BSr2F6OVFnJ/6h8liuvdLrQ88Xmnk6/+xGGuq+pG9WwTuy3A==}
+    engines: {node: ^20.17.0 || >=22.9.0}
+
+  vary@1.1.2:
+    resolution: {integrity: sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg==}
+    engines: {node: '>= 0.8'}
+
+  vaul@1.1.2:
+    resolution: {integrity: sha512-ZFkClGpWyI2WUQjdLJ/BaGuV6AVQiJ3uELGk3OYtP+B6yCO7Cmn9vPFXVJkRaGkOJu3m8bQMgtyzNHixULceQA==}
+    peerDependencies:
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0.0 || ^19.0.0-rc
+
+  vfile-message@4.0.3:
+    resolution: {integrity: sha512-QTHzsGd1EhbZs4AsQ20JX1rC3cOlt/IWJruk893DfLRr57lcnOeMaWG4K0JrRta4mIJZKth2Au3mM3u03/JWKw==}
+
+  vfile@6.0.3:
+    resolution: {integrity: sha512-KzIbH/9tXat2u30jf+smMwFCsno4wHVdNmzFyL+T/L3UGqqk6JKfVqOFOZEpZSHADH1k40ab6NUIXZq422ov3Q==}
+
+  vite-plugin-svgr@5.2.0:
+    resolution: {integrity: sha512-qj2eAKF8C6PZWemVTvQA0xgQIcP1hHU6Buh7fl6BhvayWwnuxE+z417miKxeDvRWbDrupQ1oK99hfxElopJ3sQ==}
+    peerDependencies:
+      vite: '>=3.0.0'
+
+  vite@8.0.13:
+    resolution: {integrity: sha512-MFtjBYgzmSxmgA4RAfjIyXWpGe1oALnjgUTzzV7QLx/TKxCzjtMH6Fd9/eVK+5Fg1qNoz5VAwsmMs/NofrmJvw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    hasBin: true
+    peerDependencies:
+      '@types/node': ^20.19.0 || >=22.12.0
+      '@vitejs/devtools': ^0.1.18
+      esbuild: ^0.27.0 || ^0.28.0
+      jiti: '>=1.21.0'
+      less: ^4.0.0
+      sass: ^1.70.0
+      sass-embedded: ^1.70.0
+      stylus: '>=0.54.8'
+      sugarss: ^5.0.0
+      terser: ^5.16.0
+      tsx: ^4.8.1
+      yaml: ^2.4.2
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+      '@vitejs/devtools':
+        optional: true
+      esbuild:
+        optional: true
+      jiti:
+        optional: true
+      less:
+        optional: true
+      sass:
+        optional: true
+      sass-embedded:
+        optional: true
+      stylus:
+        optional: true
+      sugarss:
+        optional: true
+      terser:
+        optional: true
+      tsx:
+        optional: true
+      yaml:
+        optional: true
+
+  void-elements@3.1.0:
+    resolution: {integrity: sha512-Dhxzh5HZuiHQhbvTW9AMetFfBHDMYpo23Uo9btPXgdYP+3T5S+p+jgNy7spra+veYhBP2dCSgxR/i2Y02h5/6w==}
+    engines: {node: '>=0.10.0'}
+
+  warning@4.0.3:
+    resolution: {integrity: sha512-rpJyN222KWIvHJ/F53XSZv0Zl/accqHR8et1kpaMTD/fLCRxtV8iX8czMzY7sVZupTI3zcUTg8eycS2kNF9l6w==}
+
+  web-streams-polyfill@3.3.3:
+    resolution: {integrity: sha512-d2JWLCivmZYTSIoge9MsgFCZrt571BikcWGYkjC1khllbTeDlGqZ2D8vD8E/lJa8WGWbb7Plm8/XJYV7IJHZZw==}
+    engines: {node: '>= 8'}
+
+  whatwg-fetch@3.6.20:
+    resolution: {integrity: sha512-EqhiFU6daOA8kpjOWTL0olhVOF3i7OrFzSYiGsEMB8GcXS+RrzauAERX65xMeNWVqxA6HXH2m69Z9LaKKdisfg==}
+
+  which@2.0.2:
+    resolution: {integrity: sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==}
+    engines: {node: '>= 8'}
+    hasBin: true
+
+  which@4.0.0:
+    resolution: {integrity: sha512-GlaYyEb07DPxYCKhKzplCWBJtvxZcZMrL+4UkrTSJHHPyZU4mYYTv3qaOe77H7EODLSSopAUFAc6W8U4yqvscg==}
+    engines: {node: ^16.13.0 || >=18.0.0}
+    hasBin: true
+
+  word-wrap@1.2.5:
+    resolution: {integrity: sha512-BN22B5eaMMI9UMtjrGd5g5eCYPpCPDUy0FJXbYsaT5zYxjFOckS53SQDE3pWkVoWpHXVb3BrYcEN4Twa55B5cA==}
+    engines: {node: '>=0.10.0'}
+
+  wrap-ansi@10.0.0:
+    resolution: {integrity: sha512-SGcvg80f0wUy2/fXES19feHMz8E0JoXv2uNgHOu4Dgi2OrCy1lqwFYEJz1BLbDI0exjPMe/ZdzZ/YpGECBG/aQ==}
+    engines: {node: '>=20'}
+
+  wrap-ansi@7.0.0:
+    resolution: {integrity: sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==}
+    engines: {node: '>=10'}
+
+  wrap-ansi@9.0.2:
+    resolution: {integrity: sha512-42AtmgqjV+X1VpdOfyTGOYRi0/zsoLqtXQckTmqTeybT+BDIbM/Guxo7x3pE2vtpr1ok6xRqM9OpBe+Jyoqyww==}
+    engines: {node: '>=18'}
+
+  wrappy@1.0.2:
+    resolution: {integrity: sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==}
+
+  wsl-utils@0.3.1:
+    resolution: {integrity: sha512-g/eziiSUNBSsdDJtCLB8bdYEUMj4jR7AGeUo96p/3dTafgjHhpF4RiCFPiRILwjQoDXx5MqkBr4fwWtR3Ky4Wg==}
+    engines: {node: '>=20'}
+
+  y18n@5.0.8:
+    resolution: {integrity: sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==}
+    engines: {node: '>=10'}
+
+  yallist@3.1.1:
+    resolution: {integrity: sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==}
+
+  yaml@2.9.0:
+    resolution: {integrity: sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==}
+    engines: {node: '>= 14.6'}
+    hasBin: true
+
+  yargs-parser@21.1.1:
+    resolution: {integrity: sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==}
+    engines: {node: '>=12'}
+
+  yargs@17.7.2:
+    resolution: {integrity: sha512-7dSzzRQ++CKnNI/krKnYRV7JKKPUXMEh61soaHKg9mrWEhzFWhFnxPxGl+69cD1Ou63C13NUPCnmIcrvqCuM6w==}
+    engines: {node: '>=12'}
+
+  yn@3.1.1:
+    resolution: {integrity: sha512-Ux4ygGWsu2c7isFWe8Yu1YluJmqVhxqK2cLXNQA5AcC3QfbGNpM7fu0Y8b/z16pXLnFxZYvWhd3fhBY9DLmC6Q==}
+    engines: {node: '>=6'}
+
+  yocto-queue@0.1.0:
+    resolution: {integrity: sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q==}
+    engines: {node: '>=10'}
+
+  yocto-spinner@1.2.0:
+    resolution: {integrity: sha512-Yw0hUB6UA3o4YUgKy3oSe9a4cxoaZ9sBfYDw+JSxo6Id0KoJGoxzPA24qqUXYKBWABs/zDSGTz9kww7t3F0XGw==}
+    engines: {node: '>=18.19'}
+
+  yoctocolors@2.1.2:
+    resolution: {integrity: sha512-CzhO+pFNo8ajLM2d2IW/R93ipy99LWjtwblvC1RsoSUMZgyLbYFr221TnSNT7GjGdYui6P459mw9JH/g/zW2ug==}
+    engines: {node: '>=18'}
+
+  zod-to-json-schema@3.25.2:
+    resolution: {integrity: sha512-O/PgfnpT1xKSDeQYSCfRI5Gy3hPf91mKVDuYLUHZJMiDFptvP41MSnWofm8dnCm0256ZNfZIM7DSzuSMAFnjHA==}
+    peerDependencies:
+      zod: ^3.25.28 || ^4
+
+  zod-validation-error@4.0.2:
+    resolution: {integrity: sha512-Q6/nZLe6jxuU80qb/4uJ4t5v2VEZ44lzQjPDhYJNztRQ4wyWc6VF3D3Kb/fAuPetZQnhS3hnajCf9CsWesghLQ==}
+    engines: {node: '>=18.0.0'}
+    peerDependencies:
+      zod: ^3.25.0 || ^4.0.0
+
+  zod@3.25.76:
+    resolution: {integrity: sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==}
+
+  zod@4.4.3:
+    resolution: {integrity: sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ==}
+
+  zwitch@2.0.4:
+    resolution: {integrity: sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A==}
+
+snapshots:
+
+  '@agentscope-ai/agentscope@0.0.13':
+    dependencies:
+      '@cfworker/json-schema': 4.1.1
+      '@modelcontextprotocol/sdk': 1.29.0(@cfworker/json-schema@4.1.1)(zod@4.4.3)
+      gray-matter: 4.0.3
+      jsonrepair: 3.14.0
+      mime-types: 3.0.2
+      ollama: 0.6.3
+      openai: 6.44.0(zod@4.4.3)
+      string-format: 2.0.0
+      uuid: 13.0.2
+      zod: 4.4.3
+      zod-to-json-schema: 3.25.2(zod@4.4.3)
+    transitivePeerDependencies:
+      - supports-color
+      - ws
+
+  '@babel/code-frame@7.29.0':
+    dependencies:
+      '@babel/helper-validator-identifier': 7.28.5
+      js-tokens: 4.0.0
+      picocolors: 1.1.1
+
+  '@babel/compat-data@7.29.3': {}
+
+  '@babel/core@7.29.0':
+    dependencies:
+      '@babel/code-frame': 7.29.0
+      '@babel/generator': 7.29.1
+      '@babel/helper-compilation-targets': 7.28.6
+      '@babel/helper-module-transforms': 7.28.6(@babel/core@7.29.0)
+      '@babel/helpers': 7.29.2
+      '@babel/parser': 7.29.3
+      '@babel/template': 7.28.6
+      '@babel/traverse': 7.29.0
+      '@babel/types': 7.29.0
+      '@jridgewell/remapping': 2.3.5
+      convert-source-map: 2.0.0
+      debug: 4.4.3(supports-color@5.5.0)
+      gensync: 1.0.0-beta.2
+      json5: 2.2.3
+      semver: 6.3.1
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/generator@7.29.1':
+    dependencies:
+      '@babel/parser': 7.29.3
+      '@babel/types': 7.29.0
+      '@jridgewell/gen-mapping': 0.3.13
+      '@jridgewell/trace-mapping': 0.3.31
+      jsesc: 3.1.0
+
+  '@babel/helper-annotate-as-pure@7.27.3':
+    dependencies:
+      '@babel/types': 7.29.0
+
+  '@babel/helper-compilation-targets@7.28.6':
+    dependencies:
+      '@babel/compat-data': 7.29.3
+      '@babel/helper-validator-option': 7.27.1
+      browserslist: 4.28.2
+      lru-cache: 5.1.1
+      semver: 6.3.1
+
+  '@babel/helper-create-class-features-plugin@7.29.3(@babel/core@7.29.0)':
+    dependencies:
+      '@babel/core': 7.29.0
+      '@babel/helper-annotate-as-pure': 7.27.3
+      '@babel/helper-member-expression-to-functions': 7.28.5
+      '@babel/helper-optimise-call-expression': 7.27.1
+      '@babel/helper-replace-supers': 7.28.6(@babel/core@7.29.0)
+      '@babel/helper-skip-transparent-expression-wrappers': 7.27.1
+      '@babel/traverse': 7.29.0
+      semver: 6.3.1
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/helper-globals@7.28.0': {}
+
+  '@babel/helper-member-expression-to-functions@7.28.5':
+    dependencies:
+      '@babel/traverse': 7.29.0
+      '@babel/types': 7.29.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/helper-module-imports@7.28.6':
+    dependencies:
+      '@babel/traverse': 7.29.0
+      '@babel/types': 7.29.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/helper-module-transforms@7.28.6(@babel/core@7.29.0)':
+    dependencies:
+      '@babel/core': 7.29.0
+      '@babel/helper-module-imports': 7.28.6
+      '@babel/helper-validator-identifier': 7.28.5
+      '@babel/traverse': 7.29.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/helper-optimise-call-expression@7.27.1':
+    dependencies:
+      '@babel/types': 7.29.0
+
+  '@babel/helper-plugin-utils@7.28.6': {}
+
+  '@babel/helper-replace-supers@7.28.6(@babel/core@7.29.0)':
+    dependencies:
+      '@babel/core': 7.29.0
+      '@babel/helper-member-expression-to-functions': 7.28.5
+      '@babel/helper-optimise-call-expression': 7.27.1
+      '@babel/traverse': 7.29.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/helper-skip-transparent-expression-wrappers@7.27.1':
+    dependencies:
+      '@babel/traverse': 7.29.0
+      '@babel/types': 7.29.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/helper-string-parser@7.27.1': {}
+
+  '@babel/helper-validator-identifier@7.28.5': {}
+
+  '@babel/helper-validator-option@7.27.1': {}
+
+  '@babel/helpers@7.29.2':
+    dependencies:
+      '@babel/template': 7.28.6
+      '@babel/types': 7.29.0
+
+  '@babel/parser@7.29.3':
+    dependencies:
+      '@babel/types': 7.29.0
+
+  '@babel/plugin-syntax-jsx@7.28.6(@babel/core@7.29.0)':
+    dependencies:
+      '@babel/core': 7.29.0
+      '@babel/helper-plugin-utils': 7.28.6
+
+  '@babel/plugin-syntax-typescript@7.28.6(@babel/core@7.29.0)':
+    dependencies:
+      '@babel/core': 7.29.0
+      '@babel/helper-plugin-utils': 7.28.6
+
+  '@babel/plugin-transform-modules-commonjs@7.28.6(@babel/core@7.29.0)':
+    dependencies:
+      '@babel/core': 7.29.0
+      '@babel/helper-module-transforms': 7.28.6(@babel/core@7.29.0)
+      '@babel/helper-plugin-utils': 7.28.6
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/plugin-transform-typescript@7.28.6(@babel/core@7.29.0)':
+    dependencies:
+      '@babel/core': 7.29.0
+      '@babel/helper-annotate-as-pure': 7.27.3
+      '@babel/helper-create-class-features-plugin': 7.29.3(@babel/core@7.29.0)
+      '@babel/helper-plugin-utils': 7.28.6
+      '@babel/helper-skip-transparent-expression-wrappers': 7.27.1
+      '@babel/plugin-syntax-typescript': 7.28.6(@babel/core@7.29.0)
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/preset-typescript@7.28.5(@babel/core@7.29.0)':
+    dependencies:
+      '@babel/core': 7.29.0
+      '@babel/helper-plugin-utils': 7.28.6
+      '@babel/helper-validator-option': 7.27.1
+      '@babel/plugin-syntax-jsx': 7.28.6(@babel/core@7.29.0)
+      '@babel/plugin-transform-modules-commonjs': 7.28.6(@babel/core@7.29.0)
+      '@babel/plugin-transform-typescript': 7.28.6(@babel/core@7.29.0)
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/runtime@7.29.2': {}
+
+  '@babel/template@7.28.6':
+    dependencies:
+      '@babel/code-frame': 7.29.0
+      '@babel/parser': 7.29.3
+      '@babel/types': 7.29.0
+
+  '@babel/traverse@7.29.0':
+    dependencies:
+      '@babel/code-frame': 7.29.0
+      '@babel/generator': 7.29.1
+      '@babel/helper-globals': 7.28.0
+      '@babel/parser': 7.29.3
+      '@babel/template': 7.28.6
+      '@babel/types': 7.29.0
+      debug: 4.4.3(supports-color@5.5.0)
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/types@7.29.0':
+    dependencies:
+      '@babel/helper-string-parser': 7.27.1
+      '@babel/helper-validator-identifier': 7.28.5
+
+  '@cfworker/json-schema@4.1.1': {}
+
+  '@cspotcode/source-map-support@0.8.1':
+    dependencies:
+      '@jridgewell/trace-mapping': 0.3.9
+
+  '@date-fns/tz@1.4.1': {}
+
+  '@dotenvx/dotenvx@1.66.0':
+    dependencies:
+      commander: 11.1.0
+      dotenv: 17.4.2
+      eciesjs: 0.4.18
+      execa: 5.1.1
+      fdir: 6.5.0(picomatch@4.0.4)
+      ignore: 5.3.2
+      object-treeify: 1.1.33
+      picomatch: 4.0.4
+      which: 4.0.0
+      yocto-spinner: 1.2.0
+
+  '@ecies/ciphers@0.2.6(@noble/ciphers@1.3.0)':
+    dependencies:
+      '@noble/ciphers': 1.3.0
+
+  '@emnapi/core@1.10.0':
+    dependencies:
+      '@emnapi/wasi-threads': 1.2.1
+      tslib: 2.8.1
+    optional: true
+
+  '@emnapi/runtime@1.10.0':
+    dependencies:
+      tslib: 2.8.1
+    optional: true
+
+  '@emnapi/wasi-threads@1.2.1':
+    dependencies:
+      tslib: 2.8.1
+    optional: true
+
+  '@eslint-community/eslint-utils@4.9.1(eslint@10.3.0(jiti@2.7.0))':
+    dependencies:
+      eslint: 10.3.0(jiti@2.7.0)
+      eslint-visitor-keys: 3.4.3
+
+  '@eslint-community/regexpp@4.12.2': {}
+
+  '@eslint/config-array@0.23.5':
+    dependencies:
+      '@eslint/object-schema': 3.0.5
+      debug: 4.4.3(supports-color@5.5.0)
+      minimatch: 10.2.5
+    transitivePeerDependencies:
+      - supports-color
+
+  '@eslint/config-helpers@0.5.5':
+    dependencies:
+      '@eslint/core': 1.2.1
+
+  '@eslint/core@1.2.1':
+    dependencies:
+      '@types/json-schema': 7.0.15
+
+  '@eslint/js@10.0.1(eslint@10.3.0(jiti@2.7.0))':
+    optionalDependencies:
+      eslint: 10.3.0(jiti@2.7.0)
+
+  '@eslint/object-schema@3.0.5': {}
+
+  '@eslint/plugin-kit@0.7.1':
+    dependencies:
+      '@eslint/core': 1.2.1
+      levn: 0.4.1
+
+  '@floating-ui/core@1.7.5':
+    dependencies:
+      '@floating-ui/utils': 0.2.11
+
+  '@floating-ui/dom@1.7.6':
+    dependencies:
+      '@floating-ui/core': 1.7.5
+      '@floating-ui/utils': 0.2.11
+
+  '@floating-ui/react-dom@2.1.8(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@floating-ui/dom': 1.7.6
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+
+  '@floating-ui/utils@0.2.11': {}
+
+  '@fontsource-variable/geist@5.2.8': {}
+
+  '@hono/node-server@1.19.14(hono@4.12.18)':
+    dependencies:
+      hono: 4.12.18
+
+  '@humanfs/core@0.19.2':
+    dependencies:
+      '@humanfs/types': 0.15.0
+
+  '@humanfs/node@0.16.8':
+    dependencies:
+      '@humanfs/core': 0.19.2
+      '@humanfs/types': 0.15.0
+      '@humanwhocodes/retry': 0.4.3
+
+  '@humanfs/types@0.15.0': {}
+
+  '@humanwhocodes/module-importer@1.0.1': {}
+
+  '@humanwhocodes/retry@0.4.3': {}
+
+  '@img/colour@1.1.0':
+    optional: true
+
+  '@img/sharp-darwin-arm64@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-darwin-arm64': 1.2.4
+    optional: true
+
+  '@img/sharp-darwin-x64@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-darwin-x64': 1.2.4
+    optional: true
+
+  '@img/sharp-libvips-darwin-arm64@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-darwin-x64@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-linux-arm64@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-linux-arm@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-linux-ppc64@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-linux-riscv64@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-linux-s390x@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-linux-x64@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-linuxmusl-arm64@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-linuxmusl-x64@1.2.4':
+    optional: true
+
+  '@img/sharp-linux-arm64@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-linux-arm64': 1.2.4
+    optional: true
+
+  '@img/sharp-linux-arm@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-linux-arm': 1.2.4
+    optional: true
+
+  '@img/sharp-linux-ppc64@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-linux-ppc64': 1.2.4
+    optional: true
+
+  '@img/sharp-linux-riscv64@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-linux-riscv64': 1.2.4
+    optional: true
+
+  '@img/sharp-linux-s390x@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-linux-s390x': 1.2.4
+    optional: true
+
+  '@img/sharp-linux-x64@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-linux-x64': 1.2.4
+    optional: true
+
+  '@img/sharp-linuxmusl-arm64@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-linuxmusl-arm64': 1.2.4
+    optional: true
+
+  '@img/sharp-linuxmusl-x64@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-linuxmusl-x64': 1.2.4
+    optional: true
+
+  '@img/sharp-wasm32@0.34.5':
+    dependencies:
+      '@emnapi/runtime': 1.10.0
+    optional: true
+
+  '@img/sharp-win32-arm64@0.34.5':
+    optional: true
+
+  '@img/sharp-win32-ia32@0.34.5':
+    optional: true
+
+  '@img/sharp-win32-x64@0.34.5':
+    optional: true
+
+  '@inquirer/ansi@2.0.5': {}
+
+  '@inquirer/confirm@6.0.13(@types/node@24.12.4)':
+    dependencies:
+      '@inquirer/core': 11.1.10(@types/node@24.12.4)
+      '@inquirer/type': 4.0.5(@types/node@24.12.4)
+    optionalDependencies:
+      '@types/node': 24.12.4
+
+  '@inquirer/core@11.1.10(@types/node@24.12.4)':
+    dependencies:
+      '@inquirer/ansi': 2.0.5
+      '@inquirer/figures': 2.0.5
+      '@inquirer/type': 4.0.5(@types/node@24.12.4)
+      cli-width: 4.1.0
+      fast-wrap-ansi: 0.2.0
+      mute-stream: 3.0.0
+      signal-exit: 4.1.0
+    optionalDependencies:
+      '@types/node': 24.12.4
+
+  '@inquirer/figures@2.0.5': {}
+
+  '@inquirer/type@4.0.5(@types/node@24.12.4)':
+    optionalDependencies:
+      '@types/node': 24.12.4
+
+  '@jridgewell/gen-mapping@0.3.13':
+    dependencies:
+      '@jridgewell/sourcemap-codec': 1.5.5
+      '@jridgewell/trace-mapping': 0.3.31
+
+  '@jridgewell/remapping@2.3.5':
+    dependencies:
+      '@jridgewell/gen-mapping': 0.3.13
+      '@jridgewell/trace-mapping': 0.3.31
+
+  '@jridgewell/resolve-uri@3.1.2': {}
+
+  '@jridgewell/sourcemap-codec@1.5.5': {}
+
+  '@jridgewell/trace-mapping@0.3.31':
+    dependencies:
+      '@jridgewell/resolve-uri': 3.1.2
+      '@jridgewell/sourcemap-codec': 1.5.5
+
+  '@jridgewell/trace-mapping@0.3.9':
+    dependencies:
+      '@jridgewell/resolve-uri': 3.1.2
+      '@jridgewell/sourcemap-codec': 1.5.5
+
+  '@modelcontextprotocol/sdk@1.29.0(@cfworker/json-schema@4.1.1)(zod@3.25.76)':
+    dependencies:
+      '@hono/node-server': 1.19.14(hono@4.12.18)
+      ajv: 8.20.0
+      ajv-formats: 3.0.1(ajv@8.20.0)
+      content-type: 1.0.5
+      cors: 2.8.6
+      cross-spawn: 7.0.6
+      eventsource: 3.0.7
+      eventsource-parser: 3.0.8
+      express: 5.2.1
+      express-rate-limit: 8.5.2(express@5.2.1)
+      hono: 4.12.18
+      jose: 6.2.3
+      json-schema-typed: 8.0.2
+      pkce-challenge: 5.0.1
+      raw-body: 3.0.2
+      zod: 3.25.76
+      zod-to-json-schema: 3.25.2(zod@3.25.76)
+    optionalDependencies:
+      '@cfworker/json-schema': 4.1.1
+    transitivePeerDependencies:
+      - supports-color
+
+  '@modelcontextprotocol/sdk@1.29.0(@cfworker/json-schema@4.1.1)(zod@4.4.3)':
+    dependencies:
+      '@hono/node-server': 1.19.14(hono@4.12.18)
+      ajv: 8.20.0
+      ajv-formats: 3.0.1(ajv@8.20.0)
+      content-type: 1.0.5
+      cors: 2.8.6
+      cross-spawn: 7.0.6
+      eventsource: 3.0.7
+      eventsource-parser: 3.0.8
+      express: 5.2.1
+      express-rate-limit: 8.5.2(express@5.2.1)
+      hono: 4.12.18
+      jose: 6.2.3
+      json-schema-typed: 8.0.2
+      pkce-challenge: 5.0.1
+      raw-body: 3.0.2
+      zod: 4.4.3
+      zod-to-json-schema: 3.25.2(zod@4.4.3)
+    optionalDependencies:
+      '@cfworker/json-schema': 4.1.1
+    transitivePeerDependencies:
+      - supports-color
+
+  '@mswjs/interceptors@0.41.9':
+    dependencies:
+      '@open-draft/deferred-promise': 2.2.0
+      '@open-draft/logger': 0.3.0
+      '@open-draft/until': 2.1.0
+      is-node-process: 1.2.0
+      outvariant: 1.4.3
+      strict-event-emitter: 0.5.1
+
+  '@napi-rs/wasm-runtime@0.2.12':
+    dependencies:
+      '@emnapi/core': 1.10.0
+      '@emnapi/runtime': 1.10.0
+      '@tybys/wasm-util': 0.10.2
+    optional: true
+
+  '@napi-rs/wasm-runtime@1.1.4(@emnapi/core@1.10.0)(@emnapi/runtime@1.10.0)':
+    dependencies:
+      '@emnapi/core': 1.10.0
+      '@emnapi/runtime': 1.10.0
+      '@tybys/wasm-util': 0.10.2
+    optional: true
+
+  '@next/env@16.2.6': {}
+
+  '@next/swc-darwin-arm64@16.2.6':
+    optional: true
+
+  '@next/swc-darwin-x64@16.2.6':
+    optional: true
+
+  '@next/swc-linux-arm64-gnu@16.2.6':
+    optional: true
+
+  '@next/swc-linux-arm64-musl@16.2.6':
+    optional: true
+
+  '@next/swc-linux-x64-gnu@16.2.6':
+    optional: true
+
+  '@next/swc-linux-x64-musl@16.2.6':
+    optional: true
+
+  '@next/swc-win32-arm64-msvc@16.2.6':
+    optional: true
+
+  '@next/swc-win32-x64-msvc@16.2.6':
+    optional: true
+
+  '@noble/ciphers@1.3.0': {}
+
+  '@noble/curves@1.9.7':
+    dependencies:
+      '@noble/hashes': 1.8.0
+
+  '@noble/hashes@1.8.0': {}
+
+  '@nodelib/fs.scandir@2.1.5':
+    dependencies:
+      '@nodelib/fs.stat': 2.0.5
+      run-parallel: 1.2.0
+
+  '@nodelib/fs.stat@2.0.5': {}
+
+  '@nodelib/fs.walk@1.2.8':
+    dependencies:
+      '@nodelib/fs.scandir': 2.1.5
+      fastq: 1.20.1
+
+  '@open-draft/deferred-promise@2.2.0': {}
+
+  '@open-draft/deferred-promise@3.0.0': {}
+
+  '@open-draft/logger@0.3.0':
+    dependencies:
+      is-node-process: 1.2.0
+      outvariant: 1.4.3
+
+  '@open-draft/until@2.1.0': {}
+
+  '@oxc-project/types@0.130.0': {}
+
+  '@package-json/types@0.0.12': {}
+
+  '@pkgr/core@0.2.9': {}
+
+  '@radix-ui/number@1.1.1': {}
+
+  '@radix-ui/primitive@1.1.3': {}
+
+  '@radix-ui/react-accessible-icon@1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/react-visually-hidden': 1.2.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-accordion@1.2.12(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-collapsible': 1.1.12(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-collection': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-direction': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-id': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-alert-dialog@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-dialog': 1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-slot': 1.2.3(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-arrow@1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-aspect-ratio@1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-avatar@1.1.10(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-is-hydrated': 0.1.0(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-checkbox@1.3.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-presence': 1.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-previous': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-size': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-collapsible@1.1.12(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-id': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-presence': 1.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-collection@1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-slot': 1.2.3(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-compose-refs@1.1.2(@types/react@19.2.14)(react@19.2.6)':
+    dependencies:
+      react: 19.2.6
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-context-menu@2.2.16(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-menu': 2.1.16(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-context@1.1.2(@types/react@19.2.14)(react@19.2.6)':
+    dependencies:
+      react: 19.2.6
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-dialog@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-dismissable-layer': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-focus-guards': 1.1.3(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-focus-scope': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-id': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-portal': 1.1.9(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-presence': 1.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-slot': 1.2.3(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.6)
+      aria-hidden: 1.2.6
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+      react-remove-scroll: 2.7.2(@types/react@19.2.14)(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-direction@1.1.1(@types/react@19.2.14)(react@19.2.6)':
+    dependencies:
+      react: 19.2.6
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-dismissable-layer@1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-escape-keydown': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-dropdown-menu@2.1.16(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-id': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-menu': 2.1.16(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-focus-guards@1.1.3(@types/react@19.2.14)(react@19.2.6)':
+    dependencies:
+      react: 19.2.6
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-focus-scope@1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-form@0.1.8(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-id': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-label': 2.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-hover-card@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-dismissable-layer': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-popper': 1.2.8(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-portal': 1.1.9(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-presence': 1.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-id@1.1.1(@types/react@19.2.14)(react@19.2.6)':
+    dependencies:
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-label@2.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-menu@2.1.16(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-collection': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-direction': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-dismissable-layer': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-focus-guards': 1.1.3(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-focus-scope': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-id': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-popper': 1.2.8(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-portal': 1.1.9(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-presence': 1.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-roving-focus': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-slot': 1.2.3(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      aria-hidden: 1.2.6
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+      react-remove-scroll: 2.7.2(@types/react@19.2.14)(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-menubar@1.1.16(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-collection': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-direction': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-id': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-menu': 2.1.16(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-roving-focus': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-navigation-menu@1.2.14(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-collection': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-direction': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-dismissable-layer': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-id': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-presence': 1.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-previous': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-visually-hidden': 1.2.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-one-time-password-field@0.1.8(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/number': 1.1.1
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-collection': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-direction': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-roving-focus': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-effect-event': 0.0.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-is-hydrated': 0.1.0(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-password-toggle-field@0.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-id': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-effect-event': 0.0.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-is-hydrated': 0.1.0(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-popover@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-dismissable-layer': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-focus-guards': 1.1.3(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-focus-scope': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-id': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-popper': 1.2.8(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-portal': 1.1.9(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-presence': 1.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-slot': 1.2.3(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.6)
+      aria-hidden: 1.2.6
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+      react-remove-scroll: 2.7.2(@types/react@19.2.14)(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-popper@1.2.8(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@floating-ui/react-dom': 2.1.8(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-arrow': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-rect': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-size': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/rect': 1.1.1
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-portal@1.1.9(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-presence@1.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-primitive@2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/react-slot': 1.2.3(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-progress@1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-radio-group@1.3.8(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-direction': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-presence': 1.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-roving-focus': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-previous': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-size': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-roving-focus@1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-collection': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-direction': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-id': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-scroll-area@1.2.10(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/number': 1.1.1
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-direction': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-presence': 1.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-select@2.2.6(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/number': 1.1.1
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-collection': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-direction': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-dismissable-layer': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-focus-guards': 1.1.3(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-focus-scope': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-id': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-popper': 1.2.8(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-portal': 1.1.9(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-slot': 1.2.3(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-previous': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-visually-hidden': 1.2.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      aria-hidden: 1.2.6
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+      react-remove-scroll: 2.7.2(@types/react@19.2.14)(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-separator@1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-slider@1.3.6(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/number': 1.1.1
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-collection': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-direction': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-previous': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-size': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-slot@1.2.3(@types/react@19.2.14)(react@19.2.6)':
+    dependencies:
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-switch@1.2.6(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-previous': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-size': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-tabs@1.1.13(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-direction': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-id': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-presence': 1.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-roving-focus': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-toast@1.2.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-collection': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-dismissable-layer': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-portal': 1.1.9(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-presence': 1.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-visually-hidden': 1.2.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-toggle-group@1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-direction': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-roving-focus': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-toggle': 1.1.10(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-toggle@1.1.10(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-toolbar@1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-direction': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-roving-focus': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-separator': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-toggle-group': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-tooltip@1.2.8(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-dismissable-layer': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-id': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-popper': 1.2.8(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-portal': 1.1.9(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-presence': 1.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-slot': 1.2.3(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-visually-hidden': 1.2.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-use-callback-ref@1.1.1(@types/react@19.2.14)(react@19.2.6)':
+    dependencies:
+      react: 19.2.6
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-use-controllable-state@1.2.2(@types/react@19.2.14)(react@19.2.6)':
+    dependencies:
+      '@radix-ui/react-use-effect-event': 0.0.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-use-effect-event@0.0.2(@types/react@19.2.14)(react@19.2.6)':
+    dependencies:
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-use-escape-keydown@1.1.1(@types/react@19.2.14)(react@19.2.6)':
+    dependencies:
+      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-use-is-hydrated@0.1.0(@types/react@19.2.14)(react@19.2.6)':
+    dependencies:
+      react: 19.2.6
+      use-sync-external-store: 1.6.0(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-use-layout-effect@1.1.1(@types/react@19.2.14)(react@19.2.6)':
+    dependencies:
+      react: 19.2.6
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-use-previous@1.1.1(@types/react@19.2.14)(react@19.2.6)':
+    dependencies:
+      react: 19.2.6
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-use-rect@1.1.1(@types/react@19.2.14)(react@19.2.6)':
+    dependencies:
+      '@radix-ui/rect': 1.1.1
+      react: 19.2.6
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-use-size@1.1.1(@types/react@19.2.14)(react@19.2.6)':
+    dependencies:
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      react: 19.2.6
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-visually-hidden@1.2.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/rect@1.1.1': {}
+
+  '@rolldown/binding-android-arm64@1.0.1':
+    optional: true
+
+  '@rolldown/binding-darwin-arm64@1.0.1':
+    optional: true
+
+  '@rolldown/binding-darwin-x64@1.0.1':
+    optional: true
+
+  '@rolldown/binding-freebsd-x64@1.0.1':
+    optional: true
+
+  '@rolldown/binding-linux-arm-gnueabihf@1.0.1':
+    optional: true
+
+  '@rolldown/binding-linux-arm64-gnu@1.0.1':
+    optional: true
+
+  '@rolldown/binding-linux-arm64-musl@1.0.1':
+    optional: true
+
+  '@rolldown/binding-linux-ppc64-gnu@1.0.1':
+    optional: true
+
+  '@rolldown/binding-linux-s390x-gnu@1.0.1':
+    optional: true
+
+  '@rolldown/binding-linux-x64-gnu@1.0.1':
+    optional: true
+
+  '@rolldown/binding-linux-x64-musl@1.0.1':
+    optional: true
+
+  '@rolldown/binding-openharmony-arm64@1.0.1':
+    optional: true
+
+  '@rolldown/binding-wasm32-wasi@1.0.1':
+    dependencies:
+      '@emnapi/core': 1.10.0
+      '@emnapi/runtime': 1.10.0
+      '@napi-rs/wasm-runtime': 1.1.4(@emnapi/core@1.10.0)(@emnapi/runtime@1.10.0)
+    optional: true
+
+  '@rolldown/binding-win32-arm64-msvc@1.0.1':
+    optional: true
+
+  '@rolldown/binding-win32-x64-msvc@1.0.1':
+    optional: true
+
+  '@rolldown/pluginutils@1.0.0-rc.7': {}
+
+  '@rolldown/pluginutils@1.0.1': {}
+
+  '@rollup/pluginutils@5.3.0':
+    dependencies:
+      '@types/estree': 1.0.9
+      estree-walker: 2.0.2
+      picomatch: 4.0.4
+
+  '@sec-ant/readable-stream@0.4.1': {}
+
+  '@sindresorhus/merge-streams@4.0.0': {}
+
+  '@svgr/babel-plugin-add-jsx-attribute@8.0.0(@babel/core@7.29.0)':
+    dependencies:
+      '@babel/core': 7.29.0
+
+  '@svgr/babel-plugin-remove-jsx-attribute@8.0.0(@babel/core@7.29.0)':
+    dependencies:
+      '@babel/core': 7.29.0
+
+  '@svgr/babel-plugin-remove-jsx-empty-expression@8.0.0(@babel/core@7.29.0)':
+    dependencies:
+      '@babel/core': 7.29.0
+
+  '@svgr/babel-plugin-replace-jsx-attribute-value@8.0.0(@babel/core@7.29.0)':
+    dependencies:
+      '@babel/core': 7.29.0
+
+  '@svgr/babel-plugin-svg-dynamic-title@8.0.0(@babel/core@7.29.0)':
+    dependencies:
+      '@babel/core': 7.29.0
+
+  '@svgr/babel-plugin-svg-em-dimensions@8.0.0(@babel/core@7.29.0)':
+    dependencies:
+      '@babel/core': 7.29.0
+
+  '@svgr/babel-plugin-transform-react-native-svg@8.1.0(@babel/core@7.29.0)':
+    dependencies:
+      '@babel/core': 7.29.0
+
+  '@svgr/babel-plugin-transform-svg-component@8.0.0(@babel/core@7.29.0)':
+    dependencies:
+      '@babel/core': 7.29.0
+
+  '@svgr/babel-preset@8.1.0(@babel/core@7.29.0)':
+    dependencies:
+      '@babel/core': 7.29.0
+      '@svgr/babel-plugin-add-jsx-attribute': 8.0.0(@babel/core@7.29.0)
+      '@svgr/babel-plugin-remove-jsx-attribute': 8.0.0(@babel/core@7.29.0)
+      '@svgr/babel-plugin-remove-jsx-empty-expression': 8.0.0(@babel/core@7.29.0)
+      '@svgr/babel-plugin-replace-jsx-attribute-value': 8.0.0(@babel/core@7.29.0)
+      '@svgr/babel-plugin-svg-dynamic-title': 8.0.0(@babel/core@7.29.0)
+      '@svgr/babel-plugin-svg-em-dimensions': 8.0.0(@babel/core@7.29.0)
+      '@svgr/babel-plugin-transform-react-native-svg': 8.1.0(@babel/core@7.29.0)
+      '@svgr/babel-plugin-transform-svg-component': 8.0.0(@babel/core@7.29.0)
+
+  '@svgr/core@8.1.0(typescript@6.0.3)':
+    dependencies:
+      '@babel/core': 7.29.0
+      '@svgr/babel-preset': 8.1.0(@babel/core@7.29.0)
+      camelcase: 6.3.0
+      cosmiconfig: 8.3.6(typescript@6.0.3)
+      snake-case: 3.0.4
+    transitivePeerDependencies:
+      - supports-color
+      - typescript
+
+  '@svgr/hast-util-to-babel-ast@8.0.0':
+    dependencies:
+      '@babel/types': 7.29.0
+      entities: 4.5.0
+
+  '@svgr/plugin-jsx@8.1.0(@svgr/core@8.1.0(typescript@6.0.3))':
+    dependencies:
+      '@babel/core': 7.29.0
+      '@svgr/babel-preset': 8.1.0(@babel/core@7.29.0)
+      '@svgr/core': 8.1.0(typescript@6.0.3)
+      '@svgr/hast-util-to-babel-ast': 8.0.0
+      svg-parser: 2.0.4
+    transitivePeerDependencies:
+      - supports-color
+
+  '@swc/helpers@0.5.15':
+    dependencies:
+      tslib: 2.8.1
+
+  '@tailwindcss/node@4.3.0':
+    dependencies:
+      '@jridgewell/remapping': 2.3.5
+      enhanced-resolve: 5.21.3
+      jiti: 2.7.0
+      lightningcss: 1.32.0
+      magic-string: 0.30.21
+      source-map-js: 1.2.1
+      tailwindcss: 4.3.0
+
+  '@tailwindcss/oxide-android-arm64@4.3.0':
+    optional: true
+
+  '@tailwindcss/oxide-darwin-arm64@4.3.0':
+    optional: true
+
+  '@tailwindcss/oxide-darwin-x64@4.3.0':
+    optional: true
+
+  '@tailwindcss/oxide-freebsd-x64@4.3.0':
+    optional: true
+
+  '@tailwindcss/oxide-linux-arm-gnueabihf@4.3.0':
+    optional: true
+
+  '@tailwindcss/oxide-linux-arm64-gnu@4.3.0':
+    optional: true
+
+  '@tailwindcss/oxide-linux-arm64-musl@4.3.0':
+    optional: true
+
+  '@tailwindcss/oxide-linux-x64-gnu@4.3.0':
+    optional: true
+
+  '@tailwindcss/oxide-linux-x64-musl@4.3.0':
+    optional: true
+
+  '@tailwindcss/oxide-wasm32-wasi@4.3.0':
+    optional: true
+
+  '@tailwindcss/oxide-win32-arm64-msvc@4.3.0':
+    optional: true
+
+  '@tailwindcss/oxide-win32-x64-msvc@4.3.0':
+    optional: true
+
+  '@tailwindcss/oxide@4.3.0':
+    optionalDependencies:
+      '@tailwindcss/oxide-android-arm64': 4.3.0
+      '@tailwindcss/oxide-darwin-arm64': 4.3.0
+      '@tailwindcss/oxide-darwin-x64': 4.3.0
+      '@tailwindcss/oxide-freebsd-x64': 4.3.0
+      '@tailwindcss/oxide-linux-arm-gnueabihf': 4.3.0
+      '@tailwindcss/oxide-linux-arm64-gnu': 4.3.0
+      '@tailwindcss/oxide-linux-arm64-musl': 4.3.0
+      '@tailwindcss/oxide-linux-x64-gnu': 4.3.0
+      '@tailwindcss/oxide-linux-x64-musl': 4.3.0
+      '@tailwindcss/oxide-wasm32-wasi': 4.3.0
+      '@tailwindcss/oxide-win32-arm64-msvc': 4.3.0
+      '@tailwindcss/oxide-win32-x64-msvc': 4.3.0
+
+  '@tailwindcss/typography@0.5.19(tailwindcss@4.3.0)':
+    dependencies:
+      postcss-selector-parser: 6.0.10
+      tailwindcss: 4.3.0
+
+  '@tailwindcss/vite@4.3.0(vite@8.0.13(@types/node@24.12.4)(jiti@2.7.0)(yaml@2.9.0))':
+    dependencies:
+      '@tailwindcss/node': 4.3.0
+      '@tailwindcss/oxide': 4.3.0
+      tailwindcss: 4.3.0
+      vite: 8.0.13(@types/node@24.12.4)(jiti@2.7.0)(yaml@2.9.0)
+
+  '@ts-morph/common@0.27.0':
+    dependencies:
+      fast-glob: 3.3.3
+      minimatch: 10.2.5
+      path-browserify: 1.0.1
+
+  '@tsconfig/node10@1.0.12': {}
+
+  '@tsconfig/node12@1.0.11': {}
+
+  '@tsconfig/node14@1.0.3': {}
+
+  '@tsconfig/node16@1.0.4': {}
+
+  '@tybys/wasm-util@0.10.2':
+    dependencies:
+      tslib: 2.8.1
+    optional: true
+
+  '@types/body-parser@1.19.6':
+    dependencies:
+      '@types/connect': 3.4.38
+      '@types/node': 20.19.41
+
+  '@types/connect@3.4.38':
+    dependencies:
+      '@types/node': 20.19.41
+
+  '@types/cors@2.8.19':
+    dependencies:
+      '@types/node': 20.19.41
+
+  '@types/debug@4.1.13':
+    dependencies:
+      '@types/ms': 2.1.0
+
+  '@types/esrecurse@4.3.1': {}
+
+  '@types/estree-jsx@1.0.5':
+    dependencies:
+      '@types/estree': 1.0.9
+
+  '@types/estree@1.0.9': {}
+
+  '@types/express-serve-static-core@4.19.8':
+    dependencies:
+      '@types/node': 20.19.41
+      '@types/qs': 6.15.1
+      '@types/range-parser': 1.2.7
+      '@types/send': 1.2.1
+
+  '@types/express@4.17.25':
+    dependencies:
+      '@types/body-parser': 1.19.6
+      '@types/express-serve-static-core': 4.19.8
+      '@types/qs': 6.15.1
+      '@types/serve-static': 1.15.10
+
+  '@types/hast@3.0.4':
+    dependencies:
+      '@types/unist': 3.0.3
+
+  '@types/http-errors@2.0.5': {}
+
+  '@types/json-schema@7.0.15': {}
+
+  '@types/mdast@4.0.4':
+    dependencies:
+      '@types/unist': 3.0.3
+
+  '@types/mime-types@3.0.1': {}
+
+  '@types/mime@1.3.5': {}
+
+  '@types/ms@2.1.0': {}
+
+  '@types/node@20.19.41':
+    dependencies:
+      undici-types: 6.21.0
+
+  '@types/node@24.12.4':
+    dependencies:
+      undici-types: 7.16.0
+
+  '@types/qs@6.15.1': {}
+
+  '@types/range-parser@1.2.7': {}
+
+  '@types/react-dom@19.2.3(@types/react@19.2.14)':
+    dependencies:
+      '@types/react': 19.2.14
+
+  '@types/react@19.2.14':
+    dependencies:
+      csstype: 3.2.3
+
+  '@types/send@0.17.6':
+    dependencies:
+      '@types/mime': 1.3.5
+      '@types/node': 20.19.41
+
+  '@types/send@1.2.1':
+    dependencies:
+      '@types/node': 20.19.41
+
+  '@types/serve-static@1.15.10':
+    dependencies:
+      '@types/http-errors': 2.0.5
+      '@types/node': 20.19.41
+      '@types/send': 0.17.6
+
+  '@types/set-cookie-parser@2.4.10':
+    dependencies:
+      '@types/node': 24.12.4
+
+  '@types/statuses@2.0.6': {}
+
+  '@types/unist@2.0.11': {}
+
+  '@types/unist@3.0.3': {}
+
+  '@types/validate-npm-package-name@4.0.2': {}
+
+  '@typescript-eslint/eslint-plugin@8.59.3(@typescript-eslint/parser@8.59.3(eslint@10.3.0(jiti@2.7.0))(typescript@6.0.3))(eslint@10.3.0(jiti@2.7.0))(typescript@6.0.3)':
+    dependencies:
+      '@eslint-community/regexpp': 4.12.2
+      '@typescript-eslint/parser': 8.59.3(eslint@10.3.0(jiti@2.7.0))(typescript@6.0.3)
+      '@typescript-eslint/scope-manager': 8.59.3
+      '@typescript-eslint/type-utils': 8.59.3(eslint@10.3.0(jiti@2.7.0))(typescript@6.0.3)
+      '@typescript-eslint/utils': 8.59.3(eslint@10.3.0(jiti@2.7.0))(typescript@6.0.3)
+      '@typescript-eslint/visitor-keys': 8.59.3
+      eslint: 10.3.0(jiti@2.7.0)
+      ignore: 7.0.5
+      natural-compare: 1.4.0
+      ts-api-utils: 2.5.0(typescript@6.0.3)
+      typescript: 6.0.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@typescript-eslint/parser@8.59.3(eslint@10.3.0(jiti@2.7.0))(typescript@6.0.3)':
+    dependencies:
+      '@typescript-eslint/scope-manager': 8.59.3
+      '@typescript-eslint/types': 8.59.3
+      '@typescript-eslint/typescript-estree': 8.59.3(typescript@6.0.3)
+      '@typescript-eslint/visitor-keys': 8.59.3
+      debug: 4.4.3(supports-color@5.5.0)
+      eslint: 10.3.0(jiti@2.7.0)
+      typescript: 6.0.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@typescript-eslint/project-service@8.59.3(typescript@6.0.3)':
+    dependencies:
+      '@typescript-eslint/tsconfig-utils': 8.59.3(typescript@6.0.3)
+      '@typescript-eslint/types': 8.59.3
+      debug: 4.4.3(supports-color@5.5.0)
+      typescript: 6.0.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@typescript-eslint/scope-manager@8.59.3':
+    dependencies:
+      '@typescript-eslint/types': 8.59.3
+      '@typescript-eslint/visitor-keys': 8.59.3
+
+  '@typescript-eslint/tsconfig-utils@8.59.3(typescript@6.0.3)':
+    dependencies:
+      typescript: 6.0.3
+
+  '@typescript-eslint/type-utils@8.59.3(eslint@10.3.0(jiti@2.7.0))(typescript@6.0.3)':
+    dependencies:
+      '@typescript-eslint/types': 8.59.3
+      '@typescript-eslint/typescript-estree': 8.59.3(typescript@6.0.3)
+      '@typescript-eslint/utils': 8.59.3(eslint@10.3.0(jiti@2.7.0))(typescript@6.0.3)
+      debug: 4.4.3(supports-color@5.5.0)
+      eslint: 10.3.0(jiti@2.7.0)
+      ts-api-utils: 2.5.0(typescript@6.0.3)
+      typescript: 6.0.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@typescript-eslint/types@8.59.3': {}
+
+  '@typescript-eslint/typescript-estree@8.59.3(typescript@6.0.3)':
+    dependencies:
+      '@typescript-eslint/project-service': 8.59.3(typescript@6.0.3)
+      '@typescript-eslint/tsconfig-utils': 8.59.3(typescript@6.0.3)
+      '@typescript-eslint/types': 8.59.3
+      '@typescript-eslint/visitor-keys': 8.59.3
+      debug: 4.4.3(supports-color@5.5.0)
+      minimatch: 10.2.5
+      semver: 7.8.0
+      tinyglobby: 0.2.16
+      ts-api-utils: 2.5.0(typescript@6.0.3)
+      typescript: 6.0.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@typescript-eslint/utils@8.59.3(eslint@10.3.0(jiti@2.7.0))(typescript@6.0.3)':
+    dependencies:
+      '@eslint-community/eslint-utils': 4.9.1(eslint@10.3.0(jiti@2.7.0))
+      '@typescript-eslint/scope-manager': 8.59.3
+      '@typescript-eslint/types': 8.59.3
+      '@typescript-eslint/typescript-estree': 8.59.3(typescript@6.0.3)
+      eslint: 10.3.0(jiti@2.7.0)
+      typescript: 6.0.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@typescript-eslint/visitor-keys@8.59.3':
+    dependencies:
+      '@typescript-eslint/types': 8.59.3
+      eslint-visitor-keys: 5.0.1
+
+  '@ungap/structured-clone@1.3.1': {}
+
+  '@unrs/resolver-binding-android-arm-eabi@1.11.1':
+    optional: true
+
+  '@unrs/resolver-binding-android-arm64@1.11.1':
+    optional: true
+
+  '@unrs/resolver-binding-darwin-arm64@1.11.1':
+    optional: true
+
+  '@unrs/resolver-binding-darwin-x64@1.11.1':
+    optional: true
+
+  '@unrs/resolver-binding-freebsd-x64@1.11.1':
+    optional: true
+
+  '@unrs/resolver-binding-linux-arm-gnueabihf@1.11.1':
+    optional: true
+
+  '@unrs/resolver-binding-linux-arm-musleabihf@1.11.1':
+    optional: true
+
+  '@unrs/resolver-binding-linux-arm64-gnu@1.11.1':
+    optional: true
+
+  '@unrs/resolver-binding-linux-arm64-musl@1.11.1':
+    optional: true
+
+  '@unrs/resolver-binding-linux-ppc64-gnu@1.11.1':
+    optional: true
+
+  '@unrs/resolver-binding-linux-riscv64-gnu@1.11.1':
+    optional: true
+
+  '@unrs/resolver-binding-linux-riscv64-musl@1.11.1':
+    optional: true
+
+  '@unrs/resolver-binding-linux-s390x-gnu@1.11.1':
+    optional: true
+
+  '@unrs/resolver-binding-linux-x64-gnu@1.11.1':
+    optional: true
+
+  '@unrs/resolver-binding-linux-x64-musl@1.11.1':
+    optional: true
+
+  '@unrs/resolver-binding-wasm32-wasi@1.11.1':
+    dependencies:
+      '@napi-rs/wasm-runtime': 0.2.12
+    optional: true
+
+  '@unrs/resolver-binding-win32-arm64-msvc@1.11.1':
+    optional: true
+
+  '@unrs/resolver-binding-win32-ia32-msvc@1.11.1':
+    optional: true
+
+  '@unrs/resolver-binding-win32-x64-msvc@1.11.1':
+    optional: true
+
+  '@vitejs/plugin-react@6.0.1(vite@8.0.13(@types/node@24.12.4)(jiti@2.7.0)(yaml@2.9.0))':
+    dependencies:
+      '@rolldown/pluginutils': 1.0.0-rc.7
+      vite: 8.0.13(@types/node@24.12.4)(jiti@2.7.0)(yaml@2.9.0)
+
+  accepts@1.3.8:
+    dependencies:
+      mime-types: 2.1.35
+      negotiator: 0.6.3
+
+  accepts@2.0.0:
+    dependencies:
+      mime-types: 3.0.2
+      negotiator: 1.0.0
+
+  acorn-jsx@5.3.2(acorn@8.16.0):
+    dependencies:
+      acorn: 8.16.0
+
+  acorn-walk@8.3.5:
+    dependencies:
+      acorn: 8.16.0
+
+  acorn@8.16.0: {}
+
+  agent-base@7.1.4: {}
+
+  ajv-formats@3.0.1(ajv@8.20.0):
+    optionalDependencies:
+      ajv: 8.20.0
+
+  ajv@6.15.0:
+    dependencies:
+      fast-deep-equal: 3.1.3
+      fast-json-stable-stringify: 2.1.0
+      json-schema-traverse: 0.4.1
+      uri-js: 4.4.1
+
+  ajv@8.20.0:
+    dependencies:
+      fast-deep-equal: 3.1.3
+      fast-uri: 3.1.2
+      json-schema-traverse: 1.0.0
+      require-from-string: 2.0.2
+
+  ansi-escapes@7.3.0:
+    dependencies:
+      environment: 1.1.0
+
+  ansi-regex@5.0.1: {}
+
+  ansi-regex@6.2.2: {}
+
+  ansi-styles@4.3.0:
+    dependencies:
+      color-convert: 2.0.1
+
+  ansi-styles@6.2.3: {}
+
+  anymatch@3.1.3:
+    dependencies:
+      normalize-path: 3.0.0
+      picomatch: 2.3.2
+
+  arg@4.1.3: {}
+
+  argparse@1.0.10:
+    dependencies:
+      sprintf-js: 1.0.3
+
+  argparse@2.0.1: {}
+
+  aria-hidden@1.2.6:
+    dependencies:
+      tslib: 2.8.1
+
+  array-flatten@1.1.1: {}
+
+  ast-types@0.16.1:
+    dependencies:
+      tslib: 2.8.1
+
+  bail@2.0.2: {}
+
+  balanced-match@4.0.4: {}
+
+  baseline-browser-mapping@2.10.29: {}
+
+  baseline-browser-mapping@2.10.33: {}
+
+  binary-extensions@2.3.0: {}
+
+  body-parser@1.20.5:
+    dependencies:
+      bytes: 3.1.2
+      content-type: 1.0.5
+      debug: 2.6.9
+      depd: 2.0.0
+      destroy: 1.2.0
+      http-errors: 2.0.1
+      iconv-lite: 0.4.24
+      on-finished: 2.4.1
+      qs: 6.15.1
+      raw-body: 2.5.3
+      type-is: 1.6.18
+      unpipe: 1.0.0
+    transitivePeerDependencies:
+      - supports-color
+
+  body-parser@2.2.2:
+    dependencies:
+      bytes: 3.1.2
+      content-type: 1.0.5
+      debug: 4.4.3(supports-color@5.5.0)
+      http-errors: 2.0.1
+      iconv-lite: 0.7.2
+      on-finished: 2.4.1
+      qs: 6.15.1
+      raw-body: 3.0.2
+      type-is: 2.1.0
+    transitivePeerDependencies:
+      - supports-color
+
+  brace-expansion@5.0.6:
+    dependencies:
+      balanced-match: 4.0.4
+
+  braces@3.0.3:
+    dependencies:
+      fill-range: 7.1.1
+
+  browserslist@4.28.2:
+    dependencies:
+      baseline-browser-mapping: 2.10.29
+      caniuse-lite: 1.0.30001792
+      electron-to-chromium: 1.5.355
+      node-releases: 2.0.44
+      update-browserslist-db: 1.2.3(browserslist@4.28.2)
+
+  bundle-name@4.1.0:
+    dependencies:
+      run-applescript: 7.1.0
+
+  bytes@3.1.2: {}
+
+  call-bind-apply-helpers@1.0.2:
+    dependencies:
+      es-errors: 1.3.0
+      function-bind: 1.1.2
+
+  call-bound@1.0.4:
+    dependencies:
+      call-bind-apply-helpers: 1.0.2
+      get-intrinsic: 1.3.0
+
+  callsites@3.1.0: {}
+
+  camelcase@6.3.0: {}
+
+  caniuse-lite@1.0.30001792: {}
+
+  caniuse-lite@1.0.30001793: {}
+
+  ccount@2.0.1: {}
+
+  chalk@4.1.2:
+    dependencies:
+      ansi-styles: 4.3.0
+      supports-color: 7.2.0
+
+  chalk@5.6.2: {}
+
+  character-entities-html4@2.1.0: {}
+
+  character-entities-legacy@3.0.0: {}
+
+  character-entities@2.0.2: {}
+
+  character-reference-invalid@2.0.1: {}
+
+  chokidar@3.6.0:
+    dependencies:
+      anymatch: 3.1.3
+      braces: 3.0.3
+      glob-parent: 5.1.2
+      is-binary-path: 2.1.0
+      is-glob: 4.0.3
+      normalize-path: 3.0.0
+      readdirp: 3.6.0
+    optionalDependencies:
+      fsevents: 2.3.3
+
+  class-variance-authority@0.7.1:
+    dependencies:
+      clsx: 2.1.1
+
+  classnames@2.5.1: {}
+
+  cli-cursor@5.0.0:
+    dependencies:
+      restore-cursor: 5.1.0
+
+  cli-spinners@2.9.2: {}
+
+  cli-truncate@5.2.0:
+    dependencies:
+      slice-ansi: 8.0.0
+      string-width: 8.2.1
+
+  cli-width@4.1.0: {}
+
+  client-only@0.0.1: {}
+
+  cliui@8.0.1:
+    dependencies:
+      string-width: 4.2.3
+      strip-ansi: 6.0.1
+      wrap-ansi: 7.0.0
+
+  clsx@2.1.1: {}
+
+  code-block-writer@13.0.3: {}
+
+  color-convert@2.0.1:
+    dependencies:
+      color-name: 1.1.4
+
+  color-name@1.1.4: {}
+
+  comma-separated-tokens@2.0.3: {}
+
+  commander@11.1.0: {}
+
+  commander@14.0.3: {}
+
+  comment-parser@1.4.6: {}
+
+  concurrently@8.2.2:
+    dependencies:
+      chalk: 4.1.2
+      date-fns: 2.30.0
+      lodash: 4.18.1
+      rxjs: 7.8.2
+      shell-quote: 1.8.3
+      spawn-command: 0.0.2
+      supports-color: 8.1.1
+      tree-kill: 1.2.2
+      yargs: 17.7.2
+
+  content-disposition@0.5.4:
+    dependencies:
+      safe-buffer: 5.2.1
+
+  content-disposition@1.1.0: {}
+
+  content-type@1.0.5: {}
+
+  content-type@2.0.0: {}
+
+  convert-source-map@2.0.0: {}
+
+  cookie-signature@1.0.7: {}
+
+  cookie-signature@1.2.2: {}
+
+  cookie@0.7.2: {}
+
+  cookie@1.1.1: {}
+
+  cors@2.8.6:
+    dependencies:
+      object-assign: 4.1.1
+      vary: 1.1.2
+
+  cosmiconfig@8.3.6(typescript@6.0.3):
+    dependencies:
+      import-fresh: 3.3.1
+      js-yaml: 4.1.1
+      parse-json: 5.2.0
+      path-type: 4.0.0
+    optionalDependencies:
+      typescript: 6.0.3
+
+  cosmiconfig@9.0.1(typescript@6.0.3):
+    dependencies:
+      env-paths: 2.2.1
+      import-fresh: 3.3.1
+      js-yaml: 4.1.1
+      parse-json: 5.2.0
+    optionalDependencies:
+      typescript: 6.0.3
+
+  create-require@1.1.1: {}
+
+  cron-parser@5.5.0:
+    dependencies:
+      luxon: 3.7.2
+
+  cross-spawn@7.0.6:
+    dependencies:
+      path-key: 3.1.1
+      shebang-command: 2.0.0
+      which: 2.0.2
+
+  cssesc@3.0.0: {}
+
+  csstype@3.2.3: {}
+
+  data-uri-to-buffer@4.0.1: {}
+
+  date-fns@2.30.0:
+    dependencies:
+      '@babel/runtime': 7.29.2
+
+  date-fns@4.1.0: {}
+
+  debug@2.6.9:
+    dependencies:
+      ms: 2.0.0
+
+  debug@4.4.3(supports-color@5.5.0):
+    dependencies:
+      ms: 2.1.3
+    optionalDependencies:
+      supports-color: 5.5.0
+
+  decode-named-character-reference@1.3.0:
+    dependencies:
+      character-entities: 2.0.2
+
+  dedent@1.7.2: {}
+
+  deep-is@0.1.4: {}
+
+  deepmerge@4.3.1: {}
+
+  default-browser-id@5.0.1: {}
+
+  default-browser@5.5.0:
+    dependencies:
+      bundle-name: 4.1.0
+      default-browser-id: 5.0.1
+
+  define-lazy-prop@3.0.0: {}
+
+  depd@2.0.0: {}
+
+  dequal@2.0.3: {}
+
+  destroy@1.2.0: {}
+
+  detect-libc@2.1.2: {}
+
+  detect-node-es@1.1.0: {}
+
+  devlop@1.1.0:
+    dependencies:
+      dequal: 2.0.3
+
+  diff-match-patch@1.0.5: {}
+
+  diff@4.0.4: {}
+
+  diff@5.2.2: {}
+
+  diff@8.0.4: {}
+
+  dot-case@3.0.4:
+    dependencies:
+      no-case: 3.0.4
+      tslib: 2.8.1
+
+  dotenv@17.4.2: {}
+
+  dunder-proto@1.0.1:
+    dependencies:
+      call-bind-apply-helpers: 1.0.2
+      es-errors: 1.3.0
+      gopd: 1.2.0
+
+  eciesjs@0.4.18:
+    dependencies:
+      '@ecies/ciphers': 0.2.6(@noble/ciphers@1.3.0)
+      '@noble/ciphers': 1.3.0
+      '@noble/curves': 1.9.7
+      '@noble/hashes': 1.8.0
+
+  ee-first@1.1.1: {}
+
+  electron-to-chromium@1.5.355: {}
+
+  emoji-regex@10.6.0: {}
+
+  emoji-regex@8.0.0: {}
+
+  encodeurl@2.0.0: {}
+
+  enhanced-resolve@5.21.3:
+    dependencies:
+      graceful-fs: 4.2.11
+      tapable: 2.3.3
+
+  entities@4.5.0: {}
+
+  env-paths@2.2.1: {}
+
+  environment@1.1.0: {}
+
+  error-ex@1.3.4:
+    dependencies:
+      is-arrayish: 0.2.1
+
+  es-define-property@1.0.1: {}
+
+  es-errors@1.3.0: {}
+
+  es-object-atoms@1.1.1:
+    dependencies:
+      es-errors: 1.3.0
+
+  escalade@3.2.0: {}
+
+  escape-html@1.0.3: {}
+
+  escape-string-regexp@4.0.0: {}
+
+  escape-string-regexp@5.0.0: {}
+
+  eslint-config-prettier@10.1.8(eslint@10.3.0(jiti@2.7.0)):
+    dependencies:
+      eslint: 10.3.0(jiti@2.7.0)
+
+  eslint-import-context@0.1.9(unrs-resolver@1.11.1):
+    dependencies:
+      get-tsconfig: 4.14.0
+      stable-hash-x: 0.2.0
+    optionalDependencies:
+      unrs-resolver: 1.11.1
+
+  eslint-plugin-import-x@4.16.2(@typescript-eslint/utils@8.59.3(eslint@10.3.0(jiti@2.7.0))(typescript@6.0.3))(eslint@10.3.0(jiti@2.7.0)):
+    dependencies:
+      '@package-json/types': 0.0.12
+      '@typescript-eslint/types': 8.59.3
+      comment-parser: 1.4.6
+      debug: 4.4.3(supports-color@5.5.0)
+      eslint: 10.3.0(jiti@2.7.0)
+      eslint-import-context: 0.1.9(unrs-resolver@1.11.1)
+      is-glob: 4.0.3
+      minimatch: 10.2.5
+      semver: 7.8.0
+      stable-hash-x: 0.2.0
+      unrs-resolver: 1.11.1
+    optionalDependencies:
+      '@typescript-eslint/utils': 8.59.3(eslint@10.3.0(jiti@2.7.0))(typescript@6.0.3)
+    transitivePeerDependencies:
+      - supports-color
+
+  eslint-plugin-prettier@5.5.5(eslint-config-prettier@10.1.8(eslint@10.3.0(jiti@2.7.0)))(eslint@10.3.0(jiti@2.7.0))(prettier@3.8.3):
+    dependencies:
+      eslint: 10.3.0(jiti@2.7.0)
+      prettier: 3.8.3
+      prettier-linter-helpers: 1.0.1
+      synckit: 0.11.12
+    optionalDependencies:
+      eslint-config-prettier: 10.1.8(eslint@10.3.0(jiti@2.7.0))
+
+  eslint-plugin-react-hooks@7.1.1(eslint@10.3.0(jiti@2.7.0)):
+    dependencies:
+      '@babel/core': 7.29.0
+      '@babel/parser': 7.29.3
+      eslint: 10.3.0(jiti@2.7.0)
+      hermes-parser: 0.25.1
+      zod: 4.4.3
+      zod-validation-error: 4.0.2(zod@4.4.3)
+    transitivePeerDependencies:
+      - supports-color
+
+  eslint-plugin-react-refresh@0.5.2(eslint@10.3.0(jiti@2.7.0)):
+    dependencies:
+      eslint: 10.3.0(jiti@2.7.0)
+
+  eslint-scope@9.1.2:
+    dependencies:
+      '@types/esrecurse': 4.3.1
+      '@types/estree': 1.0.9
+      esrecurse: 4.3.0
+      estraverse: 5.3.0
+
+  eslint-visitor-keys@3.4.3: {}
+
+  eslint-visitor-keys@5.0.1: {}
+
+  eslint@10.3.0(jiti@2.7.0):
+    dependencies:
+      '@eslint-community/eslint-utils': 4.9.1(eslint@10.3.0(jiti@2.7.0))
+      '@eslint-community/regexpp': 4.12.2
+      '@eslint/config-array': 0.23.5
+      '@eslint/config-helpers': 0.5.5
+      '@eslint/core': 1.2.1
+      '@eslint/plugin-kit': 0.7.1
+      '@humanfs/node': 0.16.8
+      '@humanwhocodes/module-importer': 1.0.1
+      '@humanwhocodes/retry': 0.4.3
+      '@types/estree': 1.0.9
+      ajv: 6.15.0
+      cross-spawn: 7.0.6
+      debug: 4.4.3(supports-color@5.5.0)
+      escape-string-regexp: 4.0.0
+      eslint-scope: 9.1.2
+      eslint-visitor-keys: 5.0.1
+      espree: 11.2.0
+      esquery: 1.7.0
+      esutils: 2.0.3
+      fast-deep-equal: 3.1.3
+      file-entry-cache: 8.0.0
+      find-up: 5.0.0
+      glob-parent: 6.0.2
+      ignore: 5.3.2
+      imurmurhash: 0.1.4
+      is-glob: 4.0.3
+      json-stable-stringify-without-jsonify: 1.0.1
+      minimatch: 10.2.5
+      natural-compare: 1.4.0
+      optionator: 0.9.4
+    optionalDependencies:
+      jiti: 2.7.0
+    transitivePeerDependencies:
+      - supports-color
+
+  espree@11.2.0:
+    dependencies:
+      acorn: 8.16.0
+      acorn-jsx: 5.3.2(acorn@8.16.0)
+      eslint-visitor-keys: 5.0.1
+
+  esprima@4.0.1: {}
+
+  esquery@1.7.0:
+    dependencies:
+      estraverse: 5.3.0
+
+  esrecurse@4.3.0:
+    dependencies:
+      estraverse: 5.3.0
+
+  estraverse@5.3.0: {}
+
+  estree-util-is-identifier-name@3.0.0: {}
+
+  estree-walker@2.0.2: {}
+
+  esutils@2.0.3: {}
+
+  etag@1.8.1: {}
+
+  eventemitter3@5.0.4: {}
+
+  eventsource-parser@3.0.8: {}
+
+  eventsource@3.0.7:
+    dependencies:
+      eventsource-parser: 3.0.8
+
+  execa@5.1.1:
+    dependencies:
+      cross-spawn: 7.0.6
+      get-stream: 6.0.1
+      human-signals: 2.1.0
+      is-stream: 2.0.1
+      merge-stream: 2.0.0
+      npm-run-path: 4.0.1
+      onetime: 5.1.2
+      signal-exit: 3.0.7
+      strip-final-newline: 2.0.0
+
+  execa@9.6.1:
+    dependencies:
+      '@sindresorhus/merge-streams': 4.0.0
+      cross-spawn: 7.0.6
+      figures: 6.1.0
+      get-stream: 9.0.1
+      human-signals: 8.0.1
+      is-plain-obj: 4.1.0
+      is-stream: 4.0.1
+      npm-run-path: 6.0.0
+      pretty-ms: 9.3.0
+      signal-exit: 4.1.0
+      strip-final-newline: 4.0.0
+      yoctocolors: 2.1.2
+
+  express-rate-limit@8.5.2(express@5.2.1):
+    dependencies:
+      express: 5.2.1
+      ip-address: 10.2.0
+
+  express@4.22.2:
+    dependencies:
+      accepts: 1.3.8
+      array-flatten: 1.1.1
+      body-parser: 1.20.5
+      content-disposition: 0.5.4
+      content-type: 1.0.5
+      cookie: 0.7.2
+      cookie-signature: 1.0.7
+      debug: 2.6.9
+      depd: 2.0.0
+      encodeurl: 2.0.0
+      escape-html: 1.0.3
+      etag: 1.8.1
+      finalhandler: 1.3.2
+      fresh: 0.5.2
+      http-errors: 2.0.1
+      merge-descriptors: 1.0.3
+      methods: 1.1.2
+      on-finished: 2.4.1
+      parseurl: 1.3.3
+      path-to-regexp: 0.1.13
+      proxy-addr: 2.0.7
+      qs: 6.15.1
+      range-parser: 1.2.1
+      safe-buffer: 5.2.1
+      send: 0.19.2
+      serve-static: 1.16.3
+      setprototypeof: 1.2.0
+      statuses: 2.0.2
+      type-is: 1.6.18
+      utils-merge: 1.0.1
+      vary: 1.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  express@5.2.1:
+    dependencies:
+      accepts: 2.0.0
+      body-parser: 2.2.2
+      content-disposition: 1.1.0
+      content-type: 1.0.5
+      cookie: 0.7.2
+      cookie-signature: 1.2.2
+      debug: 4.4.3(supports-color@5.5.0)
+      depd: 2.0.0
+      encodeurl: 2.0.0
+      escape-html: 1.0.3
+      etag: 1.8.1
+      finalhandler: 2.1.1
+      fresh: 2.0.0
+      http-errors: 2.0.1
+      merge-descriptors: 2.0.0
+      mime-types: 3.0.2
+      on-finished: 2.4.1
+      once: 1.4.0
+      parseurl: 1.3.3
+      proxy-addr: 2.0.7
+      qs: 6.15.1
+      range-parser: 1.2.1
+      router: 2.2.0
+      send: 1.2.1
+      serve-static: 2.2.1
+      statuses: 2.0.2
+      type-is: 2.1.0
+      vary: 1.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  extend-shallow@2.0.1:
+    dependencies:
+      is-extendable: 0.1.1
+
+  extend@3.0.2: {}
+
+  fast-deep-equal@3.1.3: {}
+
+  fast-diff@1.3.0: {}
+
+  fast-glob@3.3.3:
+    dependencies:
+      '@nodelib/fs.stat': 2.0.5
+      '@nodelib/fs.walk': 1.2.8
+      glob-parent: 5.1.2
+      merge2: 1.4.1
+      micromatch: 4.0.8
+
+  fast-json-stable-stringify@2.1.0: {}
+
+  fast-levenshtein@2.0.6: {}
+
+  fast-string-truncated-width@3.0.3: {}
+
+  fast-string-width@3.0.2:
+    dependencies:
+      fast-string-truncated-width: 3.0.3
+
+  fast-uri@3.1.2: {}
+
+  fast-wrap-ansi@0.2.0:
+    dependencies:
+      fast-string-width: 3.0.2
+
+  fastq@1.20.1:
+    dependencies:
+      reusify: 1.1.0
+
+  fdir@6.5.0(picomatch@4.0.4):
+    optionalDependencies:
+      picomatch: 4.0.4
+
+  fetch-blob@3.2.0:
+    dependencies:
+      node-domexception: 1.0.0
+      web-streams-polyfill: 3.3.3
+
+  figures@6.1.0:
+    dependencies:
+      is-unicode-supported: 2.1.0
+
+  file-entry-cache@8.0.0:
+    dependencies:
+      flat-cache: 4.0.1
+
+  fill-range@7.1.1:
+    dependencies:
+      to-regex-range: 5.0.1
+
+  finalhandler@1.3.2:
+    dependencies:
+      debug: 2.6.9
+      encodeurl: 2.0.0
+      escape-html: 1.0.3
+      on-finished: 2.4.1
+      parseurl: 1.3.3
+      statuses: 2.0.2
+      unpipe: 1.0.0
+    transitivePeerDependencies:
+      - supports-color
+
+  finalhandler@2.1.1:
+    dependencies:
+      debug: 4.4.3(supports-color@5.5.0)
+      encodeurl: 2.0.0
+      escape-html: 1.0.3
+      on-finished: 2.4.1
+      parseurl: 1.3.3
+      statuses: 2.0.2
+    transitivePeerDependencies:
+      - supports-color
+
+  find-up@5.0.0:
+    dependencies:
+      locate-path: 6.0.0
+      path-exists: 4.0.0
+
+  flat-cache@4.0.1:
+    dependencies:
+      flatted: 3.4.2
+      keyv: 4.5.4
+
+  flatted@3.4.2: {}
+
+  formdata-polyfill@4.0.10:
+    dependencies:
+      fetch-blob: 3.2.0
+
+  forwarded@0.2.0: {}
+
+  framer-motion@12.40.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
+    dependencies:
+      motion-dom: 12.40.0
+      motion-utils: 12.39.0
+      tslib: 2.8.1
+    optionalDependencies:
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+
+  fresh@0.5.2: {}
+
+  fresh@2.0.0: {}
+
+  fs-extra@11.3.5:
+    dependencies:
+      graceful-fs: 4.2.11
+      jsonfile: 6.2.1
+      universalify: 2.0.1
+
+  fsevents@2.3.3:
+    optional: true
+
+  function-bind@1.1.2: {}
+
+  fuzzysort@3.1.0: {}
+
+  gensync@1.0.0-beta.2: {}
+
+  get-caller-file@2.0.5: {}
+
+  get-east-asian-width@1.6.0: {}
+
+  get-intrinsic@1.3.0:
+    dependencies:
+      call-bind-apply-helpers: 1.0.2
+      es-define-property: 1.0.1
+      es-errors: 1.3.0
+      es-object-atoms: 1.1.1
+      function-bind: 1.1.2
+      get-proto: 1.0.1
+      gopd: 1.2.0
+      has-symbols: 1.1.0
+      hasown: 2.0.3
+      math-intrinsics: 1.1.0
+
+  get-nonce@1.0.1: {}
+
+  get-own-enumerable-keys@1.0.0: {}
+
+  get-proto@1.0.1:
+    dependencies:
+      dunder-proto: 1.0.1
+      es-object-atoms: 1.1.1
+
+  get-stream@6.0.1: {}
+
+  get-stream@9.0.1:
+    dependencies:
+      '@sec-ant/readable-stream': 0.4.1
+      is-stream: 4.0.1
+
+  get-tsconfig@4.14.0:
+    dependencies:
+      resolve-pkg-maps: 1.0.0
+
+  gitdiff-parser@0.3.1: {}
+
+  glob-parent@5.1.2:
+    dependencies:
+      is-glob: 4.0.3
+
+  glob-parent@6.0.2:
+    dependencies:
+      is-glob: 4.0.3
+
+  globals@17.6.0: {}
+
+  gopd@1.2.0: {}
+
+  graceful-fs@4.2.11: {}
+
+  graphql@16.14.0: {}
+
+  gray-matter@4.0.3:
+    dependencies:
+      js-yaml: 3.14.2
+      kind-of: 6.0.3
+      section-matter: 1.0.0
+      strip-bom-string: 1.0.0
+
+  has-flag@3.0.0: {}
+
+  has-flag@4.0.0: {}
+
+  has-symbols@1.1.0: {}
+
+  hasown@2.0.3:
+    dependencies:
+      function-bind: 1.1.2
+
+  hast-util-to-jsx-runtime@2.3.6:
+    dependencies:
+      '@types/estree': 1.0.9
+      '@types/hast': 3.0.4
+      '@types/unist': 3.0.3
+      comma-separated-tokens: 2.0.3
+      devlop: 1.1.0
+      estree-util-is-identifier-name: 3.0.0
+      hast-util-whitespace: 3.0.0
+      mdast-util-mdx-expression: 2.0.1
+      mdast-util-mdx-jsx: 3.2.0
+      mdast-util-mdxjs-esm: 2.0.1
+      property-information: 7.1.0
+      space-separated-tokens: 2.0.2
+      style-to-js: 1.1.21
+      unist-util-position: 5.0.0
+      vfile-message: 4.0.3
+    transitivePeerDependencies:
+      - supports-color
+
+  hast-util-whitespace@3.0.0:
+    dependencies:
+      '@types/hast': 3.0.4
+
+  headers-polyfill@5.0.1:
+    dependencies:
+      '@types/set-cookie-parser': 2.4.10
+      set-cookie-parser: 3.1.0
+
+  hermes-estree@0.25.1: {}
+
+  hermes-parser@0.25.1:
+    dependencies:
+      hermes-estree: 0.25.1
+
+  hono@4.12.18: {}
+
+  html-parse-stringify@3.0.1:
+    dependencies:
+      void-elements: 3.1.0
+
+  html-url-attributes@3.0.1: {}
+
+  http-errors@2.0.1:
+    dependencies:
+      depd: 2.0.0
+      inherits: 2.0.4
+      setprototypeof: 1.2.0
+      statuses: 2.0.2
+      toidentifier: 1.0.1
+
+  https-proxy-agent@7.0.6:
+    dependencies:
+      agent-base: 7.1.4
+      debug: 4.4.3(supports-color@5.5.0)
+    transitivePeerDependencies:
+      - supports-color
+
+  human-signals@2.1.0: {}
+
+  human-signals@8.0.1: {}
+
+  husky@9.1.7: {}
+
+  i18next-browser-languagedetector@8.2.1:
+    dependencies:
+      '@babel/runtime': 7.29.2
+
+  i18next@26.2.0(typescript@6.0.3):
+    optionalDependencies:
+      typescript: 6.0.3
+
+  iconv-lite@0.4.24:
+    dependencies:
+      safer-buffer: 2.1.2
+
+  iconv-lite@0.7.2:
+    dependencies:
+      safer-buffer: 2.1.2
+
+  ignore-by-default@1.0.1: {}
+
+  ignore@5.3.2: {}
+
+  ignore@7.0.5: {}
+
+  import-fresh@3.3.1:
+    dependencies:
+      parent-module: 1.0.1
+      resolve-from: 4.0.0
+
+  imurmurhash@0.1.4: {}
+
+  inherits@2.0.4: {}
+
+  inline-style-parser@0.2.7: {}
+
+  ip-address@10.2.0: {}
+
+  ipaddr.js@1.9.1: {}
+
+  is-alphabetical@2.0.1: {}
+
+  is-alphanumerical@2.0.1:
+    dependencies:
+      is-alphabetical: 2.0.1
+      is-decimal: 2.0.1
+
+  is-arrayish@0.2.1: {}
+
+  is-binary-path@2.1.0:
+    dependencies:
+      binary-extensions: 2.3.0
+
+  is-decimal@2.0.1: {}
+
+  is-docker@3.0.0: {}
+
+  is-extendable@0.1.1: {}
+
+  is-extglob@2.1.1: {}
+
+  is-fullwidth-code-point@3.0.0: {}
+
+  is-fullwidth-code-point@5.1.0:
+    dependencies:
+      get-east-asian-width: 1.6.0
+
+  is-glob@4.0.3:
+    dependencies:
+      is-extglob: 2.1.1
+
+  is-hexadecimal@2.0.1: {}
+
+  is-in-ssh@1.0.0: {}
+
+  is-inside-container@1.0.0:
+    dependencies:
+      is-docker: 3.0.0
+
+  is-interactive@2.0.0: {}
+
+  is-node-process@1.2.0: {}
+
+  is-number@7.0.0: {}
+
+  is-obj@3.0.0: {}
+
+  is-plain-obj@4.1.0: {}
+
+  is-promise@4.0.0: {}
+
+  is-regexp@3.1.0: {}
+
+  is-stream@2.0.1: {}
+
+  is-stream@4.0.1: {}
+
+  is-unicode-supported@1.3.0: {}
+
+  is-unicode-supported@2.1.0: {}
+
+  is-wsl@3.1.1:
+    dependencies:
+      is-inside-container: 1.0.0
+
+  isexe@2.0.0: {}
+
+  isexe@3.1.5: {}
+
+  jiti@2.7.0: {}
+
+  jose@6.2.3: {}
+
+  js-tokens@4.0.0: {}
+
+  js-yaml@3.14.2:
+    dependencies:
+      argparse: 1.0.10
+      esprima: 4.0.1
+
+  js-yaml@4.1.1:
+    dependencies:
+      argparse: 2.0.1
+
+  jsesc@3.1.0: {}
+
+  json-buffer@3.0.1: {}
+
+  json-parse-even-better-errors@2.3.1: {}
+
+  json-schema-traverse@0.4.1: {}
+
+  json-schema-traverse@1.0.0: {}
+
+  json-schema-typed@8.0.2: {}
+
+  json-stable-stringify-without-jsonify@1.0.1: {}
+
+  json5@2.2.3: {}
+
+  jsonfile@6.2.1:
+    dependencies:
+      universalify: 2.0.1
+    optionalDependencies:
+      graceful-fs: 4.2.11
+
+  jsonrepair@3.14.0: {}
+
+  keyv@4.5.4:
+    dependencies:
+      json-buffer: 3.0.1
+
+  kind-of@6.0.3: {}
+
+  kleur@3.0.3: {}
+
+  kleur@4.1.5: {}
+
+  levn@0.4.1:
+    dependencies:
+      prelude-ls: 1.2.1
+      type-check: 0.4.0
+
+  lightningcss-android-arm64@1.32.0:
+    optional: true
+
+  lightningcss-darwin-arm64@1.32.0:
+    optional: true
+
+  lightningcss-darwin-x64@1.32.0:
+    optional: true
+
+  lightningcss-freebsd-x64@1.32.0:
+    optional: true
+
+  lightningcss-linux-arm-gnueabihf@1.32.0:
+    optional: true
+
+  lightningcss-linux-arm64-gnu@1.32.0:
+    optional: true
+
+  lightningcss-linux-arm64-musl@1.32.0:
+    optional: true
+
+  lightningcss-linux-x64-gnu@1.32.0:
+    optional: true
+
+  lightningcss-linux-x64-musl@1.32.0:
+    optional: true
+
+  lightningcss-win32-arm64-msvc@1.32.0:
+    optional: true
+
+  lightningcss-win32-x64-msvc@1.32.0:
+    optional: true
+
+  lightningcss@1.32.0:
+    dependencies:
+      detect-libc: 2.1.2
+    optionalDependencies:
+      lightningcss-android-arm64: 1.32.0
+      lightningcss-darwin-arm64: 1.32.0
+      lightningcss-darwin-x64: 1.32.0
+      lightningcss-freebsd-x64: 1.32.0
+      lightningcss-linux-arm-gnueabihf: 1.32.0
+      lightningcss-linux-arm64-gnu: 1.32.0
+      lightningcss-linux-arm64-musl: 1.32.0
+      lightningcss-linux-x64-gnu: 1.32.0
+      lightningcss-linux-x64-musl: 1.32.0
+      lightningcss-win32-arm64-msvc: 1.32.0
+      lightningcss-win32-x64-msvc: 1.32.0
+
+  lines-and-columns@1.2.4: {}
+
+  lint-staged@17.0.5:
+    dependencies:
+      listr2: 10.2.1
+      picomatch: 4.0.4
+      string-argv: 0.3.2
+      tinyexec: 1.1.2
+    optionalDependencies:
+      yaml: 2.9.0
+
+  listr2@10.2.1:
+    dependencies:
+      cli-truncate: 5.2.0
+      eventemitter3: 5.0.4
+      log-update: 6.1.0
+      rfdc: 1.4.1
+      wrap-ansi: 10.0.0
+
+  locate-path@6.0.0:
+    dependencies:
+      p-locate: 5.0.0
+
+  lodash@4.18.1: {}
+
+  log-symbols@6.0.0:
+    dependencies:
+      chalk: 5.6.2
+      is-unicode-supported: 1.3.0
+
+  log-update@6.1.0:
+    dependencies:
+      ansi-escapes: 7.3.0
+      cli-cursor: 5.0.0
+      slice-ansi: 7.1.2
+      strip-ansi: 7.2.0
+      wrap-ansi: 9.0.2
+
+  longest-streak@3.1.0: {}
+
+  loose-envify@1.4.0:
+    dependencies:
+      js-tokens: 4.0.0
+
+  lower-case@2.0.2:
+    dependencies:
+      tslib: 2.8.1
+
+  lru-cache@5.1.1:
+    dependencies:
+      yallist: 3.1.1
+
+  lucide-react@1.16.0(react@19.2.6):
+    dependencies:
+      react: 19.2.6
+
+  lucide@1.3.0: {}
+
+  luxon@3.7.2: {}
+
+  magic-string@0.30.21:
+    dependencies:
+      '@jridgewell/sourcemap-codec': 1.5.5
+
+  make-error@1.3.6: {}
+
+  markdown-table@3.0.4: {}
+
+  math-intrinsics@1.1.0: {}
+
+  mdast-util-find-and-replace@3.0.2:
+    dependencies:
+      '@types/mdast': 4.0.4
+      escape-string-regexp: 5.0.0
+      unist-util-is: 6.0.1
+      unist-util-visit-parents: 6.0.2
+
+  mdast-util-from-markdown@2.0.3:
+    dependencies:
+      '@types/mdast': 4.0.4
+      '@types/unist': 3.0.3
+      decode-named-character-reference: 1.3.0
+      devlop: 1.1.0
+      mdast-util-to-string: 4.0.0
+      micromark: 4.0.2
+      micromark-util-decode-numeric-character-reference: 2.0.2
+      micromark-util-decode-string: 2.0.1
+      micromark-util-normalize-identifier: 2.0.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+      unist-util-stringify-position: 4.0.0
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-gfm-autolink-literal@2.0.1:
+    dependencies:
+      '@types/mdast': 4.0.4
+      ccount: 2.0.1
+      devlop: 1.1.0
+      mdast-util-find-and-replace: 3.0.2
+      micromark-util-character: 2.1.1
+
+  mdast-util-gfm-footnote@2.1.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      devlop: 1.1.0
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+      micromark-util-normalize-identifier: 2.0.1
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-gfm-strikethrough@2.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-gfm-table@2.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      devlop: 1.1.0
+      markdown-table: 3.0.4
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-gfm-task-list-item@2.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      devlop: 1.1.0
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-gfm@3.1.0:
+    dependencies:
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-gfm-autolink-literal: 2.0.1
+      mdast-util-gfm-footnote: 2.1.0
+      mdast-util-gfm-strikethrough: 2.0.0
+      mdast-util-gfm-table: 2.0.0
+      mdast-util-gfm-task-list-item: 2.0.0
+      mdast-util-to-markdown: 2.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-mdx-expression@2.0.1:
+    dependencies:
+      '@types/estree-jsx': 1.0.5
+      '@types/hast': 3.0.4
+      '@types/mdast': 4.0.4
+      devlop: 1.1.0
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-mdx-jsx@3.2.0:
+    dependencies:
+      '@types/estree-jsx': 1.0.5
+      '@types/hast': 3.0.4
+      '@types/mdast': 4.0.4
+      '@types/unist': 3.0.3
+      ccount: 2.0.1
+      devlop: 1.1.0
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+      parse-entities: 4.0.2
+      stringify-entities: 4.0.4
+      unist-util-stringify-position: 4.0.0
+      vfile-message: 4.0.3
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-mdxjs-esm@2.0.1:
+    dependencies:
+      '@types/estree-jsx': 1.0.5
+      '@types/hast': 3.0.4
+      '@types/mdast': 4.0.4
+      devlop: 1.1.0
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-phrasing@4.1.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      unist-util-is: 6.0.1
+
+  mdast-util-to-hast@13.2.1:
+    dependencies:
+      '@types/hast': 3.0.4
+      '@types/mdast': 4.0.4
+      '@ungap/structured-clone': 1.3.1
+      devlop: 1.1.0
+      micromark-util-sanitize-uri: 2.0.1
+      trim-lines: 3.0.1
+      unist-util-position: 5.0.0
+      unist-util-visit: 5.1.0
+      vfile: 6.0.3
+
+  mdast-util-to-markdown@2.1.2:
+    dependencies:
+      '@types/mdast': 4.0.4
+      '@types/unist': 3.0.3
+      longest-streak: 3.1.0
+      mdast-util-phrasing: 4.1.0
+      mdast-util-to-string: 4.0.0
+      micromark-util-classify-character: 2.0.1
+      micromark-util-decode-string: 2.0.1
+      unist-util-visit: 5.1.0
+      zwitch: 2.0.4
+
+  mdast-util-to-string@4.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+
+  media-typer@0.3.0: {}
+
+  media-typer@1.1.0: {}
+
+  merge-descriptors@1.0.3: {}
+
+  merge-descriptors@2.0.0: {}
+
+  merge-stream@2.0.0: {}
+
+  merge2@1.4.1: {}
+
+  methods@1.1.2: {}
+
+  micromark-core-commonmark@2.0.3:
+    dependencies:
+      decode-named-character-reference: 1.3.0
+      devlop: 1.1.0
+      micromark-factory-destination: 2.0.1
+      micromark-factory-label: 2.0.1
+      micromark-factory-space: 2.0.1
+      micromark-factory-title: 2.0.1
+      micromark-factory-whitespace: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-chunked: 2.0.1
+      micromark-util-classify-character: 2.0.1
+      micromark-util-html-tag-name: 2.0.1
+      micromark-util-normalize-identifier: 2.0.1
+      micromark-util-resolve-all: 2.0.1
+      micromark-util-subtokenize: 2.1.0
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-extension-gfm-autolink-literal@2.1.0:
+    dependencies:
+      micromark-util-character: 2.1.1
+      micromark-util-sanitize-uri: 2.0.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-extension-gfm-footnote@2.1.0:
+    dependencies:
+      devlop: 1.1.0
+      micromark-core-commonmark: 2.0.3
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-normalize-identifier: 2.0.1
+      micromark-util-sanitize-uri: 2.0.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-extension-gfm-strikethrough@2.1.0:
+    dependencies:
+      devlop: 1.1.0
+      micromark-util-chunked: 2.0.1
+      micromark-util-classify-character: 2.0.1
+      micromark-util-resolve-all: 2.0.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-extension-gfm-table@2.1.1:
+    dependencies:
+      devlop: 1.1.0
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-extension-gfm-tagfilter@2.0.0:
+    dependencies:
+      micromark-util-types: 2.0.2
+
+  micromark-extension-gfm-task-list-item@2.1.0:
+    dependencies:
+      devlop: 1.1.0
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-extension-gfm@3.0.0:
+    dependencies:
+      micromark-extension-gfm-autolink-literal: 2.1.0
+      micromark-extension-gfm-footnote: 2.1.0
+      micromark-extension-gfm-strikethrough: 2.1.0
+      micromark-extension-gfm-table: 2.1.1
+      micromark-extension-gfm-tagfilter: 2.0.0
+      micromark-extension-gfm-task-list-item: 2.1.0
+      micromark-util-combine-extensions: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-factory-destination@2.0.1:
+    dependencies:
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-factory-label@2.0.1:
+    dependencies:
+      devlop: 1.1.0
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-factory-space@2.0.1:
+    dependencies:
+      micromark-util-character: 2.1.1
+      micromark-util-types: 2.0.2
+
+  micromark-factory-title@2.0.1:
+    dependencies:
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-factory-whitespace@2.0.1:
+    dependencies:
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-util-character@2.1.1:
+    dependencies:
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-util-chunked@2.0.1:
+    dependencies:
+      micromark-util-symbol: 2.0.1
+
+  micromark-util-classify-character@2.0.1:
+    dependencies:
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-util-combine-extensions@2.0.1:
+    dependencies:
+      micromark-util-chunked: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-util-decode-numeric-character-reference@2.0.2:
+    dependencies:
+      micromark-util-symbol: 2.0.1
+
+  micromark-util-decode-string@2.0.1:
+    dependencies:
+      decode-named-character-reference: 1.3.0
+      micromark-util-character: 2.1.1
+      micromark-util-decode-numeric-character-reference: 2.0.2
+      micromark-util-symbol: 2.0.1
+
+  micromark-util-encode@2.0.1: {}
+
+  micromark-util-html-tag-name@2.0.1: {}
+
+  micromark-util-normalize-identifier@2.0.1:
+    dependencies:
+      micromark-util-symbol: 2.0.1
+
+  micromark-util-resolve-all@2.0.1:
+    dependencies:
+      micromark-util-types: 2.0.2
+
+  micromark-util-sanitize-uri@2.0.1:
+    dependencies:
+      micromark-util-character: 2.1.1
+      micromark-util-encode: 2.0.1
+      micromark-util-symbol: 2.0.1
+
+  micromark-util-subtokenize@2.1.0:
+    dependencies:
+      devlop: 1.1.0
+      micromark-util-chunked: 2.0.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-util-symbol@2.0.1: {}
+
+  micromark-util-types@2.0.2: {}
+
+  micromark@4.0.2:
+    dependencies:
+      '@types/debug': 4.1.13
+      debug: 4.4.3(supports-color@5.5.0)
+      decode-named-character-reference: 1.3.0
+      devlop: 1.1.0
+      micromark-core-commonmark: 2.0.3
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-chunked: 2.0.1
+      micromark-util-combine-extensions: 2.0.1
+      micromark-util-decode-numeric-character-reference: 2.0.2
+      micromark-util-encode: 2.0.1
+      micromark-util-normalize-identifier: 2.0.1
+      micromark-util-resolve-all: 2.0.1
+      micromark-util-sanitize-uri: 2.0.1
+      micromark-util-subtokenize: 2.1.0
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+    transitivePeerDependencies:
+      - supports-color
+
+  micromatch@4.0.8:
+    dependencies:
+      braces: 3.0.3
+      picomatch: 2.3.2
+
+  mime-db@1.52.0: {}
+
+  mime-db@1.54.0: {}
+
+  mime-types@2.1.35:
+    dependencies:
+      mime-db: 1.52.0
+
+  mime-types@3.0.2:
+    dependencies:
+      mime-db: 1.54.0
+
+  mime@1.6.0: {}
+
+  mimic-fn@2.1.0: {}
+
+  mimic-function@5.0.1: {}
+
+  minimatch@10.2.5:
+    dependencies:
+      brace-expansion: 5.0.6
+
+  minimist@1.2.8: {}
+
+  motion-dom@12.40.0:
+    dependencies:
+      motion-utils: 12.39.0
+
+  motion-utils@12.39.0: {}
+
+  ms@2.0.0: {}
+
+  ms@2.1.3: {}
+
+  msw@2.14.6(@types/node@24.12.4)(typescript@6.0.3):
+    dependencies:
+      '@inquirer/confirm': 6.0.13(@types/node@24.12.4)
+      '@mswjs/interceptors': 0.41.9
+      '@open-draft/deferred-promise': 3.0.0
+      '@types/statuses': 2.0.6
+      cookie: 1.1.1
+      graphql: 16.14.0
+      headers-polyfill: 5.0.1
+      is-node-process: 1.2.0
+      outvariant: 1.4.3
+      path-to-regexp: 6.3.0
+      picocolors: 1.1.1
+      rettime: 0.11.11
+      statuses: 2.0.2
+      strict-event-emitter: 0.5.1
+      tough-cookie: 6.0.1
+      type-fest: 5.6.0
+      until-async: 3.0.2
+      yargs: 17.7.2
+    optionalDependencies:
+      typescript: 6.0.3
+    transitivePeerDependencies:
+      - '@types/node'
+
+  mute-stream@3.0.0: {}
+
+  nanoid@3.3.12: {}
+
+  napi-postinstall@0.3.4: {}
+
+  natural-compare@1.4.0: {}
+
+  negotiator@0.6.3: {}
+
+  negotiator@1.0.0: {}
+
+  next-themes@0.4.6(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
+    dependencies:
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+
+  next@16.2.6(@babel/core@7.29.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
+    dependencies:
+      '@next/env': 16.2.6
+      '@swc/helpers': 0.5.15
+      baseline-browser-mapping: 2.10.33
+      caniuse-lite: 1.0.30001793
+      postcss: 8.4.31
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+      styled-jsx: 5.1.6(@babel/core@7.29.0)(react@19.2.6)
+    optionalDependencies:
+      '@next/swc-darwin-arm64': 16.2.6
+      '@next/swc-darwin-x64': 16.2.6
+      '@next/swc-linux-arm64-gnu': 16.2.6
+      '@next/swc-linux-arm64-musl': 16.2.6
+      '@next/swc-linux-x64-gnu': 16.2.6
+      '@next/swc-linux-x64-musl': 16.2.6
+      '@next/swc-win32-arm64-msvc': 16.2.6
+      '@next/swc-win32-x64-msvc': 16.2.6
+      sharp: 0.34.5
+    transitivePeerDependencies:
+      - '@babel/core'
+      - babel-plugin-macros
+
+  no-case@3.0.4:
+    dependencies:
+      lower-case: 2.0.2
+      tslib: 2.8.1
+
+  node-domexception@1.0.0: {}
+
+  node-fetch@3.3.2:
+    dependencies:
+      data-uri-to-buffer: 4.0.1
+      fetch-blob: 3.2.0
+      formdata-polyfill: 4.0.10
+
+  node-releases@2.0.44: {}
+
+  nodemon@3.1.14:
+    dependencies:
+      chokidar: 3.6.0
+      debug: 4.4.3(supports-color@5.5.0)
+      ignore-by-default: 1.0.1
+      minimatch: 10.2.5
+      pstree.remy: 1.1.8
+      semver: 7.8.0
+      simple-update-notifier: 2.0.0
+      supports-color: 5.5.0
+      touch: 3.1.1
+      undefsafe: 2.0.5
+
+  normalize-path@3.0.0: {}
+
+  npm-run-path@4.0.1:
+    dependencies:
+      path-key: 3.1.1
+
+  npm-run-path@6.0.0:
+    dependencies:
+      path-key: 4.0.0
+      unicorn-magic: 0.3.0
+
+  object-assign@4.1.1: {}
+
+  object-inspect@1.13.4: {}
+
+  object-treeify@1.1.33: {}
+
+  ollama@0.6.3:
+    dependencies:
+      whatwg-fetch: 3.6.20
+
+  on-finished@2.4.1:
+    dependencies:
+      ee-first: 1.1.1
+
+  onborda@1.2.5(@radix-ui/react-portal@1.1.9(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(framer-motion@12.40.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(next@16.2.6(@babel/core@7.29.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
+    dependencies:
+      '@radix-ui/react-portal': 1.1.9(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      framer-motion: 12.40.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      next: 16.2.6(@babel/core@7.29.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+
+  once@1.4.0:
+    dependencies:
+      wrappy: 1.0.2
+
+  onetime@5.1.2:
+    dependencies:
+      mimic-fn: 2.1.0
+
+  onetime@7.0.0:
+    dependencies:
+      mimic-function: 5.0.1
+
+  open@11.0.0:
+    dependencies:
+      default-browser: 5.5.0
+      define-lazy-prop: 3.0.0
+      is-in-ssh: 1.0.0
+      is-inside-container: 1.0.0
+      powershell-utils: 0.1.0
+      wsl-utils: 0.3.1
+
+  openai@6.44.0(zod@4.4.3):
+    optionalDependencies:
+      zod: 4.4.3
+
+  optionator@0.9.4:
+    dependencies:
+      deep-is: 0.1.4
+      fast-levenshtein: 2.0.6
+      levn: 0.4.1
+      prelude-ls: 1.2.1
+      type-check: 0.4.0
+      word-wrap: 1.2.5
+
+  ora@8.2.0:
+    dependencies:
+      chalk: 5.6.2
+      cli-cursor: 5.0.0
+      cli-spinners: 2.9.2
+      is-interactive: 2.0.0
+      is-unicode-supported: 2.1.0
+      log-symbols: 6.0.0
+      stdin-discarder: 0.2.2
+      string-width: 7.2.0
+      strip-ansi: 7.2.0
+
+  outvariant@1.4.3: {}
+
+  p-limit@3.1.0:
+    dependencies:
+      yocto-queue: 0.1.0
+
+  p-locate@5.0.0:
+    dependencies:
+      p-limit: 3.1.0
+
+  parent-module@1.0.1:
+    dependencies:
+      callsites: 3.1.0
+
+  parse-entities@4.0.2:
+    dependencies:
+      '@types/unist': 2.0.11
+      character-entities-legacy: 3.0.0
+      character-reference-invalid: 2.0.1
+      decode-named-character-reference: 1.3.0
+      is-alphanumerical: 2.0.1
+      is-decimal: 2.0.1
+      is-hexadecimal: 2.0.1
+
+  parse-json@5.2.0:
+    dependencies:
+      '@babel/code-frame': 7.29.0
+      error-ex: 1.3.4
+      json-parse-even-better-errors: 2.3.1
+      lines-and-columns: 1.2.4
+
+  parse-ms@4.0.0: {}
+
+  parseurl@1.3.3: {}
+
+  path-browserify@1.0.1: {}
+
+  path-exists@4.0.0: {}
+
+  path-key@3.1.1: {}
+
+  path-key@4.0.0: {}
+
+  path-to-regexp@0.1.13: {}
+
+  path-to-regexp@6.3.0: {}
+
+  path-to-regexp@8.4.2: {}
+
+  path-type@4.0.0: {}
+
+  picocolors@1.1.1: {}
+
+  picomatch@2.3.2: {}
+
+  picomatch@4.0.4: {}
+
+  pkce-challenge@5.0.1: {}
+
+  postcss-selector-parser@6.0.10:
+    dependencies:
+      cssesc: 3.0.0
+      util-deprecate: 1.0.2
+
+  postcss-selector-parser@7.1.1:
+    dependencies:
+      cssesc: 3.0.0
+      util-deprecate: 1.0.2
+
+  postcss@8.4.31:
+    dependencies:
+      nanoid: 3.3.12
+      picocolors: 1.1.1
+      source-map-js: 1.2.1
+
+  postcss@8.5.14:
+    dependencies:
+      nanoid: 3.3.12
+      picocolors: 1.1.1
+      source-map-js: 1.2.1
+
+  powershell-utils@0.1.0: {}
+
+  prelude-ls@1.2.1: {}
+
+  prettier-linter-helpers@1.0.1:
+    dependencies:
+      fast-diff: 1.3.0
+
+  prettier@3.8.3: {}
+
+  pretty-ms@9.3.0:
+    dependencies:
+      parse-ms: 4.0.0
+
+  prompts@2.4.2:
+    dependencies:
+      kleur: 3.0.3
+      sisteransi: 1.0.5
+
+  property-information@7.1.0: {}
+
+  proxy-addr@2.0.7:
+    dependencies:
+      forwarded: 0.2.0
+      ipaddr.js: 1.9.1
+
+  pstree.remy@1.1.8: {}
+
+  punycode@2.3.1: {}
+
+  qs@6.15.1:
+    dependencies:
+      side-channel: 1.1.0
+
+  queue-microtask@1.2.3: {}
+
+  radix-ui@1.4.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-accessible-icon': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-accordion': 1.2.12(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-alert-dialog': 1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-arrow': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-aspect-ratio': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-avatar': 1.1.10(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-checkbox': 1.3.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-collapsible': 1.1.12(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-collection': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-context-menu': 2.2.16(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-dialog': 1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-direction': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-dismissable-layer': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-dropdown-menu': 2.1.16(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-focus-guards': 1.1.3(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-focus-scope': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-form': 0.1.8(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-hover-card': 1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-label': 2.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-menu': 2.1.16(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-menubar': 1.1.16(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-navigation-menu': 1.2.14(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-one-time-password-field': 0.1.8(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-password-toggle-field': 0.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-popover': 1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-popper': 1.2.8(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-portal': 1.1.9(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-presence': 1.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-progress': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-radio-group': 1.3.8(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-roving-focus': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-scroll-area': 1.2.10(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-select': 2.2.6(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-separator': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-slider': 1.3.6(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-slot': 1.2.3(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-switch': 1.2.6(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-tabs': 1.1.13(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-toast': 1.2.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-toggle': 1.1.10(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-toggle-group': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-toolbar': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-tooltip': 1.2.8(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-effect-event': 0.0.2(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-escape-keydown': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-is-hydrated': 0.1.0(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-use-size': 1.1.1(@types/react@19.2.14)(react@19.2.6)
+      '@radix-ui/react-visually-hidden': 1.2.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  range-parser@1.2.1: {}
+
+  raw-body@2.5.3:
+    dependencies:
+      bytes: 3.1.2
+      http-errors: 2.0.1
+      iconv-lite: 0.4.24
+      unpipe: 1.0.0
+
+  raw-body@3.0.2:
+    dependencies:
+      bytes: 3.1.2
+      http-errors: 2.0.1
+      iconv-lite: 0.7.2
+      unpipe: 1.0.0
+
+  react-day-picker@10.0.1(@types/react@19.2.14)(react@19.2.6):
+    dependencies:
+      '@date-fns/tz': 1.4.1
+      date-fns: 4.1.0
+      react: 19.2.6
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  react-diff-view@3.3.3(react@19.2.6):
+    dependencies:
+      classnames: 2.5.1
+      diff-match-patch: 1.0.5
+      gitdiff-parser: 0.3.1
+      lodash: 4.18.1
+      react: 19.2.6
+      shallow-equal: 3.1.0
+      warning: 4.0.3
+
+  react-dom@19.2.6(react@19.2.6):
+    dependencies:
+      react: 19.2.6
+      scheduler: 0.27.0
+
+  react-i18next@17.0.8(i18next@26.2.0(typescript@6.0.3))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(typescript@6.0.3):
+    dependencies:
+      '@babel/runtime': 7.29.2
+      html-parse-stringify: 3.0.1
+      i18next: 26.2.0(typescript@6.0.3)
+      react: 19.2.6
+      use-sync-external-store: 1.6.0(react@19.2.6)
+    optionalDependencies:
+      react-dom: 19.2.6(react@19.2.6)
+      typescript: 6.0.3
+
+  react-markdown@10.1.0(@types/react@19.2.14)(react@19.2.6):
+    dependencies:
+      '@types/hast': 3.0.4
+      '@types/mdast': 4.0.4
+      '@types/react': 19.2.14
+      devlop: 1.1.0
+      hast-util-to-jsx-runtime: 2.3.6
+      html-url-attributes: 3.0.1
+      mdast-util-to-hast: 13.2.1
+      react: 19.2.6
+      remark-parse: 11.0.0
+      remark-rehype: 11.1.2
+      unified: 11.0.5
+      unist-util-visit: 5.1.0
+      vfile: 6.0.3
+    transitivePeerDependencies:
+      - supports-color
+
+  react-remove-scroll-bar@2.3.8(@types/react@19.2.14)(react@19.2.6):
+    dependencies:
+      react: 19.2.6
+      react-style-singleton: 2.2.3(@types/react@19.2.14)(react@19.2.6)
+      tslib: 2.8.1
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  react-remove-scroll@2.7.2(@types/react@19.2.14)(react@19.2.6):
+    dependencies:
+      react: 19.2.6
+      react-remove-scroll-bar: 2.3.8(@types/react@19.2.14)(react@19.2.6)
+      react-style-singleton: 2.2.3(@types/react@19.2.14)(react@19.2.6)
+      tslib: 2.8.1
+      use-callback-ref: 1.3.3(@types/react@19.2.14)(react@19.2.6)
+      use-sidecar: 1.1.3(@types/react@19.2.14)(react@19.2.6)
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  react-resizable-panels@4.11.2(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
+    dependencies:
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+
+  react-router-dom@7.15.1(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
+    dependencies:
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+      react-router: 7.15.1(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+
+  react-router@7.15.1(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
+    dependencies:
+      cookie: 1.1.1
+      react: 19.2.6
+      set-cookie-parser: 2.7.2
+    optionalDependencies:
+      react-dom: 19.2.6(react@19.2.6)
+
+  react-style-singleton@2.2.3(@types/react@19.2.14)(react@19.2.6):
+    dependencies:
+      get-nonce: 1.0.1
+      react: 19.2.6
+      tslib: 2.8.1
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  react@19.2.6: {}
+
+  readdirp@3.6.0:
+    dependencies:
+      picomatch: 2.3.2
+
+  recast@0.23.11:
+    dependencies:
+      ast-types: 0.16.1
+      esprima: 4.0.1
+      source-map: 0.6.1
+      tiny-invariant: 1.3.3
+      tslib: 2.8.1
+
+  remark-gfm@4.0.1:
+    dependencies:
+      '@types/mdast': 4.0.4
+      mdast-util-gfm: 3.1.0
+      micromark-extension-gfm: 3.0.0
+      remark-parse: 11.0.0
+      remark-stringify: 11.0.0
+      unified: 11.0.5
+    transitivePeerDependencies:
+      - supports-color
+
+  remark-parse@11.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      mdast-util-from-markdown: 2.0.3
+      micromark-util-types: 2.0.2
+      unified: 11.0.5
+    transitivePeerDependencies:
+      - supports-color
+
+  remark-rehype@11.1.2:
+    dependencies:
+      '@types/hast': 3.0.4
+      '@types/mdast': 4.0.4
+      mdast-util-to-hast: 13.2.1
+      unified: 11.0.5
+      vfile: 6.0.3
+
+  remark-stringify@11.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      mdast-util-to-markdown: 2.1.2
+      unified: 11.0.5
+
+  require-directory@2.1.1: {}
+
+  require-from-string@2.0.2: {}
+
+  resolve-from@4.0.0: {}
+
+  resolve-pkg-maps@1.0.0: {}
+
+  restore-cursor@5.1.0:
+    dependencies:
+      onetime: 7.0.0
+      signal-exit: 4.1.0
+
+  rettime@0.11.11: {}
+
+  reusify@1.1.0: {}
+
+  rfdc@1.4.1: {}
+
+  rolldown@1.0.1:
+    dependencies:
+      '@oxc-project/types': 0.130.0
+      '@rolldown/pluginutils': 1.0.1
+    optionalDependencies:
+      '@rolldown/binding-android-arm64': 1.0.1
+      '@rolldown/binding-darwin-arm64': 1.0.1
+      '@rolldown/binding-darwin-x64': 1.0.1
+      '@rolldown/binding-freebsd-x64': 1.0.1
+      '@rolldown/binding-linux-arm-gnueabihf': 1.0.1
+      '@rolldown/binding-linux-arm64-gnu': 1.0.1
+      '@rolldown/binding-linux-arm64-musl': 1.0.1
+      '@rolldown/binding-linux-ppc64-gnu': 1.0.1
+      '@rolldown/binding-linux-s390x-gnu': 1.0.1
+      '@rolldown/binding-linux-x64-gnu': 1.0.1
+      '@rolldown/binding-linux-x64-musl': 1.0.1
+      '@rolldown/binding-openharmony-arm64': 1.0.1
+      '@rolldown/binding-wasm32-wasi': 1.0.1
+      '@rolldown/binding-win32-arm64-msvc': 1.0.1
+      '@rolldown/binding-win32-x64-msvc': 1.0.1
+
+  router@2.2.0:
+    dependencies:
+      debug: 4.4.3(supports-color@5.5.0)
+      depd: 2.0.0
+      is-promise: 4.0.0
+      parseurl: 1.3.3
+      path-to-regexp: 8.4.2
+    transitivePeerDependencies:
+      - supports-color
+
+  run-applescript@7.1.0: {}
+
+  run-parallel@1.2.0:
+    dependencies:
+      queue-microtask: 1.2.3
+
+  rxjs@7.8.2:
+    dependencies:
+      tslib: 2.8.1
+
+  safe-buffer@5.2.1: {}
+
+  safer-buffer@2.1.2: {}
+
+  scheduler@0.27.0: {}
+
+  section-matter@1.0.0:
+    dependencies:
+      extend-shallow: 2.0.1
+      kind-of: 6.0.3
+
+  semver@6.3.1: {}
+
+  semver@7.8.0: {}
+
+  semver@7.8.1:
+    optional: true
+
+  send@0.19.2:
+    dependencies:
+      debug: 2.6.9
+      depd: 2.0.0
+      destroy: 1.2.0
+      encodeurl: 2.0.0
+      escape-html: 1.0.3
+      etag: 1.8.1
+      fresh: 0.5.2
+      http-errors: 2.0.1
+      mime: 1.6.0
+      ms: 2.1.3
+      on-finished: 2.4.1
+      range-parser: 1.2.1
+      statuses: 2.0.2
+    transitivePeerDependencies:
+      - supports-color
+
+  send@1.2.1:
+    dependencies:
+      debug: 4.4.3(supports-color@5.5.0)
+      encodeurl: 2.0.0
+      escape-html: 1.0.3
+      etag: 1.8.1
+      fresh: 2.0.0
+      http-errors: 2.0.1
+      mime-types: 3.0.2
+      ms: 2.1.3
+      on-finished: 2.4.1
+      range-parser: 1.2.1
+      statuses: 2.0.2
+    transitivePeerDependencies:
+      - supports-color
+
+  serve-static@1.16.3:
+    dependencies:
+      encodeurl: 2.0.0
+      escape-html: 1.0.3
+      parseurl: 1.3.3
+      send: 0.19.2
+    transitivePeerDependencies:
+      - supports-color
+
+  serve-static@2.2.1:
+    dependencies:
+      encodeurl: 2.0.0
+      escape-html: 1.0.3
+      parseurl: 1.3.3
+      send: 1.2.1
+    transitivePeerDependencies:
+      - supports-color
+
+  set-cookie-parser@2.7.2: {}
+
+  set-cookie-parser@3.1.0: {}
+
+  setprototypeof@1.2.0: {}
+
+  shadcn-prose@1.2.1: {}
+
+  shadcn@4.7.0(@cfworker/json-schema@4.1.1)(@types/node@24.12.4)(typescript@6.0.3):
+    dependencies:
+      '@babel/core': 7.29.0
+      '@babel/parser': 7.29.3
+      '@babel/plugin-transform-typescript': 7.28.6(@babel/core@7.29.0)
+      '@babel/preset-typescript': 7.28.5(@babel/core@7.29.0)
+      '@dotenvx/dotenvx': 1.66.0
+      '@modelcontextprotocol/sdk': 1.29.0(@cfworker/json-schema@4.1.1)(zod@3.25.76)
+      '@types/validate-npm-package-name': 4.0.2
+      browserslist: 4.28.2
+      commander: 14.0.3
+      cosmiconfig: 9.0.1(typescript@6.0.3)
+      dedent: 1.7.2
+      deepmerge: 4.3.1
+      diff: 8.0.4
+      execa: 9.6.1
+      fast-glob: 3.3.3
+      fs-extra: 11.3.5
+      fuzzysort: 3.1.0
+      https-proxy-agent: 7.0.6
+      kleur: 4.1.5
+      msw: 2.14.6(@types/node@24.12.4)(typescript@6.0.3)
+      node-fetch: 3.3.2
+      open: 11.0.0
+      ora: 8.2.0
+      postcss: 8.5.14
+      postcss-selector-parser: 7.1.1
+      prompts: 2.4.2
+      recast: 0.23.11
+      stringify-object: 5.0.0
+      tailwind-merge: 3.6.0
+      ts-morph: 26.0.0
+      tsconfig-paths: 4.2.0
+      validate-npm-package-name: 7.0.2
+      zod: 3.25.76
+      zod-to-json-schema: 3.25.2(zod@3.25.76)
+    transitivePeerDependencies:
+      - '@cfworker/json-schema'
+      - '@types/node'
+      - babel-plugin-macros
+      - supports-color
+      - typescript
+
+  shallow-equal@3.1.0: {}
+
+  sharp@0.34.5:
+    dependencies:
+      '@img/colour': 1.1.0
+      detect-libc: 2.1.2
+      semver: 7.8.1
+    optionalDependencies:
+      '@img/sharp-darwin-arm64': 0.34.5
+      '@img/sharp-darwin-x64': 0.34.5
+      '@img/sharp-libvips-darwin-arm64': 1.2.4
+      '@img/sharp-libvips-darwin-x64': 1.2.4
+      '@img/sharp-libvips-linux-arm': 1.2.4
+      '@img/sharp-libvips-linux-arm64': 1.2.4
+      '@img/sharp-libvips-linux-ppc64': 1.2.4
+      '@img/sharp-libvips-linux-riscv64': 1.2.4
+      '@img/sharp-libvips-linux-s390x': 1.2.4
+      '@img/sharp-libvips-linux-x64': 1.2.4
+      '@img/sharp-libvips-linuxmusl-arm64': 1.2.4
+      '@img/sharp-libvips-linuxmusl-x64': 1.2.4
+      '@img/sharp-linux-arm': 0.34.5
+      '@img/sharp-linux-arm64': 0.34.5
+      '@img/sharp-linux-ppc64': 0.34.5
+      '@img/sharp-linux-riscv64': 0.34.5
+      '@img/sharp-linux-s390x': 0.34.5
+      '@img/sharp-linux-x64': 0.34.5
+      '@img/sharp-linuxmusl-arm64': 0.34.5
+      '@img/sharp-linuxmusl-x64': 0.34.5
+      '@img/sharp-wasm32': 0.34.5
+      '@img/sharp-win32-arm64': 0.34.5
+      '@img/sharp-win32-ia32': 0.34.5
+      '@img/sharp-win32-x64': 0.34.5
+    optional: true
+
+  shebang-command@2.0.0:
+    dependencies:
+      shebang-regex: 3.0.0
+
+  shebang-regex@3.0.0: {}
+
+  shell-quote@1.8.3: {}
+
+  side-channel-list@1.0.1:
+    dependencies:
+      es-errors: 1.3.0
+      object-inspect: 1.13.4
+
+  side-channel-map@1.0.1:
+    dependencies:
+      call-bound: 1.0.4
+      es-errors: 1.3.0
+      get-intrinsic: 1.3.0
+      object-inspect: 1.13.4
+
+  side-channel-weakmap@1.0.2:
+    dependencies:
+      call-bound: 1.0.4
+      es-errors: 1.3.0
+      get-intrinsic: 1.3.0
+      object-inspect: 1.13.4
+      side-channel-map: 1.0.1
+
+  side-channel@1.1.0:
+    dependencies:
+      es-errors: 1.3.0
+      object-inspect: 1.13.4
+      side-channel-list: 1.0.1
+      side-channel-map: 1.0.1
+      side-channel-weakmap: 1.0.2
+
+  signal-exit@3.0.7: {}
+
+  signal-exit@4.1.0: {}
+
+  simple-update-notifier@2.0.0:
+    dependencies:
+      semver: 7.8.0
+
+  sisteransi@1.0.5: {}
+
+  slice-ansi@7.1.2:
+    dependencies:
+      ansi-styles: 6.2.3
+      is-fullwidth-code-point: 5.1.0
+
+  slice-ansi@8.0.0:
+    dependencies:
+      ansi-styles: 6.2.3
+      is-fullwidth-code-point: 5.1.0
+
+  snake-case@3.0.4:
+    dependencies:
+      dot-case: 3.0.4
+      tslib: 2.8.1
+
+  sonner@2.0.7(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
+    dependencies:
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+
+  source-map-js@1.2.1: {}
+
+  source-map@0.6.1: {}
+
+  space-separated-tokens@2.0.2: {}
+
+  spawn-command@0.0.2: {}
+
+  sprintf-js@1.0.3: {}
+
+  stable-hash-x@0.2.0: {}
+
+  statuses@2.0.2: {}
+
+  stdin-discarder@0.2.2: {}
+
+  strict-event-emitter@0.5.1: {}
+
+  string-argv@0.3.2: {}
+
+  string-format@2.0.0: {}
+
+  string-width@4.2.3:
+    dependencies:
+      emoji-regex: 8.0.0
+      is-fullwidth-code-point: 3.0.0
+      strip-ansi: 6.0.1
+
+  string-width@7.2.0:
+    dependencies:
+      emoji-regex: 10.6.0
+      get-east-asian-width: 1.6.0
+      strip-ansi: 7.2.0
+
+  string-width@8.2.1:
+    dependencies:
+      get-east-asian-width: 1.6.0
+      strip-ansi: 7.2.0
+
+  stringify-entities@4.0.4:
+    dependencies:
+      character-entities-html4: 2.1.0
+      character-entities-legacy: 3.0.0
+
+  stringify-object@5.0.0:
+    dependencies:
+      get-own-enumerable-keys: 1.0.0
+      is-obj: 3.0.0
+      is-regexp: 3.1.0
+
+  strip-ansi@6.0.1:
+    dependencies:
+      ansi-regex: 5.0.1
+
+  strip-ansi@7.2.0:
+    dependencies:
+      ansi-regex: 6.2.2
+
+  strip-bom-string@1.0.0: {}
+
+  strip-bom@3.0.0: {}
+
+  strip-final-newline@2.0.0: {}
+
+  strip-final-newline@4.0.0: {}
+
+  style-to-js@1.1.21:
+    dependencies:
+      style-to-object: 1.0.14
+
+  style-to-object@1.0.14:
+    dependencies:
+      inline-style-parser: 0.2.7
+
+  styled-jsx@5.1.6(@babel/core@7.29.0)(react@19.2.6):
+    dependencies:
+      client-only: 0.0.1
+      react: 19.2.6
+    optionalDependencies:
+      '@babel/core': 7.29.0
+
+  supports-color@5.5.0:
+    dependencies:
+      has-flag: 3.0.0
+
+  supports-color@7.2.0:
+    dependencies:
+      has-flag: 4.0.0
+
+  supports-color@8.1.1:
+    dependencies:
+      has-flag: 4.0.0
+
+  svg-parser@2.0.4: {}
+
+  synckit@0.11.12:
+    dependencies:
+      '@pkgr/core': 0.2.9
+
+  tagged-tag@1.0.0: {}
+
+  tailwind-merge@3.6.0: {}
+
+  tailwindcss@4.3.0: {}
+
+  tapable@2.3.3: {}
+
+  tiny-invariant@1.3.3: {}
+
+  tinyexec@1.1.2: {}
+
+  tinyglobby@0.2.16:
+    dependencies:
+      fdir: 6.5.0(picomatch@4.0.4)
+      picomatch: 4.0.4
+
+  tldts-core@7.0.30: {}
+
+  tldts@7.0.30:
+    dependencies:
+      tldts-core: 7.0.30
+
+  to-regex-range@5.0.1:
+    dependencies:
+      is-number: 7.0.0
+
+  toidentifier@1.0.1: {}
+
+  touch@3.1.1: {}
+
+  tough-cookie@6.0.1:
+    dependencies:
+      tldts: 7.0.30
+
+  tree-kill@1.2.2: {}
+
+  trim-lines@3.0.1: {}
+
+  trough@2.2.0: {}
+
+  ts-api-utils@2.5.0(typescript@6.0.3):
+    dependencies:
+      typescript: 6.0.3
+
+  ts-morph@26.0.0:
+    dependencies:
+      '@ts-morph/common': 0.27.0
+      code-block-writer: 13.0.3
+
+  ts-node@10.9.2(@types/node@20.19.41)(typescript@5.9.3):
+    dependencies:
+      '@cspotcode/source-map-support': 0.8.1
+      '@tsconfig/node10': 1.0.12
+      '@tsconfig/node12': 1.0.11
+      '@tsconfig/node14': 1.0.3
+      '@tsconfig/node16': 1.0.4
+      '@types/node': 20.19.41
+      acorn: 8.16.0
+      acorn-walk: 8.3.5
+      arg: 4.1.3
+      create-require: 1.1.1
+      diff: 4.0.4
+      make-error: 1.3.6
+      typescript: 5.9.3
+      v8-compile-cache-lib: 3.0.1
+      yn: 3.1.1
+
+  tsconfig-paths@4.2.0:
+    dependencies:
+      json5: 2.2.3
+      minimist: 1.2.8
+      strip-bom: 3.0.0
+
+  tslib@2.8.1: {}
+
+  tw-animate-css@1.4.0: {}
+
+  type-check@0.4.0:
+    dependencies:
+      prelude-ls: 1.2.1
+
+  type-fest@5.6.0:
+    dependencies:
+      tagged-tag: 1.0.0
+
+  type-is@1.6.18:
+    dependencies:
+      media-typer: 0.3.0
+      mime-types: 2.1.35
+
+  type-is@2.1.0:
+    dependencies:
+      content-type: 2.0.0
+      media-typer: 1.1.0
+      mime-types: 3.0.2
+
+  typescript-eslint@8.59.3(eslint@10.3.0(jiti@2.7.0))(typescript@6.0.3):
+    dependencies:
+      '@typescript-eslint/eslint-plugin': 8.59.3(@typescript-eslint/parser@8.59.3(eslint@10.3.0(jiti@2.7.0))(typescript@6.0.3))(eslint@10.3.0(jiti@2.7.0))(typescript@6.0.3)
+      '@typescript-eslint/parser': 8.59.3(eslint@10.3.0(jiti@2.7.0))(typescript@6.0.3)
+      '@typescript-eslint/typescript-estree': 8.59.3(typescript@6.0.3)
+      '@typescript-eslint/utils': 8.59.3(eslint@10.3.0(jiti@2.7.0))(typescript@6.0.3)
+      eslint: 10.3.0(jiti@2.7.0)
+      typescript: 6.0.3
+    transitivePeerDependencies:
+      - supports-color
+
+  typescript@5.9.3: {}
+
+  typescript@6.0.3: {}
+
+  undefsafe@2.0.5: {}
+
+  undici-types@6.21.0: {}
+
+  undici-types@7.16.0: {}
+
+  unicorn-magic@0.3.0: {}
+
+  unidiff@1.0.4:
+    dependencies:
+      diff: 5.2.2
+
+  unified@11.0.5:
+    dependencies:
+      '@types/unist': 3.0.3
+      bail: 2.0.2
+      devlop: 1.1.0
+      extend: 3.0.2
+      is-plain-obj: 4.1.0
+      trough: 2.2.0
+      vfile: 6.0.3
+
+  unist-util-is@6.0.1:
+    dependencies:
+      '@types/unist': 3.0.3
+
+  unist-util-position@5.0.0:
+    dependencies:
+      '@types/unist': 3.0.3
+
+  unist-util-stringify-position@4.0.0:
+    dependencies:
+      '@types/unist': 3.0.3
+
+  unist-util-visit-parents@6.0.2:
+    dependencies:
+      '@types/unist': 3.0.3
+      unist-util-is: 6.0.1
+
+  unist-util-visit@5.1.0:
+    dependencies:
+      '@types/unist': 3.0.3
+      unist-util-is: 6.0.1
+      unist-util-visit-parents: 6.0.2
+
+  universalify@2.0.1: {}
+
+  unpipe@1.0.0: {}
+
+  unrs-resolver@1.11.1:
+    dependencies:
+      napi-postinstall: 0.3.4
+    optionalDependencies:
+      '@unrs/resolver-binding-android-arm-eabi': 1.11.1
+      '@unrs/resolver-binding-android-arm64': 1.11.1
+      '@unrs/resolver-binding-darwin-arm64': 1.11.1
+      '@unrs/resolver-binding-darwin-x64': 1.11.1
+      '@unrs/resolver-binding-freebsd-x64': 1.11.1
+      '@unrs/resolver-binding-linux-arm-gnueabihf': 1.11.1
+      '@unrs/resolver-binding-linux-arm-musleabihf': 1.11.1
+      '@unrs/resolver-binding-linux-arm64-gnu': 1.11.1
+      '@unrs/resolver-binding-linux-arm64-musl': 1.11.1
+      '@unrs/resolver-binding-linux-ppc64-gnu': 1.11.1
+      '@unrs/resolver-binding-linux-riscv64-gnu': 1.11.1
+      '@unrs/resolver-binding-linux-riscv64-musl': 1.11.1
+      '@unrs/resolver-binding-linux-s390x-gnu': 1.11.1
+      '@unrs/resolver-binding-linux-x64-gnu': 1.11.1
+      '@unrs/resolver-binding-linux-x64-musl': 1.11.1
+      '@unrs/resolver-binding-wasm32-wasi': 1.11.1
+      '@unrs/resolver-binding-win32-arm64-msvc': 1.11.1
+      '@unrs/resolver-binding-win32-ia32-msvc': 1.11.1
+      '@unrs/resolver-binding-win32-x64-msvc': 1.11.1
+
+  until-async@3.0.2: {}
+
+  update-browserslist-db@1.2.3(browserslist@4.28.2):
+    dependencies:
+      browserslist: 4.28.2
+      escalade: 3.2.0
+      picocolors: 1.1.1
+
+  uri-js@4.4.1:
+    dependencies:
+      punycode: 2.3.1
+
+  use-callback-ref@1.3.3(@types/react@19.2.14)(react@19.2.6):
+    dependencies:
+      react: 19.2.6
+      tslib: 2.8.1
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  use-sidecar@1.1.3(@types/react@19.2.14)(react@19.2.6):
+    dependencies:
+      detect-node-es: 1.1.0
+      react: 19.2.6
+      tslib: 2.8.1
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  use-sync-external-store@1.6.0(react@19.2.6):
+    dependencies:
+      react: 19.2.6
+
+  util-deprecate@1.0.2: {}
+
+  utils-merge@1.0.1: {}
+
+  uuid@13.0.2: {}
+
+  v8-compile-cache-lib@3.0.1: {}
+
+  validate-npm-package-name@7.0.2: {}
+
+  vary@1.1.2: {}
+
+  vaul@1.1.2(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
+    dependencies:
+      '@radix-ui/react-dialog': 1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+    transitivePeerDependencies:
+      - '@types/react'
+      - '@types/react-dom'
+
+  vfile-message@4.0.3:
+    dependencies:
+      '@types/unist': 3.0.3
+      unist-util-stringify-position: 4.0.0
+
+  vfile@6.0.3:
+    dependencies:
+      '@types/unist': 3.0.3
+      vfile-message: 4.0.3
+
+  vite-plugin-svgr@5.2.0(typescript@6.0.3)(vite@8.0.13(@types/node@24.12.4)(jiti@2.7.0)(yaml@2.9.0)):
+    dependencies:
+      '@rollup/pluginutils': 5.3.0
+      '@svgr/core': 8.1.0(typescript@6.0.3)
+      '@svgr/plugin-jsx': 8.1.0(@svgr/core@8.1.0(typescript@6.0.3))
+      vite: 8.0.13(@types/node@24.12.4)(jiti@2.7.0)(yaml@2.9.0)
+    transitivePeerDependencies:
+      - rollup
+      - supports-color
+      - typescript
+
+  vite@8.0.13(@types/node@24.12.4)(jiti@2.7.0)(yaml@2.9.0):
+    dependencies:
+      lightningcss: 1.32.0
+      picomatch: 4.0.4
+      postcss: 8.5.14
+      rolldown: 1.0.1
+      tinyglobby: 0.2.16
+    optionalDependencies:
+      '@types/node': 24.12.4
+      fsevents: 2.3.3
+      jiti: 2.7.0
+      yaml: 2.9.0
+
+  void-elements@3.1.0: {}
+
+  warning@4.0.3:
+    dependencies:
+      loose-envify: 1.4.0
+
+  web-streams-polyfill@3.3.3: {}
+
+  whatwg-fetch@3.6.20: {}
+
+  which@2.0.2:
+    dependencies:
+      isexe: 2.0.0
+
+  which@4.0.0:
+    dependencies:
+      isexe: 3.1.5
+
+  word-wrap@1.2.5: {}
+
+  wrap-ansi@10.0.0:
+    dependencies:
+      ansi-styles: 6.2.3
+      string-width: 8.2.1
+      strip-ansi: 7.2.0
+
+  wrap-ansi@7.0.0:
+    dependencies:
+      ansi-styles: 4.3.0
+      string-width: 4.2.3
+      strip-ansi: 6.0.1
+
+  wrap-ansi@9.0.2:
+    dependencies:
+      ansi-styles: 6.2.3
+      string-width: 7.2.0
+      strip-ansi: 7.2.0
+
+  wrappy@1.0.2: {}
+
+  wsl-utils@0.3.1:
+    dependencies:
+      is-wsl: 3.1.1
+      powershell-utils: 0.1.0
+
+  y18n@5.0.8: {}
+
+  yallist@3.1.1: {}
+
+  yaml@2.9.0:
+    optional: true
+
+  yargs-parser@21.1.1: {}
+
+  yargs@17.7.2:
+    dependencies:
+      cliui: 8.0.1
+      escalade: 3.2.0
+      get-caller-file: 2.0.5
+      require-directory: 2.1.1
+      string-width: 4.2.3
+      y18n: 5.0.8
+      yargs-parser: 21.1.1
+
+  yn@3.1.1: {}
+
+  yocto-queue@0.1.0: {}
+
+  yocto-spinner@1.2.0:
+    dependencies:
+      yoctocolors: 2.1.2
+
+  yoctocolors@2.1.2: {}
+
+  zod-to-json-schema@3.25.2(zod@3.25.76):
+    dependencies:
+      zod: 3.25.76
+
+  zod-to-json-schema@3.25.2(zod@4.4.3):
+    dependencies:
+      zod: 4.4.3
+
+  zod-validation-error@4.0.2(zod@4.4.3):
+    dependencies:
+      zod: 4.4.3
+
+  zod@3.25.76: {}
+
+  zod@4.4.3: {}
+
+  zwitch@2.0.4: {}
diff --git a/examples/web_ui/pnpm-workspace.yaml b/examples/web_ui/pnpm-workspace.yaml
new file mode 100644
index 0000000..a71fb1f
--- /dev/null
+++ b/examples/web_ui/pnpm-workspace.yaml
@@ -0,0 +1,6 @@
+packages:
+    - frontend
+    - backend
+
+ignoredBuiltDependencies:
+    - msw
diff --git a/pyproject.toml b/pyproject.toml
new file mode 100644
index 0000000..744e971
--- /dev/null
+++ b/pyproject.toml
@@ -0,0 +1,180 @@
+
+[project]
+name = "agentscope"
+dynamic = ["version"]
+description = "AgentScope: A Flexible yet Robust Multi-Agent Platform."
+readme = "README.md"
+authors = [
+    { name = "SysML team of Alibaba Tongyi Lab", email = "gaodawei.gdw@alibaba-inc.com" }
+]
+license = "Apache-2.0"
+keywords = ["agent", "multi-agent", "LLM", "AI"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+requires-python = ">=3.11"
+dependencies = [
+    "aioitertools",
+    "anthropic",
+    "dashscope",
+    "docstring_parser",
+    "filetype",
+    "json5",
+    "json_repair",
+    "mcp",
+    "httpx",
+    "numpy",
+    "openai",
+    "python-datauri",
+    "opentelemetry-api>=1.39.0",
+    "opentelemetry-sdk>=1.39.0",
+    "opentelemetry-exporter-otlp>=1.39.0",
+    "opentelemetry-semantic-conventions>=0.60b0",
+    "python-socketio",
+    "shortuuid",
+    "python-frontmatter",
+    "jinja2",
+    "aiofiles",
+    "tree_sitter",
+    "tree_sitter_bash",
+    "jsonschema",
+]
+
+[project.optional-dependencies]
+# ------------ Model APIs ------------
+gemini = ["google-genai"]
+ollama = ["ollama>=0.5.4"]
+xai = ["xai-sdk"]
+models = [
+    "agentscope[ollama]",
+    "agentscope[gemini]",
+    "agentscope[xai]",
+]
+# ------------ Service ------------
+service = [
+    "fastapi",
+    "uvicorn",
+    "apscheduler",
+    "ag-ui-protocol>=0.1.10",
+]
+# ------------ Storage ------------
+storage = [
+    "redis",
+]
+# ------------ Workspace -----------
+k8s = ["kubernetes-asyncio"]
+workspace = [
+    "aiodocker",
+    "e2b",
+    "agentscope[k8s]",
+    "opensandbox",
+]
+# ------------ Tools ------------
+tools = [
+    "ripgrep",
+]
+# ------------ RAG ------------
+rag = [
+    "qdrant-client",
+    "pypdf",
+    "python-pptx",
+    "python-docx",
+    "openpyxl>=3.1.5",
+    "xlrd>=2.0",
+    "pandas",
+]
+milvuslite = [
+    "pymilvus[milvus-lite]>=2.4.0",
+    "milvus-lite>=3.0; sys_platform == 'win32'",
+]
+# ------------ MongoDB vector store ------------
+mongodb = [
+    "pymongo>=4.7",
+]
+
+# ------------ S3-compatible blob store ------------
+s3 = [
+    "aioboto3",
+]
+
+# ------------ Long-term memory ------------
+# Required by `agentscope.middleware._longterm_memory.Mem0Middleware`.
+# Pinned to mem0 v2.x because the middleware targets that
+# architecture: ADDITIVE_EXTRACTION_PROMPT + AGENT_CONTEXT_SUFFIX
+# (replaced v1's USER/AGENT_MEMORY_EXTRACTION_PROMPT split) and the
+# v3 phased pipeline in `_add_to_vector_store`. Running on mem0 1.x
+# wouldn't crash but the 2-tier add fallback degenerates into a
+# wasted LLM call.
+mem0 = ["mem0ai>=2.0.0"]
+# Required by `agentscope.middleware._longterm_memory.ReMeMiddleware`.
+reme = ["reme-ai>=0.4.0.6"]
+# ------------ Full ------------
+full = [
+    "agentscope[models]",
+    "agentscope[service]",
+    "agentscope[storage]",
+    "agentscope[workspace]",
+    "agentscope[tools]",
+    "agentscope[rag]",
+    "agentscope[milvuslite]",
+    "agentscope[mongodb]",
+    "agentscope[s3]",
+    "agentscope[mem0]",
+    "agentscope[reme]",
+]
+
+# ------------ Development ------------
+dev = [
+    # Include full dependencies from local package
+    "agentscope[full]",
+    # Development tools
+    "pre-commit",
+    "pytest",
+    "pytest-forked",
+    "myst_parser",
+    "matplotlib",
+    "fakeredis",
+    # S3-backend testing — moto[server] spins up an in-process S3, the
+    # store-under-test (`S3BlobStore`) uses aioboto3, and boto3 is the
+    # sync client the test fixtures use to seed/verify buckets.
+    "moto[server,s3]",
+    "aioboto3",
+    "boto3",
+    # RAG parser tests — used to generate PDF fixtures in-memory
+    "reportlab",
+]
+
+[project.urls]
+Homepage = "https://github.com/agentscope-ai/agentscope"
+Documentation = "https://doc.agentscope.io/"
+Repository = "https://github.com/agentscope-ai/agentscope"
+
+[tool.setuptools]
+packages = { find = { where = ["src"] } }
+include-package-data = true
+
+[tool.setuptools.package-data]
+# ``"*"`` applies to every discovered package. Patterns:
+# - ``py.typed`` marks the typed package per PEP 561.
+# - ``_models/*.yaml`` reaches into the data-only ``_models/``
+#  subdirs that ship with each model provider (they have no
+#   ``__init__.py`` and are not packages, but the files still
+#   live alongside the parent package's source on disk).
+"*" = [
+    "py.typed",
+    "_models/*.yaml",
+    "_cosyvoice_models/*.yaml",
+]
+"agentscope.workspace._docker" = ["Dockerfile*.template"]
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.dynamic]
+version = {attr = "agentscope._version.__version__"}
diff --git a/scripts/model_examples/README.md b/scripts/model_examples/README.md
new file mode 100644
index 0000000..704d1d8
--- /dev/null
+++ b/scripts/model_examples/README.md
@@ -0,0 +1,231 @@
+# Model Call Examples
+
+This directory contains example scripts for the major LLM providers supported by AgentScope, together with a unified test runner `run_tests.py`.
+These scripts are designed to verify that AgentScope's chat model components function correctly across various input scenarios.
+
+---
+
+## Directory Layout
+
+```
+scripts/model_examples/
+├── run_tests.py                          # Unified test runner
+├── _utils.py                             # Shared helpers (stream_and_collect)
+├── test.jpeg                             # Sample image for multimodal tests
+│
+├── openai_chat_call.py             # OpenAI Chat Completions – basic + tool call + structured output
+├── openai_chat_multiagent.py       # OpenAI Chat Completions – multi-agent conversation
+├── openai_chat_multimodal.py       # OpenAI Chat Completions – image/text multimodal
+├── openai_chat_multiagent_multimodal.py
+│
+├── openai_response_call.py         # OpenAI Responses API – reasoning models (o1/o3)
+├── openai_response_multiagent.py
+├── openai_response_multimodal.py
+├── openai_response_multiagent_multimodal.py
+│
+├── anthropic_call.py               # Anthropic Claude
+├── anthropic_multiagent.py
+├── anthropic_multimodal.py
+├── anthropic_multiagent_multimodal.py
+│
+├── dashscope_call.py               # Alibaba DashScope / Qwen
+├── dashscope_multiagent.py
+├── dashscope_multimodal.py
+├── dashscope_multiagent_multimodal.py
+│
+├── deepseek_call.py                # DeepSeek (no multimodal support)
+├── deepseek_multiagent.py
+│
+├── gemini_call.py                  # Google Gemini
+├── gemini_multiagent.py
+├── gemini_multimodal.py
+├── gemini_multiagent_multimodal.py
+│
+├── moonshot_call.py                 # Moonshot AI (Kimi)
+├── moonshot_multiagent.py
+├── moonshot_multimodal.py
+├── moonshot_multiagent_multimodal.py
+│
+├── xai_call.py                     # xAI Grok
+├── xai_multiagent.py
+├── xai_multimodal.py
+├── xai_multiagent_multimodal.py
+│
+├── ollama_call.py                  # Ollama local models (requires a running server)
+├── ollama_multiagent.py
+├── ollama_multimodal.py
+└── ollama_multiagent_multimodal.py
+```
+
+---
+
+## Test Types
+
+| Suffix | File Pattern | What it covers |
+|---|---|---|
+| `call` | `*_call.py` | Basic text call + two-round tool calling + structured output |
+| `multiagent` | `*_multiagent.py` | Multi-agent scenario using `MultiAgentFormatter` |
+| `multimodal` | `*_multimodal.py` | Image + text multimodal input (some providers also test audio/video) |
+| `multiagent_multimodal` | `*_multiagent_multimodal.py` | Multi-agent + multimodal combined |
+
+---
+
+## Providers and Their Environment Variables
+
+| Provider | Env Variable | Notes |
+|---|---|---|
+| `openai_chat` | `OPENAI_API_KEY` | Chat Completions API – gpt-4.1, etc. |
+| `openai_response` | `OPENAI_API_KEY` | Responses API – o1, o3, o4-mini, etc. |
+| `anthropic` | `ANTHROPIC_API_KEY` | Claude models, supports extended thinking |
+| `dashscope` | `DASHSCOPE_API_KEY` | Qwen series, supports `thinking_enable` |
+| `deepseek` | `DEEPSEEK_API_KEY` | Supports only `call` / `multiagent` (no multimodal) |
+| `gemini` | `GEMINI_API_KEY` | Gemini models, supports `thinking_budget` |
+| `moonshot` | `MOONSHOT_API_KEY` | Moonshot AI kimi-k2.6, etc. |
+| `xai` | `XAI_API_KEY` | Grok models, supports `reasoning_effort` |
+| `ollama` | *(none – auto-detect)* | Local server, default `http://localhost:11434` |
+
+---
+
+## Quick Start
+
+### 1. Export API Keys
+
+Set the environment variables for the providers you want to test:
+
+```bash
+export OPENAI_API_KEY="sk-..."
+export ANTHROPIC_API_KEY="sk-ant-..."
+export DASHSCOPE_API_KEY="sk-..."
+export DEEPSEEK_API_KEY="sk-..."
+export GEMINI_API_KEY="AIza..."
+export MOONSHOT_API_KEY="sk-..."
+export XAI_API_KEY="xai-..."
+```
+
+For Ollama, no API key is required. Just make sure the server is running:
+
+```bash
+ollama serve
+ollama pull qwen3:14b   # pull the default model used in the scripts
+```
+
+### 2. Check Provider Availability
+
+```bash
+python scripts/model_examples/run_tests.py --list
+```
+
+Sample output:
+```
+  Provider               Env Var                   Available    Description
+  openai_chat            OPENAI_API_KEY            YES          OpenAI Chat Completions API
+  anthropic              ANTHROPIC_API_KEY          NO           Anthropic Claude models
+  ...
+```
+
+### 3. Run All Available Tests
+
+```bash
+python scripts/model_examples/run_tests.py
+```
+
+The runner auto-detects which providers have credentials, skips those that do not, and runs all test types for the rest.
+
+---
+
+## `run_tests.py` Reference
+
+```
+usage: run_tests.py [-h] [--providers NAME[,NAME...]] [--tests TYPE[,TYPE...]]
+                    [--timeout SECONDS] [--list] [--verbose]
+```
+
+### Options
+
+| Option | Short | Default | Description |
+|---|---|---|---|
+| `--providers` | `-p` | all | Comma-separated list of providers to run |
+| `--tests` | `-t` | all | Comma-separated list of test types to run |
+| `--timeout` | | `120` | Per-script timeout in seconds |
+| `--list` | `-l` | | Print provider status table and exit |
+| `--verbose` | `-v` | | Stream each script's output in real time. By default output is suppressed and shown only when a test fails. |
+
+### Examples
+
+```bash
+# Only test specific providers
+python scripts/model_examples/run_tests.py --providers openai_chat,anthropic
+
+# Only run a specific test type (across all available providers)
+python scripts/model_examples/run_tests.py --tests call
+
+# Combine: run call + multiagent tests for dashscope and deepseek
+python scripts/model_examples/run_tests.py -p dashscope,deepseek -t call,multiagent
+
+# Only run multimodal tests
+python scripts/model_examples/run_tests.py --tests multimodal,multiagent_multimodal
+
+# Increase per-script timeout
+python scripts/model_examples/run_tests.py --timeout 180
+
+# Check provider status
+python scripts/model_examples/run_tests.py --list
+```
+
+### Summary Table
+
+At the end of a run, a summary table is printed:
+
+```
+  Provider               Test Type                    Status      Time
+  ---------------------- ---------------------------- -------- -------
+  openai_chat            call                         PASS       12.3s
+  openai_chat            multiagent                   PASS        8.1s
+  anthropic              call                         SKIP      (env var ANTHROPIC_API_KEY not set)
+  deepseek               call                         PASS       15.7s
+  deepseek               multimodal                   SKIP      (not supported)
+
+  Total: 12  |  PASS:   8  |  FAIL:   0  |  SKIP:   4
+```
+
+| Status | Meaning |
+|---|---|
+| **PASS** | Script exited with code 0 |
+| **FAIL** | Script exited with a non-zero code or timed out |
+| **SKIP** | API key missing, test type not supported, or script file absent |
+
+The runner exits with code `1` if any test fails.
+
+---
+
+## Running a Single Script
+
+Every script can be executed independently once the relevant environment variable is set:
+
+```bash
+python scripts/model_examples/openai_chat_call.py
+python scripts/model_examples/dashscope_multiagent.py
+python scripts/model_examples/ollama_multimodal.py
+```
+
+Each script typically defines two or more async functions:
+
+- `example_simple_call()` – basic text call with streaming
+- `example_tool_call()` – two-round conversation with tool/function calling
+- `example_structured_output()` – force a Pydantic-validated JSON output (in `_call.py` variants, uses a thinking-enabled model)
+- `example_image_url()` / `example_image_local_path()` / `example_image_base64()` – image + text input (in `_multimodal.py` variants)
+- `example_audio()` – audio input (e.g. `openai_chat_multimodal.py`, `dashscope_multimodal.py`)
+- `example_video()` – video input (e.g. `dashscope_multimodal.py`)
+
+---
+
+## Ollama Notes
+
+Ollama runs locally and requires no API key, but you must:
+
+1. Start the service: `ollama serve`
+2. Pull the model used by the scripts: `ollama pull qwen3:14b`
+3. If the service runs on a non-default address, set: `export OLLAMA_HOST=http://your-host:11434`
+
+`run_tests.py` pings the Ollama host before running any test. If the server is unreachable, all Ollama tests are automatically skipped.
+
diff --git a/scripts/model_examples/_utils.py b/scripts/model_examples/_utils.py
new file mode 100644
index 0000000..ad79692
--- /dev/null
+++ b/scripts/model_examples/_utils.py
@@ -0,0 +1,104 @@
+# -*- coding: utf-8 -*-
+"""Shared utility helpers for model-examples scripts."""
+import base64 as _b64
+from typing import AsyncGenerator
+
+from agentscope.message import (
+    TextBlock,
+    ThinkingBlock,
+    DataBlock,
+    Base64Source,
+)
+from agentscope.model import ChatResponse
+
+
+async def stream_and_collect(
+    gen: AsyncGenerator[ChatResponse, None],
+) -> ChatResponse:
+    """Stream delta chunks printing text in real-time; return the final chunk.
+
+    Only delta chunks (is_last=False) are printed.  The final accumulated
+    chunk (is_last=True) is returned so callers can read ToolCallBlock objects
+    from it without re-printing the entire content.  Text from the final chunk
+    is printed only when no text was streamed in any delta chunk (e.g. some
+    models batch the answer in the last chunk).
+
+    Streaming ``DataBlock`` chunks (e.g. omni audio output) are reported as
+    per-chunk size summaries while the stream is being consumed, so callers
+    can see the audio arriving incrementally rather than only in the final
+    cumulative chunk.
+    """
+    final: ChatResponse | None = None
+    in_thinking = False
+    text_was_streamed = False
+    # Track per-block audio progress: block_id -> (media_type, chunk_count,
+    # total_bytes).
+    audio_progress: dict[str, list] = {}
+    async for chunk in gen:
+        if chunk.is_last:
+            final = chunk
+            continue  # Skip printing; full content is in the final chunk
+        for block in chunk.content:
+            if isinstance(block, ThinkingBlock):
+                if not in_thinking:
+                    print("[Thinking] ", end="", flush=True)
+                    in_thinking = True
+                print(block.thinking, end="", flush=True)
+            elif isinstance(block, TextBlock):
+                if in_thinking:
+                    print()  # Newline after thinking content
+                    print("--- Answer ---")
+                    in_thinking = False
+                print(block.text, end="", flush=True)
+                text_was_streamed = True
+            elif isinstance(block, DataBlock) and isinstance(
+                block.source,
+                Base64Source,
+            ):
+                # Streaming binary delta (e.g. omni audio output).
+                if in_thinking:
+                    print()
+                    print("--- Answer ---")
+                    in_thinking = False
+                delta_bytes = len(_b64.b64decode(block.source.data))
+                state = audio_progress.setdefault(
+                    block.id,
+                    [block.source.media_type, 0, 0],
+                )
+                state[1] += 1
+                state[2] += delta_bytes
+                print(
+                    f"\n[Audio chunk #{state[1]} ({state[0]}): "
+                    f"+{delta_bytes}B, total={state[2]}B]",
+                    flush=True,
+                )
+    # If text was not streamed in any delta, print it from the final chunk now.
+    if not text_was_streamed and final is not None:
+        final_text = "".join(
+            b.text
+            for b in final.content
+            if isinstance(b, TextBlock) and b.text
+        )
+        if final_text:
+            if in_thinking:
+                print()
+                print("--- Answer ---")
+                in_thinking = False
+            print(final_text)
+    if in_thinking:
+        print()
+    # Report cumulative audio output from the final chunk.
+    if final is not None:
+        for block in final.content:
+            if isinstance(block, DataBlock) and isinstance(
+                block.source,
+                Base64Source,
+            ):
+                media = block.source.media_type
+                byte_size = len(_b64.b64decode(block.source.data))
+                print(
+                    f"[Audio output (cumulative): {media}, {byte_size} bytes]",
+                )
+    print()
+    assert final is not None
+    return final
diff --git a/scripts/model_examples/anthropic_call.py b/scripts/model_examples/anthropic_call.py
new file mode 100644
index 0000000..df8ab77
--- /dev/null
+++ b/scripts/model_examples/anthropic_call.py
@@ -0,0 +1,191 @@
+# -*- coding: utf-8 -*-
+"""Examples of Anthropic Claude model calls."""
+import asyncio
+import json
+import os
+
+from pydantic import BaseModel, Field
+
+from _utils import stream_and_collect
+from agentscope.message import (
+    Msg,
+    TextBlock,
+    ToolCallBlock,
+    ToolResultBlock,
+    ToolResultState,
+)
+from agentscope.model import AnthropicChatModel
+from agentscope.credential import AnthropicCredential
+from agentscope.tool import Toolkit, ToolChoice, FunctionTool
+
+
+# ---------------------------------------------------------------------------
+# Example 1: Simple user message (streaming)
+# ---------------------------------------------------------------------------
+
+
+async def example_simple_call() -> None:
+    """Call the Anthropic model with a simple text message."""
+    model = AnthropicChatModel(
+        credential=AnthropicCredential(
+            api_key=os.environ["ANTHROPIC_API_KEY"],
+        ),
+        model="claude-opus-4-5",
+        stream=True,
+        context_size=1_000_000,
+        parameters=AnthropicChatModel.Parameters(
+            thinking_enable=True,
+            thinking_budget=1024,
+        ),
+    )
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[TextBlock(text="What is 1 + 1? Answer briefly.")],
+            role="user",
+        ),
+    ]
+
+    print("=== Simple Call ===")
+    await stream_and_collect(await model(msgs))
+
+
+# ---------------------------------------------------------------------------
+# Example 2: Tool calling (streaming)
+# ---------------------------------------------------------------------------
+
+
+def get_weather(city: str) -> str:
+    """Get the current weather for a city.
+
+    Args:
+        city: The city name to query the weather for.
+
+    Returns:
+        A description of the current weather.
+    """
+    return f"The weather in {city} is sunny and 25°C."
+
+
+async def example_tool_call() -> None:
+    """Call the Anthropic model with tool calling enabled."""
+    toolkit = Toolkit(tools=[FunctionTool(get_weather)])
+    tools = await toolkit.get_tool_schemas()
+
+    model = AnthropicChatModel(
+        credential=AnthropicCredential(
+            api_key=os.environ["ANTHROPIC_API_KEY"],
+        ),
+        model="claude-opus-4-5",
+        stream=True,
+        context_size=1_000_000,
+        parameters=AnthropicChatModel.Parameters(
+            thinking_enable=True,
+            thinking_budget=1024,
+        ),
+    )
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[TextBlock(text="What is the weather in Shanghai?")],
+            role="user",
+        ),
+    ]
+
+    # First call: model decides to call a tool
+    print("=== Tool Call - Round 1 ===")
+    response = await stream_and_collect(
+        await model(msgs, tools=tools, tool_choice=ToolChoice(mode="auto")),
+    )
+    print(response)
+
+    tool_calls = [b for b in response.content if isinstance(b, ToolCallBlock)]
+    if tool_calls:
+        tool_result_blocks = []
+        for tool_call in tool_calls:
+            args = json.loads(tool_call.input)
+            result = get_weather(**args)
+            tool_result_blocks.append(
+                ToolResultBlock(
+                    id=tool_call.id,
+                    name=tool_call.name,
+                    output=result,
+                    state=ToolResultState.SUCCESS,
+                ),
+            )
+
+        assistant_msg = Msg(
+            name="assistant",
+            content=response.content,
+            role="assistant",
+        )
+        tool_result_msg = Msg(
+            name="tool",
+            content=tool_result_blocks,
+            role="assistant",
+        )
+        msgs = msgs + [assistant_msg, tool_result_msg]
+
+        print("=== Tool Call - Round 2 (Final) ===")
+        await stream_and_collect(await model(msgs))
+
+
+# ---------------------------------------------------------------------------
+# Example 3: Structured output
+# ---------------------------------------------------------------------------
+
+
+class MathSolution(BaseModel):
+    """Structured solution to a math problem."""
+
+    problem: str = Field(description="The original problem statement")
+    answer: float = Field(description="The final numeric answer")
+    steps: list[str] = Field(
+        description="Step-by-step reasoning leading to the answer",
+    )
+
+
+async def example_structured_output() -> None:
+    """Call the Anthropic model and force a structured (JSON) output."""
+    model = AnthropicChatModel(
+        credential=AnthropicCredential(
+            api_key=os.environ["ANTHROPIC_API_KEY"],
+        ),
+        model="claude-opus-4-5",
+        stream=True,
+        context_size=1_000_000,
+        parameters=AnthropicChatModel.Parameters(
+            thinking_enable=True,
+            thinking_budget=1024,
+        ),
+    )
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[
+                TextBlock(
+                    text=(
+                        "Solve this: A train travels at 60 km/h for "
+                        "2.5 hours. How far does it travel in km?"
+                    ),
+                ),
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Structured Output ===")
+    response = await model.generate_structured_output(
+        msgs,
+        structured_model=MathSolution,
+    )
+    print(response.content)
+
+
+if __name__ == "__main__":
+    asyncio.run(example_simple_call())
+    asyncio.run(example_tool_call())
+    asyncio.run(example_structured_output())
diff --git a/scripts/model_examples/anthropic_multiagent.py b/scripts/model_examples/anthropic_multiagent.py
new file mode 100644
index 0000000..7d529e0
--- /dev/null
+++ b/scripts/model_examples/anthropic_multiagent.py
@@ -0,0 +1,105 @@
+# -*- coding: utf-8 -*-
+"""Example of Anthropic Claude model calls with AnthropicMultiAgentFormatter.
+
+The multi-agent formatter wraps prior conversation history in
+<history></history> tags, enabling the model to handle multi-agent
+conversations where more than one non-user agent is involved.
+"""
+import asyncio
+import os
+
+from _utils import stream_and_collect
+from agentscope.formatter import AnthropicMultiAgentFormatter
+from agentscope.message import Msg, TextBlock
+from agentscope.model import AnthropicChatModel
+from agentscope.credential import AnthropicCredential
+
+
+async def example_multiagent() -> None:
+    """Simulate a multi-agent conversation and let claude-opus-4-5
+    summarize it.
+
+    Alice and Bob discuss the weather, then a moderator (the model) is asked
+    to summarize the conversation.
+    """
+    formatter = AnthropicMultiAgentFormatter()
+
+    model = AnthropicChatModel(
+        credential=AnthropicCredential(
+            api_key=os.environ["ANTHROPIC_API_KEY"],
+        ),
+        model="claude-opus-4-5",
+        stream=True,
+        context_size=1_000_000,
+        parameters=AnthropicChatModel.Parameters(
+            thinking_enable=True,
+            thinking_budget=1024,
+        ),
+        formatter=formatter,
+    )
+
+    # Multi-agent conversation history between Alice and Bob
+    msgs = [
+        Msg(
+            name="system",
+            content=[
+                TextBlock(
+                    text="You are a helpful moderator. Summarize the "
+                    "conversation.",
+                ),
+            ],
+            role="system",
+        ),
+        Msg(
+            name="alice",
+            content=[
+                TextBlock(
+                    text="Hi Bob! What do you think about the weather today?",
+                ),
+            ],
+            role="user",
+        ),
+        Msg(
+            name="bob",
+            content=[
+                TextBlock(
+                    text="It's quite sunny and warm, Alice. Perfect for a "
+                    "walk!",
+                ),
+            ],
+            role="assistant",
+        ),
+        Msg(
+            name="alice",
+            content=[
+                TextBlock(text="Agreed! I might head to the park later."),
+            ],
+            role="user",
+        ),
+        Msg(
+            name="bob",
+            content=[
+                TextBlock(
+                    text="Great idea. I'll join you if I finish work early.",
+                ),
+            ],
+            role="assistant",
+        ),
+        Msg(
+            name="moderator",
+            content=[
+                TextBlock(
+                    text="Please summarize the conversation above in one "
+                    "sentence.",
+                ),
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Multi-Agent Formatter Call ===")
+    await stream_and_collect(await model(msgs))
+
+
+if __name__ == "__main__":
+    asyncio.run(example_multiagent())
diff --git a/scripts/model_examples/anthropic_multiagent_multimodal.py b/scripts/model_examples/anthropic_multiagent_multimodal.py
new file mode 100644
index 0000000..873ef06
--- /dev/null
+++ b/scripts/model_examples/anthropic_multiagent_multimodal.py
@@ -0,0 +1,99 @@
+# -*- coding: utf-8 -*-
+"""Example of Anthropic Claude model calls with MultiAgentFormatter and
+image input.
+
+Demonstrates combining AnthropicMultiAgentFormatter with multimodal (vision)
+content: Alice shares an image in a multi-agent conversation, and the model
+is asked to summarize what everyone is looking at.
+"""
+import asyncio
+import os
+
+from _utils import stream_and_collect
+from agentscope.formatter import AnthropicMultiAgentFormatter
+from agentscope.message import Msg, TextBlock, DataBlock, URLSource
+from agentscope.model import AnthropicChatModel
+from agentscope.credential import AnthropicCredential
+
+TEST_IMAGE_URL = (
+    "https://help-static-aliyun-doc.aliyuncs.com/file-manage"
+    "-files/zh-CN/20241022/emyrja/dog_and_girl.jpeg"
+)
+
+
+async def example_multiagent_image_url() -> None:
+    """Multi-agent conversation where Alice shares an image for the group."""
+    formatter = AnthropicMultiAgentFormatter()
+
+    model = AnthropicChatModel(
+        credential=AnthropicCredential(
+            api_key=os.environ["ANTHROPIC_API_KEY"],
+        ),
+        model="claude-opus-4-5",
+        stream=True,
+        context_size=1_000_000,
+        parameters=AnthropicChatModel.Parameters(
+            thinking_enable=True,
+            thinking_budget=1024,
+        ),
+        formatter=formatter,
+    )
+
+    image_block = DataBlock(
+        source=URLSource(url=TEST_IMAGE_URL, media_type="image/jpeg"),
+    )
+
+    msgs = [
+        Msg(
+            name="system",
+            content=[
+                TextBlock(
+                    text=(
+                        "You are a helpful moderator in a group chat. "
+                        "Summarize what the image shows and what the "
+                        "participants said."
+                    ),
+                ),
+            ],
+            role="system",
+        ),
+        Msg(
+            name="alice",
+            content=[
+                TextBlock(
+                    text="Hey everyone, look at this cute photo I took!",
+                ),
+                image_block,
+            ],
+            role="user",
+        ),
+        Msg(
+            name="bob",
+            content=[
+                TextBlock(text="Aww, that's adorable! Where was this taken?"),
+            ],
+            role="assistant",
+        ),
+        Msg(
+            name="alice",
+            content=[TextBlock(text="At the local park yesterday.")],
+            role="user",
+        ),
+        Msg(
+            name="moderator",
+            content=[
+                TextBlock(
+                    text="Please summarize the image content and the "
+                    "conversation in one paragraph.",
+                ),
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Multi-Agent + Multimodal Call ===")
+    await stream_and_collect(await model(msgs))
+
+
+if __name__ == "__main__":
+    asyncio.run(example_multiagent_image_url())
diff --git a/scripts/model_examples/anthropic_multimodal.py b/scripts/model_examples/anthropic_multimodal.py
new file mode 100644
index 0000000..78830c5
--- /dev/null
+++ b/scripts/model_examples/anthropic_multimodal.py
@@ -0,0 +1,154 @@
+# -*- coding: utf-8 -*-
+"""Example of Anthropic Claude model multimodal (vision) calls using
+DataBlock."""
+import asyncio
+import base64
+import os
+from pathlib import Path
+
+from _utils import stream_and_collect
+from agentscope.message import (
+    Msg,
+    TextBlock,
+    DataBlock,
+    URLSource,
+    Base64Source,
+)
+from agentscope.model import AnthropicChatModel
+from agentscope.credential import AnthropicCredential
+
+# A publicly accessible test image (a simple cat photo)
+TEST_IMAGE_URL = (
+    "https://help-static-aliyun-doc.aliyuncs.com/file-manage"
+    "-files/zh-CN/20241022/emyrja/dog_and_girl.jpeg"
+)
+
+
+async def example_image_url() -> None:
+    """Call claude-opus-4-5 with an image URL and ask what is in the image."""
+    model = AnthropicChatModel(
+        credential=AnthropicCredential(
+            api_key=os.environ["ANTHROPIC_API_KEY"],
+        ),
+        model="claude-opus-4-5",
+        stream=True,
+        context_size=1_000_000,
+        parameters=AnthropicChatModel.Parameters(
+            thinking_enable=True,
+            thinking_budget=1024,
+        ),
+    )
+
+    image_block = DataBlock(
+        source=URLSource(
+            url=TEST_IMAGE_URL,
+            media_type="image/jpeg",
+        ),
+    )
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[
+                TextBlock(
+                    text="What animal is in this image? Describe it briefly.",
+                ),
+                image_block,
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Multimodal Call (Image URL) ===")
+    await stream_and_collect(await model(msgs))
+
+
+def _build_model() -> AnthropicChatModel:
+    """Build and return an AnthropicChatModel instance."""
+    return AnthropicChatModel(
+        credential=AnthropicCredential(
+            api_key=os.environ["ANTHROPIC_API_KEY"],
+        ),
+        model="claude-opus-4-5",
+        stream=True,
+        context_size=1_000_000,
+        parameters=AnthropicChatModel.Parameters(
+            thinking_enable=True,
+            thinking_budget=1024,
+        ),
+    )
+
+
+async def example_image_local_path() -> None:
+    """Call claude-opus-4-5 with a local image using a ``file://`` URL.
+
+    The formatter automatically reads the file and converts it to base64.
+    """
+    model = _build_model()
+
+    abs_path = str(Path(__file__).parent / "test.jpeg")
+    image_block = DataBlock(
+        source=URLSource(
+            url=f"file://{abs_path}",
+            media_type="image/jpeg",
+        ),
+    )
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[
+                TextBlock(
+                    text="What is happening in this image? Describe it "
+                    "briefly.",
+                ),
+                image_block,
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Local Path Call (file://) ===")
+    await stream_and_collect(await model(msgs))
+
+
+async def example_image_base64() -> None:
+    """Call claude-opus-4-5 with a local image using explicit base64 encoding.
+
+    Use ``Base64Source`` when you already have the binary data in memory or
+    want full control over the encoding step.
+    """
+    model = _build_model()
+
+    with open(Path(__file__).parent / "test.jpeg", "rb") as f:
+        data = base64.b64encode(f.read()).decode("utf-8")
+
+    image_block = DataBlock(
+        source=Base64Source(
+            data=data,
+            media_type="image/jpeg",
+        ),
+    )
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[
+                TextBlock(
+                    text="What is happening in this image? Describe it "
+                    "briefly.",
+                ),
+                image_block,
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Explicit Base64 Call ===")
+    await stream_and_collect(await model(msgs))
+
+
+if __name__ == "__main__":
+    asyncio.run(example_image_url())
+    asyncio.run(example_image_local_path())
+    asyncio.run(example_image_base64())
diff --git a/scripts/model_examples/dashscope_call.py b/scripts/model_examples/dashscope_call.py
new file mode 100644
index 0000000..5e86939
--- /dev/null
+++ b/scripts/model_examples/dashscope_call.py
@@ -0,0 +1,185 @@
+# -*- coding: utf-8 -*-
+"""Examples of DashScope (Alibaba) model calls."""
+import asyncio
+import json
+import os
+
+from pydantic import BaseModel, Field
+
+from _utils import stream_and_collect
+from agentscope.message import (
+    Msg,
+    ToolCallBlock,
+    ToolResultBlock,
+    ToolResultState,
+    TextBlock,
+)
+from agentscope.model import DashScopeChatModel
+from agentscope.credential import DashScopeCredential
+from agentscope.tool import Toolkit, ToolChoice, FunctionTool
+
+
+# ---------------------------------------------------------------------------
+# Example 1: Simple user message (streaming)
+# ---------------------------------------------------------------------------
+
+
+async def example_simple_call() -> None:
+    """Call the DashScope model with a simple text message."""
+    model = DashScopeChatModel(
+        credential=DashScopeCredential(
+            api_key=os.environ["DASHSCOPE_API_KEY"],
+        ),
+        model="qwen3.5-plus",
+        stream=True,
+        context_size=1_000_000,
+        parameters=DashScopeChatModel.Parameters(thinking_enable=True),
+    )
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[TextBlock(text="What is 1 + 1? Answer briefly.")],
+            role="user",
+        ),
+    ]
+
+    print("=== Simple Call ===")
+    await stream_and_collect(await model(msgs))
+
+
+# ---------------------------------------------------------------------------
+# Example 2: Tool calling (streaming)
+# ---------------------------------------------------------------------------
+
+
+def get_weather(city: str) -> str:
+    """Get the current weather for a city.
+
+    Args:
+        city: The city name to query the weather for.
+
+    Returns:
+        A description of the current weather.
+    """
+    return f"The weather in {city} is sunny and 25°C."
+
+
+async def example_tool_call() -> None:
+    """Call the DashScope model with tool calling enabled.
+
+    Uses qwen3-max which supports both thinking mode and tool calling.
+    """
+    toolkit = Toolkit(tools=[FunctionTool(get_weather)])
+    tools = await toolkit.get_tool_schemas()
+
+    model = DashScopeChatModel(
+        credential=DashScopeCredential(
+            api_key=os.environ["DASHSCOPE_API_KEY"],
+        ),
+        model="qwen3.5-plus",
+        stream=True,
+        context_size=1_000_000,
+        parameters=DashScopeChatModel.Parameters(thinking_enable=True),
+    )
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[TextBlock(text="What is the weather in Beijing?")],
+            role="user",
+        ),
+    ]
+
+    # First call: model decides to call a tool
+    print("=== Tool Call - Round 1 ===")
+    response = await stream_and_collect(
+        await model(msgs, tools=tools, tool_choice=ToolChoice(mode="auto")),
+    )
+    print(response)
+
+    tool_calls = [b for b in response.content if isinstance(b, ToolCallBlock)]
+    if tool_calls:
+        tool_result_blocks = []
+        for tool_call in tool_calls:
+            args = json.loads(tool_call.input)
+            result = get_weather(**args)
+            tool_result_blocks.append(
+                ToolResultBlock(
+                    id=tool_call.id,
+                    name=tool_call.name,
+                    output=result,
+                    state=ToolResultState.SUCCESS,
+                ),
+            )
+
+        assistant_msg = Msg(
+            name="assistant",
+            content=response.content,
+            role="assistant",
+        )
+        tool_result_msg = Msg(
+            name="tool",
+            content=tool_result_blocks,
+            role="assistant",
+        )
+        msgs = msgs + [assistant_msg, tool_result_msg]
+
+        print("=== Tool Call - Round 2 (Final) ===")
+        await stream_and_collect(await model(msgs))
+
+
+# ---------------------------------------------------------------------------
+# Example 3: Structured output
+# ---------------------------------------------------------------------------
+
+
+class MathSolution(BaseModel):
+    """Structured solution to a math problem."""
+
+    problem: str = Field(description="The original problem statement")
+    answer: float = Field(description="The final numeric answer")
+    steps: list[str] = Field(
+        description="Step-by-step reasoning leading to the answer",
+    )
+
+
+async def example_structured_output() -> None:
+    """Call the DashScope model and force a structured (JSON) output."""
+    model = DashScopeChatModel(
+        credential=DashScopeCredential(
+            api_key=os.environ["DASHSCOPE_API_KEY"],
+        ),
+        model="qwen3.5-plus",
+        stream=True,
+        context_size=1_000_000,
+        parameters=DashScopeChatModel.Parameters(thinking_enable=True),
+    )
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[
+                TextBlock(
+                    text=(
+                        "Solve this: A train travels at 60 km/h for "
+                        "2.5 hours. How far does it travel in km?"
+                    ),
+                ),
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Structured Output ===")
+    response = await model.generate_structured_output(
+        msgs,
+        structured_model=MathSolution,
+    )
+    print(response.content)
+
+
+if __name__ == "__main__":
+    asyncio.run(example_simple_call())
+    asyncio.run(example_tool_call())
+    asyncio.run(example_structured_output())
diff --git a/scripts/model_examples/dashscope_multiagent.py b/scripts/model_examples/dashscope_multiagent.py
new file mode 100644
index 0000000..132fd9e
--- /dev/null
+++ b/scripts/model_examples/dashscope_multiagent.py
@@ -0,0 +1,101 @@
+# -*- coding: utf-8 -*-
+"""Example of DashScope model calls with DashScopeMultiAgentFormatter.
+
+The multi-agent formatter wraps prior conversation history in
+<history></history> tags, enabling the model to handle multi-agent
+conversations where more than one non-user agent is involved.
+"""
+import asyncio
+import os
+
+from _utils import stream_and_collect
+from agentscope.formatter import DashScopeMultiAgentFormatter
+from agentscope.message import Msg, TextBlock
+from agentscope.model import DashScopeChatModel
+from agentscope.credential import DashScopeCredential
+
+
+async def example_multiagent() -> None:
+    """Simulate a multi-agent conversation and let qwen3.5-plus summarize it.
+
+    Alice and Bob discuss the weather, then a moderator (the model) is asked
+    to summarize the conversation.
+    """
+    formatter = DashScopeMultiAgentFormatter()
+
+    model = DashScopeChatModel(
+        credential=DashScopeCredential(
+            api_key=os.environ["DASHSCOPE_API_KEY"],
+        ),
+        model="qwen3.5-plus",
+        stream=True,
+        context_size=1_000_000,
+        parameters=DashScopeChatModel.Parameters(thinking_enable=True),
+        formatter=formatter,
+    )
+
+    # Multi-agent conversation history between Alice and Bob
+    msgs = [
+        Msg(
+            name="system",
+            content=[
+                TextBlock(
+                    text="You are a helpful moderator. Summarize the "
+                    "conversation.",
+                ),
+            ],
+            role="system",
+        ),
+        Msg(
+            name="alice",
+            content=[
+                TextBlock(
+                    text="Hi Bob! What do you think about the weather today?",
+                ),
+            ],
+            role="user",
+        ),
+        Msg(
+            name="bob",
+            content=[
+                TextBlock(
+                    text="It's quite sunny and warm, Alice. Perfect for a "
+                    "walk!",
+                ),
+            ],
+            role="assistant",
+        ),
+        Msg(
+            name="alice",
+            content=[
+                TextBlock(text="Agreed! I might head to the park later."),
+            ],
+            role="user",
+        ),
+        Msg(
+            name="bob",
+            content=[
+                TextBlock(
+                    text="Great idea. I'll join you if I finish work early.",
+                ),
+            ],
+            role="assistant",
+        ),
+        Msg(
+            name="moderator",
+            content=[
+                TextBlock(
+                    text="Please summarize the conversation above in one "
+                    "sentence.",
+                ),
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Multi-Agent Formatter Call ===")
+    await stream_and_collect(await model(msgs))
+
+
+if __name__ == "__main__":
+    asyncio.run(example_multiagent())
diff --git a/scripts/model_examples/dashscope_multiagent_multimodal.py b/scripts/model_examples/dashscope_multiagent_multimodal.py
new file mode 100644
index 0000000..441a9db
--- /dev/null
+++ b/scripts/model_examples/dashscope_multiagent_multimodal.py
@@ -0,0 +1,95 @@
+# -*- coding: utf-8 -*-
+"""Example of DashScope model calls with MultiAgentFormatter and image input.
+
+Demonstrates combining DashScopeMultiAgentFormatter with multimodal (vision)
+content: Alice shares an image in a multi-agent conversation, and the model
+is asked to summarize what everyone is looking at.
+"""
+import asyncio
+import os
+
+from _utils import stream_and_collect
+from agentscope.formatter import DashScopeMultiAgentFormatter
+from agentscope.message import Msg, TextBlock, DataBlock, URLSource
+from agentscope.model import DashScopeChatModel
+from agentscope.credential import DashScopeCredential
+
+TEST_IMAGE_URL = (
+    "https://help-static-aliyun-doc.aliyuncs.com/file-manage"
+    "-files/zh-CN/20241022/emyrja/dog_and_girl.jpeg"
+)
+
+
+async def example_multiagent_image_url() -> None:
+    """Multi-agent conversation where Alice shares an image for the group."""
+    formatter = DashScopeMultiAgentFormatter()
+
+    model = DashScopeChatModel(
+        credential=DashScopeCredential(
+            api_key=os.environ["DASHSCOPE_API_KEY"],
+        ),
+        model="qwen3.5-plus",
+        stream=True,
+        context_size=1_000_000,
+        parameters=DashScopeChatModel.Parameters(thinking_enable=True),
+        formatter=formatter,
+    )
+
+    image_block = DataBlock(
+        source=URLSource(url=TEST_IMAGE_URL, media_type="image/jpeg"),
+    )
+
+    msgs = [
+        Msg(
+            name="system",
+            content=[
+                TextBlock(
+                    text=(
+                        "You are a helpful moderator in a group chat. "
+                        "Summarize what the image shows and what the "
+                        "participants said."
+                    ),
+                ),
+            ],
+            role="system",
+        ),
+        Msg(
+            name="alice",
+            content=[
+                TextBlock(
+                    text="Hey everyone, look at this cute photo I took!",
+                ),
+                image_block,
+            ],
+            role="user",
+        ),
+        Msg(
+            name="bob",
+            content=[
+                TextBlock(text="Aww, that's adorable! Where was this taken?"),
+            ],
+            role="assistant",
+        ),
+        Msg(
+            name="alice",
+            content=[TextBlock(text="At the local park yesterday.")],
+            role="user",
+        ),
+        Msg(
+            name="moderator",
+            content=[
+                TextBlock(
+                    text="Please summarize the image content and the "
+                    "conversation in one paragraph.",
+                ),
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Multi-Agent + Multimodal Call ===")
+    await stream_and_collect(await model(msgs))
+
+
+if __name__ == "__main__":
+    asyncio.run(example_multiagent_image_url())
diff --git a/scripts/model_examples/dashscope_multimodal.py b/scripts/model_examples/dashscope_multimodal.py
new file mode 100644
index 0000000..4cae6c3
--- /dev/null
+++ b/scripts/model_examples/dashscope_multimodal.py
@@ -0,0 +1,231 @@
+# -*- coding: utf-8 -*-
+"""Example of DashScope model multimodal (vision) calls using DataBlock."""
+import asyncio
+import base64
+import os
+from pathlib import Path
+
+from _utils import stream_and_collect
+from agentscope.message import (
+    Msg,
+    TextBlock,
+    DataBlock,
+    URLSource,
+    Base64Source,
+)
+from agentscope.model import DashScopeChatModel
+from agentscope.credential import DashScopeCredential
+
+# A publicly accessible test image
+TEST_IMAGE_URL = (
+    "https://help-static-aliyun-doc.aliyuncs.com/file-manage"
+    "-files/zh-CN/20241022/emyrja/dog_and_girl.jpeg"
+)
+
+# A publicly accessible test video
+TEST_VIDEO_URL = (
+    "https://help-static-aliyun-doc.aliyuncs.com/file-manage"
+    "-files/zh-CN/20241115/cqqkru/1.mp4"
+)
+
+# A publicly accessible test audio
+TEST_AUDIO_URL = (
+    "https://help-static-aliyun-doc.aliyuncs.com/file-manage"
+    "-files/zh-CN/20250211/tixcef/cherry.wav"
+)
+
+
+async def example_image_url() -> None:
+    """Call qwen3.5-plus with an image URL and ask what is in the image."""
+    model = DashScopeChatModel(
+        credential=DashScopeCredential(
+            api_key=os.environ["DASHSCOPE_API_KEY"],
+        ),
+        model="qwen3.5-plus",
+        stream=True,
+        context_size=1_000_000,
+        parameters=DashScopeChatModel.Parameters(thinking_enable=True),
+    )
+
+    image_block = DataBlock(
+        source=URLSource(
+            url=TEST_IMAGE_URL,
+            media_type="image/jpeg",
+        ),
+    )
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[
+                TextBlock(
+                    text="What animal is in this image? Describe it briefly.",
+                ),
+                image_block,
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Multimodal Call (Image URL) ===")
+    await stream_and_collect(await model(msgs))
+
+
+def _build_model() -> DashScopeChatModel:
+    """Build and return a DashScopeChatModel instance."""
+    return DashScopeChatModel(
+        credential=DashScopeCredential(
+            api_key=os.environ["DASHSCOPE_API_KEY"],
+        ),
+        model="qwen3.5-plus",
+        stream=True,
+        context_size=1_000_000,
+        parameters=DashScopeChatModel.Parameters(thinking_enable=True),
+    )
+
+
+async def example_image_local_path() -> None:
+    """Call qwen3.5-plus with a local image using a ``file://`` URL.
+
+    The formatter reads the file from disk and converts it to a base64 data
+     URI.
+    """
+    model = _build_model()
+
+    abs_path = str(Path(__file__).parent / "test.jpeg")
+    image_block = DataBlock(
+        source=URLSource(
+            url=f"file://{abs_path}",
+            media_type="image/jpeg",
+        ),
+    )
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[
+                TextBlock(
+                    text="What is happening in this image? Describe it "
+                    "briefly.",
+                ),
+                image_block,
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Local Path Call (file://) ===")
+    await stream_and_collect(await model(msgs))
+
+
+async def example_image_base64() -> None:
+    """Call qwen3.5-plus with a local image using explicit base64 encoding.
+
+    Use ``Base64Source`` when you already have the binary data in memory or
+    want full control over the encoding step.
+    """
+    model = _build_model()
+
+    with open(Path(__file__).parent / "test.jpeg", "rb") as f:
+        data = base64.b64encode(f.read()).decode("utf-8")
+
+    image_block = DataBlock(
+        source=Base64Source(
+            data=data,
+            media_type="image/jpeg",
+        ),
+    )
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[
+                TextBlock(
+                    text="What is happening in this image? Describe it "
+                    "briefly.",
+                ),
+                image_block,
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Explicit Base64 Call ===")
+    await stream_and_collect(await model(msgs))
+
+
+async def example_video() -> None:
+    """Call qwen3.5-plus with a video URL and ask what is in the video."""
+    model = _build_model()
+
+    video_block = DataBlock(
+        source=URLSource(
+            url=TEST_VIDEO_URL,
+            media_type="video/mp4",
+        ),
+    )
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[
+                TextBlock(
+                    text="What is happening in this video? "
+                    "Describe it briefly.",
+                ),
+                video_block,
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Multimodal Call (Video URL) ===")
+    await stream_and_collect(await model(msgs))
+
+
+async def example_audio() -> None:
+    """Call qwen3.5-omni-plus with an audio URL.
+
+    Audio understanding requires an Omni model (qwen3.5-omni-plus or
+    Qwen3-Omni-Flash). Omni models also require stream=True and the
+    ``modalities`` parameter.
+    """
+    model = DashScopeChatModel(
+        credential=DashScopeCredential(
+            api_key=os.environ["DASHSCOPE_API_KEY"],
+        ),
+        model="qwen3.5-omni-plus",
+        stream=True,
+        context_size=1_000_000,
+    )
+
+    audio_block = DataBlock(
+        source=URLSource(
+            url=TEST_AUDIO_URL,
+            media_type="audio/wav",
+        ),
+    )
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[
+                TextBlock(text="What is being said in this audio clip?"),
+                audio_block,
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Multimodal Call (Audio URL - Omni) ===")
+    await stream_and_collect(
+        await model(msgs, modalities=["text", "audio"]),
+    )
+
+
+if __name__ == "__main__":
+    asyncio.run(example_image_url())
+    asyncio.run(example_image_local_path())
+    asyncio.run(example_image_base64())
+    asyncio.run(example_video())
+    asyncio.run(example_audio())
diff --git a/scripts/model_examples/deepseek_call.py b/scripts/model_examples/deepseek_call.py
new file mode 100644
index 0000000..d494592
--- /dev/null
+++ b/scripts/model_examples/deepseek_call.py
@@ -0,0 +1,189 @@
+# -*- coding: utf-8 -*-
+"""Examples of DeepSeek model calls.
+
+For DeepSeek, thinking (chain-of-thought) is controlled by the
+``thinking_enable`` parameter on ``deepseek-v4-flash``. The legacy
+``deepseek-chat`` / ``deepseek-reasoner`` model names will be deprecated;
+they correspond to the non-thinking / thinking modes of
+``deepseek-v4-flash`` respectively.
+"""
+import asyncio
+import json
+import os
+
+from pydantic import BaseModel, Field
+
+from _utils import stream_and_collect
+from agentscope.message import (
+    Msg,
+    TextBlock,
+    ToolCallBlock,
+    ToolResultBlock,
+    ToolResultState,
+)
+from agentscope.model import DeepSeekChatModel
+from agentscope.credential import DeepSeekCredential
+from agentscope.tool import Toolkit, ToolChoice, FunctionTool
+
+
+# ---------------------------------------------------------------------------
+# Example 1: Simple user message (streaming, with chain-of-thought)
+# ---------------------------------------------------------------------------
+
+
+async def example_simple_call() -> None:
+    """Call DeepSeek with thinking enabled on a simple text message."""
+    model = DeepSeekChatModel(
+        credential=DeepSeekCredential(
+            api_key=os.environ["DEEPSEEK_API_KEY"],
+        ),
+        model="deepseek-v4-flash",
+        stream=True,
+        context_size=1_000_000,
+        parameters=DeepSeekChatModel.Parameters(thinking_enable=True),
+    )
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[TextBlock(text="What is 1 + 1? Answer briefly.")],
+            role="user",
+        ),
+    ]
+
+    print("=== Simple Call ===")
+    await stream_and_collect(await model(msgs))
+
+
+# ---------------------------------------------------------------------------
+# Example 2: Tool calling (streaming)
+# ---------------------------------------------------------------------------
+
+
+def get_weather(city: str) -> str:
+    """Get the current weather for a city.
+
+    Args:
+        city: The city name to query the weather for.
+
+    Returns:
+        A description of the current weather.
+    """
+    return f"The weather in {city} is sunny and 25°C."
+
+
+async def example_tool_call() -> None:
+    """Call DeepSeek with thinking + tool calling enabled."""
+    toolkit = Toolkit(tools=[FunctionTool(get_weather)])
+    tools = await toolkit.get_tool_schemas()
+
+    model = DeepSeekChatModel(
+        credential=DeepSeekCredential(
+            api_key=os.environ["DEEPSEEK_API_KEY"],
+        ),
+        model="deepseek-v4-flash",
+        stream=True,
+        context_size=1_000_000,
+        parameters=DeepSeekChatModel.Parameters(thinking_enable=True),
+    )
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[TextBlock(text="What is the weather in Shenzhen?")],
+            role="user",
+        ),
+    ]
+
+    # First call: model decides to call a tool
+    print("=== Tool Call - Round 1 ===")
+    response = await stream_and_collect(
+        await model(msgs, tools=tools, tool_choice=ToolChoice(mode="auto")),
+    )
+    print(response)
+
+    tool_calls = [b for b in response.content if isinstance(b, ToolCallBlock)]
+    if tool_calls:
+        tool_result_blocks = []
+        for tool_call in tool_calls:
+            args = json.loads(tool_call.input)
+            result = get_weather(**args)
+            tool_result_blocks.append(
+                ToolResultBlock(
+                    id=tool_call.id,
+                    name=tool_call.name,
+                    output=result,
+                    state=ToolResultState.SUCCESS,
+                ),
+            )
+
+        assistant_msg = Msg(
+            name="assistant",
+            content=response.content,
+            role="assistant",
+        )
+        tool_result_msg = Msg(
+            name="tool",
+            content=tool_result_blocks,
+            role="assistant",
+        )
+        msgs = msgs + [assistant_msg, tool_result_msg]
+
+        print("=== Tool Call - Round 2 (Final) ===")
+        await stream_and_collect(await model(msgs))
+
+
+# ---------------------------------------------------------------------------
+# Example 3: Structured output
+# ---------------------------------------------------------------------------
+
+
+class MathSolution(BaseModel):
+    """Structured solution to a math problem."""
+
+    problem: str = Field(description="The original problem statement")
+    answer: float = Field(description="The final numeric answer")
+    steps: list[str] = Field(
+        description="Step-by-step reasoning leading to the answer",
+    )
+
+
+async def example_structured_output() -> None:
+    """Call DeepSeek with thinking enabled and force a structured output."""
+    model = DeepSeekChatModel(
+        credential=DeepSeekCredential(
+            api_key=os.environ["DEEPSEEK_API_KEY"],
+        ),
+        model="deepseek-v4-flash",
+        stream=True,
+        context_size=1_000_000,
+        parameters=DeepSeekChatModel.Parameters(thinking_enable=True),
+    )
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[
+                TextBlock(
+                    text=(
+                        "Solve this: A train travels at 60 km/h for "
+                        "2.5 hours. How far does it travel in km?"
+                    ),
+                ),
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Structured Output ===")
+    response = await model.generate_structured_output(
+        msgs,
+        structured_model=MathSolution,
+    )
+    print(response.content)
+
+
+if __name__ == "__main__":
+    asyncio.run(example_simple_call())
+    asyncio.run(example_tool_call())
+    asyncio.run(example_structured_output())
diff --git a/scripts/model_examples/deepseek_multiagent.py b/scripts/model_examples/deepseek_multiagent.py
new file mode 100644
index 0000000..c3cc5ef
--- /dev/null
+++ b/scripts/model_examples/deepseek_multiagent.py
@@ -0,0 +1,102 @@
+# -*- coding: utf-8 -*-
+"""Example of DeepSeek model calls with DeepSeekMultiAgentFormatter.
+
+The multi-agent formatter wraps prior conversation history in
+<history></history> tags, enabling the model to handle multi-agent
+conversations where more than one non-user agent is involved.
+"""
+import asyncio
+import os
+
+from _utils import stream_and_collect
+from agentscope.formatter import DeepSeekMultiAgentFormatter
+from agentscope.message import Msg, TextBlock
+from agentscope.model import DeepSeekChatModel
+from agentscope.credential import DeepSeekCredential
+
+
+async def example_multiagent() -> None:
+    """Simulate a multi-agent conversation and let deepseek-v4-flash
+    summarize it.
+
+    Alice and Bob discuss the weather, then a moderator (the model) is asked
+    to summarize the conversation.
+    """
+    formatter = DeepSeekMultiAgentFormatter()
+
+    model = DeepSeekChatModel(
+        credential=DeepSeekCredential(
+            api_key=os.environ["DEEPSEEK_API_KEY"],
+        ),
+        model="deepseek-v4-flash",
+        stream=True,
+        context_size=1_000_000,
+        parameters=DeepSeekChatModel.Parameters(thinking_enable=True),
+        formatter=formatter,
+    )
+
+    # Multi-agent conversation history between Alice and Bob
+    msgs = [
+        Msg(
+            name="system",
+            content=[
+                TextBlock(
+                    text="You are a helpful moderator. Summarize the "
+                    "conversation.",
+                ),
+            ],
+            role="system",
+        ),
+        Msg(
+            name="alice",
+            content=[
+                TextBlock(
+                    text="Hi Bob! What do you think about the weather today?",
+                ),
+            ],
+            role="user",
+        ),
+        Msg(
+            name="bob",
+            content=[
+                TextBlock(
+                    text="It's quite sunny and warm, Alice. Perfect for a "
+                    "walk!",
+                ),
+            ],
+            role="assistant",
+        ),
+        Msg(
+            name="alice",
+            content=[
+                TextBlock(text="Agreed! I might head to the park later."),
+            ],
+            role="user",
+        ),
+        Msg(
+            name="bob",
+            content=[
+                TextBlock(
+                    text="Great idea. I'll join you if I finish work early.",
+                ),
+            ],
+            role="assistant",
+        ),
+        Msg(
+            name="moderator",
+            content=[
+                TextBlock(
+                    text="Please summarize the conversation above in one "
+                    "sentence.",
+                ),
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Multi-Agent Formatter Call ===")
+    await stream_and_collect(await model(msgs))
+
+
+if __name__ == "__main__":
+    asyncio.run(example_multiagent())
diff --git a/scripts/model_examples/gemini_call.py b/scripts/model_examples/gemini_call.py
new file mode 100644
index 0000000..c557e90
--- /dev/null
+++ b/scripts/model_examples/gemini_call.py
@@ -0,0 +1,191 @@
+# -*- coding: utf-8 -*-
+"""Examples of Google Gemini model calls."""
+import asyncio
+import json
+import os
+
+from pydantic import BaseModel, Field
+
+from _utils import stream_and_collect
+from agentscope.message import (
+    Msg,
+    TextBlock,
+    ToolCallBlock,
+    ToolResultBlock,
+    ToolResultState,
+)
+from agentscope.model import GeminiChatModel
+from agentscope.credential import GeminiCredential
+from agentscope.tool import Toolkit, ToolChoice, FunctionTool
+
+
+# ---------------------------------------------------------------------------
+# Example 1: Simple user message (streaming)
+# ---------------------------------------------------------------------------
+
+
+async def example_simple_call() -> None:
+    """Call the Gemini model with a simple text message."""
+    model = GeminiChatModel(
+        credential=GeminiCredential(
+            api_key=os.environ["GEMINI_API_KEY"],
+        ),
+        model="gemini-2.5-flash",
+        stream=True,
+        context_size=1_048_576,
+        parameters=GeminiChatModel.Parameters(
+            thinking_enable=True,
+            thinking_budget=1024,
+        ),
+    )
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[TextBlock(text="What is 1 + 1? Answer briefly.")],
+            role="user",
+        ),
+    ]
+
+    print("=== Simple Call ===")
+    await stream_and_collect(await model(msgs))
+
+
+# ---------------------------------------------------------------------------
+# Example 2: Tool calling (streaming)
+# ---------------------------------------------------------------------------
+
+
+def get_weather(city: str) -> str:
+    """Get the current weather for a city.
+
+    Args:
+        city: The city name to query the weather for.
+
+    Returns:
+        A description of the current weather.
+    """
+    return f"The weather in {city} is sunny and 25°C."
+
+
+async def example_tool_call() -> None:
+    """Call the Gemini model with tool calling enabled."""
+    toolkit = Toolkit(tools=[FunctionTool(get_weather)])
+    tools = await toolkit.get_tool_schemas()
+
+    model = GeminiChatModel(
+        credential=GeminiCredential(
+            api_key=os.environ["GEMINI_API_KEY"],
+        ),
+        model="gemini-2.5-flash",
+        stream=True,
+        context_size=1_048_576,
+        parameters=GeminiChatModel.Parameters(
+            thinking_enable=True,
+            thinking_budget=1024,
+        ),
+    )
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[TextBlock(text="What is the weather in Guangzhou?")],
+            role="user",
+        ),
+    ]
+
+    # First call: model decides to call a tool
+    print("=== Tool Call - Round 1 ===")
+    response = await stream_and_collect(
+        await model(msgs, tools=tools, tool_choice=ToolChoice(mode="auto")),
+    )
+    print(response)
+
+    tool_calls = [b for b in response.content if isinstance(b, ToolCallBlock)]
+    if tool_calls:
+        tool_result_blocks = []
+        for tool_call in tool_calls:
+            args = json.loads(tool_call.input)
+            result = get_weather(**args)
+            tool_result_blocks.append(
+                ToolResultBlock(
+                    id=tool_call.id,
+                    name=tool_call.name,
+                    output=result,
+                    state=ToolResultState.SUCCESS,
+                ),
+            )
+
+        assistant_msg = Msg(
+            name="assistant",
+            content=response.content,
+            role="assistant",
+        )
+        tool_result_msg = Msg(
+            name="tool",
+            content=tool_result_blocks,
+            role="assistant",
+        )
+        msgs = msgs + [assistant_msg, tool_result_msg]
+
+        print("=== Tool Call - Round 2 (Final) ===")
+        await stream_and_collect(await model(msgs))
+
+
+# ---------------------------------------------------------------------------
+# Example 3: Structured output
+# ---------------------------------------------------------------------------
+
+
+class MathSolution(BaseModel):
+    """Structured solution to a math problem."""
+
+    problem: str = Field(description="The original problem statement")
+    answer: float = Field(description="The final numeric answer")
+    steps: list[str] = Field(
+        description="Step-by-step reasoning leading to the answer",
+    )
+
+
+async def example_structured_output() -> None:
+    """Call the Gemini model and force a structured (JSON) output."""
+    model = GeminiChatModel(
+        credential=GeminiCredential(
+            api_key=os.environ["GEMINI_API_KEY"],
+        ),
+        model="gemini-2.5-flash",
+        stream=True,
+        context_size=1_048_576,
+        parameters=GeminiChatModel.Parameters(
+            thinking_enable=True,
+            thinking_budget=1024,
+        ),
+    )
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[
+                TextBlock(
+                    text=(
+                        "Solve this: A train travels at 60 km/h for "
+                        "2.5 hours. How far does it travel in km?"
+                    ),
+                ),
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Structured Output ===")
+    response = await model.generate_structured_output(
+        msgs,
+        structured_model=MathSolution,
+    )
+    print(response.content)
+
+
+if __name__ == "__main__":
+    asyncio.run(example_simple_call())
+    asyncio.run(example_tool_call())
+    asyncio.run(example_structured_output())
diff --git a/scripts/model_examples/gemini_multiagent.py b/scripts/model_examples/gemini_multiagent.py
new file mode 100644
index 0000000..8a28b7a
--- /dev/null
+++ b/scripts/model_examples/gemini_multiagent.py
@@ -0,0 +1,105 @@
+# -*- coding: utf-8 -*-
+"""Example of Gemini model calls with GeminiMultiAgentFormatter.
+
+The multi-agent formatter wraps prior conversation history in
+<history></history> tags, enabling the model to handle multi-agent
+conversations where more than one non-user agent is involved.
+"""
+import asyncio
+import os
+
+from _utils import stream_and_collect
+from agentscope.formatter import GeminiMultiAgentFormatter
+from agentscope.message import Msg, TextBlock
+from agentscope.model import GeminiChatModel
+from agentscope.credential import GeminiCredential
+
+
+async def example_multiagent() -> None:
+    """Simulate a multi-agent conversation and let gemini-2.5-flash
+    summarize it.
+
+    Alice and Bob discuss the weather, then a moderator (the model) is asked
+    to summarize the conversation.
+    """
+    formatter = GeminiMultiAgentFormatter()
+
+    model = GeminiChatModel(
+        credential=GeminiCredential(
+            api_key=os.environ["GEMINI_API_KEY"],
+        ),
+        model="gemini-2.5-flash",
+        stream=True,
+        context_size=1_048_576,
+        parameters=GeminiChatModel.Parameters(
+            thinking_enable=True,
+            thinking_budget=1024,
+        ),
+        formatter=formatter,
+    )
+
+    # Multi-agent conversation history between Alice and Bob
+    msgs = [
+        Msg(
+            name="system",
+            content=[
+                TextBlock(
+                    text="You are a helpful moderator. Summarize the "
+                    "conversation.",
+                ),
+            ],
+            role="system",
+        ),
+        Msg(
+            name="alice",
+            content=[
+                TextBlock(
+                    text="Hi Bob! What do you think about the weather today?",
+                ),
+            ],
+            role="user",
+        ),
+        Msg(
+            name="bob",
+            content=[
+                TextBlock(
+                    text="It's quite sunny and warm, Alice. Perfect for a "
+                    "walk!",
+                ),
+            ],
+            role="assistant",
+        ),
+        Msg(
+            name="alice",
+            content=[
+                TextBlock(text="Agreed! I might head to the park later."),
+            ],
+            role="user",
+        ),
+        Msg(
+            name="bob",
+            content=[
+                TextBlock(
+                    text="Great idea. I'll join you if I finish work early.",
+                ),
+            ],
+            role="assistant",
+        ),
+        Msg(
+            name="moderator",
+            content=[
+                TextBlock(
+                    text="Please summarize the conversation above in one "
+                    "sentence.",
+                ),
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Multi-Agent Formatter Call ===")
+    await stream_and_collect(await model(msgs))
+
+
+if __name__ == "__main__":
+    asyncio.run(example_multiagent())
diff --git a/scripts/model_examples/gemini_multiagent_multimodal.py b/scripts/model_examples/gemini_multiagent_multimodal.py
new file mode 100644
index 0000000..1ac6d91
--- /dev/null
+++ b/scripts/model_examples/gemini_multiagent_multimodal.py
@@ -0,0 +1,93 @@
+# -*- coding: utf-8 -*-
+"""Example of Gemini model calls with MultiAgentFormatter and image input."""
+import asyncio
+import os
+
+from _utils import stream_and_collect
+from agentscope.formatter import GeminiMultiAgentFormatter
+from agentscope.message import Msg, TextBlock, DataBlock, URLSource
+from agentscope.model import GeminiChatModel
+from agentscope.credential import GeminiCredential
+
+TEST_IMAGE_URL = (
+    "https://help-static-aliyun-doc.aliyuncs.com/file-manage"
+    "-files/zh-CN/20241022/emyrja/dog_and_girl.jpeg"
+)
+
+
+async def example_multiagent_image_url() -> None:
+    """Multi-agent conversation where Alice shares an image for the group."""
+    formatter = GeminiMultiAgentFormatter()
+
+    model = GeminiChatModel(
+        credential=GeminiCredential(
+            api_key=os.environ["GEMINI_API_KEY"],
+        ),
+        model="gemini-2.5-flash",
+        stream=True,
+        context_size=1_048_576,
+        parameters=GeminiChatModel.Parameters(
+            thinking_enable=True,
+            thinking_budget=1024,
+        ),
+        formatter=formatter,
+    )
+
+    image_block = DataBlock(
+        source=URLSource(url=TEST_IMAGE_URL, media_type="image/jpeg"),
+    )
+
+    msgs = [
+        Msg(
+            name="system",
+            content=[
+                TextBlock(
+                    text=(
+                        "You are a helpful moderator in a group chat. "
+                        "Summarize what the image shows and what the "
+                        "participants said."
+                    ),
+                ),
+            ],
+            role="system",
+        ),
+        Msg(
+            name="alice",
+            content=[
+                TextBlock(
+                    text="Hey everyone, look at this cute photo I took!",
+                ),
+                image_block,
+            ],
+            role="user",
+        ),
+        Msg(
+            name="bob",
+            content=[
+                TextBlock(text="Aww, that's adorable! Where was this taken?"),
+            ],
+            role="assistant",
+        ),
+        Msg(
+            name="alice",
+            content=[TextBlock(text="At the local park yesterday.")],
+            role="user",
+        ),
+        Msg(
+            name="moderator",
+            content=[
+                TextBlock(
+                    text="Please summarize the image content and the "
+                    "conversation in one paragraph.",
+                ),
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Multi-Agent + Multimodal Call ===")
+    await stream_and_collect(await model(msgs))
+
+
+if __name__ == "__main__":
+    asyncio.run(example_multiagent_image_url())
diff --git a/scripts/model_examples/gemini_multimodal.py b/scripts/model_examples/gemini_multimodal.py
new file mode 100644
index 0000000..665597d
--- /dev/null
+++ b/scripts/model_examples/gemini_multimodal.py
@@ -0,0 +1,143 @@
+# -*- coding: utf-8 -*-
+"""Example of Gemini model multimodal (vision) calls using DataBlock."""
+import asyncio
+import base64
+import os
+from pathlib import Path
+
+from _utils import stream_and_collect
+from agentscope.message import (
+    Msg,
+    TextBlock,
+    DataBlock,
+    URLSource,
+    Base64Source,
+)
+from agentscope.model import GeminiChatModel
+from agentscope.credential import GeminiCredential
+
+# A publicly accessible test image (a simple cat photo)
+TEST_IMAGE_URL = (
+    "https://help-static-aliyun-doc.aliyuncs.com/file-manage"
+    "-files/zh-CN/20241022/emyrja/dog_and_girl.jpeg"
+)
+
+
+async def example_image_url() -> None:
+    """Call gemini-2.5-flash with an image URL and ask what is in the image."""
+    model = GeminiChatModel(
+        credential=GeminiCredential(
+            api_key=os.environ["GEMINI_API_KEY"],
+        ),
+        model="gemini-2.5-flash",
+        stream=True,
+        context_size=1_048_576,
+        parameters=GeminiChatModel.Parameters(
+            thinking_enable=True,
+            thinking_budget=1024,
+        ),
+    )
+
+    image_block = DataBlock(
+        source=URLSource(
+            url=TEST_IMAGE_URL,
+            media_type="image/jpeg",
+        ),
+    )
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[
+                TextBlock(
+                    text="What animal is in this image? Describe it briefly.",
+                ),
+                image_block,
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Multimodal Call (Image URL) ===")
+    await stream_and_collect(await model(msgs))
+
+
+def _build_model() -> GeminiChatModel:
+    return GeminiChatModel(
+        credential=GeminiCredential(api_key=os.environ["GEMINI_API_KEY"]),
+        model="gemini-2.5-flash",
+        stream=True,
+        context_size=1_048_576,
+        parameters=GeminiChatModel.Parameters(
+            thinking_enable=True,
+            thinking_budget=1024,
+        ),
+    )
+
+
+async def example_image_local_path() -> None:
+    """Call gemini-2.5-flash with a local image using a ``file://`` URL.
+
+    The formatter reads the file from disk and converts it to base64.
+    """
+    model = _build_model()
+
+    abs_path = str(Path(__file__).parent / "test.jpeg")
+    msgs = [
+        Msg(
+            name="user",
+            content=[
+                TextBlock(
+                    text="What is happening in this image? Describe it "
+                    "briefly.",
+                ),
+                DataBlock(
+                    source=URLSource(
+                        url=f"file://{abs_path}",
+                        media_type="image/jpeg",
+                    ),
+                ),
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Local Path Call (file://) ===")
+    await stream_and_collect(await model(msgs))
+
+
+async def example_image_base64() -> None:
+    """Call gemini-2.5-flash with a local image using explicit base64 encoding.
+
+    Use ``Base64Source`` when you already have the binary data in memory or
+    want full control over the encoding step.
+    """
+    model = _build_model()
+
+    with open(Path(__file__).parent / "test.jpeg", "rb") as f:
+        data = base64.b64encode(f.read()).decode("utf-8")
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[
+                TextBlock(
+                    text="What is happening in this image? Describe it "
+                    "briefly.",
+                ),
+                DataBlock(
+                    source=Base64Source(data=data, media_type="image/jpeg"),
+                ),
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Explicit Base64 Call ===")
+    await stream_and_collect(await model(msgs))
+
+
+if __name__ == "__main__":
+    asyncio.run(example_image_url())
+    asyncio.run(example_image_local_path())
+    asyncio.run(example_image_base64())
diff --git a/scripts/model_examples/moonshot_call.py b/scripts/model_examples/moonshot_call.py
new file mode 100644
index 0000000..74e6d01
--- /dev/null
+++ b/scripts/model_examples/moonshot_call.py
@@ -0,0 +1,180 @@
+# -*- coding: utf-8 -*-
+"""Examples of Moonshot AI model calls."""
+import asyncio
+import json
+import os
+
+from pydantic import BaseModel, Field
+
+from _utils import stream_and_collect
+from agentscope.message import (
+    Msg,
+    TextBlock,
+    ToolCallBlock,
+    ToolResultBlock,
+    ToolResultState,
+)
+from agentscope.model import MoonshotChatModel
+from agentscope.credential import MoonshotCredential
+from agentscope.tool import Toolkit, ToolChoice, FunctionTool
+
+
+# ---------------------------------------------------------------------------
+# Example 1: Simple user message (streaming)
+# ---------------------------------------------------------------------------
+
+
+async def example_simple_call() -> None:
+    """Call the Moonshot model with a simple text message."""
+    model = MoonshotChatModel(
+        credential=MoonshotCredential(
+            api_key=os.environ["MOONSHOT_API_KEY"],
+        ),
+        model="kimi-k2.6",
+        stream=True,
+        context_size=262_144,
+    )
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[TextBlock(text="What is 1 + 1? Answer briefly.")],
+            role="user",
+        ),
+    ]
+
+    print("=== Simple Call ===")
+    await stream_and_collect(await model(msgs))
+
+
+# ---------------------------------------------------------------------------
+# Example 2: Tool calling (streaming)
+# ---------------------------------------------------------------------------
+
+
+def get_weather(city: str) -> str:
+    """Get the current weather for a city.
+
+    Args:
+        city: The city name to query the weather for.
+
+    Returns:
+        A description of the current weather.
+    """
+    return f"The weather in {city} is sunny and 25°C."
+
+
+async def example_tool_call() -> None:
+    """Call the Moonshot model with tool calling enabled."""
+    toolkit = Toolkit(tools=[FunctionTool(get_weather)])
+    tools = await toolkit.get_tool_schemas()
+
+    model = MoonshotChatModel(
+        credential=MoonshotCredential(
+            api_key=os.environ["MOONSHOT_API_KEY"],
+        ),
+        model="kimi-k2.6",
+        stream=True,
+        context_size=262_144,
+    )
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[TextBlock(text="What is the weather in Xi'an?")],
+            role="user",
+        ),
+    ]
+
+    # First call: model decides to call a tool
+    print("=== Tool Call - Round 1 ===")
+    response = await stream_and_collect(
+        await model(msgs, tools=tools, tool_choice=ToolChoice(mode="auto")),
+    )
+    print(response)
+
+    tool_calls = [b for b in response.content if isinstance(b, ToolCallBlock)]
+    if tool_calls:
+        tool_result_blocks = []
+        for tool_call in tool_calls:
+            args = json.loads(tool_call.input)
+            result = get_weather(**args)
+            tool_result_blocks.append(
+                ToolResultBlock(
+                    id=tool_call.id,
+                    name=tool_call.name,
+                    output=result,
+                    state=ToolResultState.SUCCESS,
+                ),
+            )
+
+        assistant_msg = Msg(
+            name="assistant",
+            content=response.content,
+            role="assistant",
+        )
+        tool_result_msg = Msg(
+            name="tool",
+            content=tool_result_blocks,
+            role="assistant",
+        )
+        msgs = msgs + [assistant_msg, tool_result_msg]
+
+        print("=== Tool Call - Round 2 (Final) ===")
+        await stream_and_collect(await model(msgs))
+
+
+# ---------------------------------------------------------------------------
+# Example 3: Structured output
+# ---------------------------------------------------------------------------
+
+
+class MathSolution(BaseModel):
+    """Structured solution to a math problem."""
+
+    problem: str = Field(description="The original problem statement")
+    answer: float = Field(description="The final numeric answer")
+    steps: list[str] = Field(
+        description="Step-by-step reasoning leading to the answer",
+    )
+
+
+async def example_structured_output() -> None:
+    """Call the Moonshot model and force a structured (JSON) output."""
+    model = MoonshotChatModel(
+        credential=MoonshotCredential(
+            api_key=os.environ["MOONSHOT_API_KEY"],
+        ),
+        model="kimi-k2.6",
+        stream=True,
+        context_size=262_144,
+        parameters=MoonshotChatModel.Parameters(thinking_enable=True),
+    )
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[
+                TextBlock(
+                    text=(
+                        "Solve this: A train travels at 60 km/h for "
+                        "2.5 hours. How far does it travel in km?"
+                    ),
+                ),
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Structured Output ===")
+    response = await model.generate_structured_output(
+        msgs,
+        structured_model=MathSolution,
+    )
+    print(response.content)
+
+
+if __name__ == "__main__":
+    asyncio.run(example_simple_call())
+    asyncio.run(example_tool_call())
+    asyncio.run(example_structured_output())
diff --git a/scripts/model_examples/moonshot_multiagent.py b/scripts/model_examples/moonshot_multiagent.py
new file mode 100644
index 0000000..65bd99e
--- /dev/null
+++ b/scripts/model_examples/moonshot_multiagent.py
@@ -0,0 +1,101 @@
+# -*- coding: utf-8 -*-
+"""Example of Moonshot model calls with MoonshotMultiAgentFormatter.
+
+The multi-agent formatter wraps prior conversation history in
+<history></history> tags and preserves reasoning_content for Moonshot's
+Preserved Thinking feature in multi-turn conversations.
+"""
+import asyncio
+import os
+
+from _utils import stream_and_collect
+from agentscope.formatter import MoonshotMultiAgentFormatter
+from agentscope.message import Msg, TextBlock
+from agentscope.model import MoonshotChatModel
+from agentscope.credential import MoonshotCredential
+
+
+async def example_multiagent() -> None:
+    """Simulate a multi-agent conversation and let kimi-k2.6 summarize it.
+
+    Alice and Bob discuss the weather, then a moderator (the model) is asked
+    to summarize the conversation.
+    """
+    formatter = MoonshotMultiAgentFormatter()
+
+    model = MoonshotChatModel(
+        credential=MoonshotCredential(
+            api_key=os.environ["MOONSHOT_API_KEY"],
+        ),
+        model="kimi-k2.6",
+        stream=True,
+        context_size=262_144,
+        parameters=MoonshotChatModel.Parameters(thinking_enable=True),
+        formatter=formatter,
+    )
+
+    # Multi-agent conversation history between Alice and Bob
+    msgs = [
+        Msg(
+            name="system",
+            content=[
+                TextBlock(
+                    text="You are a helpful moderator. Summarize the "
+                    "conversation.",
+                ),
+            ],
+            role="system",
+        ),
+        Msg(
+            name="alice",
+            content=[
+                TextBlock(
+                    text="Hi Bob! What do you think about the weather today?",
+                ),
+            ],
+            role="user",
+        ),
+        Msg(
+            name="bob",
+            content=[
+                TextBlock(
+                    text="It's quite sunny and warm, Alice. Perfect for a "
+                    "walk!",
+                ),
+            ],
+            role="assistant",
+        ),
+        Msg(
+            name="alice",
+            content=[
+                TextBlock(text="Agreed! I might head to the park later."),
+            ],
+            role="user",
+        ),
+        Msg(
+            name="bob",
+            content=[
+                TextBlock(
+                    text="Great idea. I'll join you if I finish work early.",
+                ),
+            ],
+            role="assistant",
+        ),
+        Msg(
+            name="moderator",
+            content=[
+                TextBlock(
+                    text="Please summarize the conversation above in one "
+                    "sentence.",
+                ),
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Multi-Agent Formatter Call ===")
+    await stream_and_collect(await model(msgs))
+
+
+if __name__ == "__main__":
+    asyncio.run(example_multiagent())
diff --git a/scripts/model_examples/moonshot_multiagent_multimodal.py b/scripts/model_examples/moonshot_multiagent_multimodal.py
new file mode 100644
index 0000000..0f15cab
--- /dev/null
+++ b/scripts/model_examples/moonshot_multiagent_multimodal.py
@@ -0,0 +1,91 @@
+# -*- coding: utf-8 -*-
+"""Example of Moonshot model calls with MoonshotMultiAgentFormatter and
+image input."""
+import asyncio
+import os
+
+from _utils import stream_and_collect
+from agentscope.formatter import MoonshotMultiAgentFormatter
+from agentscope.message import Msg, TextBlock, DataBlock, URLSource
+from agentscope.model import MoonshotChatModel
+from agentscope.credential import MoonshotCredential
+
+TEST_IMAGE_URL = (
+    "https://help-static-aliyun-doc.aliyuncs.com/file-manage"
+    "-files/zh-CN/20241022/emyrja/dog_and_girl.jpeg"
+)
+
+
+async def example_multiagent_image_url() -> None:
+    """Multi-agent conversation where Alice shares an image for the group."""
+    formatter = MoonshotMultiAgentFormatter()
+
+    model = MoonshotChatModel(
+        credential=MoonshotCredential(
+            api_key=os.environ["MOONSHOT_API_KEY"],
+        ),
+        model="kimi-k2.6",
+        stream=True,
+        context_size=262_144,
+        parameters=MoonshotChatModel.Parameters(thinking_enable=True),
+        formatter=formatter,
+    )
+
+    image_block = DataBlock(
+        source=URLSource(url=TEST_IMAGE_URL, media_type="image/jpeg"),
+    )
+
+    msgs = [
+        Msg(
+            name="system",
+            content=[
+                TextBlock(
+                    text=(
+                        "You are a helpful moderator in a group chat. "
+                        "Summarize what the image shows and what the "
+                        "participants said."
+                    ),
+                ),
+            ],
+            role="system",
+        ),
+        Msg(
+            name="alice",
+            content=[
+                TextBlock(
+                    text="Hey everyone, look at this cute photo I took!",
+                ),
+                image_block,
+            ],
+            role="user",
+        ),
+        Msg(
+            name="bob",
+            content=[
+                TextBlock(text="Aww, that's adorable! Where was this taken?"),
+            ],
+            role="assistant",
+        ),
+        Msg(
+            name="alice",
+            content=[TextBlock(text="At the local park yesterday.")],
+            role="user",
+        ),
+        Msg(
+            name="moderator",
+            content=[
+                TextBlock(
+                    text="Please summarize the image content and the "
+                    "conversation in one paragraph.",
+                ),
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Multi-Agent + Multimodal Call ===")
+    await stream_and_collect(await model(msgs))
+
+
+if __name__ == "__main__":
+    asyncio.run(example_multiagent_image_url())
diff --git a/scripts/model_examples/moonshot_multimodal.py b/scripts/model_examples/moonshot_multimodal.py
new file mode 100644
index 0000000..498e3c5
--- /dev/null
+++ b/scripts/model_examples/moonshot_multimodal.py
@@ -0,0 +1,137 @@
+# -*- coding: utf-8 -*-
+"""Example of Moonshot model multimodal (vision) calls using DataBlock."""
+import asyncio
+import base64
+import os
+from pathlib import Path
+
+from _utils import stream_and_collect
+from agentscope.message import (
+    Msg,
+    TextBlock,
+    DataBlock,
+    URLSource,
+    Base64Source,
+)
+from agentscope.model import MoonshotChatModel
+from agentscope.credential import MoonshotCredential
+
+TEST_IMAGE_URL = (
+    "https://help-static-aliyun-doc.aliyuncs.com/file-manage"
+    "-files/zh-CN/20241022/emyrja/dog_and_girl.jpeg"
+)
+
+
+async def example_image_url() -> None:
+    """Call kimi-k2.6 with an image URL and ask what is in the image."""
+    model = MoonshotChatModel(
+        credential=MoonshotCredential(
+            api_key=os.environ["MOONSHOT_API_KEY"],
+        ),
+        model="kimi-k2.6",
+        stream=True,
+        context_size=262_144,
+        parameters=MoonshotChatModel.Parameters(thinking_enable=True),
+    )
+
+    image_block = DataBlock(
+        source=URLSource(
+            url=TEST_IMAGE_URL,
+            media_type="image/jpeg",
+        ),
+    )
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[
+                TextBlock(
+                    text="What animal is in this image? Describe it briefly.",
+                ),
+                image_block,
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Multimodal Call (Image URL) ===")
+    await stream_and_collect(await model(msgs))
+
+
+def _build_model() -> MoonshotChatModel:
+    return MoonshotChatModel(
+        credential=MoonshotCredential(api_key=os.environ["MOONSHOT_API_KEY"]),
+        model="kimi-k2.6",
+        stream=True,
+        context_size=262_144,
+        parameters=MoonshotChatModel.Parameters(thinking_enable=True),
+    )
+
+
+async def example_image_local_path() -> None:
+    """Call kimi-k2.6 with a local image using a ``file://`` URL.
+
+    The formatter reads the file from disk and converts it to a base64 data
+     URI.
+    """
+    model = _build_model()
+
+    abs_path = str(Path(__file__).parent / "test.jpeg")
+    msgs = [
+        Msg(
+            name="user",
+            content=[
+                TextBlock(
+                    text="What is happening in this image? Describe it "
+                    "briefly.",
+                ),
+                DataBlock(
+                    source=URLSource(
+                        url=f"file://{abs_path}",
+                        media_type="image/jpeg",
+                    ),
+                ),
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Local Path Call (file://) ===")
+    await stream_and_collect(await model(msgs))
+
+
+async def example_image_base64() -> None:
+    """Call kimi-k2.6 with a local image using explicit base64 encoding.
+
+    Use ``Base64Source`` when you already have the binary data in memory or
+    want full control over the encoding step.
+    """
+    model = _build_model()
+
+    with open(Path(__file__).parent / "test.jpeg", "rb") as f:
+        data = base64.b64encode(f.read()).decode("utf-8")
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[
+                TextBlock(
+                    text="What is happening in this image? Describe it "
+                    "briefly.",
+                ),
+                DataBlock(
+                    source=Base64Source(data=data, media_type="image/jpeg"),
+                ),
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Explicit Base64 Call ===")
+    await stream_and_collect(await model(msgs))
+
+
+if __name__ == "__main__":
+    asyncio.run(example_image_url())
+    asyncio.run(example_image_local_path())
+    asyncio.run(example_image_base64())
diff --git a/scripts/model_examples/ollama_call.py b/scripts/model_examples/ollama_call.py
new file mode 100644
index 0000000..d633f08
--- /dev/null
+++ b/scripts/model_examples/ollama_call.py
@@ -0,0 +1,188 @@
+# -*- coding: utf-8 -*-
+"""Examples of Ollama (local) model calls.
+
+Make sure Ollama is running locally before running these examples:
+    ollama serve
+
+Pull the model first if you haven't already:
+    ollama pull qwen3:14b
+"""
+import asyncio
+import json
+
+from pydantic import BaseModel, Field
+
+from _utils import stream_and_collect
+from agentscope.message import (
+    Msg,
+    TextBlock,
+    ToolCallBlock,
+    ToolResultBlock,
+    ToolResultState,
+)
+from agentscope.model import OllamaChatModel
+from agentscope.credential import OllamaCredential
+from agentscope.tool import Toolkit, ToolChoice, FunctionTool
+
+
+# ---------------------------------------------------------------------------
+# Example 1: Simple user message (streaming)
+# ---------------------------------------------------------------------------
+
+
+async def example_simple_call() -> None:
+    """Call the Ollama model with a simple text message."""
+    model = OllamaChatModel(
+        credential=OllamaCredential(
+            host="http://localhost:11434",
+        ),
+        model="qwen3:14b",
+        stream=True,
+        context_size=40_960,
+        parameters=OllamaChatModel.Parameters(thinking_enable=True),
+    )
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[TextBlock(text="What is 1 + 1? Answer briefly.")],
+            role="user",
+        ),
+    ]
+
+    print("=== Simple Call ===")
+    await stream_and_collect(await model(msgs))
+
+
+# ---------------------------------------------------------------------------
+# Example 2: Tool calling (streaming)
+# ---------------------------------------------------------------------------
+
+
+def get_weather(city: str) -> str:
+    """Get the current weather for a city.
+
+    Args:
+        city: The city name to query the weather for.
+
+    Returns:
+        A description of the current weather.
+    """
+    return f"The weather in {city} is sunny and 25°C."
+
+
+async def example_tool_call() -> None:
+    """Call the Ollama model with tool calling enabled."""
+    toolkit = Toolkit(tools=[FunctionTool(get_weather)])
+    tools = await toolkit.get_tool_schemas()
+
+    model = OllamaChatModel(
+        credential=OllamaCredential(
+            host="http://localhost:11434",
+        ),
+        model="qwen3:14b",
+        stream=True,
+        context_size=40_960,
+        parameters=OllamaChatModel.Parameters(thinking_enable=True),
+    )
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[TextBlock(text="What is the weather in Nanjing?")],
+            role="user",
+        ),
+    ]
+
+    # First call: model decides to call a tool
+    print("=== Tool Call - Round 1 ===")
+    response = await stream_and_collect(
+        await model(msgs, tools=tools, tool_choice=ToolChoice(mode="auto")),
+    )
+    print(response)
+
+    tool_calls = [b for b in response.content if isinstance(b, ToolCallBlock)]
+    if tool_calls:
+        tool_result_blocks = []
+        for tool_call in tool_calls:
+            args = json.loads(tool_call.input)
+            result = get_weather(**args)
+            tool_result_blocks.append(
+                ToolResultBlock(
+                    id=tool_call.id,
+                    name=tool_call.name,
+                    output=result,
+                    state=ToolResultState.SUCCESS,
+                ),
+            )
+
+        assistant_msg = Msg(
+            name="assistant",
+            content=response.content,
+            role="assistant",
+        )
+        tool_result_msg = Msg(
+            name="tool",
+            content=tool_result_blocks,
+            role="assistant",
+        )
+        msgs = msgs + [assistant_msg, tool_result_msg]
+
+        print("=== Tool Call - Round 2 (Final) ===")
+        await stream_and_collect(await model(msgs))
+
+
+# ---------------------------------------------------------------------------
+# Example 3: Structured output
+# ---------------------------------------------------------------------------
+
+
+class MathSolution(BaseModel):
+    """Structured solution to a math problem."""
+
+    problem: str = Field(description="The original problem statement")
+    answer: float = Field(description="The final numeric answer")
+    steps: list[str] = Field(
+        description="Step-by-step reasoning leading to the answer",
+    )
+
+
+async def example_structured_output() -> None:
+    """Call the Ollama model and force a structured (JSON) output."""
+    model = OllamaChatModel(
+        credential=OllamaCredential(
+            host="http://localhost:11434",
+        ),
+        model="qwen3:14b",
+        stream=True,
+        context_size=40_960,
+        parameters=OllamaChatModel.Parameters(thinking_enable=True),
+    )
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[
+                TextBlock(
+                    text=(
+                        "Solve this: A train travels at 60 km/h for "
+                        "2.5 hours. How far does it travel in km?"
+                    ),
+                ),
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Structured Output ===")
+    response = await model.generate_structured_output(
+        msgs,
+        structured_model=MathSolution,
+    )
+    print(response.content)
+
+
+if __name__ == "__main__":
+    asyncio.run(example_simple_call())
+    asyncio.run(example_tool_call())
+    asyncio.run(example_structured_output())
diff --git a/scripts/model_examples/ollama_multiagent.py b/scripts/model_examples/ollama_multiagent.py
new file mode 100644
index 0000000..34ed419
--- /dev/null
+++ b/scripts/model_examples/ollama_multiagent.py
@@ -0,0 +1,96 @@
+# -*- coding: utf-8 -*-
+"""Example of Ollama model calls with OllamaMultiAgentFormatter.
+
+The multi-agent formatter wraps prior conversation history in
+<history></history> tags, enabling the model to handle multi-agent
+conversations where more than one non-user agent is involved.
+"""
+import asyncio
+
+from _utils import stream_and_collect
+from agentscope.formatter import OllamaMultiAgentFormatter
+from agentscope.message import Msg, TextBlock
+from agentscope.model import OllamaChatModel
+
+
+async def example_multiagent() -> None:
+    """Simulate a multi-agent conversation and let qwen3:14b summarize it.
+
+    Alice and Bob discuss the weather, then a moderator (the model) is asked
+    to summarize the conversation.
+    """
+    formatter = OllamaMultiAgentFormatter()
+
+    model = OllamaChatModel(
+        model="qwen3:14b",
+        stream=True,
+        context_size=40_960,
+        parameters=OllamaChatModel.Parameters(thinking_enable=True),
+        formatter=formatter,
+    )
+
+    # Multi-agent conversation history between Alice and Bob
+    msgs = [
+        Msg(
+            name="system",
+            content=[
+                TextBlock(
+                    text="You are a helpful moderator. Summarize the "
+                    "conversation.",
+                ),
+            ],
+            role="system",
+        ),
+        Msg(
+            name="alice",
+            content=[
+                TextBlock(
+                    text="Hi Bob! What do you think about the weather today?",
+                ),
+            ],
+            role="user",
+        ),
+        Msg(
+            name="bob",
+            content=[
+                TextBlock(
+                    text="It's quite sunny and warm, Alice. Perfect for a "
+                    "walk!",
+                ),
+            ],
+            role="assistant",
+        ),
+        Msg(
+            name="alice",
+            content=[
+                TextBlock(text="Agreed! I might head to the park later."),
+            ],
+            role="user",
+        ),
+        Msg(
+            name="bob",
+            content=[
+                TextBlock(
+                    text="Great idea. I'll join you if I finish work early.",
+                ),
+            ],
+            role="assistant",
+        ),
+        Msg(
+            name="moderator",
+            content=[
+                TextBlock(
+                    text="Please summarize the conversation above in one "
+                    "sentence.",
+                ),
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Multi-Agent Formatter Call ===")
+    await stream_and_collect(await model(msgs))
+
+
+if __name__ == "__main__":
+    asyncio.run(example_multiagent())
diff --git a/scripts/model_examples/ollama_multiagent_multimodal.py b/scripts/model_examples/ollama_multiagent_multimodal.py
new file mode 100644
index 0000000..97c4f57
--- /dev/null
+++ b/scripts/model_examples/ollama_multiagent_multimodal.py
@@ -0,0 +1,91 @@
+# -*- coding: utf-8 -*-
+"""Example of Ollama model calls with MultiAgentFormatter and image input.
+
+Requires a multimodal Ollama model such as llava. Run `ollama pull llava`
+first.
+"""
+import asyncio
+
+from _utils import stream_and_collect
+from agentscope.formatter import OllamaMultiAgentFormatter
+from agentscope.message import Msg, TextBlock, DataBlock, URLSource
+from agentscope.model import OllamaChatModel
+
+TEST_IMAGE_URL = (
+    "https://help-static-aliyun-doc.aliyuncs.com/file-manage"
+    "-files/zh-CN/20241022/emyrja/dog_and_girl.jpeg"
+)
+
+
+async def example_multiagent_image_url() -> None:
+    """Multi-agent conversation where Alice shares an image for the group.
+
+    Requires `ollama pull llava` to have been run first.
+    """
+    formatter = OllamaMultiAgentFormatter()
+
+    model = OllamaChatModel(
+        model="llava:7b",
+        stream=True,
+        context_size=4_096,
+        formatter=formatter,
+    )
+
+    image_block = DataBlock(
+        source=URLSource(url=TEST_IMAGE_URL, media_type="image/jpeg"),
+    )
+
+    msgs = [
+        Msg(
+            name="system",
+            content=[
+                TextBlock(
+                    text=(
+                        "You are a helpful moderator in a group chat. "
+                        "Summarize what the image shows and what the "
+                        "participants said."
+                    ),
+                ),
+            ],
+            role="system",
+        ),
+        Msg(
+            name="alice",
+            content=[
+                TextBlock(
+                    text="Hey everyone, look at this cute photo I took!",
+                ),
+                image_block,
+            ],
+            role="user",
+        ),
+        Msg(
+            name="bob",
+            content=[
+                TextBlock(text="Aww, that's adorable! Where was this taken?"),
+            ],
+            role="assistant",
+        ),
+        Msg(
+            name="alice",
+            content=[TextBlock(text="At the local park yesterday.")],
+            role="user",
+        ),
+        Msg(
+            name="moderator",
+            content=[
+                TextBlock(
+                    text="Please summarize the image content and the "
+                    "conversation in one paragraph.",
+                ),
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Multi-Agent + Multimodal Call ===")
+    await stream_and_collect(await model(msgs))
+
+
+if __name__ == "__main__":
+    asyncio.run(example_multiagent_image_url())
diff --git a/scripts/model_examples/ollama_multimodal.py b/scripts/model_examples/ollama_multimodal.py
new file mode 100644
index 0000000..33a3331
--- /dev/null
+++ b/scripts/model_examples/ollama_multimodal.py
@@ -0,0 +1,136 @@
+# -*- coding: utf-8 -*-
+"""Example of Ollama model multimodal (vision) calls using DataBlock.
+
+Note: Vision input requires a multimodal Ollama model such as llava, bakllava,
+or moondream. Run `ollama pull llava` before executing this example.
+"""
+import asyncio
+import base64
+from pathlib import Path
+
+from _utils import stream_and_collect
+from agentscope.message import (
+    Msg,
+    TextBlock,
+    DataBlock,
+    URLSource,
+    Base64Source,
+)
+from agentscope.model import OllamaChatModel
+
+# A publicly accessible test image (a simple cat photo)
+TEST_IMAGE_URL = (
+    "https://help-static-aliyun-doc.aliyuncs.com/file-manage"
+    "-files/zh-CN/20241022/emyrja/dog_and_girl.jpeg"
+)
+
+
+async def example_image_url() -> None:
+    """Call llava:7b with an image URL and ask what is in the image.
+
+    Requires `ollama pull llava` to be run first.
+    """
+    model = OllamaChatModel(
+        model="llava:7b",
+        stream=True,
+        context_size=4_096,
+    )
+
+    image_block = DataBlock(
+        source=URLSource(
+            url=TEST_IMAGE_URL,
+            media_type="image/jpeg",
+        ),
+    )
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[
+                TextBlock(
+                    text="What animal is in this image? Describe it briefly.",
+                ),
+                image_block,
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Multimodal Call (Image URL) ===")
+    await stream_and_collect(await model(msgs))
+
+
+def _build_model() -> OllamaChatModel:
+    return OllamaChatModel(
+        model="llava:7b",
+        stream=True,
+        context_size=4_096,
+    )
+
+
+async def example_image_local_path() -> None:
+    """Call llava:7b with a local image using a ``file://`` URL.
+
+    The formatter reads the file from disk and converts it to base64.
+    """
+    model = _build_model()
+
+    abs_path = str(Path(__file__).parent / "test.jpeg")
+    msgs = [
+        Msg(
+            name="user",
+            content=[
+                TextBlock(
+                    text="What is happening in this image? Describe it "
+                    "briefly.",
+                ),
+                DataBlock(
+                    source=URLSource(
+                        url=f"file://{abs_path}",
+                        media_type="image/jpeg",
+                    ),
+                ),
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Local Path Call (file://) ===")
+    await stream_and_collect(await model(msgs))
+
+
+async def example_image_base64() -> None:
+    """Call llava:7b with a local image using explicit base64 encoding.
+
+    Use ``Base64Source`` when you already have the binary data in memory or
+    want full control over the encoding step.
+    """
+    model = _build_model()
+
+    with open(Path(__file__).parent / "test.jpeg", "rb") as f:
+        data = base64.b64encode(f.read()).decode("utf-8")
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[
+                TextBlock(
+                    text="What is happening in this image? Describe it "
+                    "briefly.",
+                ),
+                DataBlock(
+                    source=Base64Source(data=data, media_type="image/jpeg"),
+                ),
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Explicit Base64 Call ===")
+    await stream_and_collect(await model(msgs))
+
+
+if __name__ == "__main__":
+    asyncio.run(example_image_url())
+    asyncio.run(example_image_local_path())
+    asyncio.run(example_image_base64())
diff --git a/scripts/model_examples/openai_chat_call.py b/scripts/model_examples/openai_chat_call.py
new file mode 100644
index 0000000..660918f
--- /dev/null
+++ b/scripts/model_examples/openai_chat_call.py
@@ -0,0 +1,191 @@
+# -*- coding: utf-8 -*-
+"""Examples of OpenAI Chat Completions model calls."""
+import asyncio
+import json
+import os
+
+from pydantic import BaseModel, Field
+
+from _utils import stream_and_collect
+from agentscope.message import (
+    Msg,
+    TextBlock,
+    ToolCallBlock,
+    ToolResultBlock,
+    ToolResultState,
+)
+from agentscope.model import OpenAIChatModel
+from agentscope.credential import OpenAICredential
+from agentscope.tool import Toolkit, ToolChoice, FunctionTool
+
+
+# ---------------------------------------------------------------------------
+# Example 1: Simple user message (streaming)
+# ---------------------------------------------------------------------------
+
+
+async def example_simple_call() -> None:
+    """Call the OpenAI Chat model with a simple text message."""
+    model = OpenAIChatModel(
+        credential=OpenAICredential(
+            api_key=os.environ["OPENAI_API_KEY"],
+        ),
+        model="o4-mini",
+        stream=True,
+        context_size=200_000,
+        parameters=OpenAIChatModel.Parameters(
+            thinking_enable=True,
+            reasoning_effort="low",
+        ),
+    )
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[TextBlock(text="What is 1 + 1? Answer briefly.")],
+            role="user",
+        ),
+    ]
+
+    print("=== Simple Call ===")
+    await stream_and_collect(await model(msgs))
+
+
+# ---------------------------------------------------------------------------
+# Example 2: Tool calling (streaming)
+# ---------------------------------------------------------------------------
+
+
+def get_weather(city: str) -> str:
+    """Get the current weather for a city.
+
+    Args:
+        city: The city name to query the weather for.
+
+    Returns:
+        A description of the current weather.
+    """
+    return f"The weather in {city} is sunny and 25°C."
+
+
+async def example_tool_call() -> None:
+    """Call the OpenAI Chat model with tool calling enabled."""
+    toolkit = Toolkit(tools=[FunctionTool(get_weather)])
+    tools = await toolkit.get_tool_schemas()
+
+    model = OpenAIChatModel(
+        credential=OpenAICredential(
+            api_key=os.environ["OPENAI_API_KEY"],
+        ),
+        model="o4-mini",
+        stream=True,
+        context_size=200_000,
+        parameters=OpenAIChatModel.Parameters(
+            thinking_enable=True,
+            reasoning_effort="low",
+        ),
+    )
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[TextBlock(text="What is the weather in Chengdu?")],
+            role="user",
+        ),
+    ]
+
+    # First call: model decides to call a tool
+    print("=== Tool Call - Round 1 ===")
+    response = await stream_and_collect(
+        await model(msgs, tools=tools, tool_choice=ToolChoice(mode="auto")),
+    )
+    print(response)
+
+    tool_calls = [b for b in response.content if isinstance(b, ToolCallBlock)]
+    if tool_calls:
+        tool_result_blocks = []
+        for tool_call in tool_calls:
+            args = json.loads(tool_call.input)
+            result = get_weather(**args)
+            tool_result_blocks.append(
+                ToolResultBlock(
+                    id=tool_call.id,
+                    name=tool_call.name,
+                    output=result,
+                    state=ToolResultState.SUCCESS,
+                ),
+            )
+
+        assistant_msg = Msg(
+            name="assistant",
+            content=response.content,
+            role="assistant",
+        )
+        tool_result_msg = Msg(
+            name="tool",
+            content=tool_result_blocks,
+            role="assistant",
+        )
+        msgs = msgs + [assistant_msg, tool_result_msg]
+
+        print("=== Tool Call - Round 2 (Final) ===")
+        await stream_and_collect(await model(msgs))
+
+
+# ---------------------------------------------------------------------------
+# Example 3: Structured output
+# ---------------------------------------------------------------------------
+
+
+class MathSolution(BaseModel):
+    """Structured solution to a math problem."""
+
+    problem: str = Field(description="The original problem statement")
+    answer: float = Field(description="The final numeric answer")
+    steps: list[str] = Field(
+        description="Step-by-step reasoning leading to the answer",
+    )
+
+
+async def example_structured_output() -> None:
+    """Call the OpenAI Chat model and force a structured (JSON) output."""
+    model = OpenAIChatModel(
+        credential=OpenAICredential(
+            api_key=os.environ["OPENAI_API_KEY"],
+        ),
+        model="o4-mini",
+        stream=True,
+        context_size=200_000,
+        parameters=OpenAIChatModel.Parameters(
+            thinking_enable=True,
+            reasoning_effort="low",
+        ),
+    )
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[
+                TextBlock(
+                    text=(
+                        "Solve this: A train travels at 60 km/h for "
+                        "2.5 hours. How far does it travel in km?"
+                    ),
+                ),
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Structured Output ===")
+    response = await model.generate_structured_output(
+        msgs,
+        structured_model=MathSolution,
+    )
+    print(response.content)
+
+
+if __name__ == "__main__":
+    asyncio.run(example_simple_call())
+    asyncio.run(example_tool_call())
+    asyncio.run(example_structured_output())
diff --git a/scripts/model_examples/openai_chat_multiagent.py b/scripts/model_examples/openai_chat_multiagent.py
new file mode 100644
index 0000000..babd3ad
--- /dev/null
+++ b/scripts/model_examples/openai_chat_multiagent.py
@@ -0,0 +1,100 @@
+# -*- coding: utf-8 -*-
+"""Example of OpenAI Chat model calls with OpenAIMultiAgentFormatter.
+
+The multi-agent formatter wraps prior conversation history in
+<history></history> tags, enabling the model to handle multi-agent
+conversations where more than one non-user agent is involved.
+"""
+import asyncio
+import os
+
+from _utils import stream_and_collect
+from agentscope.formatter import OpenAIMultiAgentFormatter
+from agentscope.message import Msg, TextBlock
+from agentscope.model import OpenAIChatModel
+from agentscope.credential import OpenAICredential
+
+
+async def example_multiagent() -> None:
+    """Simulate a multi-agent conversation and let gpt-4.1 summarize it.
+
+    Alice and Bob discuss the weather, then a moderator (the model) is asked
+    to summarize the conversation.
+    """
+    formatter = OpenAIMultiAgentFormatter()
+
+    model = OpenAIChatModel(
+        credential=OpenAICredential(
+            api_key=os.environ["OPENAI_API_KEY"],
+        ),
+        model="gpt-4.1",
+        stream=True,
+        context_size=1_047_576,
+        formatter=formatter,
+    )
+
+    # Multi-agent conversation history between Alice and Bob
+    msgs = [
+        Msg(
+            name="system",
+            content=[
+                TextBlock(
+                    text="You are a helpful moderator. Summarize the "
+                    "conversation.",
+                ),
+            ],
+            role="system",
+        ),
+        Msg(
+            name="alice",
+            content=[
+                TextBlock(
+                    text="Hi Bob! What do you think about the weather today?",
+                ),
+            ],
+            role="user",
+        ),
+        Msg(
+            name="bob",
+            content=[
+                TextBlock(
+                    text="It's quite sunny and warm, Alice. Perfect for a "
+                    "walk!",
+                ),
+            ],
+            role="assistant",
+        ),
+        Msg(
+            name="alice",
+            content=[
+                TextBlock(text="Agreed! I might head to the park later."),
+            ],
+            role="user",
+        ),
+        Msg(
+            name="bob",
+            content=[
+                TextBlock(
+                    text="Great idea. I'll join you if I finish work early.",
+                ),
+            ],
+            role="assistant",
+        ),
+        Msg(
+            name="moderator",
+            content=[
+                TextBlock(
+                    text="Please summarize the conversation above in one "
+                    "sentence.",
+                ),
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Multi-Agent Formatter Call ===")
+    await stream_and_collect(await model(msgs))
+
+
+if __name__ == "__main__":
+    asyncio.run(example_multiagent())
diff --git a/scripts/model_examples/openai_chat_multiagent_multimodal.py b/scripts/model_examples/openai_chat_multiagent_multimodal.py
new file mode 100644
index 0000000..761f6b0
--- /dev/null
+++ b/scripts/model_examples/openai_chat_multiagent_multimodal.py
@@ -0,0 +1,90 @@
+# -*- coding: utf-8 -*-
+"""Example of OpenAI Chat model calls with MultiAgentFormatter and image
+input."""
+import asyncio
+import os
+
+from _utils import stream_and_collect
+from agentscope.formatter import OpenAIMultiAgentFormatter
+from agentscope.message import Msg, TextBlock, DataBlock, URLSource
+from agentscope.model import OpenAIChatModel
+from agentscope.credential import OpenAICredential
+
+TEST_IMAGE_URL = (
+    "https://help-static-aliyun-doc.aliyuncs.com/file-manage"
+    "-files/zh-CN/20241022/emyrja/dog_and_girl.jpeg"
+)
+
+
+async def example_multiagent_image_url() -> None:
+    """Multi-agent conversation where Alice shares an image for the group."""
+    formatter = OpenAIMultiAgentFormatter()
+
+    model = OpenAIChatModel(
+        credential=OpenAICredential(
+            api_key=os.environ["OPENAI_API_KEY"],
+        ),
+        model="gpt-4.1",
+        stream=True,
+        context_size=1_047_576,
+        formatter=formatter,
+    )
+
+    image_block = DataBlock(
+        source=URLSource(url=TEST_IMAGE_URL, media_type="image/jpeg"),
+    )
+
+    msgs = [
+        Msg(
+            name="system",
+            content=[
+                TextBlock(
+                    text=(
+                        "You are a helpful moderator in a group chat. "
+                        "Summarize what the image shows and what the "
+                        "participants said."
+                    ),
+                ),
+            ],
+            role="system",
+        ),
+        Msg(
+            name="alice",
+            content=[
+                TextBlock(
+                    text="Hey everyone, look at this cute photo I took!",
+                ),
+                image_block,
+            ],
+            role="user",
+        ),
+        Msg(
+            name="bob",
+            content=[
+                TextBlock(text="Aww, that's adorable! Where was this taken?"),
+            ],
+            role="assistant",
+        ),
+        Msg(
+            name="alice",
+            content=[TextBlock(text="At the local park yesterday.")],
+            role="user",
+        ),
+        Msg(
+            name="moderator",
+            content=[
+                TextBlock(
+                    text="Please summarize the image content and the "
+                    "conversation in one paragraph.",
+                ),
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Multi-Agent + Multimodal Call ===")
+    await stream_and_collect(await model(msgs))
+
+
+if __name__ == "__main__":
+    asyncio.run(example_multiagent_image_url())
diff --git a/scripts/model_examples/openai_chat_multimodal.py b/scripts/model_examples/openai_chat_multimodal.py
new file mode 100644
index 0000000..b4dcb48
--- /dev/null
+++ b/scripts/model_examples/openai_chat_multimodal.py
@@ -0,0 +1,194 @@
+# -*- coding: utf-8 -*-
+"""Example of OpenAI Chat model multimodal (vision) calls using DataBlock."""
+import asyncio
+import base64
+import os
+from pathlib import Path
+
+from _utils import stream_and_collect
+from agentscope.message import (
+    Msg,
+    TextBlock,
+    DataBlock,
+    URLSource,
+    Base64Source,
+)
+from agentscope.model import OpenAIChatModel
+from agentscope.credential import OpenAICredential
+
+# A publicly accessible test image (a simple cat photo)
+TEST_IMAGE_URL = (
+    "https://help-static-aliyun-doc.aliyuncs.com/file-manage"
+    "-files/zh-CN/20241022/emyrja/dog_and_girl.jpeg"
+)
+
+# A publicly accessible test audio
+TEST_AUDIO_URL = (
+    "https://help-static-aliyun-doc.aliyuncs.com/file-manage"
+    "-files/zh-CN/20250211/tixcef/cherry.wav"
+)
+
+
+async def example_image_url() -> None:
+    """Call gpt-4.1 with an image URL and ask what is in the image."""
+    model = OpenAIChatModel(
+        credential=OpenAICredential(
+            api_key=os.environ["OPENAI_API_KEY"],
+        ),
+        model="gpt-4.1",
+        stream=True,
+        context_size=1_047_576,
+    )
+
+    image_block = DataBlock(
+        source=URLSource(
+            url=TEST_IMAGE_URL,
+            media_type="image/jpeg",
+        ),
+    )
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[
+                TextBlock(
+                    text="What animal is in this image? Describe it briefly.",
+                ),
+                image_block,
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Multimodal Call (Image URL) ===")
+    await stream_and_collect(await model(msgs))
+
+
+def _build_model() -> OpenAIChatModel:
+    return OpenAIChatModel(
+        credential=OpenAICredential(api_key=os.environ["OPENAI_API_KEY"]),
+        model="gpt-4.1",
+        stream=True,
+        context_size=1_047_576,
+    )
+
+
+async def example_image_local_path() -> None:
+    """Call gpt-4.1 with a local image using a ``file://`` URL.
+
+    The formatter reads the file from disk and converts it to a base64 data
+     URI.
+    """
+    model = _build_model()
+
+    abs_path = str(Path(__file__).parent / "test.jpeg")
+    msgs = [
+        Msg(
+            name="user",
+            content=[
+                TextBlock(
+                    text="What is happening in this image? Describe it "
+                    "briefly.",
+                ),
+                DataBlock(
+                    source=URLSource(
+                        url=f"file://{abs_path}",
+                        media_type="image/jpeg",
+                    ),
+                ),
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Local Path Call (file://) ===")
+    await stream_and_collect(await model(msgs))
+
+
+async def example_image_base64() -> None:
+    """Call gpt-4.1 with a local image using explicit base64 encoding.
+
+    Use ``Base64Source`` when you already have the binary data in memory or
+    want full control over the encoding step.
+    """
+    model = _build_model()
+
+    with open(Path(__file__).parent / "test.jpeg", "rb") as f:
+        data = base64.b64encode(f.read()).decode("utf-8")
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[
+                TextBlock(
+                    text="What is happening in this image? Describe it "
+                    "briefly.",
+                ),
+                DataBlock(
+                    source=Base64Source(data=data, media_type="image/jpeg"),
+                ),
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Explicit Base64 Call ===")
+    await stream_and_collect(await model(msgs))
+
+
+async def example_audio() -> None:
+    """Call gpt-audio-mini with an audio URL.
+
+    Audio understanding requires an audio-capable model such as
+    ``gpt-audio-mini``.  The formatter converts the audio source
+    to the ``input_audio`` format expected by the Chat Completions API.
+    """
+    model = OpenAIChatModel(
+        credential=OpenAICredential(
+            api_key=os.environ["OPENAI_API_KEY"],
+        ),
+        model="gpt-audio-mini",
+        stream=True,
+    )
+
+    audio_block = DataBlock(
+        source=URLSource(
+            url=TEST_AUDIO_URL,
+            media_type="audio/wav",
+        ),
+    )
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[
+                TextBlock(text="What is being said in this audio clip?"),
+                audio_block,
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Multimodal Call (Audio Input and Output) ===")
+    response = await stream_and_collect(
+        await model(
+            msgs,
+            modalities=["text", "audio"],
+            audio={"voice": "alloy", "format": "pcm16"},
+        ),
+    )
+
+    # Save audio if present
+    for block in response.content:
+        if isinstance(block, DataBlock) and block.source.media_type.startswith(
+            "audio/",
+        ):
+            audio_bytes = base64.b64decode(block.source.data)
+            print(f"  Audio received: {len(audio_bytes)} bytes")
+
+
+if __name__ == "__main__":
+    asyncio.run(example_image_url())
+    asyncio.run(example_image_local_path())
+    asyncio.run(example_image_base64())
+    asyncio.run(example_audio())
diff --git a/scripts/model_examples/openai_response_call.py b/scripts/model_examples/openai_response_call.py
new file mode 100644
index 0000000..c93a309
--- /dev/null
+++ b/scripts/model_examples/openai_response_call.py
@@ -0,0 +1,199 @@
+# -*- coding: utf-8 -*-
+"""Examples of OpenAI Responses API model calls.
+
+The Responses API (vs Chat Completions API) provides first-class streaming
+events for reasoning/thinking content, making it a natural fit for reasoning
+models such as o3 and o4-mini.
+"""
+import asyncio
+import json
+import os
+
+from pydantic import BaseModel, Field
+
+from _utils import stream_and_collect
+from agentscope.message import (
+    Msg,
+    TextBlock,
+    ToolCallBlock,
+    ToolResultBlock,
+    ToolResultState,
+)
+from agentscope.model import OpenAIResponseModel
+from agentscope.credential import OpenAICredential
+from agentscope.tool import Toolkit, ToolChoice, FunctionTool
+
+
+# ---------------------------------------------------------------------------
+# Example 1: Simple user message (streaming)
+# ---------------------------------------------------------------------------
+
+
+async def example_simple_call() -> None:
+    """Call the OpenAI Response model with a simple text message."""
+    model = OpenAIResponseModel(
+        credential=OpenAICredential(
+            api_key=os.environ["OPENAI_API_KEY"],
+        ),
+        model="o1",
+        stream=True,
+        context_size=200_000,
+        parameters=OpenAIResponseModel.Parameters(
+            thinking_enable=True,
+            reasoning_effort="low",
+        ),
+    )
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[TextBlock(text="What is 1 + 1? Answer briefly.")],
+            role="user",
+        ),
+    ]
+
+    print("=== Simple Call ===")
+    await stream_and_collect(await model(msgs))
+
+
+# ---------------------------------------------------------------------------
+# Example 2: Tool calling (streaming)
+# ---------------------------------------------------------------------------
+
+
+def get_weather(city: str) -> str:
+    """Get the current weather for a city.
+
+    Args:
+        city: The city name to query the weather for.
+
+    Returns:
+        A description of the current weather.
+    """
+    return f"The weather in {city} is sunny and 25°C."
+
+
+async def example_tool_call() -> None:
+    """Call the OpenAI Response model with tool calling enabled."""
+    toolkit = Toolkit(tools=[FunctionTool(get_weather)])
+    tools = await toolkit.get_tool_schemas()
+
+    model = OpenAIResponseModel(
+        credential=OpenAICredential(
+            api_key=os.environ["OPENAI_API_KEY"],
+        ),
+        model="o1",
+        stream=True,
+        context_size=200_000,
+        parameters=OpenAIResponseModel.Parameters(
+            thinking_enable=True,
+            reasoning_effort="low",
+        ),
+    )
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[TextBlock(text="What is the weather in Hangzhou?")],
+            role="user",
+        ),
+    ]
+
+    # First call: model decides to call a tool
+    print("=== Tool Call - Round 1 ===")
+    response = await stream_and_collect(
+        await model(msgs, tools=tools, tool_choice=ToolChoice(mode="auto")),
+    )
+    print(response)
+
+    tool_calls = [b for b in response.content if isinstance(b, ToolCallBlock)]
+    if tool_calls:
+        tool_result_blocks = []
+        for tool_call in tool_calls:
+            args = json.loads(tool_call.input)
+            result = get_weather(**args)
+            tool_result_blocks.append(
+                ToolResultBlock(
+                    # Responses API: use call_id (call_xxx) so that the
+                    # function_call_output.call_id matches
+                    # function_call.call_id
+                    id=tool_call.call_id or tool_call.id,
+                    name=tool_call.name,
+                    output=result,
+                    state=ToolResultState.SUCCESS,
+                ),
+            )
+
+        assistant_msg = Msg(
+            name="assistant",
+            content=response.content,
+            role="assistant",
+        )
+        tool_result_msg = Msg(
+            name="tool",
+            content=tool_result_blocks,
+            role="assistant",
+        )
+        msgs = msgs + [assistant_msg, tool_result_msg]
+
+        print("=== Tool Call - Round 2 (Final) ===")
+        await stream_and_collect(await model(msgs))
+
+
+# ---------------------------------------------------------------------------
+# Example 3: Structured output
+# ---------------------------------------------------------------------------
+
+
+class MathSolution(BaseModel):
+    """Structured solution to a math problem."""
+
+    problem: str = Field(description="The original problem statement")
+    answer: float = Field(description="The final numeric answer")
+    steps: list[str] = Field(
+        description="Step-by-step reasoning leading to the answer",
+    )
+
+
+async def example_structured_output() -> None:
+    """Call the OpenAI Response model and force a structured (JSON) output."""
+    model = OpenAIResponseModel(
+        credential=OpenAICredential(
+            api_key=os.environ["OPENAI_API_KEY"],
+        ),
+        model="o1",
+        stream=True,
+        context_size=200_000,
+        parameters=OpenAIResponseModel.Parameters(
+            thinking_enable=True,
+            reasoning_effort="low",
+        ),
+    )
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[
+                TextBlock(
+                    text=(
+                        "Solve this: A train travels at 60 km/h for "
+                        "2.5 hours. How far does it travel in km?"
+                    ),
+                ),
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Structured Output ===")
+    response = await model.generate_structured_output(
+        msgs,
+        structured_model=MathSolution,
+    )
+    print(response.content)
+
+
+if __name__ == "__main__":
+    asyncio.run(example_simple_call())
+    asyncio.run(example_tool_call())
+    asyncio.run(example_structured_output())
diff --git a/scripts/model_examples/openai_response_multiagent.py b/scripts/model_examples/openai_response_multiagent.py
new file mode 100644
index 0000000..94f7de7
--- /dev/null
+++ b/scripts/model_examples/openai_response_multiagent.py
@@ -0,0 +1,102 @@
+# -*- coding: utf-8 -*-
+"""Example of OpenAI Responses API model calls with
+OpenAIResponseMultiAgentFormatter.
+
+The multi-agent formatter wraps prior conversation history in
+<history></history> tags, enabling the model to handle multi-agent
+conversations where more than one non-user agent is involved.
+"""
+import asyncio
+import os
+
+from _utils import stream_and_collect
+from agentscope.formatter import OpenAIResponseMultiAgentFormatter
+from agentscope.message import Msg, TextBlock
+from agentscope.model import OpenAIResponseModel
+from agentscope.credential import OpenAICredential
+
+
+async def example_multiagent() -> None:
+    """Simulate a multi-agent conversation and let gpt-4.1 (Responses API)
+    summarize it.
+
+    Alice and Bob discuss the weather, then a moderator (the model) is asked
+    to summarize the conversation.
+    """
+    formatter = OpenAIResponseMultiAgentFormatter()
+
+    model = OpenAIResponseModel(
+        credential=OpenAICredential(
+            api_key=os.environ["OPENAI_API_KEY"],
+        ),
+        model="gpt-4.1",
+        stream=True,
+        context_size=1_047_576,
+        formatter=formatter,
+    )
+
+    # Multi-agent conversation history between Alice and Bob
+    msgs = [
+        Msg(
+            name="system",
+            content=[
+                TextBlock(
+                    text="You are a helpful moderator. Summarize the "
+                    "conversation.",
+                ),
+            ],
+            role="system",
+        ),
+        Msg(
+            name="alice",
+            content=[
+                TextBlock(
+                    text="Hi Bob! What do you think about the weather today?",
+                ),
+            ],
+            role="user",
+        ),
+        Msg(
+            name="bob",
+            content=[
+                TextBlock(
+                    text="It's quite sunny and warm, Alice. Perfect for a "
+                    "walk!",
+                ),
+            ],
+            role="assistant",
+        ),
+        Msg(
+            name="alice",
+            content=[
+                TextBlock(text="Agreed! I might head to the park later."),
+            ],
+            role="user",
+        ),
+        Msg(
+            name="bob",
+            content=[
+                TextBlock(
+                    text="Great idea. I'll join you if I finish work early.",
+                ),
+            ],
+            role="assistant",
+        ),
+        Msg(
+            name="moderator",
+            content=[
+                TextBlock(
+                    text="Please summarize the conversation above in one "
+                    "sentence.",
+                ),
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Multi-Agent Formatter Call ===")
+    await stream_and_collect(await model(msgs))
+
+
+if __name__ == "__main__":
+    asyncio.run(example_multiagent())
diff --git a/scripts/model_examples/openai_response_multiagent_multimodal.py b/scripts/model_examples/openai_response_multiagent_multimodal.py
new file mode 100644
index 0000000..3754145
--- /dev/null
+++ b/scripts/model_examples/openai_response_multiagent_multimodal.py
@@ -0,0 +1,90 @@
+# -*- coding: utf-8 -*-
+"""Example of OpenAI Responses API model calls with MultiAgentFormatter and
+image input."""
+import asyncio
+import os
+
+from _utils import stream_and_collect
+from agentscope.formatter import OpenAIResponseMultiAgentFormatter
+from agentscope.message import Msg, TextBlock, DataBlock, URLSource
+from agentscope.model import OpenAIResponseModel
+from agentscope.credential import OpenAICredential
+
+TEST_IMAGE_URL = (
+    "https://help-static-aliyun-doc.aliyuncs.com/file-manage"
+    "-files/zh-CN/20241022/emyrja/dog_and_girl.jpeg"
+)
+
+
+async def example_multiagent_image_url() -> None:
+    """Multi-agent conversation where Alice shares an image for the group."""
+    formatter = OpenAIResponseMultiAgentFormatter()
+
+    model = OpenAIResponseModel(
+        credential=OpenAICredential(
+            api_key=os.environ["OPENAI_API_KEY"],
+        ),
+        model="gpt-4.1",
+        stream=True,
+        context_size=1_047_576,
+        formatter=formatter,
+    )
+
+    image_block = DataBlock(
+        source=URLSource(url=TEST_IMAGE_URL, media_type="image/jpeg"),
+    )
+
+    msgs = [
+        Msg(
+            name="system",
+            content=[
+                TextBlock(
+                    text=(
+                        "You are a helpful moderator in a group chat. "
+                        "Summarize what the image shows and what the "
+                        "participants said."
+                    ),
+                ),
+            ],
+            role="system",
+        ),
+        Msg(
+            name="alice",
+            content=[
+                TextBlock(
+                    text="Hey everyone, look at this cute photo I took!",
+                ),
+                image_block,
+            ],
+            role="user",
+        ),
+        Msg(
+            name="bob",
+            content=[
+                TextBlock(text="Aww, that's adorable! Where was this taken?"),
+            ],
+            role="assistant",
+        ),
+        Msg(
+            name="alice",
+            content=[TextBlock(text="At the local park yesterday.")],
+            role="user",
+        ),
+        Msg(
+            name="moderator",
+            content=[
+                TextBlock(
+                    text="Please summarize the image content and the "
+                    "conversation in one paragraph.",
+                ),
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Multi-Agent + Multimodal Call ===")
+    await stream_and_collect(await model(msgs))
+
+
+if __name__ == "__main__":
+    asyncio.run(example_multiagent_image_url())
diff --git a/scripts/model_examples/openai_response_multimodal.py b/scripts/model_examples/openai_response_multimodal.py
new file mode 100644
index 0000000..f0a5be8
--- /dev/null
+++ b/scripts/model_examples/openai_response_multimodal.py
@@ -0,0 +1,138 @@
+# -*- coding: utf-8 -*-
+"""Example of OpenAI Responses API model multimodal (vision) calls using
+DataBlock."""
+import asyncio
+import base64
+import os
+from pathlib import Path
+
+from _utils import stream_and_collect
+from agentscope.message import (
+    Msg,
+    TextBlock,
+    DataBlock,
+    URLSource,
+    Base64Source,
+)
+from agentscope.model import OpenAIResponseModel
+from agentscope.credential import OpenAICredential
+
+# A publicly accessible test image (a simple cat photo)
+TEST_IMAGE_URL = (
+    "https://help-static-aliyun-doc.aliyuncs.com/file-manage"
+    "-files/zh-CN/20241022/emyrja/dog_and_girl.jpeg"
+)
+
+
+async def example_image_url() -> None:
+    """Call gpt-4.1 (Responses API) with an image URL and ask what is in
+    the image."""
+    model = OpenAIResponseModel(
+        credential=OpenAICredential(
+            api_key=os.environ["OPENAI_API_KEY"],
+        ),
+        model="gpt-4.1",
+        stream=True,
+        context_size=1_047_576,
+    )
+
+    image_block = DataBlock(
+        source=URLSource(
+            url=TEST_IMAGE_URL,
+            media_type="image/jpeg",
+        ),
+    )
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[
+                TextBlock(
+                    text="What animal is in this image? Describe it briefly.",
+                ),
+                image_block,
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Multimodal Call (Image URL) ===")
+    await stream_and_collect(await model(msgs))
+
+
+def _build_model() -> OpenAIResponseModel:
+    return OpenAIResponseModel(
+        credential=OpenAICredential(api_key=os.environ["OPENAI_API_KEY"]),
+        model="gpt-4.1",
+        stream=True,
+        context_size=1_047_576,
+    )
+
+
+async def example_image_local_path() -> None:
+    """Call gpt-4.1 (Responses API) with a local image using a ``file://`` URL.
+
+    The formatter reads the file from disk and converts it to a base64 data
+     URI.
+    """
+    model = _build_model()
+
+    abs_path = str(Path(__file__).parent / "test.jpeg")
+    msgs = [
+        Msg(
+            name="user",
+            content=[
+                TextBlock(
+                    text="What is happening in this image? Describe it "
+                    "briefly.",
+                ),
+                DataBlock(
+                    source=URLSource(
+                        url=f"file://{abs_path}",
+                        media_type="image/jpeg",
+                    ),
+                ),
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Local Path Call (file://) ===")
+    await stream_and_collect(await model(msgs))
+
+
+async def example_image_base64() -> None:
+    """Call gpt-4.1 (Responses API) with a local image using explicit base64.
+
+    Use ``Base64Source`` when you already have the binary data in memory or
+    want full control over the encoding step.
+    """
+    model = _build_model()
+
+    with open(Path(__file__).parent / "test.jpeg", "rb") as f:
+        data = base64.b64encode(f.read()).decode("utf-8")
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[
+                TextBlock(
+                    text="What is happening in this image? Describe it "
+                    "briefly.",
+                ),
+                DataBlock(
+                    source=Base64Source(data=data, media_type="image/jpeg"),
+                ),
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Explicit Base64 Call ===")
+    await stream_and_collect(await model(msgs))
+
+
+if __name__ == "__main__":
+    asyncio.run(example_image_url())
+    asyncio.run(example_image_local_path())
+    asyncio.run(example_image_base64())
diff --git a/scripts/model_examples/run_tests.py b/scripts/model_examples/run_tests.py
new file mode 100644
index 0000000..3a1643e
--- /dev/null
+++ b/scripts/model_examples/run_tests.py
@@ -0,0 +1,585 @@
+# -*- coding: utf-8 -*-
+"""Unified test runner for AgentScope model scripts.
+
+Automatically reads API keys from environment variables and only runs tests
+for providers whose keys are present. Supports fine-grained control over
+which providers and test types to run.
+
+Usage examples:
+    # Run all available tests (auto-detected from env vars)
+    python scripts/model_examples/run_tests.py
+
+    # Run only specific providers
+    python scripts/model_examples/run_tests.py --providers openai_chat,
+    anthropic,gemini
+
+    # Run only specific test types
+    python scripts/model_examples/run_tests.py --tests call,multiagent
+
+    # Combine: only call tests for openai and dashscope
+    python scripts/model_examples/run_tests.py --providers openai_chat,
+    dashscope --tests call
+
+    # List all providers and their env var / availability status
+    python scripts/model_examples/run_tests.py --list
+
+    # Include ollama even if server may not be running
+    python scripts/model_examples/run_tests.py --providers ollama
+
+    # Set a per-test timeout (seconds, default 120)
+    python scripts/model_examples/run_tests.py --timeout 60
+
+    # Stream each script's output to the terminal (default: suppressed,
+    shown only on failure)
+    python scripts/model_examples/run_tests.py --verbose
+"""
+import argparse
+import os
+import subprocess
+import sys
+import textwrap
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+# ---------------------------------------------------------------------------
+# Provider definitions
+# ---------------------------------------------------------------------------
+
+SCRIPTS_DIR = Path(__file__).parent
+
+
+@dataclass
+class Provider:
+    """Metadata for a model provider."""
+
+    name: str
+    env_var: Optional[str]  # None for local providers (e.g. Ollama)
+    file_prefix: str  # e.g. "openai_chat_model"
+    supported_tests: list[str] = field(default_factory=list)
+    description: str = ""
+
+    def is_available(self) -> bool:
+        """Return True if the provider's credentials are present."""
+        if self.env_var is None:
+            # Ollama: check if server is reachable
+            return _ollama_is_running()
+        return bool(os.environ.get(self.env_var, "").strip())
+
+    def script_path(self, test_type: str) -> Optional[Path]:
+        """Return the script path for the given test type, or None if it
+        doesn't exist."""
+        path = SCRIPTS_DIR / f"{self.file_prefix}_{test_type}.py"
+        return path if path.exists() else None
+
+
+def _ollama_is_running() -> bool:
+    """Check whether an Ollama server is reachable."""
+    import urllib.request
+    import urllib.error
+
+    host = os.environ.get("OLLAMA_HOST", "http://localhost:11434")
+    try:
+        with urllib.request.urlopen(f"{host}/api/tags", timeout=3):
+            pass
+        return True
+    except Exception:
+        return False
+
+
+ALL_PROVIDERS: list[Provider] = [
+    Provider(
+        name="openai_chat",
+        env_var="OPENAI_API_KEY",
+        file_prefix="openai_chat",
+        supported_tests=[
+            "call",
+            "multiagent",
+            "multimodal",
+            "multiagent_multimodal",
+        ],
+        description="OpenAI Chat Completions API (gpt-4.1, etc.)",
+    ),
+    Provider(
+        name="openai_response",
+        env_var="OPENAI_API_KEY",
+        file_prefix="openai_response",
+        supported_tests=[
+            "call",
+            "multiagent",
+            "multimodal",
+            "multiagent_multimodal",
+        ],
+        description="OpenAI Responses API (o1, o3, etc.)",
+    ),
+    Provider(
+        name="anthropic",
+        env_var="ANTHROPIC_API_KEY",
+        file_prefix="anthropic",
+        supported_tests=[
+            "call",
+            "multiagent",
+            "multimodal",
+            "multiagent_multimodal",
+        ],
+        description="Anthropic Claude models",
+    ),
+    Provider(
+        name="dashscope",
+        env_var="DASHSCOPE_API_KEY",
+        file_prefix="dashscope",
+        supported_tests=[
+            "call",
+            "multiagent",
+            "multimodal",
+            "multiagent_multimodal",
+        ],
+        description="Alibaba DashScope / Qwen models",
+    ),
+    Provider(
+        name="deepseek",
+        env_var="DEEPSEEK_API_KEY",
+        file_prefix="deepseek",
+        supported_tests=["call", "multiagent"],
+        description="DeepSeek models (no multimodal support)",
+    ),
+    Provider(
+        name="gemini",
+        env_var="GEMINI_API_KEY",
+        file_prefix="gemini",
+        supported_tests=[
+            "call",
+            "multiagent",
+            "multimodal",
+            "multiagent_multimodal",
+        ],
+        description="Google Gemini models",
+    ),
+    Provider(
+        name="moonshot",
+        env_var="MOONSHOT_API_KEY",
+        file_prefix="moonshot",
+        supported_tests=[
+            "call",
+            "multiagent",
+            "multimodal",
+            "multiagent_multimodal",
+        ],
+        description="Moonshot AI (Kimi) models",
+    ),
+    Provider(
+        name="xai",
+        env_var="XAI_API_KEY",
+        file_prefix="xai",
+        supported_tests=[
+            "call",
+            "multiagent",
+            "multimodal",
+            "multiagent_multimodal",
+        ],
+        description="xAI Grok models",
+    ),
+    Provider(
+        name="ollama",
+        env_var=None,
+        file_prefix="ollama",
+        supported_tests=[
+            "call",
+            "multiagent",
+            "multimodal",
+            "multiagent_multimodal",
+        ],
+        description="Ollama local models (requires running server)",
+    ),
+]
+
+PROVIDER_MAP: dict[str, Provider] = {p.name: p for p in ALL_PROVIDERS}
+ALL_TEST_TYPES = ["call", "multiagent", "multimodal", "multiagent_multimodal"]
+
+# ---------------------------------------------------------------------------
+# Result tracking
+# ---------------------------------------------------------------------------
+
+PASS = "PASS"
+FAIL = "FAIL"
+SKIP = "SKIP"
+
+COLOR_GREEN = "\033[92m"
+COLOR_RED = "\033[91m"
+COLOR_YELLOW = "\033[93m"
+COLOR_BLUE = "\033[94m"
+COLOR_RESET = "\033[0m"
+COLOR_BOLD = "\033[1m"
+
+
+def _color(text: str, color: str) -> str:
+    """Wrap *text* in ANSI *color* escape codes when stdout is a TTY."""
+    if sys.stdout.isatty():
+        return f"{color}{text}{COLOR_RESET}"
+    return text
+
+
+@dataclass
+class TestResult:
+    """Result of a single test run."""
+
+    provider: str
+    test_type: str
+    status: str  # PASS / FAIL / SKIP
+    reason: str = ""
+    duration: float = 0.0
+    output: str = ""  # captured stdout+stderr (only when not streaming)
+
+
+# ---------------------------------------------------------------------------
+# Core runner
+# ---------------------------------------------------------------------------
+
+
+def run_script(
+    script_path: Path,
+    timeout: int,
+    verbose: bool,
+) -> tuple[str, float, str]:
+    """Run a script as a subprocess; return (status, elapsed_seconds, output).
+
+    In verbose mode the subprocess output streams directly to the terminal and
+    the returned output string is empty.  In quiet mode (default) output is
+    captured; it is printed only when the test fails.
+    """
+    start = time.monotonic()
+    try:
+        if verbose:
+            result = subprocess.run(
+                [sys.executable, str(script_path)],
+                timeout=timeout,
+                text=True,
+                check=False,
+            )
+            captured = ""
+        else:
+            result = subprocess.run(
+                [sys.executable, str(script_path)],
+                timeout=timeout,
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+            captured = (result.stdout or "") + (result.stderr or "")
+        elapsed = time.monotonic() - start
+        status = PASS if result.returncode == 0 else FAIL
+        return status, elapsed, captured
+    except subprocess.TimeoutExpired:
+        elapsed = time.monotonic() - start
+        return FAIL, elapsed, f"[Timed out after {timeout}s]"
+
+
+def print_header(text: str) -> None:
+    """Print a prominent section header separated by a full-width rule."""
+    width = 72
+    print()
+    print(_color("=" * width, COLOR_BLUE))
+    print(_color(f"  {text}", COLOR_BOLD))
+    print(_color("=" * width, COLOR_BLUE))
+
+
+def print_section(text: str) -> None:
+    """Print a lightweight subsection heading."""
+    print()
+    print(_color(f"--- {text} ---", COLOR_BLUE))
+
+
+def run_all(
+    providers: list[str],
+    test_types: list[str],
+    timeout: int,
+    verbose: bool,
+) -> list[TestResult]:
+    """Run every requested test type for each provider and return all results.
+
+    Providers whose credentials are absent are skipped automatically.
+    For each (provider, test_type) pair the corresponding script file is
+    located and executed as a subprocess.
+
+    Args:
+        providers: Ordered list of provider names to evaluate.
+        test_types: List of test-type suffixes to run per provider.
+        timeout: Per-script timeout in seconds.
+        verbose: When True, stream subprocess output directly to the terminal.
+            When False, capture it and print only on failure.
+
+    Returns:
+        A list of :class:`TestResult` objects, one per (provider, test_type).
+    """
+    results: list[TestResult] = []
+
+    for pname in providers:
+        provider = PROVIDER_MAP[pname]
+
+        available = provider.is_available()
+        if not available:
+            if provider.env_var:
+                reason = f"env var {provider.env_var} not set"
+            else:
+                reason = "Ollama server not reachable"
+            for ttype in test_types:
+                results.append(TestResult(pname, ttype, SKIP, reason))
+            print_section(
+                f"{pname.upper()}  [{_color('SKIP', COLOR_YELLOW)}] —"
+                f" {reason}",
+            )
+            continue
+
+        print_section(
+            f"{pname.upper()} — running tests: {', '.join(test_types)}",
+        )
+
+        for ttype in test_types:
+            if ttype not in provider.supported_tests:
+                results.append(
+                    TestResult(
+                        pname,
+                        ttype,
+                        SKIP,
+                        f"not supported by {pname}",
+                    ),
+                )
+                print(
+                    f"  [{_color('SKIP', COLOR_YELLOW)}] {ttype:30s}  (not "
+                    f"supported)",
+                )
+                continue
+
+            script = provider.script_path(ttype)
+            if script is None:
+                results.append(
+                    TestResult(pname, ttype, SKIP, "script not found"),
+                )
+                print(
+                    f"  [{_color('SKIP', COLOR_YELLOW)}] {ttype:30s}  ("
+                    f"script not found)",
+                )
+                continue
+
+            print(f"\n  >>> {script.name}")
+            status, elapsed, captured = run_script(script, timeout, verbose)
+            elapsed_str = f"{elapsed:.1f}s"
+
+            if status == PASS:
+                label = _color(PASS, COLOR_GREEN)
+            else:
+                label = _color(FAIL, COLOR_RED)
+                # Always show captured output on failure (even in quiet mode)
+                if captured and not verbose:
+                    print(captured, end="")
+
+            print(f"  [{label}] {ttype:30s}  {elapsed_str}")
+            results.append(
+                TestResult(
+                    pname,
+                    ttype,
+                    status,
+                    duration=elapsed,
+                    output=captured,
+                ),
+            )
+
+    return results
+
+
+# ---------------------------------------------------------------------------
+# Summary table
+# ---------------------------------------------------------------------------
+
+
+def print_summary(results: list[TestResult]) -> None:
+    """Print a formatted table summarising every test result.
+
+    Args:
+        results: All :class:`TestResult` objects produced by :func:`run_all`.
+    """
+    print_header("TEST SUMMARY")
+
+    passes = [r for r in results if r.status == PASS]
+    fails = [r for r in results if r.status == FAIL]
+    skips = [r for r in results if r.status == SKIP]
+
+    col_p = f"{len(passes):>3}"
+    col_f = f"{len(fails):>3}"
+    col_s = f"{len(skips):>3}"
+
+    print(f"  {'Provider':<22} {'Test Type':<28} {'Status':<8} {'Time':>7}")
+    print(f"  {'-'*22} {'-'*28} {'-'*8} {'-'*7}")
+    for r in results:
+        if r.status == PASS:
+            status_str = _color(r.status, COLOR_GREEN)
+        elif r.status == FAIL:
+            status_str = _color(r.status, COLOR_RED)
+        else:
+            status_str = _color(r.status, COLOR_YELLOW)
+        time_str = (
+            f"{r.duration:.1f}s"
+            if r.duration
+            else (r.reason[:20] if r.reason else "")
+        )
+        print(
+            f"  {r.provider:<22} {r.test_type:<28} {status_str:<18}"
+            f" {time_str:>7}",
+        )
+
+    print()
+    total = len(results)
+    summary_line = (
+        f"  Total: {total}  |  "
+        f"{_color('PASS', COLOR_GREEN)}: {col_p}  |  "
+        f"{_color('FAIL', COLOR_RED)}: {col_f}  |  "
+        f"{_color('SKIP', COLOR_YELLOW)}: {col_s}"
+    )
+    print(summary_line)
+    print()
+
+    if fails:
+        print(_color("  Failed tests:", COLOR_RED))
+        for r in fails:
+            print(f"    - {r.provider} / {r.test_type}")
+        print()
+
+
+# ---------------------------------------------------------------------------
+# --list mode
+# ---------------------------------------------------------------------------
+
+
+def print_provider_list() -> None:
+    """Print a status table of all registered providers and their
+    availability."""
+    print_header("PROVIDER STATUS")
+    print(f"  {'Provider':<22} {'Env Var':<25} {'Available':<12} Description")
+    print(f"  {'-'*22} {'-'*25} {'-'*12} {'-'*30}")
+    for p in ALL_PROVIDERS:
+        avail = p.is_available()
+        avail_str = (
+            _color("YES", COLOR_GREEN) if avail else _color("NO", COLOR_RED)
+        )
+        env_str = p.env_var or "(local — ping server)"
+        tests_str = ", ".join(p.supported_tests)
+        print(f"  {p.name:<22} {env_str:<25} {avail_str:<21} {p.description}")
+        print(f"  {'':22} {'Supported tests:':<25} {tests_str}")
+        print()
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Construct and return the CLI argument parser."""
+    parser = argparse.ArgumentParser(
+        description=textwrap.dedent(__doc__),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "--providers",
+        "-p",
+        metavar="NAME[,NAME...]",
+        default=None,
+        help=(
+            "Comma-separated list of providers to test "
+            f"(default: all). Available: {', '.join(PROVIDER_MAP)}"
+        ),
+    )
+    parser.add_argument(
+        "--tests",
+        "-t",
+        metavar="TYPE[,TYPE...]",
+        default=None,
+        help=(
+            "Comma-separated list of test types to run "
+            f"(default: all). Available: {', '.join(ALL_TEST_TYPES)}"
+        ),
+    )
+    parser.add_argument(
+        "--timeout",
+        type=int,
+        default=120,
+        metavar="SECONDS",
+        help="Per-script timeout in seconds (default: 120)",
+    )
+    parser.add_argument(
+        "--list",
+        "-l",
+        action="store_true",
+        help="List all providers with their env var and availability "
+        "status, then exit",
+    )
+    parser.add_argument(
+        "--verbose",
+        "-v",
+        action="store_true",
+        help=(
+            "Stream each script's output to the terminal in real time. "
+            "By default output is suppressed and only shown when a test fails."
+        ),
+    )
+    return parser
+
+
+def main() -> int:
+    """Entry point: parse arguments, run tests, and return an exit code.
+
+    Returns:
+        0 if all executed tests passed (or were skipped); 1 if any test failed.
+    """
+    parser = build_parser()
+    args = parser.parse_args()
+
+    if args.list:
+        print_provider_list()
+        return 0
+
+    # Resolve providers
+    if args.providers:
+        requested = [p.strip() for p in args.providers.split(",") if p.strip()]
+        unknown = [p for p in requested if p not in PROVIDER_MAP]
+        if unknown:
+            print(f"Unknown providers: {', '.join(unknown)}")
+            print(f"Available: {', '.join(PROVIDER_MAP)}")
+            return 1
+        providers = requested
+    else:
+        providers = list(PROVIDER_MAP)
+
+    # Resolve test types
+    if args.tests:
+        requested_tests = [
+            t.strip() for t in args.tests.split(",") if t.strip()
+        ]
+        unknown_tests = [t for t in requested_tests if t not in ALL_TEST_TYPES]
+        if unknown_tests:
+            print(f"Unknown test types: {', '.join(unknown_tests)}")
+            print(f"Available: {', '.join(ALL_TEST_TYPES)}")
+            return 1
+        test_types = requested_tests
+    else:
+        test_types = ALL_TEST_TYPES
+
+    print_header(
+        f"AgentScope Model Tests  |  providers: {len(providers)}  |  test "
+        f"types: {len(test_types)}",
+    )
+    print(f"  Providers : {', '.join(providers)}")
+    print(f"  Test types: {', '.join(test_types)}")
+    print(f"  Timeout   : {args.timeout}s per script")
+
+    results = run_all(providers, test_types, args.timeout, args.verbose)
+    print_summary(results)
+
+    # Exit with non-zero if any test failed
+    failed = any(r.status == FAIL for r in results)
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/scripts/model_examples/test.jpeg b/scripts/model_examples/test.jpeg
new file mode 100644
index 0000000..9fdc040
Binary files /dev/null and b/scripts/model_examples/test.jpeg differ
diff --git a/scripts/model_examples/xai_call.py b/scripts/model_examples/xai_call.py
new file mode 100644
index 0000000..2d44e4d
--- /dev/null
+++ b/scripts/model_examples/xai_call.py
@@ -0,0 +1,195 @@
+# -*- coding: utf-8 -*-
+"""Examples of xAI Grok model calls using the official xai_sdk gRPC client.
+
+Unlike the OpenAI-compatible approach, the xai_sdk provides native access to
+xAI-specific features such as server-side agentic tools (web search, X search,
+code execution) and extended reasoning control.
+"""
+import asyncio
+import json
+import os
+
+from pydantic import BaseModel, Field
+
+from _utils import stream_and_collect
+from agentscope.message import (
+    Msg,
+    TextBlock,
+    ToolCallBlock,
+    ToolResultBlock,
+    ToolResultState,
+)
+from agentscope.model import XAIChatModel
+from agentscope.credential import XAICredential
+from agentscope.tool import Toolkit, ToolChoice, FunctionTool
+
+
+# ---------------------------------------------------------------------------
+# Example 1: Simple user message (streaming, with reasoning)
+# ---------------------------------------------------------------------------
+
+
+async def example_simple_call() -> None:
+    """Call the xAI reasoning model with a simple text message."""
+    model = XAIChatModel(
+        credential=XAICredential(
+            api_key=os.environ["XAI_API_KEY"],
+        ),
+        model="grok-3-mini",
+        stream=True,
+        context_size=131_072,
+        parameters=XAIChatModel.Parameters(
+            thinking_enable=True,
+            reasoning_effort="low",
+        ),
+    )
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[TextBlock(text="What is 1 + 1? Answer briefly.")],
+            role="user",
+        ),
+    ]
+
+    print("=== Simple Call ===")
+    await stream_and_collect(await model(msgs))
+
+
+# ---------------------------------------------------------------------------
+# Example 2: Tool calling (streaming)
+# ---------------------------------------------------------------------------
+
+
+def get_weather(city: str) -> str:
+    """Get the current weather for a city.
+
+    Args:
+        city: The city name to query the weather for.
+
+    Returns:
+        A description of the current weather.
+    """
+    return f"The weather in {city} is sunny and 25°C."
+
+
+async def example_tool_call() -> None:
+    """Call the Grok model with tool calling enabled.
+
+    Uses grok-4.3, xAI's flagship mainstream model.
+    """
+    toolkit = Toolkit(tools=[FunctionTool(get_weather)])
+    tools = await toolkit.get_tool_schemas()
+
+    model = XAIChatModel(
+        credential=XAICredential(
+            api_key=os.environ["XAI_API_KEY"],
+        ),
+        model="grok-4.3",
+        stream=True,
+        context_size=1_000_000,
+    )
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[TextBlock(text="What is the weather in Wuhan?")],
+            role="user",
+        ),
+    ]
+
+    # First call: model decides to call a tool
+    print("=== Tool Call - Round 1 ===")
+    response = await stream_and_collect(
+        await model(msgs, tools=tools, tool_choice=ToolChoice(mode="auto")),
+    )
+    print(response)
+
+    tool_calls = [b for b in response.content if isinstance(b, ToolCallBlock)]
+    if tool_calls:
+        tool_result_blocks = []
+        for tool_call in tool_calls:
+            args = json.loads(tool_call.input)
+            result = get_weather(**args)
+            tool_result_blocks.append(
+                ToolResultBlock(
+                    id=tool_call.id,
+                    name=tool_call.name,
+                    output=result,
+                    state=ToolResultState.SUCCESS,
+                ),
+            )
+
+        assistant_msg = Msg(
+            name="assistant",
+            content=response.content,
+            role="assistant",
+        )
+        tool_result_msg = Msg(
+            name="tool",
+            content=tool_result_blocks,
+            role="assistant",
+        )
+        msgs = msgs + [assistant_msg, tool_result_msg]
+
+        print("=== Tool Call - Round 2 (Final) ===")
+        await stream_and_collect(await model(msgs))
+
+
+# ---------------------------------------------------------------------------
+# Example 3: Structured output
+# ---------------------------------------------------------------------------
+
+
+class MathSolution(BaseModel):
+    """Structured solution to a math problem."""
+
+    problem: str = Field(description="The original problem statement")
+    answer: float = Field(description="The final numeric answer")
+    steps: list[str] = Field(
+        description="Step-by-step reasoning leading to the answer",
+    )
+
+
+async def example_structured_output() -> None:
+    """Call the xAI reasoning model and force a structured (JSON) output."""
+    model = XAIChatModel(
+        credential=XAICredential(
+            api_key=os.environ["XAI_API_KEY"],
+        ),
+        model="grok-3-mini",
+        stream=True,
+        context_size=131_072,
+        parameters=XAIChatModel.Parameters(
+            thinking_enable=True,
+            reasoning_effort="low",
+        ),
+    )
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[
+                TextBlock(
+                    text=(
+                        "Solve this: A train travels at 60 km/h for "
+                        "2.5 hours. How far does it travel in km?"
+                    ),
+                ),
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Structured Output ===")
+    response = await model.generate_structured_output(
+        msgs,
+        structured_model=MathSolution,
+    )
+    print(response.content)
+
+
+if __name__ == "__main__":
+    asyncio.run(example_simple_call())
+    asyncio.run(example_tool_call())
+    asyncio.run(example_structured_output())
diff --git a/scripts/model_examples/xai_multiagent.py b/scripts/model_examples/xai_multiagent.py
new file mode 100644
index 0000000..a4573f4
--- /dev/null
+++ b/scripts/model_examples/xai_multiagent.py
@@ -0,0 +1,101 @@
+# -*- coding: utf-8 -*-
+"""Example of Grok (xAI) model calls with XAIMultiAgentFormatter.
+
+The multi-agent formatter wraps prior conversation history in
+<history></history> tags within a user protobuf message, enabling the xAI
+Grok model to handle multi-agent conversations where more than one non-user
+agent is involved.
+"""
+import asyncio
+import os
+
+from _utils import stream_and_collect
+from agentscope.formatter import XAIMultiAgentFormatter
+from agentscope.message import Msg, TextBlock
+from agentscope.model import XAIChatModel
+from agentscope.credential import XAICredential
+
+
+async def example_multiagent() -> None:
+    """Simulate a multi-agent conversation and let grok-4.3 summarize it.
+
+    Alice and Bob discuss the weather, then a moderator (the model) is asked
+    to summarize the conversation.
+    """
+    formatter = XAIMultiAgentFormatter()
+
+    model = XAIChatModel(
+        credential=XAICredential(
+            api_key=os.environ["XAI_API_KEY"],
+        ),
+        model="grok-4.3",
+        stream=True,
+        context_size=1_000_000,
+        formatter=formatter,
+    )
+
+    # Multi-agent conversation history between Alice and Bob
+    msgs = [
+        Msg(
+            name="system",
+            content=[
+                TextBlock(
+                    text="You are a helpful moderator. Summarize the "
+                    "conversation.",
+                ),
+            ],
+            role="system",
+        ),
+        Msg(
+            name="alice",
+            content=[
+                TextBlock(
+                    text="Hi Bob! What do you think about the weather today?",
+                ),
+            ],
+            role="user",
+        ),
+        Msg(
+            name="bob",
+            content=[
+                TextBlock(
+                    text="It's quite sunny and warm, Alice. Perfect for a "
+                    "walk!",
+                ),
+            ],
+            role="assistant",
+        ),
+        Msg(
+            name="alice",
+            content=[
+                TextBlock(text="Agreed! I might head to the park later."),
+            ],
+            role="user",
+        ),
+        Msg(
+            name="bob",
+            content=[
+                TextBlock(
+                    text="Great idea. I'll join you if I finish work early.",
+                ),
+            ],
+            role="assistant",
+        ),
+        Msg(
+            name="moderator",
+            content=[
+                TextBlock(
+                    text="Please summarize the conversation above in one "
+                    "sentence.",
+                ),
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Multi-Agent Formatter Call ===")
+    await stream_and_collect(await model(msgs))
+
+
+if __name__ == "__main__":
+    asyncio.run(example_multiagent())
diff --git a/scripts/model_examples/xai_multiagent_multimodal.py b/scripts/model_examples/xai_multiagent_multimodal.py
new file mode 100644
index 0000000..66bcd60
--- /dev/null
+++ b/scripts/model_examples/xai_multiagent_multimodal.py
@@ -0,0 +1,93 @@
+# -*- coding: utf-8 -*-
+"""Example of Grok (xAI) model calls with XAIMultiAgentFormatter and image
+input.
+
+Note: Vision (image) input requires grok-4.3 or above.
+"""
+import asyncio
+import os
+
+from _utils import stream_and_collect
+from agentscope.formatter import XAIMultiAgentFormatter
+from agentscope.message import Msg, TextBlock, DataBlock, URLSource
+from agentscope.model import XAIChatModel
+from agentscope.credential import XAICredential
+
+TEST_IMAGE_URL = (
+    "https://help-static-aliyun-doc.aliyuncs.com/file-manage"
+    "-files/zh-CN/20241022/emyrja/dog_and_girl.jpeg"
+)
+
+
+async def example_multiagent_image_url() -> None:
+    """Multi-agent conversation where Alice shares an image for the group."""
+    formatter = XAIMultiAgentFormatter()
+
+    model = XAIChatModel(
+        credential=XAICredential(
+            api_key=os.environ["XAI_API_KEY"],
+        ),
+        model="grok-4.3",
+        stream=True,
+        context_size=1_000_000,
+        formatter=formatter,
+    )
+
+    image_block = DataBlock(
+        source=URLSource(url=TEST_IMAGE_URL, media_type="image/jpeg"),
+    )
+
+    msgs = [
+        Msg(
+            name="system",
+            content=[
+                TextBlock(
+                    text=(
+                        "You are a helpful moderator in a group chat. "
+                        "Summarize what the image shows and what the "
+                        "participants said."
+                    ),
+                ),
+            ],
+            role="system",
+        ),
+        Msg(
+            name="alice",
+            content=[
+                TextBlock(
+                    text="Hey everyone, look at this cute photo I took!",
+                ),
+                image_block,
+            ],
+            role="user",
+        ),
+        Msg(
+            name="bob",
+            content=[
+                TextBlock(text="Aww, that's adorable! Where was this taken?"),
+            ],
+            role="assistant",
+        ),
+        Msg(
+            name="alice",
+            content=[TextBlock(text="At the local park yesterday.")],
+            role="user",
+        ),
+        Msg(
+            name="moderator",
+            content=[
+                TextBlock(
+                    text="Please summarize the image content and the "
+                    "conversation in one paragraph.",
+                ),
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Multi-Agent + Multimodal Call ===")
+    await stream_and_collect(await model(msgs))
+
+
+if __name__ == "__main__":
+    asyncio.run(example_multiagent_image_url())
diff --git a/scripts/model_examples/xai_multimodal.py b/scripts/model_examples/xai_multimodal.py
new file mode 100644
index 0000000..bee93d0
--- /dev/null
+++ b/scripts/model_examples/xai_multimodal.py
@@ -0,0 +1,140 @@
+# -*- coding: utf-8 -*-
+"""Example of Grok model multimodal (vision) calls using DataBlock.
+
+Note: Vision (image) input is supported by grok-4.3 and above.
+grok-3-mini does NOT support image input.
+"""
+import asyncio
+import base64
+import os
+from pathlib import Path
+
+from _utils import stream_and_collect
+from agentscope.message import (
+    Msg,
+    TextBlock,
+    DataBlock,
+    URLSource,
+    Base64Source,
+)
+from agentscope.model import XAIChatModel
+from agentscope.credential import XAICredential
+
+# A publicly accessible test image (a simple cat photo)
+TEST_IMAGE_URL = (
+    "https://help-static-aliyun-doc.aliyuncs.com/file-manage"
+    "-files/zh-CN/20241022/emyrja/dog_and_girl.jpeg"
+)
+
+
+async def example_image_url() -> None:
+    """Call grok-4.3 with an image URL and ask what is in the image."""
+    model = XAIChatModel(
+        credential=XAICredential(
+            api_key=os.environ["XAI_API_KEY"],
+        ),
+        model="grok-4.3",
+        stream=True,
+        context_size=1_000_000,
+    )
+
+    image_block = DataBlock(
+        source=URLSource(
+            url=TEST_IMAGE_URL,
+            media_type="image/jpeg",
+        ),
+    )
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[
+                TextBlock(
+                    text="What animal is in this image? Describe it briefly.",
+                ),
+                image_block,
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Multimodal Call (Image URL) ===")
+    await stream_and_collect(await model(msgs))
+
+
+def _build_model() -> XAIChatModel:
+    return XAIChatModel(
+        credential=XAICredential(api_key=os.environ["XAI_API_KEY"]),
+        model="grok-4.3",
+        stream=True,
+        context_size=1_000_000,
+    )
+
+
+async def example_image_local_path() -> None:
+    """Call grok-4.3 with a local image using a ``file://`` URL.
+
+    The XAI formatter automatically reads the file from disk and converts
+    it to a base64 data URI.
+    """
+    model = _build_model()
+
+    abs_path = str(Path(__file__).parent / "test.jpeg")
+    msgs = [
+        Msg(
+            name="user",
+            content=[
+                TextBlock(
+                    text="What is happening in this image? Describe it "
+                    "briefly.",
+                ),
+                DataBlock(
+                    source=URLSource(
+                        url=f"file://{abs_path}",
+                        media_type="image/jpeg",
+                    ),
+                ),
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Local Path Call (file://) ===")
+    await stream_and_collect(await model(msgs))
+
+
+async def example_image_base64() -> None:
+    """Call grok-4.3 with a local image using explicit base64 encoding.
+
+    Use ``Base64Source`` when you already have the binary data in memory or
+    want full control over the encoding step.
+    """
+    model = _build_model()
+
+    with open(Path(__file__).parent / "test.jpeg", "rb") as f:
+        data = base64.b64encode(f.read()).decode("utf-8")
+
+    msgs = [
+        Msg(
+            name="user",
+            content=[
+                TextBlock(
+                    text="What is happening in this image? Describe it "
+                    "briefly.",
+                ),
+                DataBlock(
+                    source=Base64Source(data=data, media_type="image/jpeg"),
+                ),
+            ],
+            role="user",
+        ),
+    ]
+
+    print("=== Explicit Base64 Call ===")
+    await stream_and_collect(await model(msgs))
+
+
+if __name__ == "__main__":
+    asyncio.run(example_image_url())
+    asyncio.run(example_image_local_path())
+    asyncio.run(example_image_base64())
diff --git a/src/agentscope/__init__.py b/src/agentscope/__init__.py
new file mode 100644
index 0000000..f2ce726
--- /dev/null
+++ b/src/agentscope/__init__.py
@@ -0,0 +1,21 @@
+# -*- coding: utf-8 -*-
+"""The agentscope serialization module"""
+import warnings
+
+from ._logging import (
+    logger,
+    setup_logger,
+)
+from ._utils._common import set_id_factory
+from ._version import __version__
+
+# Raise each warning only once
+warnings.filterwarnings("once", category=DeprecationWarning)
+
+
+__all__ = [
+    "logger",
+    "setup_logger",
+    "set_id_factory",
+    "__version__",
+]
diff --git a/src/agentscope/_logging.py b/src/agentscope/_logging.py
new file mode 100644
index 0000000..caf29a0
--- /dev/null
+++ b/src/agentscope/_logging.py
@@ -0,0 +1,47 @@
+# -*- coding: utf-8 -*-
+"""The logger for agentscope."""
+
+import logging
+
+
+_DEFAULT_FORMAT = (
+    "%(asctime)s | %(levelname)-7s | "
+    "%(module)s:%(funcName)s:%(lineno)s - %(message)s"
+)
+
+logger = logging.getLogger("as")
+
+
+def setup_logger(
+    level: str,
+    filepath: str | None = None,
+) -> None:
+    """Set up the agentscope logger.
+
+    Args:
+        level (`str`):
+            The logging level, chosen from "INFO", "DEBUG", "WARNING",
+            "ERROR", "CRITICAL".
+        filepath (`str | None`, optional):
+            The filepath to save the logging output.
+    """
+    if level not in ["INFO", "DEBUG", "WARNING", "ERROR", "CRITICAL"]:
+        raise ValueError(
+            f"Invalid logging level: {level}. Must be one of "
+            f"'INFO', 'DEBUG', 'WARNING', 'ERROR', 'CRITICAL'.",
+        )
+    logger.handlers.clear()
+    logger.setLevel(level)
+    handler = logging.StreamHandler()
+    handler.setFormatter(logging.Formatter(_DEFAULT_FORMAT))
+    logger.addHandler(handler)
+
+    if filepath:
+        handler = logging.FileHandler(filepath)
+        handler.setFormatter(logging.Formatter(_DEFAULT_FORMAT))
+        logger.addHandler(handler)
+
+    logger.propagate = False
+
+
+setup_logger("INFO")
diff --git a/src/agentscope/_utils/__init__.py b/src/agentscope/_utils/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/src/agentscope/_utils/_audio.py b/src/agentscope/_utils/_audio.py
new file mode 100644
index 0000000..b93b5cb
--- /dev/null
+++ b/src/agentscope/_utils/_audio.py
@@ -0,0 +1,42 @@
+# -*- coding: utf-8 -*-
+"""Audio utilities shared across model providers."""
+import struct
+
+
+def _build_streaming_wav_header(
+    sample_rate: int = 24000,
+    channels: int = 1,
+    bits_per_sample: int = 16,
+) -> bytes:
+    """Build a 44-byte WAV/RIFF header for streaming PCM.
+
+    The RIFF and ``data`` chunk sizes are set to ``0xFFFFFFFF`` since the
+    total length isn't known yet. Decoders that only need sample-rate,
+    channel count and bit depth (e.g. the web ``WavStreamPlayer``) treat
+    everything after the ``data`` chunk header as PCM, so this is
+    sufficient for live decoding of an open-ended stream.
+
+    Both DashScope omni and OpenAI streaming deliver raw PCM upstream;
+    prefixing the first chunk with this header lets the frontend start
+    playback immediately without buffering the whole response.
+    """
+    byte_rate = sample_rate * channels * bits_per_sample // 8
+    block_align = channels * bits_per_sample // 8
+    return (
+        b"RIFF"
+        + struct.pack("<I", 0xFFFFFFFF)
+        + b"WAVE"
+        + b"fmt "
+        + struct.pack("<I", 16)
+        + struct.pack(
+            "<HHIIHH",
+            1,
+            channels,
+            sample_rate,
+            byte_rate,
+            block_align,
+            bits_per_sample,
+        )
+        + b"data"
+        + struct.pack("<I", 0xFFFFFFFF)
+    )
diff --git a/src/agentscope/_utils/_common.py b/src/agentscope/_utils/_common.py
new file mode 100644
index 0000000..41c585d
--- /dev/null
+++ b/src/agentscope/_utils/_common.py
@@ -0,0 +1,341 @@
+# -*- coding: utf-8 -*-
+"""The common utilities for agentscope library."""
+import asyncio
+import base64
+import copy
+import functools
+import inspect
+import json
+import os
+import types
+import uuid
+from datetime import datetime
+from typing import Any, Callable
+
+from .._logging import logger
+from ..exception import ToolJSONDecodeError
+
+
+def _default_id_factory() -> str:
+    return uuid.uuid4().hex
+
+
+_id_factory: Callable[[], str] = _default_id_factory
+
+
+def set_id_factory(factory: Callable[[], str]) -> None:
+    """Override the global ID factory used by all AgentScope entities.
+
+    Entity IDs default to ``uuid.uuid4().hex``. Call this once at
+    startup to substitute a different strategy.
+
+    .. note::
+        Security-sensitive tokens (gateway tokens, Redis lock tokens)
+        are **not** affected and always use ``uuid.uuid4().hex``.
+
+    Args:
+        factory (`Callable[[], str]`):
+            A no-arg callable returning a string ID.
+
+    Raises:
+        TypeError: If ``factory`` is not callable.
+
+    Example:
+        >>> from agentscope import set_id_factory
+        >>> set_id_factory(lambda: uuid7().hex)
+    """
+    if not callable(factory):
+        raise TypeError(
+            f"factory must be a callable, got {type(factory).__name__}",
+        )
+    global _id_factory
+    _id_factory = factory
+
+
+def _generate_id() -> str:
+    """Generate an ID string using the current global ID factory."""
+    return _id_factory()
+
+
+def _json_loads_with_repair(
+    json_str: str,
+    schema: dict | None = None,
+) -> dict:
+    """The given json_str maybe incomplete, e.g. '{"key', so we need to
+    repair and load it into a Python object.
+
+    .. note::
+        This function is currently only used for parsing the streaming output
+        of the argument field in `tool_use`, so the parsed result must be a
+        dict.
+
+    Args:
+        json_str (`str`):
+            The JSON string to parse, which may be incomplete or malformed.
+        schema (`dict`, optional):
+            An optional JSON schema to guide the repair process.
+
+    Returns:
+        `dict`:
+            A dictionary parsed from the JSON string after repair attempts.
+            Returns an empty dict if all repair attempts fail.
+    """
+    try:
+        # Loads directly
+        res = json.loads(json_str)
+        if isinstance(res, dict):
+            return res
+
+        error_message = (
+            f"Error: Your argument string is decoded into a {type(res)} "
+            f"object, but a dict object is expected!"
+        )
+    except json.JSONDecodeError as e:
+        error_message = (
+            f"Error: When decoding your tool arguments from JSON format "
+            f"to a Python dictionary, a JSONDecodeError was raised with "
+            f"message: {str(e)}."
+        )
+
+    try:
+        # Try to repair with json_repair
+        from json_repair import repair_json
+
+        repaired = repair_json(json_str, stream_stable=True, schema=schema)
+        res = json.loads(repaired)
+        if isinstance(res, dict):
+            return res
+
+    except Exception:
+        # Whatever the error is, we throw the original error message to the
+        # agent, which is more helpful for debugging.
+        pass
+
+    # If still failed, we throw the original error message to the agent, rather
+    # than the error from json_repair, which is less helpful for debugging.
+    if len(json_str) > 200:
+        error_json_str = json_str[:100] + "[TRUNCATE]" + json_str[-100:]
+        ellipsis_hint = (
+            "(Because the JSON string is too long, a truncated label "
+            '"[TRUNCATE]" is used here to indicate the truncation)'
+        )
+    else:
+        error_json_str = json_str
+        ellipsis_hint = ""
+
+    raise ToolJSONDecodeError(
+        f"""<system-reminder>{error_message}
+
+Your argument string is decoded by the following code snippet{ellipsis_hint}:
+```python
+import json
+
+your_tool_arguments = {repr(error_json_str)}
+json.loads(your_tool_arguments)
+```
+
+**You should recorrect the arguments in JSON format.**</system-reminder>""",
+    )
+
+
+def _get_timestamp(add_random_suffix: bool = False) -> str:
+    """Get the current timestamp in the format YYYY-MM-DD HH:MM:SS.sss."""
+    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S.%f")[:-3]
+
+    if add_random_suffix:
+        # Add a random suffix to the timestamp
+        timestamp += f"_{os.urandom(3).hex()}"
+
+    return timestamp
+
+
+async def _is_async_func(func: Callable) -> bool:
+    """Check if the given function is an async function, including
+    coroutine functions, async generators, and coroutine objects.
+    """
+
+    return (
+        inspect.iscoroutinefunction(func)
+        or inspect.isasyncgenfunction(func)
+        or isinstance(func, types.CoroutineType)
+        or isinstance(func, types.GeneratorType)
+        and asyncio.iscoroutine(func)
+        or isinstance(func, functools.partial)
+        and await _is_async_func(func.func)
+    )
+
+
+async def _execute_async_or_sync_func(
+    func: Callable,
+    *args: Any,
+    **kwargs: Any,
+) -> Any:
+    """Execute an async or sync function based on its type.
+
+    Args:
+        func (`Callable`):
+            The function to be executed, which can be either async or sync.
+        *args (`Any`):
+            Positional arguments to be passed to the function.
+        **kwargs (`Any`):
+            Keyword arguments to be passed to the function.
+
+    Returns:
+        `Any`:
+            The result of the function execution.
+    """
+
+    if await _is_async_func(func):
+        return await func(*args, **kwargs)
+
+    return func(*args, **kwargs)
+
+
+def _get_bytes_from_web_url(
+    url: str,
+    max_retries: int = 3,
+) -> str:
+    """Get the bytes from a given URL.
+
+    Args:
+        url (`str`):
+            The URL to fetch the bytes from.
+        max_retries (`int`, defaults to `3`):
+            The maximum number of retries.
+    """
+    import requests
+
+    for _ in range(max_retries):
+        try:
+            response = requests.get(url)
+            response.raise_for_status()
+            return response.content.decode("utf-8")
+
+        except UnicodeDecodeError:
+            return base64.b64encode(response.content).decode("ascii")
+
+        except Exception as e:
+            logger.info(
+                "Failed to fetch bytes from URL %s. Error %s. Retrying...",
+                url,
+                str(e),
+            )
+
+    raise RuntimeError(
+        f"Failed to fetch bytes from URL `{url}` after {max_retries} retries.",
+    )
+
+
+def _map_text_to_uuid(text: str) -> str:
+    """Map the given text to a deterministic UUID string.
+
+    Args:
+        text (`str`):
+            The input text to be mapped to a UUID.
+
+    Returns:
+        `str`:
+            A deterministic UUID string derived from the input text.
+    """
+    return str(uuid.uuid3(uuid.NAMESPACE_DNS, text))
+
+
+def _flatten_json_schema(schema: dict) -> dict:
+    """Flatten a JSON schema by resolving all local ``$ref`` references.
+
+    Some LLM providers (e.g. Gemini, GLM-5.x via OpenCode Go) cannot
+    process ``$defs`` / ``$ref`` patterns in tool parameter schemas.
+    When Pydantic generates schemas for complex nested types it emits a
+    ``$defs`` block (or the legacy ``definitions`` block) and refers to
+    it with ``{"$ref": "#/$defs/TypeName"}``.
+
+    This function resolves every such reference by substituting the full
+    definition inline, then drops the ``$defs`` / ``definitions``
+    sections so the output is a flat, self-contained schema.
+
+    Circular references are detected and replaced with a fallback object
+    schema to avoid infinite recursion.  Only local references of the
+    form ``#/$defs/<name>`` or ``#/definitions/<name>`` are expanded;
+    external ``$ref`` URLs are left unchanged.
+
+    Args:
+        schema (`dict`):
+            The JSON schema that may contain ``$defs`` and ``$ref``
+            references.
+
+    Returns:
+        `dict`:
+            A flattened JSON schema with all references resolved inline.
+    """
+    has_defs = isinstance(schema.get("$defs"), dict) or isinstance(
+        schema.get("definitions"),
+        dict,
+    )
+    if not has_defs:
+        return schema
+
+    schema = copy.deepcopy(schema)
+    defs: dict[str, Any] = {}
+    if isinstance(schema.get("$defs"), dict):
+        defs.update(schema.pop("$defs"))
+    if isinstance(schema.get("definitions"), dict):
+        defs.update(schema.pop("definitions"))
+
+    if not defs:
+        return schema
+
+    def _resolve_ref(obj: Any, visited: frozenset = frozenset()) -> Any:
+        if isinstance(obj, list):
+            return [_resolve_ref(item, visited) for item in obj]
+        if not isinstance(obj, dict):
+            return obj
+        if "$ref" in obj:
+            ref_path = obj["$ref"]
+            if isinstance(ref_path, str) and (
+                ref_path.startswith("#/$defs/")
+                or ref_path.startswith("#/definitions/")
+            ):
+                def_name = ref_path.split("/")[-1]
+                if def_name in visited:
+                    logger.warning(
+                        "Circular reference detected for '%s' in tool "
+                        "schema",
+                        def_name,
+                    )
+                    return {
+                        "type": "object",
+                        "description": f"(circular: {def_name})",
+                    }
+                if def_name in defs:
+                    resolved = _resolve_ref(
+                        defs[def_name],
+                        visited | {def_name},
+                    )
+                    for key, value in obj.items():
+                        if key != "$ref":
+                            resolved[key] = _resolve_ref(
+                                value,
+                                visited | {def_name},
+                            )
+                    return resolved
+            return obj
+        result: dict[str, Any] = {}
+        for key, value in obj.items():
+            if key in ("$defs", "definitions"):
+                continue
+            result[key] = _resolve_ref(value, visited)
+        return result
+
+    return _resolve_ref(schema)
+
+
+def _estimate_tokens(text: str) -> int:
+    """Estimate the number of tokens in a given text."""
+
+    return int(len(text.encode("utf-8")) / 4 + 0.5)
+
+
+def _estimate_bytes(tokens: int) -> int:
+    """Estimate the number of bytes with given tokens."""
+
+    return int(tokens * 4)
diff --git a/src/agentscope/_utils/_mixin.py b/src/agentscope/_utils/_mixin.py
new file mode 100644
index 0000000..1ead2b6
--- /dev/null
+++ b/src/agentscope/_utils/_mixin.py
@@ -0,0 +1,9 @@
+# -*- coding: utf-8 -*-
+"""The mixin for agentscope."""
+
+
+class DictMixin(dict):
+    """The dictionary mixin that allows attribute-style access."""
+
+    __setattr__ = dict.__setitem__
+    __getattr__ = dict.__getitem__
diff --git a/src/agentscope/_version.py b/src/agentscope/_version.py
new file mode 100644
index 0000000..0e63fe4
--- /dev/null
+++ b/src/agentscope/_version.py
@@ -0,0 +1,4 @@
+# -*- coding: utf-8 -*-
+"""The version of agentscope."""
+
+__version__ = "2.0.4"
diff --git a/src/agentscope/agent/__init__.py b/src/agentscope/agent/__init__.py
new file mode 100644
index 0000000..39a93b8
--- /dev/null
+++ b/src/agentscope/agent/__init__.py
@@ -0,0 +1,6 @@
+# -*- coding: utf-8 -*-
+"""Initialize the agent module."""
+from ._agent import Agent
+from ._config import ContextConfig, ModelConfig, ReActConfig
+
+__all__ = ["Agent", "ContextConfig", "ModelConfig", "ReActConfig"]
diff --git a/src/agentscope/agent/_agent.py b/src/agentscope/agent/_agent.py
new file mode 100644
index 0000000..d9c982b
--- /dev/null
+++ b/src/agentscope/agent/_agent.py
@@ -0,0 +1,2836 @@
+# -*- coding: utf-8 -*-
+"""The unified agent class in AgentScope library."""
+import asyncio
+import inspect
+
+from asyncio import Queue
+from copy import deepcopy
+from typing import (
+    Any,
+    AsyncGenerator,
+    Sequence,
+    Literal,
+    List,
+    TYPE_CHECKING,
+)
+
+import jsonschema
+
+from ._config import ContextConfig, ReActConfig, ModelConfig
+from ..state import AgentState
+from ._utils import _ToolCallBatch
+from .._logging import logger
+from .._utils._common import _generate_id, _json_loads_with_repair
+from ..event import (
+    AgentEvent,
+    ModelCallEndEvent,
+    ModelCallStartEvent,
+    ReplyEndEvent,
+    ReplyStartEvent,
+    TextBlockDeltaEvent,
+    TextBlockEndEvent,
+    TextBlockStartEvent,
+    ThinkingBlockDeltaEvent,
+    ThinkingBlockEndEvent,
+    ThinkingBlockStartEvent,
+    ToolCallDeltaEvent,
+    ToolCallEndEvent,
+    ToolCallStartEvent,
+    ToolResultDataDeltaEvent,
+    ToolResultEndEvent,
+    ToolResultStartEvent,
+    ToolResultTextDeltaEvent,
+    RequireUserConfirmEvent,
+    RequireExternalExecutionEvent,
+    ExternalExecutionResultEvent,
+    UserConfirmResultEvent,
+    DataBlockStartEvent,
+    DataBlockDeltaEvent,
+    DataBlockEndEvent,
+    ExceedMaxItersEvent,
+    ReplyEndReason,
+    UserInterruptEvent,
+)
+from ..exception import AgentOrientedException
+from ..model import (
+    ChatResponse,
+    ChatUsage,
+    ChatModelBase,
+    FinishedReason,
+)
+from ..message import (
+    Msg,
+    AssistantMsg,
+    SystemMsg,
+    UserMsg,
+    TextBlock,
+    ThinkingBlock,
+    ToolCallBlock,
+    ToolResultBlock,
+    DataBlock,
+    Base64Source,
+    URLSource,
+    ToolCallState,
+    ToolResultState,
+    Usage,
+    HintBlock,
+)
+from ..tool import (
+    Toolkit,
+    ToolChunk,
+    ToolChoice,
+    ToolResponse,
+)
+from ..permission import (
+    PermissionBehavior,
+    PermissionEngine,
+    PermissionDecision,
+)
+from ..workspace import Offloader, WorkspaceBase
+
+if TYPE_CHECKING:
+    from ..middleware import MiddlewareBase
+else:
+    MiddlewareBase = Any
+
+
+class Agent:
+    """The agent class."""
+
+    def __init__(
+        self,
+        name: str,
+        system_prompt: str,
+        model: ChatModelBase,
+        toolkit: Toolkit | None = None,
+        middlewares: list[MiddlewareBase] | None = None,
+        state: AgentState | None = None,
+        offloader: Offloader | None = None,
+        # The agent configurations
+        model_config: ModelConfig | None = None,
+        context_config: ContextConfig | None = None,
+        react_config: ReActConfig | None = None,
+    ) -> None:
+        """Initialize the agent class in AgentScope.
+
+        Args:
+            name (`str`):
+                The agent identifier.
+            system_prompt (`str`):
+                The agent's system prompt. Additional instructions may be
+                appended to it dynamically during operation.
+            model (`ChatModelBase`):
+                The chat model/llm used for this agent.
+            toolkit (`Toolkit | None`, optional):
+                The toolkit used for registering tools, MCPs and skills as the
+                sole source.
+            middlewares (`list[MiddlewareBase] | None`, optional):
+                Middlewares applied to the agent to modify its behavior
+                without altering its source code. Supported hook points
+                include: reply, reasoning, acting, model call, and system
+                prompt retrieval.
+            state (`AgentState | None`, optional):
+                The agent state. A new state will be created if not provided.
+            offloader (`Offloader | None`, optional):
+                The context offloader. If provided, the compressed context and
+                tool result will be offloaded.
+            model_config (`ModelConfig | None`, optional):
+                The additional chat model configuration including fallback
+                model and retries.
+            context_config (`ContextConfig | None`, optional):
+                The context config for context compression and tool result
+                compression.
+            react_config (`ReActConfig | None`, optional):
+                The config for the reasoning-acting loop.
+        """
+        self.name = name
+        self._system_prompt = system_prompt
+        self.model = model
+        self.state = state or AgentState()
+
+        self.model_config = model_config or ModelConfig()
+        self.context_config = context_config or ContextConfig()
+        self.react_config = react_config or ReActConfig()
+
+        # The permission engine
+        self._engine = PermissionEngine(self.state.permission_context)
+
+        # The offloader/workspace
+        self.offloader = offloader
+
+        # ====================================================================
+        # The Tool-related logics
+        # ====================================================================
+        self.toolkit = toolkit or Toolkit()
+
+        # ====================================================================
+        # The Middleware-related attributes
+        # ====================================================================
+        # Filter middlewares by implemented hooks (only once)
+        middlewares = middlewares or []
+        self._reply_middlewares = [
+            _ for _ in middlewares if _.is_implemented("on_reply")
+        ]
+        self._reasoning_middlewares = [
+            _ for _ in middlewares if _.is_implemented("on_reasoning")
+        ]
+        self._acting_middlewares = [
+            _ for _ in middlewares if _.is_implemented("on_acting")
+        ]
+        self._model_call_middlewares = [
+            _ for _ in middlewares if _.is_implemented("on_model_call")
+        ]
+        self._system_prompt_middlewares = [
+            _ for _ in middlewares if _.is_implemented("on_system_prompt")
+        ]
+        self._compress_context_middlewares = [
+            _ for _ in middlewares if _.is_implemented("on_compress_context")
+        ]
+
+    # =======================================================================
+    # Agent public methods
+    # =======================================================================
+
+    async def reply_stream(
+        self,
+        inputs: Msg
+        | list[Msg]
+        | UserConfirmResultEvent
+        | UserInterruptEvent
+        | ExternalExecutionResultEvent
+        | None = None,
+    ) -> AsyncGenerator[AgentEvent, None]:
+        """Reply to the given inputs and stream agent events.
+
+        Args:
+            inputs (`Msg | list[Msg] | UserConfirmResultEvent | \
+            UserInterruptEvent | ExternalExecutionResultEvent | None`, \
+            optional):
+                The inputs that trigger this reply. See :meth:`reply` for
+                the full list of accepted variants.
+
+        Yields:
+            `AgentEvent`:
+                Streamed events produced during the reply.
+
+        .. note:: If requiring outside interaction for multiple tool calls
+            and only receive partial confirmation or execution results, the
+            agent won't re-send the requiring events for the unconfirmed
+            or unexecuted tool calls.
+        """
+        async for chunk in self._reply(inputs=inputs):
+            if not isinstance(chunk, Msg):
+                yield chunk
+
+    async def reply(
+        self,
+        inputs: Msg
+        | list[Msg]
+        | UserConfirmResultEvent
+        | UserInterruptEvent
+        | ExternalExecutionResultEvent
+        | None = None,
+    ) -> Msg:
+        """Reply to the given inputs, consuming all streamed events.
+
+        Args:
+            inputs (`Msg | list[Msg] | UserConfirmResultEvent | \
+            UserInterruptEvent | ExternalExecutionResultEvent | None`, \
+            optional):
+                The inputs that trigger this reply. It can be:
+
+                - a single `Msg` or a list of `Msg` objects to start a new
+                  reply,
+                - a `UserConfirmResultEvent` or
+                  `ExternalExecutionResultEvent` to continue from the
+                  outside interaction required by the previous reply,
+                - a `UserInterruptEvent` to abort a parked reply — the
+                  agent closes all pending tool calls with an interrupted
+                  tool result and ends the reply without entering the
+                  reasoning-acting loop,
+                - `None` if there is nothing new to feed in (e.g. just
+                  continue from the current state).
+
+        Returns:
+            `Msg`:
+                A final reply message.
+        """
+        final_msg: Msg | None = None
+        async for evt_or_msg in self._reply(inputs=inputs):
+            if isinstance(evt_or_msg, Msg):
+                final_msg = evt_or_msg
+        if final_msg is None:
+            raise RuntimeError("Agent did not produce a final message.")
+        return final_msg
+
+    async def observe(self, msgs: Msg | list[Msg] | None = None) -> None:
+        """Receive external observation message(s) and save them into
+        context."""
+        await self._handle_incoming_messages(msgs)
+
+    async def compress_context(
+        self,
+        context_config: ContextConfig | None = None,
+        instructions: HintBlock | None = None,
+    ) -> None:
+        """Compress the agent's context if the token count exceeds the
+        threshold.
+
+        Args:
+            context_config (`ContextConfig | None`, optional):
+                If provided, compress the context with the given context
+                config. Otherwise, use the default context config in the
+                agent.
+            instructions (`HintBlock | None`, optional):
+                Optional hints or instructions injected into the compression
+                context to guide the summarization behavior.
+        """
+        if not self._compress_context_middlewares:
+            await self._compress_context_impl(
+                context_config=context_config,
+                instructions=instructions,
+            )
+        else:
+
+            async def execute_chain(
+                index: int = 0,
+                context_config: ContextConfig | None = context_config,
+                instructions: HintBlock | None = instructions,
+            ) -> None:
+                """Execute the compress_context middleware chain."""
+                if index >= len(self._compress_context_middlewares):
+                    await self._compress_context_impl(
+                        context_config=context_config,
+                        instructions=instructions,
+                    )
+                else:
+                    mw = self._compress_context_middlewares[index]
+                    input_kwargs = {
+                        "context_config": context_config,
+                        "instructions": instructions,
+                    }
+
+                    async def next_handler(**kwargs: Any) -> None:
+                        await execute_chain(
+                            index + 1,
+                            **{**input_kwargs, **kwargs},
+                        )
+
+                    await mw.on_compress_context(
+                        agent=self,
+                        input_kwargs=input_kwargs,
+                        next_handler=next_handler,
+                    )
+
+            await execute_chain()
+
+    async def _compress_context_impl(
+        self,
+        context_config: ContextConfig | None = None,
+        instructions: HintBlock | None = None,
+    ) -> None:
+        """Compress the agent's context if the token count exceeds the
+        threshold.
+
+        Args:
+            context_config (`ContextConfig | None`, optional):
+                If provided, compress the context with the given context
+                config. Otherwise, use the default context config in the
+                agent.
+            instructions (`HintBlock | None`, optional):
+                Optional hints or instructions injected into the compression
+                context to guide the summarization behavior.
+        """
+        cfg: ContextConfig = context_config or self.context_config
+
+        # Count the current tokens
+        kwargs = await self._prepare_model_input()
+        estimated_tokens = await self.model.count_tokens(**kwargs)
+
+        # Skip if no compression is needed
+        threshold = cfg.trigger_ratio * self.model.context_size
+        if estimated_tokens < threshold:
+            return
+
+        logger.info(
+            "[AGENT %s]: Current token count %d exceeds the threshold %d, "
+            "activating compression.",
+            self.name,
+            int(estimated_tokens),
+            int(threshold),
+        )
+
+        if len(self.state.context) == 0:
+            # The system prompt and the summary (if exists) exceeds the
+            # threshold, which cannot be compressed, raise the error to the
+            # developer!
+            suffix = ""
+            if self.state.summary:
+                suffix = "and the compression summary "
+            raise RuntimeError(
+                f"The system prompt {suffix}exceed(s) the compression "
+                f"threshold ({threshold} tokens), cannot be compressed.",
+            )
+
+        # Split the context into the ones to be compressed, and the others to
+        # be reserved
+        tools = kwargs.get("tools", [])
+        (
+            msgs_to_compress,
+            msgs_to_reserve,
+        ) = await self._split_context_for_compression(
+            cfg.reserve_ratio * self.model.context_size,
+            tools,
+        )
+
+        if len(msgs_to_compress) == 0:
+            # The reserve ratio is too large so that although it exceeds the
+            # trigger threshold, the context to be compressed is empty
+            # Fallback by lowering the reserve ratio to compress more context.
+            logger.warning(
+                "The reserve ratio %.2f is too large to compress any context."
+                "Lower the reserve ratio to 0 as a fallback.",
+                cfg.reserve_ratio,
+            )
+            (
+                msgs_to_compress,
+                msgs_to_reserve,
+            ) = await self._split_context_for_compression(
+                0 * self.model.context_size,
+                tools,
+            )
+
+            # The msgs to be compressed cannot be empty here, unless the
+            # system prompt and summary (if any) already exceed the context
+            # length, which we have handled before.
+
+        # Prepare the messages to compress
+        msgs_system = [
+            SystemMsg(
+                name="system",
+                content=await self._get_system_prompt(),
+            ),
+        ]
+        if self.state.summary:
+            msgs_system.append(UserMsg("user", self.state.summary))
+
+        instruction_msgs: list[Msg] = []
+        if instructions is not None:
+            instruction_msgs.append(
+                AssistantMsg(
+                    name=self.name,
+                    content=[instructions],
+                ),
+            )
+
+        messages = (
+            msgs_system
+            + msgs_to_compress
+            + instruction_msgs
+            + [
+                UserMsg(name="user", content=cfg.compression_prompt),
+            ]
+        )
+
+        # The compression prompt may exceed the context length, here we mark
+        # the overflow by a bool flag
+        compression_tool_schema = [
+            {
+                "type": "function",
+                "function": {
+                    "name": "generate_structured_output",
+                    "description": "Call this function to generate "
+                    "structured output required by "
+                    "the user.",
+                    "parameters": cfg.summary_schema,
+                },
+            },
+        ]
+        context_overflow = False
+        estimated_compression_tokens = await self.model.count_tokens(
+            messages,
+            compression_tool_schema,
+        )
+        if estimated_compression_tokens > self.model.context_size:
+            logger.warning(
+                "The current context length exceeds the model's context "
+                "length (%d tokens), the compression maybe failed due to "
+                "insufficient reserved context for compression.",
+                self.model.context_size,
+            )
+            context_overflow = True
+
+        # Compress the messages
+        try:
+            res = await self.model.generate_structured_output(
+                messages=messages,
+                structured_model=cfg.summary_schema,
+            )
+
+        except Exception as e:
+            if context_overflow:
+                logger.warning(
+                    "Failed to compress context, which may be caused by "
+                    "insufficient reserved context for compression. "
+                    "Trying to compress by removing the oldest context.",
+                )
+                for i in range(1, len(msgs_to_compress) + 1):
+                    messages = (
+                        msgs_system
+                        + msgs_to_compress[i:]
+                        + instruction_msgs
+                        + [
+                            UserMsg(
+                                name="user",
+                                content=cfg.compression_prompt,
+                            ),
+                        ]
+                    )
+                    estimated_compression_tokens = (
+                        await self.model.count_tokens(
+                            messages,
+                            compression_tool_schema,
+                        )
+                    )
+                    # Considering trigger_ratio <= 0.9, at least reserve 10%
+                    # tokens for compression response
+                    if (
+                        estimated_compression_tokens
+                        < self.model.context_size * cfg.trigger_ratio
+                    ):
+                        break
+
+                res = await self.model.generate_structured_output(
+                    messages=messages,
+                    structured_model=cfg.summary_schema,
+                )
+
+            else:
+                raise e from None
+
+        if res.finished_reason == FinishedReason.INTERRUPTED:
+            logger.warning(
+                "The context compression was interrupted and skipped. ",
+            )
+            raise asyncio.CancelledError()
+
+        # Update the summary
+        async def _apply_change() -> None:
+            """Apply the context change with interruption protection."""
+            new_summary = cfg.summary_template.format(**res.content)
+            if self.offloader:
+                path = await self.offloader.offload_context(
+                    self.state.session_id,
+                    msgs=msgs_to_compress,
+                )
+                new_summary += (
+                    f"\n<system-reminder>The compressed context is offloaded "
+                    f"to '{path}', you can refer to it when needed."
+                    f"</system-reminder>"
+                )
+
+            # Protected from interruption
+            await self._clear_unreserved_read_cache(msgs_to_reserve)
+
+            # Update the context
+            self.state.summary = new_summary
+            self.state.context = msgs_to_reserve
+
+            logger.info(
+                "[AGENT %s]: The context compression finished.",
+                self.name,
+            )
+
+        apply_task = asyncio.create_task(_apply_change())
+        try:
+            await asyncio.shield(apply_task)
+        except asyncio.CancelledError:
+            await apply_task
+            raise
+
+    # ======================================================================
+    # Agent core methods, including _reply, _reasoning, _acting, etc.
+    # ======================================================================
+
+    async def _reply(
+        self,
+        inputs: Msg
+        | list[Msg]
+        | UserConfirmResultEvent
+        | UserInterruptEvent
+        | ExternalExecutionResultEvent
+        | None = None,
+    ) -> AsyncGenerator[AgentEvent | Msg, None]:
+        """Reply entry point (maybe wrapped by middleware)."""
+        if not self._reply_middlewares:
+            async for item in self._reply_impl(inputs=inputs):
+                yield item
+        else:
+
+            async def execute_chain(
+                index: int = 0,
+                inputs: Msg
+                | list[Msg]
+                | UserConfirmResultEvent
+                | UserInterruptEvent
+                | ExternalExecutionResultEvent
+                | None = inputs,
+            ) -> AsyncGenerator[AgentEvent | Msg, None]:
+                if index >= len(self._reply_middlewares):
+                    async for item in self._reply_impl(inputs=inputs):
+                        yield item
+                else:
+                    mw = self._reply_middlewares[index]
+                    input_kwargs = {"inputs": inputs}
+
+                    async def next_handler(
+                        **kwargs: Any,
+                    ) -> AsyncGenerator[AgentEvent | Msg, None]:
+                        async for item in execute_chain(
+                            index + 1,
+                            **{**input_kwargs, **kwargs},
+                        ):
+                            yield item
+
+                    async for item in mw.on_reply(
+                        agent=self,
+                        input_kwargs=input_kwargs,
+                        next_handler=next_handler,
+                    ):
+                        yield item
+
+            async for item in execute_chain():
+                yield item
+
+    async def _close_unfinished_tool_calls(
+        self,
+    ) -> AsyncGenerator[
+        ToolResultStartEvent | ToolResultTextDeltaEvent | ToolResultEndEvent,
+        None,
+    ]:
+        """Close the unfinished tool calls on interruption, so the next
+        input will be handled normally."""
+        if not self.state.context:
+            return
+
+        last_msg = self.state.context[-1]
+        if last_msg.role != "assistant" or last_msg.name != self.name:
+            return
+
+        # Searching for tool calls that requires user confirmation or external
+        # execution without tool results
+        awaiting_tool_calls: dict = {}
+        for index, block in enumerate(last_msg.content):
+            if isinstance(block, ToolCallBlock):
+                awaiting_tool_calls[block.id] = index
+            elif isinstance(block, ToolResultBlock):
+                awaiting_tool_calls.pop(block.id, None)
+
+        interruption_message = (
+            "<system-reminder>The tool call has been interrupted by "
+            "the user.</system-reminder>"
+        )
+
+        for index in awaiting_tool_calls.values():
+            # First update the status
+            assert isinstance(last_msg.content[index], ToolCallBlock)
+            last_msg.content[index].state = ToolCallState.FINISHED
+
+            # Emit the full tool_result lifecycle (START → DELTA → END)
+            yield ToolResultStartEvent(
+                reply_id=self.state.reply_id,
+                tool_call_id=last_msg.content[index].id,
+                tool_call_name=last_msg.content[index].name,
+            )
+            yield ToolResultTextDeltaEvent(
+                reply_id=self.state.reply_id,
+                tool_call_id=last_msg.content[index].id,
+                delta=interruption_message,
+            )
+            yield ToolResultEndEvent(
+                reply_id=self.state.reply_id,
+                tool_call_id=last_msg.content[index].id,
+                state=ToolResultState.INTERRUPTED,
+            )
+            last_msg.content.append(
+                ToolResultBlock(
+                    id=last_msg.content[index].id,
+                    name=last_msg.content[index].name,
+                    output=interruption_message,
+                    state=ToolResultState.INTERRUPTED,
+                ),
+            )
+
+    async def _reply_impl(
+        self,
+        inputs: Msg
+        | list[Msg]
+        | UserConfirmResultEvent
+        | UserInterruptEvent
+        | ExternalExecutionResultEvent
+        | None = None,
+    ) -> AsyncGenerator[AgentEvent | Msg, None]:
+        """Core reply logic."""
+
+        end_event: ReplyEndEvent | None = None
+        try:
+            # Dispatch the unified inputs by type into the legacy local
+            # variables
+            event: (
+                UserConfirmResultEvent
+                | UserInterruptEvent
+                | ExternalExecutionResultEvent
+                | None
+            )
+            msgs: Msg | list[Msg] | None
+            if isinstance(
+                inputs,
+                (
+                    UserConfirmResultEvent,
+                    UserInterruptEvent,
+                    ExternalExecutionResultEvent,
+                ),
+            ):
+                event = inputs
+                msgs = None
+            else:
+                event = None
+                msgs = inputs
+
+            # Parked-interrupt short-circuit: only signal an INTERRUPTED
+            # end when there is actual HITL work to close; otherwise the
+            # session is effectively idle and the call is a silent no-op.
+            # ``finally`` reuses the CancelledError cleanup path when
+            # ``end_event`` is set — no reasoning-acting loop either way.
+            if isinstance(inputs, UserInterruptEvent):
+                if self.state.has_awaiting_tool_calls(self.name):
+                    end_event = ReplyEndEvent(
+                        session_id=self.state.session_id,
+                        reply_id=self.state.reply_id,
+                        finished_reason=ReplyEndReason.INTERRUPTED,
+                    )
+                return
+
+            # ===================================================================
+            # Step 1: Checking agent input:
+            #  - if incoming event and agent is waiting for an event
+            #  - if event is None and agent is not waiting for an event
+            # ===================================================================
+            is_awaiting = await self._check_incoming_event(event)
+
+            # ===================================================================
+            # Step 2: Handling agent event if applicable
+            #  - yield tool result events for the denied tool calls, or
+            #  - update the reply state as a new reply process
+            # ===================================================================
+            if is_awaiting:
+                async for evt in self._handle_incoming_event(event):
+                    yield evt
+            else:
+                await self._handle_incoming_messages(msgs)
+                # Update the context with the incoming message and state
+                self.state.reply_id = _generate_id()
+                self.state.cur_iter = 0
+
+                yield ReplyStartEvent(
+                    session_id=self.state.session_id,
+                    reply_id=self.state.reply_id,
+                    name=self.name,
+                )
+
+            # =================================================================
+            # Step 3: Enter the reasoning-acting loop until reaching max_iters
+            #  or no more tool calls to execute
+            # =================================================================
+            while self.state.cur_iter < self.react_config.max_iters:
+                # =============================================================
+                # Step 3.1:
+                # =============================================================
+                action, data = self._check_next_action()
+                if action == "exit" and isinstance(data, Msg):
+                    yield data
+                    return
+
+                # =============================================================
+                # Step 3.2: Execute reasoning if no more tools to be executed
+                # =============================================================
+                if action == "reasoning":
+                    # Compressed the memory if needed before reasoning
+                    await self.compress_context()
+
+                    # Perform reasoning
+                    interrupted = False
+                    async for evt in self._reasoning():
+                        # Exit the loop when no tool calls generated and the
+                        # reply message is generated
+                        if isinstance(evt, Msg):
+                            end_event = ReplyEndEvent(
+                                session_id=self.state.session_id,
+                                reply_id=self.state.reply_id,
+                                finished_reason=ReplyEndReason.COMPLETED,
+                            )
+                            yield evt
+                            return
+
+                        elif isinstance(evt, ModelCallEndEvent):
+                            interrupted = (
+                                evt.finished_reason
+                                == FinishedReason.INTERRUPTED
+                            )
+
+                        yield evt
+
+                    if interrupted:
+                        end_event = ReplyEndEvent(
+                            session_id=self.state.session_id,
+                            reply_id=self.state.reply_id,
+                            finished_reason=ReplyEndReason.INTERRUPTED,
+                        )
+                        return
+
+                # =============================================================
+                # Step 3.3: Getting batches of tool calls to be executed
+                #  - If not, finish loop by yielding RunFinishedEvent and exit
+                #  - Otherwise, execute by batch and continue the loop
+                # =============================================================
+                for batch in await self._batch_tool_calls():
+                    if batch.type == "sequential":
+                        evt_generator = self._execute_sequential_tool_calls(
+                            batch.tool_calls,
+                        )
+
+                    elif batch.type == "concurrent":
+                        evt_generator = self._execute_concurrent_tool_calls(
+                            batch.tool_calls,
+                        )
+
+                    else:
+                        raise ValueError(
+                            f"Invalid batch type: {batch.type}",
+                        )
+
+                    break_execution_for_hitl = False
+                    break_execution_for_interruption = False
+                    break_message = ""
+                    async for evt in evt_generator:
+                        yield evt
+                        if isinstance(
+                            evt,
+                            (
+                                RequireUserConfirmEvent,
+                                RequireExternalExecutionEvent,
+                            ),
+                        ):
+                            break_execution_for_hitl = True
+                            break_message = (
+                                "Waiting for tool calls to be confirmed or "
+                                "executed from outside ..."
+                            )
+
+                        elif (
+                            isinstance(evt, ToolResultEndEvent)
+                            and evt.state == ToolResultState.INTERRUPTED
+                        ):
+                            # Handle the interruption event
+                            break_execution_for_interruption = True
+
+                    if break_execution_for_interruption:
+                        end_event = ReplyEndEvent(
+                            session_id=self.state.session_id,
+                            reply_id=self.state.reply_id,
+                            finished_reason=ReplyEndReason.INTERRUPTED,
+                        )
+                        return
+
+                    # If it requires outside interaction stop executing the
+                    # next batch and wait for outside trigger events
+                    if break_execution_for_hitl:
+                        yield AssistantMsg(
+                            id=self.state.reply_id,
+                            name=self.name,
+                            content=break_message,
+                        )
+                        return
+
+                # Update iteration count after each round of reasoning-acting
+                self.state.cur_iter += 1
+
+            # =================================================================
+            # Step 4: Handling the max iteration executed
+            # =================================================================
+            yield ExceedMaxItersEvent(
+                reply_id=self.state.reply_id,
+                name=self.name,
+            )
+            logger.warning(
+                "Agent %s exceeds the max iteration numbers %d. "
+                "Stop the react loop.",
+                self.name,
+                self.react_config.max_iters,
+            )
+
+            # Mirror the normal-exit path so subscribers (e.g. SSE clients
+            # waiting on a terminal event) don't hang when the loop bails
+            # out on max_iters.
+            end_event = ReplyEndEvent(
+                session_id=self.state.session_id,
+                reply_id=self.state.reply_id,
+                finished_reason=ReplyEndReason.EXCEED_MAX_ITERS,
+            )
+
+            yield AssistantMsg(
+                id=self.state.reply_id,
+                name=self.name,
+                content="Executed maximum iterations of reasoning-acting loop "
+                "without finishing the task.",
+            )
+
+        except asyncio.CancelledError:
+            # Handle the CancelledError within the _reply_impl for the
+            # agent middlewares
+            end_event = ReplyEndEvent(
+                session_id=self.state.session_id,
+                reply_id=self.state.reply_id,
+                finished_reason=ReplyEndReason.INTERRUPTED,
+            )
+
+            if self.react_config.interruption_raise_cancelled_error:
+                raise
+
+        finally:
+            if end_event is not None:
+                if end_event.finished_reason == ReplyEndReason.INTERRUPTED:
+                    # Handle the context when interruption
+                    async for _ in self._close_unfinished_tool_calls():
+                        yield _
+
+                    # A fallback msg object
+                    yield AssistantMsg(
+                        id=self.state.reply_id,
+                        name=self.name,
+                        content=self.react_config.interruption_message,
+                    )
+
+                yield end_event
+
+    async def _reasoning(
+        self,
+        tool_choice: ToolChoice | None = None,
+    ) -> AsyncGenerator[
+        ModelCallStartEvent
+        | TextBlockStartEvent
+        | TextBlockDeltaEvent
+        | TextBlockEndEvent
+        | ToolCallBlock
+        | ToolCallDeltaEvent
+        | ToolCallEndEvent
+        | ThinkingBlockStartEvent
+        | ThinkingBlockDeltaEvent
+        | ThinkingBlockEndEvent
+        | DataBlockStartEvent
+        | DataBlockDeltaEvent
+        | DataBlockEndEvent
+        | ModelCallEndEvent
+        | Msg,
+        None,
+    ]:
+        """Reasoning entry point (maybe wrapped by middleware)."""
+        if not self._reasoning_middlewares:
+            async for item in self._reasoning_impl(tool_choice=tool_choice):
+                yield item
+        else:
+
+            async def execute_chain(
+                index: int = 0,
+                tool_choice: ToolChoice = tool_choice,
+            ) -> AsyncGenerator:
+                if index >= len(self._reasoning_middlewares):
+                    async for item in self._reasoning_impl(
+                        tool_choice=tool_choice,
+                    ):
+                        yield item
+                else:
+                    mw = self._reasoning_middlewares[index]
+                    input_kwargs = {"tool_choice": tool_choice}
+
+                    async def next_handler(**kwargs: Any) -> AsyncGenerator:
+                        async for item in execute_chain(
+                            index + 1,
+                            **{**input_kwargs, **kwargs},
+                        ):
+                            yield item
+
+                    async for item in mw.on_reasoning(
+                        agent=self,
+                        input_kwargs=input_kwargs,
+                        next_handler=next_handler,
+                    ):
+                        yield item
+
+            async for item in execute_chain():
+                yield item
+
+    async def _reasoning_impl(
+        self,
+        tool_choice: ToolChoice | None = None,
+    ) -> AsyncGenerator[
+        ModelCallStartEvent
+        | TextBlockStartEvent
+        | TextBlockDeltaEvent
+        | TextBlockEndEvent
+        | ToolCallBlock
+        | ToolCallDeltaEvent
+        | ToolCallEndEvent
+        | ThinkingBlockStartEvent
+        | ThinkingBlockDeltaEvent
+        | ThinkingBlockEndEvent
+        | DataBlockStartEvent
+        | DataBlockDeltaEvent
+        | DataBlockEndEvent
+        | ModelCallEndEvent
+        | Msg,
+        None,
+    ]:
+        """Core reasoning logic. Yields chunks with is_last flag."""
+
+        yield ModelCallStartEvent(
+            reply_id=self.state.reply_id,
+            model_name=self.model.model,
+        )
+
+        # Get the input arguments for the chat model, including messages and
+        # tools
+        kwargs = await self._prepare_model_input()
+
+        # Call the chat model
+        res = await self._call_model(
+            tool_choice=tool_choice,
+            **kwargs,
+        )
+
+        block_ids: dict = {
+            "text": None,
+            "thinking": None,
+            "tools": [],
+            "data": [],
+        }
+        completed_response: ChatResponse | None = None
+
+        # Check if res is an async generator (streaming response)
+        if inspect.isasyncgen(res):
+            async for chunk in res:
+                # Save the last chunk with completed response
+                if chunk.is_last:
+                    completed_response = chunk
+
+                else:
+                    # Convert the chunk into events
+                    async for evt in self._convert_chat_response_to_event(
+                        block_ids,
+                        chunk,
+                    ):
+                        yield evt
+
+        elif isinstance(res, ChatResponse):
+            completed_response = res
+            async for evt in self._convert_chat_response_to_event(
+                block_ids,
+                res,
+            ):
+                yield evt
+
+        # Send the ended events for the remaining active blocks
+        if block_ids["text"] is not None:
+            yield TextBlockEndEvent(
+                reply_id=self.state.reply_id,
+                block_id=block_ids["text"],
+            )
+        if block_ids["thinking"] is not None:
+            yield ThinkingBlockEndEvent(
+                reply_id=self.state.reply_id,
+                block_id=block_ids["thinking"],
+            )
+        for tool_call_id in block_ids["tools"]:
+            yield ToolCallEndEvent(
+                reply_id=self.state.reply_id,
+                tool_call_id=tool_call_id,
+            )
+        for data_block_id in block_ids["data"]:
+            yield DataBlockEndEvent(
+                reply_id=self.state.reply_id,
+                block_id=data_block_id,
+            )
+
+        # Guard against empty or interrupted streaming responses.
+        if completed_response is None:
+            raise RuntimeError(
+                "Model returned an empty streaming response: no is_last=True"
+                " chunk was received.  The model call may have been "
+                "interrupted mid-stream (network dropout, timeout, or model "
+                "bug).",
+            )
+
+        # Send the model call ended event with usage if available
+        yield ModelCallEndEvent(
+            reply_id=self.state.reply_id,
+            input_tokens=completed_response.usage.input_tokens
+            if completed_response.usage
+            else 0,
+            output_tokens=completed_response.usage.output_tokens
+            if completed_response.usage
+            else 0,
+            finished_reason=completed_response.finished_reason,
+        )
+
+        self._save_to_context(
+            list(completed_response.content),
+            completed_response.usage,
+        )
+
+        # If no tool call is generated, return the final message directly
+        if (
+            completed_response.finished_reason != FinishedReason.INTERRUPTED
+            and not any(
+                isinstance(_, ToolCallBlock)
+                for _ in completed_response.content
+            )
+        ):
+            last_ctx = self._get_last_msg()
+            final_usage = (
+                Usage(
+                    input_tokens=last_ctx.usage.input_tokens,
+                    output_tokens=last_ctx.usage.output_tokens,
+                )
+                if last_ctx is not None and last_ctx.usage is not None
+                else None
+            )
+            yield AssistantMsg(
+                id=self.state.reply_id,
+                name=self.name,
+                # Text only response message
+                content=list(completed_response.content),
+                usage=final_usage,
+            )
+
+    async def _check_incoming_event(
+        self,
+        event: UserConfirmResultEvent | ExternalExecutionResultEvent | None,
+    ) -> bool:
+        """Check if the agent is waiting for the incoming event, if no, raise
+        error.
+
+        Args:
+            event (`UserConfirmResultEvent | ExternalExecutionResultEvent \
+            | None`):
+                The incoming event to be checked.
+
+        Raises:
+            `ValueError`:
+                If the agent is not waiting for the incoming event, or the
+                event is not valid.
+
+        Returns:
+            `bool`:
+                If the agent is waiting for the incoming event, that means
+                this reply calling continues from the previous one. If not,
+                the reply id and iteration count should be updated for the new
+                reply.
+        """
+        awaiting_confirmations = []
+        awaiting_external_executions = []
+
+        last_msg = self._get_last_msg()
+        if last_msg:
+            # The completed tool call ids
+            tool_result_ids = [
+                _.id for _ in last_msg.get_content_blocks("tool_result")
+            ]
+
+            for tool_call in last_msg.get_content_blocks("tool_call"):
+                if tool_call.state == ToolCallState.ASKING:
+                    awaiting_confirmations.append(tool_call.id)
+                elif (
+                    tool_call.state == ToolCallState.SUBMITTED
+                    and tool_call.id not in tool_result_ids
+                ):
+                    # submitted but no result yet, i.e. external execution
+                    awaiting_external_executions.append(tool_call.id)
+
+        # No incoming event but needed
+        if event is None and (
+            awaiting_confirmations or awaiting_external_executions
+        ):
+            raise ValueError(
+                f"Agent is waiting for {len(awaiting_confirmations)} tool "
+                f"calls and external execution results for "
+                f"{len(awaiting_external_executions)} tool calls, "
+                f"but received no event.",
+            )
+
+        if isinstance(event, UserConfirmResultEvent):
+            if not awaiting_confirmations:
+                raise ValueError(
+                    f"Agent is not waiting for user confirmation, "
+                    f"but received UserConfirmResultEvent: {event}",
+                )
+
+            # Given event, required but not match
+            extra_ids = set(
+                _.tool_call.id for _ in event.confirm_results
+            ) - set(awaiting_confirmations)
+            if extra_ids:
+                raise ValueError(
+                    f"Received UserConfirmResultEvent with tool call ids "
+                    f"{extra_ids} that are not waiting for confirmation.",
+                )
+
+        if isinstance(event, ExternalExecutionResultEvent):
+            if not awaiting_external_executions:
+                raise ValueError(
+                    f"Agent is not waiting for external execution result, "
+                    f"but received ExternalExecutionResultEvent: {event}",
+                )
+
+            extra_ids = set(_.id for _ in event.execution_results) - set(
+                awaiting_external_executions,
+            )
+            if extra_ids:
+                raise ValueError(
+                    f"Received ExternalExecutionResultEvent with tool call "
+                    f"ids {extra_ids} that are not waiting for external "
+                    f"execution results.",
+                )
+
+        return event is not None
+
+    async def _handle_incoming_event(
+        self,
+        event: UserConfirmResultEvent | ExternalExecutionResultEvent | None,
+    ) -> AsyncGenerator[
+        ToolResultStartEvent
+        | ToolResultTextDeltaEvent
+        | ToolResultDataDeltaEvent
+        | ToolResultEndEvent,
+        None,
+    ]:
+        """Handle the incoming event and update the context accordingly.
+
+        Args:
+            event (`UserConfirmResultEvent | ExternalExecutionResultEvent \
+            | None`):
+                The incoming event to be handled.
+
+        Yields:
+            `ToolResultStartEvent \
+            | ToolResultTextDeltaEvent \
+            | ToolResultDataDeltaEvent \
+            | ToolResultEndEvent`:
+                The events generated during the handling of the incoming event.
+        """
+        # Return directly if no event
+        if event is None or len(self.state.context) == 0:
+            return
+
+        if isinstance(event, UserConfirmResultEvent):
+            # The confirmed tool calls
+            confirmed_tool_calls = {
+                _.tool_call.id: _ for _ in event.confirm_results
+            }
+
+            # Update the state with the confirmed tool calls
+            last_msg = self.state.context[-1]
+            for tool_call in last_msg.get_content_blocks("tool_call"):
+                if len(confirmed_tool_calls) == 0:
+                    break
+
+                if tool_call.id in confirmed_tool_calls:
+                    confirmation = confirmed_tool_calls[tool_call.id]
+                    if confirmation.confirmed:
+                        # Update state and wait for execution in the next step
+                        self._update_tool_call_state(
+                            tool_call.id,
+                            ToolCallState.ALLOWED,
+                        )
+
+                        # Update name and  input in case user modification is
+                        # allowed
+                        tool_call.name = confirmation.tool_call.name
+                        tool_call.input = confirmation.tool_call.input
+
+                        # Update the permission rule if accepted
+                        if confirmation.rules:
+                            for rule in confirmation.rules:
+                                self._engine.add_rule(rule)
+
+                    else:
+                        # Update the state to deny and handling
+                        async for evt in self._handle_error_tool_call(
+                            tool_call,
+                            message=(
+                                "<system-reminder>The execution of tool "
+                                f'"{tool_call.name}" is denied by user!'
+                                "</system-reminder>"
+                            ),
+                            state=ToolResultState.DENIED,
+                        ):
+                            yield evt
+
+                    # Delete for quick lookup and later processing
+                    confirmed_tool_calls.pop(tool_call.id)
+
+        elif isinstance(event, ExternalExecutionResultEvent):
+            # Directly append the execution results into context
+            for tool_result in event.execution_results:
+                async for evt in self._convert_tool_chunk_to_event(
+                    tool_result.id,
+                    tool_result.output,
+                ):
+                    yield evt
+
+                yield ToolResultEndEvent(
+                    reply_id=self.state.reply_id,
+                    tool_call_id=tool_result.id,
+                    state=tool_result.state,
+                    metadata=tool_result.metadata,
+                )
+
+                self._save_to_context([tool_result])
+
+                # Update the state according to the execution result state
+                self._update_tool_call_state(
+                    tool_result.id,
+                    ToolCallState.FINISHED,
+                )
+
+        else:
+            raise ValueError(f"Invalid event type: {event}")
+
+    async def _handle_incoming_messages(
+        self,
+        msgs: Msg | list[Msg] | None,
+    ) -> None:
+        """Check and handle the incoming messages before the reasoning-acting
+        loop."""
+        if msgs:
+            copied_msgs: list = deepcopy(msgs)
+            if isinstance(copied_msgs, Msg):
+                copied_msgs = [copied_msgs]
+            for msg in copied_msgs:
+                if (
+                    not isinstance(msg, Msg)
+                    or msg.role == "system"
+                    or msg.has_content_blocks(
+                        ["tool_call", "tool_result", "thinking"],
+                    )
+                ):
+                    raise ValueError(
+                        f"Invalid message in the input: {msg}. "
+                        f"The message should be a Msg object with "
+                        f"role 'user' or 'assistant', "
+                        f"and should not contain tool calls, "
+                        f"tool results or thinking blocks.",
+                    )
+
+                self.state.context.append(msg)
+
+    async def _batch_tool_calls(self) -> list[_ToolCallBatch]:
+        """Batch the tool calls into a sequence of batches that should be
+        executed **sequentially** or **concurrently** according to the tool
+        properties `is_concurrency_safe` and `is_read_only`.
+        """
+        # All tool calls that haven't the corresponding results in the context
+        tool_calls = self._get_executable_tool_calls()
+
+        # Batch the tool calls according to whether they can be executed
+        # concurrently or not
+        batches: list[_ToolCallBatch] = []
+        for tool_call in tool_calls:
+            tool = await self.toolkit.get_tool(tool_call.name)
+
+            # Treat unregistered or unavailable tools as concurrent tools since
+            # it will not generate side effects and be blocked with acting
+            if tool is None or tool.is_concurrency_safe:
+                if len(batches) == 0 or batches[-1].type != "concurrent":
+                    batches.append(
+                        _ToolCallBatch(
+                            type="concurrent",
+                            tool_calls=[tool_call],
+                        ),
+                    )
+                else:
+                    batches[-1].tool_calls.append(tool_call)
+            else:
+                if len(batches) == 0 or batches[-1].type != "sequential":
+                    batches.append(
+                        _ToolCallBatch(
+                            type="sequential",
+                            tool_calls=[tool_call],
+                        ),
+                    )
+                else:
+                    batches[-1].tool_calls.append(tool_call)
+
+        return batches
+
+    async def _execute_sequential_tool_calls(
+        self,
+        tool_calls: list[ToolCallBlock],
+    ) -> AsyncGenerator[
+        RequireUserConfirmEvent
+        | RequireExternalExecutionEvent
+        | ToolResultStartEvent
+        | ToolResultTextDeltaEvent
+        | ToolResultDataDeltaEvent
+        | ToolResultEndEvent,
+        None,
+    ]:
+        """Execute the given tool calls sequentially and yield the events.
+
+        If "RequireUserConfirmEvent" or "RequireExternalExecutionEvent" is
+        yielded during the execution, the execution will be paused in the
+        sequential mode and wait for the outside trigger events.
+
+        Args:
+            tool_calls (`list[ToolCallBlock]`):
+                The tool calls to be executed sequentially.
+
+        Yields:
+            `RequireUserConfirmEvent \
+            | RequireExternalExecutionEvent \
+            | ToolResultStartEvent \
+            | ToolResultTextDeltaEvent \
+            | ToolResultDataDeltaEvent \
+            | ToolResultEndEvent`:
+                The events generated during the execution of the tool calls.
+        """
+        break_execution = False
+        for tool_call in tool_calls:
+            async for evt in self._execute_tool_call(tool_call):
+                yield evt
+                if isinstance(
+                    evt,
+                    (
+                        RequireUserConfirmEvent,
+                        RequireExternalExecutionEvent,
+                    ),
+                ) or (
+                    isinstance(evt, ToolResultEndEvent)
+                    and evt.state == ToolResultState.INTERRUPTED
+                ):
+                    break_execution = True
+                    break
+            if break_execution:
+                break
+
+    async def _execute_concurrent_tool_calls(
+        self,
+        tool_calls: list[ToolCallBlock],
+    ) -> AsyncGenerator[
+        RequireUserConfirmEvent
+        | RequireExternalExecutionEvent
+        | ToolResultStartEvent
+        | ToolResultTextDeltaEvent
+        | ToolResultDataDeltaEvent
+        | ToolResultEndEvent,
+        None,
+    ]:
+        """Execute the given tool calls concurrently and yield the events.
+
+        All tool calls are executed concurrently. If one or more tool calls
+        fail, the remaining ones are **not** cancelled and will run to
+        completion. After all tool calls finish, every exception is collected
+        and re-raised together as an :py:exc:`ExceptionGroup` so the caller
+        can inspect each failure individually.
+
+        The event stream is guaranteed to be complete: the loop exits only
+        after a sentinel value placed by the gather task is received, which
+        means every ``queue.put`` from every worker has already finished
+        before the generator returns.
+
+        If the caller task is cancelled from outside, the concurrent worker
+        tasks are cancelled explicitly (to avoid orphan tasks), any events
+        already queued by the workers (including interruption chunks emitted
+        by ``toolkit.call_tool`` when it catches ``CancelledError``) are
+        flushed to the caller, and the generator returns normally. The
+        caller is expected to detect the interruption via the flushed
+        ``ToolResultEndEvent(state=INTERRUPTED)`` events, mirroring the
+        event-based propagation used by
+        :meth:`_execute_sequential_tool_calls`.
+
+        Args:
+            tool_calls (`list[ToolCallBlock]`):
+                The tool calls to be executed concurrently.
+
+        Yields:
+            `RequireUserConfirmEvent \
+            | RequireExternalExecutionEvent \
+            | ToolResultStartEvent \
+            | ToolResultTextDeltaEvent \
+            | ToolResultDataDeltaEvent \
+            | ToolResultEndEvent`:
+                The events generated during the execution of the tool calls.
+
+        Raises:
+            `ExceptionGroup`:
+                Raised after all tool calls finish when one or more of them
+                raised an exception. Each individual exception is included in
+                the group.
+        """
+        # A sentinel object that signals all worker tasks have finished and
+        # all events have already been put into the queue.
+        sentinel = object()
+
+        # Create a queue to collect events from all concurrent workers.
+        queue: Queue = Queue()
+
+        async def _run_all() -> list[BaseException | None]:
+            """Run all tool calls concurrently and push the sentinel when done.
+
+            Returns:
+                `list[BaseException | None]`:
+                    One entry per tool call. Each entry is either ``None``
+                    (success) or the exception raised by that tool call.
+            """
+            # return_exceptions=True keeps all tasks running even when some
+            # fail, and returns exceptions as values instead of re-raising.
+            results = await asyncio.gather(
+                *[self._into_queue(tc, queue) for tc in tool_calls],
+                return_exceptions=True,
+            )
+            # The sentinel is placed AFTER gather returns, which guarantees
+            # that every queue.put inside _into_queue has already completed.
+            await queue.put(sentinel)
+            return results  # type: ignore[return-value]
+
+        gather_task = asyncio.create_task(_run_all())
+
+        try:
+            # Drain the queue until the sentinel is encountered.
+            while True:
+                event = await queue.get()
+                if event is sentinel:
+                    break
+                yield event
+        except asyncio.CancelledError:
+            # Cancel the gather tasks, which will be handled within the toolkit
+            gather_task.cancel()
+            try:
+                await gather_task
+            except asyncio.CancelledError:
+                pass
+            while True:
+                try:
+                    event = queue.get_nowait()
+                except asyncio.QueueEmpty:
+                    break
+                if event is sentinel:
+                    continue
+                yield event
+            # Consume the cancel so this generator returns normally. The
+            # caller relies on the flushed ``ToolResultEndEvent(state=
+            # INTERRUPTED)`` events, not on the exception, to detect the
+            # interruption — mirroring the event-based propagation used by
+            # :meth:`_execute_sequential_tool_calls`.
+            asyncio.current_task().uncancel()
+            return
+
+        # All tasks are done at this point; collect and re-raise exceptions.
+        results = await gather_task
+        exceptions = [r for r in results if isinstance(r, Exception)]
+        if exceptions:
+            raise ExceptionGroup(
+                "One or more tool calls raised an exception",
+                exceptions,
+            )
+
+    async def _into_queue(
+        self,
+        tool_call: ToolCallBlock,
+        queue: Queue,
+    ) -> None:
+        """Execute a single tool call and forward every event into *queue*.
+
+        Args:
+            tool_call (`ToolCallBlock`):
+                The tool call to execute.
+            queue (`Queue`):
+                The shared async queue that collects events from all
+                concurrent workers.
+        """
+        async for evt in self._execute_tool_call(tool_call):
+            await queue.put(evt)
+
+    async def _execute_tool_call(
+        self,
+        tool_call: ToolCallBlock,
+    ) -> AsyncGenerator[
+        RequireUserConfirmEvent
+        | RequireExternalExecutionEvent
+        | ToolResultStartEvent
+        | ToolResultTextDeltaEvent
+        | ToolResultDataDeltaEvent
+        | ToolResultEndEvent,
+        None,
+    ]:
+        """Execute a single tool call with permission checking and context
+        management.
+
+        This method handles the full tool call lifecycle: input validation,
+        permission checking, event emission, and context writes.  The raw
+        tool execution (``toolkit.call_tool``) is delegated to
+        :meth:`_acting`, which is the hook point for ``on_acting``
+        middleware.
+
+        Args:
+            tool_call (`ToolCallBlock`):
+                The tool call block to be executed.
+
+        Yields:
+            `RequireUserConfirmEvent \
+            | RequireExternalExecutionEvent \
+            | ToolResultStartEvent \
+            | ToolResultTextDeltaEvent \
+            | ToolResultDataDeltaEvent \
+            | ToolResultEndEvent`:
+                The events generated during the tool call execution.
+        """
+        # ===================================================================
+        # Step 1: Check and parse the tool call input:
+        #  - if failed, directly return the error message to the agent
+        #  - if success, continue to permission checking and tool execution
+        # ===================================================================
+        try:
+            # Check if the tool is available
+            tool = await self.toolkit.check_tool_available(
+                tool_call.name,
+                self.state.tool_context.activated_groups,
+            )
+
+            # Try to parse the input with the tool schema
+            parsed_input = _json_loads_with_repair(
+                tool_call.input,
+                tool.input_schema,
+            )
+
+            # Validate the parsed input with the tool schema
+            # TODO: Maybe some logic to mix the validation error in runtime
+            try:
+                jsonschema.validate(parsed_input, tool.input_schema)
+            except jsonschema.ValidationError as e:
+                raise AgentOrientedException(
+                    f"Input validation failed for tool '{tool_call.name}': "
+                    f"{e.message}",
+                ) from e
+
+        # The exceptions that
+        #  - cannot found tool
+        #  - tool not available
+        #  - input parsing failure
+        except AgentOrientedException as e:
+            async for evt in self._handle_error_tool_call(
+                tool_call,
+                e.message,
+                state=ToolResultState.ERROR,
+            ):
+                yield evt
+
+            return
+
+        # ===================================================================
+        # Step 2: Check permission by toolkit and permission engine
+        # ===================================================================
+        if tool_call.state == ToolCallState.ALLOWED:
+            # Already allowed by user confirmation, skip permission checking
+            decision = PermissionDecision(
+                behavior=PermissionBehavior.ALLOW,
+                message="Already allowed by user confirmation.",
+            )
+        else:
+            decision = await self._engine.check_permission(
+                tool,
+                parsed_input,
+            )
+
+        # ===================================================================
+        # Step 3: Handle the permission and execute the tool call if allowed
+        # ===================================================================
+
+        # Case 1: Ask for user confirmation if needed
+        if decision.behavior in [
+            PermissionBehavior.ASK,
+            PermissionBehavior.PASSTHROUGH,
+        ]:
+            # Set the state of the tool call to "ask"
+            # **Note** the update must be done before yielding the event
+            self._update_tool_call_state(
+                tool_call.id,
+                ToolCallState.ASKING,
+            )
+
+            tool_call.suggested_rules = decision.suggested_rules or []
+            yield RequireUserConfirmEvent(
+                reply_id=self.state.reply_id,
+                tool_calls=[tool_call],
+            )
+            return
+
+        # Case 2: Denied by the permission system
+        if decision.behavior == PermissionBehavior.DENY:
+            async for evt in self._handle_error_tool_call(
+                tool_call,
+                decision.message,
+                state=ToolResultState.DENIED,
+            ):
+                yield evt
+
+            return
+
+        # Case 3: Allowed by the permission system, execute the tool call and
+        #  yield the events
+        if decision.behavior == PermissionBehavior.ALLOW:
+            self._update_tool_call_state(
+                tool_call.id,
+                ToolCallState.ALLOWED,
+            )
+            # Send start event
+            yield ToolResultStartEvent(
+                reply_id=self.state.reply_id,
+                tool_call_id=tool_call.id,
+                tool_call_name=tool_call.name,
+            )
+            # Send requiring external execution event if it's an external tool
+            if tool.is_external_tool:
+                # Update the state to "submitted" BEFORE yielding
+                # because the outer loop will break immediately after
+                # receiving this event, preventing any code after yield
+                # from executing
+                self._update_tool_call_state(
+                    tool_call.id,
+                    ToolCallState.SUBMITTED,
+                )
+                yield RequireExternalExecutionEvent(
+                    reply_id=self.state.reply_id,
+                    tool_calls=[tool_call],
+                )
+                return
+
+            # ================================================================
+            # Step 4: Delegate raw execution to _acting (middleware hook point)
+            # ================================================================
+            async for chunk in self._acting(tool_call):
+                # The ToolResponse is the last and completed tool result here
+                if isinstance(chunk, ToolResponse):
+                    tool_result_block = ToolResultBlock(
+                        id=tool_call.id,
+                        name=tool_call.name,
+                        output=[TextBlock(text=chunk.content)]
+                        if isinstance(chunk.content, str)
+                        else chunk.content,
+                        state=chunk.state,
+                        metadata=chunk.metadata,
+                    )
+
+                    # ========================================================
+                    # Step 5: Truncate the tool result if exceed
+                    # ========================================================
+                    (
+                        reserved_tool_result_block,
+                        offload_tool_result_block,
+                    ) = await self._split_tool_result_for_compression(
+                        tool_result_block,
+                    )
+
+                    # If offload result is not empty, attach reminder to the
+                    # reserved context
+                    if offload_tool_result_block is not None:
+                        reminder = (
+                            "\n<<<TRUNCATED>>>\n<system-reminder>The "
+                            "remaining content has been omitted for "
+                            "limited context.{offload_reminder}"
+                            "</system-reminder>"
+                        )
+
+                        offload_reminder = ""
+                        if self.offloader:
+                            path = await self.offloader.offload_tool_result(
+                                self.state.session_id,
+                                offload_tool_result_block,
+                            )
+
+                            offload_reminder = (
+                                f" You can refer to the file in '{path}' "
+                                f"for the truncated content if needed."
+                            )
+
+                        reminder = reminder.format(
+                            offload_reminder=offload_reminder,
+                        )
+
+                        # Insert the reminder to the tool result output
+                        if isinstance(reserved_tool_result_block.output, str):
+                            reserved_tool_result_block.output += reminder
+
+                        elif len(
+                            reserved_tool_result_block.output,
+                        ) > 0 and isinstance(
+                            reserved_tool_result_block.output[-1],
+                            TextBlock,
+                        ):
+                            reserved_tool_result_block.output[
+                                -1
+                            ].text += reminder
+
+                        else:
+                            reserved_tool_result_block.output += [
+                                TextBlock(text=reminder),
+                            ]
+
+                    self._save_to_context([reserved_tool_result_block])
+                    # Ends the tool call lifecycle.
+                    self._update_tool_call_state(
+                        tool_call.id,
+                        ToolCallState.FINISHED,
+                    )
+                    # The ended event for the tool result
+                    yield ToolResultEndEvent(
+                        reply_id=self.state.reply_id,
+                        tool_call_id=tool_call.id,
+                        state=chunk.state,
+                        metadata=chunk.metadata,
+                    )
+
+                else:
+                    # Intermediate ToolChunk — convert to streaming events
+                    async for evt in self._convert_tool_chunk_to_event(
+                        tool_call.id,
+                        chunk.content,
+                    ):
+                        yield evt
+
+            return
+
+        raise ValueError(
+            f"Invalid permission decision behavior: {decision.behavior}",
+        )
+
+    async def _acting(
+        self,
+        tool_call: ToolCallBlock,
+    ) -> AsyncGenerator["ToolChunk | ToolResponse", None]:
+        """Raw tool execution entry point (maybe wrapped by middleware).
+
+        This method is the hook point for ``on_acting`` middleware.  It
+        delegates to :meth:`_acting_impl` which wraps
+        ``toolkit.call_tool`` directly.  Permission checking and context
+        writes are **not** part of this method — they are handled by
+        :meth:`_execute_tool_call` before and after this call.
+
+        Args:
+            tool_call (`ToolCallBlock`):
+                The tool call block to execute.
+
+        Yields:
+            `ToolChunk | ToolResponse`:
+                Intermediate :class:`~agentscope.tool.ToolChunk` objects
+                followed by a final :class:`~agentscope.tool.ToolResponse`.
+        """
+        if not self._acting_middlewares:
+            async for item in self._acting_impl(tool_call):
+                yield item
+        else:
+
+            async def execute_chain(
+                index: int = 0,
+                tool_call: ToolCallBlock = tool_call,
+            ) -> AsyncGenerator:
+                if index >= len(self._acting_middlewares):
+                    async for item in self._acting_impl(tool_call):
+                        yield item
+                else:
+                    mw = self._acting_middlewares[index]
+                    input_kwargs = {"tool_call": tool_call}
+
+                    async def next_handler(**kwargs: Any) -> AsyncGenerator:
+                        async for item in execute_chain(
+                            index + 1,
+                            **{**input_kwargs, **kwargs},
+                        ):
+                            yield item
+
+                    async for item in mw.on_acting(
+                        agent=self,
+                        input_kwargs=input_kwargs,
+                        next_handler=next_handler,
+                    ):
+                        yield item
+
+            async for item in execute_chain():
+                yield item
+
+    async def _acting_impl(
+        self,
+        tool_call: ToolCallBlock,
+    ) -> AsyncGenerator["ToolChunk | ToolResponse", None]:
+        """Core tool execution logic.
+
+        Wraps :meth:`~agentscope.tool.Toolkit.call_tool` and yields its
+        output unchanged.  Does **not** perform permission checking or
+        write to the agent context — those responsibilities belong to
+        :meth:`_execute_tool_call`.
+
+        .. note::
+            Tools with ``is_state_injected=True`` receive the live
+            ``agent.state`` object.  Offloading such tools to a background
+            task (via ``on_acting`` middleware) may cause concurrent state
+            mutations.  TODO: block background offloading for
+            state-injected tools.
+
+        Args:
+            tool_call (`ToolCallBlock`):
+                The tool call block to execute.
+
+        Yields:
+            `ToolChunk | ToolResponse`:
+                Intermediate :class:`~agentscope.tool.ToolChunk` objects
+                followed by a final :class:`~agentscope.tool.ToolResponse`.
+        """
+        async for chunk in self.toolkit.call_tool(tool_call, self.state):
+            yield chunk
+
+    async def _handle_error_tool_call(
+        self,
+        tool_call: ToolCallBlock,
+        message: str,
+        state: ToolResultState,
+    ) -> AsyncGenerator[
+        ToolResultStartEvent
+        | ToolResultTextDeltaEvent
+        | ToolResultDataDeltaEvent
+        | ToolResultEndEvent,
+        None,
+    ]:
+        """A quick handling for the non-streaming tool results, and ends the
+        lifecycle of the tool call by updating its state to "finished".
+
+        Args:
+            tool_call (`ToolCallBlock`):
+                The tool call block that has errors.
+            message (`str`):
+                The error message to be returned for the tool call.
+            state (`ToolResultState`):
+                The state of the tool result, such as "error" or "denied".
+
+        Yields:
+            `ToolResultStartEvent \
+            | ToolResultTextDeltaEvent \
+            | ToolResultDataDeltaEvent \
+            | ToolResultEndEvent`:
+                The events generated for the error tool call.
+        """
+
+        yield ToolResultStartEvent(
+            reply_id=self.state.reply_id,
+            tool_call_id=tool_call.id,
+            tool_call_name=tool_call.name,
+        )
+
+        result = ToolChunk(
+            content=[TextBlock(text=message)],
+            state=state,
+        )
+
+        # Return the result directly to the agent
+        self._save_to_context(
+            [
+                ToolResultBlock(
+                    id=tool_call.id,
+                    name=tool_call.name,
+                    output=message,
+                    state=state,
+                ),
+            ],
+        )
+
+        async for evt in self._convert_tool_chunk_to_event(
+            tool_call.id,
+            result.content,
+        ):
+            yield evt
+
+        yield ToolResultEndEvent(
+            reply_id=self.state.reply_id,
+            tool_call_id=tool_call.id,
+            state=state,
+        )
+
+        self._update_tool_call_state(
+            tool_call.id,
+            ToolCallState.FINISHED,
+        )
+
+    # =======================================================================
+    # Context management related methods
+    # =======================================================================
+
+    async def _split_context_for_compression(
+        self,
+        to_reserved_tokens: float,
+        tools: list[dict],
+    ) -> tuple[list[Msg], list[Msg]]:
+        """Split context into parts to compress and parts to keep recent.
+
+        Args:
+            to_reserved_tokens (`float`):
+                The tokens to be reserved.
+            tools (`list[dict]`):
+                The tools JSON schemas used for token counting.
+
+        Returns:
+            `tuple[list[Msg], list[Msg]]`:
+                The message objects to be compressed and reserved during
+                context compression.
+        """
+
+        # The system prompt
+        system_msg = [
+            SystemMsg(name="system", content=await self._get_system_prompt()),
+        ]
+
+        # Append the current summary if exists
+        if self.state.summary:
+            system_msg.append(
+                UserMsg("user", self.state.summary),
+            )
+
+        msg_index = len(self.state.context) - 1
+        while msg_index >= 0:
+            # Count the tokens when msgs after msg_index are reserved
+            reserved_tokens = await self.model.count_tokens(
+                system_msg + self.state.context[msg_index:],
+                tools,
+            )
+            # If reserved tokens exceed the limit
+            if reserved_tokens >= to_reserved_tokens:
+                break
+            msg_index -= 1
+
+        if msg_index < 0:
+            return [], deepcopy(self.state.context)
+
+        # The msgs that won't exceed the reserved token limit
+        msgs_to_compress = self.state.context[:msg_index]
+        msgs_to_reserve = self.state.context[msg_index + 1 :]
+        boundary_msg = self.state.context[msg_index]
+
+        # Handle the boundary Msg
+        boundary_msg_to_compress = deepcopy(boundary_msg)
+        boundary_msg_to_reserve = deepcopy(boundary_msg)
+
+        attempt_msg = deepcopy(boundary_msg)
+
+        boundary_msg_content = boundary_msg.get_content_blocks()
+        block_index = len(boundary_msg_content) - 1
+        while block_index >= 0:
+            attempt_msg.content = boundary_msg_content[block_index:]
+
+            try_reserved = system_msg + [attempt_msg] + msgs_to_reserve
+            reserved_tokens = await self.model.count_tokens(
+                try_reserved,
+                tools,
+            )
+            if reserved_tokens > to_reserved_tokens:
+                break
+            block_index -= 1
+
+        # Adjust the block_index to avoid splitting tool call and result pairs
+
+        # Check if the reserved part has tool results that don't have the
+        # corresponding tool calls
+        remain_result_ids = {}
+        for i in range(len(boundary_msg_content) - 1, block_index, -1):
+            block = boundary_msg_content[i]
+            if isinstance(block, ToolResultBlock):
+                remain_result_ids[block.id] = i
+            elif isinstance(block, ToolCallBlock):
+                remain_result_ids.pop(block.id, None)
+
+        # Find the largest index of the remaining tool results, which doesn't
+        # have the corresponding tool calls in the reserved parts
+        if remain_result_ids:
+            block_index = max(remain_result_ids.values())
+
+        # Split the boundary msg content
+        boundary_msg_to_compress.content = boundary_msg_content[
+            : block_index + 1
+        ]
+        boundary_msg_to_reserve.content = boundary_msg_content[
+            block_index + 1 :
+        ]
+
+        if len(boundary_msg_to_compress.content) > 0:
+            msgs_to_compress += [boundary_msg_to_compress]
+
+        if len(boundary_msg_to_reserve.content) > 0:
+            msgs_to_reserve = [boundary_msg_to_reserve] + msgs_to_reserve
+
+        return msgs_to_compress, msgs_to_reserve
+
+    async def _clear_unreserved_read_cache(
+        self,
+        msgs_to_reserve: list[Msg],
+    ) -> None:
+        """Clean Read caches not referenced by reserved Read tool calls."""
+        reserved_paths: set[str] = set()
+        for msg in msgs_to_reserve:
+            for block in msg.get_content_blocks("tool_call"):
+                if not (
+                    isinstance(block, ToolCallBlock) and block.name == "Read"
+                ):
+                    continue
+
+                try:
+                    tool_input = _json_loads_with_repair(block.input)
+                except Exception:  # pylint: disable=broad-exception-caught
+                    continue
+
+                file_path = tool_input.get("file_path")
+                if isinstance(file_path, str):
+                    reserved_paths.add(file_path)
+
+        await self.state.tool_context.clean_file_cache(
+            reserved_file_paths=reserved_paths,
+        )
+
+    async def _split_tool_result_for_compression(
+        self,
+        tool_result: ToolResultBlock,
+    ) -> tuple[ToolResultBlock, ToolResultBlock | None]:
+        """Split the tool result for compression.
+
+        Args:
+            tool_result (`ToolResultBlock`):
+                The tool result block.
+
+        Returns:
+            `tuple[ToolResultBlock, ToolResultBlock | None]`:
+                A tuple of the tool result blocks to reserved in context and
+                to offload (if any).
+        """
+        n_tokens = await self.model.count_tokens(
+            [AssistantMsg(self.name, content=tool_result.output)],
+            None,
+        )
+
+        # Return the tool result without truncation
+        if n_tokens <= self.context_config.tool_result_limit:
+            return tool_result, None
+
+        # Use a copied block for token counting
+        copied_tool_result = deepcopy(tool_result)
+
+        # Normalized into content blocks
+        if isinstance(copied_tool_result.output, str):
+            copied_tool_result.output = [
+                TextBlock(text=copied_tool_result.output),
+            ]
+
+        # Find the index of the block that will exceed the limit
+        boundary_index = 0
+        for i in range(len(copied_tool_result.output) - 1, 0, -1):
+            copied_tool_result.output = tool_result.output[:i]
+            cur_tokens = await self.model.count_tokens(
+                [
+                    AssistantMsg(
+                        self.name,
+                        content=copied_tool_result.output,
+                    ),
+                ],
+                None,
+            )
+            if cur_tokens < self.context_config.tool_result_limit:
+                boundary_index = i
+                break
+
+        # The blocks to reserve and offload (deep copy to avoid
+        # modifying original)
+        reserved_blocks: list = [
+            deepcopy(b) for b in tool_result.output[:boundary_index]
+        ]
+        offload_blocks: list = [
+            deepcopy(b) for b in tool_result.output[boundary_index + 1 :]
+        ]
+
+        # Get the boundary block, if text block, we can truncate it
+        boundary_block = tool_result.output[boundary_index]
+        if isinstance(boundary_block, TextBlock):
+            # Truncate it
+            truncated_text = boundary_block.text
+            cur_tokens = await self.model.count_tokens(
+                [AssistantMsg(self.name, content=reserved_blocks)],
+                None,
+            )
+            cur_tokens_plus = await self.model.count_tokens(
+                [
+                    AssistantMsg(
+                        self.name,
+                        content=reserved_blocks + [boundary_block],
+                    ),
+                ],
+                None,
+            )
+            # Truncate the text by proportion of tokens
+            token_delta = cur_tokens_plus - cur_tokens
+            remaining_token_budget = (
+                self.context_config.tool_result_limit - cur_tokens
+            )
+            if token_delta <= 0:
+                reserved_tokens = (
+                    len(truncated_text) if remaining_token_budget > 0 else 0
+                )
+            else:
+                reserved_tokens = int(
+                    remaining_token_budget / token_delta * len(truncated_text),
+                )
+            reserved_tokens = max(
+                0,
+                min(len(truncated_text), reserved_tokens),
+            )
+
+            reserved_text = truncated_text[:reserved_tokens]
+            offload_text = truncated_text[reserved_tokens:]
+
+            if reserved_text:
+                if (
+                    len(reserved_blocks) > 0
+                    and reserved_blocks[-1].type == "text"
+                ):
+                    reserved_blocks[-1].text += reserved_text
+
+                else:
+                    reserved_blocks.append(
+                        TextBlock(text=reserved_text, id=boundary_block.id),
+                    )
+
+            if offload_text:
+                if (
+                    len(offload_blocks) > 0
+                    and offload_blocks[0].type == "text"
+                ):
+                    offload_blocks[0].text = (
+                        offload_text + offload_blocks[0].text
+                    )
+
+                else:
+                    offload_blocks.insert(
+                        0,
+                        TextBlock(text=offload_text, id=boundary_block.id),
+                    )
+
+        else:
+            # Drop the boundary block if inseparable
+            offload_blocks.insert(0, boundary_block)
+
+        if len(offload_blocks) == 0:
+            return tool_result, None
+
+        # Create new ToolResultBlock instances for reserved and offload
+        reserved_tool_result = ToolResultBlock(
+            id=tool_result.id,
+            name=tool_result.name,
+            output=reserved_blocks,
+            state=tool_result.state,
+        )
+        offload_tool_result = ToolResultBlock(
+            id=tool_result.id,
+            name=tool_result.name,
+            output=offload_blocks,
+            state=tool_result.state,
+        )
+
+        return reserved_tool_result, offload_tool_result
+
+    # ======================================================================
+    # Agent internal utility methods
+    # ======================================================================
+    async def _get_system_prompt(self) -> str:
+        """Get the system prompt of the agent."""
+        prompt = [self._system_prompt]
+
+        # Skill related instructions
+        skill_instructions = await self.toolkit.get_skill_instructions(
+            self.state.tool_context.activated_groups,
+        )
+        if skill_instructions:
+            prompt.append(skill_instructions)
+
+        # Workspace & offloader instructions
+        if isinstance(self.offloader, WorkspaceBase):
+            offload_instructions = await self.offloader.get_instructions()
+            if offload_instructions:
+                prompt.append(offload_instructions)
+
+        result = "\n".join(prompt)
+
+        # Apply system_prompt middlewares sequentially (transformer pattern)
+        for mw in self._system_prompt_middlewares:
+            result = await mw.on_system_prompt(self, result)
+
+        return result
+
+    async def _prepare_model_input(self) -> dict[str, Any]:
+        """A unified method to prepare the chat model input according to
+        the current context.
+
+        Returns:
+            `dict[str, Any]`
+                The keyword arguments passed to the model.
+        """
+        # The system prompt
+        messages = [
+            SystemMsg(name="system", content=await self._get_system_prompt()),
+        ]
+        # The compressed summary
+        if self.state.summary:
+            messages.append(
+                UserMsg(name="user", content=self.state.summary),
+            )
+        # The conversation context
+        messages.extend(self.state.context)
+
+        # Get the tools schemas
+        tools = await self.toolkit.get_tool_schemas(
+            self.state.tool_context.activated_groups,
+        )
+
+        return {
+            "messages": messages,
+            "tools": tools,
+        }
+
+    async def _call_model(
+        self,
+        messages: list[Msg],
+        tools: list[dict],
+        tool_choice: ToolChoice | None = None,
+    ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:
+        """Perform model inference with retry logic and middleware support.
+
+        Args:
+            messages (`list[Msg]`):
+                The input messages to the model.
+            tools (`list[dict]`):
+                The function schemas of the tools.
+            tool_choice (`ToolChoice | None`, optional):
+                The tool choice strategy for the model call.
+
+        Returns:
+            `ChatResponse | AsyncGenerator[ChatResponse, None]`:
+                The model response, which can be a `ChatResponse` for
+                non-streaming models, or an async generator yielding
+                `ChatResponse` chunks for streaming models.
+        """
+        models = [self.model]
+
+        # Fallback to the secondary model if the primary model fails after
+        # retries
+        if self.model_config.fallback_model:
+            models.append(self.model_config.fallback_model)
+
+        last_exception = None
+        # ``max_retries`` is the number of retries on top of the initial
+        # call (mirrors ``ChatModelBase.max_retries``), so total attempts
+        # per model is ``max_retries + 1``.
+        for index, model in enumerate(models):
+            if index > 0:
+                logger.info(
+                    "Fallback to model '%s'",
+                    model.model,
+                )
+
+            for attempt in range(self.model_config.max_retries + 1):
+                try:
+                    # Apply middleware to wrap the actual model() call
+                    if not self._model_call_middlewares:
+                        return await model(
+                            messages=messages,
+                            tools=tools,
+                            tool_choice=tool_choice,
+                        )
+                    else:
+                        # pylint: disable=cell-var-from-loop
+                        async def execute_chain(
+                            index: int = 0,
+                            current_model: ChatModelBase = model,
+                            messages: list[Msg] = messages,
+                            tools: list[dict] = tools,
+                            tool_choice: ToolChoice = tool_choice,
+                        ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:
+                            """Execute the model chain."""
+                            if index >= len(self._model_call_middlewares):
+                                return await current_model(
+                                    messages=messages,
+                                    tools=tools,
+                                    tool_choice=tool_choice,
+                                )
+                            else:
+                                mw = self._model_call_middlewares[index]
+                                input_kwargs = {
+                                    "current_model": current_model,
+                                    "messages": messages,
+                                    "tools": tools,
+                                    "tool_choice": tool_choice,
+                                }
+
+                                async def next_handler(
+                                    **kwargs: Any,
+                                ) -> (
+                                    ChatResponse
+                                    | AsyncGenerator[ChatResponse, None]
+                                ):
+                                    # pylint: disable=cell-var-from-loop
+                                    return await execute_chain(
+                                        index + 1,
+                                        **{**input_kwargs, **kwargs},
+                                    )
+
+                                return await mw.on_model_call(
+                                    agent=self,
+                                    input_kwargs=input_kwargs,
+                                    next_handler=next_handler,
+                                )
+
+                        return await execute_chain()
+                except Exception as e:
+                    last_exception = e
+                    # Only log a "Retrying" message when there's actually a
+                    # next attempt left for this model. When ``max_retries=0``
+                    # or the last retry has been used, the outer loop either
+                    # falls over to the fallback or raises.
+                    if attempt < self.model_config.max_retries:
+                        logger.warning(
+                            "Model %s call failed for agent %s. "
+                            "Retrying (%d/%d)...",
+                            model.model,
+                            self.name,
+                            attempt + 1,
+                            self.model_config.max_retries,
+                        )
+                    else:
+                        logger.warning(
+                            "Model %s exhausted all %d attempt(s) "
+                            "for agent %s.",
+                            model.model,
+                            self.model_config.max_retries + 1,
+                            self.name,
+                        )
+
+        if last_exception:
+            raise last_exception from None
+
+        raise RuntimeError(
+            "Model call failed after retries, but no exception was raised.",
+        )
+
+    def _update_tool_call_state(
+        self,
+        tool_call_id: str,
+        state: ToolCallState,
+    ) -> None:
+        """Update the tool call state. This function is to avoid the update
+        not reflected in the context due to the shallow copy of the content
+        blocks somewhere in the code.
+
+        Args:
+            tool_call_id (`str`):
+                The tool call id to be updated.
+            state (`ToolCallState`):
+                The new state of the tool call.
+        """
+        if len(self.state.context) == 0:
+            return
+        last_msg = self.state.context[-1]
+        if last_msg.role != "assistant" or last_msg.name != self.name:
+            return
+        for block in last_msg.get_content_blocks():
+            if isinstance(block, ToolCallBlock) and block.id == tool_call_id:
+                block.state = state
+                break
+
+    def _save_to_context(
+        self,
+        blocks: Sequence[
+            TextBlock
+            | ThinkingBlock
+            | ToolCallBlock
+            | ToolResultBlock
+            | DataBlock
+        ],
+        usage: ChatUsage | None = None,
+    ) -> None:
+        """Save content blocks into the context.
+
+        Newly created :class:`AssistantMsg` uses ``self.state.reply_id`` as
+        its id so that one reply corresponds to one message and the message
+        id matches the ``reply_id`` carried by streaming events.
+        """
+        msg_usage = (
+            Usage(
+                input_tokens=usage.input_tokens,
+                output_tokens=usage.output_tokens,
+            )
+            if usage is not None
+            else None
+        )
+
+        # Assistant-produced audio (e.g. qwen-omni speaking aloud) is delivered
+        # to the user via streaming events; the raw bytes don't belong in
+        # conversation memory. Filtering here keeps every downstream walker
+        # (formatter, count_tokens, persistence) honest without each having
+        # to remember.
+        persisted_blocks = [
+            b
+            for b in blocks
+            if not (
+                isinstance(b, DataBlock)
+                and isinstance(b.source, (Base64Source, URLSource))
+                and b.source.media_type.startswith("audio/")
+            )
+        ]
+        if not persisted_blocks and msg_usage is None:
+            return
+
+        if len(self.state.context) == 0:
+            self.state.context.append(
+                AssistantMsg(
+                    id=self.state.reply_id,
+                    name=self.name,
+                    content=persisted_blocks,
+                    usage=msg_usage,
+                ),
+            )
+        else:
+            last_msg = self.state.context[-1]
+            if last_msg.role == "assistant" and last_msg.name == self.name:
+                if isinstance(last_msg.content, str):
+                    last_msg.content = [TextBlock(text=last_msg.content)]
+                last_msg.content.extend(persisted_blocks)
+                if msg_usage is not None:
+                    if last_msg.usage is None:
+                        last_msg.usage = msg_usage
+                    else:
+                        last_msg.usage.input_tokens += msg_usage.input_tokens
+                        last_msg.usage.output_tokens += msg_usage.output_tokens
+            else:
+                self.state.context.append(
+                    AssistantMsg(
+                        id=self.state.reply_id,
+                        name=self.name,
+                        content=persisted_blocks,
+                        usage=msg_usage,
+                    ),
+                )
+
+    def _get_last_msg(self) -> Msg | None:
+        """Get the last message in the context that belongs to this agent."""
+        if len(self.state.context) == 0:
+            return None
+        last_msg = self.state.context[-1]
+        if last_msg.role == "assistant" and last_msg.name == self.name:
+            return last_msg
+        return None
+
+    def _check_next_action(
+        self,
+    ) -> (
+        tuple[Literal["exit"], Msg]
+        | tuple[Literal["reasoning"], None]
+        | tuple[Literal["acting"], None]
+    ):
+        """Check the next action for the agent
+
+        Awaiting tool calls:
+            The tool calls waiting for the outside events (confirmation or
+            external execution results, state = "asking" or "submitted")
+        Executable tool calls:
+            The tool calls allowed by the incoming confirmation events and
+            haven't been executed yet (state = "allowed")
+
+        The next action:
+
+        |                          | Awaiting tool calls          | No awaiting tool call        |
+        | ------------------------ | ---------------------------- | ---------------------------- |
+        | Executable tool calls    | Acting executable tool calls | Acting executable tool calls |
+        | No executable tool calls | Exit the _reply              | Reasoning                    |
+
+        Returns:
+            `tuple[Literal["exit"], Msg]`:
+                If there is no executable tool call and there are awaiting tool
+                calls, which means the agent is waiting for the outside events
+                and should not do anything before that, the next action is to
+                exit the _reply and wait for the outside events.
+            `tuple[Literal["reasoning"], None]`:
+                If there is no executable tool call and no awaiting tool call,
+                which means the agent has nothing to do in this iteration and
+                can continue reasoning for the next step.
+            `tuple[Literal["acting"], None]`:
+                If there are executable tool calls, which means the agent can
+                act by executing the tool calls.
+        """  # noqa: E501
+        last_msg = self._get_last_msg()
+        if last_msg is None:
+            return "reasoning", None
+
+        # In case wrong tool call state, first filter with the results
+        finished_ids = {
+            _.id for _ in last_msg.get_content_blocks("tool_result")
+        }
+        unfinished_tool_calls = [
+            _
+            for _ in last_msg.get_content_blocks("tool_call")
+            if _.id not in finished_ids
+        ]
+
+        # Find if there are executable or awaiting tool calls
+        awaiting_tool_calls: list[ToolCallBlock] = []
+        executable_tool_calls: list[ToolCallBlock] = []
+
+        confirming_names, asking_names = [], []
+        for _ in unfinished_tool_calls:
+            if _.state in [ToolCallState.PENDING, ToolCallState.ALLOWED]:
+                executable_tool_calls.append(_)
+
+            elif _.state == ToolCallState.ASKING:
+                asking_names.append(_.name)
+                awaiting_tool_calls.append(_)
+
+            elif _.state == ToolCallState.SUBMITTED:
+                confirming_names.append(_.name)
+                awaiting_tool_calls.append(_)
+
+        if executable_tool_calls:
+            return "acting", None
+
+        if awaiting_tool_calls:
+            # Prepare the message
+            evt = ["I'm waiting for "]
+            if asking_names:
+                evt += [
+                    f"user confirmation for {len(asking_names)} tool calls",
+                ]
+
+            if confirming_names:
+                if evt:
+                    evt += [", and "]
+                evt += [
+                    f"external execution results for {len(confirming_names)} "
+                    f"tool calls",
+                ]
+
+            text = "".join(evt) + "."
+
+            return "exit", AssistantMsg(
+                name=self.name,
+                content=[TextBlock(text=text)],
+            )
+
+        return "reasoning", None
+
+    def _get_executable_tool_calls(self) -> list[ToolCallBlock]:
+        """Get tool calls from the last message that to be executed, which
+        means we should reserve the tool calls that:
+
+        1. doesn't have results yet, **and**
+        2. haven't been submitted for external execution (state != "submitted")
+        """
+        last_msg = self._get_last_msg()
+        if last_msg is None:
+            return []
+
+        # The tool results
+        result_ids = {_.id for _ in last_msg.get_content_blocks("tool_result")}
+        # The tool calls that doesn't have results yet
+        tool_calls_wo_results = [
+            _
+            for _ in last_msg.get_content_blocks("tool_call")
+            if _.id not in result_ids
+        ]
+
+        # Filter the ones that are "submitted", which already report the
+        # external execution requirement
+        pending_tool_calls = [
+            _
+            for _ in tool_calls_wo_results
+            if _.state
+            in [
+                ToolCallState.PENDING,
+                ToolCallState.ALLOWED,
+            ]
+        ]
+        return pending_tool_calls
+
+    async def _convert_chat_response_to_event(
+        self,
+        block_ids: dict,
+        chunk: ChatResponse,
+    ) -> AsyncGenerator:
+        """Convert a ChatResponse chunk into a sequence of agent events. To
+        keep the identifiers of the content blocks reasonable, the input
+        blocks_ids is used to track the block ids.
+
+        Args:
+            block_ids (`dict`):
+                The block ids used to track the block generation.
+            chunk (`ChatResponse`):
+                The chat response chunk to be converted.
+        """
+
+        # Classify the content blocks into different types
+        text_blocks, thinking_blocks, tool_call_blocks = [], [], []
+        data_blocks: list = []
+        for block in chunk.content:
+            if isinstance(block, TextBlock):
+                text_blocks.append(block)
+            elif isinstance(block, ThinkingBlock):
+                thinking_blocks.append(block)
+            elif isinstance(block, ToolCallBlock):
+                tool_call_blocks.append(block)
+            elif isinstance(block, DataBlock):
+                data_blocks.append(block)
+
+        # Handle the thinking stream: continue/open or close.
+        # We only auto-close when the chunk also carries no data blocks;
+        # a data-only chunk (e.g. an omni-style audio PCM delta) must keep
+        # both text and thinking streams alive so the frontend doesn't
+        # fragment one logical stream into many separate bubbles.
+        if thinking_blocks:
+            # Generate a new thinking block id and start event
+            if not block_ids.get("thinking"):
+                block_ids["thinking"] = _generate_id()
+                yield ThinkingBlockStartEvent(
+                    reply_id=self.state.reply_id,
+                    block_id=block_ids["thinking"],
+                )
+            # Generate the thinking delta event with the existing id
+            yield ThinkingBlockDeltaEvent(
+                reply_id=self.state.reply_id,
+                block_id=block_ids["thinking"],
+                delta="".join([_.thinking for _ in thinking_blocks]),
+            )
+
+        elif block_ids.get("thinking") and not data_blocks:
+            yield ThinkingBlockEndEvent(
+                reply_id=self.state.reply_id,
+                block_id=block_ids["thinking"],
+            )
+            block_ids["thinking"] = None
+
+        # Handle the text stream: continue/open or close.  Placed after
+        # thinking so that a chunk carrying both ThinkingBlock and TextBlock
+        # emits thinking events first.
+        if text_blocks:
+            if not block_ids.get("text"):
+                block_ids["text"] = _generate_id()
+                yield TextBlockStartEvent(
+                    reply_id=self.state.reply_id,
+                    block_id=block_ids["text"],
+                )
+            yield TextBlockDeltaEvent(
+                reply_id=self.state.reply_id,
+                block_id=block_ids["text"],
+                delta="".join([_.text for _ in text_blocks]),
+            )
+        elif block_ids.get("text") and not data_blocks:
+            yield TextBlockEndEvent(
+                reply_id=self.state.reply_id,
+                block_id=block_ids["text"],
+            )
+            block_ids["text"] = None
+
+        # Handle the tool calls that exist in the current chunk
+        for tool_call in tool_call_blocks:
+            # Not in previous chunk, start with a start event
+            if tool_call.id not in block_ids["tools"]:
+                block_ids["tools"].append(tool_call.id)
+                yield ToolCallStartEvent(
+                    reply_id=self.state.reply_id,
+                    tool_call_id=tool_call.id,
+                    tool_call_name=tool_call.name,
+                )
+            yield ToolCallDeltaEvent(
+                reply_id=self.state.reply_id,
+                tool_call_id=tool_call.id,
+                delta=tool_call.input,
+            )
+
+        # Handle the tool calls that exist in the previous chunk but not in the
+        # current chunk
+        finished_ids = set(block_ids["tools"]) - set(
+            _.id for _ in tool_call_blocks
+        )
+        for finished_id in finished_ids:
+            yield ToolCallEndEvent(
+                reply_id=self.state.reply_id,
+                tool_call_id=finished_id,
+            )
+            block_ids["tools"].remove(finished_id)
+
+        # Handle the data blocks (streaming binary content, e.g. omni audio).
+        # Each DataBlock chunk from the model carries a delta payload with a
+        # stable block id; we open a stream the first time we see an id and
+        # emit delta events for subsequent chunks with the same id.
+        for data_block in data_blocks:
+            if not isinstance(data_block.source, Base64Source):
+                # Only Base64Source carries inline delta bytes; URLSource is
+                # one-shot and not part of the streaming protocol.
+                continue
+            if data_block.id not in block_ids["data"]:
+                block_ids["data"].append(data_block.id)
+                yield DataBlockStartEvent(
+                    reply_id=self.state.reply_id,
+                    block_id=data_block.id,
+                    media_type=data_block.source.media_type,
+                )
+            yield DataBlockDeltaEvent(
+                reply_id=self.state.reply_id,
+                block_id=data_block.id,
+                data=data_block.source.data,
+                media_type=data_block.source.media_type,
+            )
+
+    async def _convert_tool_chunk_to_event(
+        self,
+        tool_call_id: str,
+        output_blocks: str | List[TextBlock | DataBlock],
+    ) -> AsyncGenerator:
+        """Convert a ToolChunk into a sequence of agent events."""
+        if isinstance(output_blocks, str):
+            yield ToolResultTextDeltaEvent(
+                reply_id=self.state.reply_id,
+                tool_call_id=tool_call_id,
+                delta=output_blocks,
+            )
+            return
+
+        for block in output_blocks:
+            if isinstance(block, TextBlock):
+                yield ToolResultTextDeltaEvent(
+                    reply_id=self.state.reply_id,
+                    tool_call_id=tool_call_id,
+                    delta=block.text,
+                )
+
+            elif isinstance(block, DataBlock):
+                if isinstance(block.source, Base64Source):
+                    yield ToolResultDataDeltaEvent(
+                        reply_id=self.state.reply_id,
+                        tool_call_id=tool_call_id,
+                        media_type=block.source.media_type,
+                        data=block.source.data,
+                    )
+                elif isinstance(block.source, URLSource):
+                    yield ToolResultDataDeltaEvent(
+                        reply_id=self.state.reply_id,
+                        tool_call_id=tool_call_id,
+                        media_type=block.source.media_type,
+                        url=str(block.source.url),
+                    )
diff --git a/src/agentscope/agent/_config.py b/src/agentscope/agent/_config.py
new file mode 100644
index 0000000..ad9cf92
--- /dev/null
+++ b/src/agentscope/agent/_config.py
@@ -0,0 +1,191 @@
+# -*- coding: utf-8 -*-
+"""The agent config classes."""
+
+from pydantic import BaseModel, Field
+
+from ..model import ChatModelBase
+
+
+class SummarySchema(BaseModel):
+    """The compressed memory model, used to generate summary of old memories"""
+
+    task_overview: str = Field(
+        description=(
+            "The user's core request and success criteria.\n"
+            "Any clarifications or constraints they specified"
+        ),
+    )
+    current_state: str = Field(
+        description=(
+            "What has been completed so far.\n"
+            "File created, modified, or analyzed (with paths if relevant).\n"
+            "Key outputs or artifacts produced."
+        ),
+    )
+    important_discoveries: str = Field(
+        description=(
+            "Technical constraints or requirements uncovered.\n"
+            "Decisions made and their rationale.\n"
+            "Errors encountered and how they were resolved.\n"
+            "What approaches were tried that didn't work (and why)"
+        ),
+    )
+    next_steps: str = Field(
+        description=(
+            "Specific actions needed to complete the task.\n"
+            "Any blockers or open questions to resolve.\n"
+            "Priority order if multiple steps remain"
+        ),
+    )
+    context_to_preserve: str = Field(
+        description=(
+            "User preferences or style requirements.\n"
+            "Domain-specific details that aren't obvious.\n"
+            "Any promises made to the user"
+        ),
+    )
+    """The important context to preserve across compression, e.g. user
+    preferences, domain-specific details and promises made to the user."""
+
+
+class ContextConfig(BaseModel):
+    """The context related configuration in AgentScope"""
+
+    model_config = {"arbitrary_types_allowed": True}
+    """Allow arbitrary types in the pydantic model."""
+
+    trigger_ratio: float = Field(default=0.8, gt=0, lt=0.9)
+    """When the token exceeds this ratio of the maximum context length, the
+    context will be compressed. To reserve the context for context compression,
+    the maximum ratio is 0.9."""
+
+    reserve_ratio: float = Field(default=0.1, gt=0, lt=0.9)
+    """The ratio of the tokens to reserve in context compression, which should
+    be smaller than the trigger ratio."""
+
+    compression_prompt: str = Field(
+        default=(
+            "<system-hint>You have been working on the task described above "
+            "but have not yet completed it. "
+            "Now write a continuation summary that will allow you to resume "
+            "work efficiently in a future context window where the "
+            "conversation history will be replaced with this summary. "
+            "Your summary should be structured, concise, and actionable."
+            "</system-hint>"
+        ),
+        # ``format: textarea`` is a hint for schema-driven UI renderers
+        # to use a multi-line input. Plain JSON Schema doesn't natively
+        # express this, so we piggy-back on ``json_schema_extra``.
+        json_schema_extra={"format": "textarea"},
+    )
+    """The prompt used to guide the compression model to generate the
+    compressed summary, which will be wrapped into a user message and
+    attach to the end of the current memory."""
+
+    summary_template: str = Field(
+        default=(
+            "<system-info>Here is a summary of your previous work\n"
+            "# Task Overview\n"
+            "{task_overview}\n\n"
+            "# Current State\n"
+            "{current_state}\n\n"
+            "# Important Discoveries\n"
+            "{important_discoveries}\n\n"
+            "# Next Steps\n"
+            "{next_steps}\n\n"
+            "# Context to Preserve\n"
+            "{context_to_preserve}"
+            "</system-info>"
+        ),
+        json_schema_extra={"format": "textarea"},
+    )
+    """The string template to present the compressed summary to the agent,
+    which will be formatted with the fields from the
+    `summary_schema`."""
+
+    summary_schema: dict = Field(
+        default_factory=SummarySchema.model_json_schema,
+    )
+    """The structured model used to guide the agent to generate the
+    structured compressed summary."""
+
+    tool_result_limit: int = Field(
+        title="Tool Result Limit",
+        default=50000,
+        description=(
+            "The maximum length of the tool results in tokens. "
+            "If exceeded, the tool result will be truncated."
+        ),
+    )
+    """The tool result limit to avoid tool result bursting."""
+
+
+class ReActConfig(BaseModel):
+    """The reasoning related configuration"""
+
+    max_iters: int = Field(
+        title="Max Iterations",
+        default=20,
+        description="The maximum number of reasoning-acting iterations in "
+        "one reply",
+    )
+    """The maximum number of iterations for the reasoning-acting loop."""
+
+    stop_on_reject: bool = Field(
+        title="Rejection Handling",
+        default=False,
+        description="Whether to stop replying when being rejected to "
+        "execute tools.",
+    )
+    """If stop reasoning when tool call(s) are rejected. If `True`, the agent
+    won't continue reasoning and wait for outside interaction from the user.
+    """
+
+    interruption_message: str = Field(
+        title="Interruption Message",
+        default="I notice the interruption. How can I help you?",
+        description="The quick reply message when interrupted.",
+    )
+    """The interruption message."""
+
+    interruption_raise_cancelled_error: bool = Field(
+        title="Raise CancelledError on Interruption",
+        default=False,
+        description="Whether to re-raise ``asyncio.CancelledError`` after "
+        "handling the interruption. When ``False``, the ``CancelledError`` "
+        "is swallowed once the interruption context has been produced.",
+    )
+    """Whether to re-raise the ``asyncio.CancelledError`` after the
+    interruption has been handled. When ``False``, the ``CancelledError``
+    is swallowed once the fallback interruption message and
+    ``ReplyEndEvent`` have been emitted."""
+
+
+class ModelConfig(BaseModel):
+    """The model related configuration."""
+
+    # TODO: remove this line after PR #1564 is merged, where the ChatModel
+    #  will be child class of BaseModel
+    model_config = {"arbitrary_types_allowed": True}
+
+    max_retries: int = Field(
+        default=0,
+        ge=0,
+        description=(
+            "Number of retries on top of the initial call before falling "
+            "over to the fallback model. ``0`` means call the model exactly "
+            "once and immediately move to the fallback on failure. Same "
+            "semantics as ``ChatModelBase.max_retries``. Defaults to 0 to "
+            "avoid compounding with the model's own inner retry loop."
+        ),
+    )
+    """Number of retries on top of the initial call before falling over to
+    the fallback model. ``0`` means a single attempt with no retries.
+    Mirrors the semantics of ``ChatModelBase.max_retries``."""
+
+    fallback_model: ChatModelBase | None = Field(
+        default=None,
+        description="The fallback model used when the main model fails.",
+    )
+    """The fallback model used when the main model fails. Also supports the
+    max_retries logic."""
diff --git a/src/agentscope/agent/_utils.py b/src/agentscope/agent/_utils.py
new file mode 100644
index 0000000..2c3889a
--- /dev/null
+++ b/src/agentscope/agent/_utils.py
@@ -0,0 +1,17 @@
+# -*- coding: utf-8 -*-
+"""The utility classes used in building the agent class."""
+from dataclasses import dataclass
+from typing import Literal
+
+from ..message import ToolCallBlock
+
+
+@dataclass
+class _ToolCallBatch:
+    """A batch of tool calls that execute either sequentially or
+    concurrently."""
+
+    type: Literal["sequential", "concurrent"]
+    """The batch type"""
+    tool_calls: list[ToolCallBlock]
+    """The list of tool calls in the batch."""
diff --git a/src/agentscope/app/__init__.py b/src/agentscope/app/__init__.py
new file mode 100644
index 0000000..c609104
--- /dev/null
+++ b/src/agentscope/app/__init__.py
@@ -0,0 +1,12 @@
+# -*- coding: utf-8 -*-
+"""The FastAPI based agent service module, which contains all service-related
+components and a configurable FastAPI app factory.
+"""
+
+from ._app import create_app
+from ._types import SubAgentTemplate
+
+__all__ = [
+    "create_app",
+    "SubAgentTemplate",
+]
diff --git a/src/agentscope/app/_app.py b/src/agentscope/app/_app.py
new file mode 100644
index 0000000..255b2c9
--- /dev/null
+++ b/src/agentscope/app/_app.py
@@ -0,0 +1,274 @@
+# -*- coding: utf-8 -*-
+"""AgentScope app factory."""
+from typing import Type, TYPE_CHECKING, Any
+
+from ._lifespan import lifespan
+from .access import DenyAllResourceAccessPolicy, ResourceAccessPolicyBase
+from .rag.blob_store import BlobStoreBase, LocalBlobStore
+from .rag.knowledge_base_manager import KnowledgeBaseManagerBase
+from .workspace_manager import WorkspaceManagerBase
+from ._router import (
+    agent_router,
+    chat_router,
+    credential_router,
+    knowledge_base_router,
+    model_router,
+    tts_model_router,
+    schedule_router,
+    session_router,
+    workspace_router,
+)
+from ._types import AgentMiddlewareFactory, AgentToolFactory, SubAgentTemplate
+from .message_bus import MessageBus
+from .storage import StorageBase
+from ..agent import Agent
+from ..credential import CredentialFactory, CredentialBase
+from ..rag import (
+    ApproxTokenChunker,
+    ChunkerBase,
+    ParserBase,
+    TextParser,
+)
+from .._version import __version__
+
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+    from fastapi.middleware import Middleware as FastAPIMiddleware
+else:
+    FastAPI = Any
+    FastAPIMiddleware = Any
+
+
+def create_app(
+    storage: StorageBase,
+    message_bus: MessageBus,
+    workspace_manager: WorkspaceManagerBase,
+    knowledge_base_manager: KnowledgeBaseManagerBase | None = None,
+    knowledge_parsers: list[ParserBase] | dict[str, ParserBase] | None = None,
+    knowledge_chunker: ChunkerBase | None = None,
+    blob_store: BlobStoreBase | None = None,
+    enable_index_worker: bool = True,
+    *,
+    extra_credentials: list[Type[CredentialBase]] | None = None,
+    extra_middlewares: list[FastAPIMiddleware] | None = None,
+    extra_agent_middlewares: AgentMiddlewareFactory | None = None,
+    extra_agent_tools: AgentToolFactory | None = None,
+    custom_subagent_templates: list[SubAgentTemplate] | None = None,
+    custom_agent_cls: Type[Agent] | None = None,
+    resource_access_policy: ResourceAccessPolicyBase | None = None,
+    title: str = "AgentScope",
+    version: str = __version__,
+) -> FastAPI:
+    """Create and configure a FastAPI application.
+
+    This is the primary entry point for embedding AgentScope into an existing
+    service or running it standalone.  All built-in routers are registered
+    automatically; pass ``extra_middlewares`` to add your own.
+
+    Usage — standalone::
+
+        app = create_app(
+            storage=RedisStorage(),
+            message_bus=RedisMessageBus(),
+            workspace_manager=LocalWorkspaceManager(),
+        )
+        uvicorn.run(app, host="0.0.0.0", port=8000)
+
+    Usage — mount onto an existing app::
+
+        root = FastAPI()
+        agentscope_app = create_app(
+            storage=RedisStorage(),
+            message_bus=RedisMessageBus(),
+            workspace_manager=LocalWorkspaceManager(),
+        )
+        root.mount("/agentscope", agentscope_app)
+
+    Args:
+        storage (`StorageBase`):
+            The storage backend.  Its lifecycle (``__aenter__`` /
+            ``__aexit__``) is managed by the app lifespan.
+        message_bus (`MessageBus`):
+            The live message bus used for cross-session inbox delivery
+            and idle-session triggers. Required — the bus is intentionally
+            decoupled from ``storage`` so the persistence backend (e.g.
+            SQL) can differ from the transport backend (Redis). Its
+            lifecycle is also managed by the app lifespan.
+        workspace_manager (`WorkspaceManagerBase`):
+            The workspace manager. Required — every chat run and every
+            ``/workspace`` endpoint depends on it. Its lifecycle (
+            ``__aenter__`` / ``__aexit__``) is managed by the app
+            lifespan. Pass a :class:`~agentscope.app._manager.
+            LocalWorkspaceManager` for local-directory workspaces.
+        knowledge_base_manager (`KnowledgeBaseManagerBase | None`, \
+         optional):
+            The knowledge base manager that owns knowledge base
+            lifecycle and serves
+            :class:`~agentscope.rag.KnowledgeBase`
+            runtime handles to both HTTP service and agent code.
+            The manager carries its own vector store instance — its
+            ``__aenter__`` / ``__aexit__`` enter and release that
+            vector store, so the caller does not pass the vector
+            store separately.  ``None`` disables knowledge base
+            endpoints entirely.
+        knowledge_parsers (`list[ParserBase] | dict[str, ParserBase] | \
+         None`, optional):
+            Parsers registered for knowledge base document uploads.
+            Pass a **list** to have the service route by each parser's
+            ``supported_media_types`` (later entries override earlier
+            ones for overlapping types, with a warning); pass a
+            **dict** ``media_type → parser`` for explicit routing
+            (one parser bound to multiple types, type aliases, ...).
+            Defaults to ``[TextParser()]`` when
+            ``knowledge_base_manager`` is set.
+        knowledge_chunker (`ChunkerBase | None`, optional):
+            The chunker shared across every knowledge base.  Defaults
+            to :class:`~agentscope.rag.ApproxTokenChunker()` when
+            ``knowledge_base_manager`` is set.
+        blob_store (`BlobStoreBase | None`, optional):
+            Backend storing uploaded document bytes between the
+            upload endpoint and the indexing worker.  Required when
+            ``knowledge_base_manager`` is set; defaults to
+            :class:`~agentscope.app.rag.blob_store.LocalBlobStore`
+            rooted at ``./blobs``.  Its lifecycle (``__aenter__`` /
+            ``__aexit__``) is managed by the app lifespan.
+        enable_index_worker (`bool`, defaults to ``True``):
+            When ``True`` (embedded deployment) the API process starts
+            an :class:`~agentscope.app._service.IndexWorker` and an
+            :class:`~agentscope.app._service.IndexSweeper` in its
+            lifespan, and dispatches indexing tasks via an
+            in-process queue.  When ``False`` (dedicated deployment)
+            the API process performs no indexing — a separate worker
+            process is expected to consume tasks from the message
+            bus.  No effect when ``knowledge_base_manager`` is
+            ``None``.
+        extra_credentials (`list[Type[CredentialBase]] | None`, optional):
+            Additional :class:`~agentscope.credential.CredentialBase`
+            subclasses to register before the app starts.  Equivalent to
+            calling :func:`~agentscope.credential.CredentialFactory.
+            register_credential` for each class.
+        extra_middlewares (`list[Middleware] | None`, optional):
+            Additional ASGI middlewares to add to the application.
+        extra_agent_middlewares (`AgentMiddlewareFactory | None`, optional):
+            An async factory ``(user_id, agent_id, session_id) -> awaitable
+            of list[MiddlewareBase]`` that produces extra
+            :class:`~agentscope.middleware.MiddlewareBase` instances to
+            attach to the agent on each invocation.  Called once per agent
+            assembly (i.e. per chat turn / scheduled trigger), so it can
+            return user/session-specific middleware (auth, audit logging,
+            tenant isolation, etc.).  The returned middlewares are appended
+            to the framework-supplied ones (e.g. ``ToolOffloadMiddleware``).
+        extra_agent_tools (`AgentToolFactory | None`, optional):
+            An async factory ``(user_id, agent_id, session_id) -> awaitable
+            of list[ToolBase]`` that produces extra
+            :class:`~agentscope.tool.ToolBase` instances to register in the
+            agent's toolkit on each invocation.  Useful when tool
+            availability depends on the caller (per-tenant integrations,
+            user-specific credentials).  The returned tools are added to
+            the workspace-derived tools in the toolkit's ``"basic"`` group.
+        custom_subagent_templates (`list[SubAgentTemplate] | None`, optional):
+            Reusable blueprints for sub-agent creation within teams.
+            Each template defines a sub-agent *type* (e.g. ``"researcher"``,
+            ``"coder"``) with pre-configured system prompt, context config,
+            ReAct config, permission context, and task context. When
+            registered, the ``AgentCreate`` tool exposes a
+            ``subagent_type`` parameter so the leader agent can route to
+            the appropriate template.  See
+            :class:`~agentscope.app._types.SubAgentTemplate` for details.
+        custom_agent_cls (`Type[Agent] | None`, optional):
+            A custom :class:`~agentscope.agent.Agent` subclass to use
+            when assembling agents.  When ``None`` (default), the
+            built-in :class:`~agentscope.agent.Agent` is used.
+        resource_access_policy (`ResourceAccessPolicyBase | None`, optional):
+            Policy deciding whether a viewer may access
+            credentials / agents / knowledge bases owned by another
+            user. When ``None`` (default), a
+            :class:`DenyAllResourceAccessPolicy` is installed which
+            preserves the historical owner-isolated behavior.
+        title (`str`, defaults to ``"AgentScope"``):
+            OpenAPI title shown in the docs UI.
+        version (`str`, defaults to the package version):
+            API version shown in the docs UI.
+
+    Returns:
+        `FastAPI`: A fully configured application ready to serve requests.
+    """
+    from fastapi import FastAPI
+
+    # Register any user-supplied credential types before the app starts
+    for cls in extra_credentials or []:
+        CredentialFactory.register_credential(cls)
+
+    app = FastAPI(title=title, version=version, lifespan=lifespan)
+
+    # Attach shared state that lifespan and dependencies read from app.state
+    app.state.storage = storage
+    app.state.message_bus = message_bus
+    app.state.workspace_manager = workspace_manager
+    app.state.knowledge_base_manager = knowledge_base_manager
+    app.state.extra_agent_middlewares = extra_agent_middlewares
+    app.state.extra_agent_tools = extra_agent_tools
+    app.state.custom_agent_cls = custom_agent_cls
+    app.state.resource_access_policy = (
+        resource_access_policy or DenyAllResourceAccessPolicy()
+    )
+
+    # Parser / chunker / blob-store defaults only make sense when the
+    # KB feature is actually enabled.  When ``knowledge_base_manager`` is
+    # ``None`` every KB endpoint is disabled, so leaving these as ``None``
+    # avoids unused imports being eagerly constructed at app startup.
+    if knowledge_base_manager is not None:
+        app.state.knowledge_parsers = (
+            knowledge_parsers
+            if knowledge_parsers is not None
+            else [TextParser()]
+        )
+        app.state.knowledge_chunker = knowledge_chunker or ApproxTokenChunker()
+        app.state.blob_store = (
+            blob_store
+            if blob_store is not None
+            else LocalBlobStore(root_dir="./blobs")
+        )
+    else:
+        app.state.knowledge_parsers = knowledge_parsers
+        app.state.knowledge_chunker = knowledge_chunker
+        app.state.blob_store = blob_store
+    app.state.enable_index_worker = (
+        enable_index_worker and knowledge_base_manager is not None
+    )
+
+    # Validate custom sub-agent templates for duplicate types and store in
+    #  app.state
+    templates = custom_subagent_templates or []
+    seen_types: set[str] = set()
+    duplicates: set[str] = set()
+    for t in templates:
+        if t.type in seen_types:
+            duplicates.add(t.type)
+        seen_types.add(t.type)
+    if duplicates:
+        raise ValueError(
+            f"Duplicate sub_agent_template type(s): {duplicates}",
+        )
+    app.state.custom_subagent_templates = {t.type: t for t in templates}
+
+    # Built-in routers
+    for router in (
+        agent_router,
+        chat_router,
+        credential_router,
+        knowledge_base_router,
+        schedule_router,
+        session_router,
+        workspace_router,
+        model_router,
+        tts_model_router,
+    ):
+        app.include_router(router)
+
+    # Optional extra middlewares
+    for middleware in extra_middlewares or []:
+        app.add_middleware(middleware.cls, **middleware.kwargs)
+
+    return app
diff --git a/src/agentscope/app/_bus_ops.py b/src/agentscope/app/_bus_ops.py
new file mode 100644
index 0000000..b2ff904
--- /dev/null
+++ b/src/agentscope/app/_bus_ops.py
@@ -0,0 +1,169 @@
+# -*- coding: utf-8 -*-
+"""Business-level operations built on top of MessageBus primitives.
+
+These helpers compose generic bus primitives (``log_append``, ``publish``,
+``queue_push``) with domain-specific key layouts from ``MessageBusKeys``.
+They live here — between the transport layer (``message_bus``) and the
+service layer (``_service``) — so that neither layer needs to know about the
+other's internals.
+
+.. list-table::
+   :widths: 30 70
+
+   * - :func:`publish_session_event`
+     - Append an event to the session replay log and fan it out live.
+   * - :func:`enqueue_run_trigger`
+     - Enqueue a typed run trigger and signal dispatchers.
+   * - :func:`enqueue_index_task`
+     - Enqueue a knowledge-document indexing task and signal consumers.
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+from .message_bus._keys import MessageBusKeys
+
+if TYPE_CHECKING:
+    from .message_bus._base import MessageBus
+
+    from agentscope.event import (
+        ExternalExecutionResultEvent,
+        UserConfirmResultEvent,
+        UserInterruptEvent,
+    )
+
+
+# ── publish_session_event ──────────────────────────────────────────────
+
+
+async def publish_session_event(
+    bus: "MessageBus",
+    session_id: str,
+    event: dict,
+) -> str:
+    """Append event to replay log + fan out live.
+
+    Args:
+        bus (`MessageBus`):
+            The application message bus.
+        session_id (`str`):
+            The session this event belongs to.
+        event (`dict`):
+            JSON-serializable event payload.
+
+    Returns:
+        `str`:
+            The replay-log entry id assigned by the backend.
+    """
+    key = MessageBusKeys.session_events(session_id)
+    entry_id = await bus.log_append(
+        key,
+        event,
+        max_len=MessageBusKeys.SESSION_REPLAY_MAX_LEN,
+    )
+    await bus.publish(key, {**event, "_entry_id": entry_id})
+    return entry_id
+
+
+# ── enqueue_run_trigger ────────────────────────────────────────────────
+
+
+async def enqueue_run_trigger(
+    bus: "MessageBus",
+    user_id: str,
+    session_id: str,
+    agent_id: str,
+    *,
+    kind: Literal["wake", "resume"] = MessageBusKeys.WAKEUP_KIND_WAKE,
+    inputs: UserConfirmResultEvent
+    | ExternalExecutionResultEvent
+    | UserInterruptEvent
+    | None = None,
+) -> None:
+    """Enqueue a typed run trigger and signal dispatchers.
+
+    ``kind`` selects how the dispatcher handles the entry:
+
+    - ``wake`` — idle-session wake-up.  The dispatcher skips the entry
+      when the session is already running (the live run drains the inbox
+      itself).  ``inputs`` must be ``None``.
+    - ``resume`` — resume a HITL-parked session with a user confirmation,
+      an external execution result, or a user interrupt.  The dispatcher
+      waits (with backoff) until the parked run releases its lock, then
+      spawns with ``input_msg`` set to the deserialised event.
+
+    The payload is serialised to a plain dict before being pushed to the
+    wakeup queue; the ``MessageBus`` transport layer never sees event
+    types.
+
+    Args:
+        bus (`MessageBus`):
+            The application message bus.
+        user_id (`str`):
+            The owning user id.
+        session_id (`str`):
+            The session to trigger a run for.
+        agent_id (`str`):
+            The agent id that owns the session.
+        kind:
+            Trigger kind.  Defaults to ``"wake"``.
+        inputs:
+            The input event for ``resume`` triggers.  Ignored (and
+            should be ``None``) for ``wake``.  The function calls
+            ``model_dump(mode="json")`` internally — callers pass the
+            event object, not a pre-serialised dict.
+    """
+    await bus.queue_push(
+        MessageBusKeys.wakeup_queue(),
+        {
+            "user_id": user_id,
+            "session_id": session_id,
+            "agent_id": agent_id,
+            "kind": kind,
+            "input": inputs.model_dump(mode="json") if inputs else None,
+        },
+    )
+    await bus.publish(MessageBusKeys.wakeup_signal(), {})
+
+
+# ── enqueue_index_task ─────────────────────────────────────────────────
+
+
+async def enqueue_index_task(
+    bus: "MessageBus",
+    user_id: str,
+    knowledge_base_id: str,
+    document_id: str,
+) -> None:
+    """Enqueue a knowledge-document indexing task and signal consumers.
+
+    Pushes a structured payload onto the durable index-task queue and
+    publishes a signal so any subscribed
+    :class:`~agentscope.app._service.IndexTaskConsumer` drains it within
+    one ``subscribe`` round-trip.
+
+    The push happens *before* the publish so a worker woken by the
+    signal is guaranteed to find the entry on its drain.  Re-enqueuing
+    the same document is safe — the worker's lease CAS rejects
+    duplicates — so the queue may legitimately hold multiple entries
+    for the same document (one from upload, one from sweeper).
+
+    Args:
+        bus (`MessageBus`):
+            The application message bus.
+        user_id (`str`):
+            The owning user id.
+        knowledge_base_id (`str`):
+            The parent knowledge base id.
+        document_id (`str`):
+            The document id to index.
+    """
+    await bus.queue_push(
+        MessageBusKeys.index_tasks_queue(),
+        {
+            "user_id": user_id,
+            "knowledge_base_id": knowledge_base_id,
+            "document_id": document_id,
+        },
+    )
+    await bus.publish(MessageBusKeys.index_tasks_signal(), {})
diff --git a/src/agentscope/app/_lifespan.py b/src/agentscope/app/_lifespan.py
new file mode 100644
index 0000000..5e4c148
--- /dev/null
+++ b/src/agentscope/app/_lifespan.py
@@ -0,0 +1,194 @@
+# -*- coding: utf-8 -*-
+"""The lifespan of the agent service."""
+import socket
+import uuid
+from contextlib import AsyncExitStack, asynccontextmanager
+from typing import TYPE_CHECKING, Any, AsyncIterator
+
+from ._manager import (
+    BackgroundTaskManager,
+    CancelDispatcher,
+    ChatRunRegistry,
+    SchedulerManager,
+    WakeupDispatcher,
+)
+from ._service import (
+    ChatService,
+    IndexSweeper,
+    IndexTaskConsumer,
+    IndexWorker,
+    KnowledgeBaseService,
+    ResourceAccessService,
+    SessionService,
+)
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+else:
+    FastAPI = Any
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+    """Manage startup and shutdown of all application-wide resources.
+
+    Every resource with a lifecycle is an async context manager and is
+    entered through a single :class:`AsyncExitStack`. The stack tears
+    them down in reverse order on shutdown — including when an entry
+    later in the sequence raises during startup, so no resource leaks
+    on partial failure.
+
+    Service-layer ``ChatService`` and ``SessionService`` have no
+    lifecycle of their own and are constructed inline.
+    """
+    storage = app.state.storage
+    message_bus = app.state.message_bus
+    workspace_manager = app.state.workspace_manager
+    knowledge_base_manager = app.state.knowledge_base_manager
+    blob_store = app.state.blob_store
+    enable_index_worker = app.state.enable_index_worker
+    resource_access_policy = app.state.resource_access_policy
+
+    async with AsyncExitStack() as stack:
+        await stack.enter_async_context(storage)
+        await stack.enter_async_context(message_bus)
+        await stack.enter_async_context(workspace_manager)
+        if knowledge_base_manager is not None:
+            # ``KnowledgeBaseManagerBase.__aenter__`` enters the bound
+            # vector store too, so a single context covers both.
+            await stack.enter_async_context(knowledge_base_manager)
+        if blob_store is not None:
+            await stack.enter_async_context(blob_store)
+
+        bg_manager = await stack.enter_async_context(
+            BackgroundTaskManager(message_bus=message_bus),
+        )
+        app.state.background_task_manager = bg_manager
+
+        # Per-process registry of in-flight chat-run asyncio tasks.
+        # Entered before the wake-up + cancel dispatchers so they can
+        # share the same registry; exited last so its shutdown can
+        # cancel any leftover runs after the dispatchers stop.
+        chat_run_registry = await stack.enter_async_context(ChatRunRegistry())
+        app.state.chat_run_registry = chat_run_registry
+
+        # Scheduler is independent of ChatService now (its fire path
+        # pushes to inbox + enqueues wakeup via the bus), so we build it
+        # before ChatService and inject it via the constructor.
+        scheduler = await stack.enter_async_context(
+            SchedulerManager(
+                storage=storage,
+                message_bus=message_bus,
+            ),
+        )
+        app.state.scheduler_manager = scheduler
+
+        # Resource access service — combines owner-scoped storage reads
+        # with the injected policy so both routers and runtime services
+        # go through a single choke point when resolving credentials /
+        # agents / knowledge bases.
+        resource_access_service = ResourceAccessService(
+            storage=storage,
+            policy=resource_access_policy,
+        )
+        app.state.resource_access_service = resource_access_service
+
+        chat_service = ChatService(
+            storage=storage,
+            workspace_manager=workspace_manager,
+            scheduler_manager=scheduler,
+            background_task_manager=bg_manager,
+            message_bus=message_bus,
+            resource_access_service=resource_access_service,
+            knowledge_base_manager=knowledge_base_manager,
+            extra_agent_middlewares=app.state.extra_agent_middlewares,
+            extra_agent_tools=app.state.extra_agent_tools,
+            custom_subagent_templates=app.state.custom_subagent_templates,
+            custom_agent_cls=app.state.custom_agent_cls,
+        )
+        app.state.chat_service = chat_service
+
+        app.state.session_service = SessionService(
+            storage=storage,
+            message_bus=message_bus,
+        )
+
+        # ---------------- Knowledge-base wiring ----------------
+        knowledge_base_service = None
+        if knowledge_base_manager is not None:
+            # Indexing is uniformly driven by the message bus: the
+            # service publishes an index-task entry, and a consumer
+            # (in-process or in a dedicated worker process) drains it.
+            #
+            # * Embedded — ``enable_index_worker=True``: this lifespan
+            #   additionally starts an :class:`IndexWorker` plus an
+            #   :class:`IndexTaskConsumer` that subscribes to the same
+            #   channel. The ``InMemoryMessageBus`` makes the round
+            #   trip near-free; everything runs in one binary.
+            #
+            # * Dedicated — ``enable_index_worker=False``: this
+            #   lifespan does NOT start a worker. One or more separate
+            #   processes (``python -m agentscope.app.rag.index_worker``)
+            #   run their own consumer + worker pair subscribed to the
+            #   same channel.
+            #
+            # The sweeper STILL runs in the API process either way,
+            # because the API is the only resource guaranteed to be
+            # live whenever uploads happen — if the publish ever races
+            # a worker restart the durable queue catches the task, and
+            # if the queue write itself failed the sweeper eventually
+            # re-enqueues from storage.
+            if enable_index_worker:
+                node_id = f"{socket.gethostname()}:{uuid.uuid4().hex[:8]}"
+                worker = IndexWorker(
+                    storage=storage,
+                    blob_store=blob_store,
+                    knowledge_base_manager=knowledge_base_manager,
+                    parsers=app.state.knowledge_parsers,
+                    chunker=app.state.knowledge_chunker,
+                    node_id=node_id,
+                )
+                await stack.enter_async_context(
+                    IndexTaskConsumer(
+                        message_bus=message_bus,
+                        worker=worker,
+                    ),
+                )
+
+            sweeper = IndexSweeper(
+                storage=storage,
+                message_bus=message_bus,
+            )
+            await sweeper.start()
+            stack.push_async_callback(sweeper.stop)
+
+            knowledge_base_service = KnowledgeBaseService(
+                storage=storage,
+                knowledge_base_manager=knowledge_base_manager,
+                blob_store=blob_store,
+                message_bus=message_bus,
+                resource_access_service=resource_access_service,
+            )
+
+        app.state.knowledge_base_service = knowledge_base_service
+
+        # Dispatchers need live references somewhere, or they would be
+        # garbage-collected; the AsyncExitStack holds those references
+        # for us, so we don't need local bindings or app.state slots.
+        await stack.enter_async_context(
+            WakeupDispatcher(
+                message_bus=message_bus,
+                storage=storage,
+                chat_service=chat_service,
+                chat_run_registry=chat_run_registry,
+            ),
+        )
+        await stack.enter_async_context(
+            CancelDispatcher(
+                message_bus=message_bus,
+                registry=chat_run_registry,
+                bg_manager=bg_manager,
+            ),
+        )
+
+        yield
diff --git a/src/agentscope/app/_manager/__init__.py b/src/agentscope/app/_manager/__init__.py
new file mode 100644
index 0000000..f4facb0
--- /dev/null
+++ b/src/agentscope/app/_manager/__init__.py
@@ -0,0 +1,17 @@
+# -*- coding: utf-8 -*-
+"""The agent service managers, used in FastAPI lifespan to manage
+application-wide resources."""
+
+from ._scheduler import SchedulerManager
+from ._wakeup_dispatcher import WakeupDispatcher
+from ._cancel_dispatcher import CancelDispatcher
+from ._chat_run_registry import ChatRunRegistry
+from ._background_task_manager import BackgroundTaskManager
+
+__all__ = [
+    "BackgroundTaskManager",
+    "CancelDispatcher",
+    "ChatRunRegistry",
+    "SchedulerManager",
+    "WakeupDispatcher",
+]
diff --git a/src/agentscope/app/_manager/_background_task_manager.py b/src/agentscope/app/_manager/_background_task_manager.py
new file mode 100644
index 0000000..80cc257
--- /dev/null
+++ b/src/agentscope/app/_manager/_background_task_manager.py
@@ -0,0 +1,470 @@
+# -*- coding: utf-8 -*-
+"""The background task manager."""
+import asyncio
+import json
+import time
+from collections import OrderedDict
+from dataclasses import dataclass, field
+from typing import Any, Self, TYPE_CHECKING
+
+import shortuuid
+from pydantic import BaseModel, Field
+
+from agentscope.message import TextBlock, ToolResultState
+from agentscope.permission import (
+    PermissionContext,
+    PermissionDecision,
+    PermissionBehavior,
+)
+from agentscope.tool import ToolBase, ToolChunk
+from agentscope._logging import logger
+from ..message_bus import MessageBusKeys
+
+if TYPE_CHECKING:
+    from ..message_bus import MessageBus
+
+
+@dataclass
+class BackgroundTask:
+    """Metadata for a single background task.
+
+    Attributes:
+        asyncio_task (`asyncio.Task`):
+            The running asyncio task.
+        session_id (`str`):
+            The session id of the originating request.
+        agent_id (`str`):
+            The name of the agent that created the task.
+        user_id (`str`):
+            The user id of the originating request.
+        tool_name (`str`):
+            The name of the tool that was offloaded.
+        id (`str`):
+            Auto-generated unique task identifier.
+    """
+
+    asyncio_task: asyncio.Task
+    """The running asyncio task."""
+
+    session_id: str
+    """The session id of the background task."""
+
+    agent_id: str
+    """The agent that created the background task."""
+
+    user_id: str
+    """The user id of the originating request."""
+
+    tool_name: str
+    """The name of the offloaded tool."""
+
+    id: str = field(default_factory=shortuuid.uuid)
+    """The background task id."""
+
+
+class _ToolStopParams(BaseModel):
+    """The params of the stop tool."""
+
+    task_id: str = Field(
+        description="The task id of the background tool to stop.",
+    )
+
+
+class ToolStop(ToolBase):
+    """A tool to stop a running background tool execution."""
+
+    name: str = "ToolStop"
+    """The tool name."""
+
+    description: str = (
+        "Stop a background tool execution by its task id. "
+        "Use this when you want to cancel a previously offloaded tool "
+        "that is still running in the background."
+    )
+    """The tool description."""
+
+    input_schema: dict = _ToolStopParams.model_json_schema()
+    """The input schema."""
+
+    is_concurrency_safe: bool = True
+    is_read_only: bool = False
+    is_state_injected: bool = False
+    is_external_tool: bool = False
+    is_mcp: bool = False
+    mcp_name: str | None = None
+
+    def __init__(
+        self,
+        background_tasks: dict[str, BackgroundTask],
+        message_bus: "MessageBus",
+        session_id: str,
+    ) -> None:
+        """Initialize the ToolStop tool.
+
+        Args:
+            background_tasks (`dict[str, BackgroundTask]`):
+                A reference to the local background tasks managed by
+                the :class:`BackgroundTaskManager`.
+            message_bus (`MessageBus`):
+                The application message bus, used to check the global
+                registry and broadcast cross-worker cancel requests.
+            session_id (`str`):
+                The current session id, used to scope Redis registry
+                lookups.
+        """
+        self.background_tasks = background_tasks
+        self._message_bus = message_bus
+        self._session_id = session_id
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        """Check permission for the tool usage.
+
+        Args:
+            tool_input (`dict[str, Any]`):
+                The tool input parameters.
+            context (`PermissionContext`):
+                The permission context.
+
+        Returns:
+            `PermissionDecision`:
+                Always returns ALLOW.
+        """
+        return PermissionDecision(
+            behavior=PermissionBehavior.ALLOW,
+            message=f"{self.name} is always allowed to be called.",
+        )
+
+    async def __call__(self, task_id: str) -> ToolChunk:
+        """Stop the background task.
+
+        Args:
+            task_id (`str`):
+                The task id.
+
+        Returns:
+            `ToolChunk`:
+                The tool chunk.
+        """
+        # Path 1: task is on this worker — cancel directly.
+        # Only cancel when the task belongs to the same session as this
+        # ToolStop instance, so a leaked/guessed task_id from another
+        # session cannot trigger cross-session cancellation on a shared
+        # worker.
+        local_task = self.background_tasks.get(task_id)
+        if (
+            local_task is not None
+            and local_task.session_id == self._session_id
+        ):
+            self.background_tasks.pop(task_id, None)
+            local_task.asyncio_task.cancel()
+            logger.info(
+                "Background task stopped via ToolStop (local): task_id=%s, "
+                "session_id=%s, agent_id=%s",
+                task_id,
+                local_task.session_id,
+                local_task.agent_id,
+            )
+            return ToolChunk(
+                content=[
+                    TextBlock(text=f"Task {task_id} stopped successfully."),
+                ],
+                state=ToolResultState.SUCCESS,
+            )
+
+        # Path 2: task exists in the global registry (another worker, or
+        # a different session on this worker).
+        if await self._message_bus.registry_exists(
+            MessageBusKeys.bg_tasks(self._session_id),
+            task_id,
+        ):
+            await self._message_bus.publish(
+                MessageBusKeys.task_cancel_channel(),
+                {"task_id": task_id},
+            )
+            logger.info(
+                "Background task cancel broadcast via ToolStop (remote): "
+                "task_id=%s, session_id=%s",
+                task_id,
+                self._session_id,
+            )
+            return ToolChunk(
+                content=[
+                    TextBlock(
+                        text=f"Cancel request sent for task {task_id}. "
+                        f"The owning worker will stop it shortly.",
+                    ),
+                ],
+                state=ToolResultState.SUCCESS,
+            )
+
+        # Path 3: task not found anywhere.
+        return ToolChunk(
+            content=[
+                TextBlock(
+                    text=f"TaskNotFoundError: The task {task_id} "
+                    f"does not exist.",
+                ),
+            ],
+            state=ToolResultState.ERROR,
+        )
+
+
+class BackgroundTaskManager:
+    """Tracks background asyncio task lifecycle within the agent service.
+
+    Responsibilities:
+
+    - **Global registry**: register/unregister tasks in Redis so any
+      process can query which tasks are alive for a session.
+    - **Local handle cache**: hold ``asyncio.Task`` references for
+      cancel and shutdown.
+    - **Task scheduling**: convenience method for creating a task from
+      a plain coroutine with a done callback that cleans up both sides.
+
+    Completion results are delivered via the :class:`MessageBus` inbox
+    + wakeup path (same as team messages), so any process's
+    :class:`WakeupDispatcher` can pick up the result.
+    """
+
+    def __init__(self, message_bus: "MessageBus") -> None:
+        """Initialise the background task manager.
+
+        Args:
+            message_bus (`MessageBus`):
+                The application message bus; used for the global BG
+                task registry (Redis Hash) and task-level cancel
+                broadcasts.
+        """
+        self._message_bus = message_bus
+        self.tasks: OrderedDict[str, BackgroundTask] = OrderedDict()
+
+    # ------------------------------------------------------------------
+    # Task registration
+    # ------------------------------------------------------------------
+
+    async def register_task(
+        self,
+        asyncio_task: asyncio.Task,
+        session_id: str,
+        agent_id: str,
+        user_id: str,
+        tool_name: str = "",
+    ) -> str:
+        """Register an already-running asyncio task.
+
+        Writes to both the local handle cache and the global Redis
+        registry. The task auto-removes from both when it finishes
+        (via ``add_done_callback``).
+
+        Args:
+            asyncio_task (`asyncio.Task`):
+                The already-running task to register.
+            session_id (`str`):
+                The originating session id.
+            agent_id (`str`):
+                The agent record id that owns the task.
+            user_id (`str`):
+                The user id of the originating request.
+            tool_name (`str`, optional):
+                The name of the offloaded tool.
+
+        Returns:
+            `str`:
+                The generated task id.
+        """
+        bg_task = BackgroundTask(
+            asyncio_task=asyncio_task,
+            session_id=session_id,
+            agent_id=agent_id,
+            user_id=user_id,
+            tool_name=tool_name,
+        )
+        task_id = bg_task.id
+        self.tasks[task_id] = bg_task
+
+        # Register in the global Redis registry.
+        metadata = json.dumps(
+            {
+                "tool_name": tool_name,
+                "agent_id": agent_id,
+                "started_at": time.time(),
+            },
+            ensure_ascii=False,
+        )
+        await self._message_bus.registry_set(
+            MessageBusKeys.bg_tasks(session_id),
+            task_id,
+            metadata,
+            ttl_secs=MessageBusKeys.BG_TASKS_TTL_SECS,
+        )
+
+        logger.info(
+            "Background task registered: task_id=%s, session_id=%s, "
+            "agent_id=%s, tool_name=%s",
+            task_id,
+            session_id,
+            agent_id,
+            tool_name,
+        )
+
+        def _on_done(_t: asyncio.Task) -> None:
+            self.tasks.pop(task_id, None)
+            # Schedule async Redis cleanup (fire-and-forget). Wrap in a
+            # coroutine that logs failures so the bus error (e.g. Redis
+            # connection drop) does not surface as
+            # ``Task exception was never retrieved``.
+            try:
+                asyncio.ensure_future(
+                    self._safe_bg_task_unregister(session_id, task_id),
+                )
+            except RuntimeError:
+                # Event loop already closed during shutdown.
+                pass
+
+        asyncio_task.add_done_callback(_on_done)
+        return task_id
+
+    async def _safe_bg_task_unregister(
+        self,
+        session_id: str,
+        task_id: str,
+    ) -> None:
+        """Unregister a finished background task, logging any failure.
+
+        Args:
+            session_id (`str`):
+                The session id of the finished task.
+            task_id (`str`):
+                The task id to unregister from the global registry.
+        """
+        try:
+            await self._message_bus.registry_del(
+                MessageBusKeys.bg_tasks(session_id),
+                task_id,
+            )
+        except Exception as e:  # pylint: disable=broad-except
+            logger.exception(
+                "Failed to unregister background task from the global "
+                "registry: task_id=%s, session_id=%s, error=%s",
+                task_id,
+                session_id,
+                str(e),
+            )
+
+    # ------------------------------------------------------------------
+    # Tool listing
+    # ------------------------------------------------------------------
+
+    async def list_tools(self, session_id: str) -> list[ToolBase]:
+        """List the background task tools for a given session.
+
+        Args:
+            session_id (`str`):
+                The current session id (for ToolStop's registry
+                lookups).
+
+        Returns:
+            `list[ToolBase]`:
+                A list containing the :class:`ToolStop` tool.
+        """
+        return [ToolStop(self.tasks, self._message_bus, session_id)]
+
+    # ------------------------------------------------------------------
+    # Session-scoped cancel
+    # ------------------------------------------------------------------
+
+    def cancel_session_tasks(self, session_id: str) -> int:
+        """Cancel every locally-tracked task whose owner session matches.
+
+        Called by :class:`CancelDispatcher` on each incoming session
+        cancel broadcast. Returns the number of tasks cancelled on this
+        process.
+
+        Args:
+            session_id (`str`):
+                The session whose tasks should be cancelled.
+
+        Returns:
+            `int`:
+                Number of tasks cancelled locally.
+        """
+        cancelled = 0
+        for bg_task in list(self.tasks.values()):
+            if bg_task.session_id != session_id:
+                continue
+            logger.info(
+                "Cancelling background task for session cancel: "
+                "task_id=%s, session_id=%s, agent_id=%s",
+                bg_task.id,
+                bg_task.session_id,
+                bg_task.agent_id,
+            )
+            bg_task.asyncio_task.cancel()
+            cancelled += 1
+        return cancelled
+
+    # ------------------------------------------------------------------
+    # Single-task cancel (called by CancelDispatcher on bus signal)
+    # ------------------------------------------------------------------
+
+    def cancel_task(self, task_id: str) -> bool:
+        """Cancel a single locally-tracked task by its id.
+
+        Called by :class:`CancelDispatcher` when a task-level cancel
+        broadcast arrives. Returns whether the task was found and
+        cancelled on this process.
+
+        Args:
+            task_id (`str`):
+                The task to cancel.
+
+        Returns:
+            `bool`:
+                ``True`` if the task was found locally and cancelled.
+        """
+        bg_task = self.tasks.get(task_id)
+        if bg_task is None:
+            return False
+        logger.info(
+            "Cancelling background task via bus signal: "
+            "task_id=%s, session_id=%s, agent_id=%s",
+            task_id,
+            bg_task.session_id,
+            bg_task.agent_id,
+        )
+        bg_task.asyncio_task.cancel()
+        return True
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def __aenter__(self) -> Self:
+        """Enter the async context. No setup required.
+
+        Returns:
+            `Self`: This manager instance.
+        """
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        """Cancel all running background tasks on context exit."""
+        count = len(self.tasks)
+        logger.info(
+            "Shutting down BackgroundTaskManager: cancelling %d task(s).",
+            count,
+        )
+        for bg_task in list(self.tasks.values()):
+            logger.info(
+                "Cancelling background task on shutdown: task_id=%s, "
+                "session_id=%s, agent_id=%s",
+                bg_task.id,
+                bg_task.session_id,
+                bg_task.agent_id,
+            )
+            bg_task.asyncio_task.cancel()
+        self.tasks.clear()
diff --git a/src/agentscope/app/_manager/_cancel_dispatcher.py b/src/agentscope/app/_manager/_cancel_dispatcher.py
new file mode 100644
index 0000000..c5364f7
--- /dev/null
+++ b/src/agentscope/app/_manager/_cancel_dispatcher.py
@@ -0,0 +1,246 @@
+# -*- coding: utf-8 -*-
+"""Single per-process dispatcher for cross-process cancels.
+
+Subscribes to two bus channels:
+
+1. **Session cancel** — cancel all local work for a session (chat run
+   + all BG tasks). Triggered by session deletion or explicit abort.
+2. **Task cancel** — cancel a single BG task by task_id. Triggered by
+   the :class:`ToolStop` agent tool when the target task lives on a
+   different worker.
+
+Processes whose registry / BG-manager do not hold the targeted session
+or task simply do no work — the publisher does not need to know which
+worker holds what; it broadcasts and lets each holder self-select.
+"""
+import asyncio
+from typing import TYPE_CHECKING, Self
+
+from ..._logging import logger
+from ..message_bus import MessageBusKeys
+
+if TYPE_CHECKING:
+    from ..message_bus import MessageBus
+    from ._background_task_manager import BackgroundTaskManager
+    from ._chat_run_registry import ChatRunRegistry
+
+
+class CancelDispatcher:
+    """Subscribes to bus cancel channels and cancels matching local
+    tasks.
+
+    Args:
+        message_bus (`MessageBus`):
+            Application message bus.
+        registry (`ChatRunRegistry`):
+            The per-process chat-run registry whose tasks may be
+            cancelled.
+        bg_manager (`BackgroundTaskManager`):
+            The per-process background task manager.
+    """
+
+    def __init__(
+        self,
+        message_bus: "MessageBus",
+        registry: "ChatRunRegistry",
+        bg_manager: "BackgroundTaskManager",
+    ) -> None:
+        """Bind dependencies.
+
+        Args:
+            message_bus (`MessageBus`):
+                Application message bus.
+            registry (`ChatRunRegistry`):
+                The per-process chat-run registry.
+            bg_manager (`BackgroundTaskManager`):
+                The per-process background task manager.
+        """
+        self._bus = message_bus
+        self._registry = registry
+        self._bg_manager = bg_manager
+        self._session_task: asyncio.Task | None = None
+        self._task_cancel_task: asyncio.Task | None = None
+        self._interrupt_task: asyncio.Task | None = None
+
+    async def __aenter__(self) -> Self:
+        """Start both dispatcher loops and wait until their bus
+        subscriptions are live.
+
+        Returns:
+            `Self`: This dispatcher instance.
+        """
+        session_ready = asyncio.Event()
+        task_ready = asyncio.Event()
+        interrupt_ready = asyncio.Event()
+
+        self._session_task = asyncio.create_task(
+            self._session_cancel_loop(session_ready),
+            name="cancel-dispatcher:session",
+        )
+        self._task_cancel_task = asyncio.create_task(
+            self._task_cancel_loop(task_ready),
+            name="cancel-dispatcher:task",
+        )
+        self._interrupt_task = asyncio.create_task(
+            self._interrupt_loop(interrupt_ready),
+            name="cancel-dispatcher:interrupt",
+        )
+
+        await session_ready.wait()
+        await task_ready.wait()
+        await interrupt_ready.wait()
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        """Cancel all dispatcher loops on context exit."""
+        for task in (
+            self._session_task,
+            self._task_cancel_task,
+            self._interrupt_task,
+        ):
+            if task is None:
+                continue
+            task.cancel()
+            try:
+                await task
+            except asyncio.CancelledError:
+                pass
+        self._session_task = None
+        self._task_cancel_task = None
+        self._interrupt_task = None
+
+    # ------------------------------------------------------------------
+    # Session-level cancel loop
+    # ------------------------------------------------------------------
+
+    async def _session_cancel_loop(self, ready: asyncio.Event) -> None:
+        """Subscribe to session cancel channel and act on each signal.
+
+        Args:
+            ready (`asyncio.Event`):
+                Signalled after the underlying SUBSCRIBE completes.
+        """
+        try:
+            async for payload in self._bus.subscribe(
+                MessageBusKeys.session_cancel_channel(),
+                on_ready=ready.set,
+            ):
+                sid = payload.get("session_id")
+                if isinstance(sid, str):
+                    self._cancel_session(sid)
+        except Exception:
+            logger.exception(
+                "CancelDispatcher session-cancel loop crashed.",
+            )
+        finally:
+            # Unblock ``__aenter__`` even if subscribe failed before
+            # ``on_ready`` ran, so startup cannot deadlock.
+            ready.set()
+
+    def _cancel_session(self, session_id: str) -> None:
+        """Cancel every locally-tracked task for a session.
+
+        Args:
+            session_id (`str`):
+                The session whose runs and BG tasks should be cancelled.
+        """
+        task = self._registry.get(session_id)
+        if task is not None and not task.done():
+            logger.info(
+                "CancelDispatcher: cancelling local chat run for "
+                "session %s",
+                session_id,
+            )
+            task.cancel()
+
+        bg_cancelled = self._bg_manager.cancel_session_tasks(session_id)
+        if bg_cancelled:
+            logger.info(
+                "CancelDispatcher: cancelled %d local BG task(s) for "
+                "session %s",
+                bg_cancelled,
+                session_id,
+            )
+
+    # ------------------------------------------------------------------
+    # Task-level cancel loop
+    # ------------------------------------------------------------------
+
+    async def _task_cancel_loop(self, ready: asyncio.Event) -> None:
+        """Subscribe to the task cancel channel and act on each signal.
+
+        Args:
+            ready (`asyncio.Event`):
+                Signalled after the underlying SUBSCRIBE completes.
+        """
+        try:
+            async for payload in self._bus.subscribe(
+                MessageBusKeys.task_cancel_channel(),
+                on_ready=ready.set,
+            ):
+                task_id = payload.get("task_id")
+                if not isinstance(task_id, str):
+                    continue
+                cancelled = self._bg_manager.cancel_task(task_id)
+                if cancelled:
+                    logger.info(
+                        "CancelDispatcher: cancelled local BG task %s "
+                        "via task-level broadcast.",
+                        task_id,
+                    )
+        except Exception:  # pylint: disable=broad-except
+            logger.exception(
+                "CancelDispatcher task-cancel loop crashed.",
+            )
+        finally:
+            # Unblock ``__aenter__`` even if subscribe failed before
+            # ``on_ready`` ran, so startup cannot deadlock.
+            ready.set()
+
+    # ------------------------------------------------------------------
+    # Session-level interrupt loop
+    # ------------------------------------------------------------------
+
+    async def _interrupt_loop(self, ready: asyncio.Event) -> None:
+        """Subscribe to the session interrupt channel and cancel matching
+        local tasks.
+
+        Args:
+            ready (`asyncio.Event`):
+                Signalled after the underlying SUBSCRIBE completes.
+        """
+        try:
+            async for payload in self._bus.subscribe(
+                MessageBusKeys.session_interrupt_channel(),
+                on_ready=ready.set,
+            ):
+                sid = payload.get("session_id")
+                if isinstance(sid, str):
+                    self._interrupt_session(sid)
+        except Exception:  # pylint: disable=broad-except
+            logger.exception(
+                "CancelDispatcher interrupt loop crashed.",
+            )
+        finally:
+            ready.set()
+
+    def _interrupt_session(self, session_id: str) -> None:
+        """Cancel the local chat-run task for a session.
+
+        Unlike ``_cancel_session``, this method only cancels the
+        chat-run asyncio task—it does **not** cancel background tasks.
+        The agent handles ``CancelledError`` gracefully at each
+        breakpoint, preserving partial context.
+
+        Args:
+            session_id (`str`):
+                The session whose chat run should be interrupted.
+        """
+        task = self._registry.get(session_id)
+        if task is not None and not task.done():
+            logger.info(
+                "CancelDispatcher: interrupting local chat run for "
+                "session %s",
+                session_id,
+            )
+            task.cancel()
diff --git a/src/agentscope/app/_manager/_chat_run_registry.py b/src/agentscope/app/_manager/_chat_run_registry.py
new file mode 100644
index 0000000..8659bbf
--- /dev/null
+++ b/src/agentscope/app/_manager/_chat_run_registry.py
@@ -0,0 +1,134 @@
+# -*- coding: utf-8 -*-
+"""Per-process registry of in-flight ``ChatService.run`` asyncio tasks.
+
+Owns the asyncio.Task handles only — it is not the public cancel
+entry point. The cross-process cancel path goes through the bus's
+:meth:`~agentscope.app.message_bus.MessageBus.session_publish_cancel`
+broadcast, picked up locally by
+:class:`~agentscope.app._manager.CancelDispatcher`, which then looks
+up the task here and calls ``.cancel()`` on it.
+
+A given ``session_id`` can have at most one entry. Concurrent runs for
+the same session are already prevented at a cluster level by
+:meth:`~agentscope.app.message_bus.MessageBus.session_run` (the
+distributed lock), so a second :meth:`spawn` for the same id is treated
+as a programming error.
+"""
+import asyncio
+from typing import Coroutine, Self
+
+from ..._logging import logger
+
+
+class ChatRunRegistry:
+    """In-process index of active chat-run asyncio tasks, keyed by
+    session id.
+
+    Used by :class:`~agentscope.app._manager.CancelDispatcher` to find
+    and cancel the local task for a given session, and by the lifespan
+    to cancel any leftover runs on application shutdown.
+    """
+
+    def __init__(self) -> None:
+        """Initialise an empty registry."""
+        self._tasks: dict[str, asyncio.Task] = {}
+
+    def spawn(
+        self,
+        coro: Coroutine,
+        *,
+        session_id: str,
+        name: str | None = None,
+    ) -> asyncio.Task:
+        """Create and register an asyncio task that runs ``coro``.
+
+        The task auto-removes from the registry when it finishes (via
+        ``add_done_callback``).
+
+        Args:
+            coro (`Coroutine`):
+                A coroutine — typically ``chat_service.run(...)`` — to
+                run as a background task.
+            session_id (`str`):
+                The session this run belongs to. Used as the registry
+                key for later cancel lookup.
+            name (`str | None`, optional):
+                Optional task name passed through to
+                :func:`asyncio.create_task`. Defaults to
+                ``f"chat-run:{session_id}"``.
+
+        Returns:
+            `asyncio.Task`:
+                The created task. Callers normally do not need to keep
+                the reference — the registry holds it for the task's
+                lifetime.
+
+        Raises:
+            `RuntimeError`:
+                When a non-finished task is already registered for
+                ``session_id``. Callers are expected to coordinate via
+                the distributed session lock before spawning.
+        """
+        existing = self._tasks.get(session_id)
+        if existing is not None and not existing.done():
+            raise RuntimeError(
+                f"Session {session_id!r} already has an active chat run "
+                "in this process.",
+            )
+
+        task = asyncio.create_task(
+            coro,
+            name=name or f"chat-run:{session_id}",
+        )
+        self._tasks[session_id] = task
+
+        def _cleanup(t: asyncio.Task) -> None:
+            # Only remove the entry if it still points at this task —
+            # a fresh spawn for the same sid may have replaced it.
+            if self._tasks.get(session_id) is t:
+                self._tasks.pop(session_id, None)
+
+        task.add_done_callback(_cleanup)
+        return task
+
+    def get(self, session_id: str) -> asyncio.Task | None:
+        """Return the registered task for ``session_id``, or ``None``.
+
+        Args:
+            session_id (`str`):
+                The session whose task to look up.
+
+        Returns:
+            `asyncio.Task | None`:
+                The task if one is currently registered for the
+                session, else ``None``.
+        """
+        return self._tasks.get(session_id)
+
+    async def __aenter__(self) -> Self:
+        """No-op enter; the registry has no startup work.
+
+        Returns:
+            `Self`: This registry instance.
+        """
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        """Cancel every still-running task on application shutdown.
+
+        Each task is cancelled and awaited so its ``finally`` blocks
+        and any ``async with`` cleanups (notably the bus's session
+        run-lock release) execute before the process exits.
+        """
+        if not self._tasks:
+            return
+        logger.info(
+            "ChatRunRegistry shutdown: cancelling %d in-flight chat run(s).",
+            len(self._tasks),
+        )
+        tasks = list(self._tasks.values())
+        for task in tasks:
+            task.cancel()
+        # Wait for every cancel to land; swallow CancelledError per task.
+        await asyncio.gather(*tasks, return_exceptions=True)
+        self._tasks.clear()
diff --git a/src/agentscope/app/_manager/_scheduler/__init__.py b/src/agentscope/app/_manager/_scheduler/__init__.py
new file mode 100644
index 0000000..365ce58
--- /dev/null
+++ b/src/agentscope/app/_manager/_scheduler/__init__.py
@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+"""The scheduler related components."""
+
+from ._scheduler_manager import SchedulerManager
+
+__all__ = [
+    "SchedulerManager",
+]
diff --git a/src/agentscope/app/_manager/_scheduler/_scheduler_manager.py b/src/agentscope/app/_manager/_scheduler/_scheduler_manager.py
new file mode 100644
index 0000000..18aa81a
--- /dev/null
+++ b/src/agentscope/app/_manager/_scheduler/_scheduler_manager.py
@@ -0,0 +1,432 @@
+# -*- coding: utf-8 -*-
+"""The cron scheduler manager class."""
+import json
+from collections.abc import Callable, Coroutine
+
+from typing import Self
+
+from ....message import HintBlock
+from ....permission import PermissionContext
+from ....state import AgentState
+from ....tool import ToolBase
+from ...._logging import logger
+from ._tools import ScheduleCreate, ScheduleDelete, ScheduleList, ScheduleView
+from ...message_bus import MessageBus, MessageBusKeys
+from ..._bus_ops import enqueue_run_trigger
+from ...storage import (
+    StorageBase,
+    ScheduleRecord,
+    ChatModelConfig,
+    SessionConfig,
+    SessionSource,
+)
+
+
+class SchedulerManager:
+    """The cron scheduler manager, responsible for managing scheduled-task
+    lifecycle within the agent service.
+
+    The manager owns both the in-memory APScheduler instance and the trigger
+    logic that fires scheduled tasks. Triggers do not call ``ChatService``
+    directly; instead they push a :class:`HintBlock` to the target session's
+    inbox and enqueue a wakeup, so that the application-wide
+    :class:`WakeupDispatcher` (running on any process) picks up the work.
+    This keeps the scheduler decoupled from ``ChatService`` and makes the
+    fire path consistent with team / background-tool result delivery.
+    """
+
+    def __init__(
+        self,
+        storage: StorageBase,
+        message_bus: MessageBus,
+    ) -> None:
+        """Initialize the scheduler manager.
+
+        Args:
+            storage (`StorageBase`):
+                The storage backend used for persistence and session
+                creation.
+            message_bus (`MessageBus`):
+                The application message bus. Each scheduled fire pushes
+                a :class:`HintBlock` to the target session's inbox and
+                enqueues a wakeup via this bus.
+        """
+        from apscheduler.schedulers.asyncio import AsyncIOScheduler
+
+        self._storage = storage
+        self._message_bus = message_bus
+        self._scheduler = AsyncIOScheduler()
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def __aenter__(self) -> Self:
+        """Start APScheduler and re-register persisted schedules.
+
+        Reading all schedules from storage and restoring them is the
+        only thing a caller would ever do right after starting this
+        manager, so the work lives inside the context entry — the
+        lifespan does not need to remember to call :meth:`restore`.
+
+        Returns:
+            `Self`: This manager instance.
+        """
+        logger.info("SchedulerManager starting APScheduler")
+        self._scheduler.start()
+        logger.info("SchedulerManager APScheduler started")
+
+        records = await self._storage.list_all_schedules()
+        if records:
+            await self.restore(records)
+
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        """Shut down the underlying APScheduler on context exit."""
+        logger.info("SchedulerManager shutting down APScheduler")
+        self._scheduler.shutdown()
+        logger.info("SchedulerManager APScheduler shut down")
+
+    # ------------------------------------------------------------------
+    # Trigger construction
+    # ------------------------------------------------------------------
+
+    def _build_trigger(
+        self,
+        record: ScheduleRecord,
+    ) -> Callable[[], Coroutine]:
+        """Build the zero-argument coroutine executed by APScheduler on each
+        trigger fire.
+
+        The returned coroutine:
+
+        1. Skips execution when the schedule is disabled.
+        2. Resolves or creates the target session (stateful reuses a fixed
+           session; non-stateful creates a fresh one on every fire).
+        3. Calls :class:`~agentscope.app._service._chat.ChatService` and
+           drains the response stream (fire-and-forget).
+        4. Catches and logs all exceptions to prevent APScheduler from
+           removing the job on failure.
+
+        Args:
+            record (`ScheduleRecord`):
+                The persisted schedule record that describes what to run.
+
+        Returns:
+            `Callable[[], Coroutine]`:
+                A zero-argument async callable suitable for APScheduler.
+        """
+        # Closure-friendly references so APScheduler doesn't have to
+        # re-look these up on every fire.
+        storage = self._storage
+        message_bus = self._message_bus
+
+        async def _trigger() -> None:
+            logger.info(
+                "[Schedule:%s(%s)] Trigger fired",
+                record.id,
+                record.data.name,
+            )
+
+            if not record.data.enabled:
+                logger.info(
+                    "[Schedule:%s(%s)] Skipped — schedule disabled",
+                    record.id,
+                    record.data.name,
+                )
+                return
+
+            try:
+                if record.data.stateful:
+                    stateful_session_id = f"{record.id}_stateful"
+                    logger.info(
+                        "[Schedule:%s(%s)] Stateful mode, "
+                        "looking up session %s",
+                        record.id,
+                        record.data.name,
+                        stateful_session_id,
+                    )
+                    session = await storage.get_session(
+                        record.user_id,
+                        record.agent_id,
+                        stateful_session_id,
+                    )
+                    if session is None:
+                        logger.info(
+                            "[Schedule:%s(%s)] First fire, "
+                            "creating stateful session",
+                            record.id,
+                            record.data.name,
+                        )
+                        state = AgentState()
+                        state.permission_context = PermissionContext(
+                            mode=record.data.permission_mode,
+                        )
+                        session_config = SessionConfig(
+                            workspace_id="",
+                            chat_model_config=record.data.chat_model_config,
+                        )
+                        session = await storage.upsert_session(
+                            user_id=record.user_id,
+                            agent_id=record.agent_id,
+                            config=session_config,
+                            state=state,
+                            session_id=stateful_session_id,
+                            source=SessionSource.SCHEDULE,
+                            source_schedule_id=record.id,
+                        )
+                    else:
+                        logger.info(
+                            "[Schedule:%s(%s)] Reusing existing "
+                            "stateful session %s",
+                            record.id,
+                            record.data.name,
+                            session.id,
+                        )
+                else:
+                    logger.info(
+                        "[Schedule:%s(%s)] Non-stateful mode, "
+                        "creating fresh session",
+                        record.id,
+                        record.data.name,
+                    )
+                    state = AgentState()
+                    state.permission_context = PermissionContext(
+                        mode=record.data.permission_mode,
+                    )
+                    session = await storage.upsert_session(
+                        user_id=record.user_id,
+                        agent_id=record.agent_id,
+                        config=SessionConfig(
+                            workspace_id="",
+                            chat_model_config=record.data.chat_model_config,
+                        ),
+                        state=state,
+                        source=SessionSource.SCHEDULE,
+                        source_schedule_id=record.id,
+                    )
+
+                logger.info(
+                    "[Schedule:%s(%s)] Session ready: %s, "
+                    "delivering prompt via inbox + wakeup",
+                    record.id,
+                    record.data.name,
+                    session.id,
+                )
+
+                # Wrap the schedule prompt in an XML tag so the LLM
+                # recognises it as a system-driven trigger rather than
+                # a regular user turn — same shape as team / system
+                # notification hints.
+                hint = HintBlock(
+                    hint=(
+                        f"<scheduled-task>\n"
+                        f"{record.data.description}\n"
+                        f"</scheduled-task>"
+                    ),
+                    source=json.dumps(
+                        {
+                            "label": "schedule",
+                            "sublabel": record.data.name,
+                        },
+                        ensure_ascii=False,
+                    ),
+                )
+                await message_bus.queue_push(
+                    MessageBusKeys.inbox(session.id),
+                    hint.model_dump(mode="json"),
+                )
+                await enqueue_run_trigger(
+                    message_bus,
+                    user_id=record.user_id,
+                    session_id=session.id,
+                    agent_id=record.agent_id,
+                )
+
+                logger.info(
+                    "[Schedule:%s(%s)] Wakeup enqueued for session %s",
+                    record.id,
+                    record.data.name,
+                    session.id,
+                )
+
+            except Exception:
+                logger.exception(
+                    "[Schedule:%s(%s)] Trigger failed",
+                    record.id,
+                    record.data.name,
+                )
+
+        return _trigger
+
+    # ------------------------------------------------------------------
+    # Schedule management
+    # ------------------------------------------------------------------
+
+    async def register_schedule(self, record: ScheduleRecord) -> str:
+        """Persist-and-register a schedule record with APScheduler.
+
+        Builds the trigger coroutine via :meth:`_build_trigger` and adds the
+        job to APScheduler.  This is the single entry point used by both the
+        HTTP API and the :class:`ScheduleCreate` agent tool.
+
+        Args:
+            record (`ScheduleRecord`):
+                The fully-populated record (already persisted to storage).
+
+        Returns:
+            `str`:
+                The APScheduler job ID (equal to ``record.id``).
+        """
+
+        from apscheduler.triggers.cron import CronTrigger
+
+        logger.info(
+            "Registering schedule %s(%s) cron=%s tz=%s",
+            record.id,
+            record.data.name,
+            record.data.cron_expression,
+            record.data.timezone,
+        )
+
+        # ``CronTrigger.from_crontab`` is a thin helper that only forwards
+        # the 5 parsed fields and ``timezone`` — it has no parameter for
+        # ``start_date`` / ``end_date``.  Parse the expression ourselves so
+        # the configured activation window is honoured.
+        fields = record.data.cron_expression.split()
+        if len(fields) != 5:
+            raise ValueError(
+                "Expected a 5-field cron expression, got "
+                f"{record.data.cron_expression!r}",
+            )
+        minute, hour, day, month, day_of_week = fields
+
+        trigger = self._build_trigger(record)
+        job = self._scheduler.add_job(
+            trigger,
+            trigger=CronTrigger(
+                minute=minute,
+                hour=hour,
+                day=day,
+                month=month,
+                day_of_week=day_of_week,
+                timezone=record.data.timezone,
+                start_date=record.data.started_at,
+                end_date=record.data.ended_at,
+            ),
+            id=record.id,
+            name=record.data.name,
+            misfire_grace_time=300,
+        )
+        logger.info(
+            "Schedule %s(%s) registered, next_run=%s",
+            record.id,
+            record.data.name,
+            job.next_run_time,
+        )
+        return job.id
+
+    async def remove_schedule(self, job_id: str) -> None:
+        """Remove a job from APScheduler.
+
+        Args:
+            job_id (`str`):
+                The APScheduler job ID to remove.
+        """
+        from apscheduler.jobstores.base import JobLookupError
+
+        logger.info("Removing schedule job %s", job_id)
+        try:
+            self._scheduler.remove_job(job_id)
+            logger.info("Schedule job %s removed", job_id)
+        except JobLookupError:
+            logger.warning("Schedule job %s not found in APScheduler", job_id)
+
+    async def restore(self, records: list[ScheduleRecord]) -> None:
+        """Re-register persisted schedules on service startup.
+
+        Only enabled schedules are restored.
+
+        Args:
+            records (`list[ScheduleRecord]`):
+                All schedule records loaded from storage on startup.
+        """
+        enabled = [r for r in records if r.data.enabled]
+        logger.info(
+            "Restoring schedules: %d total, %d enabled",
+            len(records),
+            len(enabled),
+        )
+        for record in enabled:
+            await self.register_schedule(record)
+        logger.info("Schedule restore complete")
+
+    async def list_tasks(self) -> list[dict]:
+        """Return a summary of all currently registered APScheduler jobs.
+
+        Returns:
+            `list[dict]`:
+                Each entry contains ``id``, ``name``, and ``next_run``.
+        """
+        return [
+            {
+                "id": job.id,
+                "name": job.name,
+                "next_run": job.next_run_time,
+            }
+            for job in self._scheduler.get_jobs()
+        ]
+
+    # ------------------------------------------------------------------
+    # Agent tools
+    # ------------------------------------------------------------------
+
+    async def list_tools(
+        self,
+        user_id: str,
+        agent_id: str,
+        chat_model_config: ChatModelConfig,
+    ) -> list[ToolBase]:
+        """Return the agent-facing tools provided by the scheduler manager.
+
+        Args:
+            user_id (`str`):
+                The authenticated user who owns the schedules.
+            agent_id (`str`):
+                The agent that will be run by newly created schedules.
+            chat_model_config (`ChatModelConfig`):
+                Model configuration inherited from the current session and
+                stored on new :class:`~...ScheduleRecord` objects.
+
+        Returns:
+            `list[ToolBase]`:
+                The four schedule tools: :class:`ScheduleCreate`,
+                :class:`ScheduleView`, :class:`ScheduleDelete`, and
+                :class:`ScheduleList`.
+        """
+        return [
+            ScheduleCreate(
+                user_id=user_id,
+                agent_id=agent_id,
+                chat_model_config=chat_model_config,
+                storage=self._storage,
+                scheduler_manager=self,
+            ),
+            ScheduleView(
+                user_id=user_id,
+                scheduler=self._scheduler,
+                storage=self._storage,
+            ),
+            ScheduleDelete(
+                user_id=user_id,
+                scheduler=self._scheduler,
+                storage=self._storage,
+                message_bus=self._message_bus,
+            ),
+            ScheduleList(
+                user_id=user_id,
+                scheduler=self._scheduler,
+                storage=self._storage,
+            ),
+        ]
diff --git a/src/agentscope/app/_manager/_scheduler/_tools/__init__.py b/src/agentscope/app/_manager/_scheduler/_tools/__init__.py
new file mode 100644
index 0000000..beb4b69
--- /dev/null
+++ b/src/agentscope/app/_manager/_scheduler/_tools/__init__.py
@@ -0,0 +1,14 @@
+# -*- coding: utf-8 -*-
+"""The schedule related tools."""
+
+from ._schedule_create import ScheduleCreate
+from ._schedule_delete import ScheduleDelete
+from ._schedule_list import ScheduleList
+from ._schedule_view import ScheduleView
+
+__all__ = [
+    "ScheduleCreate",
+    "ScheduleDelete",
+    "ScheduleList",
+    "ScheduleView",
+]
diff --git a/src/agentscope/app/_manager/_scheduler/_tools/_schedule_create.py b/src/agentscope/app/_manager/_scheduler/_tools/_schedule_create.py
new file mode 100644
index 0000000..36c773f
--- /dev/null
+++ b/src/agentscope/app/_manager/_scheduler/_tools/_schedule_create.py
@@ -0,0 +1,253 @@
+# -*- coding: utf-8 -*-
+"""The schedule create tool."""
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from .....message import ToolResultState, TextBlock
+from .....permission import (
+    PermissionContext,
+    PermissionDecision,
+    PermissionBehavior,
+    PermissionMode,
+)
+from .....state import AgentState
+from .....tool import ToolBase, ToolChunk
+from ....storage import (
+    ScheduleData,
+    ScheduleRecord,
+    ScheduleSource,
+    ChatModelConfig,
+)
+
+
+class _ScheduleCreateParams(BaseModel):
+    """The params for the schedule create tool."""
+
+    name: str = Field(description="Display name of the schedule.")
+
+    description: str = Field(
+        default="",
+        description="Description of the schedule, including its purpose.",
+    )
+
+    cron_expression: str = Field(
+        description="Standard 5-field cron expression, e.g. '0 9 * * 1-5'.",
+    )
+
+    timezone: str = Field(
+        default="UTC",
+        description="IANA timezone name used to evaluate the cron expression, "
+        "e.g. 'America/New_York' or 'Asia/Shanghai'.",
+    )
+
+    enabled: bool = Field(
+        default=True,
+        description="Whether the schedule is active immediately after "
+        "creation. Set to False to create a disabled schedule.",
+    )
+
+    started_at: datetime | None = Field(
+        default=None,
+        description="ISO-8601 datetime at which the schedule becomes active. "
+        "Defaults to the current time when not specified.",
+    )
+
+    ended_at: datetime | None = Field(
+        default=None,
+        description="ISO-8601 datetime at which the schedule stops firing. "
+        "If not set the schedule runs indefinitely.",
+    )
+
+    stateful: bool = Field(
+        default=False,
+        description="If True, consecutive executions share the same session "
+        "context. If False, each execution gets a fresh session.",
+    )
+
+    permission_mode: str = Field(
+        default=PermissionMode.DONT_ASK.value,
+        description=(
+            "Permission mode for the agent during scheduled execution. "
+            f"Allowed values: {[m.value for m in PermissionMode]}. "
+            "Defaults to 'dont_ask' since no user is present."
+        ),
+    )
+
+
+class ScheduleCreate(ToolBase):
+    """The schedule create tool.
+
+    Creates a new scheduled task that will execute the current agent at a
+    given cron interval.  The record is persisted to storage and immediately
+    registered with the in-memory APScheduler.
+
+    The schedule inherits the model configuration of the current session.
+    The agent that creates the schedule is also the agent that will be run
+    on each trigger.
+    """
+
+    name: str = "ScheduleCreate"
+
+    description: str = """Create a new recurring scheduled task for yourself. \
+You will be notified in a new session each time the schedule is triggered.
+
+**About the cron expression:**
+- Determine your current timezone first, that's very important for setting a \
+correct cron expression. Get it by bash command like `date +%z`, \
+`cat /etc/timezone` or directly ask the user.
+- Determine whether the task should run once or recur at an interval, \
+then set the cron expression accordingly.
+- For a one-off task, query the current time first and set the cron \
+expression to fire at that specific moment.
+- Set `started_at` and `ended_at` to match the user's requirements. \
+When in doubt, ask for clarification before creating the schedule.
+
+**About the description field:**
+- The `description` is the only context available to you when the \
+schedule fires in a new session. Include all necessary details: the goal, \
+expected output, constraints, relevant file paths, and anything else needed \
+to complete the task independently.
+"""
+
+    input_schema: dict = _ScheduleCreateParams.model_json_schema()
+
+    is_concurrency_safe: bool = False
+    is_read_only: bool = False
+    is_state_injected: bool = True
+    is_external_tool: bool = False
+    is_mcp: bool = False
+    mcp_name: str | None = None
+
+    def __init__(
+        self,
+        user_id: str,
+        agent_id: str,
+        chat_model_config: ChatModelConfig,
+        storage: Any,
+        scheduler_manager: Any,
+    ) -> None:
+        """Initialize the schedule create tool.
+
+        Args:
+            user_id (`str`):
+                The authenticated user who owns this schedule.
+            agent_id (`str`):
+                The agent that will be executed on each trigger.
+            chat_model_config (`ChatModelConfig`):
+                Model configuration inherited from the current session.
+            storage (`Any`):
+                The storage backend used to persist the schedule record.
+            scheduler_manager (`Any`):
+                The scheduler manager used to register the APScheduler job.
+                Must expose a ``register_schedule(record)`` coroutine.
+        """
+        self._user_id = user_id
+        self._agent_id = agent_id
+        self._chat_model_config = chat_model_config
+        self._storage = storage
+        self._scheduler_manager = scheduler_manager
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        """Check permission for the tool usage."""
+        return PermissionDecision(
+            behavior=PermissionBehavior.ALLOW,
+            message=f"{self.name} is always allowed to be called.",
+        )
+
+    async def __call__(  # type: ignore[override]
+        self,
+        name: str,
+        cron_expression: str,
+        description: str = "",
+        timezone: str = "UTC",
+        enabled: bool = True,
+        started_at: datetime | None = None,
+        ended_at: datetime | None = None,
+        stateful: bool = False,
+        permission_mode: str = PermissionMode.DONT_ASK.value,
+        _agent_state: AgentState | None = None,
+    ) -> ToolChunk:
+        """Create a new scheduled task.
+
+        Args:
+            name (`str`):
+                Display name of the schedule.
+            cron_expression (`str`):
+                Standard 5-field cron expression, e.g. ``'0 9 * * 1-5'``.
+            description (`str`, optional):
+                Human-readable description of what this schedule does.
+            timezone (`str`, optional):
+                IANA timezone name, e.g. ``'Asia/Shanghai'``.
+            enabled (`bool`, optional):
+                Whether the schedule is active immediately after creation.
+            started_at (`datetime | None`, optional):
+                Datetime at which the schedule becomes active. Defaults to
+                the current time when not specified.
+            ended_at (`datetime | None`, optional):
+                Datetime at which the schedule stops firing. If not set the
+                schedule runs indefinitely.
+            stateful (`bool`, optional):
+                Whether consecutive executions share the same session context.
+            permission_mode (`str`, optional):
+                Permission mode value string.
+            _agent_state (`AgentState | None`, optional):
+                Injected agent state; provides the source session ID.
+
+        Returns:
+            `ToolChunk`:
+                A chunk with the new schedule ID on success, or an error
+                description on failure.
+        """
+        try:
+            perm_mode = PermissionMode(permission_mode)
+        except ValueError:
+            perm_mode = PermissionMode.DONT_ASK
+
+        source_session_id = (
+            _agent_state.session_id if _agent_state is not None else ""
+        )
+
+        record = ScheduleRecord(
+            user_id=self._user_id,
+            agent_id=self._agent_id,
+            data=ScheduleData(
+                name=name,
+                description=description,
+                enabled=enabled,
+                cron_expression=cron_expression,
+                timezone=timezone,
+                started_at=started_at or datetime.now(),
+                ended_at=ended_at,
+                stateful=stateful,
+                permission_mode=perm_mode,
+                source=ScheduleSource.AGENT,
+                source_session_id=source_session_id,
+                chat_model_config=self._chat_model_config,
+            ),
+        )
+
+        await self._storage.upsert_schedule(self._user_id, record)
+        await self._scheduler_manager.register_schedule(record)
+
+        return ToolChunk(
+            content=[
+                TextBlock(
+                    text=(
+                        f"Schedule {name!r} created successfully.\n"
+                        f"Schedule ID: {record.id}\n"
+                        f"Cron: {cron_expression} (timezone: {timezone})\n"
+                        f"Enabled: {enabled}\n"
+                        f"Started at: {record.data.started_at}\n"
+                        f"Ended at: {ended_at or '(no end time)'}\n"
+                        f"Stateful: {stateful}"
+                    ),
+                ),
+            ],
+            state=ToolResultState.SUCCESS,
+        )
diff --git a/src/agentscope/app/_manager/_scheduler/_tools/_schedule_delete.py b/src/agentscope/app/_manager/_scheduler/_tools/_schedule_delete.py
new file mode 100644
index 0000000..aa1a860
--- /dev/null
+++ b/src/agentscope/app/_manager/_scheduler/_tools/_schedule_delete.py
@@ -0,0 +1,154 @@
+# -*- coding: utf-8 -*-
+"""Schedule delete tool – removes a job from the scheduler and storage."""
+from typing import Any
+
+from pydantic import BaseModel, Field
+from apscheduler.jobstores.base import JobLookupError
+
+from .....message import ToolResultState, TextBlock
+from .....permission import (
+    PermissionContext,
+    PermissionDecision,
+    PermissionBehavior,
+)
+from .....tool import ToolBase, ToolChunk
+from ....message_bus import MessageBus
+from ....storage._base import StorageBase
+
+
+class _ScheduleDeleteParams(BaseModel):
+    """The params for the schedule delete tool."""
+
+    schedule_id: str = Field(
+        description="The schedule ID to delete (permanently remove).",
+    )
+
+
+class ScheduleDelete(ToolBase):
+    """The schedule delete tool.
+
+    Permanently removes the given scheduled job from APScheduler,
+    storage, and the message bus. Every execution session spawned by
+    the schedule is cancelled (if running) and has its bus state
+    purged. The job cannot be recovered after removal.
+    """
+
+    name: str = "ScheduleDelete"
+
+    description: str = (
+        "Permanently delete a scheduled task by its schedule ID. "
+        "After this call the task will no longer be executed and its record "
+        "will be deleted from storage."
+    )
+    input_schema: dict = _ScheduleDeleteParams.model_json_schema()
+
+    is_concurrency_safe: bool = False
+    is_read_only: bool = False
+    is_state_injected: bool = False
+    is_external_tool: bool = False
+    is_mcp: bool = False
+    mcp_name: str | None = None
+
+    def __init__(
+        self,
+        user_id: str,
+        scheduler: Any,
+        storage: StorageBase,
+        message_bus: MessageBus,
+    ) -> None:
+        """Initialize the schedule delete tool.
+
+        Args:
+            user_id (`str`):
+                The authenticated user; used to scope the storage deletion.
+            scheduler (`Any`):
+                The ``AsyncIOScheduler`` instance whose job will be removed.
+            storage (`StorageBase`):
+                The storage backend used to delete the persisted record.
+            message_bus (`MessageBus`):
+                The message bus used to cancel in-flight chat runs for
+                any execution session spawned by this schedule and to
+                purge their per-session bus state.
+        """
+        self._user_id = user_id
+        self._scheduler = scheduler
+        self._storage = storage
+        self._message_bus = message_bus
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        """Check permission for the tool usage."""
+        return PermissionDecision(
+            behavior=PermissionBehavior.ALLOW,
+            message=f"{self.name} is always allowed to be called.",
+        )
+
+    async def __call__(
+        self,
+        schedule_id: str,
+    ) -> ToolChunk:  # type: ignore[override]
+        """Permanently delete the scheduled task with the given ID.
+
+        Delegates the storage + bus cascade to
+        :meth:`SessionService.delete_schedule`, which cancels in-flight
+        runs for any session this schedule spawned and purges their
+        bus state before dropping the schedule record. The APScheduler
+        job is removed separately because it lives in-process and the
+        service layer is bus/storage-only.
+
+        Args:
+            schedule_id (`str`):
+                The unique identifier of the schedule to delete.
+
+        Returns:
+            `ToolChunk`:
+                A chunk describing the result of the delete operation.
+        """
+
+        # Remove from the in-memory scheduler (best-effort; may already be
+        # absent if the job finished naturally or the server restarted)
+        try:
+            self._scheduler.remove_job(schedule_id)
+        except JobLookupError:
+            pass
+
+        # Local import to avoid a circular dependency between
+        # ``_manager`` and ``_service`` at module load.
+        from ...._service import SessionService  # noqa: PLC0415
+
+        session_service = SessionService(
+            storage=self._storage,
+            message_bus=self._message_bus,
+        )
+        deleted = await session_service.delete_schedule(
+            self._user_id,
+            schedule_id,
+        )
+
+        if not deleted:
+            return ToolChunk(
+                content=[
+                    TextBlock(
+                        text=(
+                            f"ScheduleNotFoundError: Schedule with id "
+                            f"{schedule_id!r} not found in storage."
+                        ),
+                    ),
+                ],
+                state=ToolResultState.ERROR,
+            )
+
+        return ToolChunk(
+            content=[
+                TextBlock(
+                    text=(
+                        f"Schedule {schedule_id!r} has been permanently "
+                        f"deleted."
+                    ),
+                ),
+            ],
+            state=ToolResultState.SUCCESS,
+        )
diff --git a/src/agentscope/app/_manager/_scheduler/_tools/_schedule_list.py b/src/agentscope/app/_manager/_scheduler/_tools/_schedule_list.py
new file mode 100644
index 0000000..29bce5d
--- /dev/null
+++ b/src/agentscope/app/_manager/_scheduler/_tools/_schedule_list.py
@@ -0,0 +1,115 @@
+# -*- coding: utf-8 -*-
+"""The tool to list the scheduled jobs in the cron scheduler manager."""
+from typing import Any
+
+from pydantic import BaseModel
+
+from .....message import ToolResultState, TextBlock
+from .....permission import (
+    PermissionContext,
+    PermissionDecision,
+    PermissionBehavior,
+)
+from .....tool import ToolBase, ToolChunk
+from ....storage import StorageBase
+
+
+class _ScheduleListParams(BaseModel):
+    """The params for the schedule list tool."""
+
+
+class ScheduleList(ToolBase):
+    """The schedule list tool.
+
+    Lists all scheduled tasks owned by the current user.  Each entry is
+    fetched from storage (rich :class:`ScheduleData`) and augmented with
+    ``next_run_time`` from the in-memory APScheduler job when available.
+    """
+
+    name: str = "ScheduleList"
+
+    description: str = (
+        "List all scheduled tasks for the current user. "
+        "Shows schedule ID, name, cron expression, timezone, next run time, "
+        "enabled/disabled status, and whether the schedule is stateful."
+    )
+    input_schema: dict = _ScheduleListParams.model_json_schema()
+
+    is_concurrency_safe: bool = True
+    is_read_only: bool = True
+    is_state_injected: bool = False
+    is_external_tool: bool = False
+    is_mcp: bool = False
+    mcp_name: str | None = None
+
+    def __init__(
+        self,
+        user_id: str,
+        scheduler: Any,
+        storage: StorageBase,
+    ) -> None:
+        """Initialize the schedule list tool.
+
+        Args:
+            user_id (`str`):
+                The authenticated user; used to scope the storage lookup.
+            scheduler (`Any`):
+                The ``AsyncIOScheduler`` instance for reading ``next_run_time``
+            storage (`StorageBase`):
+                The storage backend that holds the persisted schedule records.
+        """
+        self._user_id = user_id
+        self._scheduler = scheduler
+        self._storage = storage
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        """Check permission for the tool usage."""
+        return PermissionDecision(
+            behavior=PermissionBehavior.ALLOW,
+            message=f"{self.name} is always allowed to be called.",
+        )
+
+    async def __call__(self) -> ToolChunk:  # type: ignore[override]
+        """List all scheduled tasks for the current user.
+
+        Returns:
+            `ToolChunk`:
+                A chunk containing a formatted list of all scheduled tasks,
+                or a message indicating none exist.
+        """
+        records = await self._storage.list_schedules(self._user_id)
+
+        if not records:
+            return ToolChunk(
+                content=[TextBlock(text="No scheduled tasks found.")],
+                state=ToolResultState.SUCCESS,
+            )
+
+        # Build a map of schedule_id -> next_run_time from the live scheduler
+        next_run_map: dict[str, str] = {
+            job.id: str(job.next_run_time)
+            for job in self._scheduler.get_jobs()
+        }
+
+        lines: list[str] = [f"Found {len(records)} scheduled task(s):\n"]
+        for record in records:
+            enabled_str = "enabled" if record.data.enabled else "disabled"
+            next_run = next_run_map.get(record.id, "not in scheduler")
+            lines.append(
+                f"- [{enabled_str}] {record.data.name!r}  (ID: {record.id})\n"
+                f"  Cron:      {record.data.cron_expression}"
+                f" ({record.data.timezone})\n"
+                f"  Next run:  {next_run}\n"
+                f"  Stateful:  {record.data.stateful}"
+                f"  |  Agent: {record.agent_id}\n"
+                f"  Source:    {record.data.source.value}\n",
+            )
+
+        return ToolChunk(
+            content=[TextBlock(text="\n".join(lines))],
+            state=ToolResultState.SUCCESS,
+        )
diff --git a/src/agentscope/app/_manager/_scheduler/_tools/_schedule_view.py b/src/agentscope/app/_manager/_scheduler/_tools/_schedule_view.py
new file mode 100644
index 0000000..4116a29
--- /dev/null
+++ b/src/agentscope/app/_manager/_scheduler/_tools/_schedule_view.py
@@ -0,0 +1,138 @@
+# -*- coding: utf-8 -*-
+"""The schedule view tool."""
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from .....message import ToolResultState, TextBlock
+from .....permission import (
+    PermissionContext,
+    PermissionDecision,
+    PermissionBehavior,
+)
+from .....tool import ToolBase, ToolChunk
+from ....storage import StorageBase
+
+
+class _ScheduleViewParams(BaseModel):
+    """The params for the schedule view tool."""
+
+    schedule_id: str = Field(
+        description="The schedule ID.",
+    )
+
+
+class ScheduleView(ToolBase):
+    """The schedule view tool.
+
+    Fetches the persisted :class:`ScheduleRecord` from storage and enriches
+    it with the ``next_run_time`` from the in-memory APScheduler job.
+    """
+
+    name: str = "ScheduleView"
+
+    description: str = (
+        "View the full details of a scheduled task by its schedule ID, "
+        "including cron expression, timezone, stateful flag, permission "
+        "mode, and the next scheduled run time."
+    )
+    input_schema: dict = _ScheduleViewParams.model_json_schema()
+
+    is_concurrency_safe: bool = True
+    is_read_only: bool = True
+    is_state_injected: bool = False
+    is_external_tool: bool = False
+    is_mcp: bool = False
+    mcp_name: str | None = None
+
+    def __init__(
+        self,
+        user_id: str,
+        scheduler: Any,
+        storage: StorageBase,
+    ) -> None:
+        """Initialize the schedule view tool.
+
+        Args:
+            user_id (`str`):
+                The authenticated user; used to scope the storage lookup.
+            scheduler (`Any`):
+                The ``AsyncIOScheduler`` instance for
+                reading ``next_run_time``.
+            storage (`StorageBase`):
+                The storage backend that holds the persisted schedule records.
+        """
+        self._user_id = user_id
+        self._scheduler = scheduler
+        self._storage = storage
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        """Check permission for the tool usage."""
+        return PermissionDecision(
+            behavior=PermissionBehavior.ALLOW,
+            message=f"{self.name} is always allowed to be called.",
+        )
+
+    async def __call__(
+        self,
+        schedule_id: str,
+    ) -> ToolChunk:  # type: ignore[override]
+        """View the full details of a scheduled task.
+
+        Args:
+            schedule_id (`str`):
+                The unique identifier of the schedule to view.
+
+        Returns:
+            `ToolChunk`:
+                A chunk containing the formatted schedule details, or an
+                error description if the schedule is not found.
+        """
+        record = await self._storage.get_schedule(self._user_id, schedule_id)
+
+        if record is None:
+            return ToolChunk(
+                content=[
+                    TextBlock(
+                        text=(
+                            f"ScheduleNotFoundError: Schedule with "
+                            f"id {schedule_id!r} not found."
+                        ),
+                    ),
+                ],
+                state=ToolResultState.ERROR,
+            )
+
+        job = self._scheduler.get_job(schedule_id)
+        next_run = (
+            str(job.next_run_time)
+            if job is not None
+            else "not in scheduler (may be disabled)"
+        )
+        enabled_str = "enabled" if record.data.enabled else "disabled"
+
+        text = (
+            f"Schedule ID:     {record.id}\n"
+            f"Name:            {record.data.name}\n"
+            f"Description:     {record.data.description or '(none)'}\n"
+            f"Status:          {enabled_str}\n"
+            f"Cron:            {record.data.cron_expression}"
+            f" (timezone: {record.data.timezone})\n"
+            f"Next run:        {next_run}\n"
+            f"Stateful:        {record.data.stateful}\n"
+            f"Permission mode: {record.data.permission_mode.value}\n"
+            f"Source:          {record.data.source.value}\n"
+            f"Source session:  {record.data.source_session_id or '(none)'}\n"
+            f"Agent ID:        {record.agent_id}\n"
+            f"Created at:      {record.created_at}\n"
+            f"Updated at:      {record.updated_at}\n"
+        )
+
+        return ToolChunk(
+            content=[TextBlock(text=text)],
+            state=ToolResultState.SUCCESS,
+        )
diff --git a/src/agentscope/app/_manager/_wakeup_dispatcher.py b/src/agentscope/app/_manager/_wakeup_dispatcher.py
new file mode 100644
index 0000000..5932340
--- /dev/null
+++ b/src/agentscope/app/_manager/_wakeup_dispatcher.py
@@ -0,0 +1,375 @@
+# -*- coding: utf-8 -*-
+"""Single per-process dispatcher for all cross-session run triggers.
+
+One asyncio task per process. Subscribes to the shared trigger signal
+channel and drains the durable trigger queue on each signal. It is the
+**sole** site that spawns :meth:`ChatService.run` into the shared
+:class:`ChatRunRegistry`, which is what makes concurrent-spawn races
+(two writers contending for one session's run slot → a spurious "already
+has an active chat run" 409) structurally impossible: every run trigger
+funnels through this one serial consumer.
+
+Each queue entry carries a ``kind`` that selects how a busy session is
+handled:
+
+- ``wake`` (idle-session wake-up, ``input_msg=None``): skipped while the
+  session is already running — the live run will drain the inbox.
+- ``resume`` (a parked HITL run being fed its result): must *not* be
+  skipped while running, because the session is typically still running
+  the parked tail at trigger time. It is re-queued after a short backoff
+  until the parked run releases its session lock, then spawned with the
+  carried input event.
+
+All bus keys live on the :class:`MessageBus` base class (see
+``enqueue_wakeup`` / ``enqueue_input``, ``dequeue_wakeups``,
+``subscribe_wakeup_signal``, ``session_is_running``), so this file has
+no hard-coded key strings.
+"""
+import asyncio
+from typing import TYPE_CHECKING, Self
+
+from pydantic import TypeAdapter
+
+from ..._logging import logger
+from ...event import (
+    ExternalExecutionResultEvent,
+    UserConfirmResultEvent,
+    UserInterruptEvent,
+)
+from ..message_bus import MessageBusKeys
+from .._bus_ops import enqueue_run_trigger
+
+if TYPE_CHECKING:
+    from ..message_bus import MessageBus
+    from ..storage import StorageBase
+    from .._service import ChatService
+    from ._chat_run_registry import ChatRunRegistry
+
+# Parses a queued ``resume`` input dict back into its concrete event,
+# discriminated by the ``type`` field shared by these result events.
+_RESUME_INPUT_ADAPTER: TypeAdapter = TypeAdapter(
+    UserConfirmResultEvent | ExternalExecutionResultEvent | UserInterruptEvent,
+)
+
+# Delay before re-queuing a ``resume`` trigger whose target session is
+# still running (the parked run is finishing and about to free its
+# lock). Short enough to feel instant to the user, long enough to avoid
+# a hot re-enqueue loop while the lock is held.
+_RESUME_RETRY_BACKOFF_SECS = 0.1
+
+
+class WakeupDispatcher:
+    """One asyncio task per process, draining the shared trigger queue.
+
+    Args:
+        message_bus (`MessageBus`):
+            Application message bus. Used for signal subscription,
+            queue drain, ``session_is_running`` checks, and re-queuing
+            deferred ``resume`` triggers.
+        storage (`StorageBase`):
+            Persistent storage backend. Consulted before spawning a
+            run so triggers whose target session has been deleted are
+            dropped instead of crashing :class:`ChatService.run`.
+        chat_service (`ChatService`):
+            Drives the actual chat run when a trigger fires.
+        chat_run_registry (`ChatRunRegistry`):
+            Per-process registry that holds the spawned task handle so
+            it can be located by :class:`CancelDispatcher`.
+    """
+
+    def __init__(
+        self,
+        message_bus: "MessageBus",
+        storage: "StorageBase",
+        chat_service: "ChatService",
+        chat_run_registry: "ChatRunRegistry",
+    ) -> None:
+        """Bind dependencies.
+
+        Args:
+            message_bus (`MessageBus`):
+                Application message bus.
+            storage (`StorageBase`):
+                Persistent storage backend.
+            chat_service (`ChatService`):
+                Drives session runs via :meth:`ChatService.run`.
+            chat_run_registry (`ChatRunRegistry`):
+                Shared chat-run registry to spawn into.
+        """
+        self._bus = message_bus
+        self._storage = storage
+        self._chat_service = chat_service
+        self._registry = chat_run_registry
+        self._task: asyncio.Task | None = None
+        # Detached backoff timers for deferred ``resume`` re-enqueues.
+        # Held so they are not garbage-collected mid-sleep and can be
+        # cancelled on shutdown.
+        self._retry_tasks: set[asyncio.Task] = set()
+
+    async def __aenter__(self) -> Self:
+        """Start the dispatcher loop and wait until its bus
+        subscription is live.
+
+        Also performs an initial drain right after subscription so
+        triggers produced while this process was down (durable in
+        the queue) are picked up immediately on startup.
+
+        Returns:
+            `Self`: This dispatcher instance.
+        """
+        ready = asyncio.Event()
+        self._task = asyncio.create_task(
+            self._loop(ready),
+            name="wakeup-dispatcher",
+        )
+        await ready.wait()
+        await self._drain_and_dispatch()
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        """Cancel the dispatcher loop and any pending retries."""
+        retries = list(self._retry_tasks)
+        for retry in retries:
+            retry.cancel()
+        for retry in retries:
+            try:
+                await retry
+            except asyncio.CancelledError:
+                pass
+        self._retry_tasks.clear()
+        if self._task is None:
+            return
+        self._task.cancel()
+        try:
+            await self._task
+        except asyncio.CancelledError:
+            pass
+        self._task = None
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    async def _loop(self, ready: asyncio.Event) -> None:
+        """Long-lived loop: subscribe to the signal channel and drain
+        the queue on every received signal.
+
+        Args:
+            ready (`asyncio.Event`):
+                Signalled after the underlying SUBSCRIBE completes.
+                :meth:`start` blocks on this so callers can publish a
+                trigger immediately after start without racing.
+        """
+        try:
+            async for _signal in self._bus.subscribe(
+                MessageBusKeys.wakeup_signal(),
+                on_ready=ready.set,
+            ):
+                await self._drain_and_dispatch()
+        except Exception:  # pylint: disable=broad-except
+            logger.exception(
+                "WakeupDispatcher loop crashed; subscription ended.",
+            )
+
+    async def _drain_and_dispatch(self) -> None:
+        """Read up to a batch of trigger entries and dispatch each."""
+        try:
+            raw_entries = await self._bus.queue_drain(
+                MessageBusKeys.wakeup_queue(),
+                max_count=64,
+            )
+            entries = [payload for _entry_id, payload in raw_entries]
+        except Exception:  # pylint: disable=broad-except
+            logger.exception("WakeupDispatcher: dequeue_wakeups failed.")
+            return
+
+        for payload in entries:
+            try:
+                user_id = payload["user_id"]
+                session_id = payload["session_id"]
+                agent_id = payload["agent_id"]
+            except (KeyError, TypeError):
+                logger.warning(
+                    "WakeupDispatcher: skipping malformed trigger entry %r",
+                    payload,
+                )
+                continue
+            # Entries from older producers omit ``kind`` — treat as wake.
+            kind = payload.get("kind", MessageBusKeys.WAKEUP_KIND_WAKE)
+            await self._dispatch_one(
+                user_id=user_id,
+                session_id=session_id,
+                agent_id=agent_id,
+                kind=kind,
+                raw_input=payload.get("input"),
+            )
+
+    async def _dispatch_one(
+        self,
+        user_id: str,
+        session_id: str,
+        agent_id: str,
+        kind: str,
+        raw_input: dict | None,
+    ) -> None:
+        """Dispatch a single trigger entry by its ``kind``.
+
+        Args:
+            user_id (`str`):
+                The owning user id.
+            session_id (`str`):
+                The session to trigger.
+            agent_id (`str`):
+                The agent that owns the session.
+            kind (`str`):
+                Trigger kind (``wake`` / ``resume``); see module docstring.
+            raw_input (`dict | None`):
+                Serialised input event for ``resume`` triggers, else
+                ``None``.
+        """
+        is_resume = kind == MessageBusKeys.WAKEUP_KIND_RESUME
+
+        # Parse the resume input early so every downstream path
+        # (lock-retry, spawn-retry) receives a typed event object
+        # rather than a raw dict.
+        input_msg: UserConfirmResultEvent | ExternalExecutionResultEvent | None
+        input_msg = None
+        if is_resume:
+            if raw_input is None:
+                logger.warning(
+                    "WakeupDispatcher: dropping resume trigger for session "
+                    "%s — no input event carried.",
+                    session_id,
+                )
+                return
+            try:
+                input_msg = _RESUME_INPUT_ADAPTER.validate_python(raw_input)
+            except Exception:  # pylint: disable=broad-except
+                logger.exception(
+                    "WakeupDispatcher: dropping resume trigger for session "
+                    "%s — input event failed to parse: %r",
+                    session_id,
+                    raw_input,
+                )
+                return
+
+        if await self._bus.is_locked(
+            MessageBusKeys.session_lock(session_id),
+        ):
+            if is_resume:
+                # The session is busy finishing its parked tail. Do NOT
+                # drop the resume — re-queue it after a short backoff so
+                # it lands once the parked run releases its lock.
+                self._schedule_resume_retry(
+                    user_id,
+                    session_id,
+                    agent_id,
+                    input_msg,
+                )
+            # ``wake`` triggers are safe to drop while running — the
+            # live run drains the inbox itself.
+            return
+
+        # Orphan guard: the queue is unaware of session lifecycle. A
+        # trigger enqueued before the session was deleted (e.g. by a
+        # BG-task completion callback or a schedule trigger) will still
+        # arrive here. Drop it rather than letting ChatService.run crash
+        # on a missing storage record.
+        if (
+            await self._storage.get_session(user_id, agent_id, session_id)
+            is None
+        ):
+            logger.warning(
+                "WakeupDispatcher: dropping %s trigger for session %s "
+                "(agent %s, user %s) — session no longer exists in "
+                "storage; it was likely enqueued before the session was "
+                "deleted.",
+                kind,
+                session_id,
+                agent_id,
+                user_id,
+            )
+            return
+
+        try:
+            self._registry.spawn(
+                self._chat_service.run(
+                    user_id=user_id,
+                    session_id=session_id,
+                    agent_id=agent_id,
+                    input_msg=input_msg,
+                ),
+                session_id=session_id,
+                name=f"{kind}-run:{session_id}",
+            )
+        except RuntimeError:
+            # A local run was registered between the running-check and
+            # the spawn. For ``wake`` that run will drain the inbox; for
+            # ``resume`` re-queue so the result is not lost.
+            if is_resume:
+                self._schedule_resume_retry(
+                    user_id,
+                    session_id,
+                    agent_id,
+                    input_msg,
+                )
+            else:
+                logger.debug(
+                    "WakeupDispatcher: skipping wake trigger for session "
+                    "%s; a local run is already registered.",
+                    session_id,
+                )
+
+    def _schedule_resume_retry(
+        self,
+        user_id: str,
+        session_id: str,
+        agent_id: str,
+        input_msg: UserConfirmResultEvent
+        | ExternalExecutionResultEvent
+        | None,
+    ) -> None:
+        """Re-enqueue a ``resume`` trigger after a short backoff.
+
+        Spawns a detached timer that sleeps, then re-enqueues the resume
+        (which re-fires the signal, re-driving the drain). This keeps the
+        resume alive across the window where the parked run still holds
+        the session lock, without a hot re-enqueue loop.
+
+        Args:
+            user_id (`str`):
+                The owning user id.
+            session_id (`str`):
+                The session to resume.
+            agent_id (`str`):
+                The agent that owns the session.
+            input_msg:
+                The parsed input event to redeliver.
+        """
+
+        async def _retry() -> None:
+            try:
+                await asyncio.sleep(_RESUME_RETRY_BACKOFF_SECS)
+                await enqueue_run_trigger(
+                    self._bus,
+                    user_id=user_id,
+                    session_id=session_id,
+                    agent_id=agent_id,
+                    kind=MessageBusKeys.WAKEUP_KIND_RESUME,
+                    inputs=input_msg,
+                )
+            except asyncio.CancelledError:
+                pass
+            except Exception:  # pylint: disable=broad-except
+                logger.exception(
+                    "WakeupDispatcher: failed to re-enqueue resume trigger "
+                    "for session %s.",
+                    session_id,
+                )
+
+        task = asyncio.create_task(
+            _retry(),
+            name=f"resume-retry:{session_id}",
+        )
+        self._retry_tasks.add(task)
+        task.add_done_callback(self._retry_tasks.discard)
diff --git a/src/agentscope/app/_router/__init__.py b/src/agentscope/app/_router/__init__.py
new file mode 100644
index 0000000..9f8ea42
--- /dev/null
+++ b/src/agentscope/app/_router/__init__.py
@@ -0,0 +1,23 @@
+# -*- coding: utf-8 -*-
+"""App routers."""
+from ._agent import agent_router
+from ._chat import chat_router
+from ._credential import credential_router
+from ._knowledge_base import knowledge_base_router
+from ._schedule import schedule_router
+from ._session import session_router
+from ._model import model_router
+from ._tts_model import tts_model_router
+from ._workspace import workspace_router
+
+__all__ = [
+    "agent_router",
+    "model_router",
+    "tts_model_router",
+    "chat_router",
+    "credential_router",
+    "knowledge_base_router",
+    "schedule_router",
+    "session_router",
+    "workspace_router",
+]
diff --git a/src/agentscope/app/_router/_agent.py b/src/agentscope/app/_router/_agent.py
new file mode 100644
index 0000000..e7b622a
--- /dev/null
+++ b/src/agentscope/app/_router/_agent.py
@@ -0,0 +1,318 @@
+# -*- coding: utf-8 -*-
+"""Agent router — CRUD endpoints for agent configurations."""
+from datetime import datetime
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from pydantic import ValidationError
+
+from ...agent import ContextConfig, ReActConfig
+from ..._utils._common import _flatten_json_schema
+from ..access import ResourceKind
+from ..deps import (
+    get_current_user_id,
+    get_resource_access_service,
+    get_session_service,
+    get_storage,
+)
+from ._schema import (
+    AgentSchemaResponse,
+    AgentSchemaV2Response,
+    ListAgentsResponse,
+    CreateAgentRequest,
+    CreateAgentResponse,
+    UpdateAgentRequest,
+)
+from .._service import AgentView, ResourceAccessService, SessionService
+from ..storage import StorageBase, AgentData, AgentRecord
+
+agent_router = APIRouter(
+    prefix="/agent",
+    tags=["agent"],
+    responses={404: {"description": "Not found"}},
+)
+
+
+@agent_router.get(
+    "/schema",
+    response_model=AgentSchemaResponse,
+    deprecated=True,
+    summary="[Deprecated] Legacy sectioned schema — use /schema/v2",
+)
+async def get_agent_schema() -> AgentSchemaResponse:
+    """Return the legacy sectioned JSON Schema fragments.
+
+    .. deprecated::
+        Superseded by :func:`get_agent_schema_v2`, which returns the
+        full :class:`AgentData` schema in a single ``schema`` field.
+        Kept for backwards compatibility with existing API consumers.
+        New consumers should call ``GET /agent/schema/v2``.
+
+    The frontend previously used three sections — identity, context
+    config, and react config — so we return them as separate
+    self-contained schemas rather than a single :class:`AgentData`
+    schema with ``$ref`` s.
+
+    Returns:
+        `AgentSchemaResponse`:
+            Schemas for the three form sections.
+    """
+    # Slice ``AgentData``'s schema down to the identity-relevant fields.
+    # Going through ``AgentData.model_json_schema()`` (rather than building
+    # a dict by hand) keeps Pydantic as the single source of truth for
+    # defaults, titles, descriptions, and the ``format: textarea`` hint.
+    agent_schema = AgentData.model_json_schema()
+    identity_keys = ("name", "system_prompt")
+    identity = {
+        "type": "object",
+        "title": "Identity",
+        "properties": {
+            k: v
+            for k, v in agent_schema.get("properties", {}).items()
+            if k in identity_keys
+        },
+        "required": [
+            r for r in agent_schema.get("required", []) if r in identity_keys
+        ],
+    }
+
+    context_schema = ContextConfig.model_json_schema()
+    # ``summary_schema`` holds a Pydantic JSON Schema describing how the
+    # compression model should structure its output. The end-user is not
+    # expected to edit it from the form, so we hide it.
+    context_schema.get("properties", {}).pop("summary_schema", None)
+
+    return AgentSchemaResponse(
+        identity=identity,
+        context_config=context_schema,
+        react_config=ReActConfig.model_json_schema(),
+    )
+
+
+@agent_router.get(
+    "/schema/v2",
+    response_model=AgentSchemaV2Response,
+    summary="Full AgentData JSON Schema for the agent form",
+)
+async def get_agent_schema_v2() -> AgentSchemaV2Response:
+    """Return the full :class:`AgentData` JSON Schema.
+
+    Superset of the legacy sectioned endpoint. The response body is a
+    single ``schema`` field carrying the whole Pydantic-generated
+    schema of :class:`AgentData`, with two curated exclusions handled
+    at the model layer (so no post-processing is needed here):
+
+    - ``id``: server-assigned, marked :class:`SkipJsonSchema` on
+      :attr:`AgentData.id`.
+    - ``context_config.summary_schema``: internal structured-output
+      spec for the compression model, dropped below since it is not
+      user-editable and there is no equivalent hook on the Pydantic
+      side.
+
+    ``$ref`` inlining is delegated to
+    :func:`~agentscope._utils._common._flatten_json_schema` so the
+    frontend can render every property from the response body alone.
+
+    The frontend derives its section grouping (identity / context /
+    react / invite) directly from this schema — top-level scalar
+    properties are the "identity" section, and top-level nested-object
+    properties each become their own section. Adding a new
+    user-editable field to :class:`AgentData` is thus enough to have it
+    appear in the create / edit form without a router change.
+
+    Returns:
+        `AgentSchemaV2Response`:
+            ``schema`` = the full :class:`AgentData` JSON Schema.
+    """
+    schema = _flatten_json_schema(AgentData.model_json_schema())
+    # ``summary_schema`` is Pydantic's structured-output spec fed to the
+    # compression model — internal, not user-editable. No pydantic-side
+    # hook covers this deep nested field, so drop it after inlining.
+    context_config = schema.get("properties", {}).get("context_config", {})
+    context_config.get("properties", {}).pop("summary_schema", None)
+    return AgentSchemaV2Response(schema=schema)
+
+
+@agent_router.get(
+    "/",
+    response_model=ListAgentsResponse,
+    summary="List all agents",
+)
+async def list_agents(
+    user_id: str = Depends(get_current_user_id),
+    access: ResourceAccessService = Depends(get_resource_access_service),
+) -> ListAgentsResponse:
+    """Return all agent records visible to the authenticated user.
+
+    Includes the caller's own ``source == "user"`` agents plus any agents
+    shared to them through :class:`ResourceAccessPolicyBase`. Each entry
+    carries an ``editable`` flag indicating whether the caller may
+    PATCH/DELETE it.
+
+    Args:
+        user_id (`str`):
+            Injected authenticated user ID.
+        access (`ResourceAccessService`):
+            Injected resource access service.
+
+    Returns:
+        `ListAgentsResponse`:
+            All visible agent records paired with per-viewer editability.
+    """
+    entries = await access.list_resource(user_id, ResourceKind.AGENT)
+    return ListAgentsResponse(agents=entries, total=len(entries))
+
+
+@agent_router.post(
+    "/",
+    response_model=CreateAgentResponse,
+    status_code=status.HTTP_201_CREATED,
+    summary="Create a new agent",
+)
+async def create_agent(
+    body: CreateAgentRequest,
+    user_id: str = Depends(get_current_user_id),
+    storage: StorageBase = Depends(get_storage),
+) -> CreateAgentResponse:
+    """Create and persist a new agent configuration.
+
+    Args:
+        body (`CreateAgentRequest`):
+            Agent configuration to store.
+        user_id (`str`):
+            Injected authenticated user ID.
+        storage (`StorageBase`):
+            Injected storage backend.
+
+    Returns:
+        `CreateAgentResponse`:
+            The server-assigned agent identifier.
+
+    Raises:
+        `HTTPException`: 422 if the request body passes
+            :class:`CreateAgentRequest` validation but the resulting
+            :class:`AgentData` fails its cross-field invariants (e.g.
+            ``invite_config.invitable=True`` without a non-empty
+            ``invite_description``). Symmetrical with
+            :func:`update_agent`.
+    """
+    try:
+        data = AgentData(
+            name=body.name,
+            system_prompt=body.system_prompt,
+            context_config=body.context_config,
+            react_config=body.react_config,
+            invite_config=body.invite_config,
+        )
+    except ValidationError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            detail=exc.errors(),
+        ) from exc
+    record = AgentRecord(user_id=user_id, data=data)
+    agent_id = await storage.upsert_agent(user_id, record)
+    return CreateAgentResponse(agent_id=agent_id)
+
+
+@agent_router.patch(
+    "/{agent_id}",
+    response_model=AgentView,
+    summary="Update an agent",
+)
+async def update_agent(
+    agent_id: str,
+    body: UpdateAgentRequest,
+    user_id: str = Depends(get_current_user_id),
+    storage: StorageBase = Depends(get_storage),
+    access: ResourceAccessService = Depends(get_resource_access_service),
+) -> AgentView:
+    """Partially update an existing agent configuration.
+
+    Only the fields present in the request body are updated; all other fields
+    keep their current values.
+
+    Args:
+        agent_id (`str`): The agent to update.
+        body (`UpdateAgentRequest`): Fields to update.
+        user_id (`str`): Injected authenticated user ID.
+        storage (`StorageBase`): Injected storage backend.
+        access (`ResourceAccessService`): Injected access service.
+
+    Returns:
+        `AgentView`: The full agent record after the update.
+
+    Raises:
+        `HTTPException`: 404 if the agent is not visible to the caller;
+            403 if visible but only readable.
+    """
+    owner_id, existing = await access.resolve_for_edit(
+        user_id,
+        ResourceKind.AGENT,
+        agent_id,
+    )
+
+    updates = body.model_dump(exclude_none=True)
+    # ``model_copy(update=...)`` skips validators; re-run
+    # ``AgentData.model_validate`` on the merged shape so the
+    # ``invite_config`` sub-model's ``invitable ⇒ non-empty description``
+    # invariant enforced by ``@model_validator(mode="after")`` produces
+    # an HTTP 422 instead of a stored-but-invalid record.
+    try:
+        updated_data = AgentData.model_validate(
+            {**existing.data.model_dump(), **updates},
+        )
+    except ValidationError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            detail=exc.errors(),
+        ) from exc
+    updated_agent = existing.model_copy(
+        update={"data": updated_data, "updated_at": datetime.now()},
+    )
+    await storage.upsert_agent(owner_id, updated_agent)
+    # Only reachable via ``resolve_for_edit``, so the caller has edit
+    # permission by construction.
+    return AgentView.model_validate(
+        {**updated_agent.model_dump(), "editable": True},
+    )
+
+
+@agent_router.delete(
+    "/{agent_id}",
+    status_code=status.HTTP_204_NO_CONTENT,
+    summary="Delete an agent",
+)
+async def delete_agent(
+    agent_id: str,
+    user_id: str = Depends(get_current_user_id),
+    session_service: SessionService = Depends(get_session_service),
+    access: ResourceAccessService = Depends(get_resource_access_service),
+) -> None:
+    """Permanently delete an agent configuration.
+
+    Cascades through every session owned by this agent (and, for team
+    leaders, through every worker session) — cancelling any in-flight
+    chat run, removing storage records, and purging bus state.
+
+    Args:
+        agent_id (`str`): The agent to delete.
+        user_id (`str`): Injected authenticated user ID.
+        session_service (`SessionService`): Injected session service.
+        access (`ResourceAccessService`): Injected access service — used
+            to resolve the owning user and enforce the edit permission
+            when a shared editor deletes the agent.
+
+    Raises:
+        `HTTPException`: 404 if the agent is not visible to the caller;
+            403 if visible but only readable.
+    """
+    owner_id, _ = await access.resolve_for_edit(
+        user_id,
+        ResourceKind.AGENT,
+        agent_id,
+    )
+    deleted = await session_service.delete_agent(owner_id, agent_id)
+    if not deleted:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Agent '{agent_id}' not found.",
+        )
diff --git a/src/agentscope/app/_router/_chat.py b/src/agentscope/app/_router/_chat.py
new file mode 100644
index 0000000..ae76a39
--- /dev/null
+++ b/src/agentscope/app/_router/_chat.py
@@ -0,0 +1,160 @@
+# -*- coding: utf-8 -*-
+"""Chat router — fire-and-forget trigger for chat runs.
+
+The endpoint no longer returns an SSE stream. Instead, it kicks off a
+chat run as a background task and returns immediately. Events produced
+by the run are published to the message bus and delivered to the
+frontend via the long-lived ``GET /sessions/{sid}/stream`` SSE
+connection provided by the session router.
+
+Two trigger paths, deliberately asymmetric:
+
+- **New user message(s)** are spawned directly into the
+  :class:`ChatRunRegistry`. The registry's single-run-per-session rule
+  surfaces as a 409, which is exactly the desired double-submit guard.
+- **HITL results** (``UserConfirmResultEvent`` /
+  ``ExternalExecutionResultEvent``) are *enqueued* onto the shared
+  run-trigger queue and drained by the single
+  :class:`WakeupDispatcher`. Routing the resume through the queue keeps
+  the dispatcher the sole spawn site, so a resume can never collide with
+  the worker's still-finishing parked run (the old 409 race) — the
+  dispatcher serialises them.
+"""
+from fastapi import APIRouter, Depends, HTTPException, status
+
+from ..deps import (
+    get_chat_run_registry,
+    get_chat_service,
+    get_current_user_id,
+    get_message_bus,
+)
+from ._schema import ChatRequest, ChatTriggerResponse
+from .._manager import ChatRunRegistry
+from .._service import (
+    ChatService,
+    SessionProjection,
+    SubagentHitlProjector,
+)
+from ..message_bus import MessageBus, MessageBusKeys
+from .._bus_ops import enqueue_run_trigger
+from ...event import UserConfirmResultEvent, ExternalExecutionResultEvent
+
+chat_router = APIRouter(
+    prefix="/chat",
+    tags=["chat"],
+    responses={404: {"description": "Not found"}},
+)
+
+
+@chat_router.post(
+    "/",
+    response_model=ChatTriggerResponse,
+    summary="Trigger a chat run (fire-and-forget)",
+)
+async def chat(
+    request: ChatRequest,
+    user_id: str = Depends(get_current_user_id),
+    chat_service: ChatService = Depends(get_chat_service),
+    chat_run_registry: ChatRunRegistry = Depends(get_chat_run_registry),
+    message_bus: MessageBus = Depends(get_message_bus),
+) -> ChatTriggerResponse:
+    """Trigger a chat run for the specified session.
+
+    Events produced during the run are published to the message bus and
+    delivered to any active ``GET /sessions/{session_id}/stream`` SSE
+    subscriber. The caller does **not** receive events from this
+    endpoint's response body.
+
+    Accepts the same ``input`` payloads as before:
+
+    - ``Msg`` / ``list[Msg]``: new user message(s) — spawned directly.
+    - ``UserConfirmResultEvent`` / ``ExternalExecutionResultEvent``:
+      resume a paused tool call (human-in-the-loop) — routed to the
+      owning session and enqueued for the dispatcher.
+    - ``None``: continue from current state — spawned directly.
+
+    Args:
+        request (`ChatRequest`):
+            JSON body with ``agent_id``, ``session_id``, and ``input``.
+        user_id (`str`):
+            Injected user id.
+        chat_service (`ChatService`):
+            Injected application-wide chat service.
+        chat_run_registry (`ChatRunRegistry`):
+            Injected per-process chat-run registry.
+        message_bus (`MessageBus`):
+            Injected message bus, used to resolve subagent-confirm
+            routing and to enqueue resume triggers.
+
+    Returns:
+        `ChatTriggerResponse`:
+            Confirms the run was scheduled (for a resume, that it was
+            enqueued).
+
+    Raises:
+        `HTTPException`:
+            409 if a chat run for this session is already in flight in
+            this process (the registry enforces single-run-per-session).
+            Only direct-spawn paths (new messages / ``None``) can raise
+            this; the enqueued resume path never does.
+    """
+    # ------------------------------------------------------------------
+    # HITL resume — route to the owning session, then enqueue.
+    #
+    # A confirmation / external-result POSTed to a *leader* session may
+    # actually belong to a team *member*: the leader is the single front
+    # door clients talk to. Resolve the owning worker HERE, then enqueue
+    # a ``resume`` trigger for that session. The single WakeupDispatcher
+    # drains it — spawning under the *worker* session id, serialised
+    # behind any still-finishing parked run, so there is no registry
+    # collision (no 409) and the leader's run slot is never occupied by
+    # the worker's resume.
+    # ------------------------------------------------------------------
+    if isinstance(
+        request.input,
+        (UserConfirmResultEvent, ExternalExecutionResultEvent),
+    ):
+        run_session_id = request.session_id
+        run_agent_id = request.agent_id
+        target = await SubagentHitlProjector.resolve(
+            SessionProjection(message_bus),
+            request.session_id,
+            request.input.reply_id,
+        )
+        if target is not None:
+            run_session_id = target["worker_session_id"]
+            run_agent_id = target["worker_agent_id"]
+
+        await enqueue_run_trigger(
+            message_bus,
+            user_id=user_id,
+            session_id=run_session_id,
+            agent_id=run_agent_id,
+            kind=MessageBusKeys.WAKEUP_KIND_RESUME,
+            inputs=request.input,
+        )
+        return ChatTriggerResponse(status="started", session_id=run_session_id)
+
+    # ------------------------------------------------------------------
+    # New user message(s) / None — spawn directly. The registry's
+    # single-run-per-session rule is the desired double-submit guard.
+    # ------------------------------------------------------------------
+    try:
+        chat_run_registry.spawn(
+            chat_service.run(
+                user_id=user_id,
+                session_id=request.session_id,
+                agent_id=request.agent_id,
+                input_msg=request.input,
+            ),
+            session_id=request.session_id,
+        )
+    except RuntimeError as e:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=str(e),
+        ) from e
+    return ChatTriggerResponse(
+        status="started",
+        session_id=request.session_id,
+    )
diff --git a/src/agentscope/app/_router/_credential.py b/src/agentscope/app/_router/_credential.py
new file mode 100644
index 0000000..598d735
--- /dev/null
+++ b/src/agentscope/app/_router/_credential.py
@@ -0,0 +1,195 @@
+# -*- coding: utf-8 -*-
+"""Credential router — CRUD endpoints for API key credentials."""
+from fastapi import APIRouter, Depends, status
+
+from ..access import ResourceKind
+from ..deps import (
+    get_current_user_id,
+    get_resource_access_service,
+    get_storage,
+)
+from ._schema import (
+    CreateCredentialRequest,
+    CreateCredentialResponse,
+    ListCredentialsResponse,
+    ListCredentialSchemasResponse,
+    UpdateCredentialRequest,
+)
+from .._service import CredentialView, ResourceAccessService
+from ..storage import StorageBase
+from ...credential import CredentialFactory
+
+credential_router = APIRouter(
+    prefix="/credential",
+    tags=["credential"],
+    responses={404: {"description": "Not found"}},
+)
+
+
+@credential_router.get(
+    "/schemas",
+    response_model=ListCredentialSchemasResponse,
+    summary="List JSON schemas for all credential types",
+)
+async def list_credential_schemas() -> ListCredentialSchemasResponse:
+    """Return JSON schemas for all registered credential types.
+
+    Used by the frontend to render credential creation forms dynamically.
+    """
+
+    return ListCredentialSchemasResponse(
+        schemas=CredentialFactory.list_schemas(),
+    )
+
+
+@credential_router.get(
+    "/",
+    response_model=ListCredentialsResponse,
+    summary="List all credentials",
+)
+async def list_credentials(
+    user_id: str = Depends(get_current_user_id),
+    access: ResourceAccessService = Depends(get_resource_access_service),
+) -> ListCredentialsResponse:
+    """Return all credential records visible to the authenticated user.
+
+    Includes the caller's own credentials plus any credentials shared to
+    them through :class:`ResourceAccessPolicyBase`. Shared entries have
+    their secret ``data`` payload masked — only the discriminator and
+    display name survive in the response — while runtime resolution
+    (e.g. the chat model service) still sees the full payload.
+
+    Args:
+        user_id (`str`):
+            Injected authenticated user ID.
+        access (`ResourceAccessService`):
+            Injected resource access service.
+
+    Returns:
+        `ListCredentialsResponse`:
+            All visible credentials paired with editability and
+            (for shared entries) redacted data.
+    """
+    entries = await access.list_resource(user_id, ResourceKind.CREDENTIAL)
+    return ListCredentialsResponse(
+        credentials=entries,
+        total=len(entries),
+    )
+
+
+@credential_router.post(
+    "/",
+    response_model=CreateCredentialResponse,
+    status_code=status.HTTP_201_CREATED,
+    summary="Create a new credential",
+)
+async def create_credential(
+    body: CreateCredentialRequest,
+    user_id: str = Depends(get_current_user_id),
+    storage: StorageBase = Depends(get_storage),
+) -> CreateCredentialResponse:
+    """Store a new credential.
+
+    Args:
+        body (`CreateCredentialRequest`): Credential payload to store.
+        user_id (`str`): Injected authenticated user ID.
+        storage (`StorageBase`): Injected storage backend.
+
+    Returns:
+        `CreateCredentialResponse`: The server-assigned credential identifier.
+    """
+    credential_id = await storage.upsert_credential(
+        user_id,
+        CredentialFactory.from_dict(body.data),
+    )
+    return CreateCredentialResponse(credential_id=credential_id)
+
+
+@credential_router.patch(
+    "/{credential_id}",
+    response_model=CredentialView,
+    summary="Update a credential",
+)
+async def update_credential(
+    credential_id: str,
+    body: UpdateCredentialRequest,
+    user_id: str = Depends(get_current_user_id),
+    storage: StorageBase = Depends(get_storage),
+    access: ResourceAccessService = Depends(get_resource_access_service),
+) -> CredentialView:
+    """Replace the payload of an existing credential.
+
+    Args:
+        credential_id (`str`): The credential to update.
+        body (`UpdateCredentialRequest`): New credential payload.
+        user_id (`str`): Injected authenticated user ID.
+        storage (`StorageBase`): Injected storage backend.
+        access (`ResourceAccessService`): Injected access service — used
+            to resolve the owning user and enforce the edit permission
+            when a shared editor updates the credential.
+
+    Returns:
+        `CredentialView`: The updated credential record.
+
+    Raises:
+        `HTTPException`: 404 if the credential is not visible to the
+            caller; 403 if visible but only readable.
+    """
+    owner_id, _ = await access.resolve_for_edit(
+        user_id,
+        ResourceKind.CREDENTIAL,
+        credential_id,
+    )
+
+    credential = CredentialFactory.from_dict(body.data)
+    credential.id = credential_id
+    await storage.upsert_credential(owner_id, credential)
+    # ``resolve_for_edit`` proved the record existed under ``owner_id``
+    # and the upsert above just wrote back to the same key, so the read
+    # is a value refresh, not an existence check. If it still comes back
+    # empty (e.g. a concurrent delete), surface an explicit server error
+    # rather than relying on ``assert`` (which ``-O`` strips).
+    updated = await storage.get_credential(owner_id, credential_id)
+    if updated is None:
+        raise RuntimeError(
+            f"Credential {credential_id!r} for owner {owner_id!r} "
+            "disappeared immediately after a successful upsert.",
+        )
+    # Only reachable via ``resolve_for_edit``, so the caller has edit
+    # permission by construction.
+    return CredentialView.model_validate(
+        {**updated.model_dump(), "editable": True},
+    )
+
+
+@credential_router.delete(
+    "/{credential_id}",
+    status_code=status.HTTP_204_NO_CONTENT,
+    summary="Delete a credential",
+)
+async def delete_credential(
+    credential_id: str,
+    user_id: str = Depends(get_current_user_id),
+    storage: StorageBase = Depends(get_storage),
+    access: ResourceAccessService = Depends(get_resource_access_service),
+) -> None:
+    """Permanently delete a credential.
+
+    Args:
+        credential_id (`str`): The credential to delete.
+        user_id (`str`): Injected authenticated user ID.
+        storage (`StorageBase`): Injected storage backend.
+        access (`ResourceAccessService`): Injected access service — used
+            to resolve the owning user and enforce the edit permission
+            when a shared editor deletes the credential.
+
+    Raises:
+        `HTTPException`: 404 if the credential is not visible to the
+            caller; 403 if visible but only readable.
+    """
+    owner_id, _ = await access.resolve_for_edit(
+        user_id,
+        ResourceKind.CREDENTIAL,
+        credential_id,
+    )
+    await storage.delete_credential(owner_id, credential_id)
diff --git a/src/agentscope/app/_router/_knowledge_base.py b/src/agentscope/app/_router/_knowledge_base.py
new file mode 100644
index 0000000..901acc4
--- /dev/null
+++ b/src/agentscope/app/_router/_knowledge_base.py
@@ -0,0 +1,575 @@
+# -*- coding: utf-8 -*-
+"""Knowledge base router — manage knowledge bases and their documents.
+
+A knowledge base is the user-facing concept; physically each one maps
+to a single vector store collection (in the MVP isolation strategy).
+The HTTP layer is intentionally thin — every endpoint translates the
+request into a single :class:`~agentscope.app._service.
+KnowledgeBaseService` call and returns the result.
+"""
+from fastapi import (
+    APIRouter,
+    Depends,
+    File,
+    Form,
+    Path,
+    Query,
+    UploadFile,
+    status,
+)
+
+from ..access import ResourceKind
+from ..deps import (
+    get_current_user_id,
+    get_knowledge_base_manager,
+    get_knowledge_base_service,
+    get_knowledge_parsers,
+    get_resource_access_service,
+)
+from ._schema import (
+    CreateKnowledgeBaseRequest,
+    CreateKnowledgeBaseResponse,
+    KbEmbeddingProvider,
+    KbMiddlewareParametersSchemaResponse,
+    KnowledgeDocumentView,
+    ListKbEmbeddingModelsResponse,
+    ListKnowledgeBasesResponse,
+    ListKnowledgeDocumentsResponse,
+    ListKnowledgeDocumentStatusResponse,
+    ListSupportedContentTypesResponse,
+    SearchKnowledgeBaseRequest,
+    SearchKnowledgeBaseResponse,
+    UpdateKnowledgeBaseRequest,
+    UploadKnowledgeDocumentResponse,
+)
+from ...credential import CredentialFactory
+from ..rag.knowledge_base_manager import KnowledgeBaseManagerBase
+from .._service import (
+    KnowledgeBaseService,
+    KnowledgeBaseView,
+    ResourceAccessService,
+)
+from ...middleware import RAGMiddleware
+from ...rag import ParserBase
+
+
+knowledge_base_router = APIRouter(
+    prefix="/knowledge_bases",
+    tags=["knowledge_bases"],
+    responses={404: {"description": "Not found"}},
+)
+
+
+@knowledge_base_router.get(
+    "/embedding_models",
+    response_model=ListKbEmbeddingModelsResponse,
+    summary="List embedding models compatible with the KB dimension policy",
+)
+async def list_kb_embedding_models(
+    user_id: str = Depends(get_current_user_id),
+    access: "ResourceAccessService" = Depends(get_resource_access_service),
+    manager: "KnowledgeBaseManagerBase" = Depends(
+        get_knowledge_base_manager,
+    ),
+) -> ListKbEmbeddingModelsResponse:
+    """List embedding models the user can pick at KB-creation time.
+
+    Walks every credential visible to the caller (own + shared via the
+    resource access policy), looks up each provider's embedding model
+    class, gathers its model cards, and projects each card through the
+    manager's :class:`DimensionPolicy`. Incompatible cards are
+    dropped; matryoshka cards under a ``FIXED`` /
+    ``LOCKED_BY_EXISTING`` policy are narrowed to the locked
+    dimension.  Providers that end up with zero compatible models are
+    omitted from the response entirely.
+
+    Args:
+        user_id (`str`):
+            Injected authenticated user ID.
+        access (`ResourceAccessService`):
+            Injected resource access service; enumerates visible
+            credentials (own + shared) so KB creation works against
+            shared credentials too.
+        manager (`KnowledgeBaseManagerBase`):
+            Injected knowledge base manager.
+
+    Returns:
+        `ListKbEmbeddingModelsResponse`:
+            One entry per credential with at least one compatible
+            embedding model, plus the policy used for filtering.
+    """
+    policy = await manager.get_dimension_policy()
+    credentials = await access.list_resource(user_id, ResourceKind.CREDENTIAL)
+
+    providers: list[KbEmbeddingProvider] = []
+    for credential in credentials:
+        credential_type = credential.data.get("type")
+        if not credential_type:
+            continue
+        credential_cls = CredentialFactory.get_credential_class(
+            credential_type,
+        )
+        if credential_cls is None:
+            continue
+        embedding_cls = credential_cls.get_embedding_model_class()
+        if embedding_cls is None:
+            continue
+
+        filtered = []
+        for card in embedding_cls.list_models():
+            projected = policy.filter_card(card)
+            if projected is not None:
+                filtered.append(projected)
+        if not filtered:
+            continue
+        providers.append(
+            KbEmbeddingProvider(credential=credential, models=filtered),
+        )
+
+    return ListKbEmbeddingModelsResponse(providers=providers, policy=policy)
+
+
+@knowledge_base_router.get(
+    "/middleware/parameters_schema",
+    response_model=KbMiddlewareParametersSchemaResponse,
+    summary="JSON Schema for the KB middleware's tunable parameters",
+)
+async def get_kb_middleware_parameters_schema(
+    _: str = Depends(get_current_user_id),
+) -> KbMiddlewareParametersSchemaResponse:
+    """Return the parameter schema for
+    :class:`agentscope.middleware.RAGMiddleware`.
+
+    The schema is shaped like every other ``parameter_schema`` served
+    by this service — title / description / default / enum / minimum
+    / maximum — so the front-end can render the session-level KB
+    attachment form with the same schema-driven component used for
+    model parameters.
+
+    Args:
+        _ (`str`):
+            Injected authenticated user ID; only used to gate the
+            endpoint behind authentication.
+
+    Returns:
+        `KbMiddlewareParametersSchemaResponse`:
+            The JSON Schema describing the middleware's
+            user-tunable parameters.
+    """
+    return KbMiddlewareParametersSchemaResponse(
+        parameter_schema=(RAGMiddleware.Parameters.model_json_schema()),
+    )
+
+
+@knowledge_base_router.get(
+    "/supported_content_types",
+    response_model=ListSupportedContentTypesResponse,
+    summary="List file types the configured parsers can ingest",
+)
+async def list_supported_content_types(
+    _: str = Depends(get_current_user_id),
+    parsers: list[ParserBase]
+    | dict[str, ParserBase] = Depends(
+        get_knowledge_parsers,
+    ),
+) -> ListSupportedContentTypesResponse:
+    """Advertise the union of media types and filename extensions every
+    registered parser accepts.
+
+    Used by the front-end to populate the document picker's ``accept``
+    attribute and to reject drag-dropped files whose extension lies
+    outside the supported set before the upload starts.  Routing on
+    upload still goes through the media type — this endpoint is a
+    capability hint, not authoritative dispatch.
+
+    Args:
+        _ (`str`):
+            Injected authenticated user ID; only used to gate the
+            endpoint behind authentication.
+        parsers (`list[ParserBase] | dict[str, ParserBase]`):
+            Injected parser registry — the same value the index worker
+            uses to dispatch uploads.
+
+    Returns:
+        `ListSupportedContentTypesResponse`:
+            Deduplicated, sorted unions of ``media_types`` and
+            ``extensions``.
+    """
+    parser_iter = parsers.values() if isinstance(parsers, dict) else parsers
+    media_types: set[str] = set()
+    extensions: set[str] = set()
+    for parser in parser_iter:
+        media_types.update(parser.supported_media_types)
+        extensions.update(parser.supported_extensions())
+    return ListSupportedContentTypesResponse(
+        media_types=sorted(media_types),
+        extensions=sorted(extensions),
+    )
+
+
+# ----------------------------------------------------------------------
+# Knowledge base management
+# ----------------------------------------------------------------------
+
+
+@knowledge_base_router.post(
+    "/",
+    response_model=CreateKnowledgeBaseResponse,
+    status_code=status.HTTP_201_CREATED,
+    summary="Create a new knowledge base",
+)
+async def create_knowledge_base(
+    body: CreateKnowledgeBaseRequest,
+    user_id: str = Depends(get_current_user_id),
+    service: "KnowledgeBaseService" = Depends(get_knowledge_base_service),
+) -> CreateKnowledgeBaseResponse:
+    """Create a new knowledge base for the authenticated user.
+
+    Allocates a fresh vector store collection sized to the embedding
+    model's output dimension and persists the knowledge base record.
+
+    Args:
+        body (`CreateKnowledgeBaseRequest`):
+            Knowledge base name, description, and embedding model
+            configuration.
+        user_id (`str`):
+            Injected authenticated user ID.
+        service (`KnowledgeBaseService`):
+            Injected knowledge base service.
+
+    Returns:
+        `CreateKnowledgeBaseResponse`:
+            The server-assigned knowledge base identifier.
+    """
+    record = await service.create_knowledge_base(
+        user_id=user_id,
+        name=body.name,
+        description=body.description,
+        embedding_model_config=body.embedding_model_config,
+    )
+    return CreateKnowledgeBaseResponse(knowledge_base_id=record.id)
+
+
+@knowledge_base_router.get(
+    "/",
+    response_model=ListKnowledgeBasesResponse,
+    summary="List the caller's knowledge bases",
+)
+async def list_knowledge_bases(
+    user_id: str = Depends(get_current_user_id),
+    access: "ResourceAccessService" = Depends(get_resource_access_service),
+) -> ListKnowledgeBasesResponse:
+    """Return all knowledge bases visible to the authenticated user.
+
+    Includes the caller's own knowledge bases plus any shared to them
+    through :class:`ResourceAccessPolicyBase`. Each entry carries an
+    ``editable`` flag: ``read`` grants search + attach; ``edit`` also
+    grants document add/delete and metadata update.
+
+    Args:
+        user_id (`str`):
+            Injected authenticated user ID.
+        access (`ResourceAccessService`):
+            Injected resource access service.
+
+    Returns:
+        `ListKnowledgeBasesResponse`:
+            All visible knowledge bases paired with per-viewer
+            editability.
+    """
+    entries = await access.list_resource(user_id, ResourceKind.KNOWLEDGE_BASE)
+    return ListKnowledgeBasesResponse(
+        knowledge_bases=entries,
+        total=len(entries),
+    )
+
+
+@knowledge_base_router.patch(
+    "/{knowledge_base_id}",
+    response_model=KnowledgeBaseView,
+    summary="Update mutable fields on a knowledge base",
+)
+async def update_knowledge_base(
+    body: UpdateKnowledgeBaseRequest,
+    knowledge_base_id: str = Path(description="The knowledge base id."),
+    user_id: str = Depends(get_current_user_id),
+    service: "KnowledgeBaseService" = Depends(get_knowledge_base_service),
+) -> KnowledgeBaseView:
+    """Update mutable fields on a knowledge base.
+
+    Only ``name`` and ``description`` can be updated.  The embedding
+    model configuration is pinned at creation time and cannot be
+    changed.
+
+    Args:
+        body (`UpdateKnowledgeBaseRequest`):
+            The fields to update; omitted fields stay unchanged.
+        knowledge_base_id (`str`):
+            The knowledge base to update.
+        user_id (`str`):
+            Injected authenticated user ID.
+        service (`KnowledgeBaseService`):
+            Injected knowledge base service.
+
+    Returns:
+        `KnowledgeBaseView`:
+            The knowledge base record after the update.
+    """
+    record = await service.update_knowledge_base(
+        user_id=user_id,
+        knowledge_base_id=knowledge_base_id,
+        name=body.name,
+        description=body.description,
+    )
+    # Only reachable via ``_require_edit`` inside the service, so the
+    # caller definitionally has edit permission.
+    return KnowledgeBaseView.model_validate(
+        {**record.model_dump(), "editable": True},
+    )
+
+
+@knowledge_base_router.delete(
+    "/{knowledge_base_id}",
+    status_code=status.HTTP_204_NO_CONTENT,
+    summary="Delete a knowledge base",
+)
+async def delete_knowledge_base(
+    knowledge_base_id: str = Path(description="The knowledge base id."),
+    user_id: str = Depends(get_current_user_id),
+    service: "KnowledgeBaseService" = Depends(get_knowledge_base_service),
+) -> None:
+    """Permanently delete a knowledge base.
+
+    Drops the underlying vector store collection together with every
+    associated document and the knowledge base record itself.
+
+    Args:
+        knowledge_base_id (`str`):
+            The knowledge base to delete.
+        user_id (`str`):
+            Injected authenticated user ID.
+        service (`KnowledgeBaseService`):
+            Injected knowledge base service.
+    """
+    await service.delete_knowledge_base(user_id, knowledge_base_id)
+
+
+# ----------------------------------------------------------------------
+# Document management
+# ----------------------------------------------------------------------
+
+
+@knowledge_base_router.get(
+    "/{knowledge_base_id}/documents",
+    response_model=ListKnowledgeDocumentsResponse,
+    summary="List documents registered in a knowledge base",
+)
+async def list_knowledge_documents(
+    knowledge_base_id: str = Path(description="The knowledge base id."),
+    user_id: str = Depends(get_current_user_id),
+    service: "KnowledgeBaseService" = Depends(get_knowledge_base_service),
+) -> ListKnowledgeDocumentsResponse:
+    """List every document registered against a knowledge base.
+
+    Reads from the storage backend (service-mode source of truth), so
+    documents in any lifecycle state — including ``pending`` /
+    ``parsing`` / ``error`` — are returned alongside ``ready`` ones.
+
+    Args:
+        knowledge_base_id (`str`):
+            The target knowledge base id.
+        user_id (`str`):
+            Injected authenticated user ID.
+        service (`KnowledgeBaseService`):
+            Injected knowledge base service.
+
+    Returns:
+        `ListKnowledgeDocumentsResponse`:
+            One view per registered document.
+    """
+    records = await service.list_documents(user_id, knowledge_base_id)
+    views = [KnowledgeDocumentView.from_record(r) for r in records]
+    return ListKnowledgeDocumentsResponse(
+        documents=views,
+        total=len(views),
+    )
+
+
+@knowledge_base_router.get(
+    "/{knowledge_base_id}/documents/status",
+    response_model=ListKnowledgeDocumentStatusResponse,
+    summary="Batch-query indexing status of one or more documents",
+)
+async def list_knowledge_document_status(
+    knowledge_base_id: str = Path(description="The knowledge base id."),
+    ids: str = Query(
+        description=(
+            "Comma-separated list of document ids to query. "
+            "Missing ids are silently omitted from the response."
+        ),
+    ),
+    user_id: str = Depends(get_current_user_id),
+    service: "KnowledgeBaseService" = Depends(get_knowledge_base_service),
+) -> ListKnowledgeDocumentStatusResponse:
+    """Return the current lifecycle state of a batch of documents.
+
+    Designed for the front-end's status polling loop: the page sends
+    every in-flight document id at once so per-document round-trips
+    do not multiply with concurrency.
+
+    Args:
+        knowledge_base_id (`str`):
+            The target knowledge base id.
+        ids (`str`):
+            Comma-separated document ids.
+        user_id (`str`):
+            Injected authenticated user ID.
+        service (`KnowledgeBaseService`):
+            Injected knowledge base service.
+
+    Returns:
+        `ListKnowledgeDocumentStatusResponse`:
+            Views for the matched documents.
+    """
+    document_ids = [tok for tok in (s.strip() for s in ids.split(",")) if tok]
+    records = await service.get_document_status(
+        user_id,
+        knowledge_base_id,
+        document_ids,
+    )
+    return ListKnowledgeDocumentStatusResponse(
+        items=[KnowledgeDocumentView.from_record(r) for r in records],
+    )
+
+
+@knowledge_base_router.post(
+    "/{knowledge_base_id}/documents",
+    response_model=UploadKnowledgeDocumentResponse,
+    status_code=status.HTTP_201_CREATED,
+    summary="Upload a document into a knowledge base",
+)
+async def upload_knowledge_document(
+    knowledge_base_id: str = Path(description="The knowledge base id."),
+    file: UploadFile = File(
+        description="The document to index (PDF, TXT, Markdown, …).",
+    ),
+    content_type: str
+    | None = Form(
+        default=None,
+        description=(
+            "Override the IANA media type used to route the upload. "
+            "Defaults to the type guessed from the filename."
+        ),
+    ),
+    user_id: str = Depends(get_current_user_id),
+    service: "KnowledgeBaseService" = Depends(get_knowledge_base_service),
+) -> UploadKnowledgeDocumentResponse:
+    """Register an uploaded document and dispatch it for indexing.
+
+    The HTTP connection covers only the upload phase: the request body
+    is streamed into the blob store, a ``pending`` document record is
+    persisted, the indexing task is dispatched, and the response is
+    returned.  Parsing / chunking / embedding happen asynchronously in
+    a worker; the client tracks progress via
+    :func:`list_knowledge_document_status`.
+
+    Args:
+        knowledge_base_id (`str`):
+            The knowledge base to receive the document.
+        file (`UploadFile`):
+            The uploaded file (multipart/form-data).
+        content_type (`str | None`, optional):
+            Override the IANA media type used to route the upload.
+        user_id (`str`):
+            Injected authenticated user ID.
+        service (`KnowledgeBaseService`):
+            Injected knowledge base service.
+
+    Returns:
+        `UploadKnowledgeDocumentResponse`:
+            The server-assigned document id, filename, and the
+            initial lifecycle state (always ``"pending"``).
+    """
+    record = await service.register_document(
+        user_id=user_id,
+        knowledge_base_id=knowledge_base_id,
+        filename=file.filename or "uploaded_file",
+        stream=file.file,
+        size=file.size or 0,
+        content_type=content_type or file.content_type,
+    )
+    return UploadKnowledgeDocumentResponse(
+        document_id=record.id,
+        filename=record.data.filename,
+        status=record.data.status,
+    )
+
+
+@knowledge_base_router.delete(
+    "/{knowledge_base_id}/documents/{document_id}",
+    status_code=status.HTTP_204_NO_CONTENT,
+    summary="Delete a document from a knowledge base",
+)
+async def delete_knowledge_document(
+    knowledge_base_id: str = Path(description="The knowledge base id."),
+    document_id: str = Path(description="The document id."),
+    user_id: str = Depends(get_current_user_id),
+    service: "KnowledgeBaseService" = Depends(get_knowledge_base_service),
+) -> None:
+    """Remove a document and all its chunks from a knowledge base.
+
+    Args:
+        knowledge_base_id (`str`):
+            The knowledge base the document belongs to.
+        document_id (`str`):
+            The document to delete.
+        user_id (`str`):
+            Injected authenticated user ID.
+        service (`KnowledgeBaseService`):
+            Injected knowledge base service.
+    """
+    await service.delete_document(user_id, knowledge_base_id, document_id)
+
+
+# ----------------------------------------------------------------------
+# Search
+# ----------------------------------------------------------------------
+
+
+@knowledge_base_router.post(
+    "/{knowledge_base_id}/search",
+    response_model=SearchKnowledgeBaseResponse,
+    summary="Search a knowledge base by natural-language query",
+)
+async def search_knowledge_base(
+    body: SearchKnowledgeBaseRequest,
+    knowledge_base_id: str = Path(description="The knowledge base id."),
+    user_id: str = Depends(get_current_user_id),
+    service: "KnowledgeBaseService" = Depends(get_knowledge_base_service),
+) -> SearchKnowledgeBaseResponse:
+    """Run a similarity search over a knowledge base.
+
+    Embeds the query with the knowledge base's configured embedding
+    model and returns the top-K most similar chunks.
+
+    Args:
+        body (`SearchKnowledgeBaseRequest`):
+            The query text and ``top_k``.
+        knowledge_base_id (`str`):
+            The knowledge base to search.
+        user_id (`str`):
+            Injected authenticated user ID.
+        service (`KnowledgeBaseService`):
+            Injected knowledge base service.
+
+    Returns:
+        `SearchKnowledgeBaseResponse`:
+            Matched chunks ordered by descending similarity.
+    """
+    results = await service.search(
+        user_id=user_id,
+        knowledge_base_id=knowledge_base_id,
+        query=body.query,
+        top_k=body.top_k,
+    )
+    return SearchKnowledgeBaseResponse(results=results, total=len(results))
diff --git a/src/agentscope/app/_router/_model.py b/src/agentscope/app/_router/_model.py
new file mode 100644
index 0000000..b429431
--- /dev/null
+++ b/src/agentscope/app/_router/_model.py
@@ -0,0 +1,40 @@
+# -*- coding: utf-8 -*-
+"""The model router."""
+
+from fastapi import APIRouter, Depends, HTTPException, status
+
+from ._schema import ListModelsResponse, ListModelsRequest
+from ...credential import CredentialFactory
+
+model_router = APIRouter(
+    prefix="/model",
+    tags=["model"],
+    responses={404: {"description": "Not found"}},
+)
+
+
+@model_router.get(
+    "/",
+    response_model=ListModelsResponse,
+    summary="List all candidate models under the given credential type",
+)
+async def list_models(
+    body: ListModelsRequest = Depends(),
+) -> ListModelsResponse:
+    """Return all candidate models under the given credential type.
+
+    Args:
+        body (ListModelsRequest): The request body.
+
+    Returns:
+        `ListModelsResponse`: The response body.
+    """
+    credential_cls = CredentialFactory.get_credential_class(body.provider)
+    if credential_cls is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Provider '{body.provider}' not found.",
+        )
+
+    models = credential_cls.get_chat_model_class().list_models()
+    return ListModelsResponse(models=models, total=len(models))
diff --git a/src/agentscope/app/_router/_schedule.py b/src/agentscope/app/_router/_schedule.py
new file mode 100644
index 0000000..aab4a81
--- /dev/null
+++ b/src/agentscope/app/_router/_schedule.py
@@ -0,0 +1,253 @@
+# -*- coding: utf-8 -*-
+"""Schedule router — CRUD endpoints for scheduled agent tasks."""
+from datetime import datetime
+
+from fastapi import APIRouter, Depends, HTTPException, status
+
+from ..access import ResourceKind
+from .._manager import SchedulerManager
+from ..deps import (
+    get_current_user_id,
+    get_resource_access_service,
+    get_scheduler_manager,
+    get_session_service,
+    get_storage,
+)
+from ._schema import (
+    CreateScheduleRequest,
+    CreateScheduleResponse,
+    ListSchedulesResponse,
+    ScheduleSessionsResponse,
+    UpdateScheduleRequest,
+)
+from .._service import ResourceAccessService, SessionService
+from ..storage import (
+    StorageBase,
+    ScheduleData,
+    ScheduleRecord,
+    ScheduleSource,
+)
+
+schedule_router = APIRouter(
+    prefix="/schedule",
+    tags=["schedule"],
+    responses={404: {"description": "Not found"}},
+)
+
+
+@schedule_router.get(
+    "/",
+    response_model=ListSchedulesResponse,
+    summary="List all schedules",
+)
+async def list_schedules(
+    user_id: str = Depends(get_current_user_id),
+    storage: StorageBase = Depends(get_storage),
+) -> ListSchedulesResponse:
+    """List all schedules owned by the current user.
+
+    Args:
+        user_id (`str`): Authenticated user ID.
+        storage (`StorageBase`): Storage instance.
+
+    Returns:
+        `ListSchedulesResponse`:
+            Paginated list of schedule records.
+    """
+    schedules = await storage.list_schedules(user_id)
+    return ListSchedulesResponse(schedules=schedules, total=len(schedules))
+
+
+@schedule_router.post(
+    "/",
+    response_model=CreateScheduleResponse,
+    status_code=status.HTTP_201_CREATED,
+    summary="Create a new schedule",
+)
+async def create_schedule(
+    body: CreateScheduleRequest,
+    user_id: str = Depends(get_current_user_id),
+    storage: StorageBase = Depends(get_storage),
+    access: ResourceAccessService = Depends(get_resource_access_service),
+    scheduler: SchedulerManager = Depends(get_scheduler_manager),
+) -> CreateScheduleResponse:
+    """Create a new schedule and register it with the scheduler.
+
+    The referenced agent may be either the viewer's own or one shared
+    to them through :class:`ResourceAccessPolicyBase`; the schedule
+    record itself is always owned by the caller.
+
+    Args:
+        body (`CreateScheduleRequest`): Schedule configuration.
+        user_id (`str`): Authenticated user ID.
+        storage (`StorageBase`): Storage instance.
+        access (`ResourceAccessService`): Access service.
+        scheduler (`SchedulerManager`): Scheduler manager.
+
+    Returns:
+        `CreateScheduleResponse`:
+            The ID of the newly created schedule.
+
+    Raises:
+        `HTTPException`: 404 if the specified agent or the credential
+            referenced by ``chat_model_config`` is not visible to the
+            caller.
+    """
+    # Visibility checks — raise 404 when neither owned nor shared. The
+    # schedule fires under the owner's user_id, so re-validating the
+    # credential here surfaces the error at creation time rather than
+    # silently at the first (possibly much later) scheduled run.
+    await access.resolve_agent(user_id, body.agent_id)
+    await access.get_resource(
+        user_id,
+        ResourceKind.CREDENTIAL,
+        body.chat_model_config.credential_id,
+    )
+
+    record = ScheduleRecord(
+        user_id=user_id,
+        agent_id=body.agent_id,
+        data=ScheduleData(
+            name=body.name,
+            description=body.description,
+            cron_expression=body.cron_expression,
+            timezone=body.timezone,
+            enabled=body.enabled,
+            stateful=body.stateful,
+            permission_mode=body.permission_mode,
+            chat_model_config=body.chat_model_config,
+            source=ScheduleSource.USER,
+            started_at=datetime.now(),
+        ),
+    )
+    await storage.upsert_schedule(user_id, record)
+
+    if record.data.enabled:
+        await scheduler.register_schedule(record)
+
+    return CreateScheduleResponse(schedule_id=record.id)
+
+
+@schedule_router.patch(
+    "/{schedule_id}",
+    response_model=ScheduleRecord,
+    summary="Update a schedule",
+)
+async def update_schedule(
+    schedule_id: str,
+    body: UpdateScheduleRequest,
+    user_id: str = Depends(get_current_user_id),
+    storage: StorageBase = Depends(get_storage),
+    scheduler: SchedulerManager = Depends(get_scheduler_manager),
+) -> ScheduleRecord:
+    """Partially update a schedule.
+
+    Fields omitted from the request body keep their current values.
+    Changing ``cron_expression`` or ``timezone`` immediately reschedules the
+    APScheduler job.  Setting ``enable=False`` removes the job from the
+    scheduler without deleting the record.
+
+    Args:
+        schedule_id (`str`): ID of the schedule to update.
+        body (`UpdateScheduleRequest`): Fields to update.
+        user_id (`str`): Authenticated user ID.
+        storage (`StorageBase`): Storage instance.
+        scheduler (`SchedulerManager`): Scheduler manager.
+
+    Returns:
+        `ScheduleRecord`:
+            The updated schedule record.
+
+    Raises:
+        `HTTPException`: 404 if the schedule does not exist.
+    """
+    existing = await storage.get_schedule(user_id, schedule_id)
+    if existing is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Schedule '{schedule_id}' not found.",
+        )
+
+    updates = body.model_dump(exclude_none=True)
+    updated_data = existing.data.model_copy(update=updates)
+    updated_record = existing.model_copy(
+        update={"data": updated_data, "updated_at": datetime.now()},
+    )
+    await storage.upsert_schedule(user_id, updated_record)
+
+    # Always remove the existing job first; re-register only if still enabled.
+    await scheduler.remove_schedule(schedule_id)
+    if updated_record.data.enabled:
+        await scheduler.register_schedule(updated_record)
+
+    return updated_record
+
+
+@schedule_router.delete(
+    "/{schedule_id}",
+    status_code=status.HTTP_204_NO_CONTENT,
+    summary="Delete a schedule",
+)
+async def delete_schedule(
+    schedule_id: str,
+    user_id: str = Depends(get_current_user_id),
+    session_service: SessionService = Depends(get_session_service),
+    scheduler: SchedulerManager = Depends(get_scheduler_manager),
+) -> None:
+    """Permanently delete a schedule.
+
+    Cancels any in-flight chat run for sessions this schedule has
+    triggered, removes their records via the session service, and
+    finally unregisters the APScheduler job.
+
+    Args:
+        schedule_id (`str`): ID of the schedule to delete.
+        user_id (`str`): Authenticated user ID.
+        session_service (`SessionService`): Injected session service.
+        scheduler (`SchedulerManager`): Scheduler manager.
+
+    Raises:
+        `HTTPException`: 404 if the schedule does not exist.
+    """
+    deleted = await session_service.delete_schedule(user_id, schedule_id)
+    if not deleted:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Schedule '{schedule_id}' not found.",
+        )
+    await scheduler.remove_schedule(schedule_id)
+
+
+@schedule_router.get(
+    "/{schedule_id}/sessions",
+    response_model=ScheduleSessionsResponse,
+    summary="List execution sessions for a schedule",
+)
+async def list_schedule_sessions(
+    schedule_id: str,
+    user_id: str = Depends(get_current_user_id),
+    storage: StorageBase = Depends(get_storage),
+) -> ScheduleSessionsResponse:
+    """Return all sessions triggered by a given schedule.
+
+    Args:
+        schedule_id (`str`): ID of the schedule.
+        user_id (`str`): Authenticated user ID.
+        storage (`StorageBase`): Storage instance.
+
+    Returns:
+        `ScheduleSessionsResponse`:
+            List of execution sessions ordered by creation time (newest first).
+
+    Raises:
+        `HTTPException`: 404 if the schedule does not exist.
+    """
+    existing = await storage.get_schedule(user_id, schedule_id)
+    if existing is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Schedule '{schedule_id}' not found.",
+        )
+
+    sessions = await storage.list_sessions_by_schedule(user_id, schedule_id)
+    return ScheduleSessionsResponse(sessions=sessions, total=len(sessions))
diff --git a/src/agentscope/app/_router/_schema/__init__.py b/src/agentscope/app/_router/_schema/__init__.py
new file mode 100644
index 0000000..8b08faa
--- /dev/null
+++ b/src/agentscope/app/_router/_schema/__init__.py
@@ -0,0 +1,116 @@
+# -*- coding: utf-8 -*-
+"""Schema models for the agent service."""
+
+from ._chat import ChatRequest, ChatTriggerResponse
+from ._model import ListModelsResponse, ListModelsRequest
+from ._tts_model import ListTTSModelsResponse, ListTTSModelsRequest
+from ._schedule import (
+    CreateScheduleRequest,
+    CreateScheduleResponse,
+    ListSchedulesResponse,
+    ScheduleSessionsResponse,
+    UpdateScheduleRequest,
+)
+from ._agent import (
+    AgentSchemaResponse,
+    AgentSchemaV2Response,
+    ListAgentsResponse,
+    CreateAgentRequest,
+    CreateAgentResponse,
+    UpdateAgentRequest,
+)
+from ._credential import (
+    CreateCredentialRequest,
+    CreateCredentialResponse,
+    UpdateCredentialRequest,
+    ListCredentialsResponse,
+    ListCredentialSchemasResponse,
+)
+from ._knowledge_base import (
+    CreateKnowledgeBaseRequest,
+    CreateKnowledgeBaseResponse,
+    KbEmbeddingProvider,
+    KbMiddlewareParametersSchemaResponse,
+    KnowledgeDocumentView,
+    ListKbEmbeddingModelsResponse,
+    ListKnowledgeBasesResponse,
+    ListKnowledgeDocumentsResponse,
+    ListKnowledgeDocumentStatusResponse,
+    ListSupportedContentTypesResponse,
+    SearchKnowledgeBaseRequest,
+    SearchKnowledgeBaseResponse,
+    UpdateKnowledgeBaseRequest,
+    UploadKnowledgeDocumentResponse,
+)
+from ._session import (
+    CreateSessionRequest,
+    CreateSessionResponse,
+    InterruptSessionResponse,
+    UpdateSessionRequest,
+    ListSessionsResponse,
+    ListMessagesResponse,
+    SessionStatus,
+    SessionStatusResponse,
+    SessionView,
+    TeamDetailResponse,
+    TeamMemberView,
+)
+
+__all__ = [
+    # Agent
+    "AgentSchemaResponse",
+    "AgentSchemaV2Response",
+    "ListAgentsResponse",
+    "CreateAgentRequest",
+    "CreateAgentResponse",
+    "UpdateAgentRequest",
+    "ListSchedulesResponse",
+    # Chat
+    "ChatRequest",
+    "ChatTriggerResponse",
+    # Credential
+    "CreateCredentialRequest",
+    "CreateCredentialResponse",
+    "UpdateCredentialRequest",
+    "ListCredentialsResponse",
+    "ListCredentialSchemasResponse",
+    # Knowledge base
+    "CreateKnowledgeBaseRequest",
+    "CreateKnowledgeBaseResponse",
+    "KbEmbeddingProvider",
+    "KbMiddlewareParametersSchemaResponse",
+    "KnowledgeDocumentView",
+    "ListKbEmbeddingModelsResponse",
+    "ListKnowledgeBasesResponse",
+    "ListKnowledgeDocumentsResponse",
+    "ListKnowledgeDocumentStatusResponse",
+    "ListSupportedContentTypesResponse",
+    "SearchKnowledgeBaseRequest",
+    "SearchKnowledgeBaseResponse",
+    "UpdateKnowledgeBaseRequest",
+    "UploadKnowledgeDocumentResponse",
+    # Model
+    "ListModelsRequest",
+    "ListModelsResponse",
+    # TTS Model
+    "ListTTSModelsRequest",
+    "ListTTSModelsResponse",
+    # Schedule
+    "CreateScheduleRequest",
+    "CreateScheduleResponse",
+    "ListSchedulesResponse",
+    "ScheduleSessionsResponse",
+    "UpdateScheduleRequest",
+    # Session
+    "CreateSessionRequest",
+    "CreateSessionResponse",
+    "InterruptSessionResponse",
+    "UpdateSessionRequest",
+    "ListSessionsResponse",
+    "ListMessagesResponse",
+    "SessionStatus",
+    "SessionStatusResponse",
+    "SessionView",
+    "TeamDetailResponse",
+    "TeamMemberView",
+]
diff --git a/src/agentscope/app/_router/_schema/_agent.py b/src/agentscope/app/_router/_schema/_agent.py
new file mode 100644
index 0000000..750db69
--- /dev/null
+++ b/src/agentscope/app/_router/_schema/_agent.py
@@ -0,0 +1,139 @@
+# -*- coding: utf-8 -*-
+"""Request / response schemas for the agent router."""
+import warnings
+
+from pydantic import BaseModel, Field
+
+from ....agent import ContextConfig, ReActConfig
+from ...storage import InviteConfig
+from ..._service import AgentView
+
+
+class CreateAgentRequest(BaseModel):
+    """Request body for creating a new agent."""
+
+    name: str = Field(description="Display name of the agent.")
+    system_prompt: str = Field(
+        default="You're a helpful assistant.",
+        description="Base system prompt fed to the agent.",
+    )
+    context_config: ContextConfig = Field(
+        default_factory=ContextConfig,
+        description="Context-window management configuration.",
+    )
+    react_config: ReActConfig = Field(
+        default_factory=ReActConfig,
+        description="ReAct loop configuration.",
+    )
+    invite_config: InviteConfig = Field(
+        default_factory=InviteConfig,
+        description=(
+            "Invite-pool settings for this agent. See "
+            ":class:`InviteConfig` — enforces the "
+            "``invitable ⇒ non-empty description`` invariant."
+        ),
+    )
+
+
+class CreateAgentResponse(BaseModel):
+    """Response body after creating an agent."""
+
+    agent_id: str = Field(description="Server-assigned agent identifier.")
+
+
+class UpdateAgentRequest(BaseModel):
+    """Request body for partially updating an agent.
+
+    Omit any field to keep its current value.
+    """
+
+    name: str | None = Field(default=None, description="New display name.")
+    system_prompt: str | None = Field(
+        default=None,
+        description="New system prompt.",
+    )
+    context_config: ContextConfig | None = Field(
+        default=None,
+        description="New context configuration.",
+    )
+    react_config: ReActConfig | None = Field(
+        default=None,
+        description="New ReAct loop configuration.",
+    )
+    invite_config: InviteConfig | None = Field(
+        default=None,
+        description=(
+            "New invite-pool settings. Pass the full :class:`InviteConfig` "
+            "object to update; omit to leave both invitable-related "
+            "fields unchanged."
+        ),
+    )
+
+
+class ListAgentsResponse(BaseModel):
+    """Response body for listing agents."""
+
+    agents: list[AgentView] = Field(description="Agent records.")
+    total: int = Field(description="Total number of agents.")
+
+
+class AgentSchemaResponse(BaseModel):
+    """**Deprecated.** JSON Schema fragments used by the frontend to
+    render the agent create / edit forms.
+
+    Superseded by :class:`AgentSchemaV2Response`, which returns the full
+    :class:`AgentData` JSON Schema in a single ``schema`` field so newly
+    added agent fields (like the ``invite_config`` sub-model) reach the
+    frontend automatically without the router having to know about them.
+
+    The frontend previously split :class:`AgentData` into three
+    hand-picked sections (``identity``, ``context_config``,
+    ``react_config``) here, which required a router edit every time a
+    new user-editable field landed on :class:`AgentData`. Kept for
+    backwards compatibility with pre-v2 API consumers.
+    """
+
+    identity: dict = Field(
+        description=(
+            "Schema for the agent's identity fields (``name``, "
+            "``system_prompt``)."
+        ),
+    )
+    context_config: dict = Field(
+        description="Schema for ``ContextConfig``.",
+    )
+    react_config: dict = Field(
+        description="Schema for ``ReActConfig``.",
+    )
+
+
+# The ``schema`` field name below is intentional — the wire contract for
+# ``GET /agent/schema/v2`` is ``{"schema": ...}`` so the response is
+# self-documenting. Pydantic v2's :meth:`BaseModel.schema` is a
+# deprecated legacy classmethod (superseded by ``model_json_schema``);
+# a like-named instance field triggers a cosmetic "shadows an attribute
+# in parent BaseModel" warning that is irrelevant here because we never
+# call the legacy classmethod. Suppress it locally instead of adding an
+# alias that would obscure the wire contract at every call site.
+with warnings.catch_warnings():
+    warnings.filterwarnings(
+        "ignore",
+        message=r'Field name "schema" in "AgentSchemaV2Response"',
+    )
+
+    class AgentSchemaV2Response(BaseModel):
+        """Response for ``GET /agent/schema/v2``.
+
+        Wraps the full :class:`AgentData` JSON Schema in a single
+        ``schema`` field so the frontend can render every user-editable
+        property without the router having to enumerate them.
+        """
+
+        schema: dict = Field(
+            description=(
+                "Full :class:`AgentData` JSON Schema. All user-editable "
+                "fields appear as top-level entries in ``properties`` — "
+                "the frontend derives its section grouping from this "
+                "single schema."
+            ),
+        )
diff --git a/src/agentscope/app/_router/_schema/_chat.py b/src/agentscope/app/_router/_schema/_chat.py
new file mode 100644
index 0000000..5bb68a3
--- /dev/null
+++ b/src/agentscope/app/_router/_schema/_chat.py
@@ -0,0 +1,45 @@
+# -*- coding: utf-8 -*-
+"""The chat endpoint schema."""
+
+from pydantic import BaseModel, Field
+
+from ....message import Msg
+from ....event import UserConfirmResultEvent, ExternalExecutionResultEvent
+
+
+class ChatRequest(BaseModel):
+    """Request body for the chat endpoint."""
+
+    agent_id: str = Field(
+        description="Agent ID for the chat endpoint.",
+    )
+
+    session_id: str = Field(
+        description="The session to send the message to.",
+    )
+
+    input: (
+        Msg
+        | list[Msg]
+        | UserConfirmResultEvent
+        | ExternalExecutionResultEvent
+        | None
+    ) = Field(
+        description="The input message(s), or agent event, or None.",
+    )
+
+
+class ChatTriggerResponse(BaseModel):
+    """Response body for the fire-and-forget chat trigger.
+
+    Confirms that the chat run was scheduled. Events produced by the
+    run arrive separately via the session's SSE stream endpoint.
+    """
+
+    status: str = Field(
+        default="started",
+        description='Always ``"started"`` when the trigger succeeded.',
+    )
+    session_id: str = Field(
+        description="Echo of the session id the run was started for.",
+    )
diff --git a/src/agentscope/app/_router/_schema/_credential.py b/src/agentscope/app/_router/_schema/_credential.py
new file mode 100644
index 0000000..445260a
--- /dev/null
+++ b/src/agentscope/app/_router/_schema/_credential.py
@@ -0,0 +1,42 @@
+# -*- coding: utf-8 -*-
+"""Request / response schemas for the credential router."""
+from pydantic import BaseModel, Field
+
+from ..._service import CredentialView
+
+
+class CreateCredentialRequest(BaseModel):
+    """Request body for creating a new credential."""
+
+    data: dict = Field(description="Credential payload (e.g. API keys).")
+
+
+class CreateCredentialResponse(BaseModel):
+    """Response body after creating a credential."""
+
+    credential_id: str = Field(
+        description="Server-assigned credential identifier.",
+    )
+
+
+class UpdateCredentialRequest(BaseModel):
+    """Request body for updating an existing credential."""
+
+    data: dict = Field(description="New credential payload.")
+
+
+class ListCredentialsResponse(BaseModel):
+    """Response body for listing credentials."""
+
+    credentials: list[CredentialView] = Field(
+        description="Credential records.",
+    )
+    total: int = Field(description="Total number of credentials.")
+
+
+class ListCredentialSchemasResponse(BaseModel):
+    """Response body for listing credential type schemas."""
+
+    schemas: list[dict] = Field(
+        description="JSON schemas for all registered credential types.",
+    )
diff --git a/src/agentscope/app/_router/_schema/_knowledge_base.py b/src/agentscope/app/_router/_schema/_knowledge_base.py
new file mode 100644
index 0000000..5484b74
--- /dev/null
+++ b/src/agentscope/app/_router/_schema/_knowledge_base.py
@@ -0,0 +1,274 @@
+# -*- coding: utf-8 -*-
+"""Request / response schemas for the knowledge base router."""
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+from ...storage import (
+    EmbeddingModelConfig,
+    KnowledgeDocumentRecord,
+    KnowledgeDocumentStatus,
+)
+from ..._service import CredentialView, KnowledgeBaseView
+from ....embedding import EmbeddingModelCard
+from ....rag import VectorSearchResult
+from ...rag.knowledge_base_manager._dimension_policy import DimensionPolicy
+
+
+class CreateKnowledgeBaseRequest(BaseModel):
+    """Request body for creating a new knowledge base."""
+
+    name: str = Field(description="Display name of the knowledge base.")
+    description: str = Field(
+        default="",
+        description="Free-form description shown in the UI.",
+    )
+    embedding_model_config: EmbeddingModelConfig = Field(
+        description=(
+            "Embedding model used both at indexing and at query time. "
+            "Cannot be changed after creation — switching would "
+            "invalidate every previously inserted vector."
+        ),
+    )
+
+
+class CreateKnowledgeBaseResponse(BaseModel):
+    """Response body after creating a knowledge base."""
+
+    knowledge_base_id: str = Field(
+        description="Server-assigned knowledge base identifier.",
+    )
+
+
+class UpdateKnowledgeBaseRequest(BaseModel):
+    """Request body for updating a knowledge base.
+
+    Only mutable fields can be set here.  The embedding model
+    configuration is pinned at creation time and cannot be changed —
+    switching it would invalidate every previously inserted vector.
+    """
+
+    name: str | None = Field(
+        default=None,
+        description="New display name; omit to leave unchanged.",
+    )
+    description: str | None = Field(
+        default=None,
+        description="New free-form description; omit to leave unchanged.",
+    )
+
+
+class ListKnowledgeBasesResponse(BaseModel):
+    """Response body for listing the caller's knowledge bases."""
+
+    knowledge_bases: list[KnowledgeBaseView] = Field(
+        description="All knowledge bases owned by the caller.",
+    )
+    total: int = Field(description="Total number of returned items.")
+
+
+class KnowledgeDocumentView(BaseModel):
+    """A document record as exposed to API clients.
+
+    Surfaces both the static fields the UI needs to render a row
+    (``filename`` / ``size``) and the live lifecycle fields the front
+    end polls (``status`` / ``error`` / ``chunk_count``).  Internal
+    fields (``user_id`` / ``blob_uri`` / ``processing_node`` / lease)
+    are deliberately omitted — clients have no business introspecting
+    them.
+    """
+
+    id: str = Field(description="The document identifier.")
+    filename: str = Field(description="Original filename at upload time.")
+    size: int = Field(description="Document size in bytes.")
+    content_type: str | None = Field(
+        default=None,
+        description="IANA media type recorded at upload time, if any.",
+    )
+    status: KnowledgeDocumentStatus = Field(
+        description="Current lifecycle state of the document.",
+    )
+    error: str | None = Field(
+        default=None,
+        description=(
+            "Human-readable failure reason when ``status == 'error'``."
+        ),
+    )
+    chunk_count: int = Field(
+        default=0,
+        description="Number of chunks indexed so far.",
+    )
+    created_at: datetime = Field(description="Upload timestamp.")
+    updated_at: datetime = Field(
+        description="Last status transition timestamp.",
+    )
+
+    @classmethod
+    def from_record(
+        cls,
+        record: KnowledgeDocumentRecord,
+    ) -> "KnowledgeDocumentView":
+        """Project a storage record onto the API view.
+
+        Centralised so router code stays a one-liner and the field
+        mapping has exactly one source of truth.
+        """
+        return cls(
+            id=record.id,
+            filename=record.data.filename,
+            size=record.data.size,
+            content_type=record.data.content_type,
+            status=record.data.status,
+            error=record.data.error,
+            chunk_count=record.data.chunk_count,
+            created_at=record.created_at,
+            updated_at=record.updated_at,
+        )
+
+
+class ListKnowledgeDocumentsResponse(BaseModel):
+    """Response body for listing documents inside a knowledge base."""
+
+    documents: list[KnowledgeDocumentView] = Field(
+        description="One view per registered document.",
+    )
+    total: int = Field(description="Total number of returned items.")
+
+
+class ListKnowledgeDocumentStatusResponse(BaseModel):
+    """Response body for batch document-status polling."""
+
+    items: list[KnowledgeDocumentView] = Field(
+        description=(
+            "Subset of the requested documents that still exist. "
+            "Missing ids are silently omitted — clients may legitimately "
+            "ask about a document that was deleted between two polls."
+        ),
+    )
+
+
+class UploadKnowledgeDocumentResponse(BaseModel):
+    """Response body after uploading a document into a knowledge base."""
+
+    document_id: str = Field(
+        description="Server-assigned document identifier.",
+    )
+    filename: str = Field(
+        description="The original filename of the uploaded document.",
+    )
+    status: KnowledgeDocumentStatus = Field(
+        description=(
+            "Lifecycle state immediately after upload — always "
+            "``'pending'`` in the happy path; surfaced so the client "
+            "can seed its progress tracker without an extra round-trip."
+        ),
+    )
+
+
+class SearchKnowledgeBaseRequest(BaseModel):
+    """Request body for searching a knowledge base."""
+
+    query: str = Field(description="The natural-language search query.")
+    top_k: int = Field(
+        default=5,
+        ge=1,
+        le=50,
+        description="Maximum number of results to return.",
+    )
+
+
+class SearchKnowledgeBaseResponse(BaseModel):
+    """Response body for a knowledge base search."""
+
+    results: list[VectorSearchResult] = Field(
+        description="Matched chunks ordered by descending similarity score.",
+    )
+    total: int = Field(description="Total number of returned results.")
+
+
+class KbEmbeddingProvider(BaseModel):
+    """One credential and the embedding models it can serve.
+
+    The model cards have been projected through the manager's
+    dimension policy: incompatible models are removed and matryoshka
+    cards are narrowed to the locked dimension when applicable.
+    """
+
+    credential: CredentialView = Field(
+        description="The credential record exposing these models.",
+    )
+    models: list[EmbeddingModelCard] = Field(
+        description=(
+            "Embedding model cards available under this credential, "
+            "filtered to those compatible with the manager's "
+            "dimension policy."
+        ),
+    )
+
+
+class ListKbEmbeddingModelsResponse(BaseModel):
+    """Response body listing KB-compatible embedding models.
+
+    The list is pre-filtered server-side against the manager's
+    dimension policy.  The policy itself is also returned so the
+    front-end can render an explanatory banner and lock the dimension
+    selector when applicable.
+    """
+
+    providers: list[KbEmbeddingProvider] = Field(
+        description=(
+            "One entry per credential that has at least one "
+            "compatible embedding model."
+        ),
+    )
+    policy: DimensionPolicy = Field(
+        description=(
+            "The dimension policy used to filter the cards; surfaced "
+            "verbatim so the UI can explain *why* models were filtered."
+        ),
+    )
+
+
+class KbMiddlewareParametersSchemaResponse(BaseModel):
+    """Response body exposing the KB middleware's parameters schema.
+
+    The schema is derived from
+    :class:`agentscope.middleware.RAGMiddleware.Parameters`
+    via ``model_json_schema()`` so the front-end can render the
+    session-level KB attachment form with the same schema-driven
+    component used for model parameters.
+    """
+
+    parameter_schema: dict = Field(
+        description=(
+            "JSON Schema produced by `RAGMiddleware.Parameters"
+            "model_json_schema()`.  Shaped identically to the "
+            "`parameter_schema` field on `ModelCard`."
+        ),
+    )
+
+
+class ListSupportedContentTypesResponse(BaseModel):
+    """Response body advertising the parser-supported upload types.
+
+    Aggregated across every parser registered on the app — the union of
+    each parser's :attr:`supported_media_types` and
+    :meth:`supported_extensions`.  The front-end uses this to populate
+    ``<input accept>`` and to reject unsupported drops on the client
+    before the file leaves the browser.
+    """
+
+    media_types: list[str] = Field(
+        description=(
+            "Union of IANA media types every registered parser claims "
+            "to handle.  Deduplicated and sorted."
+        ),
+    )
+    extensions: list[str] = Field(
+        description=(
+            "Filename extensions (each starting with `.`) every "
+            "registered parser claims to handle.  Deduplicated and "
+            "sorted.  Derived from `mimetypes` by the base parser; "
+            "subclasses may override the default."
+        ),
+    )
diff --git a/src/agentscope/app/_router/_schema/_mcp.py b/src/agentscope/app/_router/_schema/_mcp.py
new file mode 100644
index 0000000..023f941
--- /dev/null
+++ b/src/agentscope/app/_router/_schema/_mcp.py
@@ -0,0 +1,127 @@
+# -*- coding: utf-8 -*-
+"""MCP schemas for API requests and responses."""
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+from ....mcp import StdioMCPConfig, HttpMCPConfig
+
+
+class ConnectionScope(str, Enum):
+    """MCP connection scope and lifecycle strategy.
+
+    This determines how MCP connections are managed in the service layer.
+    """
+
+    SHARED = "shared"
+    """Shared connection across all agents/users.
+    - One connection per MCP config, shared globally
+    - Created on first use, destroyed on application shutdown
+    - Use case: Stateless HTTP MCP (e.g., weather API, web search)
+    """
+
+    ISOLATED = "isolated"
+    """Isolated connection per agent.
+    - One connection per (MCP config, agent)
+    - Created on first use per agent, destroyed on agent session end
+    - Use case: Stateful MCP (e.g., browser-use), STDIO MCP
+    """
+
+    EPHEMERAL = "ephemeral"
+    """Ephemeral connection per request.
+    - New connection created for each request, destroyed immediately after
+    - No connection pooling
+    - Use case: Low-frequency stateless HTTP MCP
+    """
+
+
+class MCPBase(BaseModel):
+    """Base MCP fields shared across request/response schemas."""
+
+    name: str = Field(
+        title="MCP Name",
+        description="The unique name to identify this MCP configuration.",
+    )
+
+    connection_scope: ConnectionScope = Field(
+        title="Connection Scope",
+        description="The connection scope and lifecycle strategy.",
+    )
+
+    mcp_config: StdioMCPConfig | HttpMCPConfig = Field(
+        discriminator="type",
+        title="MCP Config",
+        description="The base MCP server configuration.",
+    )
+
+    def validate_config(self) -> None:
+        """Validate the configuration.
+
+        Raises:
+            ValueError: If the configuration is invalid.
+        """
+        # STDIO MCP cannot use ephemeral mode
+        if (
+            self.mcp_config.type == "stdio_mcp"
+            and self.connection_scope == ConnectionScope.EPHEMERAL
+        ):
+            raise ValueError(
+                "STDIO MCP does not support ephemeral mode. "
+                "Use 'shared' or 'isolated' instead.",
+            )
+
+
+class MCPCreateRequest(MCPBase):
+    """Request body for creating a new MCP configuration.
+
+    Used in POST /mcp endpoint. Does not include server-generated fields
+    like creator_id, created_at, updated_at.
+    """
+
+
+class MCPUpdateRequest(BaseModel):
+    """Request body for partially updating an MCP configuration.
+
+    Used in PATCH /mcp/{name} endpoint. All fields are optional.
+    """
+
+    connection_scope: ConnectionScope | None = Field(
+        default=None,
+        description="New connection scope.",
+    )
+    mcp_config: StdioMCPConfig | HttpMCPConfig | None = Field(
+        default=None,
+        discriminator="type",
+        description="New MCP server configuration.",
+    )
+
+
+class MCPResponse(MCPBase):
+    """Response model for MCP configuration with server-generated metadata.
+
+    Used in GET /mcp/{name}, GET /mcp (list), and POST /mcp responses.
+    Includes all fields from MCPBase plus server-assigned metadata.
+    """
+
+    creator_id: str = Field(
+        description="User ID of the creator.",
+    )
+
+    created_at: float = Field(
+        description="Creation timestamp (Unix epoch).",
+    )
+
+    updated_at: float = Field(
+        description="Last-updated timestamp (Unix epoch).",
+    )
+
+
+class ListMCPsResponse(BaseModel):
+    """Response model for listing MCP configurations."""
+
+    mcps: list[MCPResponse] = Field(
+        description="List of MCP configurations.",
+    )
+    total: int = Field(
+        description="Total number of MCP configurations.",
+    )
diff --git a/src/agentscope/app/_router/_schema/_model.py b/src/agentscope/app/_router/_schema/_model.py
new file mode 100644
index 0000000..23c24de
--- /dev/null
+++ b/src/agentscope/app/_router/_schema/_model.py
@@ -0,0 +1,21 @@
+# -*- coding: utf-8 -*-
+"""The chat model configuration, used as DTO layer."""
+
+from pydantic import BaseModel, Field
+
+from ....model import ModelCard
+
+
+class ListModelsResponse(BaseModel):
+    """List the candidate models response."""
+
+    models: list[ModelCard] = Field(description="The candidate models.")
+    total: int = Field(description="The total number of candidates.")
+
+
+class ListModelsRequest(BaseModel):
+    """List the candidate models request."""
+
+    provider: str = Field(
+        description="The provider type, e.g. openai, dashscope, etc.",
+    )
diff --git a/src/agentscope/app/_router/_schema/_schedule.py b/src/agentscope/app/_router/_schema/_schedule.py
new file mode 100644
index 0000000..472b571
--- /dev/null
+++ b/src/agentscope/app/_router/_schema/_schedule.py
@@ -0,0 +1,118 @@
+# -*- coding: utf-8 -*-
+"""Request / response schemas for the schedule router."""
+from pydantic import BaseModel, Field
+
+from ...storage import (
+    ScheduleRecord,
+    SessionRecord,
+    ChatModelConfig,
+)
+from ....permission import PermissionMode
+
+
+class CreateScheduleRequest(BaseModel):
+    """Request body for creating a new schedule."""
+
+    name: str = Field(description="Display name of the schedule.")
+
+    description: str = Field(default="", description="Optional description.")
+
+    cron_expression: str = Field(
+        description="Standard 5-field cron expression, e.g. '0 9 * * 1-5'.",
+    )
+
+    timezone: str = Field(
+        default="UTC",
+        description="IANA timezone name, e.g. 'America/New_York' or "
+        "'Asia/Shanghai'.",
+    )
+
+    agent_id: str = Field(description="Agent to run when the schedule fires.")
+
+    chat_model_config: ChatModelConfig = Field(
+        description="Model configuration for the auto-created session.",
+    )
+
+    enabled: bool = Field(
+        default=True,
+        description="Whether the schedule is active immediately "
+        "after creation.",
+    )
+
+    stateful: bool = Field(
+        default=False,
+        description="If True, consecutive executions share the same session "
+        "context.",
+    )
+
+    permission_mode: PermissionMode = Field(
+        default=PermissionMode.DONT_ASK,
+        description="Permission level for the agent during "
+        "scheduled execution.",
+    )
+
+
+class CreateScheduleResponse(BaseModel):
+    """Response body after creating a schedule."""
+
+    schedule_id: str = Field(
+        description="Server-assigned schedule identifier.",
+    )
+
+
+class UpdateScheduleRequest(BaseModel):
+    """Request body for partially updating a schedule.
+
+    Omit any field to keep its current value.  Changing ``cron_expression``
+    or ``timezone`` will reschedule the APScheduler job immediately.
+    Changing ``enable`` to ``False`` removes the job from the scheduler
+    without deleting the record; setting it back to ``True`` re-registers it.
+    """
+
+    name: str | None = Field(default=None, description="New display name.")
+
+    description: str | None = Field(
+        default=None,
+        description="New description.",
+    )
+
+    cron_expression: str | None = Field(
+        default=None,
+        description="New cron expression. Reschedules the task immediately.",
+    )
+
+    timezone: str | None = Field(
+        default=None,
+        description="New IANA timezone name.",
+    )
+
+    enabled: bool | None = Field(
+        default=None,
+        description="Set to False to pause the schedule without deleting it.",
+    )
+
+    stateful: bool | None = Field(
+        default=None,
+        description="Change whether executions share session context.",
+    )
+
+    permission_mode: PermissionMode | None = Field(
+        default=None,
+        description="New permission mode.",
+    )
+
+
+class ListSchedulesResponse(BaseModel):
+    """Response body for listing schedules."""
+
+    schedules: list[ScheduleRecord] = Field(description="Schedule records.")
+    total: int = Field(description="Total number of schedules.")
+
+
+class ScheduleSessionsResponse(BaseModel):
+    """Response body for listing execution sessions of a schedule."""
+
+    sessions: list[SessionRecord] = Field(
+        description="Sessions triggered by this schedule.",
+    )
+    total: int = Field(description="Total number of execution sessions.")
diff --git a/src/agentscope/app/_router/_schema/_session.py b/src/agentscope/app/_router/_schema/_session.py
new file mode 100644
index 0000000..52a4078
--- /dev/null
+++ b/src/agentscope/app/_router/_schema/_session.py
@@ -0,0 +1,238 @@
+# -*- coding: utf-8 -*-
+"""Request / response schemas for the session router."""
+from pydantic import BaseModel, Field
+
+from ....permission import PermissionMode
+from ...storage import (
+    ChatModelConfig,
+    SessionKnowledgeConfig,
+    TTSModelConfig,
+    SessionRecord,
+    TeamRecord,
+)
+from ..._service import AgentView, SessionStatus
+
+
+class TeamMemberView(BaseModel):
+    """One row in :attr:`TeamDetailResponse.members`.
+
+    Pairs each member's :class:`AgentView` with its single
+    ``session_id`` so the UI can subscribe to the worker's chat
+    stream without a separate lookup.
+    """
+
+    agent: AgentView = Field(
+        description="The worker agent record.",
+    )
+    session_id: str | None = Field(
+        default=None,
+        description=(
+            "The worker's session id. ``None`` if the agent is in an "
+            "inconsistent state (worker without a session)."
+        ),
+    )
+
+
+class TeamDetailResponse(BaseModel):
+    """Resolved team detail embedded inside :class:`SessionView.team`."""
+
+    team: TeamRecord = Field(description="The team record.")
+    leader_agent: AgentView | None = Field(
+        default=None,
+        description=(
+            "Leader's agent record (resolved from the team's "
+            "``session_id`` → session.agent_id)."
+        ),
+    )
+    members: list[TeamMemberView] = Field(
+        default_factory=list,
+        description=(
+            "Worker agents listed in :attr:`TeamData.member_ids`, each "
+            "paired with its single session id when available."
+        ),
+    )
+
+
+class CreateSessionRequest(BaseModel):
+    """Request body for creating a new session."""
+
+    agent_id: str = Field(description="Agent this session belongs to.")
+    workspace_id: str | None = Field(
+        default=None,
+        description=(
+            "Optional explicit workspace binding. When omitted the "
+            "server calls "
+            "``WorkspaceManagerBase.assign_workspace_id`` under the "
+            "configured isolation policy. Set only to force a "
+            "specific binding (e.g. share workspace with another "
+            "existing session)."
+        ),
+    )
+    name: str | None = Field(
+        default=None,
+        description="Display name. Defaults to current datetime if omitted.",
+    )
+    chat_model_config: ChatModelConfig | None = Field(
+        default=None,
+        description="Model provider and parameters. "
+        "Can be set later via PATCH.",
+    )
+    fallback_chat_model_config: ChatModelConfig | None = Field(
+        default=None,
+        description="Fallback model used when the primary model fails. "
+        "Can be set later via PATCH.",
+    )
+    tts_model_config: TTSModelConfig | None = Field(
+        default=None,
+        description="TTS model configuration. Can be set later via PATCH.",
+    )
+    knowledge_config: SessionKnowledgeConfig | None = Field(
+        default=None,
+        description=(
+            "Knowledge bases attached to this session plus the "
+            "`RAGMiddleware` parameters. Can be set later "
+            "via PATCH."
+        ),
+    )
+
+
+class CreateSessionResponse(BaseModel):
+    """Response body after creating a session."""
+
+    session_id: str = Field(description="Server-assigned session identifier.")
+
+
+class UpdateSessionRequest(BaseModel):
+    """Request body for updating an existing session.
+
+    Omit any field to keep its current value.
+    """
+
+    name: str | None = Field(
+        default=None,
+        description="New display name.",
+    )
+    chat_model_config: ChatModelConfig | None = Field(
+        default=None,
+        description="New model configuration. "
+        "Replaces the existing one entirely. "
+        "Pass null to clear; omit to leave unchanged.",
+    )
+    fallback_chat_model_config: ChatModelConfig | None = Field(
+        default=None,
+        description="New fallback model configuration. "
+        "Pass null to clear; omit to leave unchanged.",
+    )
+    tts_model_config: TTSModelConfig | None = Field(
+        default=None,
+        description="New TTS model configuration. "
+        "Pass null to clear; omit to leave unchanged.",
+    )
+    knowledge_config: SessionKnowledgeConfig | None = Field(
+        default=None,
+        description=(
+            "New knowledge base attachment + middleware parameters. "
+            "Pass null to clear; omit to leave unchanged."
+        ),
+    )
+    permission_mode: PermissionMode | None = Field(
+        default=None,
+        description="New permission mode for the session.",
+    )
+
+
+class SessionView(BaseModel):
+    """Per-session bundle with everything the frontend needs to
+    render either the list view or open a session.
+
+    Bundles three orthogonal pieces of information so opening a
+    session does not require a waterfall of follow-up requests:
+
+    - the persisted :class:`SessionRecord` itself (config + state),
+    - whether the session has an active chat run right now,
+    - the team detail (resolved leader + members) when the session
+      participates in a team.
+
+    Messages are intentionally **not** included here — they are
+    paginated separately via ``GET /sessions/{id}/messages``.
+    """
+
+    session: SessionRecord = Field(
+        description=(
+            "The persisted session record. Includes ``state`` "
+            "(``permission_context`` / ``tool_context`` / "
+            "``tasks_context``) inline."
+        ),
+    )
+    is_running: bool = Field(
+        description="Whether a chat run is currently active on this session.",
+    )
+    team: TeamDetailResponse | None = Field(
+        default=None,
+        description=(
+            "Resolved team detail when ``session.team_id`` is set "
+            "(leader agent + member agents with their session ids). "
+            "``None`` when the session does not participate in any team."
+        ),
+    )
+
+
+class ListSessionsResponse(BaseModel):
+    """Response body for listing sessions."""
+
+    sessions: list[SessionView] = Field(
+        description="Session views (record + is_running + team).",
+    )
+    total: int = Field(description="Total number of sessions.")
+
+
+class ListMessagesResponse(BaseModel):
+    """Response body for listing messages in a session."""
+
+    messages: list = Field(description="Messages in chronological order.")
+    is_running: bool = Field(
+        description="Whether the session is currently running.",
+    )
+
+
+class SessionStatusResponse(BaseModel):
+    """Response body for probing a session's high-level status.
+
+    See :class:`~agentscope.app._service.SessionStatus` for the
+    semantics of each ``status`` value and the precedence rules used
+    to derive it.
+    """
+
+    session_id: str = Field(description="The session that was probed.")
+    status: SessionStatus = Field(
+        description=(
+            "The session's unified status. One of ``running`` "
+            "(some worker holds the run lease), ``idle`` (no worker, "
+            "context clean), ``awaiting_permission`` (no worker, "
+            "context parked on HITL tool call), or "
+            "``awaiting_external_result`` (no worker, context parked "
+            "on external executor)."
+        ),
+    )
+
+
+class InterruptSessionResponse(BaseModel):
+    """Response body for ``POST /sessions/{sid}/interrupt`` (HTTP 202).
+
+    The interrupt operation is idempotent and always succeeds for an
+    existing session (only ``404`` is raised when the session id does
+    not exist):
+
+    - If the session is **running**, an interrupt signal is published
+      so the local
+      :class:`~agentscope.app._manager.CancelDispatcher` cancels the
+      chat-run task; the agent then runs its ``CancelledError`` cleanup
+      path.
+    - If the session is **parked** on HITL / external execution, a
+      resume trigger carrying a
+      :class:`~agentscope.event.UserInterruptEvent` is enqueued so the
+      agent short-circuits into the same cleanup path.
+    - If the session is **idle**, the call is a no-op.
+    """
+
+    session_id: str = Field(description="Echo of the interrupted session id.")
diff --git a/src/agentscope/app/_router/_schema/_tts_model.py b/src/agentscope/app/_router/_schema/_tts_model.py
new file mode 100644
index 0000000..d37998a
--- /dev/null
+++ b/src/agentscope/app/_router/_schema/_tts_model.py
@@ -0,0 +1,23 @@
+# -*- coding: utf-8 -*-
+"""The TTS model configuration, used as DTO layer."""
+
+from pydantic import BaseModel, Field
+
+from ....tts import TTSModelCard
+
+
+class ListTTSModelsResponse(BaseModel):
+    """List the candidate TTS models response."""
+
+    models: list[TTSModelCard] = Field(
+        description="The candidate TTS models.",
+    )
+    total: int = Field(description="The total number of candidates.")
+
+
+class ListTTSModelsRequest(BaseModel):
+    """List the candidate TTS models request."""
+
+    provider: str = Field(
+        description="The provider type, e.g. dashscope_credential.",
+    )
diff --git a/src/agentscope/app/_router/_session.py b/src/agentscope/app/_router/_session.py
new file mode 100644
index 0000000..35a29e5
--- /dev/null
+++ b/src/agentscope/app/_router/_session.py
@@ -0,0 +1,837 @@
+# -*- coding: utf-8 -*-
+"""Session router — create, list, update, delete, stream, and get messages."""
+import asyncio
+import json
+from typing import AsyncGenerator
+
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+from fastapi.responses import StreamingResponse
+
+from ..._utils._common import _generate_id
+from ..access import ResourceKind
+from ..deps import (
+    get_chat_service,
+    get_current_user_id,
+    get_message_bus,
+    get_resource_access_service,
+    get_session_service,
+    get_storage,
+    get_workspace_manager,
+)
+from ._schema import (
+    CreateSessionRequest,
+    CreateSessionResponse,
+    InterruptSessionResponse,
+    ListMessagesResponse,
+    ListSessionsResponse,
+    SessionStatusResponse,
+    SessionView,
+    TeamDetailResponse,
+    TeamMemberView,
+    UpdateSessionRequest,
+)
+from ..message_bus import MessageBus, MessageBusKeys
+from .._service import (
+    AgentView,
+    ResourceAccessService,
+    ChatService,
+    SessionService,
+    SessionProjection,
+    SubagentHitlProjector,
+)
+from ..storage import (
+    ChatModelConfig,
+    SessionKnowledgeConfig,
+    TTSModelConfig,
+    SessionConfig,
+    SessionRecord,
+    StorageBase,
+    TeamRecord,
+)
+from ...message import ToolCallState
+from ..storage._utils import _ensure_team_members
+from ...event import CustomEvent
+from ..workspace_manager import WorkspaceManagerBase
+
+
+async def _build_team_detail(
+    storage: StorageBase,
+    user_id: str,
+    team: TeamRecord,
+) -> TeamDetailResponse:
+    """Resolve a team's leader agent + member agents into a
+    :class:`TeamDetailResponse` for the session list endpoint.
+
+    Args:
+        storage (`StorageBase`):
+            Application storage. Used to look up the leader session,
+            each member agent, and each member's session.
+        user_id (`str`):
+            The owner user id.
+        team (`TeamRecord`):
+            The team to resolve. Caller has already loaded it.
+
+    Returns:
+        `TeamDetailResponse`:
+            The team plus its resolved leader and member agents (each
+            member paired with its session id when available).
+    """
+    leader_agent: AgentView | None = None
+    leader_session = await storage.get_session(user_id, "", team.session_id)
+    if leader_session is not None:
+        leader_record = await storage.get_agent(
+            user_id,
+            leader_session.agent_id,
+        )
+        if leader_record is not None:
+            leader_agent = AgentView.model_validate(
+                {
+                    **leader_record.model_dump(),
+                    "editable": leader_record.user_id == user_id,
+                },
+            )
+
+    members: list[TeamMemberView] = []
+    for member in await _ensure_team_members(storage, user_id, team):
+        agent = await storage.get_agent(member.owner_id, member.agent_id)
+        if agent is None:
+            continue
+        # Use the member's team-scoped session id directly; an invited
+        # agent has multiple sessions and only ``member.session_id``
+        # belongs to this team. A member whose owner is not the current
+        # user was invited from another user's pool — read-only here.
+        members.append(
+            TeamMemberView(
+                agent=AgentView.model_validate(
+                    {
+                        **agent.model_dump(),
+                        "editable": member.owner_id == user_id,
+                    },
+                ),
+                session_id=member.session_id,
+            ),
+        )
+
+    return TeamDetailResponse(
+        team=team,
+        leader_agent=leader_agent,
+        members=members,
+    )
+
+
+session_router = APIRouter(
+    prefix="/sessions",
+    tags=["sessions"],
+    responses={404: {"description": "Not found"}},
+)
+
+
+async def _ensure_credential_exists(
+    access: ResourceAccessService,
+    user_id: str,
+    config: ChatModelConfig | TTSModelConfig | None,
+) -> None:
+    """Validate that the credential referenced by ``config`` is visible to
+    the given user (own or shared). No-op when ``config`` is ``None``.
+
+    Args:
+        access (`ResourceAccessService`): Injected access service.
+        user_id (`str`): The authenticated user ID.
+        config (`ChatModelConfig | TTSModelConfig | None`): Model config to
+            validate. Pass ``None`` to skip the check.
+
+    Raises:
+        `HTTPException`: 404 if the credential does not exist or is not
+            visible to the user.
+    """
+    if config is None:
+        return
+    # ``get_resource`` raises 404 when the credential is neither owned
+    # nor shared to the viewer — exactly the semantics we want.
+    await access.get_resource(
+        user_id,
+        ResourceKind.CREDENTIAL,
+        config.credential_id,
+    )
+
+
+async def _ensure_knowledge_bases_exist(
+    access: ResourceAccessService,
+    user_id: str,
+    config: SessionKnowledgeConfig | None,
+) -> None:
+    """Validate every KB id in ``config`` is visible to the given user.
+
+    No-op when ``config`` is ``None`` or its ``knowledge_base_ids``
+    list is empty.
+
+    Args:
+        access (`ResourceAccessService`): Injected access service.
+        user_id (`str`): The authenticated user ID.
+        config (`SessionKnowledgeConfig | None`):
+            Knowledge config to validate.  Pass ``None`` to skip.
+
+    Raises:
+        `HTTPException`: 404 if any KB id is not visible to the user.
+    """
+    if config is None or not config.knowledge_base_ids:
+        return
+    for kb_id in config.knowledge_base_ids:
+        await access.get_resource(
+            user_id,
+            ResourceKind.KNOWLEDGE_BASE,
+            kb_id,
+        )
+
+
+@session_router.get(
+    "/",
+    response_model=ListSessionsResponse,
+    summary="List sessions for an agent",
+)
+async def list_sessions(
+    agent_id: str = Query(description="Filter sessions by agent ID."),
+    user_id: str = Depends(get_current_user_id),
+    storage: StorageBase = Depends(get_storage),
+    access: ResourceAccessService = Depends(get_resource_access_service),
+    message_bus: MessageBus = Depends(get_message_bus),
+) -> ListSessionsResponse:
+    """Return all sessions for an agent as enriched
+    :class:`SessionView` entries.
+
+    Each entry bundles three things the chat UI needs to render
+    without follow-up requests: the session record (incl.
+    ``state``), whether a chat run is currently active, and — when
+    the session participates in a team — the resolved team detail
+    (leader agent + member agents with their session ids).
+
+    Args:
+        agent_id (`str`):
+            Agent whose sessions to list. May be an agent shared to
+            the viewer through :class:`ResourceAccessPolicyBase`;
+            the returned sessions are still the viewer's own.
+        user_id (`str`):
+            Injected authenticated user ID.
+        storage (`StorageBase`):
+            Injected storage backend.
+        access (`ResourceAccessService`):
+            Injected resource access service; used to validate that
+            the target agent is visible to the viewer.
+        message_bus (`MessageBus`):
+            Injected message bus (used for ``session_is_running``).
+
+    Returns:
+        `ListSessionsResponse`:
+            Enriched session views and their count.
+
+    Raises:
+        `HTTPException`: 404 if the agent is not visible to the caller.
+    """
+    # Verify visibility (own or shared) — raises 404 otherwise. Sessions
+    # themselves are always looked up under ``user_id``, so a viewer
+    # only ever sees their own runs of a shared agent.
+    await access.resolve_agent(user_id, agent_id)
+
+    sessions = await storage.list_sessions(user_id, agent_id)
+    views: list[SessionView] = []
+    for session in sessions:
+        team_detail = None
+        if session.team_id:
+            team_record = await storage.get_team(user_id, session.team_id)
+            if team_record is not None:
+                team_detail = await _build_team_detail(
+                    storage,
+                    user_id,
+                    team_record,
+                )
+        views.append(
+            SessionView(
+                session=session,
+                is_running=await message_bus.is_locked(
+                    MessageBusKeys.session_lock(session.id),
+                ),
+                team=team_detail,
+            ),
+        )
+    return ListSessionsResponse(sessions=views, total=len(views))
+
+
+@session_router.post(
+    "/",
+    response_model=CreateSessionResponse,
+    status_code=status.HTTP_201_CREATED,
+    summary="Create a new session",
+)
+async def create_session(
+    body: CreateSessionRequest,
+    user_id: str = Depends(get_current_user_id),
+    storage: StorageBase = Depends(get_storage),
+    workspace_manager: WorkspaceManagerBase = Depends(get_workspace_manager),
+    access: ResourceAccessService = Depends(get_resource_access_service),
+) -> CreateSessionResponse:
+    """Create (or resume) a session for a given agent and workspace.
+
+    At most one session exists per ``(user_id, agent_id, workspace_id)``
+    triple — a second call with the same triple updates the existing session
+    rather than creating a duplicate.
+
+    Args:
+        body (`CreateSessionRequest`): Agent, workspace, and model config.
+        user_id (`str`): Injected authenticated user ID.
+        storage (`StorageBase`): Injected storage backend.
+        workspace_manager (`WorkspaceManagerBase`): Injected workspace
+            manager; consulted via
+            :meth:`WorkspaceManagerBase.assign_workspace_id` to fill in
+            ``workspace_id`` when the request body omits it.
+        access (`ResourceAccessService`): Injected access service.
+
+    Returns:
+        `CreateSessionResponse`: The session identifier.
+
+    Raises:
+        `HTTPException`: 404 if the agent / credential / knowledge base
+            is not visible to the caller.
+    """
+    # Agent must be visible to the caller (own or shared).
+    await access.resolve_agent(user_id, body.agent_id)
+
+    await _ensure_credential_exists(access, user_id, body.chat_model_config)
+    await _ensure_credential_exists(
+        access,
+        user_id,
+        body.fallback_chat_model_config,
+    )
+    await _ensure_credential_exists(access, user_id, body.tts_model_config)
+    await _ensure_knowledge_bases_exist(
+        access,
+        user_id,
+        body.knowledge_config,
+    )
+
+    # Resolve the workspace binding for this session. Explicit
+    # ``body.workspace_id`` always wins (used by team invite / borrow
+    # flows to force sharing); otherwise defer to the manager's
+    # isolation policy — see ``WorkspaceManagerBase.assign_workspace_id``.
+    resolved_workspace_id = body.workspace_id or (
+        workspace_manager.assign_workspace_id(
+            user_id=user_id,
+            agent_id=body.agent_id,
+            session_id=_generate_id(),
+        )
+    )
+
+    session_record = await storage.upsert_session(
+        user_id=user_id,
+        agent_id=body.agent_id,
+        config=SessionConfig(
+            workspace_id=resolved_workspace_id,
+            chat_model_config=body.chat_model_config,
+            fallback_chat_model_config=body.fallback_chat_model_config,
+            tts_model_config=body.tts_model_config,
+            knowledge_config=body.knowledge_config,
+            **({"name": body.name} if body.name is not None else {}),
+        ),
+    )
+    return CreateSessionResponse(session_id=session_record.id)
+
+
+@session_router.delete(
+    "/{session_id}",
+    status_code=status.HTTP_204_NO_CONTENT,
+    summary="Delete a session",
+)
+async def delete_session(
+    session_id: str,
+    agent_id: str = Query(description="Agent the session belongs to."),
+    user_id: str = Depends(get_current_user_id),
+    session_service: SessionService = Depends(get_session_service),
+) -> None:
+    """Permanently delete a session and all its associated state.
+
+    Cancels any in-flight chat run for this session (and for every
+    worker session if this one is a team leader) before dropping
+    storage records and bus state. The cancel path is cross-process:
+    whichever worker is actually running the session will receive the
+    cancel broadcast and abort.
+
+    Args:
+        session_id (`str`): The session to delete.
+        agent_id (`str`): The agent the session belongs to.
+        user_id (`str`): Injected authenticated user ID.
+        session_service (`SessionService`): Injected session service.
+
+    Raises:
+        `HTTPException`: 404 if the session does not exist or does not belong
+            to the authenticated user.
+    """
+    deleted = await session_service.delete_session(
+        user_id,
+        agent_id,
+        session_id,
+    )
+    if not deleted:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Session '{session_id}' not found.",
+        )
+
+
+@session_router.post(
+    "/{session_id}/interrupt",
+    status_code=status.HTTP_202_ACCEPTED,
+    summary="Interrupt a running or HITL-parked chat run for a session",
+    responses={
+        404: {"description": "Session not found."},
+    },
+)
+async def interrupt_session(
+    session_id: str,
+    agent_id: str = Query(description="Agent the session belongs to."),
+    user_id: str = Depends(get_current_user_id),
+    chat_service: ChatService = Depends(get_chat_service),
+) -> InterruptSessionResponse:
+    """Request interruption of an in-progress reply for a session.
+
+    Thin HTTP wrapper around :meth:`ChatService.interrupt`; see that
+    method for the running vs not-running dispatch. Idempotent — an
+    idle target session is a silent no-op at the agent layer.
+
+    Args:
+        session_id: The session whose reply should be interrupted.
+        agent_id: The agent that owns the session.
+        user_id: Injected authenticated user id.
+        chat_service: Injected chat service.
+
+    Returns:
+        202 with :class:`InterruptSessionResponse` echoing the
+        session id.
+
+    Raises:
+        HTTPException: 404 if the session does not exist.
+    """
+    try:
+        await chat_service.interrupt(user_id, session_id, agent_id)
+    except LookupError as e:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=str(e),
+        ) from e
+    return InterruptSessionResponse(session_id=session_id)
+
+
+@session_router.patch(
+    "/{session_id}",
+    response_model=SessionRecord,
+    summary="Update a session",
+)
+async def update_session(
+    session_id: str,
+    body: UpdateSessionRequest,
+    agent_id: str = Query(description="Agent the session belongs to."),
+    user_id: str = Depends(get_current_user_id),
+    storage: StorageBase = Depends(get_storage),
+    access: ResourceAccessService = Depends(get_resource_access_service),
+) -> SessionRecord:
+    """Update the model configuration of an existing session.
+
+    Args:
+        session_id (`str`): The session to update.
+        body (`UpdateSessionRequest`): Fields to update.
+        user_id (`str`): Injected authenticated user ID.
+        storage (`StorageBase`): Injected storage backend.
+        access (`ResourceAccessService`): Injected access service.
+
+    Returns:
+        `SessionRecord`: The full session record after the update.
+
+    Raises:
+        `HTTPException`: 404 if the session does not exist, or if the
+            referenced credential / KB is not visible to the caller.
+    """
+    existing = await storage.get_session(user_id, agent_id, session_id)
+    if existing is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Session '{session_id}' not found.",
+        )
+
+    await _ensure_credential_exists(access, user_id, body.chat_model_config)
+    await _ensure_credential_exists(
+        access,
+        user_id,
+        body.fallback_chat_model_config,
+    )
+    await _ensure_credential_exists(access, user_id, body.tts_model_config)
+    await _ensure_knowledge_bases_exist(
+        access,
+        user_id,
+        body.knowledge_config,
+    )
+
+    updated_state = existing.state
+    if body.permission_mode is not None:
+        updated_ctx = existing.state.permission_context.model_copy(
+            update={"mode": body.permission_mode},
+        )
+
+        updated_state = existing.state.model_copy(
+            update={
+                "permission_context": updated_ctx,
+            },
+        )
+
+    # PATCH semantics: only fields explicitly present in the request body are
+    # applied. ``exclude_unset=True`` lets clients distinguish "leave
+    # unchanged" (omit) from "clear" (send ``null``) — required for clearing
+    # ``fallback_chat_model_config``.
+    config_updates = body.model_dump(
+        exclude_unset=True,
+        exclude={"permission_mode"},
+    )
+
+    return await storage.upsert_session(
+        user_id=user_id,
+        agent_id=agent_id,
+        config=SessionConfig.model_validate(
+            {**existing.config.model_dump(mode="json"), **config_updates},
+        ),
+        state=updated_state,
+        session_id=session_id,
+    )
+
+
+# ----------------------------------------------------------------------
+# Messages: fetch persisted messages for a session
+# ----------------------------------------------------------------------
+
+
+@session_router.get(
+    "/{session_id}/messages",
+    response_model=ListMessagesResponse,
+    summary="List messages for a session",
+)
+async def list_messages(
+    session_id: str,
+    agent_id: str = Query(description="Agent the session belongs to."),
+    offset: int = Query(0, ge=0, description="Pagination offset."),
+    limit: int = Query(50, ge=1, le=200, description="Max messages."),
+    user_id: str = Depends(get_current_user_id),
+    storage: StorageBase = Depends(get_storage),
+    message_bus: MessageBus = Depends(get_message_bus),
+) -> ListMessagesResponse:
+    """Return persisted messages for a session.
+
+    Args:
+        session_id: The session to query.
+        agent_id: Agent the session belongs to.
+        offset: Pagination offset.
+        limit: Maximum number of messages to return.
+        user_id: Injected authenticated user ID.
+        storage: Injected storage backend.
+        message_bus: Injected message bus.
+
+    Returns:
+        Messages and running status.
+    """
+    existing = await storage.get_session(user_id, agent_id, session_id)
+    if existing is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Session '{session_id}' not found.",
+        )
+
+    messages = await storage.list_messages(
+        user_id,
+        session_id,
+        offset=offset,
+        limit=limit,
+    )
+    return ListMessagesResponse(
+        messages=messages,
+        is_running=await message_bus.is_locked(
+            MessageBusKeys.session_lock(session_id),
+        ),
+    )
+
+
+# ----------------------------------------------------------------------
+# Status probe: unified session status (cluster liveness + parking state)
+# ----------------------------------------------------------------------
+
+
+@session_router.get(
+    "/{session_id}/status",
+    response_model=SessionStatusResponse,
+    summary="Probe the session's high-level status",
+)
+async def get_session_status(
+    session_id: str,
+    agent_id: str = Query(description="Agent the session belongs to."),
+    user_id: str = Depends(get_current_user_id),
+    session_service: SessionService = Depends(get_session_service),
+) -> SessionStatusResponse:
+    """Return the unified :class:`SessionStatus` for a session.
+
+    Ownership validation, cluster-liveness probing, and parked-state
+    derivation are all delegated to
+    :meth:`SessionService.get_session_status` — see that method for
+    the precedence rules that collapse the two orthogonal signals
+    (message-bus run lock + persisted context tail) into a single
+    four-valued enum.
+
+    Args:
+        session_id (`str`):
+            The session to probe.
+        agent_id (`str`):
+            The agent that owns the session (ownership validation).
+        user_id (`str`):
+            Injected authenticated user ID.
+        session_service (`SessionService`):
+            Injected session service. Owns both storage and message
+            bus dependencies so the composed answer is derived in a
+            single layer.
+
+    Returns:
+        `SessionStatusResponse`:
+            The probed session id and its unified status.
+
+    Raises:
+        `HTTPException`: 404 if the session does not exist or does not
+            belong to the authenticated user.
+    """
+    session_status = await session_service.get_session_status(
+        user_id,
+        agent_id,
+        session_id,
+    )
+    if session_status is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Session '{session_id}' not found.",
+        )
+    return SessionStatusResponse(
+        session_id=session_id,
+        status=session_status,
+    )
+
+
+# ----------------------------------------------------------------------
+# Stream: live SSE connection for session events
+# ----------------------------------------------------------------------
+
+_HEARTBEAT_INTERVAL_SECS = 30
+# Interval between SSE heartbeat comment frames (``:\\n\\n``).
+
+
+async def _worker_still_asking(
+    storage: StorageBase,
+    user_id: str,
+    worker_agent_id: str,
+    worker_session_id: str,
+    reply_id: str,
+) -> bool:
+    """Return whether a worker session is still parked on the ASKING
+    tool call identified by ``reply_id``.
+
+    This is the reconcile-on-read check (design §3.5): the worker
+    session's own ``state.context`` is the single source of truth for
+    "does this confirmation still need answering". A leader-side
+    pending projection whose worker has already resolved / cancelled
+    the call is a ghost and must not be replayed.
+
+    Mirrors the wakeup guard in
+    :meth:`ChatService._run_impl` — a request is "still asking" when
+    the tail ``AssistantMsg`` of the worker carries a tool call in
+    ``ASKING`` or ``SUBMITTED`` state for the matching ``reply_id``.
+
+    Args:
+        storage (`StorageBase`):
+            Application storage.
+        user_id (`str`):
+            The owner user id.
+        worker_agent_id (`str`):
+            The worker agent that owns the session.
+        worker_session_id (`str`):
+            The worker session to inspect.
+        reply_id (`str`):
+            The reply id the pending request belongs to.
+
+    Returns:
+        `bool`:
+            ``True`` if the worker is still awaiting confirmation for
+            ``reply_id``; ``False`` otherwise (resolved, cancelled, or
+            the session/record is gone).
+    """
+    session = await storage.get_session(
+        user_id,
+        worker_agent_id,
+        worker_session_id,
+    )
+    if session is None or not session.state.context:
+        return False
+    last_msg = session.state.context[-1]
+    if last_msg.role != "assistant" or last_msg.id != reply_id:
+        return False
+    return any(
+        tc.state in (ToolCallState.ASKING, ToolCallState.SUBMITTED)
+        for tc in last_msg.get_content_blocks("tool_call")
+    )
+
+
+@session_router.get(
+    "/{session_id}/stream",
+    summary="Subscribe to a session's event stream (SSE)",
+    response_description="Server-Sent Events stream of AgentEvent objects",
+)
+async def stream_session_events(
+    session_id: str,
+    agent_id: str = Query(description="Agent the session belongs to."),
+    user_id: str = Depends(get_current_user_id),
+    storage: StorageBase = Depends(get_storage),
+    message_bus: MessageBus = Depends(get_message_bus),
+) -> StreamingResponse:
+    """Subscribe to a session's live event stream.
+
+    Returns a ``text/event-stream`` that first replays any buffered
+    events from the current run's replay log (if a run is in progress
+    or just finished), then streams live events as they are produced
+    by :meth:`ChatService.run`. The connection stays open
+    until the client disconnects — subsequent runs on the same session
+    are delivered over the same connection.
+
+    A heartbeat comment frame (``:\\n\\n``) is sent every 30 seconds to
+    keep the connection alive through reverse proxies.
+
+    Args:
+        session_id (`str`):
+            The session to subscribe to.
+        agent_id (`str`):
+            The agent that owns the session (used for ownership
+            validation).
+        user_id (`str`):
+            Injected authenticated user id.
+        storage (`StorageBase`):
+            Injected storage backend (ownership check only).
+        message_bus (`MessageBus`):
+            Injected message bus (replay + live subscription).
+
+    Returns:
+        `StreamingResponse`:
+            SSE stream of AgentEvent frames + periodic heartbeats.
+    """
+    existing = await storage.get_session(user_id, agent_id, session_id)
+    if existing is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Session '{session_id}' not found.",
+        )
+
+    async def _sse_generator() -> AsyncGenerator[str, None]:
+        # 1. Replay buffered events from the current run (if any).
+        for _entry_id, event in await message_bus.log_read(
+            MessageBusKeys.session_events(session_id),
+            max_count=MessageBusKeys.SESSION_REPLAY_MAX_LEN,
+        ):
+            yield f"data: {json.dumps(event, ensure_ascii=False)}\n\n"
+
+        # 1b. Inject pending subagent HITL cards projected onto this
+        #     session as a team leader (design §3.5). These live in a
+        #     durable Redis hash — NOT in the replay log (trimmed per
+        #     run) nor in the leader's own Msg history — so a fresh
+        #     reconnect after the worker parked still surfaces them.
+        #
+        #     Reconcile-on-read: the worker session's own context is the
+        #     SSOT. Inject only when the worker is still ASKING; drop and
+        #     delete ghosts (worker resolved/cancelled without clearing).
+        projection = SessionProjection(message_bus)
+        for payload in await projection.list(
+            session_id,
+            SubagentHitlProjector.KIND,
+        ):
+            if not await _worker_still_asking(
+                storage,
+                user_id,
+                payload["worker_agent_id"],
+                payload["worker_session_id"],
+                payload["reply_id"],
+            ):
+                await projection.delete(
+                    session_id,
+                    SubagentHitlProjector.KIND,
+                    SubagentHitlProjector.entry_id(
+                        payload["worker_session_id"],
+                        payload["reply_id"],
+                    ),
+                )
+                continue
+            custom = CustomEvent(
+                name=SubagentHitlProjector.EVT_REQUIRE,
+                value=payload,
+            )
+            data = json.dumps(
+                custom.model_dump(mode="json"),
+                ensure_ascii=False,
+            )
+
+            yield f"data: {data}\n\n"
+
+        # 2. Live subscribe via a background feeder task that pushes
+        #    events into a queue. The main loop reads from the queue
+        #    with a timeout so we can interleave heartbeat frames.
+        #
+        #    We avoid calling ``wait_for(__anext__())`` on the async
+        #    generator directly because cancelling a suspended
+        #    ``__anext__`` leaves the generator in a "running" state
+        #    that prevents ``aclose()`` from working.
+        queue: asyncio.Queue[dict | None] = asyncio.Queue()
+
+        async def _feeder() -> None:
+            """Read from the bus subscription and forward to the queue.
+
+            Pushes ``None`` as a sentinel when the subscription ends
+            (which in practice only happens if the bus shuts down).
+            """
+            try:
+                async for evt in message_bus.subscribe(
+                    MessageBusKeys.session_events(session_id),
+                ):
+                    await queue.put(
+                        {k: v for k, v in evt.items() if k != "_entry_id"},
+                    )
+            except asyncio.CancelledError:
+                pass
+            finally:
+                await queue.put(None)
+
+        feeder_task = asyncio.create_task(
+            _feeder(),
+            name=f"sse-feeder:{session_id}",
+        )
+
+        try:
+            while True:
+                try:
+                    item = await asyncio.wait_for(
+                        queue.get(),
+                        timeout=_HEARTBEAT_INTERVAL_SECS,
+                    )
+                    if item is None:
+                        break
+                    yield f"data: {json.dumps(item, ensure_ascii=False)}\n\n"
+                except asyncio.TimeoutError:
+                    yield ":\n\n"
+        finally:
+            feeder_task.cancel()
+            try:
+                await feeder_task
+            except asyncio.CancelledError:
+                pass
+
+    return StreamingResponse(
+        _sse_generator(),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "X-Accel-Buffering": "no",
+        },
+    )
diff --git a/src/agentscope/app/_router/_tts_model.py b/src/agentscope/app/_router/_tts_model.py
new file mode 100644
index 0000000..949388c
--- /dev/null
+++ b/src/agentscope/app/_router/_tts_model.py
@@ -0,0 +1,40 @@
+# -*- coding: utf-8 -*-
+"""The TTS model router."""
+
+from fastapi import APIRouter, Depends, HTTPException, status
+
+from ._schema import ListTTSModelsResponse, ListTTSModelsRequest
+from ...credential import CredentialFactory
+
+tts_model_router = APIRouter(
+    prefix="/tts-model",
+    tags=["tts-model"],
+    responses={404: {"description": "Not found"}},
+)
+
+
+@tts_model_router.get(
+    "/",
+    response_model=ListTTSModelsResponse,
+    summary="List all candidate TTS models under the given credential type",
+)
+async def list_tts_models(
+    body: ListTTSModelsRequest = Depends(),
+) -> ListTTSModelsResponse:
+    """Return all candidate TTS models under the given credential type.
+
+    Args:
+        body (ListTTSModelsRequest): The request body.
+
+    Returns:
+        `ListTTSModelsResponse`: The response body.
+    """
+    credential_cls = CredentialFactory.get_credential_class(body.provider)
+    if credential_cls is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Provider '{body.provider}' not found.",
+        )
+
+    models = credential_cls.list_tts_models()
+    return ListTTSModelsResponse(models=models, total=len(models))
diff --git a/src/agentscope/app/_router/_workspace.py b/src/agentscope/app/_router/_workspace.py
new file mode 100644
index 0000000..eb3236c
--- /dev/null
+++ b/src/agentscope/app/_router/_workspace.py
@@ -0,0 +1,220 @@
+# -*- coding: utf-8 -*-
+"""Workspace router — manage MCP clients and skills on a workspace."""
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+from pydantic import BaseModel, Field
+
+from ..deps import (
+    get_current_user_id,
+    get_storage,
+    get_workspace_manager,
+)
+from ..workspace_manager import WorkspaceManagerBase
+from ..storage import StorageBase
+from ...mcp import MCPClient
+from ...skill import Skill
+from ...workspace import WorkspaceBase
+
+workspace_router = APIRouter(prefix="/workspace", tags=["workspace"])
+
+
+class AddSkillRequest(BaseModel):
+    """The request to add skill."""
+
+    skill_path: str
+
+
+class ToolInfo(BaseModel):
+    """The tool info."""
+
+    name: str
+    description: str | None = None
+
+
+class MCPClientStatus(MCPClient):
+    """MCPClient enriched with live tool list and health status."""
+
+    is_healthy: bool = False
+    tools: list[ToolInfo] = Field(default_factory=list)
+
+
+async def _resolve_workspace(
+    user_id: str,
+    agent_id: str,
+    session_id: str,
+    storage: StorageBase,
+    workspace_manager: WorkspaceManagerBase,
+) -> WorkspaceBase:
+    """Resolve the workspace for the given session, raising 404 if not
+    found."""
+    session_record = await storage.get_session(user_id, agent_id, session_id)
+    if session_record is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Session {session_id!r} not found.",
+        )
+    return await workspace_manager.get_workspace(
+        user_id,
+        agent_id,
+        session_id,
+        session_record.config.workspace_id,
+    )
+
+
+# ---------------------------------------------------------------------------
+# MCP endpoints
+# ---------------------------------------------------------------------------
+
+
+@workspace_router.get("/mcp")
+async def list_mcps(
+    agent_id: str = Query(...),
+    session_id: str = Query(...),
+    user_id: str = Depends(get_current_user_id),
+    storage: StorageBase = Depends(get_storage),
+    workspace_manager: WorkspaceManagerBase = Depends(get_workspace_manager),
+) -> list[MCPClientStatus]:
+    """Return all MCP clients with live tool list and health status."""
+    workspace = await _resolve_workspace(
+        user_id,
+        agent_id,
+        session_id,
+        storage,
+        workspace_manager,
+    )
+    clients = await workspace.list_mcps()
+
+    results = []
+    for client in clients:
+        base = client.model_dump()
+        try:
+            mcp_tools = await client.list_tools()
+            tools = [
+                ToolInfo(name=t.name, description=t.description)
+                for t in mcp_tools
+            ]
+            results.append(
+                MCPClientStatus(
+                    **base,
+                    is_healthy=True,
+                    tools=tools,
+                ),
+            )
+        except Exception:
+            results.append(
+                MCPClientStatus(
+                    **base,
+                    is_healthy=False,
+                ),
+            )
+
+    return results
+
+
+@workspace_router.post("/mcp", status_code=status.HTTP_201_CREATED)
+async def add_mcp(
+    mcp: MCPClient,
+    agent_id: str = Query(...),
+    session_id: str = Query(...),
+    user_id: str = Depends(get_current_user_id),
+    storage: StorageBase = Depends(get_storage),
+    workspace_manager: WorkspaceManagerBase = Depends(get_workspace_manager),
+) -> None:
+    """Add an MCP client to the session's workspace."""
+    workspace = await _resolve_workspace(
+        user_id,
+        agent_id,
+        session_id,
+        storage,
+        workspace_manager,
+    )
+    await workspace.add_mcp(mcp)
+
+
+@workspace_router.delete(
+    "/mcp/{mcp_name}",
+    status_code=status.HTTP_204_NO_CONTENT,
+)
+async def remove_mcp(
+    mcp_name: str,
+    agent_id: str = Query(...),
+    session_id: str = Query(...),
+    user_id: str = Depends(get_current_user_id),
+    storage: StorageBase = Depends(get_storage),
+    workspace_manager: WorkspaceManagerBase = Depends(get_workspace_manager),
+) -> None:
+    """Remove an MCP client from the session's workspace by name."""
+    workspace = await _resolve_workspace(
+        user_id,
+        agent_id,
+        session_id,
+        storage,
+        workspace_manager,
+    )
+    await workspace.remove_mcp(mcp_name)
+
+
+# ---------------------------------------------------------------------------
+# Skill endpoints
+# ---------------------------------------------------------------------------
+
+
+@workspace_router.get("/skill")
+async def list_skills(
+    agent_id: str = Query(...),
+    session_id: str = Query(...),
+    user_id: str = Depends(get_current_user_id),
+    storage: StorageBase = Depends(get_storage),
+    workspace_manager: WorkspaceManagerBase = Depends(get_workspace_manager),
+) -> list[Skill]:
+    """Return all skills available in the session's workspace."""
+    workspace = await _resolve_workspace(
+        user_id,
+        agent_id,
+        session_id,
+        storage,
+        workspace_manager,
+    )
+    return await workspace.list_skills()
+
+
+@workspace_router.post("/skill", status_code=status.HTTP_201_CREATED)
+async def add_skill(
+    body: AddSkillRequest,
+    agent_id: str = Query(...),
+    session_id: str = Query(...),
+    user_id: str = Depends(get_current_user_id),
+    storage: StorageBase = Depends(get_storage),
+    workspace_manager: WorkspaceManagerBase = Depends(get_workspace_manager),
+) -> None:
+    """Add a skill to the session's workspace from the given path."""
+    workspace = await _resolve_workspace(
+        user_id,
+        agent_id,
+        session_id,
+        storage,
+        workspace_manager,
+    )
+    await workspace.add_skill(body.skill_path)
+
+
+@workspace_router.delete(
+    "/skill/{skill_name}",
+    status_code=status.HTTP_204_NO_CONTENT,
+)
+async def remove_skill(
+    skill_name: str,
+    agent_id: str = Query(...),
+    session_id: str = Query(...),
+    user_id: str = Depends(get_current_user_id),
+    storage: StorageBase = Depends(get_storage),
+    workspace_manager: WorkspaceManagerBase = Depends(get_workspace_manager),
+) -> None:
+    """Remove a skill from the session's workspace by name."""
+    workspace = await _resolve_workspace(
+        user_id,
+        agent_id,
+        session_id,
+        storage,
+        workspace_manager,
+    )
+    await workspace.remove_skill(skill_name)
diff --git a/src/agentscope/app/_service/__init__.py b/src/agentscope/app/_service/__init__.py
new file mode 100644
index 0000000..2d66483
--- /dev/null
+++ b/src/agentscope/app/_service/__init__.py
@@ -0,0 +1,40 @@
+# -*- coding: utf-8 -*-
+"""Service layer for the AgentScope app."""
+from ._access import (
+    AgentView,
+    CredentialView,
+    KnowledgeBaseView,
+    ResourceAccessService,
+)
+from ._chat import ChatService
+from ._embedding import get_embedding_model
+from ._index_sweeper import IndexSweeper
+from ._index_task_consumer import IndexTaskConsumer
+from ._index_worker import IndexWorker
+from ._knowledge_base import KnowledgeBaseService
+from ._model import get_model
+from ._tts_model import get_tts_model
+from ._session import SessionService, SessionStatus
+from ._session_projection import SessionProjection
+from ._projectors import SubagentHitlProjector
+from ._toolkit import get_toolkit
+
+__all__ = [
+    "AgentView",
+    "ChatService",
+    "CredentialView",
+    "IndexSweeper",
+    "IndexTaskConsumer",
+    "IndexWorker",
+    "KnowledgeBaseService",
+    "KnowledgeBaseView",
+    "ResourceAccessService",
+    "SessionService",
+    "SessionStatus",
+    "SessionProjection",
+    "SubagentHitlProjector",
+    "get_embedding_model",
+    "get_model",
+    "get_tts_model",
+    "get_toolkit",
+]
diff --git a/src/agentscope/app/_service/_access.py b/src/agentscope/app/_service/_access.py
new file mode 100644
index 0000000..8026ba4
--- /dev/null
+++ b/src/agentscope/app/_service/_access.py
@@ -0,0 +1,473 @@
+# -*- coding: utf-8 -*-
+"""Resource access service — cross-owner reads with viewer-relative views."""
+from __future__ import annotations
+
+from typing import Any, Literal, TypeVar, overload
+
+from fastapi import HTTPException, status
+from pydantic import BaseModel, Field
+
+from ..access import (
+    ResourceAccessPolicyBase,
+    ResourceKind,
+    ResourcePermission,
+    ResourceRef,
+)
+from ..storage import (
+    AgentRecord,
+    CredentialRecord,
+    KnowledgeBaseRecord,
+    StorageBase,
+)
+
+
+# ---------------------------------------------------------------------
+# Views — viewer-relative projections of storage records.
+# ---------------------------------------------------------------------
+
+
+class AgentView(AgentRecord):
+    """Agent record + viewer-relative ``editable``.
+
+    Subclasses :class:`AgentRecord` so the wire format is a strict
+    superset of the historical response (one extra top-level field);
+    old clients ignore ``editable`` transparently.
+    """
+
+    editable: bool = Field(
+        description=(
+            "Whether the current viewer may PATCH/DELETE this agent."
+        ),
+    )
+
+
+class CredentialView(CredentialRecord):
+    """Credential record + viewer-relative ``editable``.
+
+    ``data`` inherits :class:`CredentialRecord.data` in shape, but the
+    service masks it for shared credentials before constructing the
+    view: only ``type`` and ``name`` survive. Runtime paths that need
+    the raw payload call :meth:`ResourceAccessService.resolve_credential`
+    instead, which returns the underlying record.
+    """
+
+    editable: bool = Field(
+        description=(
+            "Whether the current viewer may PATCH/DELETE this credential."
+        ),
+    )
+
+
+class KnowledgeBaseView(KnowledgeBaseRecord):
+    """Knowledge base record + viewer-relative ``editable``.
+
+    Subclasses :class:`KnowledgeBaseRecord` so the wire format is a
+    strict superset of the record (one extra top-level field), matching
+    :class:`AgentView` and :class:`CredentialView`.
+    """
+
+    editable: bool = Field(
+        description=(
+            "Whether the current viewer may modify this knowledge base."
+        ),
+    )
+
+
+# ---------------------------------------------------------------------
+# Service
+# ---------------------------------------------------------------------
+
+
+_T = TypeVar("_T", bound=BaseModel)
+
+
+class ResourceAccessService:
+    """Resolve resources visible to a viewer.
+
+    Combines owner-scoped storage reads with cross-owner refs from
+    :class:`ResourceAccessPolicyBase`. Routers use it for list/get and
+    edit checks; runtime services use it to resolve shared credentials,
+    agents, and knowledge bases without depending on FastAPI dependencies.
+    """
+
+    def __init__(
+        self,
+        storage: StorageBase,
+        policy: ResourceAccessPolicyBase,
+    ) -> None:
+        """Initialize the service.
+
+        Args:
+            storage: Owner-scoped storage backend.
+            policy: Cross-owner access policy.
+        """
+        self._storage = storage
+        self._policy = policy
+
+    # ------------------------------------------------------------------
+    # list_resource
+    # ------------------------------------------------------------------
+
+    @overload
+    async def list_resource(
+        self,
+        viewer_id: str,
+        kind: Literal[ResourceKind.CREDENTIAL],
+    ) -> list[CredentialView]:
+        ...
+
+    @overload
+    async def list_resource(
+        self,
+        viewer_id: str,
+        kind: Literal[ResourceKind.AGENT],
+    ) -> list[AgentView]:
+        ...
+
+    @overload
+    async def list_resource(
+        self,
+        viewer_id: str,
+        kind: Literal[ResourceKind.KNOWLEDGE_BASE],
+    ) -> list[KnowledgeBaseView]:
+        ...
+
+    async def list_resource(
+        self,
+        viewer_id: str,
+        kind: ResourceKind,
+    ) -> list[BaseModel]:
+        """List resources of ``kind`` visible to ``viewer_id``.
+
+        The result merges the viewer's own records (always ``editable``)
+        with any cross-owner records granted by
+        :class:`ResourceAccessPolicyBase`. Credentials shared to the
+        viewer have their ``data`` payload masked in the view;
+        :meth:`resolve_credential` should be used when the raw payload
+        is required for runtime provider calls.
+        """
+        if kind is ResourceKind.CREDENTIAL:
+            own = await self._storage.list_credentials(viewer_id)
+        elif kind is ResourceKind.AGENT:
+            own = [
+                record
+                for record in await self._storage.list_agents(viewer_id)
+                if record.source != "team"
+            ]
+        else:
+            own = await self._storage.list_knowledge_bases(viewer_id)
+
+        views: list[BaseModel] = [
+            self._build_view(record, viewer_id, True) for record in own
+        ]
+        seen = {(record.user_id, record.id) for record in own}
+
+        for ref in await self._list_refs(viewer_id, kind):
+            key = (ref.owner_id, ref.resource_id)
+            if key in seen:
+                continue
+            record = await self._get_owned(
+                kind,
+                ref.owner_id,
+                ref.resource_id,
+            )
+            if record is None:
+                continue
+            # Team workers are not shareable; owner reads still see them
+            # via ``resolve_agent`` (used by ChatService).
+            if isinstance(record, AgentRecord) and record.source == "team":
+                continue
+            views.append(
+                self._build_view(
+                    record,
+                    viewer_id,
+                    ref.permission == ResourcePermission.EDIT,
+                ),
+            )
+            seen.add(key)
+        return views
+
+    # ------------------------------------------------------------------
+    # get_resource
+    # ------------------------------------------------------------------
+
+    @overload
+    async def get_resource(
+        self,
+        viewer_id: str,
+        kind: Literal[ResourceKind.CREDENTIAL],
+        resource_id: str,
+    ) -> CredentialView:
+        ...
+
+    @overload
+    async def get_resource(
+        self,
+        viewer_id: str,
+        kind: Literal[ResourceKind.AGENT],
+        resource_id: str,
+    ) -> AgentView:
+        ...
+
+    @overload
+    async def get_resource(
+        self,
+        viewer_id: str,
+        kind: Literal[ResourceKind.KNOWLEDGE_BASE],
+        resource_id: str,
+    ) -> KnowledgeBaseView:
+        ...
+
+    async def get_resource(
+        self,
+        viewer_id: str,
+        kind: ResourceKind,
+        resource_id: str,
+    ) -> BaseModel:
+        """Get a visible resource by id or raise ``404``.
+
+        Returns the viewer-relative view so the caller does not have to
+        query editability separately (see the KB detail-page case). For
+        the viewer's own resource the view is derived directly from
+        storage; for a shared resource the policy ref supplies the
+        ``permission`` used to compute ``editable``. Credential ``data``
+        is masked for shared entries — use :meth:`resolve_credential`
+        for runtime provider calls.
+        """
+        own = await self._get_owned(kind, viewer_id, resource_id)
+        if own is not None:
+            # Owner-side reads bypass the ``team`` filter on purpose:
+            # runtime paths legitimately load the owner's ``source ==
+            # "team"`` agents, and we want a single call site.
+            return self._build_view(own, viewer_id, True)
+
+        for ref in await self._list_refs(viewer_id, kind):
+            if ref.resource_id != resource_id:
+                continue
+            record = await self._get_owned(
+                kind,
+                ref.owner_id,
+                ref.resource_id,
+            )
+            if record is None:
+                continue
+            if isinstance(record, AgentRecord) and record.source == "team":
+                continue
+            return self._build_view(
+                record,
+                viewer_id,
+                ref.permission == ResourcePermission.EDIT,
+            )
+        raise self._not_found(kind, resource_id)
+
+    # ------------------------------------------------------------------
+    # Runtime-only helpers
+    # ------------------------------------------------------------------
+
+    async def resolve_credential(
+        self,
+        viewer_id: str,
+        credential_id: str,
+    ) -> CredentialRecord:
+        """Resolve a credential for runtime use — returns the raw record.
+
+        Unlike :meth:`get_resource`, the returned record is NOT masked:
+        the caller is expected to feed the ``data`` payload into a
+        provider client. Restrict use to trusted runtime paths
+        (chat / embedding / TTS model construction).
+        """
+        record = await self._storage.get_credential(viewer_id, credential_id)
+        if record is not None:
+            return record
+
+        for ref in await self._list_refs(viewer_id, ResourceKind.CREDENTIAL):
+            if ref.resource_id != credential_id:
+                continue
+            record = await self._storage.get_credential(
+                ref.owner_id,
+                ref.resource_id,
+            )
+            if record is not None:
+                return record
+        raise self._not_found(ResourceKind.CREDENTIAL, credential_id)
+
+    async def resolve_agent(
+        self,
+        viewer_id: str,
+        agent_id: str,
+    ) -> AgentRecord:
+        """Resolve an agent for runtime use — returns the raw record.
+
+        Owner reads include team workers (needed by ChatService when
+        running a worker session); cross-owner refs only resolve
+        ``source == "user"`` agents since team workers are not
+        shareable.
+        """
+        record = await self._storage.get_agent(viewer_id, agent_id)
+        if record is not None:
+            return record
+
+        for ref in await self._list_refs(viewer_id, ResourceKind.AGENT):
+            if ref.resource_id != agent_id:
+                continue
+            record = await self._storage.get_agent(
+                ref.owner_id,
+                ref.resource_id,
+            )
+            if record is not None and record.source != "team":
+                return record
+        raise self._not_found(ResourceKind.AGENT, agent_id)
+
+    async def resolve_knowledge_base(
+        self,
+        viewer_id: str,
+        knowledge_base_id: str,
+    ) -> KnowledgeBaseRecord:
+        """Resolve a knowledge base for runtime use — returns the raw
+        record. Used by the RAG middleware and the KB service to look
+        up the vector-store collection tied to a shared KB."""
+        record = await self._storage.get_knowledge_base(
+            viewer_id,
+            knowledge_base_id,
+        )
+        if record is not None:
+            return record
+
+        for ref in await self._list_refs(
+            viewer_id,
+            ResourceKind.KNOWLEDGE_BASE,
+        ):
+            if ref.resource_id != knowledge_base_id:
+                continue
+            record = await self._storage.get_knowledge_base(
+                ref.owner_id,
+                ref.resource_id,
+            )
+            if record is not None:
+                return record
+        raise self._not_found(
+            ResourceKind.KNOWLEDGE_BASE,
+            knowledge_base_id,
+        )
+
+    # ------------------------------------------------------------------
+    # Edit resolution
+    # ------------------------------------------------------------------
+
+    async def resolve_for_edit(
+        self,
+        viewer_id: str,
+        kind: ResourceKind,
+        resource_id: str,
+    ) -> tuple[str, Any]:
+        """Resolve ``(owner_id, record)`` for a mutation.
+
+        Routers use this before PATCH/DELETE to keep the resource_id
+        aware of shared editors: an owner writes under their own
+        user_id, but a shared editor writes back through the owning
+        user's storage key. The returned ``record`` is the raw storage
+        record (not a masked view) so callers can inspect and modify
+        it before persisting.
+
+        Raises:
+            HTTPException:
+                * 404 if the resource is not visible to ``viewer_id``
+                  (matches the historical owner-only 404).
+                * 403 if the resource is visible but ``viewer_id`` only
+                  has ``READ`` permission on it.
+        """
+        own = await self._get_owned(kind, viewer_id, resource_id)
+        if own is not None:
+            return viewer_id, own
+
+        for ref in await self._list_refs(viewer_id, kind):
+            if ref.resource_id != resource_id:
+                continue
+            record = await self._get_owned(
+                kind,
+                ref.owner_id,
+                ref.resource_id,
+            )
+            if record is None:
+                continue
+            if isinstance(record, AgentRecord) and record.source == "team":
+                continue
+            if ref.permission != ResourcePermission.EDIT:
+                raise HTTPException(
+                    status_code=status.HTTP_403_FORBIDDEN,
+                    detail=(
+                        f"{kind.value.replace('_', ' ').title()} "
+                        f"'{resource_id}' is read-only for this viewer."
+                    ),
+                )
+            return ref.owner_id, record
+        raise self._not_found(kind, resource_id)
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    async def _get_owned(
+        self,
+        kind: ResourceKind,
+        owner_id: str,
+        resource_id: str,
+    ) -> Any:
+        """Owner-scoped read on the storage backend, dispatched by kind."""
+        if kind is ResourceKind.CREDENTIAL:
+            return await self._storage.get_credential(owner_id, resource_id)
+        if kind is ResourceKind.AGENT:
+            return await self._storage.get_agent(owner_id, resource_id)
+        return await self._storage.get_knowledge_base(owner_id, resource_id)
+
+    def _build_view(
+        self,
+        record: Any,
+        viewer_id: str,
+        editable: bool,
+    ) -> BaseModel:
+        """Project a raw storage record onto a viewer-relative view.
+
+        Credential ``data`` is masked when the viewer is not the owner
+        so the wire format never leaks the shared secret; other kinds
+        pass through unchanged apart from the added ``editable`` flag.
+        """
+        if isinstance(record, CredentialRecord):
+            payload = record.model_dump()
+            if record.user_id != viewer_id:
+                payload["data"] = {
+                    k: payload["data"][k]
+                    for k in ("type", "name")
+                    if k in payload["data"]
+                }
+            payload["editable"] = editable
+            return CredentialView.model_validate(payload)
+        if isinstance(record, AgentRecord):
+            return AgentView.model_validate(
+                {**record.model_dump(), "editable": editable},
+            )
+        return KnowledgeBaseView.model_validate(
+            {**record.model_dump(), "editable": editable},
+        )
+
+    async def _list_refs(
+        self,
+        viewer_id: str,
+        kind: ResourceKind,
+    ) -> list[ResourceRef]:
+        """Return policy refs for ``kind`` and drop mismatched refs."""
+        refs = await self._policy.list_accessible(
+            viewer_id,
+            kind,
+            self._storage,
+        )
+        return [ref for ref in refs if ref.kind == kind]
+
+    @staticmethod
+    def _not_found(kind: ResourceKind, resource_id: str) -> HTTPException:
+        """Build a consistent not-found exception for visible resources."""
+        label = kind.value.replace("_", " ")
+        return HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"{label.title()} '{resource_id}' not found.",
+        )
diff --git a/src/agentscope/app/_service/_chat.py b/src/agentscope/app/_service/_chat.py
new file mode 100644
index 0000000..8d93cff
--- /dev/null
+++ b/src/agentscope/app/_service/_chat.py
@@ -0,0 +1,690 @@
+# -*- coding: utf-8 -*-
+"""Chat service encapsulating agent execution + persistence logic.
+
+This is the single source of truth for running an agent against a
+session. Both the HTTP chat endpoint and the wakeup dispatcher call
+:meth:`ChatService.run`, guaranteeing identical message persistence,
+middleware wiring, and state handling.
+
+Events produced by the agent are not exposed back through this method
+— they are published to the message bus inside the run, and any client
+that wants them subscribes through the
+``GET /sessions/{sid}/stream`` SSE endpoint.
+"""
+import asyncio
+
+from fastapi import HTTPException
+
+from .._bus_ops import enqueue_run_trigger, publish_session_event
+from ..message_bus import MessageBus, MessageBusKeys
+from ..rag.knowledge_base_manager import KnowledgeBaseManagerBase
+from ..storage import StorageBase, AgentRecord, SessionRecord
+from .._manager import BackgroundTaskManager, SchedulerManager
+from ..workspace_manager import WorkspaceManagerBase
+from ..middleware import (
+    InboxMiddleware,
+    StateChangeMiddleware,
+    ToolOffloadMiddleware,
+)
+from ...middleware import TTSMiddleware, RAGMiddleware
+from ...rag import KnowledgeBase
+from .._types import (
+    AgentMiddlewareFactory,
+    AgentToolFactory,
+    EventProjector,
+    SubAgentTemplate,
+)
+from ._access import ResourceAccessService
+from ._model import get_model
+from ._tts_model import get_tts_model
+from ._toolkit import get_toolkit
+from ._session_projection import SessionProjection
+from ._projectors import SubagentHitlProjector
+
+from ..._logging import logger
+from ...agent import Agent, ModelConfig
+from ...event import (
+    AgentEvent,
+    ReplyStartEvent,
+    UserConfirmResultEvent,
+    ExternalExecutionResultEvent,
+    UserInterruptEvent,
+)
+from ...message import AssistantMsg, Msg, ToolCallState
+from ...permission import AdditionalWorkingDirectory
+
+
+class ChatService:
+    """Run an agent against a session, persisting input/reply messages
+    and updated agent state.
+
+    Shared by the HTTP chat endpoint and the wakeup dispatcher so both
+    paths go through identical validation, assembly, and persistence.
+
+    Session serialisation and event fan-out are both handled by the
+    :class:`MessageBus`: :meth:`bus.session_run` acquires a distributed
+    lock (guaranteeing at most one chat run per session across all
+    processes), and :meth:`bus.session_publish_event` writes each event
+    to both a replay log (for late-joining subscribers) and a live
+    Pub/Sub channel.
+    """
+
+    def __init__(
+        self,
+        storage: StorageBase,
+        workspace_manager: WorkspaceManagerBase,
+        scheduler_manager: SchedulerManager,
+        background_task_manager: BackgroundTaskManager,
+        message_bus: MessageBus,
+        resource_access_service: ResourceAccessService,
+        knowledge_base_manager: KnowledgeBaseManagerBase | None = None,
+        extra_agent_middlewares: AgentMiddlewareFactory | None = None,
+        extra_agent_tools: AgentToolFactory | None = None,
+        custom_subagent_templates: dict[str, SubAgentTemplate] | None = None,
+        custom_agent_cls: type[Agent] | None = None,
+        extra_projectors: list[EventProjector] | None = None,
+    ) -> None:
+        """Initialize chat service.
+
+        Args:
+            storage (`StorageBase`):
+                Application storage backend.
+            workspace_manager (`WorkspaceManagerBase`):
+                Provides per-session workspace (tools, MCPs, skills) used
+                during agent assembly.
+            scheduler_manager (`SchedulerManager`):
+                Application scheduler — passed through to
+                :func:`get_toolkit` so the agent toolkit gets the four
+                ``Schedule*`` tools.
+            background_task_manager (`BackgroundTaskManager`):
+                Tracks offloaded long-running tool tasks. Also provides
+                the :class:`ToolStop` tool through
+                :func:`get_toolkit`.
+            message_bus (`MessageBus`):
+                Application-wide message bus. Provides session-level
+                distributed locking (via :meth:`session_run`), event
+                replay + live fan-out (via :meth:`session_publish_event`),
+                and inbox delivery (via :class:`InboxMiddleware`).
+            resource_access_service (`ResourceAccessService`):
+                Resolves cross-owner resources at runtime. Agent
+                assembly and model / TTS construction all route
+                through this service so shared credentials, agents,
+                and knowledge bases work uniformly.
+            knowledge_base_manager (`KnowledgeBaseManagerBase | None`, \
+             optional):
+                The application's knowledge base manager.  When
+                provided and the session config carries a
+                ``knowledge_config``, a
+                :class:`~agentscope.middleware.RAGMiddleware`
+                is attached to the agent at run time.  ``None``
+                disables knowledge-base wiring even for sessions that
+                have one configured.
+            extra_agent_middlewares (`AgentMiddlewareFactory | None`, \
+             optional):
+                Async factory invoked at every chat turn to produce
+                user/session-specific middlewares to attach to the agent.
+            extra_agent_tools (`AgentToolFactory | None`, optional):
+                Async factory invoked at every chat turn to produce
+                user/session-specific tools to register in the toolkit.
+            custom_subagent_templates (`dict[str, SubAgentTemplate] | None`,\
+             optional):
+                Sub-agent template registry, keyed by template type.
+                Passed through to :func:`get_toolkit` so that
+                ``AgentCreate`` can route to the appropriate template
+                when a ``subagent_type`` is specified.
+            custom_agent_cls (`type[Agent] | None`, optional):
+                Custom :class:`Agent` subclass for assembling agents.
+                Falls back to :class:`Agent` when ``None``.
+            extra_projectors (`list[EventProjector] | None`, optional):
+                Additional cross-session event projectors to run after
+                the built-in ones (mirrors the ``extra_agent_*``
+                injection style). Each is invoked once per produced
+                event to mirror a UI feed onto another session; see
+                :class:`~agentscope.app._types.EventProjector`.
+        """
+        self._storage = storage
+        self._workspace_manager = workspace_manager
+        self._scheduler_manager = scheduler_manager
+        self._background_task_manager = background_task_manager
+        self._message_bus = message_bus
+        self._access = resource_access_service
+        self._knowledge_base_manager = knowledge_base_manager
+        self._extra_agent_middlewares = extra_agent_middlewares
+        self._extra_agent_tools = extra_agent_tools
+        self._sub_agent_templates = custom_subagent_templates
+        self._agent_cls = custom_agent_cls or Agent
+        self._projection = SessionProjection(message_bus)
+        self._projectors: list[EventProjector] = [
+            SubagentHitlProjector(storage),
+            *(extra_projectors or []),
+        ]
+
+    async def run(
+        self,
+        user_id: str,
+        session_id: str,
+        agent_id: str,
+        input_msg: Msg
+        | list[Msg]
+        | UserConfirmResultEvent
+        | ExternalExecutionResultEvent
+        | UserInterruptEvent
+        | None = None,
+    ) -> None:
+        """Drive a chat run to completion.
+
+        Persists input messages (Case A) or the incoming continuation
+        event applied to the existing reply (Case B), runs the agent
+        while publishing every produced event to the message bus, and
+        persists the rebuilt reply ``Msg`` + updated agent state when
+        finished.
+
+        Session serialisation is handled by the bus's distributed lock
+        (:meth:`MessageBus.session_run`); events are simultaneously
+        persisted to the replay log and fanned out on the live channel
+        via :meth:`MessageBus.session_publish_event`. Exceptions are
+        logged and swallowed so a single failed fire does not tear
+        down its trigger (HTTP request task, wakeup dispatcher, …).
+
+        Args:
+            user_id (`str`):
+                Authenticated caller's user ID.
+            session_id (`str`):
+                Target session ID.
+            agent_id (`str`):
+                Agent to run.
+            input_msg:
+                One of:
+
+                - ``Msg`` / ``list[Msg]``: new user message(s) (Case A).
+                - ``None``: continue from current state — used by the
+                  wakeup dispatcher when there is no fresh user input
+                  but pending inbox content needs draining (Case A
+                  with no input).
+                - ``UserConfirmResultEvent`` /
+                  ``ExternalExecutionResultEvent``: resume an awaiting
+                  tool call (Case B).
+                - ``UserInterruptEvent``: abort a parked reply — the
+                  agent closes pending tool calls with interrupted
+                  results and ends the reply (Case B, no reasoning).
+        """
+        try:
+            await self._run_impl(user_id, session_id, agent_id, input_msg)
+        except Exception as e:
+            logger.exception(
+                "ChatService.run failed for user_id=%s session_id=%s "
+                "agent_id=%s, error=%s",
+                user_id,
+                session_id,
+                agent_id,
+                str(e),
+            )
+
+    async def interrupt(
+        self,
+        user_id: str,
+        session_id: str,
+        agent_id: str,
+    ) -> None:
+        """Interrupt an in-progress reply for a session.
+
+        Two paths, chosen by session liveness:
+
+        - **Running** (lock held): publish on the interrupt channel so
+          the local :class:`~agentscope.app._manager.CancelDispatcher`
+          cancels its chat-run task; the agent's ``CancelledError``
+          cleanup runs (fake tool results for pending calls, fallback
+          message, ``ReplyEndEvent(INTERRUPTED)``).
+        - **Not running**: enqueue a ``resume`` trigger carrying a
+          :class:`UserInterruptEvent`. If the session is parked on
+          HITL, the agent short-circuits into the same cleanup path;
+          if it is idle, the agent silently no-ops. Callers do not
+          need to distinguish the two — the operation is idempotent.
+
+        Args:
+            user_id (`str`):
+                Authenticated caller's user id.
+            session_id (`str`):
+                Target session id.
+            agent_id (`str`):
+                Agent that owns the session.
+
+        Raises:
+            LookupError:
+                The session does not exist.
+        """
+        session = await self._storage.get_session(
+            user_id,
+            agent_id,
+            session_id,
+        )
+        if session is None:
+            raise LookupError(f"Session '{session_id}' not found.")
+
+        if await self._message_bus.is_locked(
+            MessageBusKeys.session_lock(session_id),
+        ):
+            await self._message_bus.publish(
+                MessageBusKeys.session_interrupt_channel(),
+                {"session_id": session_id},
+            )
+            return
+
+        await enqueue_run_trigger(
+            self._message_bus,
+            user_id=user_id,
+            session_id=session_id,
+            agent_id=agent_id,
+            kind=MessageBusKeys.WAKEUP_KIND_RESUME,
+            inputs=UserInterruptEvent(reply_id=session.state.reply_id),
+        )
+
+    async def _run_impl(
+        self,
+        user_id: str,
+        session_id: str,
+        agent_id: str,
+        input_msg: Msg
+        | list[Msg]
+        | UserConfirmResultEvent
+        | ExternalExecutionResultEvent
+        | UserInterruptEvent
+        | None,
+    ) -> None:
+        """The actual chat-run body; wrapped by :meth:`run` for error
+        swallowing. Separated so the try/except doesn't bury the
+        per-step logic at one extra indentation level."""
+
+        # ----------------------------------------------------------------
+        # 1. Load records + resolve workspace ONCE here, reused below.
+        # Reject missing records up front with a clear error so the
+        # downstream assembly code can rely on non-None values.
+        #
+        # ``resolve_agent`` covers own agents (including team workers,
+        # which the owner runs directly) and cross-owner shared agents
+        # (viewer runs a shared user-source agent). It raises 404 when
+        # the agent is not visible to the caller.
+        # ----------------------------------------------------------------
+        try:
+            agent_record = await self._access.resolve_agent(user_id, agent_id)
+        except HTTPException as exc:
+            raise HTTPException(
+                status_code=404,
+                detail=f"Agent {agent_id!r} not found.",
+            ) from exc
+        session_record = await self._storage.get_session(
+            user_id,
+            agent_id,
+            session_id,
+        )
+        if session_record is None:
+            raise HTTPException(
+                status_code=404,
+                detail=(
+                    f"Session {session_id!r} not found for "
+                    f"agent {agent_id!r}."
+                ),
+            )
+        workspace = await self._workspace_manager.get_workspace(
+            user_id,
+            agent_id,
+            session_id,
+            session_record.config.workspace_id,
+        )
+
+        # Add workspace working directory to the permission context
+        if (
+            workspace.workdir
+            not in session_record.state.permission_context.working_directories
+        ):
+            session_record.state.permission_context.working_directories[
+                workspace.workdir
+            ] = AdditionalWorkingDirectory(
+                path=workspace.workdir,
+                source="session",
+            )
+
+        # ----------------------------------------------------------------
+        # 2. Middlewares — framework-supplied first, then caller extras.
+        # Background-tool completions deliver their results via
+        # ``message_bus.inbox_push + enqueue_wakeup``, so the dispatcher
+        # (any process) wakes an idle session — no in-process retrigger
+        # plumbing is needed here.
+        # ----------------------------------------------------------------
+        middlewares: list = [
+            InboxMiddleware(self._message_bus),
+            StateChangeMiddleware(
+                message_bus=self._message_bus,
+                session_id=session_id,
+            ),
+            ToolOffloadMiddleware(
+                bg_manager=self._background_task_manager,
+                message_bus=self._message_bus,
+                user_id=user_id,
+                agent_id=agent_id,
+            ),
+        ]
+        if self._extra_agent_middlewares is not None:
+            middlewares.extend(
+                await self._extra_agent_middlewares(
+                    user_id,
+                    agent_id,
+                    session_id,
+                ),
+            )
+
+        # ----------------------------------------------------------------
+        # 2b. TTS middleware — inject when the session has a TTS config.
+        # ----------------------------------------------------------------
+        tts_cfg = session_record.config.tts_model_config
+        if tts_cfg is not None:
+            tts_model = await get_tts_model(
+                user_id,
+                tts_cfg,
+                self._access,
+            )
+            middlewares.append(TTSMiddleware(tts_model))
+
+        # ----------------------------------------------------------------
+        # 2c. Knowledge-base middleware — inject when the session has KBs
+        # attached.  Each KB resolves to its own :class:`KnowledgeBase` handle
+        # (own embedding model + vector store), so the middleware can
+        # retrieve across heterogeneous KBs in one fan-out.
+        #
+        # Each KB may be either owned by the caller or shared to them
+        # via the resource access policy. We resolve the owner through
+        # ``resolve_knowledge_base`` first and hand the KB manager the
+        # true owner id — its own storage lookups stay owner-scoped
+        # and unaware of sharing.
+        # ----------------------------------------------------------------
+        kb_cfg = session_record.config.knowledge_config
+        if (
+            kb_cfg is not None
+            and kb_cfg.knowledge_base_ids
+            and self._knowledge_base_manager is not None
+        ):
+            knowledges: list[KnowledgeBase] = []
+            for kb_id in kb_cfg.knowledge_base_ids:
+                try:
+                    kb_record = await self._access.resolve_knowledge_base(
+                        user_id,
+                        kb_id,
+                    )
+                    knowledge = (
+                        await self._knowledge_base_manager.get_knowledge(
+                            kb_record.user_id,
+                            kb_id,
+                        )
+                    )
+                except Exception:  # pylint: disable=broad-except
+                    # A KB the session referenced was deleted, its
+                    # sharing revoked, or its credential is gone —
+                    # log and skip so the chat turn can still run
+                    # with the remaining KBs.
+                    logger.exception(
+                        "Skipping knowledge base %r for session %r: "
+                        "failed to resolve runtime handle.",
+                        kb_id,
+                        session_id,
+                    )
+                    continue
+                knowledges.append(knowledge)
+            if knowledges:
+                middlewares.append(
+                    RAGMiddleware(
+                        knowledge_bases=knowledges,
+                        parameters=RAGMiddleware.Parameters(
+                            **(kb_cfg.parameters or {}),
+                        ),
+                    ),
+                )
+
+        # ----------------------------------------------------------------
+        # 3. Toolkit (workspace tools + planning + ToolStop + schedule +
+        # team + extras + skills + mcps).
+        # ----------------------------------------------------------------
+        toolkit = await get_toolkit(
+            storage=self._storage,
+            workspace=workspace,
+            workspace_manager=self._workspace_manager,
+            scheduler_manager=self._scheduler_manager,
+            background_task_manager=self._background_task_manager,
+            message_bus=self._message_bus,
+            middlewares=middlewares,
+            user_id=user_id,
+            agent_record=agent_record,
+            session_record=session_record,
+            resource_access_service=self._access,
+            extra_factory=self._extra_agent_tools,
+            sub_agent_templates=self._sub_agent_templates,
+        )
+
+        # ----------------------------------------------------------------
+        # 4. Model + fallback (resolved from session's config).
+        # ----------------------------------------------------------------
+        model_cfg = session_record.config.chat_model_config
+        if not model_cfg:
+            raise HTTPException(
+                status_code=404,
+                detail=f"No model configuration found for agent {agent_id}",
+            )
+        model = await get_model(user_id, model_cfg, self._access)
+
+        fallback_cfg = session_record.config.fallback_chat_model_config
+        fallback_model = (
+            await get_model(user_id, fallback_cfg, self._access)
+            if fallback_cfg is not None
+            else None
+        )
+
+        # ----------------------------------------------------------------
+        # 5. Assemble the Agent.
+        # ----------------------------------------------------------------
+        agent_state = session_record.state
+        agent_state.session_id = session_id
+        agent = self._agent_cls(
+            name=agent_record.data.name,
+            system_prompt=agent_record.data.system_prompt,
+            model=model,
+            toolkit=toolkit,
+            model_config=ModelConfig(fallback_model=fallback_model),
+            context_config=agent_record.data.context_config,
+            react_config=agent_record.data.react_config,
+            state=agent_state,
+            middlewares=middlewares,
+            offloader=workspace,
+        )
+
+        # ----------------------------------------------------------------
+        # 6. Guard: skip wake-up driven runs when the agent is parked on
+        # an awaiting tool call.
+        #
+        # Wake-ups deliver pending inbox content (team messages, etc.) by
+        # poking the dispatcher to run the session with ``input_msg=None``.
+        # If the agent is currently parked on an ``ASKING`` or
+        # ``SUBMITTED`` tool call (waiting for user confirmation or
+        # external-execution results), kicking off another ``None`` run
+        # would hit :meth:`Agent._check_incoming_event`, which rightly
+        # rejects ``None`` when there is something to confirm — and fail
+        # the run noisily. The inbox content is safe to leave queued:
+        # whenever the user does confirm (or the external result lands),
+        # the resuming run's next reasoning step lets
+        # :class:`InboxMiddleware` drain the queue naturally.
+        # ----------------------------------------------------------------
+        if input_msg is None and agent.state.context:
+            last_msg = agent.state.context[-1]
+            if last_msg.role == "assistant" and last_msg.name == agent.name:
+                awaiting = [
+                    tc
+                    for tc in last_msg.get_content_blocks("tool_call")
+                    if tc.state
+                    in (ToolCallState.ASKING, ToolCallState.SUBMITTED)
+                ]
+                if awaiting:
+                    logger.info(
+                        "Skipping wake-up for session %s: agent is parked "
+                        "on %d awaiting tool call(s); inbox messages will "
+                        "be drained when the agent resumes.",
+                        session_id,
+                        len(awaiting),
+                    )
+                    return
+
+        # ----------------------------------------------------------------
+        # 7. Run the agent inside the distributed session lock
+        # ----------------------------------------------------------------
+        lock_key = MessageBusKeys.session_lock(session_id)
+        events_key = MessageBusKeys.session_events(session_id)
+        async with self._message_bus.acquire_lock(
+            lock_key,
+            ttl_secs=MessageBusKeys.SESSION_RUN_TTL_SECS,
+        ):
+            reply_msg: Msg | None = None
+            try:
+                if input_msg is None or isinstance(input_msg, (Msg, list)):
+                    # Case A: new reply (user message(s), or retrigger with
+                    # empty input)
+                    if isinstance(input_msg, (Msg, list)):
+                        input_msgs = (
+                            [input_msg]
+                            if isinstance(input_msg, Msg)
+                            else input_msg
+                        )
+                        for msg in input_msgs:
+                            await self._storage.upsert_message(
+                                user_id,
+                                session_id,
+                                msg,
+                            )
+
+                    async for event in agent.reply_stream(inputs=input_msg):
+                        await publish_session_event(
+                            self._message_bus,
+                            session_id,
+                            event.model_dump(mode="json"),
+                        )
+                        await self._project_event(
+                            user_id,
+                            session_record,
+                            agent_record,
+                            event,
+                        )
+                        if isinstance(event, ReplyStartEvent):
+                            reply_msg = AssistantMsg(
+                                id=event.reply_id,
+                                name=event.name,
+                                content=[],
+                            )
+                        elif reply_msg is not None:
+                            reply_msg.append_event(event)
+
+                else:
+                    # Case B: continuation (UserConfirmResult
+                    #  / ExternalExecResult)
+                    reply_msg = await self._storage.get_message(
+                        user_id,
+                        session_id,
+                        agent.state.reply_id,
+                    )
+
+                    if reply_msg is None:
+                        logger.warning(
+                            "Reply message %r not found in storage for "
+                            "session %r; tool-call state changes from the "
+                            "incoming event will not be persisted.",
+                            agent.state.reply_id,
+                            session_id,
+                        )
+                    elif input_msg:
+                        reply_msg.append_event(input_msg)
+
+                    async for event in agent.reply_stream(inputs=input_msg):
+                        await publish_session_event(
+                            self._message_bus,
+                            session_id,
+                            event.model_dump(mode="json"),
+                        )
+                        await self._project_event(
+                            user_id,
+                            session_record,
+                            agent_record,
+                            event,
+                        )
+                        if reply_msg is not None:
+                            reply_msg.append_event(event)
+
+            finally:
+                # All persistence in a single coroutine, shielded from
+                # outer cancellation.  Must complete BEFORE the session
+                # lock is released — otherwise another worker could
+                # acquire the lock and load a stale state from storage
+                # before this write lands.
+                async def _persist() -> None:
+                    if reply_msg is not None:
+                        await self._storage.upsert_message(
+                            user_id,
+                            session_id,
+                            reply_msg,
+                        )
+                    await self._storage.update_session_state(
+                        user_id=user_id,
+                        agent_id=agent_id,
+                        session_id=session_id,
+                        state=agent.state,
+                    )
+                    await self._message_bus.log_trim(events_key)
+
+                persist_task = asyncio.create_task(_persist())
+                try:
+                    await asyncio.shield(persist_task)
+                except asyncio.CancelledError:
+                    # Await the shielded task so the lock is only
+                    # released after storage is consistent, then
+                    # propagate to honour asyncio semantics.
+                    await persist_task
+                    raise
+
+    async def _project_event(
+        self,
+        user_id: str,
+        session_record: SessionRecord,
+        agent_record: AgentRecord,
+        event: AgentEvent,
+    ) -> None:
+        """Run every registered projector against one produced event.
+
+        Each :class:`~agentscope.app._types.EventProjector` decides
+        whether the event is relevant to its cross-session UI feed and,
+        if so, mirrors it onto the owning session via the shared
+        :class:`SessionProjection`. Projectors are independent: one
+        failing must neither tear down the producing run nor block the
+        others, so each call is guarded individually and its error
+        logged. Adding a feed means adding a projector — no change here.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+            session_record (`SessionRecord`):
+                The currently-running session's record.
+            agent_record (`AgentRecord`):
+                The currently-running agent's record.
+            event (`AgentEvent`):
+                The event just published to this session's channel.
+        """
+        for projector in self._projectors:
+            try:
+                await projector.maybe_project(
+                    user_id,
+                    session_record,
+                    agent_record,
+                    event,
+                    self._projection,
+                )
+            except Exception as e:  # pylint: disable=broad-except
+                logger.warning(
+                    "Projector %s failed on event %s from session %s: %s",
+                    type(projector).__name__,
+                    type(event).__name__,
+                    session_record.id,
+                    str(e),
+                )
diff --git a/src/agentscope/app/_service/_embedding.py b/src/agentscope/app/_service/_embedding.py
new file mode 100644
index 0000000..d3e6bd7
--- /dev/null
+++ b/src/agentscope/app/_service/_embedding.py
@@ -0,0 +1,126 @@
+# -*- coding: utf-8 -*-
+"""Embedding model service: builds an EmbeddingModelBase from stored
+credential + config.
+
+Mirrors :mod:`._model` (which does the same for chat models).
+
+Two entry points are provided:
+
+- :func:`get_embedding_model` — HTTP / ChatService path. Resolves the
+  credential through :class:`ResourceAccessService`, so shared
+  credentials work.
+- :func:`build_embedding_model` — pure record-in, model-out helper.
+  Used by owner-internal paths (e.g. the knowledge-base manager, which
+  already holds the KB owner's :class:`CredentialRecord`) and by
+  :func:`get_embedding_model` under the hood.
+"""
+from fastapi import HTTPException, status
+
+from ._access import ResourceAccessService
+from ..storage import CredentialRecord, EmbeddingModelConfig
+from ...credential import CredentialFactory
+from ...embedding import EmbeddingModelBase
+
+
+def build_embedding_model(
+    credential_record: CredentialRecord,
+    config: EmbeddingModelConfig,
+) -> EmbeddingModelBase:
+    """Construct an embedding model from an already-resolved credential.
+
+    This is the record-in variant used by owner-internal paths (e.g.
+    the KB manager, which reads the credential directly from storage
+    since KB owner == credential owner). HTTP / cross-owner paths
+    should call :func:`get_embedding_model` instead.
+
+    Args:
+        credential_record (`CredentialRecord`):
+            The credential record whose ``data`` will be handed to the
+            provider client.
+        config (`EmbeddingModelConfig`):
+            The embedding model configuration (``type``, ``model``,
+            ``parameters``, ``dimensions``).
+
+    Returns:
+        `EmbeddingModelBase`:
+            A configured embedding model instance.
+
+    Raises:
+        `HTTPException`:
+            400 if the provider does not support embedding.
+    """
+    credential = CredentialFactory.from_dict(credential_record.data)
+
+    credential_cls = CredentialFactory.get_credential_class(config.type)
+    if credential_cls is None:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Provider {config.type!r} not found.",
+        )
+
+    embedding_cls = credential_cls.get_embedding_model_class()
+    if embedding_cls is None:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=(
+                f"Provider {config.type!r} does not support "
+                f"embedding models."
+            ),
+        )
+
+    context_size: int | None = None
+    for card in embedding_cls.list_models():
+        if card.name == config.model:
+            context_size = card.context_size
+            break
+
+    parameters = (
+        embedding_cls.Parameters(**config.parameters)
+        if config.parameters
+        else None
+    )
+
+    kwargs: dict = {
+        "credential": credential,
+        "model": config.model,
+        "dimensions": config.dimensions,
+        "parameters": parameters,
+    }
+    if context_size is not None:
+        kwargs["context_size"] = context_size
+
+    return embedding_cls(**kwargs)
+
+
+async def get_embedding_model(
+    user_id: str,
+    config: EmbeddingModelConfig,
+    access: ResourceAccessService,
+) -> EmbeddingModelBase:
+    """Resolve a credential through :class:`ResourceAccessService` and
+    build the corresponding embedding model.
+
+    Args:
+        user_id (`str`):
+            The viewer's user id (may differ from the credential owner
+            for shared credentials).
+        config (`EmbeddingModelConfig`):
+            The embedding model configuration.
+        access (`ResourceAccessService`):
+            Injected resource access service.
+
+    Returns:
+        `EmbeddingModelBase`:
+            A configured embedding model instance.
+
+    Raises:
+        `HTTPException`:
+            404 if the credential is neither owned by ``user_id`` nor
+            shared to them.
+            400 if the provider does not support embedding.
+    """
+    credential_record = await access.resolve_credential(
+        user_id,
+        config.credential_id,
+    )
+    return build_embedding_model(credential_record, config)
diff --git a/src/agentscope/app/_service/_index_sweeper.py b/src/agentscope/app/_service/_index_sweeper.py
new file mode 100644
index 0000000..51f14a2
--- /dev/null
+++ b/src/agentscope/app/_service/_index_sweeper.py
@@ -0,0 +1,150 @@
+# -*- coding: utf-8 -*-
+"""Background sweep for stuck knowledge-document indexing jobs.
+
+The indexing pipeline relies on two storage-level signals to keep
+moving when something goes wrong:
+
+- a *lease* per in-flight document — its ``lease_expires_at`` is the
+  upper bound on how long a worker may sit on the document before
+  another worker is allowed to take over;
+- a *creation timestamp* on every ``pending`` record — used to catch
+  documents that were never picked up by a worker (e.g. process died
+  right after the upload endpoint persisted the record).
+
+The sweeper periodically scans storage for both classes of stuck
+records and re-enqueues them on the index-task channel.  Re-enqueue is
+safe because the worker's CAS lease acquisition rejects duplicates,
+so multiple nodes running their own sweeper does not produce double
+processing.
+"""
+import asyncio
+from datetime import datetime, timedelta
+from typing import TYPE_CHECKING
+
+from ..._logging import logger
+from .._bus_ops import enqueue_index_task
+
+if TYPE_CHECKING:
+    from ..message_bus import MessageBus
+    from ..storage import StorageBase
+
+
+class IndexSweeper:
+    """Periodically re-enqueues documents stuck in indexing.
+
+    Lifecycle is wired into the app's lifespan: :meth:`start` schedules
+    the background task and runs an immediate sweep so that documents
+    left stuck by the previous process generation get picked up at
+    once; :meth:`stop` cancels the loop on shutdown.
+    """
+
+    def __init__(
+        self,
+        storage: "StorageBase",
+        message_bus: "MessageBus",
+        interval: timedelta = timedelta(seconds=60),
+        pending_grace: timedelta = timedelta(minutes=5),
+    ) -> None:
+        """Initialize the sweeper.
+
+        Args:
+            storage (`StorageBase`):
+                Used to find stuck records and as the contract holder
+                for the lease semantics.
+            message_bus (`MessageBus`):
+                The same bus the upload endpoint uses.  Re-enqueuing
+                a document re-enters the worker pipeline, where the
+                CAS lease acquisition decides whether to actually
+                process or bail.
+            interval (`timedelta`, defaults to ``60s``):
+                How often the loop wakes up.  Roughly one order of
+                magnitude shorter than the typical lease TTL — fast
+                enough to recover from crashes within a few minutes,
+                slow enough not to thrash storage.
+            pending_grace (`timedelta`, defaults to ``5min``):
+                A record may legitimately sit in ``pending`` while the
+                bus push is still queued; only after this grace period
+                do we treat the record as orphaned.
+        """
+        self._storage = storage
+        self._bus = message_bus
+        self._interval = interval
+        self._pending_grace = pending_grace
+        self._task: asyncio.Task[None] | None = None
+
+    async def start(self) -> None:
+        """Start the background sweep loop and run one immediate sweep."""
+        if self._task is not None:
+            return
+        # Catch up from any state the previous generation left behind.
+        await self._sweep_once()
+        self._task = asyncio.create_task(
+            self._loop(),
+            name="kb-index-sweeper",
+        )
+
+    async def stop(self) -> None:
+        """Cancel the sweep loop and wait for it to exit."""
+        if self._task is None:
+            return
+        self._task.cancel()
+        try:
+            await self._task
+        except asyncio.CancelledError:
+            pass
+        self._task = None
+
+    async def _loop(self) -> None:
+        """Run sweeps forever until cancelled."""
+        interval_seconds = self._interval.total_seconds()
+        while True:
+            try:
+                await asyncio.sleep(interval_seconds)
+            except asyncio.CancelledError:
+                return
+            try:
+                await self._sweep_once()
+            except asyncio.CancelledError:
+                return
+            except Exception:  # noqa: BLE001 — keep the loop alive
+                logger.exception("Sweep iteration failed")
+
+    async def _sweep_once(self) -> None:
+        """Find and re-enqueue every stuck document.
+
+        De-duplication: a document showing up in both the
+        expired-lease and orphan-pending queries (a record that was
+        never picked up and whose lease pre-dates the grace period)
+        is enqueued only once per sweep, by record id.
+        """
+        now = datetime.now()
+        pending_threshold = now - self._pending_grace
+
+        seen: set[str] = set()
+        stuck = (
+            await self._storage.list_knowledge_documents_with_expired_lease(
+                now=now,
+            )
+        )
+        orphans = await self._storage.list_knowledge_documents_pending_since(
+            threshold=pending_threshold,
+        )
+        for record in (*stuck, *orphans):
+            if record.id in seen:
+                continue
+            seen.add(record.id)
+            try:
+                await enqueue_index_task(
+                    self._bus,
+                    user_id=record.user_id,
+                    knowledge_base_id=record.knowledge_base_id,
+                    document_id=record.id,
+                )
+            except Exception:  # noqa: BLE001 — keep iterating
+                logger.exception(
+                    "Failed to re-enqueue document %s",
+                    record.id,
+                )
+
+        if seen:
+            logger.info("Re-enqueued %d stuck document(s)", len(seen))
diff --git a/src/agentscope/app/_service/_index_task_consumer.py b/src/agentscope/app/_service/_index_task_consumer.py
new file mode 100644
index 0000000..3b3aaba
--- /dev/null
+++ b/src/agentscope/app/_service/_index_task_consumer.py
@@ -0,0 +1,216 @@
+# -*- coding: utf-8 -*-
+"""Single per-worker-process consumer of the shared index-task channel.
+
+One asyncio task per worker process. Subscribes to the shared
+:meth:`~agentscope.app.message_bus.MessageBusKeys.index_tasks_signal`
+channel and drains the durable
+:meth:`~agentscope.app.message_bus.MessageBusKeys.index_tasks_queue`
+on each signal. For each queued entry it invokes
+:meth:`IndexWorker.process` directly — the worker holds its own
+semaphore so we can fire-and-forget multiple ``process`` calls without
+overrunning resources.
+
+Mirrors :class:`~agentscope.app._manager.WakeupDispatcher`. The two
+patterns are deliberately identical: both subscribe to a signal,
+drain a queue, dispatch each entry, and run forever inside an
+``async with`` block. Keeping them shaped the same makes it cheap to
+reason about either one once you've read the other.
+
+The bus exposes only transport-level primitives — there is no
+``enqueue_index_task`` or ``dequeue_index_task`` method on it. The
+key constants live on :class:`~agentscope.app.message_bus.
+MessageBusKeys` (next to every other application-layer key) and the
+composition is inline here because the consumer is the only sink for
+the channel; introducing a separate ``IndexTaskBroker`` would be
+ceremony without gain.
+"""
+import asyncio
+from typing import TYPE_CHECKING, Any, Self
+
+from ..message_bus import MessageBusKeys
+from ..._logging import logger
+
+if TYPE_CHECKING:
+    from ..message_bus import MessageBus
+    from ._index_worker import IndexWorker
+
+
+class IndexTaskConsumer:
+    """Subscribe-then-drain consumer that feeds :class:`IndexWorker`.
+
+    Args:
+        message_bus (`MessageBus`):
+            Application message bus. The consumer only uses the two
+            transport-level primitives — ``subscribe`` (for the
+            signal channel) and ``queue_drain`` (for the durable
+            task queue).
+        worker (`IndexWorker`):
+            The worker that owns the parse → chunk → index pipeline.
+            ``process`` is invoked once per queue entry; the worker's
+            internal semaphore + lease CAS handle concurrency and
+            deduplication.
+        max_batch (`int`, defaults to ``32``):
+            Maximum entries drained per signal. Keeps a single
+            signal from monopolising the loop when the queue is
+            backed up; remaining entries are picked up on the next
+            signal or the next sweeper-driven eager drain.
+    """
+
+    def __init__(
+        self,
+        message_bus: "MessageBus",
+        worker: "IndexWorker",
+        max_batch: int = 32,
+    ) -> None:
+        self._bus = message_bus
+        self._worker = worker
+        self._max_batch = max_batch
+        self._task: asyncio.Task | None = None
+        # In-flight ``worker.process`` calls. Tracked so ``__aexit__``
+        # can cancel + drain them; otherwise the event-loop teardown
+        # would swallow exceptions raised inside the worker.
+        self._inflight: set[asyncio.Task[Any]] = set()
+
+    async def __aenter__(self) -> Self:
+        """Start the consumer loop and wait until its subscription
+        is live.
+
+        After the subscription is established, an initial drain runs
+        synchronously so tasks queued while every worker was down
+        get picked up immediately on startup, without waiting for
+        a fresh signal.
+        """
+        ready = asyncio.Event()
+        self._task = asyncio.create_task(
+            self._loop(ready),
+            name="index-task-consumer",
+        )
+        await ready.wait()
+        await self._drain_and_dispatch()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: Any,
+    ) -> None:
+        """Cancel the consumer loop and drain any in-flight work.
+
+        Cancellation of the worker's ``process`` calls is a clean
+        shutdown signal — the worker holds the storage lease and
+        will let it expire so the sweeper re-dispatches the document
+        on the next loop tick.
+        """
+        if self._task is not None:
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+            self._task = None
+
+        for task in list(self._inflight):
+            task.cancel()
+        if self._inflight:
+            await asyncio.gather(*self._inflight, return_exceptions=True)
+        self._inflight.clear()
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    async def _loop(self, ready: asyncio.Event) -> None:
+        """Long-lived loop: subscribe to the signal and drain on each
+        received signal.
+
+        Args:
+            ready (`asyncio.Event`):
+                Signalled after the underlying SUBSCRIBE completes.
+                :meth:`__aenter__` blocks on this so the producer
+                can publish a signal immediately after start-up
+                without racing.
+        """
+        try:
+            async for _signal in self._bus.subscribe(
+                MessageBusKeys.index_tasks_signal(),
+                on_ready=ready.set,
+            ):
+                await self._drain_and_dispatch()
+        except Exception:  # pylint: disable=broad-except
+            logger.exception(
+                "IndexTaskConsumer loop crashed; subscription ended.",
+            )
+        finally:
+            # If ``subscribe`` raises before ``on_ready`` fires, the
+            # ``__aenter__`` coroutine would deadlock on ``ready.wait()``.
+            # Set the event unconditionally on the way out so startup
+            # cannot stall on a transient bus failure.
+            ready.set()
+
+    async def _drain_and_dispatch(self) -> None:
+        """Read up to a batch of task entries and dispatch each one."""
+        try:
+            entries = await self._bus.queue_drain(
+                MessageBusKeys.index_tasks_queue(),
+                max_count=self._max_batch,
+            )
+        except Exception:  # pylint: disable=broad-except
+            logger.exception("IndexTaskConsumer: drain failed.")
+            return
+
+        for _entry_id, payload in entries:
+            try:
+                user_id = payload["user_id"]
+                knowledge_base_id = payload["knowledge_base_id"]
+                document_id = payload["document_id"]
+            except (KeyError, TypeError):
+                logger.warning(
+                    "IndexTaskConsumer: skipping malformed entry %r",
+                    payload,
+                )
+                continue
+
+            self._spawn(
+                user_id=user_id,
+                knowledge_base_id=knowledge_base_id,
+                document_id=document_id,
+            )
+
+    def _spawn(
+        self,
+        *,
+        user_id: str,
+        knowledge_base_id: str,
+        document_id: str,
+    ) -> None:
+        """Run :meth:`IndexWorker.process` as a tracked background task.
+
+        We do not ``await`` ``worker.process`` inline — a slow parse
+        would block draining the next signal. The worker holds its
+        own concurrency semaphore, so spawning many tasks at once is
+        safe; they will queue at the semaphore.
+        """
+        task = asyncio.create_task(
+            self._worker.process(
+                user_id=user_id,
+                knowledge_base_id=knowledge_base_id,
+                document_id=document_id,
+            ),
+            name=f"index-task:{knowledge_base_id}:{document_id}",
+        )
+        self._inflight.add(task)
+        task.add_done_callback(self._on_done)
+
+    def _on_done(self, task: asyncio.Task[Any]) -> None:
+        """Drop the task reference and log any uncaught exception."""
+        self._inflight.discard(task)
+        if task.cancelled():
+            return
+        exc = task.exception()
+        if exc is not None:
+            logger.exception(
+                "IndexTaskConsumer: worker.process(%s) raised",
+                task.get_name(),
+                exc_info=exc,
+            )
diff --git a/src/agentscope/app/_service/_index_worker.py b/src/agentscope/app/_service/_index_worker.py
new file mode 100644
index 0000000..3c2eae7
--- /dev/null
+++ b/src/agentscope/app/_service/_index_worker.py
@@ -0,0 +1,534 @@
+# -*- coding: utf-8 -*-
+"""Background indexing pipeline for one knowledge document.
+
+The :class:`IndexWorker` owns the post-upload half of the document
+lifecycle.  Given a ``document_id`` it:
+
+1. acquires the processing lease via storage CAS (so only one worker
+   in the cluster handles the document at a time);
+2. reads the bytes back from the blob store (streamed);
+3. routes to a parser by IANA media type;
+4. chunks the resulting sections;
+5. embeds + writes to the vector store through
+   :class:`~agentscope.rag.KnowledgeBase`;
+6. transitions the status through ``parsing → chunking → indexing →
+   ready`` (or ``error``) on the way.
+
+The worker is intentionally embeddable: a single instance can live
+inside the API process (embedded deployment) or inside a dedicated
+worker process (dedicated deployment).  Coordination across workers
+is done entirely through the storage lease — workers do not need to
+know about each other.
+"""
+import asyncio
+import contextlib
+import mimetypes
+from concurrent.futures import ProcessPoolExecutor
+from datetime import timedelta
+from typing import TYPE_CHECKING
+
+from ..._logging import logger
+
+if TYPE_CHECKING:
+    from ..rag.blob_store import BlobStoreBase
+    from ..rag.knowledge_base_manager import KnowledgeBaseManagerBase
+    from ..storage import StorageBase
+    from ...rag import ChunkerBase, ParserBase, Section
+
+# Read blob bytes in chunks bounded so the worker never holds the whole
+# file in memory at once even when the parser is byte-oriented.
+_READ_CHUNK = 1 << 20  # 1 MiB
+
+
+def _build_parser_registry(
+    parsers: "list[ParserBase] | dict[str, ParserBase]",
+) -> "dict[str, ParserBase]":
+    """Normalise the user-supplied parser registry.
+
+    Two input shapes are accepted:
+
+    - **List** — each parser's ``supported_media_types`` is expanded;
+      duplicate media types resolve to the **last** parser in the list
+      (so callers can layer custom parsers over the defaults), with a
+      warning logged for each override so silent shadowing is not
+      possible.
+    - **Dict** — the caller's mapping is used verbatim.  This is the
+      escape hatch for callers who want full control over routing (one
+      parser bound to multiple types, type aliases, etc.); a warning is
+      logged when a parser is registered against a media type it does
+      not declare in ``supported_media_types``, since that almost
+      always indicates a typo.
+
+    Args:
+        parsers (`list[ParserBase] | dict[str, ParserBase]`):
+            The user-supplied parser registry.
+
+    Returns:
+        `dict[str, ParserBase]`:
+            The resolved ``media_type → parser`` routing table.
+    """
+    if isinstance(parsers, dict):
+        for media_type, parser in parsers.items():
+            declared = getattr(parser, "supported_media_types", ())
+            if declared and media_type not in declared:
+                logger.warning(
+                    "Parser %s registered for media type %r but it only "
+                    "declares %s — proceeding with the caller-supplied "
+                    "mapping.",
+                    type(parser).__name__,
+                    media_type,
+                    list(declared),
+                )
+        return dict(parsers)
+
+    registry: dict[str, "ParserBase"] = {}
+    for parser in parsers:
+        for media_type in parser.supported_media_types:
+            previous = registry.get(media_type)
+            if previous is not None and previous is not parser:
+                logger.warning(
+                    "Parser %s overrides %s for media type %r — later "
+                    "entries in `parsers` win.  Pass a "
+                    "`dict[str, ParserBase]` if you want explicit "
+                    "routing.",
+                    type(parser).__name__,
+                    type(previous).__name__,
+                    media_type,
+                )
+            registry[media_type] = parser
+    return registry
+
+
+class IndexWorker:
+    """Drive one document through parse → chunk → index.
+
+    Multiple invocations of :meth:`process` are run concurrently up to
+    a per-worker semaphore.  The semaphore protects shared resources
+    that scale with the number of in-flight parses (memory for big
+    PDFs, embedding API rate budget), while the lease CAS in storage
+    protects against the *cross-worker* version of the same race.
+    """
+
+    def __init__(
+        self,
+        storage: "StorageBase",
+        blob_store: "BlobStoreBase",
+        knowledge_base_manager: "KnowledgeBaseManagerBase",
+        parsers: "list[ParserBase] | dict[str, ParserBase]",
+        chunker: "ChunkerBase",
+        node_id: str,
+        max_concurrency: int = 4,
+        lease_ttl: timedelta = timedelta(seconds=90),
+        parser_executor: ProcessPoolExecutor | None = None,
+    ) -> None:
+        """Initialize the worker.
+
+        Args:
+            storage (`StorageBase`):
+                Document records, lease, status.
+            blob_store (`BlobStoreBase`):
+                Source of the document bytes.
+            knowledge_base_manager (`KnowledgeBaseManagerBase`):
+                Resolves the :class:`KnowledgeBase` runtime for embedding
+                and vector store writes.
+            parsers (`list[ParserBase] | dict[str, ParserBase]`):
+                Parsers used to dispatch uploads by IANA media type.
+                Two input shapes are accepted:
+
+                - **List** — each parser's ``supported_media_types`` is
+                  expanded into a routing table; later entries override
+                  earlier ones for overlapping types, with a warning
+                  logged at construction time.
+                - **Dict** — caller-supplied ``media_type → parser``
+                  routing table used verbatim.  ``supported_media_types``
+                  is **not** consulted, but a warning is logged if a
+                  parser is registered against a media type it does not
+                  declare.
+
+                Same registry the upload service uses, passed in by DI.
+            chunker (`ChunkerBase`):
+                The shared chunker.
+            node_id (`str`):
+                Stable identifier for this worker process.  Used as
+                ``processing_node`` on the lease so the sweeper can
+                tell whose work expired.  Typically
+                ``f"{hostname}:{pid}:{uuid}"``.
+            max_concurrency (`int`, defaults to ``4``):
+                Maximum number of documents processed concurrently by
+                this worker.  Higher values trade memory for
+                throughput; tune per embedding-API rate limits and
+                per-document parse cost.
+            lease_ttl (`timedelta`, defaults to ``90s``):
+                How long a single processing lease lives.  The worker
+                renews periodically so long-running parses do not
+                trip the sweeper.
+            parser_executor (`ProcessPoolExecutor | None`, optional):
+                Process pool used to off-load CPU-intensive parses
+                (PDF, Office).  ``None`` runs parses in the event-loop
+                thread, which is fine for plain text but unsafe for
+                third-party byte-oriented parsers.  Injected so a
+                single pool can be shared across the app (built in
+                lifespan).
+        """
+        self._storage = storage
+        self._blob_store = blob_store
+        self._manager = knowledge_base_manager
+        self._parsers_by_media_type = _build_parser_registry(parsers)
+        self._chunker = chunker
+        self._node_id = node_id
+        self._lease_ttl = lease_ttl
+        self._sem = asyncio.Semaphore(max_concurrency)
+        self._parser_executor = parser_executor
+        # Renewal cadence: refresh while there is still half the lease
+        # left so a one-cycle missed renewal doesn't drop the lease.
+        self._renew_interval = max(lease_ttl / 2, timedelta(seconds=5))
+
+    async def process(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+        document_id: str,
+    ) -> None:
+        """Run the full indexing pipeline for one document.
+
+        Steps:
+
+        1. **Lease** — CAS-acquire the processing lease; bail if some
+           other worker already holds it (duplicate dispatch / sweep).
+        2. **Throttle** — wait on the per-worker semaphore so the
+           number of in-flight parses stays bounded.
+        3. **Pipeline** — parse → chunk → embed + write vector store,
+           updating status before each phase.  A background heartbeat
+           keeps the lease alive while parsing runs.
+        4. **Finalise** — on success mark ``ready`` with the final
+           chunk count; on failure mark ``error`` with a sanitised
+           message.  The lease is released regardless.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+            knowledge_base_id (`str`):
+                The parent knowledge base id.
+            document_id (`str`):
+                The document to process.
+        """
+        acquired = await self._storage.acquire_knowledge_document_lease(
+            user_id=user_id,
+            knowledge_base_id=knowledge_base_id,
+            document_id=document_id,
+            processing_node=self._node_id,
+            lease_ttl=self._lease_ttl,
+        )
+        if not acquired:
+            logger.debug(
+                "Skipping %s — another worker holds the lease.",
+                document_id,
+            )
+            return
+
+        pipeline_task = asyncio.create_task(
+            self._guarded_pipeline(
+                user_id,
+                knowledge_base_id,
+                document_id,
+            ),
+            name=f"pipeline:{document_id}",
+        )
+        heartbeat_task = asyncio.create_task(
+            self._heartbeat(user_id, knowledge_base_id, document_id),
+            name=f"lease-renew:{document_id}",
+        )
+        try:
+            # Race the pipeline against the heartbeat: if the heartbeat
+            # returns first, the lease was stolen mid-flight (e.g. the
+            # sweeper reaped this worker after a renewal gap) — we MUST
+            # stop the pipeline before it writes the vector store again,
+            # otherwise the worker that just took over and this one will
+            # both insert the same chunks.
+            await asyncio.wait(
+                {pipeline_task, heartbeat_task},
+                return_when=asyncio.FIRST_COMPLETED,
+            )
+
+            if not pipeline_task.done():
+                # Heartbeat reached the end first; only `_heartbeat`'s
+                # lost-lease branch returns, so cancel the pipeline and
+                # surface it as a terminal error for this document.
+                pipeline_task.cancel()
+                with contextlib.suppress(
+                    asyncio.CancelledError,
+                    Exception,
+                ):
+                    await pipeline_task
+                raise RuntimeError(
+                    f"Lost lease on {document_id} during processing; "
+                    "another worker has taken over.",
+                )
+
+            # Pipeline finished first; stop the heartbeat and re-raise
+            # whatever the pipeline raised (if anything).
+            heartbeat_task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await heartbeat_task
+            await pipeline_task
+        except Exception as exc:  # noqa: BLE001 — terminal error sink
+            await self._mark_error(
+                user_id,
+                knowledge_base_id,
+                document_id,
+                exc,
+            )
+        finally:
+            # Release is CAS-guarded server-side on ``processing_node``
+            # (storage._base.release_knowledge_document_lease) — calling
+            # it after a stolen lease is a safe no-op.
+            await self._storage.release_knowledge_document_lease(
+                user_id=user_id,
+                knowledge_base_id=knowledge_base_id,
+                document_id=document_id,
+                processing_node=self._node_id,
+            )
+
+    async def _guarded_pipeline(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+        document_id: str,
+    ) -> None:
+        """Run the throttled pipeline inside the per-worker semaphore."""
+        async with self._sem:
+            await self._run_pipeline(
+                user_id,
+                knowledge_base_id,
+                document_id,
+            )
+
+    # ------------------------------------------------------------------
+    # Pipeline
+    # ------------------------------------------------------------------
+
+    async def _run_pipeline(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+        document_id: str,
+    ) -> None:
+        """Walk the document through parse → chunk → index."""
+        record = await self._storage.get_knowledge_document(
+            user_id,
+            knowledge_base_id,
+            document_id,
+        )
+        if record is None:
+            logger.warning(
+                "Document %s vanished before processing.",
+                document_id,
+            )
+            return
+
+        data = record.data
+        media_type = (
+            data.content_type or mimetypes.guess_type(data.filename)[0]
+        )
+        if not media_type:
+            raise ValueError(
+                f"Cannot determine media type for {data.filename!r}.",
+            )
+        parser = self._parsers_by_media_type.get(media_type)
+        if parser is None:
+            raise ValueError(
+                f"No parser registered for media type {media_type!r}.",
+            )
+
+        # ---- parsing ----
+        await self._storage.update_knowledge_document_status(
+            user_id,
+            knowledge_base_id,
+            document_id,
+            "parsing",
+        )
+        file_bytes = await self._read_blob(data.blob_uri)
+        sections = await self._parse(parser, file_bytes, data.filename)
+
+        # ---- chunking ----
+        await self._storage.update_knowledge_document_status(
+            user_id,
+            knowledge_base_id,
+            document_id,
+            "chunking",
+        )
+        chunks = await self._chunker.chunk(sections)
+
+        # ---- indexing ----
+        await self._storage.update_knowledge_document_status(
+            user_id,
+            knowledge_base_id,
+            document_id,
+            "indexing",
+        )
+        knowledge = await self._manager.get_knowledge(
+            user_id,
+            knowledge_base_id,
+        )
+        await knowledge.insert_document(
+            chunks=chunks,
+            document_id=document_id,
+            document_metadata={
+                "filename": data.filename,
+                "media_type": media_type,
+                "size_bytes": data.size,
+            },
+        )
+
+        # ---- ready ----
+        await self._storage.update_knowledge_document_status(
+            user_id,
+            knowledge_base_id,
+            document_id,
+            "ready",
+            chunk_count=len(chunks),
+        )
+
+    async def _parse(
+        self,
+        parser: "ParserBase",
+        file_bytes: bytes,
+        filename: str,
+    ) -> "list[Section]":
+        """Run the parser, optionally on the process pool."""
+        if self._parser_executor is None:
+            return await parser.parse(file_bytes, filename)
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(
+            self._parser_executor,
+            _run_parser_sync,
+            parser,
+            file_bytes,
+            filename,
+        )
+
+    async def _read_blob(self, blob_uri: str) -> bytes:
+        """Stream the blob into memory in bounded chunks.
+
+        We buffer the whole file before handing it to the parser
+        because today's parser API is byte-oriented (``parse(file:
+        bytes, filename: str)``).  The read loop still avoids large
+        single allocations and gives us a single place to upgrade to a
+        true streaming parser API later — only this method needs to
+        change.
+        """
+        buffer = bytearray()
+        async with self._blob_store.open(blob_uri) as fp:
+            while True:
+                chunk = await fp.read(_READ_CHUNK)
+                if not chunk:
+                    break
+                buffer.extend(chunk)
+        return bytes(buffer)
+
+    # ------------------------------------------------------------------
+    # Lease heartbeat
+    # ------------------------------------------------------------------
+
+    async def _heartbeat(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+        document_id: str,
+    ) -> None:
+        """Renew the lease in the background while processing runs.
+
+        Two exit paths:
+
+        - The surrounding pipeline finishes first and cancels this
+          task — silent return via :class:`asyncio.CancelledError`.
+        - The renewal fails (the sweeper reaped this worker and
+          another worker now holds the lease).  The task **returns
+          normally** in this case; :meth:`process` is racing this task
+          against the pipeline and treats a normal return as the
+          "lost-lease" signal, cancelling the pipeline before it
+          double-writes the vector store.
+
+        Anything other than ``ok=False`` keeps the loop alive.
+        """
+        interval_seconds = self._renew_interval.total_seconds()
+        while True:
+            try:
+                await asyncio.sleep(interval_seconds)
+            except asyncio.CancelledError:
+                return
+            ok = await self._storage.renew_knowledge_document_lease(
+                user_id=user_id,
+                knowledge_base_id=knowledge_base_id,
+                document_id=document_id,
+                processing_node=self._node_id,
+                lease_ttl=self._lease_ttl,
+            )
+            if not ok:
+                logger.warning(
+                    "Lost lease on %s while processing.",
+                    document_id,
+                )
+                return
+
+    # ------------------------------------------------------------------
+    # Error sink
+    # ------------------------------------------------------------------
+
+    async def _mark_error(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+        document_id: str,
+        exc: BaseException,
+    ) -> None:
+        """Persist a sanitised error and mark the document failed."""
+        logger.exception(
+            "Indexing failed for %s/%s",
+            knowledge_base_id,
+            document_id,
+            exc_info=exc,
+        )
+        message = _sanitise_error(exc)
+        try:
+            await self._storage.update_knowledge_document_status(
+                user_id,
+                knowledge_base_id,
+                document_id,
+                "error",
+                error=message,
+            )
+        except Exception:  # noqa: BLE001 — last-resort log
+            logger.exception(
+                "Failed to persist error status for %s",
+                document_id,
+            )
+
+
+# ----------------------------------------------------------------------
+# Module-level helpers (picklable for ProcessPoolExecutor)
+# ----------------------------------------------------------------------
+
+
+def _run_parser_sync(
+    parser: "ParserBase",
+    file_bytes: bytes,
+    filename: str,
+) -> "list[Section]":
+    """Run an async parser to completion inside a sync executor."""
+    return asyncio.run(parser.parse(file_bytes, filename))
+
+
+def _sanitise_error(exc: BaseException) -> str:
+    """Reduce an exception to a single user-facing line.
+
+    Only the exception class name + first line of its message are
+    kept — stack traces and filesystem paths stay inside the worker
+    log and out of the user-visible record.
+    """
+    raw = str(exc) or exc.__class__.__name__
+    first_line = raw.splitlines()[0].strip()
+    cls = exc.__class__.__name__
+    if not first_line:
+        return cls
+    return f"{cls}: {first_line[:240]}"
diff --git a/src/agentscope/app/_service/_knowledge_base.py b/src/agentscope/app/_service/_knowledge_base.py
new file mode 100644
index 0000000..180e0bc
--- /dev/null
+++ b/src/agentscope/app/_service/_knowledge_base.py
@@ -0,0 +1,545 @@
+# -*- coding: utf-8 -*-
+"""Knowledge base service: HTTP-side orchestration.
+
+The router stays thin and DTO-shaped; everything HTTP-side that needs
+to coordinate persistence, the blob store, the indexing pipeline,
+and the vector store goes through this service.
+
+The split with :class:`~agentscope.rag.KnowledgeBase`
+is deliberate.  ``KnowledgeBase`` is a **library-mode** handle that only
+depends on the vector store; embedded users instantiate one and drive
+the parse → chunk → embed pipeline themselves.  ``KnowledgeBaseService``
+is **service-mode** orchestration: it owns the document records
+(status / blob / lease) and is the single source of truth for "what
+documents exist in this KB" when the app is running over HTTP.  The
+two views are intentionally not blended — mixing library-mode inserts
+with service-mode listing would leave records out of sync, and the
+project's stance is that a knowledge base is managed end-to-end in one
+mode.
+"""
+import uuid
+from typing import IO, TYPE_CHECKING
+
+from fastapi import HTTPException, status
+
+from ..access import ResourceKind
+from ..rag.knowledge_base_manager import (
+    DimensionPolicyError,
+    KnowledgeBaseNotFoundError,
+)
+from ..storage import (
+    KnowledgeDocumentData,
+    KnowledgeDocumentRecord,
+)
+from ..._logging import logger
+from .._bus_ops import enqueue_index_task
+from ._access import ResourceAccessService
+
+if TYPE_CHECKING:
+    from ..rag.blob_store import BlobStoreBase
+    from ..rag.knowledge_base_manager import KnowledgeBaseManagerBase
+    from ..message_bus import MessageBus
+    from ..storage import (
+        EmbeddingModelConfig,
+        KnowledgeBaseRecord,
+        StorageBase,
+    )
+    from ...rag import VectorSearchResult
+
+
+class KnowledgeBaseService:
+    """HTTP service for knowledge bases.
+
+    Owns the document lifecycle in service mode: register on upload,
+    enqueue an index task, query status during indexing, and clean up
+    record + blob + vector store on delete.  All parsing / chunking /
+    embedding work happens inside the
+    :class:`~agentscope.app._service.IndexWorker`; the service only
+    hands off (via the message bus) and observes.
+    """
+
+    def __init__(
+        self,
+        storage: "StorageBase",
+        knowledge_base_manager: "KnowledgeBaseManagerBase",
+        blob_store: "BlobStoreBase",
+        message_bus: "MessageBus",
+        resource_access_service: "ResourceAccessService",
+    ) -> None:
+        """Initialize the service.
+
+        Args:
+            storage (`StorageBase`):
+                The application storage backend; documents are
+                persisted here, not inside the vector store.
+            knowledge_base_manager (`KnowledgeBaseManagerBase`):
+                Resolves the :class:`KnowledgeBase` runtime used to clear
+                vector store records on document deletion.
+            blob_store (`BlobStoreBase`):
+                Owns the bytes from upload until the worker is done.
+                The service writes on upload and deletes on document
+                removal.
+            message_bus (`MessageBus`):
+                Application message bus.  The service publishes one
+                index-task entry per uploaded document via
+                :func:`~agentscope.app._bus_ops.enqueue_index_task`;
+                a co-located or out-of-process
+                :class:`IndexTaskConsumer` drains and processes them.
+            resource_access_service (`ResourceAccessService`):
+                Cross-owner access resolver. Every KB lookup (read
+                *and* mutation) goes through it so shared knowledge
+                bases work end-to-end: readers see documents +
+                search hits, editors can also upload / delete.
+        """
+        self._storage = storage
+        self._manager = knowledge_base_manager
+        self._blob_store = blob_store
+        self._bus = message_bus
+        self._access = resource_access_service
+
+    # ------------------------------------------------------------------
+    # Knowledge base CRUD
+    # ------------------------------------------------------------------
+
+    async def create_knowledge_base(
+        self,
+        user_id: str,
+        name: str,
+        description: str,
+        embedding_model_config: "EmbeddingModelConfig",
+    ) -> "KnowledgeBaseRecord":
+        """Delegate creation to the manager, mapping policy errors.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+            name (`str`):
+                Display name.
+            description (`str`):
+                Free-form description.
+            embedding_model_config (`EmbeddingModelConfig`):
+                Embedding model configuration; pinned to the record.
+
+        Returns:
+            `KnowledgeBaseRecord`:
+                The newly persisted record.
+
+        Raises:
+            `HTTPException`:
+                ``409`` when the requested embedding dimension
+                violates the manager's dimension policy.
+        """
+        try:
+            return await self._manager.create_knowledge_base(
+                user_id=user_id,
+                name=name,
+                description=description,
+                embedding_model_config=embedding_model_config,
+            )
+        except DimensionPolicyError as exc:
+            raise HTTPException(
+                status_code=status.HTTP_409_CONFLICT,
+                detail=str(exc),
+            ) from exc
+
+    async def list_knowledge_bases(
+        self,
+        user_id: str,
+    ) -> "list[KnowledgeBaseRecord]":
+        """List all knowledge base records owned by the given user.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+
+        Returns:
+            `list[KnowledgeBaseRecord]`:
+                All knowledge base records belonging to the user.
+        """
+        return await self._manager.list_knowledge_bases(user_id)
+
+    async def update_knowledge_base(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+        name: str | None = None,
+        description: str | None = None,
+    ) -> "KnowledgeBaseRecord":
+        """Update mutable fields on a knowledge base, raising 404 if absent.
+
+        Only ``name`` and ``description`` are mutable.  The embedding
+        model configuration is pinned at creation time.
+        """
+        owner_id = await self._require_edit(user_id, knowledge_base_id)
+        record = await self._manager.update_knowledge_base(
+            user_id=owner_id,
+            knowledge_base_id=knowledge_base_id,
+            name=name,
+            description=description,
+        )
+        if record is None:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Knowledge base {knowledge_base_id!r} not found.",
+            )
+        return record
+
+    async def delete_knowledge_base(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+    ) -> None:
+        """Delete a knowledge base, raising 404 if absent.
+
+        Documents under the KB are cascade-deleted at the storage
+        layer; blob files referenced by those records are released
+        best-effort here so disk space is reclaimed even though the
+        manager + storage cascade would otherwise orphan them.
+        """
+        owner_id = await self._require_edit(user_id, knowledge_base_id)
+        documents = await self._storage.list_knowledge_documents(
+            owner_id,
+            knowledge_base_id,
+        )
+        for document in documents:
+            await self._delete_blob_quietly(document.data.blob_uri)
+
+        deleted = await self._manager.delete_knowledge_base(
+            owner_id,
+            knowledge_base_id,
+        )
+        if not deleted:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Knowledge base {knowledge_base_id!r} not found.",
+            )
+
+    # ------------------------------------------------------------------
+    # Document management
+    # ------------------------------------------------------------------
+
+    async def register_document(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+        filename: str,
+        stream: IO[bytes],
+        size: int,
+        content_type: str | None = None,
+    ) -> KnowledgeDocumentRecord:
+        """Persist an uploaded document and enqueue it for indexing.
+
+        Streams ``stream`` into the blob store (so the bytes never
+        live fully in memory), records a ``pending`` document, and
+        pushes an index-task entry onto the message bus.  Returns
+        immediately — a worker (in-process or dedicated) takes over
+        from here and the client tracks progress via
+        :meth:`get_document_status`.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+            knowledge_base_id (`str`):
+                The target knowledge base id.
+            filename (`str`):
+                The original filename.
+            stream (`IO[bytes]`):
+                A synchronous binary stream — typically
+                ``UploadFile.file`` from FastAPI.
+            size (`int`):
+                Byte length declared by the uploader.  Persisted on
+                the record for the UI; not authoritative.
+            content_type (`str | None`, optional):
+                IANA media type; ``None`` lets the worker fall back
+                to a filename guess at processing time.
+
+        Returns:
+            `KnowledgeDocumentRecord`:
+                The persisted record (``status='pending'``) with the
+                final ``blob_uri`` filled in.
+
+        Raises:
+            `HTTPException`:
+                ``404`` if the knowledge base does not exist.
+        """
+        # Authorise before touching the blob store: raising after a
+        # write would leave the blob orphaned. Uploading a document is
+        # a mutation, so require edit permission.
+        owner_id = await self._require_edit(user_id, knowledge_base_id)
+
+        document_id = uuid.uuid4().hex
+        blob_uri = await self._blob_store.write_stream(
+            key=f"kb/{knowledge_base_id}/{document_id}",
+            stream=stream,
+        )
+
+        record = KnowledgeDocumentRecord(
+            id=document_id,
+            user_id=owner_id,
+            knowledge_base_id=knowledge_base_id,
+            data=KnowledgeDocumentData(
+                filename=filename,
+                size=size,
+                content_type=content_type,
+                blob_uri=blob_uri,
+            ),
+        )
+        try:
+            stored = await self._storage.upsert_knowledge_document(
+                owner_id,
+                record,
+            )
+        except Exception:
+            # Storage write failed — drop the blob so the orphan
+            # sweeper doesn't later see a referenced-by-nobody file.
+            await self._delete_blob_quietly(blob_uri)
+            raise
+
+        await enqueue_index_task(
+            self._bus,
+            user_id=owner_id,
+            knowledge_base_id=knowledge_base_id,
+            document_id=document_id,
+        )
+        return stored
+
+    async def list_documents(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+    ) -> list[KnowledgeDocumentRecord]:
+        """List every document registered against a knowledge base.
+
+        Service-mode source of truth: reads from storage, NOT the
+        vector store.  Documents in ``pending`` / ``parsing`` /
+        ``chunking`` / ``indexing`` / ``error`` show up here even
+        though they have no chunks in the vector store yet.
+
+        Args:
+            user_id (`str`):
+                The viewer user id — can be the owner or a viewer
+                granted access through the resource access policy.
+            knowledge_base_id (`str`):
+                The target knowledge base id.
+
+        Returns:
+            `list[KnowledgeDocumentRecord]`:
+                Every document registered against the knowledge base,
+                in unspecified order.
+
+        Raises:
+            `HTTPException`:
+                ``404`` if the knowledge base is not visible to the
+                caller.
+        """
+        record = await self._access.resolve_knowledge_base(
+            user_id,
+            knowledge_base_id,
+        )
+        return await self._storage.list_knowledge_documents(
+            record.user_id,
+            knowledge_base_id,
+        )
+
+    async def get_document_status(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+        document_ids: list[str],
+    ) -> list[KnowledgeDocumentRecord]:
+        """Batch-fetch documents for status polling.
+
+        The endpoint backing this method accepts a comma-separated list
+        of ids so the front-end can ask "what's the state of these N
+        in-flight uploads" in a single round-trip.  Records that do
+        not exist or do not belong to the user are silently skipped —
+        the front-end may legitimately ask about a document that was
+        deleted between two polls.
+
+        Args:
+            user_id (`str`):
+                The viewer user id.
+            knowledge_base_id (`str`):
+                The target knowledge base id.
+            document_ids (`list[str]`):
+                Document ids to look up.
+
+        Returns:
+            `list[KnowledgeDocumentRecord]`:
+                One record per matched id; missing ids omitted.
+
+        Raises:
+            `HTTPException`:
+                ``404`` if the knowledge base is not visible to the
+                caller.
+        """
+        record = await self._access.resolve_knowledge_base(
+            user_id,
+            knowledge_base_id,
+        )
+        records: list[KnowledgeDocumentRecord] = []
+        for document_id in document_ids:
+            record_doc = await self._storage.get_knowledge_document(
+                record.user_id,
+                knowledge_base_id,
+                document_id,
+            )
+            if record_doc is not None:
+                records.append(record_doc)
+        return records
+
+    async def delete_document(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+        document_id: str,
+    ) -> None:
+        """Remove a document end-to-end: vector store, record, blob.
+
+        Order is chosen so that a crash mid-way always leaves a
+        recoverable state:
+
+        1. Vector store delete (idempotent — re-deleting an already
+           empty document_id is harmless).
+        2. Storage record delete.
+        3. Blob delete (idempotent).
+
+        A failure at step 1 surfaces as an exception to the caller and
+        the record + blob are left untouched, so a retry sees the same
+        state.  Failures at steps 2/3 leave a small amount of orphan
+        data but the user-visible deletion has already succeeded from
+        the vector store's point of view.
+
+        Args:
+            user_id (`str`):
+                The viewer user id — owner or shared editor.
+            knowledge_base_id (`str`):
+                The target knowledge base id.
+            document_id (`str`):
+                The document to delete.
+
+        Raises:
+            `HTTPException`:
+                ``404`` if the knowledge base is not visible to the
+                caller; ``403`` if visible but not editable.
+        """
+        owner_id = await self._require_edit(user_id, knowledge_base_id)
+        record = await self._storage.get_knowledge_document(
+            owner_id,
+            knowledge_base_id,
+            document_id,
+        )
+        if record is None:
+            # Idempotent: KB exists (edit check succeeded) but the
+            # document is already gone.
+            return
+
+        knowledge = await self._resolve_knowledge(user_id, knowledge_base_id)
+        await knowledge.delete_document(document_id)
+        await self._storage.delete_knowledge_document(
+            owner_id,
+            knowledge_base_id,
+            document_id,
+        )
+        await self._delete_blob_quietly(record.data.blob_uri)
+
+    # ------------------------------------------------------------------
+    # Search
+    # ------------------------------------------------------------------
+
+    async def search(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+        query: str,
+        top_k: int = 5,
+    ) -> "list[VectorSearchResult]":
+        """Search a knowledge base by text query.
+
+        Args:
+            user_id (`str`):
+                The viewer user id — owner or shared reader.
+            knowledge_base_id (`str`):
+                The knowledge base to search.
+            query (`str`):
+                The natural-language query.
+            top_k (`int`, defaults to ``5``):
+                Maximum number of results.
+
+        Returns:
+            `list[VectorSearchResult]`:
+                The top hits ordered by descending similarity score.
+
+        Raises:
+            `HTTPException`:
+                ``404`` if the knowledge base is not visible to the
+                caller.
+        """
+        knowledge = await self._resolve_knowledge(user_id, knowledge_base_id)
+        return await knowledge.search(queries=[query], top_k=top_k)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    async def _require_edit(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+    ) -> str:
+        """Ensure the caller can mutate this KB; return the *owner* id.
+
+        Every KB mutation writes back through the owner's storage key,
+        so a shared editor's request must be resolved to the owner id
+        before touching storage. Raises ``404`` when the KB is not
+        visible to ``user_id`` and ``403`` when it is visible but only
+        readable.
+        """
+        owner_id, _ = await self._access.resolve_for_edit(
+            user_id,
+            ResourceKind.KNOWLEDGE_BASE,
+            knowledge_base_id,
+        )
+        return owner_id
+
+    async def _resolve_knowledge(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+    ) -> "object":
+        """Resolve a :class:`KnowledgeBase` for a viewer.
+
+        Rewrites ``user_id`` to the owning user id when the caller is a
+        shared reader/editor, so the manager reads the correct
+        collection metadata from storage. ``KnowledgeBaseNotFoundError``
+        is translated to ``404``.
+        """
+        record = await self._access.resolve_knowledge_base(
+            user_id,
+            knowledge_base_id,
+        )
+        try:
+            return await self._manager.get_knowledge(
+                record.user_id,
+                knowledge_base_id,
+            )
+        except KnowledgeBaseNotFoundError as exc:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=str(exc),
+            ) from exc
+
+    async def _delete_blob_quietly(self, blob_uri: str) -> None:
+        """Best-effort blob delete — swallow backend errors.
+
+        Treated as cleanup: if the blob store is unavailable the
+        record/vector-store state is still consistent and a future
+        sweep can reclaim the disk space.  Surface only via logs.
+        """
+        try:
+            await self._blob_store.delete(blob_uri)
+        except Exception:  # noqa: BLE001 — cleanup only
+            logger.exception(
+                "Failed to delete blob %s",
+                blob_uri,
+            )
diff --git a/src/agentscope/app/_service/_model.py b/src/agentscope/app/_service/_model.py
new file mode 100644
index 0000000..6d11344
--- /dev/null
+++ b/src/agentscope/app/_service/_model.py
@@ -0,0 +1,57 @@
+# -*- coding: utf-8 -*-
+"""Model service: builds a ChatModelBase from stored credential + config."""
+from ._access import ResourceAccessService
+from ..storage import ChatModelConfig
+from ...credential import CredentialFactory
+from ...model import ChatModelBase
+
+
+async def get_model(
+    user_id: str,
+    config: ChatModelConfig,
+    access: ResourceAccessService,
+) -> ChatModelBase:
+    """Build a chat model instance from a stored credential and config.
+
+    Credentials are resolved through :class:`ResourceAccessService` so
+    both the viewer's own credentials and any shared to them via the
+    resource access policy work. Runtime paths use
+    :meth:`ResourceAccessService.resolve_credential` which returns the
+    raw record (not the masked view) — required for making real
+    provider calls.
+
+    Args:
+        user_id (`str`):
+            The viewer's user id. May differ from the credential owner
+            when the credential is shared.
+        config (`ChatModelConfig`):
+            The chat model configuration.
+        access (`ResourceAccessService`):
+            Injected resource access service.
+
+    Returns:
+        `ChatModelBase`:
+            The model instance.
+
+    Raises:
+        `HTTPException`:
+            404 when the credential is neither owned by ``user_id`` nor
+            shared to them.
+    """
+    credential_record = await access.resolve_credential(
+        user_id,
+        config.credential_id,
+    )
+
+    credential = CredentialFactory.from_dict(credential_record.data)
+    model_cls = credential.get_chat_model_class()
+    parameters = (
+        model_cls.Parameters(**config.parameters)
+        if config.parameters
+        else None
+    )
+    return model_cls(
+        credential=credential,
+        model=config.model,
+        parameters=parameters,
+    )
diff --git a/src/agentscope/app/_service/_projectors/__init__.py b/src/agentscope/app/_service/_projectors/__init__.py
new file mode 100644
index 0000000..7a3ae51
--- /dev/null
+++ b/src/agentscope/app/_service/_projectors/__init__.py
@@ -0,0 +1,13 @@
+# -*- coding: utf-8 -*-
+"""Built-in event projectors.
+
+Each projector mirrors one cross-session UI feed onto the owning
+session via the shared
+:class:`~agentscope.app._service._session_projection.SessionProjection`
+primitive. See :class:`~agentscope.app._types.EventProjector`.
+"""
+from ._subagent_hitl import SubagentHitlProjector
+
+__all__ = [
+    "SubagentHitlProjector",
+]
diff --git a/src/agentscope/app/_service/_projectors/_subagent_hitl.py b/src/agentscope/app/_service/_projectors/_subagent_hitl.py
new file mode 100644
index 0000000..fccacfd
--- /dev/null
+++ b/src/agentscope/app/_service/_projectors/_subagent_hitl.py
@@ -0,0 +1,275 @@
+# -*- coding: utf-8 -*-
+"""Projector that bridges team-member HITL events to leader sessions.
+
+When a team *member* (worker) session hits a tool call that needs human
+confirmation, the worker run parks on an ``ASKING`` tool call in its
+**own** session — invisible to a client subscribed only to the *leader*
+session's event stream. This projector mirrors each such pending
+request onto the leader session so the leader UI can render and resolve
+it, and clears it when the request is answered.
+
+It is a thin strategy over the generic
+:class:`~agentscope.app._service._session_projection.SessionProjection`
+primitive: this file holds only the HITL-specific policy (which events
+matter, how to resolve the leader, what the card payload looks like).
+The durable hash, live notification, and key conventions all live in
+the shared primitive.
+
+Persistence model (see the design doc, §2.4):
+
+- **Authoritative state** is the worker session's own ``state.context``
+  (the ``ASKING`` tool call). The projection is only a mirror.
+- The projected hash entry carries **no TTL**: a legitimate
+  confirmation can stay pending indefinitely. Stale entries (worker
+  cancelled/crashed without clearing) are healed by reconcile-on-read
+  at SSE replay time.
+"""
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+from ....event import (
+    RequireUserConfirmEvent,
+    RequireExternalExecutionEvent,
+    UserConfirmResultEvent,
+    ExternalExecutionResultEvent,
+    ReplyEndEvent,
+)
+
+if TYPE_CHECKING:
+    from ...storage import AgentRecord, SessionRecord, StorageBase
+    from ....event import AgentEvent
+    from .._session_projection import SessionProjection
+
+
+class SubagentHitlProjector:
+    """Project pending team-member HITL requests onto leader sessions.
+
+    Holds the storage handle it needs to resolve a worker's team (and
+    thus its leader). The :class:`SessionProjection` it writes through
+    is passed in per call by
+    :class:`~agentscope.app._service.ChatService`, which also resolves
+    confirm-routing and SSE replay through this projector's
+    :meth:`resolve` / :meth:`entry_id` helpers.
+    """
+
+    KIND = "subagent_hitl"
+    """Projection feed key (namespaces the entry within a session's
+    shared projection hash)."""
+
+    EVT_REQUIRE = "subagent_require_user_confirm"
+    """``CustomEvent.name`` used to push/replay a pending request to the
+    leader's event stream."""
+
+    EVT_RESULT = "subagent_user_confirm_result"
+    """``CustomEvent.name`` used to tell the leader UI a pending request
+    has been resolved and its card should be cleared."""
+
+    def __init__(self, storage: "StorageBase") -> None:
+        """Bind the storage backend.
+
+        Args:
+            storage (`StorageBase`):
+                Application storage, used to resolve the team (and hence
+                the leader session) a worker session belongs to.
+        """
+        self._storage = storage
+
+    @staticmethod
+    def entry_id(worker_session_id: str, reply_id: str) -> str:
+        """Return the projection entry id for one pending request.
+
+        Args:
+            worker_session_id (`str`):
+                The worker session that emitted the HITL request.
+            reply_id (`str`):
+                The worker-side reply id the request belongs to.
+
+        Returns:
+            `str`:
+                The entry id, ``"{worker_session_id}:{reply_id}"``.
+        """
+        return f"{worker_session_id}:{reply_id}"
+
+    async def maybe_project(
+        self,
+        user_id: str,
+        session_record: "SessionRecord",
+        agent_record: "AgentRecord",
+        event: "AgentEvent",
+        projection: "SessionProjection",
+    ) -> None:
+        """Mirror a worker HITL event onto its team's leader session.
+
+        When a *worker* session emits an HITL request, write the pending
+        card (durable entry + live notification) onto the leader; when
+        it resolves one or its reply ends, clear the card. No-op for
+        non-team sessions and for the leader session itself (a leader's
+        own HITL reaches its client directly).
+
+        Args:
+            user_id (`str`):
+                The owner of the running session.
+            session_record (`SessionRecord`):
+                The currently-running session's record.
+            agent_record (`AgentRecord`):
+                The currently-running agent's record. Whether this
+                session forwards is decided by ``session_record.team_id``
+                (and the leader check below), NOT by
+                ``agent_record.source`` — an ``AgentInvite`` borrowed
+                session runs on a ``source='user'`` record but is still
+                a team worker, so its HITL must project onto the leader.
+            event (`AgentEvent`):
+                The event just published to this session's channel.
+            projection (`SessionProjection`):
+                Shared primitive used to write the durable entry and the
+                live notification.
+        """
+        # Fast path: only sessions that participate in a team forward
+        # anything, and only for the event kinds we care about. The
+        # leader/worker distinction is made below via ``team.session_id``.
+        if not session_record.team_id:
+            return
+        if not isinstance(
+            event,
+            (
+                RequireUserConfirmEvent,
+                RequireExternalExecutionEvent,
+                UserConfirmResultEvent,
+                ExternalExecutionResultEvent,
+                ReplyEndEvent,
+            ),
+        ):
+            return
+
+        team = await self._storage.get_team(
+            user_id,
+            session_record.team_id,
+        )
+        if team is None or team.session_id == session_record.id:
+            # No team, or this IS the leader session — nothing to mirror.
+            return
+        leader_sid = team.session_id
+
+        if isinstance(
+            event,
+            (RequireUserConfirmEvent, RequireExternalExecutionEvent),
+        ):
+            payload = {
+                "worker_session_id": session_record.id,
+                "worker_agent_id": agent_record.id,
+                "worker_agent_name": agent_record.data.name,
+                "reply_id": event.reply_id,
+                "event_type": (
+                    "require_user_confirm"
+                    if isinstance(event, RequireUserConfirmEvent)
+                    else "require_external_execution"
+                ),
+                "event": event.model_dump(mode="json"),
+                "created_at": datetime.now().isoformat(),
+            }
+            await projection.upsert(
+                leader_sid,
+                self.KIND,
+                self.entry_id(session_record.id, event.reply_id),
+                payload,
+            )
+            await projection.publish(leader_sid, self.EVT_REQUIRE, payload)
+        else:
+            # Clear the pending card. ``ReplyEndEvent`` is the primary
+            # clear signal (the resume's continuation event is NOT
+            # republished through the stream); the explicit result
+            # events clear early when they do flow through. All are
+            # idempotent — deleting an already-gone entry is a no-op.
+            await projection.delete(
+                leader_sid,
+                self.KIND,
+                self.entry_id(session_record.id, event.reply_id),
+            )
+            await projection.publish(
+                leader_sid,
+                self.EVT_RESULT,
+                {
+                    "worker_session_id": session_record.id,
+                    "reply_id": event.reply_id,
+                },
+            )
+
+    @classmethod
+    async def resolve(
+        cls,
+        projection: "SessionProjection",
+        leader_sid: str,
+        reply_id: str,
+    ) -> dict | None:
+        """Find the pending entry for ``reply_id`` under a leader.
+
+        Used by the confirm-routing entry point (the chat router): given
+        a confirm result POSTed to the leader session, locate which
+        worker session it actually belongs to so the result can be
+        forwarded there.
+
+        Args:
+            projection (`SessionProjection`):
+                The shared projection store to scan.
+            leader_sid (`str`):
+                The leader session the confirm result was POSTed to.
+            reply_id (`str`):
+                The worker-side reply id carried by the confirm result.
+
+        Returns:
+            `dict | None`:
+                The stored payload (with ``worker_session_id`` /
+                ``worker_agent_id``), or ``None`` when no pending entry
+                matches — meaning the confirm is the leader's own.
+        """
+        for entry in await projection.list(leader_sid, cls.KIND):
+            if entry.get("reply_id") == reply_id:
+                return entry
+        return None
+
+    @classmethod
+    async def purge(
+        cls,
+        projection: "SessionProjection",
+        leader_sid: str,
+    ) -> None:
+        """Drop every pending HITL entry for a leader session.
+
+        Used when the leader session (or its team) is deleted. Scoped to
+        this feed so other projections on the same session survive.
+
+        Args:
+            projection (`SessionProjection`):
+                The shared projection store.
+            leader_sid (`str`):
+                The leader session to purge.
+        """
+        await projection.purge(leader_sid, cls.KIND)
+
+    @classmethod
+    async def drop_worker(
+        cls,
+        projection: "SessionProjection",
+        leader_sid: str,
+        worker_sid: str,
+    ) -> None:
+        """Drop every pending entry that originated from one worker.
+
+        Used when a single worker session is deleted while the leader
+        survives.
+
+        Args:
+            projection (`SessionProjection`):
+                The shared projection store.
+            leader_sid (`str`):
+                The leader session the entries are projected onto.
+            worker_sid (`str`):
+                The worker session whose entries should be dropped.
+        """
+        for entry in await projection.list(leader_sid, cls.KIND):
+            if entry.get("worker_session_id") == worker_sid:
+                await projection.delete(
+                    leader_sid,
+                    cls.KIND,
+                    cls.entry_id(worker_sid, entry["reply_id"]),
+                )
diff --git a/src/agentscope/app/_service/_session.py b/src/agentscope/app/_service/_session.py
new file mode 100644
index 0000000..3a67d7e
--- /dev/null
+++ b/src/agentscope/app/_service/_session.py
@@ -0,0 +1,687 @@
+# -*- coding: utf-8 -*-
+"""Cross-resource session lifecycle service.
+
+Owns the "stop in-flight runs + delete records + drop bus state"
+cascades that ``DELETE /sessions/{sid}``, ``DELETE /agents/{aid}``,
+``DELETE /schedules/{sid}`` and the agent-facing
+:class:`~agentscope.app._tools.TeamDelete` /
+:class:`~agentscope.app._manager._scheduler._tools.ScheduleDelete`
+tools all share.
+
+Layering
+========
+
+Methods deliberately delegate down the cascade so the bus-touching
+logic lives in exactly one place — :meth:`delete_session`. Higher-level
+methods only orchestrate which sessions to delete, then ask storage
+to clean its own non-session scope (records, indexes, back-refs).
+
+::
+
+    delete_session    ← atomic: cancel run, storage.delete_session,
+                        bus.session_purge
+        │
+    delete_team       → service.delete_agent per worker
+                      → storage.delete_team    (record + leader detach)
+        │
+    delete_agent      → service.delete_session per session
+                      → service.delete_schedule per owned schedule
+                      → storage.delete_agent   (agent record + team back-refs)
+        │
+    delete_schedule   → service.delete_session per spawned session
+                      → storage.delete_schedule (schedule record + indexes)
+
+Storage's own internal cascades (e.g.
+``storage.delete_agent`` re-iterating sessions) become idempotent
+no-ops because the records are already gone — they still execute, but
+do no work and never touch the bus, so the storage layer stays
+unaware of the message bus.
+
+Separation of concerns
+======================
+
+Storage and message bus are treated as distinct backends — they may
+live in different databases in the future. The service is the **only**
+component that touches both in the same call. Storage code never
+imports the bus; bus code never imports storage.
+"""
+import asyncio
+from enum import StrEnum
+
+from ..message_bus import MessageBus, MessageBusKeys
+from ..storage import StorageBase
+from ..storage._utils import _ensure_team_members
+from ._session_projection import SessionProjection
+from ._projectors import SubagentHitlProjector
+from ..._logging import logger
+from ...message import ToolCallState
+
+
+class SessionStatus(StrEnum):
+    """The high-level status of a session, unifying cluster liveness
+    (from the message bus) with the durable tool-call parking state
+    (from the persisted :class:`~agentscope.state.AgentState.context`).
+
+    Exactly one value applies at any moment — the frontend renders a
+    single indicator without having to reconcile multiple boolean
+    flags.
+
+    Precedence: ``RUNNING`` is decided first from the distributed
+    session-run lock; only when the session is not held by any worker
+    do the ``AWAITING_*`` / ``IDLE`` values (derived from the stored
+    context tail) apply. This ordering reflects the ground-truth
+    hierarchy — while a worker owns the run, the live in-memory state
+    supersedes the persisted snapshot, which is by definition stale
+    until the run yields.
+
+    Values:
+        - ``RUNNING``: a worker somewhere in the cluster currently
+          holds the session's run lease on the message bus.
+        - ``IDLE``: no worker is running the session, and its
+          persisted context is not parked on any pending tool call.
+        - ``AWAITING_PERMISSION``: no worker is running the session,
+          and the persisted context tail has at least one tool call
+          waiting for user permission confirmation (HITL).
+        - ``AWAITING_EXTERNAL_RESULT``: no worker is running the
+          session, and the persisted context tail has at least one
+          tool call dispatched to an external executor and awaiting
+          its result (with no peer awaiting permission).
+    """
+
+    RUNNING = "running"
+    IDLE = "idle"
+    AWAITING_PERMISSION = "awaiting_permission"
+    AWAITING_EXTERNAL_RESULT = "awaiting_external_result"
+
+
+class SessionService:
+    """Cancel in-flight chat runs and cascade-delete related records.
+
+    The cancel side broadcasts via
+    :meth:`MessageBus.session_publish_cancel`, then polls
+    :meth:`MessageBus.session_is_running` until the run-lock clears or
+    a timeout expires — so the implementation is multi-process and
+    multi-node by construction.
+
+    Args:
+        storage (`StorageBase`):
+            Persistent storage backend. Owns durable records and their
+            cascades among themselves.
+        message_bus (`MessageBus`):
+            Live message bus. Owns transient per-session state (events
+            log, inbox, run-lock, cancel channel).
+    """
+
+    _CANCEL_POLL_INTERVAL_SECS: float = 0.1
+    """Interval between :meth:`MessageBus.session_is_running` polls
+    while waiting for a cancelled run to release its distributed
+    run-lock."""
+
+    def __init__(
+        self,
+        storage: StorageBase,
+        message_bus: MessageBus,
+    ) -> None:
+        """Bind dependencies.
+
+        Args:
+            storage (`StorageBase`): Persistent storage backend.
+            message_bus (`MessageBus`): Live message bus.
+        """
+        self._storage = storage
+        self._bus = message_bus
+        self._projection = SessionProjection(message_bus)
+
+    # ------------------------------------------------------------------
+    # Status
+    # ------------------------------------------------------------------
+
+    async def get_session_status(
+        self,
+        user_id: str,
+        agent_id: str,
+        session_id: str,
+    ) -> SessionStatus | None:
+        """Return the unified :class:`SessionStatus` for a session.
+
+        The status collapses two orthogonal signals into a single
+        four-valued enum:
+
+        - cluster liveness comes from the distributed session-run lock
+          on the shared message bus (Redis in production) — the answer
+          is cluster-wide, so any worker in the deployment holding the
+          lease yields ``RUNNING`` regardless of which API replica
+          serves the caller;
+        - the parked state (``AWAITING_PERMISSION`` /
+          ``AWAITING_EXTERNAL_RESULT`` / ``IDLE``) is derived from the
+          persisted ``AgentState.context`` tail, and only applies when
+          no worker owns the run.
+
+        The ``RUNNING`` check is performed **before** loading the
+        persisted context: while a worker owns the run, the live
+        in-memory state supersedes the stored snapshot, and the parked
+        derivation would be stale. This also saves a storage round-trip
+        in the hot ``RUNNING`` case.
+
+        .. note::
+            The run lease auto-expires after
+            ``MessageBusKeys.SESSION_RUN_TTL_SECS`` and is refreshed by
+            the owning worker while it is actively producing events, so
+            a crashed worker's session flips out of ``RUNNING`` on
+            lease expiry.
+
+        Args:
+            user_id (`str`):
+                The authenticated user id (ownership check).
+            agent_id (`str`):
+                The agent that owns the session (ownership check).
+            session_id (`str`):
+                The session to probe.
+
+        Returns:
+            `SessionStatus | None`:
+                The unified status, or ``None`` if the session does
+                not exist or is not owned by the user.
+        """
+        # RUNNING is checked first: while a worker owns the lease, the
+        # persisted context is by definition a stale snapshot, and we
+        # save a storage round-trip.
+        if await self._bus.is_locked(
+            MessageBusKeys.session_lock(session_id),
+        ):
+            return SessionStatus.RUNNING
+
+        session = await self._storage.get_session(
+            user_id,
+            agent_id,
+            session_id,
+        )
+        if session is None:
+            return None
+
+        return self._derive_parked_status(session.state.context)
+
+    @staticmethod
+    def _derive_parked_status(context: list) -> SessionStatus:
+        """Derive the parked :class:`SessionStatus` from a persisted
+        ``AgentState.context``.
+
+        Only the tail assistant message is inspected — a paused reply
+        can only park pending tool calls at the very end of the
+        context. ``AWAITING_PERMISSION`` wins over
+        ``AWAITING_EXTERNAL_RESULT`` when both appear on the tail: no
+        submitted call can complete while a peer is still awaiting user
+        confirmation, so the caller-visible status is dominated by the
+        blocker.
+
+        Callers must first ensure the session is not currently held by
+        any worker (see :attr:`SessionStatus.RUNNING`) — while a worker
+        owns the run, the live in-memory state supersedes the persisted
+        snapshot and this function's answer is by definition stale.
+
+        Args:
+            context (`list[Msg]`):
+                The persisted ``AgentState.context`` list.
+
+        Returns:
+            `SessionStatus`:
+                One of ``AWAITING_PERMISSION``,
+                ``AWAITING_EXTERNAL_RESULT``, or ``IDLE``.
+        """
+        if not context:
+            return SessionStatus.IDLE
+        last_msg = context[-1]
+        if last_msg.role != "assistant":
+            return SessionStatus.IDLE
+        tool_calls = last_msg.get_content_blocks("tool_call")
+        if not tool_calls:
+            return SessionStatus.IDLE
+        if any(tc.state == ToolCallState.ASKING for tc in tool_calls):
+            return SessionStatus.AWAITING_PERMISSION
+        if any(tc.state == ToolCallState.SUBMITTED for tc in tool_calls):
+            return SessionStatus.AWAITING_EXTERNAL_RESULT
+        return SessionStatus.IDLE
+
+    # ------------------------------------------------------------------
+    # Cancel
+    # ------------------------------------------------------------------
+
+    async def cancel_session_run(
+        self,
+        session_id: str,
+        *,
+        timeout: float = 10.0,
+    ) -> bool:
+        """Broadcast a session cancel and wait for the chat-run lock to
+        clear.
+
+        Publishes one cancel payload on the bus's shared cancel channel,
+        unconditionally. Every process's
+        :class:`~agentscope.app._manager.CancelDispatcher` reacts to the
+        broadcast by cancelling whatever it locally holds for the
+        session — the chat-run asyncio task **and** any background
+        tasks owned by that session. The publisher does not need to
+        know which worker holds which piece.
+
+        After publishing, polls
+        :meth:`MessageBus.session_is_running` until the distributed
+        chat-run lock clears. Only the chat run holds a distributed
+        lock; BG tasks do not, so this poll only waits for the chat
+        run. Returns immediately when no chat run was active.
+
+        Idempotent: calling on an idle session just sends a no-op
+        broadcast and observes a clear lock.
+
+        Args:
+            session_id (`str`):
+                The session whose chat run + BG tasks should be
+                cancelled.
+            timeout (`float`, defaults to ``10.0``):
+                Maximum seconds to wait for the chat-run lock to
+                release. On timeout the method returns ``False`` so
+                callers can proceed (e.g. with cascade delete) instead
+                of hanging on a process that may have died.
+
+        Returns:
+            `bool`:
+                ``True`` if the chat-run lock was confirmed released
+                within ``timeout`` seconds (or was never held).
+                ``False`` if the lock was still held when the timeout
+                expired.
+        """
+        await self._bus.publish(
+            MessageBusKeys.session_cancel_channel(),
+            {"session_id": session_id},
+        )
+
+        deadline = asyncio.get_event_loop().time() + timeout
+        while True:
+            if not await self._bus.is_locked(
+                MessageBusKeys.session_lock(session_id),
+            ):
+                return True
+            if asyncio.get_event_loop().time() >= deadline:
+                logger.warning(
+                    "Session %s did not release its run-lock within "
+                    "%.1fs after cancel; proceeding anyway.",
+                    session_id,
+                    timeout,
+                )
+                return False
+            await asyncio.sleep(self._CANCEL_POLL_INTERVAL_SECS)
+
+    # ------------------------------------------------------------------
+    # Delete cascades — every higher-level method delegates to
+    # ``delete_session`` so the cancel + bus-purge logic exists in
+    # exactly one place.
+    # ------------------------------------------------------------------
+
+    async def delete_session(
+        self,
+        user_id: str,
+        agent_id: str,
+        session_id: str,
+    ) -> bool:
+        """Cancel, delete and bus-purge a single session.
+
+        This is the atomic primitive — every other cascade delegates
+        here for per-session work.
+
+        Steps:
+
+        1. Cancel any in-flight run for ``session_id`` (cross-process
+           via the bus cancel channel).
+        2. Delete the session record (and its storage-side cascade:
+           message log, schedule-session index, team dissolution when
+           this session leads one — recursive into worker agents).
+        3. Purge transient bus state for ``session_id`` (events log,
+           inbox).
+
+        Worker sessions that storage cascades through are picked up
+        here too: when this session is a team leader,
+        ``storage.delete_session`` calls ``storage.delete_team`` →
+        ``storage.delete_agent`` → ``storage.delete_session`` for each
+        worker, and we mirror that on the bus side by purging worker
+        sessions identified up front via
+        :meth:`_team_worker_session_ids`.
+
+        Args:
+            user_id (`str`): The owner user id.
+            agent_id (`str`): The agent that owns the session.
+            session_id (`str`): The session to delete.
+
+        Returns:
+            `bool`:
+                ``True`` if the session record existed and was deleted,
+                ``False`` otherwise. Mirrors
+                :meth:`StorageBase.delete_session`.
+        """
+        # Identify all bus-purge targets before storage mutates anything.
+        worker_sids = await self._team_worker_session_ids(
+            user_id,
+            agent_id,
+            session_id,
+        )
+        all_sids = [session_id, *worker_sids]
+
+        # Clean leader-side subagent HITL projections before storage
+        # cascades remove the records we need to resolve roles from.
+        await self._purge_subagent_hitl(user_id, agent_id, session_id)
+
+        await self._cancel_runs(all_sids)
+        deleted = await self._storage.delete_session(
+            user_id,
+            agent_id,
+            session_id,
+        )
+        await self._purge_bus(all_sids)
+        return deleted
+
+    async def delete_team(self, user_id: str, team_id: str) -> bool:
+        """Cancel, delete and bus-purge a team.
+
+        With :meth:`StorageBase.delete_team` now role-aware, the service
+        method's sole responsibility is to run per-member
+        ``cancel + bus purge`` (storage cannot touch the bus) via the
+        role-appropriate ``delete_agent`` / ``delete_session`` call, and
+        then delegate to storage for the remaining leader-detach +
+        team-record cleanup.
+
+        Branches per member role:
+
+        - ``role == "created"``: the member was spawned by ``AgentCreate``
+          and lives only as long as the team — delegate to
+          :meth:`delete_agent` so its record, session, and bus state
+          are fully removed.
+        - ``role == "invited"``: the member is a pre-existing user-owned
+          agent borrowed via ``AgentInvite``. Only the borrowed
+          team-scoped session is removed; the underlying
+          :class:`AgentRecord` and its other sessions survive.
+
+        The leader's own session is **not** deleted — teams dissolve,
+        leaders survive (and have their ``team_id`` cleared by
+        ``storage.delete_team``).
+
+        Args:
+            user_id (`str`): The owner user id.
+            team_id (`str`): The team to dissolve.
+
+        Returns:
+            `bool`:
+                ``True`` if the team record existed and was deleted.
+        """
+        team = await self._storage.get_team(user_id, team_id)
+        if team is None:
+            # Still call storage.delete_team so it can clean any index
+            # residue, but the return value will be False.
+            return await self._storage.delete_team(user_id, team_id)
+
+        members = await _ensure_team_members(self._storage, user_id, team)
+        for member in members:
+            if member.role == "created":
+                await self.delete_agent(member.owner_id, member.agent_id)
+            else:  # invited
+                await self.delete_session(
+                    member.owner_id,
+                    member.agent_id,
+                    member.session_id,
+                )
+
+        # storage.delete_team walks the same members again to run its
+        # own role-aware cascade — those calls are now idempotent
+        # no-ops (records already removed above). What remains for
+        # storage is leader-detach + team-record + index cleanup.
+        return await self._storage.delete_team(user_id, team_id)
+
+    async def delete_agent(self, user_id: str, agent_id: str) -> bool:
+        """Cancel, delete and bus-purge every session and schedule
+        owned by an agent, then drop the agent record.
+
+        Delegates per-session work to :meth:`delete_session` and
+        per-schedule work to :meth:`delete_schedule`, then asks
+        storage to clean the remaining agent-scoped state (the agent
+        record, the agent index entry, and any team back-references).
+
+        **Reverse-cascade for invited members.** When an agent is
+        borrowed into a team (``AgentInvite``), it has a session with
+        ``team_id`` set that it does not lead. Deleting the agent while
+        such a borrowed session exists would leave a stale
+        :class:`TeamMember` entry behind, and — worse — trigger the
+        storage cascade in that team's next ``delete_team``, which
+        iterates the team roster (via ``_ensure_team_members``) and
+        would try to re-delete this already-gone agent. So before
+        deleting each session, this method extracts the corresponding
+        entry from the borrowing team's roster (matched by
+        ``session_id``, not ``agent_id``, so a leader session that
+        happens to share the agent id — impossible today but cheap to
+        be careful about — is not touched).
+
+        Args:
+            user_id (`str`): The owner user id.
+            agent_id (`str`): The agent to delete.
+
+        Returns:
+            `bool`:
+                ``True`` if the agent record existed and was deleted.
+        """
+        for session in await self._storage.list_sessions(user_id, agent_id):
+            if session.team_id is not None:
+                team = await self._storage.get_team(
+                    user_id,
+                    session.team_id,
+                )
+                # Only worker sessions require the extraction — a leader
+                # session dropping its team is handled by
+                # ``storage.delete_session -> delete_team`` further down.
+                if team is not None and team.session_id != session.id:
+                    members = await _ensure_team_members(
+                        self._storage,
+                        user_id,
+                        team,
+                    )
+                    filtered = [
+                        m for m in members if m.session_id != session.id
+                    ]
+                    if len(filtered) != len(members):
+                        team.data.members = filtered
+                        team.data.member_ids = [
+                            mid
+                            for mid in team.data.member_ids
+                            if mid != agent_id
+                        ]
+                        await self._storage.upsert_team(user_id, team)
+            await self.delete_session(user_id, agent_id, session.id)
+
+        for schedule in await self._storage.list_schedules(user_id):
+            if schedule.agent_id == agent_id:
+                await self.delete_schedule(user_id, schedule.id)
+
+        # storage.delete_agent re-iterates sessions and schedules —
+        # those re-runs are idempotent no-ops because the records were
+        # already removed above. What remains is the agent record,
+        # the agent index entry, and team back-reference scrubbing.
+        return await self._storage.delete_agent(user_id, agent_id)
+
+    async def delete_schedule(
+        self,
+        user_id: str,
+        schedule_id: str,
+    ) -> bool:
+        """Cancel, delete and bus-purge every session spawned by a
+        schedule, then drop the schedule record.
+
+        Args:
+            user_id (`str`): The owner user id.
+            schedule_id (`str`): The schedule to delete.
+
+        Returns:
+            `bool`:
+                ``True`` if the schedule record existed and was deleted.
+        """
+        for session in await self._storage.list_sessions_by_schedule(
+            user_id,
+            schedule_id,
+        ):
+            await self.delete_session(
+                user_id,
+                session.agent_id,
+                session.id,
+            )
+
+        # storage.delete_schedule re-iterates the same sessions —
+        # idempotent no-ops; only schedule record + indexes remain.
+        return await self._storage.delete_schedule(user_id, schedule_id)
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    async def _team_worker_session_ids(
+        self,
+        user_id: str,
+        agent_id: str,
+        session_id: str,
+    ) -> list[str]:
+        """Return the session ids of every worker in the team that
+        ``session_id`` leads, or ``[]`` when the session does not lead
+        a team.
+
+        Mirrors :meth:`StorageBase.delete_session`'s own team-leader
+        cascade so the bus side can purge the same sessions.
+
+        Uses :func:`ensure_team_members` — which carries the exact
+        session id per member (including invited members whose agent
+        can have multiple sessions of its own, only one of which
+        belongs to this team). Falling back to
+        ``list_sessions(agent_id)[0]`` here would pick the wrong
+        session for invited agents.
+
+        Args:
+            user_id (`str`): The owner user id.
+            agent_id (`str`):
+                The agent that owns ``session_id``. May be empty when
+                unknown; team-leader lookup does not depend on it.
+            session_id (`str`):
+                The candidate leader session.
+
+        Returns:
+            `list[str]`:
+                Worker session ids, empty when this session is not a
+                team leader.
+        """
+        session = await self._storage.get_session(
+            user_id,
+            agent_id,
+            session_id,
+        )
+        if session is None or not session.team_id:
+            return []
+        team = await self._storage.get_team(user_id, session.team_id)
+        if team is None or team.session_id != session_id:
+            return []
+        members = await _ensure_team_members(self._storage, user_id, team)
+        return [m.session_id for m in members]
+
+    async def _cancel_runs(self, session_ids: list[str]) -> None:
+        """Cancel every in-flight run in ``session_ids`` concurrently.
+
+        Args:
+            session_ids (`list[str]`):
+                Sessions whose runs should be cancelled.
+        """
+        if not session_ids:
+            return
+        await asyncio.gather(
+            *(self.cancel_session_run(sid) for sid in session_ids),
+        )
+
+    async def _purge_bus(self, session_ids: list[str]) -> None:
+        """Drop bus state (events log + inbox) for each id concurrently.
+
+        Args:
+            session_ids (`list[str]`):
+                Sessions whose bus state should be purged.
+        """
+        if not session_ids:
+            return
+        await asyncio.gather(
+            *(self._purge_session_bus(sid) for sid in session_ids),
+        )
+
+    async def _purge_session_bus(self, session_id: str) -> None:
+        """Drop all per-session bus state for one session."""
+        await self._bus.log_trim(
+            MessageBusKeys.session_events(session_id),
+        )
+        await self._bus.queue_delete(
+            MessageBusKeys.inbox(session_id),
+        )
+        await self._bus.registry_drop(
+            MessageBusKeys.bg_tasks(session_id),
+        )
+
+    async def _purge_subagent_hitl(
+        self,
+        user_id: str,
+        agent_id: str,
+        session_id: str,
+    ) -> None:
+        """Clean leader-side subagent HITL projections for a session
+        about to be deleted (design §3.7).
+
+        Two cases, resolved from the session's role:
+
+        - **Leader session** (it leads a team): purge the entire hash
+          keyed by this session — every projected member card goes.
+        - **Worker session** (it has a ``team_id`` but is not the
+          leader): drop just this worker's entries from the *leader's*
+          hash, leaving sibling members' cards intact.
+
+        Must run before storage cascades remove the team / session
+        records this resolution depends on. Failures are swallowed — a
+        stale projection is self-healed by reconcile-on-read and must
+        not block the delete cascade.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+            agent_id (`str`):
+                The agent that owns ``session_id``.
+            session_id (`str`):
+                The session being deleted.
+        """
+        try:
+            session = await self._storage.get_session(
+                user_id,
+                agent_id,
+                session_id,
+            )
+            if session is None or not session.team_id:
+                # Not in a team — also clear any hash that may have been
+                # created with this session as a (future) leader key.
+                await SubagentHitlProjector.purge(self._projection, session_id)
+                return
+
+            team = await self._storage.get_team(user_id, session.team_id)
+            if team is None:
+                await SubagentHitlProjector.purge(self._projection, session_id)
+                return
+
+            if team.session_id == session_id:
+                # Leader session — drop the whole projection store.
+                await SubagentHitlProjector.purge(self._projection, session_id)
+            else:
+                # Worker session — drop only its entries from the
+                # leader's store.
+                await SubagentHitlProjector.drop_worker(
+                    self._projection,
+                    team.session_id,
+                    session_id,
+                )
+        except Exception as e:  # pylint: disable=broad-except
+            logger.warning(
+                "Failed to purge subagent HITL projection for session "
+                "%s: %s",
+                session_id,
+                str(e),
+            )
diff --git a/src/agentscope/app/_service/_session_projection.py b/src/agentscope/app/_service/_session_projection.py
new file mode 100644
index 0000000..bf6f33d
--- /dev/null
+++ b/src/agentscope/app/_service/_session_projection.py
@@ -0,0 +1,186 @@
+# -*- coding: utf-8 -*-
+"""Generic cross-session UI projection primitive.
+
+A *projection* mirrors a UI card owned by one session onto another
+session's event stream, so a client subscribed only to the target
+session can render and resolve it. The canonical use is team HITL: a
+worker (member) session parks on a tool call awaiting confirmation in
+its own session — invisible to a client watching only the *leader* —
+so the pending request is projected onto the leader.
+
+This class is **pure mechanism**: it knows nothing about teams,
+workers, leaders, or HITL. It is the reusable substrate every such
+feature shares — a durable per-session hash plus a live notification —
+so a new projection feature is a small strategy object (an
+``EventProjector``) over this primitive, not a new bus wrapper class.
+
+Backed entirely by the message-bus generic registry primitives
+(``registry_*``) and :meth:`MessageBus.session_publish_event`; no
+business methods are added to ``MessageBus``. Key conventions live in
+:class:`~agentscope.app.message_bus.MessageBusKeys`.
+
+Persistence model:
+
+- The Redis hash is the **only durable** record of a projected card —
+  the target session's event channel (replay log + pub/sub) is not
+  durable across runs. It carries **no TTL**: a legitimate card can
+  stay pending indefinitely. Authoritative truth for whether a card is
+  still live lives in the *owning* session's own state; stale hash
+  entries are healed by reconcile-on-read at SSE replay time, not by
+  expiry.
+- ``kind`` partitions the hash so one target session can host several
+  independent feeds (HITL, progress, errors, …) without collision.
+"""
+import json
+from typing import TYPE_CHECKING
+
+from ..message_bus import MessageBusKeys
+from .._bus_ops import publish_session_event
+from ...event import CustomEvent
+
+if TYPE_CHECKING:
+    from ..message_bus import MessageBus
+
+
+class SessionProjection:
+    """Durable per-session store of UI cards projected from elsewhere.
+
+    A thin stateless wrapper around the message bus — construct one
+    wherever needed (it holds only a bus reference). Entries are grouped
+    per ``(target_session_id, kind)``; within a feed each entry is keyed
+    by a caller-chosen ``entry_id``.
+
+    Live notification piggybacks on the target session's existing event
+    channel via :meth:`publish`, so front-ends receive updates over the
+    same ``GET /sessions/{sid}/stream`` SSE connection they already use.
+    """
+
+    def __init__(self, message_bus: "MessageBus") -> None:
+        """Bind the message bus.
+
+        Args:
+            message_bus (`MessageBus`):
+                Application message bus; only its generic ``registry_*``
+                primitives and :meth:`session_publish_event` are used.
+        """
+        self._bus = message_bus
+
+    async def upsert(
+        self,
+        target_sid: str,
+        kind: str,
+        entry_id: str,
+        payload: dict,
+    ) -> None:
+        """Persist (or overwrite) one projected entry.
+
+        Args:
+            target_sid (`str`):
+                The session the entry is projected onto.
+            kind (`str`):
+                The projection feed (e.g. ``"subagent_hitl"``).
+            entry_id (`str`):
+                Identity of the entry within the feed.
+            payload (`dict`):
+                The entry to store (JSON-serializable).
+        """
+        await self._bus.registry_set(
+            MessageBusKeys.projection_namespace(target_sid),
+            MessageBusKeys.projection_field(kind, entry_id),
+            json.dumps(payload, ensure_ascii=False),
+        )
+
+    async def delete(
+        self,
+        target_sid: str,
+        kind: str,
+        entry_id: str,
+    ) -> None:
+        """Remove one projected entry.
+
+        Idempotent: a no-op when the entry is already gone.
+
+        Args:
+            target_sid (`str`):
+                The session the entry was projected onto.
+            kind (`str`):
+                The projection feed.
+            entry_id (`str`):
+                Identity of the entry within the feed.
+        """
+        await self._bus.registry_del(
+            MessageBusKeys.projection_namespace(target_sid),
+            MessageBusKeys.projection_field(kind, entry_id),
+        )
+
+    async def list(self, target_sid: str, kind: str) -> list[dict]:
+        """Return every entry in one feed for a target session.
+
+        Args:
+            target_sid (`str`):
+                The session whose projections to read.
+            kind (`str`):
+                The projection feed to filter by.
+
+        Returns:
+            `list[dict]`:
+                All stored payloads in the feed; empty when none.
+        """
+        raw = await self._bus.registry_getall(
+            MessageBusKeys.projection_namespace(target_sid),
+        )
+        prefix = MessageBusKeys.projection_field_prefix(kind)
+        return [
+            json.loads(value)
+            for field, value in raw.items()
+            if field.startswith(prefix)
+        ]
+
+    async def purge(self, target_sid: str, kind: str | None = None) -> None:
+        """Drop projected entries for a target session.
+
+        Args:
+            target_sid (`str`):
+                The session to purge.
+            kind (`str | None`, optional):
+                When given, drop only that feed's entries (preserving
+                other feeds on the same session). When ``None``, drop
+                the session's entire projection store in one shot.
+        """
+        if kind is None:
+            await self._bus.registry_drop(
+                MessageBusKeys.projection_namespace(target_sid),
+            )
+            return
+        ns = MessageBusKeys.projection_namespace(target_sid)
+        prefix = MessageBusKeys.projection_field_prefix(kind)
+        raw = await self._bus.registry_getall(ns)
+        for field in raw:
+            if field.startswith(prefix):
+                await self._bus.registry_del(ns, field)
+
+    async def publish(
+        self,
+        target_sid: str,
+        event_name: str,
+        value: dict,
+    ) -> None:
+        """Send a live ``CustomEvent`` to a target session's channel.
+
+        Notifies front-ends subscribed to the target session that a
+        projected card should be rendered or cleared.
+
+        Args:
+            target_sid (`str`):
+                The session to notify.
+            event_name (`str`):
+                The ``CustomEvent.name`` carried to the front-end.
+            value (`dict`):
+                The event payload.
+        """
+        custom = CustomEvent(name=event_name, value=value)
+        await publish_session_event(
+            self._bus,
+            target_sid,
+            custom.model_dump(mode="json"),
+        )
diff --git a/src/agentscope/app/_service/_toolkit.py b/src/agentscope/app/_service/_toolkit.py
new file mode 100644
index 0000000..d0c6ef9
--- /dev/null
+++ b/src/agentscope/app/_service/_toolkit.py
@@ -0,0 +1,251 @@
+# -*- coding: utf-8 -*-
+"""Toolkit assembly for an (agent, session) pair.
+
+The single entry point :func:`get_toolkit` gathers every tool source —
+workspace builtins, MCPs, skills, planning tools (Task*), background-task
+control (ToolStop), schedule control (Schedule*), team participation
+tools, and caller-supplied extras — into one :class:`Toolkit`.
+"""
+from typing import Any, Literal
+
+from .._manager import BackgroundTaskManager, SchedulerManager
+from ..message_bus import MessageBus
+from .._tool import (
+    AgentCreate,
+    AgentInvite,
+    TeamCreate,
+    TeamDelete,
+    TeamSay,
+)
+from .._types import AgentToolFactory, SubAgentTemplate
+from ..storage import AgentRecord, SessionRecord, StorageBase
+from ..workspace_manager import WorkspaceManagerBase
+from ...middleware import MiddlewareBase
+from ...tool import (
+    TaskCreate,
+    TaskGet,
+    TaskList,
+    TaskUpdate,
+    Toolkit,
+    ToolGroup,
+)
+from ...workspace import WorkspaceBase
+from ..access import ResourceKind
+from ._access import ResourceAccessService
+
+
+async def get_toolkit(
+    *,
+    storage: StorageBase,
+    workspace: WorkspaceBase,
+    workspace_manager: WorkspaceManagerBase,
+    scheduler_manager: SchedulerManager,
+    background_task_manager: BackgroundTaskManager,
+    message_bus: MessageBus,
+    middlewares: list[MiddlewareBase],
+    user_id: str,
+    agent_record: AgentRecord,
+    session_record: SessionRecord,
+    resource_access_service: ResourceAccessService,
+    extra_factory: AgentToolFactory | None = None,
+    sub_agent_templates: dict[str, SubAgentTemplate] | None = None,
+) -> Toolkit:
+    """Assemble the complete :class:`Toolkit` for one chat turn.
+
+    Tool sources (in attachment order):
+
+    1. Workspace builtins (Bash / Read / Write / Grep / …)
+    2. Planning tools (:class:`TaskCreate` / :class:`TaskList` /
+       :class:`TaskGet` / :class:`TaskUpdate`)
+    3. Background-task control (:class:`ToolStop`, from
+       :meth:`BackgroundTaskManager.list_tools`)
+    4. Schedule control (:class:`ScheduleCreate` / :class:`ScheduleView`
+       / :class:`ScheduleDelete` / :class:`ScheduleList`, from
+       :meth:`SchedulerManager.list_tools`). Only attached when the
+       session has a model configured (Schedule tools need a model to
+       fire new chats with).
+    5. Team tools — variant based on the *session's* team role, not
+       the agent's ``source``. This matters because a borrowed
+       ("invited") agent's session must see worker-only tools even
+       though its underlying :class:`AgentRecord` still has
+       ``source='user'``. A session that is a worker in some team
+       gets only ``TeamSay``. A session that is not in any team OR
+       that is its team's leader gets the full leader-side toolset
+       (``TeamCreate / AgentCreate / TeamSay / TeamDelete``, plus
+       ``AgentInvite`` when the user has at least one invitable agent).
+    6. Caller-supplied extras (``extra_factory``)
+
+    Plus the workspace's skills and MCPs, which become the toolkit's
+    ``skills_or_loaders`` and ``mcps`` parameters.
+
+    Args:
+        storage (`StorageBase`):
+            Application storage backend; needed by team tools to read
+            fresh team / session state at call time, and by schedule
+            tools.
+        workspace (`WorkspaceBase`):
+            Pre-resolved per-session workspace (caller resolves it
+            via :meth:`WorkspaceManagerBase.get_workspace`). Used here
+            for tool / skill / MCP discovery.
+        scheduler_manager (`SchedulerManager`):
+            Application scheduler. Provides the four schedule tools and
+            persists schedules through it.
+        background_task_manager (`BackgroundTaskManager`):
+            Application background-task registry. Provides the
+            :class:`ToolStop` tool bound to its live task dict.
+        message_bus (`MessageBus`):
+            Application message bus; passed to team tools so they can
+            push HintBlocks + wakeups when delivering inter-session
+            messages.
+        middlewares (`list[MiddlewareBase]`):
+            The agent middlewares that may provide tools to the agent via the
+            `list_tools` interface.
+        user_id (`str`):
+            Caller user id.
+        agent_record (`AgentRecord`):
+            Pre-loaded agent record (loaded once by the caller). Still
+            used for its identity (``id``) and for pipeline consumers
+            downstream; the ``source`` field is no longer the team-tool
+            gate — see :attr:`session_record.team_id` below.
+        session_record (`SessionRecord`):
+            Pre-loaded session record (loaded once by the caller).
+            Used for the schedule-tool model configuration and — via
+            :attr:`SessionRecord.team_id` and the resolved team's
+            leader session id — for deciding which team tools to
+            attach.
+        extra_factory (`AgentToolFactory | None`, optional):
+            Async factory invoked once per assembly to produce
+            user/session-specific extra tools.
+        sub_agent_templates (`dict[str, SubAgentTemplate] | None`, \
+optional):
+            Sub-agent template registry, keyed by template type.
+            Passed to the ``AgentCreate`` tool so it can route to
+            the appropriate template when a ``subagent_type`` is
+            specified by the leader agent.
+
+    Returns:
+        `Toolkit`: Fully populated toolkit (tools + skills + MCPs).
+    """
+
+    tool_groups = []
+
+    # The general tools running in the workspace
+    tools = await workspace.list_tools()
+
+    # Planning tools — always on.
+    tools += [TaskCreate(), TaskList(), TaskGet(), TaskUpdate()]
+
+    # Background-task control.
+    tools += await background_task_manager.list_tools(
+        session_id=session_record.id,
+    )
+
+    # Schedule control. Requires a model config on this session because
+    # ``ScheduleCreate`` records it into new ``ScheduleRecord`` instances.
+    if session_record.config.chat_model_config is not None:
+        # Add schedule tools as a tool group
+        tool_groups.append(
+            ToolGroup(
+                name="schedule_tools",
+                description=(
+                    """Tools for managing cron schedules. A cron schedule is \
+a recurring task that fires at a specified time — at that point, a new \
+session is created and an agent will be invoked to complete the given task \
+autonomously.
+
+## When to Use This Tool Group
+- When you need to create a new cron schedule that triggers at a specific \
+time or interval"
+- When you're asked to list, inspect, stop, or delete existing cron schedules
+"""
+                ),
+                tools=await scheduler_manager.list_tools(
+                    user_id=user_id,
+                    agent_id=agent_record.id,
+                    chat_model_config=session_record.config.chat_model_config,
+                ),
+            ),
+        )
+
+    # Team tools — variant based on the session's team role rather
+    # than the agent's ``source`` field. A borrowed ("invited") agent
+    # runs with ``source='user'`` on its underlying AgentRecord but
+    # its session must behave as a worker; the session-level check
+    # captures both created and invited workers uniformly. Sessions
+    # not in a team fall through to the leader-side toolset — each
+    # leader tool has a runtime precondition check anyway (am I in a
+    # team? am I the leader?), so attaching the full set is safe.
+    team_tool_kwargs: dict[str, Any] = {
+        "storage": storage,
+        "message_bus": message_bus,
+        "workspace_manager": workspace_manager,
+        "user_id": user_id,
+        "session_id": session_record.id,
+        "agent_id": agent_record.id,
+    }
+    team_role: Literal["leader", "worker"] | None = None
+    if session_record.team_id is not None:
+        team = await storage.get_team(user_id, session_record.team_id)
+        if team is not None:
+            team_role = (
+                "leader" if team.session_id == session_record.id else "worker"
+            )
+    if team_role == "worker":
+        tools.append(TeamSay(**team_tool_kwargs, role="worker"))
+    else:
+        tools += [
+            TeamCreate(**team_tool_kwargs),
+            AgentCreate(
+                **team_tool_kwargs,
+                sub_agent_templates=sub_agent_templates or {},
+            ),
+            TeamSay(**team_tool_kwargs, role="leader"),
+            TeamDelete(**team_tool_kwargs),
+        ]
+        # Conditionally attach AgentInvite. Skipping construction when
+        # the user has no invitable agents keeps the input_schema enum
+        # non-empty (an empty enum would break tool-schema validators
+        # and confuse the LLM into calling a tool with no valid
+        # targets). Team-tool base is safe to call for either team or
+        # non-team sessions — AgentInvite rechecks the leader
+        # precondition at call time.
+        #
+        # Walk agents *visible* to the caller (own + shared through the
+        # resource access policy) so a leader can invite a partner's
+        # agent when the policy grants access.
+        visible_agents = await resource_access_service.list_resource(
+            user_id,
+            ResourceKind.AGENT,
+        )
+        invitable_pool = [
+            view
+            for view in visible_agents
+            if view.data.invite_config.invitable
+            and (view.data.invite_config.invite_description or "").strip()
+        ]
+        if invitable_pool:
+            tools.append(
+                AgentInvite(
+                    **team_tool_kwargs,
+                    invitable_pool=invitable_pool,
+                ),
+            )
+
+    # Caller-supplied extras.
+    if extra_factory is not None:
+        tools += await extra_factory(
+            user_id,
+            agent_record.id,
+            session_record.id,
+        )
+
+    # Tools from middleware
+    for mw in middlewares:
+        tools.extend(await mw.list_tools())
+
+    return Toolkit(
+        tools=tools,
+        skills_or_loaders=await workspace.list_skills(),
+        mcps=await workspace.list_mcps(),
+        tool_groups=tool_groups,
+    )
diff --git a/src/agentscope/app/_service/_tts_model.py b/src/agentscope/app/_service/_tts_model.py
new file mode 100644
index 0000000..88c7a5a
--- /dev/null
+++ b/src/agentscope/app/_service/_tts_model.py
@@ -0,0 +1,65 @@
+# -*- coding: utf-8 -*-
+"""TTS model service: builds a TTSModelBase from stored credential + config."""
+from typing import Type
+
+from fastapi import HTTPException, status
+
+from ._access import ResourceAccessService
+from ..storage import TTSModelConfig
+from ...credential import CredentialFactory
+from ...tts import TTSModelBase
+
+
+async def get_tts_model(
+    user_id: str,
+    config: TTSModelConfig,
+    access: ResourceAccessService,
+) -> TTSModelBase:
+    """Build a TTS model instance from a stored credential and config.
+
+    Args:
+        user_id (`str`):
+            The viewer's user id (may differ from the credential owner
+            for shared credentials).
+        config (`TTSModelConfig`):
+            The TTS model configuration.
+        access (`ResourceAccessService`):
+            Injected resource access service.
+
+    Returns:
+        `TTSModelBase`:
+            The TTS model instance.
+    """
+    credential_record = await access.resolve_credential(
+        user_id,
+        config.credential_id,
+    )
+
+    credential = CredentialFactory.from_dict(credential_record.data)
+    tts_classes = credential.get_tts_model_classes()
+    if not tts_classes:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Provider {config.type!r} does not support TTS models.",
+        )
+
+    tts_cls = _resolve_tts_class(tts_classes, config.model)
+    parameters = (
+        tts_cls.Parameters(**config.parameters) if config.parameters else None
+    )
+    return tts_cls(
+        credential=credential,
+        model=config.model,
+        parameters=parameters,
+    )
+
+
+def _resolve_tts_class(
+    classes: list[Type[TTSModelBase]],
+    model: str,
+) -> Type[TTSModelBase]:
+    """Pick the TTS class that lists the given model name."""
+    for cls in classes:
+        if any(card.name == model for card in cls.list_models()):
+            return cls
+    return classes[0]
diff --git a/src/agentscope/app/_tool/__init__.py b/src/agentscope/app/_tool/__init__.py
new file mode 100644
index 0000000..1585fd3
--- /dev/null
+++ b/src/agentscope/app/_tool/__init__.py
@@ -0,0 +1,46 @@
+# -*- coding: utf-8 -*-
+"""Framework-builtin tools wired into team-participating agents.
+
+These tools differ from the workspace-provided builtins (Bash, Read,
+Task series, …) in two ways:
+
+1. **Construction depends on app-level resources** — they bind a
+   :class:`StorageBase` + :class:`MessageBus` reference plus the
+   request-scoped ``user_id`` / ``session_id`` / ``agent_id`` at agent
+   assembly time, and call storage / bus directly in their
+   ``__call__`` — except ``TeamDelete``, which delegates to
+   :class:`SessionService` for cascade deletion.
+2. **Visibility depends on the session's team role, not the agent's
+   source field** — a session that is not in any team OR that is its
+   team's leader gets the full leader-side toolset (``TeamCreate /
+   AgentCreate / TeamSay / TeamDelete``, plus ``AgentInvite`` when the
+   user has any invitable agents). A session that is a worker in some
+   team gets only ``TeamSay``. This session-level distinction is what
+   lets a borrowed ("invited") agent's session see worker-only tools
+   even though the underlying ``AgentRecord`` still has
+   ``source='user'``. Each tool re-reads the current session + team
+   from storage at ``__call__`` time and fails clearly if its
+   precondition is not met.
+
+   The benefit is that a single chat run can ``TeamCreate`` and then
+   ``AgentCreate`` immediately afterward — there is no toolkit
+   refresh point because the toolkit never changed; only the
+   underlying storage state did, which the next tool reads fresh.
+
+Selection of the right subset happens inline in :func:`get_toolkit`;
+there is no separate "team tool factory" helper.
+"""
+from ._agent_create import AgentCreate, DEFAULT_SUB_AGENT_TEMPLATE
+from ._agent_invite import AgentInvite
+from ._team_create import TeamCreate
+from ._team_delete import TeamDelete
+from ._team_say import TeamSay
+
+__all__ = [
+    "AgentCreate",
+    "AgentInvite",
+    "DEFAULT_SUB_AGENT_TEMPLATE",
+    "TeamCreate",
+    "TeamDelete",
+    "TeamSay",
+]
diff --git a/src/agentscope/app/_tool/_agent_create.py b/src/agentscope/app/_tool/_agent_create.py
new file mode 100644
index 0000000..1973e0c
--- /dev/null
+++ b/src/agentscope/app/_tool/_agent_create.py
@@ -0,0 +1,574 @@
+# -*- coding: utf-8 -*-
+"""The AgentCreate tool — spawns a worker into the current team."""
+from __future__ import annotations
+
+import copy
+import json
+from typing import TYPE_CHECKING
+
+from pydantic import Field
+
+from ._team_tool_base import _TeamToolBase
+from .._types import SubAgentTemplate
+from ..message_bus import MessageBusKeys
+from .._bus_ops import enqueue_run_trigger
+from ..storage import AgentData, AgentRecord, SessionConfig, TeamMember
+from ..storage._utils import _ensure_team_members
+from ...message import HintBlock, TextBlock, ToolResultState
+from ...permission import PermissionContext
+from ...state import AgentState
+from ...tool import ToolChunk, ParamsBase
+
+if TYPE_CHECKING:
+    from ..message_bus import MessageBus
+    from ..storage import StorageBase
+    from ..workspace_manager import WorkspaceManagerBase
+
+
+_DEFAULT_SYSTEM_PROMPT_TEMPLATE = (
+    "You are {member_name}, a member of team '{team_name}' led by "
+    "{leader_name}.\n\n"
+    "Team purpose: {team_description}\n\n"
+    "Your role: {member_description}\n\n"
+    "You communicate with the team leader and other members "
+    "through the TeamSay tool. "
+    "Speak on the team only when you have something "
+    "external to share — your private reasoning stays private."
+)
+
+DEFAULT_SUB_AGENT_TEMPLATE = SubAgentTemplate(
+    type="default",
+    description="Default worker agent with standard configuration.",
+    system_prompt_template=_DEFAULT_SYSTEM_PROMPT_TEMPLATE,
+    override_leader_mode=False,
+    extend_leader_permission_rules=True,
+    extend_leader_working_directories=True,
+)
+# The built-in default sub-agent template.
+#
+# Used when no custom templates are registered, or when the leader
+# agent creates a member without specifying a ``subagent_type`` (or
+# explicitly specifies ``subagent_type="default"``).  Developers can
+# override this by registering their own template with
+# ``type="default"`` via :func:`~agentscope.app.create_app`.
+#
+# The default template fully follows the leader: the worker inherits
+# the leader's permission mode, working directories, and rules —
+# matching the intuition that a generic worker should behave like the
+# leader unless the developer registers a more opinionated template.
+
+
+def _merge_leader_permissions(
+    template: SubAgentTemplate,
+    leader_context: PermissionContext,
+) -> PermissionContext:
+    """Build the worker's permission context from the template, layered
+    with the leader's runtime state according to the template's three
+    inherit-from-leader flags.
+
+    - ``override_leader_mode``: if True, the template's
+      :attr:`PermissionContext.mode` wins; otherwise the worker
+      inherits the leader's mode.
+    - ``extend_leader_permission_rules``: if True, the leader's
+      allow/deny/ask rules are appended after the template's rules for
+      each tool, so the worker doesn't re-prompt for permissions the
+      user has already granted in the leader session. The template's
+      rules appear first in each list, so the engine — which returns
+      on the first matching rule per stage — evaluates the template's
+      intent before the leader's.
+    - ``extend_leader_working_directories``: if True, the leader's
+      working directories are merged in; on key (path) collisions the
+      template's entry wins.
+
+    The template fields are deep-copied so the returned context is
+    independent of both the template and the leader state.
+    """
+    merged = template.permission_context.model_copy(deep=True)
+
+    if not template.override_leader_mode:
+        merged.mode = leader_context.mode
+
+    if template.extend_leader_working_directories:
+        for path, wd in leader_context.working_directories.items():
+            merged.working_directories.setdefault(
+                path,
+                wd.model_copy(deep=True),
+            )
+
+    if template.extend_leader_permission_rules:
+        for attr in ("allow_rules", "deny_rules", "ask_rules"):
+            merged_rules: dict = getattr(merged, attr)
+            for tool_name, rules in getattr(leader_context, attr).items():
+                merged_rules.setdefault(tool_name, []).extend(
+                    r.model_copy(deep=True) for r in rules
+                )
+
+    return merged
+
+
+class _AgentCreateParams(ParamsBase):
+    """Parameters for :class:`AgentCreate`."""
+
+    name: str = Field(
+        description=(
+            'Short identifier for the new member, e.g. ``"researcher"`` '
+            'or ``"coder-1"``. Other members address it via '
+            "``TeamSay(to=<this name>)``, so it MUST be unique within "
+            "the team."
+        ),
+    )
+    description: str = Field(
+        description=(
+            "One-sentence summary of the member's role — e.g. "
+            '``"Researches background information on the target topic"``. '
+            "Becomes part of the member's system prompt so it understands "
+            "its place in the team."
+        ),
+    )
+    prompt: str = Field(
+        description=(
+            "The first task delivered to the member as a user message. "
+            "The member begins executing immediately upon creation, so "
+            "make this concrete and self-contained — do not just say "
+            '``"wait for instructions"`` (use TeamSay later instead). '
+            "Include any context, constraints, deliverables, and "
+            "deadlines the member needs."
+        ),
+    )
+
+
+class AgentCreate(_TeamToolBase):
+    """Spawn a new worker member into the team you lead."""
+
+    name: str = "AgentCreate"
+    is_state_injected: bool = True
+
+    description: str = """Add a new member to the team you lead.
+
+## When to Use This Tool
+After ``TeamCreate``, call this for each member you want on the team. \
+Each call:
+- Creates a worker agent dedicated to this team.
+- Delivers ``prompt`` as the worker's first user message — **the worker \
+starts executing it immediately**. (So DONT use ``TeamSay`` right after \
+creating one agent).
+
+## When NOT to Use This Tool
+- You're not currently leading a team. Call ``TeamCreate`` first.
+- The new member would duplicate an existing member's role; reuse the \
+existing member via ``TeamSay`` instead.
+
+## Effects
+- Use the ``name`` you chose as ``to=<name>`` in ``TeamSay`` to direct \
+messages to this member specifically. Names must be unique within the \
+team (including against the leader's name); duplicates are rejected.
+- Members spawned this way live only as long as the team — they are \
+deleted when ``TeamDelete`` is called.
+
+## Important
+- You are responsible for organising the team, assigning tasks, collecting \
+every member's report, and producing the final answer — all members report \
+directly to you. Therefore, **DO NOT** encourage members to communicate with \
+each other, and **AVOID** creating "integrator"-style members; both make the \
+overall communication topology unnecessarily complex.
+"""
+
+    input_schema: dict = _AgentCreateParams.model_json_schema()
+
+    def __init__(
+        self,
+        storage: "StorageBase",
+        message_bus: "MessageBus",
+        workspace_manager: "WorkspaceManagerBase",
+        user_id: str,
+        session_id: str,
+        agent_id: str,
+        sub_agent_templates: dict[str, SubAgentTemplate] | None = None,
+    ) -> None:
+        """Bind request-scoped identifiers plus sub-agent templates.
+
+        Extends :meth:`_TeamToolBase.__init__` with the optional
+        template registry. The built-in ``"default"`` template is
+        always injected; extra templates unlock a ``subagent_type``
+        enum in the tool's input schema.
+
+        Args:
+            storage (`StorageBase`):
+                Application storage backend.
+            message_bus (`MessageBus`):
+                Application message bus.
+            workspace_manager (`WorkspaceManagerBase`):
+                Workspace manager (forwarded to base for uniform
+                team-tool wiring; currently unused here).
+            user_id (`str`):
+                The owner user id.
+            session_id (`str`):
+                The calling session id.
+            agent_id (`str`):
+                The calling agent id.
+            sub_agent_templates (`dict[str, SubAgentTemplate] | None`, \
+optional):
+                Template registry keyed by type.
+        """
+        super().__init__(
+            storage,
+            message_bus,
+            workspace_manager,
+            user_id,
+            session_id,
+            agent_id,
+        )
+
+        self._sub_agent_templates: dict[str, SubAgentTemplate] = dict(
+            sub_agent_templates or {},
+        )
+        if "default" not in self._sub_agent_templates:
+            self._sub_agent_templates["default"] = DEFAULT_SUB_AGENT_TEMPLATE
+
+        # Only expose subagent_type when the developer registered
+        # custom templates — a single "default" type is redundant in
+        # the schema and would confuse the LLM.
+        has_custom_templates = set(self._sub_agent_templates) != {"default"}
+        if has_custom_templates:
+            schema = copy.deepcopy(
+                _AgentCreateParams.model_json_schema(),
+            )
+            type_descriptions = "\n".join(
+                f"- ``{t.type!r}`` — {t.description}"
+                for t in self._sub_agent_templates.values()
+            )
+            schema["properties"]["subagent_type"] = {
+                "type": "string",
+                "enum": list(self._sub_agent_templates),
+                "description": (
+                    "The type of sub-agent template to use. "
+                    "Available types:\n\n"
+                    f"{type_descriptions}\n\n"
+                    "Each type has pre-configured system prompt, "
+                    "permissions, and task context."
+                ),
+            }
+            self.input_schema = schema
+
+    async def __call__(
+        self,
+        name: str,
+        description: str,
+        prompt: str,
+        subagent_type: str = "default",
+        _agent_state: AgentState | None = None,
+    ) -> ToolChunk:
+        """Spawn the worker agent + session directly via storage.
+
+        Reads the current session + team records from storage to
+        enforce two preconditions: the calling session must be in a
+        team, and it must be that team's leader.
+
+        The worker's configuration (system prompt, context/react
+        config, permission context, task context) is determined by
+        the :class:`SubAgentTemplate` matching ``subagent_type``. The
+        leader's user-confirmed permission rules and working
+        directories are merged into the template's permission context
+        so the worker does not re-prompt for permissions the user has
+        already granted.
+
+        Args:
+            name (`str`):
+                Short identifier for the worker, unique within the
+                team. Used as the ``to`` target in ``TeamSay``.
+            description (`str`):
+                One-sentence summary of the worker's role.
+            prompt (`str`):
+                First task delivered as a user message to the worker.
+            subagent_type (`str`, defaults to ``"default"``):
+                Template type to use. Must match a registered
+                :class:`SubAgentTemplate.type`.
+            _agent_state (`AgentState | None`, optional):
+                Live leader state injected by the toolkit.
+
+        Returns:
+            `ToolChunk`:
+                A success message containing the new member id, or an
+                error chunk on failure.
+        """
+        try:
+            session = await self._storage.get_session(
+                self._user_id,
+                self._agent_id,
+                self._session_id,
+            )
+            if session is None or session.team_id is None:
+                return ToolChunk(
+                    content=[
+                        TextBlock(
+                            text=(
+                                "AgentCreate: this session is not in "
+                                "any team — call TeamCreate first."
+                            ),
+                        ),
+                    ],
+                    state=ToolResultState.ERROR,
+                )
+            team = await self._storage.get_team(
+                self._user_id,
+                session.team_id,
+            )
+            if team is None:
+                return ToolChunk(
+                    content=[
+                        TextBlock(
+                            text=(
+                                "AgentCreate: team "
+                                f"{session.team_id} no longer exists."
+                            ),
+                        ),
+                    ],
+                    state=ToolResultState.ERROR,
+                )
+            if team.session_id != self._session_id:
+                return ToolChunk(
+                    content=[
+                        TextBlock(
+                            text=(
+                                "AgentCreate: only the team leader "
+                                "can add members; this session is a "
+                                "worker."
+                            ),
+                        ),
+                    ],
+                    state=ToolResultState.ERROR,
+                )
+
+            # Look up leader session for chat-model inheritance + name.
+            leader_session = await self._storage.get_session(
+                self._user_id,
+                "",  # agent_id unused at storage level
+                team.session_id,
+            )
+            if leader_session is None:
+                return ToolChunk(
+                    content=[
+                        TextBlock(
+                            text=(
+                                f"AgentCreate: leader session "
+                                f"{team.session_id} for team {team.id} is "
+                                f"missing — team is in an inconsistent "
+                                f"state."
+                            ),
+                        ),
+                    ],
+                    state=ToolResultState.ERROR,
+                )
+
+            # Resolve the template.
+            template = self._sub_agent_templates.get(subagent_type)
+            if template is None:
+                available = list(self._sub_agent_templates)
+                return ToolChunk(
+                    content=[
+                        TextBlock(
+                            text=(
+                                f"AgentCreate: unknown subagent_type "
+                                f"{subagent_type!r}; expected one of "
+                                f"{available}."
+                            ),
+                        ),
+                    ],
+                    state=ToolResultState.ERROR,
+                )
+
+            # Enforce team-scoped name uniqueness. TeamSay routes by
+            # ``name`` (not agent_id), so duplicates would be ambiguous
+            # and unaddressable. The leader's name participates too —
+            # workers must not collide with it.
+            #
+            # Also reject ``@`` in the name: invited members display as
+            # ``"<name>@<agent_id[:8]>"`` in TeamSay, and letting a
+            # created member sneak an ``@`` into its name would make
+            # the two routing forms visually collide.
+            if "@" in name:
+                return ToolChunk(
+                    content=[
+                        TextBlock(
+                            text=(
+                                f"AgentCreate: member name {name!r} cannot "
+                                f"contain the character '@'."
+                            ),
+                        ),
+                    ],
+                    state=ToolResultState.ERROR,
+                )
+
+            leader_agent_record = await self._storage.get_agent(
+                self._user_id,
+                leader_session.agent_id,
+            )
+            existing_names: set[str] = set()
+            if leader_agent_record is not None:
+                existing_names.add(leader_agent_record.data.name)
+            members = await _ensure_team_members(
+                self._storage,
+                self._user_id,
+                team,
+            )
+            for member in members:
+                member_record = await self._storage.get_agent(
+                    member.owner_id,
+                    member.agent_id,
+                )
+                if member_record is not None:
+                    existing_names.add(member_record.data.name)
+            if name in existing_names:
+                return ToolChunk(
+                    content=[
+                        TextBlock(
+                            text=(
+                                f"AgentCreate: a team member named "
+                                f"{name!r} already exists. Member names "
+                                f"must be unique within the team "
+                                f"(including the leader's name); pick "
+                                f"another."
+                            ),
+                        ),
+                    ],
+                    state=ToolResultState.ERROR,
+                )
+
+            # Resolve leader name early — needed both for the system
+            # prompt template and for the initial team-message hint.
+            leader_name = (
+                leader_agent_record.data.name
+                if leader_agent_record is not None
+                else leader_session.agent_id
+            )
+
+            # 1. Build worker AgentRecord (source="team" so it's hidden
+            #    from the global agent list).
+            system_prompt = template.system_prompt_template.format(
+                team_name=team.data.name,
+                team_description=team.data.description,
+                member_name=name,
+                member_description=description,
+                leader_name=leader_name,
+            )
+            worker_agent = AgentRecord(
+                user_id=self._user_id,
+                source="team",
+                data=AgentData(
+                    name=name,
+                    system_prompt=system_prompt,
+                    context_config=template.context_config.model_copy(
+                        deep=True,
+                    ),
+                    react_config=template.react_config.model_copy(
+                        deep=True,
+                    ),
+                ),
+            )
+            await self._storage.upsert_agent(self._user_id, worker_agent)
+
+            # 2. Build worker SessionRecord, inheriting leader's model
+            #    config. The template's permission context is the base;
+            #    on top of it we merge the leader's mode and/or rules
+            #    and/or working directories according to the template's
+            #    inherit-from-leader flags. See
+            #    :func:`_merge_leader_permissions` for the policy.
+            leader_permission_context = (
+                _agent_state.permission_context
+                if _agent_state is not None
+                else leader_session.state.permission_context
+            )
+            worker_permission_context = _merge_leader_permissions(
+                template,
+                leader_permission_context,
+            )
+            worker_state = AgentState(
+                permission_context=worker_permission_context,
+                tasks_context=template.tasks_context.model_copy(
+                    deep=True,
+                ),
+            )
+            worker_session = await self._storage.upsert_session(
+                user_id=self._user_id,
+                agent_id=worker_agent.id,
+                config=SessionConfig(
+                    workspace_id=leader_session.config.workspace_id,
+                    name=f"team:{team.id}/{name}",
+                    chat_model_config=(
+                        leader_session.config.chat_model_config
+                    ),
+                    fallback_chat_model_config=(
+                        leader_session.config.fallback_chat_model_config
+                    ),
+                ),
+                state=worker_state,
+            )
+            await self._storage.set_session_team_id(
+                self._user_id,
+                worker_session.id,
+                team.id,
+            )
+
+            # 3. Append worker to the team roster. Write both the
+            #    legacy ``member_ids`` (for backwards-compatible
+            #    readers) and the new ``members`` entry with
+            #    ``role="created"`` — the two must stay in sync so
+            #    ``ensure_team_members`` and any legacy reader agree
+            #    on membership. ``members`` above was materialised via
+            #    the same helper, so it includes any prior migration.
+            team.data.member_ids = [
+                *team.data.member_ids,
+                worker_agent.id,
+            ]
+            team.data.members = [
+                *members,
+                TeamMember(
+                    owner_id=self._user_id,
+                    agent_id=worker_agent.id,
+                    session_id=worker_session.id,
+                    role="created",
+                ),
+            ]
+            await self._storage.upsert_team(self._user_id, team)
+
+            # 4. Deliver the initial task to the worker's inbox + wakeup.
+            hint = HintBlock(
+                hint=(
+                    f'<team-message from="{leader_name}">\n'
+                    f"{prompt}\n"
+                    f"</team-message>"
+                ),
+                source=json.dumps(
+                    {
+                        "label": "team_message",
+                        "sublabel": leader_name,
+                    },
+                    ensure_ascii=False,
+                ),
+            )
+            await self._message_bus.queue_push(
+                MessageBusKeys.inbox(worker_session.id),
+                hint.model_dump(mode="json"),
+            )
+            await enqueue_run_trigger(
+                self._message_bus,
+                user_id=self._user_id,
+                session_id=worker_session.id,
+                agent_id=worker_agent.id,
+            )
+
+            return ToolChunk(
+                content=[
+                    TextBlock(
+                        text=(
+                            f"Member {name!r} added to team "
+                            f"{team.data.name!r}."
+                        ),
+                    ),
+                ],
+            )
+        except Exception as e:  # pylint: disable=broad-except
+            return ToolChunk(
+                content=[TextBlock(text=f"AgentCreate failed: {e}")],
+                state=ToolResultState.ERROR,
+            )
diff --git a/src/agentscope/app/_tool/_agent_invite.py b/src/agentscope/app/_tool/_agent_invite.py
new file mode 100644
index 0000000..1116a05
--- /dev/null
+++ b/src/agentscope/app/_tool/_agent_invite.py
@@ -0,0 +1,566 @@
+# -*- coding: utf-8 -*-
+"""The AgentInvite tool — borrows an existing agent into the leader's team.
+
+Unlike :class:`AgentCreate`, which spawns a brand-new worker
+(``source='team'``) from a :class:`SubAgentTemplate`, this tool
+**borrows** a pre-existing user-owned agent by minting a fresh
+team-scoped :class:`SessionRecord` on top of the *existing*
+:class:`AgentRecord`.  The borrowed agent keeps its system prompt,
+context/react configs, workspace, MCP, skills, and model choice; only
+a new session is created so it can hold a parallel conversation for
+the team.
+
+When the team is dissolved or the leader is deleted, only the borrowed
+session is cleaned up — the underlying :class:`AgentRecord` survives
+so the user can still use the agent stand-alone.
+"""
+from __future__ import annotations
+
+import copy
+import json
+from typing import TYPE_CHECKING
+
+from pydantic import Field
+
+from ._constants import HANDLE_LEN
+from ._team_tool_base import _TeamToolBase
+from ..message_bus import MessageBusKeys
+from .._bus_ops import enqueue_run_trigger
+from ..storage import SessionConfig, TeamMember
+from ..storage._utils import _ensure_team_members
+from ...message import HintBlock, TextBlock, ToolResultState
+from ...state import AgentState
+from ...tool import ToolChunk, ParamsBase
+from ..._utils._common import _generate_id
+
+if TYPE_CHECKING:
+    from ..message_bus import MessageBus
+    from ..storage import AgentRecord, StorageBase
+    from ..workspace_manager import WorkspaceManagerBase
+
+
+def _display_handle(agent_id: str) -> str:
+    """Return the derived routing handle for ``agent_id``.
+
+    Kept as a tiny helper (rather than inlining ``agent_id[:HANDLE_LEN]``
+    at every call site) so a future change to how a handle is derived
+    (widening the prefix, hashing, etc.) has exactly one place to touch.
+    The length itself lives in :mod:`_constants` so ``TeamSay``'s
+    parser agrees byte-for-byte with what this producer emits.
+    """
+    return agent_id[:HANDLE_LEN]
+
+
+def _display_name(agent_name: str, agent_id: str) -> str:
+    """Format the leader-facing display / routing string.
+
+    Example: ``"Monday@9f3c1a20"``. Used by both :class:`AgentInvite`
+    (as the ``target`` enum values) and :func:`TeamSay` (as the
+    directory keys for invited members).
+    """
+    return f"{agent_name}@{_display_handle(agent_id)}"
+
+
+class _AgentInviteParams(ParamsBase):
+    """Parameters for :class:`AgentInvite`.
+
+    ``target`` and ``prompt`` are the only inputs — the borrowed
+    agent's name, system prompt, and configuration all come from its
+    existing :class:`AgentRecord`, so there is nothing else for the
+    leader LLM to override.
+    """
+
+    target: str = Field(
+        description=(
+            "The invitable agent to borrow, formatted "
+            '``"<name>@<handle>"`` (e.g. ``"Monday@9f3c1a20"``). Choose '
+            "from the enum values — each was populated from the "
+            "user's currently-invitable agents at the moment the tool "
+            "list was assembled."
+        ),
+    )
+    prompt: str = Field(
+        description=(
+            "The first task delivered to the invited agent as a user "
+            "message. It begins executing immediately upon joining — "
+            "do NOT tell it to wait for further instructions. Include "
+            "context, constraints, deliverables, and deadlines the "
+            "agent needs to work autonomously."
+        ),
+    )
+
+
+_DESCRIPTION_HEADER = """Borrow an existing user-owned agent into the \
+team you lead.
+
+<If ``AgentCreate`` is not available in your toolset, ignore all \
+references to it below.>
+
+## Difference From ``AgentCreate``
+- ``AgentCreate`` spins up a brand-new agent that **shares your \
+workspace**, so you and it can collaborate on files inside the same \
+working directory. ``AgentInvite`` borrows a pre-existing agent that has \
+its **own workspace** — depending on how the user has configured it, the \
+two workspaces MAY or MAY NOT expose the same filesystem, so paths you \
+hand over cannot be assumed to resolve on the invited agent's side.
+- The invited agent already has a name; you cannot rename it.
+
+## When to Use This Tool
+- A user-owned agent already exists whose stated purpose matches a role \
+you need — reuse it instead of spawning a fresh worker with \
+``AgentCreate``.
+- You want to notify or delegate to an existing agent that specialises \
+in a specific domain.
+
+## When NOT to Use This Tool
+- No suitable invitable agent exists — use ``AgentCreate`` instead.
+- You need to customise the member's system prompt or role for this \
+team specifically — invited members' configs are frozen; use \
+``AgentCreate`` if you need per-team customisation.
+- You are not currently leading a team. Call ``TeamCreate`` first.
+
+## Important
+- Do NOT assume the invited agent shares your filesystem. Prefer \
+self-contained messages; do not embed working-directory or file paths \
+unless you have first verified the two sides can see them.
+- If (and only if) the task genuinely requires jointly operating on the \
+same large file or complex project directory, first use ``TeamSay`` to \
+check whether the invited agent can actually see the same files (e.g. \
+by asking it to list or stat a specific path). Skip this handshake for \
+tasks where only message content matters.
+- ``TeamSay`` is the primary communication channel between you and the \
+invited agent.
+- ``TeamDelete`` does NOT delete the invited agent — only the \
+team-scoped session is cleaned up. If you invite the same agent into \
+multiple teams over time, it may retain long-term memory or files from \
+earlier collaborations with you.
+
+## Available invitable agents"""
+
+
+class AgentInvite(_TeamToolBase):
+    """Borrow one of the user's invitable agents into the current team.
+
+    The tool is only attached to the leader's toolkit when the calling
+    user has at least one agent with ``invitable=True`` and a non-empty
+    ``invite_description`` — see the toolkit assembly logic in
+    :func:`get_toolkit`. The invitable pool is captured as a **snapshot**
+    at attachment time so the tool's ``input_schema`` can enumerate
+    concrete targets; ``__call__`` re-fetches the target's record and
+    re-checks invitability before minting the session, so a race
+    between snapshot and call (e.g. the user just turned off the toggle)
+    is caught cleanly.
+    """
+
+    name: str = "AgentInvite"
+    # No leader state needed — the borrowed session starts from a
+    # fresh PermissionContext(); nothing carries over from the leader.
+    is_state_injected: bool = False
+
+    description: str
+    input_schema: dict
+
+    def __init__(
+        self,
+        storage: "StorageBase",
+        message_bus: "MessageBus",
+        workspace_manager: "WorkspaceManagerBase",
+        user_id: str,
+        session_id: str,
+        agent_id: str,
+        invitable_pool: list["AgentRecord"],
+    ) -> None:
+        """Bind request-scoped identifiers plus the invitable pool snapshot.
+
+        Args:
+            storage (`StorageBase`):
+                Application storage backend.
+            message_bus (`MessageBus`):
+                Application message bus.
+            workspace_manager (`WorkspaceManagerBase`):
+                Used to mint the workspace id for freshly-invited
+                agents (see :meth:`__call__`).
+            user_id (`str`):
+                The owner user id.
+            session_id (`str`):
+                The calling session id.
+            agent_id (`str`):
+                The calling agent id.
+            invitable_pool (`list[AgentRecord]`):
+                Snapshot of currently-invitable agents. Must be
+                non-empty — the caller skips construction otherwise.
+        """
+        super().__init__(
+            storage,
+            message_bus,
+            workspace_manager,
+            user_id,
+            session_id,
+            agent_id,
+        )
+
+        self._pool_by_id: dict[str, "AgentRecord"] = {
+            a.id: a for a in invitable_pool
+        }
+
+        # Build enum + a human-readable per-target rundown for the LLM.
+        enum_values = [
+            _display_name(a.data.name, a.id) for a in invitable_pool
+        ]
+        target_lines = [
+            f"- ``{_display_name(a.data.name, a.id)!r}`` — "
+            f"{a.data.invite_config.invite_description}"
+            for a in invitable_pool
+        ]
+        self.description = (
+            _DESCRIPTION_HEADER + "\n" + "\n".join(target_lines) + "\n"
+        )
+
+        schema = copy.deepcopy(_AgentInviteParams.model_json_schema())
+        schema["properties"]["target"]["enum"] = enum_values
+        self.input_schema = schema
+
+    async def __call__(
+        self,
+        target: str,
+        prompt: str,
+    ) -> ToolChunk:
+        """Mint a team-scoped session on top of an existing agent record.
+
+        Preconditions (all rechecked at call time against fresh storage
+        reads):
+        - Caller's session is in a team AND is that team's leader.
+        - ``target`` is a well-formed ``"<name>@<handle>"`` string whose
+          handle prefix-matches an agent id in the current invitable
+          pool.
+        - The matched agent is still ``invitable=True`` with a
+          non-empty ``invite_description`` (guards against a
+          toggle-off race between attachment and invocation).
+        - The team does not already have this agent as a member (one
+          borrow per agent per team).
+        - The invited agent has at least one existing session to
+          inherit ``workspace_id`` / ``chat_model_config`` from — a
+          brand-new never-opened agent record is not invitable in
+          practice because it has no runtime state to reuse.
+
+        Args:
+            target (`str`):
+                The ``"<name>@<handle>"`` display string chosen from
+                the enum.
+            prompt (`str`):
+                First task delivered as a user message to the invited
+                agent.
+
+        Returns:
+            `ToolChunk`:
+                A success message containing the invited agent's
+                display name, or an error chunk on failure.
+        """
+        try:
+            invited, resolve_err = _resolve_target(
+                self._pool_by_id,
+                target,
+            )
+            if resolve_err is not None:
+                return _error(resolve_err)
+            assert invited is not None  # narrows for mypy
+
+            session = await self._storage.get_session(
+                self._user_id,
+                self._agent_id,
+                self._session_id,
+            )
+            if session is None or session.team_id is None:
+                return _error(
+                    "AgentInvite: this session is not in any team — "
+                    "call TeamCreate first.",
+                )
+            team = await self._storage.get_team(
+                self._user_id,
+                session.team_id,
+            )
+            if team is None:
+                return _error(
+                    f"AgentInvite: team {session.team_id} no longer "
+                    f"exists.",
+                )
+            if team.session_id != self._session_id:
+                return _error(
+                    "AgentInvite: only the team leader can invite "
+                    "members; this session is a worker.",
+                )
+
+            # Re-fetch fresh — the snapshot could be stale if the user
+            # just toggled the invite off.
+            fresh = await self._storage.get_agent(
+                self._user_id,
+                invited.id,
+            )
+            if (
+                fresh is None
+                or not fresh.data.invite_config.invitable
+                or not (
+                    fresh.data.invite_config.invite_description or ""
+                ).strip()
+            ):
+                return _error(
+                    f"AgentInvite: agent {invited.data.name!r} is no "
+                    f"longer invitable.",
+                )
+            invited = fresh
+
+            # Duplicate-borrow guard — one team, one borrow per agent.
+            existing_members = await _ensure_team_members(
+                self._storage,
+                self._user_id,
+                team,
+            )
+            if any(m.agent_id == invited.id for m in existing_members):
+                return _error(
+                    f"AgentInvite: agent {invited.data.name!r} is "
+                    f"already a member of team "
+                    f"{team.data.name!r}.",
+                )
+
+            # Leader session — needed for chat-model / workspace fallback
+            # when the invited agent has no existing session, and for the
+            # sender-name in the initial team-message hint.
+            leader_session = await self._storage.get_session(
+                self._user_id,
+                "",
+                team.session_id,
+            )
+            if leader_session is None:
+                return _error(
+                    f"AgentInvite: leader session {team.session_id} "
+                    f"for team {team.id} is missing — team is in an "
+                    f"inconsistent state.",
+                )
+            leader_agent = await self._storage.get_agent(
+                self._user_id,
+                leader_session.agent_id,
+            )
+            leader_name = (
+                leader_agent.data.name
+                if leader_agent is not None
+                else leader_session.agent_id
+            )
+
+            # Prefer the invited agent's own primary session for
+            # workspace + chat-model reuse: it already has any MCP /
+            # skills / cache set up. Fall back to a freshly-generated
+            # workspace id + the leader's chat model when the agent has
+            # never been opened — the underlying workspace is created
+            # lazily by the workspace manager on first chat, so a bare
+            # id is enough.
+            invited_sessions = await self._storage.list_sessions(
+                self._user_id,
+                invited.id,
+            )
+            if invited_sessions:
+                primary = invited_sessions[0]
+                borrowed_workspace_id = primary.config.workspace_id
+                borrowed_chat_model = (
+                    primary.config.chat_model_config
+                    or leader_session.config.chat_model_config
+                )
+                borrowed_fallback_model = (
+                    primary.config.fallback_chat_model_config
+                    or leader_session.config.fallback_chat_model_config
+                )
+            else:
+                borrowed_workspace_id = (
+                    self._workspace_manager.assign_workspace_id(
+                        user_id=self._user_id,
+                        agent_id=invited.id,
+                        session_id=_generate_id(),
+                    )
+                )
+                borrowed_chat_model = leader_session.config.chat_model_config
+                borrowed_fallback_model = (
+                    leader_session.config.fallback_chat_model_config
+                )
+
+            # Permission context is NOT inherited from the leader.
+            # PermissionContext.working_directories and allow/deny/ask
+            # rules are anchored to the leader's workspace, which the
+            # invited agent may not share (it has its own workspace_id).
+            # Merging leader dirs / rules would advertise paths the
+            # invited agent cannot reach and pull in user confirmations
+            # granted against a different filesystem. Nor do we inherit
+            # from the invited agent's own primary session — the
+            # team-scoped conversation is a separate context; prior
+            # "user approved X" state should not silently cross over.
+            # HITL prompts in this team will re-confirm any sensitive
+            # tool call.
+            worker_state = AgentState(
+                # permission_context defaults to a fresh
+                # ``PermissionContext()``; tasks_context defaults to
+                # empty. Both are the intended reset for the borrowed
+                # session — the invited agent's main-session state
+                # stays with its own session.
+            )
+
+            invited_display = _display_name(
+                invited.data.name,
+                invited.id,
+            )
+            invited_handle = _display_handle(invited.id)
+            borrowed = await self._storage.upsert_session(
+                user_id=self._user_id,
+                agent_id=invited.id,
+                config=SessionConfig(
+                    workspace_id=borrowed_workspace_id,
+                    name=f"team:{team.id}/invited:{invited_handle}",
+                    chat_model_config=borrowed_chat_model,
+                    fallback_chat_model_config=borrowed_fallback_model,
+                ),
+                state=worker_state,
+            )
+            await self._storage.set_session_team_id(
+                self._user_id,
+                borrowed.id,
+                team.id,
+            )
+
+            team.data.members = [
+                *existing_members,
+                TeamMember(
+                    owner_id=self._user_id,
+                    agent_id=invited.id,
+                    session_id=borrowed.id,
+                    role="invited",
+                ),
+            ]
+            await self._storage.upsert_team(self._user_id, team)
+
+            hint = HintBlock(
+                hint=(
+                    "<system-reminder>You're now invited into a team named "
+                    f"'{team.data.name}' led by an agent named "
+                    f"'{leader_name}' in this session. All team members "
+                    f"can **ONLY** communicate through the `TeamSay` tool. "
+                    f"Once you finished the given tasks, or want to "
+                    f"communicate with the leader or team members, "
+                    f"use `TeamSay`.</system-reminder>\n"
+                    f'<team-message from="{leader_name}">\n'
+                    f"{prompt}\n"
+                    f"</team-message>"
+                ),
+                source=json.dumps(
+                    {
+                        "label": "team_message",
+                        "sublabel": leader_name,
+                    },
+                    ensure_ascii=False,
+                ),
+            )
+            await self._message_bus.queue_push(
+                MessageBusKeys.inbox(borrowed.id),
+                hint.model_dump(mode="json"),
+            )
+            await enqueue_run_trigger(
+                self._message_bus,
+                user_id=self._user_id,
+                session_id=borrowed.id,
+                agent_id=invited.id,
+            )
+
+            return ToolChunk(
+                content=[
+                    TextBlock(
+                        text=(
+                            f"Invited {invited_display!r} into team "
+                            f"{team.data.name!r}."
+                        ),
+                    ),
+                ],
+            )
+        except Exception as e:  # pylint: disable=broad-except
+            return ToolChunk(
+                content=[TextBlock(text=f"AgentInvite failed: {e}")],
+                state=ToolResultState.ERROR,
+            )
+
+
+def _resolve_target(
+    pool_by_id: dict[str, "AgentRecord"],
+    target: str,
+) -> tuple["AgentRecord | None", str | None]:
+    """Parse a ``"<name>@<handle>"`` string and look up the pool entry.
+
+    Matches on **both** the name part and the handle so that two
+    invitable agents sharing an 8-char UUID4 prefix are still
+    disambiguated by the LLM-supplied name. Falls back to a
+    handle-only lookup when exactly one pool entry matches the handle,
+    which keeps the common single-agent case working. If two or more
+    entries share the handle AND the name does not narrow the match,
+    an ``ambiguous`` error is returned so the caller can retry.
+
+    Returns ``(record, None)`` on success or ``(None, error_message)``
+    on any parse or resolution failure.
+    """
+    if "@" not in target:
+        return None, (
+            f"AgentInvite: malformed target {target!r} — expected "
+            f'"<name>@<handle>", got no ``@`` separator.'
+        )
+    name_part, handle = target.rsplit("@", 1)
+    name_part = name_part.strip()
+    handle = handle.strip()
+    if not handle:
+        return None, (
+            f"AgentInvite: malformed target {target!r} — empty handle "
+            f"after ``@``."
+        )
+    handle_matches = [
+        record
+        for agent_id, record in pool_by_id.items()
+        if _display_handle(agent_id) == handle
+    ]
+    # Preferred: unique (name, handle) match. Guards against the rare
+    # 8-char-prefix collision on distinct agents with distinct names.
+    named_matches = [r for r in handle_matches if r.data.name == name_part]
+    if len(named_matches) == 1:
+        return named_matches[0], None
+    if len(named_matches) > 1:
+        # Same name AND same handle prefix on multiple pool entries —
+        # the display strings are indistinguishable, so no client
+        # input could disambiguate. Surface the ids so the caller can
+        # see what collided.
+        ids = sorted(r.id for r in named_matches)
+        return None, (
+            f"AgentInvite: target {target!r} is ambiguous — multiple "
+            f"invitable agents share this display string: {ids}."
+        )
+    # Fallback: no name match, but exactly one handle match — accept it.
+    if len(handle_matches) == 1:
+        return handle_matches[0], None
+    if len(handle_matches) > 1:
+        colliding = sorted(
+            _display_name(r.data.name, r.id) for r in handle_matches
+        )
+        return None, (
+            f"AgentInvite: handle {handle!r} matches multiple invitable "
+            f"agents: {colliding}. Retry with the exact display string."
+        )
+    available = sorted(
+        _display_name(a.data.name, a.id) for a in pool_by_id.values()
+    )
+    return None, (
+        f"AgentInvite: no invitable agent matches target {target!r}. "
+        f"Available: {available}."
+    )
+
+
+def _error(text: str) -> ToolChunk:
+    """Build an ``ERROR``-state :class:`ToolChunk` with a text block.
+
+    Not moved to :mod:`_team_tool_base` because that shape is specific
+    to :class:`AgentInvite`'s branchy validation path — the other team
+    tools currently inline the same pattern.
+    """
+    return ToolChunk(
+        content=[TextBlock(text=text)],
+        state=ToolResultState.ERROR,
+    )
diff --git a/src/agentscope/app/_tool/_constants.py b/src/agentscope/app/_tool/_constants.py
new file mode 100644
index 0000000..65a4938
--- /dev/null
+++ b/src/agentscope/app/_tool/_constants.py
@@ -0,0 +1,19 @@
+# -*- coding: utf-8 -*-
+"""Shared constants for the framework-builtin team tools.
+
+Centralised here (rather than duplicated per-module) so contracts that
+must agree across tools have exactly one source of truth. Adding a new
+tool that touches the same invariant should import from here, not
+redeclare the value.
+"""
+
+HANDLE_LEN: int = 8
+# Length of the ``agent_id`` prefix used to disambiguate invited
+# members in the ``"<name>@<handle>"`` display string.
+#
+# Must be the same value at every producer (``AgentInvite``, which
+# builds the enum and the display string) and every consumer
+# (``TeamSay``, which parses the display string back into a routing
+# key). Widening this in the future is a coordinated change — leaders
+# that already routed via the old length would target the wrong member
+# otherwise.
diff --git a/src/agentscope/app/_tool/_team_create.py b/src/agentscope/app/_tool/_team_create.py
new file mode 100644
index 0000000..d2c2c47
--- /dev/null
+++ b/src/agentscope/app/_tool/_team_create.py
@@ -0,0 +1,145 @@
+# -*- coding: utf-8 -*-
+"""The TeamCreate tool — establishes a new team led by the current session."""
+from pydantic import Field
+
+from ._team_tool_base import _TeamToolBase
+from ..storage import TeamData, TeamRecord
+from ...message import TextBlock, ToolResultState
+from ...tool import ToolChunk, ParamsBase
+
+
+class _TeamCreateParams(ParamsBase):
+    """Parameters for :class:`TeamCreate`."""
+
+    name: str = Field(
+        description=(
+            "Display name of the team. Used by the user to identify the "
+            "team and shown in the team UI."
+        ),
+    )
+    description: str = Field(
+        description=(
+            "What the team is for — its overall goal or shared context. "
+            "This becomes the team's charter and is wired into every "
+            "member's system prompt so all members share the same "
+            "high-level understanding of why the team exists."
+        ),
+    )
+
+
+class TeamCreate(_TeamToolBase):
+    """Create a new team and become its leader."""
+
+    name: str = "TeamCreate"
+
+    description: str = """Create a new team led by your current session and \
+return its team id.
+
+## When to Use This Tool
+Use this tool when the task you've been given is best decomposed into \
+parallel sub-tasks executed by multiple specialised agents (members) \
+under your coordination. After creating the team, use ``AgentCreate`` to \
+spawn each member with its own role, prompt, and permission mode. NOTE: \
+the ``prompt`` you pass to ``AgentCreate`` is delivered to that member \
+automatically, so do **NOT** call ``TeamSay`` right after ``AgentCreate`` — \
+just wait for the members to report back.
+
+## When NOT to Use This Tool
+- The task is small enough to handle yourself.
+- You already lead a team in this session — a session can only lead \
+one team at a time.
+"""
+
+    input_schema: dict = _TeamCreateParams.model_json_schema()
+
+    async def __call__(
+        self,
+        name: str,
+        description: str,
+    ) -> ToolChunk:
+        """Create the team directly via storage.
+
+        Reads the current session record from storage to enforce the
+        precondition: a session can only lead one team at a time.
+        This makes the tool safe to attach unconditionally to
+        ``source='user'`` agents — calling it when the session
+        already leads a team returns a clear error rather than
+        silently corrupting state.
+
+        Args:
+            name (`str`):
+                Display name of the team.
+            description (`str`):
+                Description / charter of the team.
+
+        Returns:
+            `ToolChunk`:
+                A success message containing the team id, or an error
+                chunk if a precondition fails or creation failed.
+        """
+        try:
+            session = await self._storage.get_session(
+                self._user_id,
+                self._agent_id,
+                self._session_id,
+            )
+            if session is None:
+                return ToolChunk(
+                    content=[
+                        TextBlock(
+                            text=(
+                                "TeamCreate: session "
+                                f"{self._session_id} not found."
+                            ),
+                        ),
+                    ],
+                    state=ToolResultState.ERROR,
+                )
+            if session.team_id is not None:
+                return ToolChunk(
+                    content=[
+                        TextBlock(
+                            text=(
+                                "TeamCreate: this session is already "
+                                f"part of team {session.team_id}. A "
+                                "session can only lead one team at a "
+                                "time — dissolve the current one with "
+                                "TeamDelete first."
+                            ),
+                        ),
+                    ],
+                    state=ToolResultState.ERROR,
+                )
+
+            team = TeamRecord(
+                user_id=self._user_id,
+                session_id=self._session_id,
+                data=TeamData(
+                    name=name,
+                    description=description,
+                    member_ids=[],
+                ),
+            )
+            await self._storage.upsert_team(self._user_id, team)
+            await self._storage.set_session_team_id(
+                self._user_id,
+                self._session_id,
+                team.id,
+            )
+
+            return ToolChunk(
+                content=[
+                    TextBlock(
+                        text=(
+                            f"Team {team.id} ({team.data.name}) created. "
+                            f"You are the leader. Use AgentCreate to add "
+                            f"members, then TeamSay to coordinate them."
+                        ),
+                    ),
+                ],
+            )
+        except Exception as e:  # pylint: disable=broad-except
+            return ToolChunk(
+                content=[TextBlock(text=f"TeamCreate failed: {e}")],
+                state=ToolResultState.ERROR,
+            )
diff --git a/src/agentscope/app/_tool/_team_delete.py b/src/agentscope/app/_tool/_team_delete.py
new file mode 100644
index 0000000..ea34bfe
--- /dev/null
+++ b/src/agentscope/app/_tool/_team_delete.py
@@ -0,0 +1,130 @@
+# -*- coding: utf-8 -*-
+"""The TeamDelete tool — dissolves the team led by the current session."""
+from ._team_tool_base import _TeamToolBase
+from ...message import TextBlock, ToolResultState
+from ...tool import ToolChunk, ParamsBase
+
+
+class _TeamDeleteParams(ParamsBase):
+    """Parameters for :class:`TeamDelete` — none."""
+
+
+class TeamDelete(_TeamToolBase):
+    """Dissolve the team you currently lead and clean up all members."""
+
+    name: str = "TeamDelete"
+
+    description: str = """Dissolve the team you currently lead.
+
+## When to Use This Tool
+- The team has finished its work and you want to clean up.
+- The team is unrecoverably stuck and you want to start over.
+- You have collected the deliverables you need from each member.
+
+## When NOT to Use This Tool
+- Members are still producing useful output and you may want their \
+follow-up; dissolving deletes them and they cannot be revived.
+- You want to remove only one specific member — there is no "remove \
+single member" tool in v1, only whole-team dissolution.
+
+## Effects
+- Every member agent + its session is deleted.
+- The team record is deleted.
+- Your own session continues to exist but is no longer associated with \
+any team — the team-related tools become unavailable on subsequent \
+reasoning steps.
+
+This is irreversible.
+"""
+
+    input_schema: dict = _TeamDeleteParams.model_json_schema()
+
+    async def __call__(self) -> ToolChunk:
+        """Dissolve the bound session's team via :class:`SessionService`.
+
+        Reads the current session + team records from storage to
+        enforce: caller must be in a team AND must be its leader.
+        Then delegates the actual cancel + delete + bus-purge cascade
+        to :meth:`SessionService.delete_team`, which routes every
+        member through the shared session-level primitive — so worker
+        chat runs are cancelled cross-process and their bus state is
+        cleaned up the same way ``DELETE /agents`` would.
+
+        Returns:
+            `ToolChunk`:
+                A confirmation message, or an error chunk if a
+                precondition fails.
+        """
+        try:
+            session = await self._storage.get_session(
+                self._user_id,
+                self._agent_id,
+                self._session_id,
+            )
+            if session is None or session.team_id is None:
+                return ToolChunk(
+                    content=[
+                        TextBlock(
+                            text=(
+                                "TeamDelete: this session is not in "
+                                "any team."
+                            ),
+                        ),
+                    ],
+                    state=ToolResultState.ERROR,
+                )
+            team = await self._storage.get_team(
+                self._user_id,
+                session.team_id,
+            )
+            if team is None:
+                return ToolChunk(
+                    content=[
+                        TextBlock(
+                            text=(
+                                "TeamDelete: team "
+                                f"{session.team_id} no longer exists."
+                            ),
+                        ),
+                    ],
+                    state=ToolResultState.ERROR,
+                )
+            if team.session_id != self._session_id:
+                return ToolChunk(
+                    content=[
+                        TextBlock(
+                            text=(
+                                "TeamDelete: only the team leader "
+                                "can dissolve the team; this session "
+                                "is a worker."
+                            ),
+                        ),
+                    ],
+                    state=ToolResultState.ERROR,
+                )
+
+            # Local import to avoid a circular dependency between
+            # ``_tools`` and ``_service`` at module load.
+            from .._service import SessionService  # noqa: PLC0415
+
+            session_service = SessionService(
+                storage=self._storage,
+                message_bus=self._message_bus,
+            )
+            await session_service.delete_team(self._user_id, team.id)
+            return ToolChunk(
+                content=[
+                    TextBlock(
+                        text=(
+                            f"Team {team.id} dissolved. All members "
+                            f"deleted; your session is no longer "
+                            f"leading any team."
+                        ),
+                    ),
+                ],
+            )
+        except Exception as e:  # pylint: disable=broad-except
+            return ToolChunk(
+                content=[TextBlock(text=f"TeamDelete failed: {e}")],
+                state=ToolResultState.ERROR,
+            )
diff --git a/src/agentscope/app/_tool/_team_say.py b/src/agentscope/app/_tool/_team_say.py
new file mode 100644
index 0000000..eaf7d5a
--- /dev/null
+++ b/src/agentscope/app/_tool/_team_say.py
@@ -0,0 +1,352 @@
+# -*- coding: utf-8 -*-
+"""The TeamSay tool — sends a message to one or all team members."""
+from typing import Any
+
+from pydantic import Field
+
+from ._constants import HANDLE_LEN
+from ._team_tool_base import _TeamToolBase
+from ..message_bus import MessageBusKeys
+from .._bus_ops import enqueue_run_trigger
+from ..storage._utils import _ensure_team_members
+from ...message import HintBlock, TextBlock, ToolResultState
+from ...tool import ToolChunk, ParamsBase
+
+
+class _TeamSayParams(ParamsBase):
+    """Parameters for :class:`TeamSay`."""
+
+    content: str = Field(
+        description=(
+            "The message text. Plain natural-language; the recipient "
+            "sees it as a user message in its context."
+        ),
+    )
+    to: str | None = Field(
+        default=None,
+        description=(
+            "Recipient member name. Pass ``null`` (the default) to "
+            "broadcast to every other member of the team. To address "
+            "a specific peer use that member's name."
+        ),
+    )
+
+
+_LEADER_DESCRIPTION = """Send a message to a specific team member or \
+broadcast to all members.
+
+## When to Use This Tool
+- Pass **new** requirements or context from the user to a specific member.
+- Broadcast an update or coordination message to all members.
+- Ask a member a follow-up question when you need clarification.
+
+## When NOT to Use This Tool
+- DO NOT repeatedly call this to check on a member's progress — members \
+will automatically notify you via ``TeamSay`` when they finish their task. \
+Wait for their message instead of polling.
+- DO NOT call this right after creating a member by ``AgentCreate``, the \
+member will receive its initial task from the ``prompt`` of the \
+``AgentCreate`` call and report back when done — just wait for their message. \
+- The session is not in a team yet (call ``TeamCreate`` first).
+- You want to talk to yourself — use your own reasoning.
+
+## Important
+- Each member starts working immediately when created via AgentCreate. \
+When a member finishes its task, it will call ``TeamSay`` to report results \
+back to you. You do NOT need to prompt them — just wait for their reply.
+- **DO NOT** reply to a member's report message unless you have further \
+questions or requirements. ``TeamSay`` is for coordination, not chit-chat — \
+your top priority is to complete the overall task.
+"""
+
+_WORKER_DESCRIPTION = """Send a message to the team leader or broadcast to \
+all team members.
+
+## When to Use This Tool
+- **IMPORTANT**: When you finish your assigned task, you MUST call this \
+tool to report your results back to the leader. The leader is waiting \
+for your report — do not end your turn without sending it.
+- Share intermediate findings or ask the leader for clarification.
+- Broadcast information that other members might need.
+
+## When NOT to Use This Tool
+- You want to talk to yourself — use your own reasoning.
+- The message is a transient internal thought with no value to others.
+"""
+
+
+class TeamSay(_TeamToolBase):
+    """Send a message to a teammate (or broadcast to all teammates).
+
+    Resolves the team membership at ``__call__`` time from storage,
+    so a member added moments earlier in the same chat run is
+    addressable immediately.
+
+    The ``description`` shown to the agent differs by role: leaders
+    are reminded not to poll members, workers are reminded to report
+    results when done. The role is passed at construction time via
+    the ``role`` parameter.
+    """
+
+    name: str = "TeamSay"
+    description: str
+
+    is_concurrency_safe: bool = True
+    is_read_only: bool = True
+
+    input_schema: dict = _TeamSayParams.model_json_schema()
+
+    def __init__(
+        self,
+        *args: Any,
+        role: str = "leader",
+        **kwargs: Any,
+    ) -> None:
+        """Initialise with role-specific description.
+
+        Args:
+            role (`str`, defaults to ``"leader"``):
+                Either ``"leader"`` or ``"worker"``. Determines which
+                description the agent sees for this tool.
+            *args:
+                Forwarded to :class:`_TeamToolBase.__init__`.
+            **kwargs:
+                Forwarded to :class:`_TeamToolBase.__init__`.
+        """
+        super().__init__(*args, **kwargs)
+        self.description = (
+            _LEADER_DESCRIPTION if role == "leader" else _WORKER_DESCRIPTION
+        )
+
+    async def __call__(
+        self,
+        content: str,
+        to: str | None = None,
+    ) -> ToolChunk:
+        """Deliver the message directly via storage + message bus.
+
+        Reads the current session record from storage to resolve the
+        team_id (the agent's team membership may have changed since
+        agent assembly), builds the team's (agent_id, session_id)
+        directory, and pushes a HintBlock + wakeup to each recipient.
+
+        Args:
+            content (`str`):
+                Message body.
+            to (`str | None`, defaults to ``None``):
+                Display name of a specific team member to target, or
+                ``None`` for broadcast.  Routing is by name (not
+                agent id) so workers can address the leader by the
+                name they see in ``<team-message from="...">``.
+                Name uniqueness within a team is enforced at
+                ``AgentCreate`` time.
+
+        Returns:
+            `ToolChunk`:
+                A confirmation containing the recipient count, or an
+                error chunk on failure.
+        """
+        try:
+            session = await self._storage.get_session(
+                self._user_id,
+                self._agent_id,
+                self._session_id,
+            )
+            if session is None or session.team_id is None:
+                return ToolChunk(
+                    content=[
+                        TextBlock(
+                            text=(
+                                "TeamSay: this session is not in any "
+                                "team — call TeamCreate first if you "
+                                "want to start one."
+                            ),
+                        ),
+                    ],
+                    state=ToolResultState.ERROR,
+                )
+
+            team = await self._storage.get_team(
+                self._user_id,
+                session.team_id,
+            )
+            if team is None:
+                return ToolChunk(
+                    content=[
+                        TextBlock(
+                            text=(
+                                f"TeamSay: team {session.team_id} no longer "
+                                f"exists."
+                            ),
+                        ),
+                    ],
+                    state=ToolResultState.ERROR,
+                )
+
+            leader_session = await self._storage.get_session(
+                self._user_id,
+                "",
+                team.session_id,
+            )
+            if leader_session is None:
+                return ToolChunk(
+                    content=[
+                        TextBlock(
+                            text=(
+                                f"TeamSay: leader session "
+                                f"{team.session_id} missing for team "
+                                f"{team.id}."
+                            ),
+                        ),
+                    ],
+                    state=ToolResultState.ERROR,
+                )
+
+            # Build a (name -> (session_id, agent_id)) directory. The
+            # leader is always in the directory under its plain agent
+            # name; workers come from the team's members roster via
+            # ``ensure_team_members`` (which migrates legacy
+            # ``member_ids``-only records on first read). Invited
+            # members display as ``"<name>@<agent_id[:8]>"`` so a
+            # borrowed agent whose name collides with an already-created
+            # member (or the leader) remains addressable.
+            #
+            # Uniqueness of the resulting display strings within a team
+            # is preserved by the AgentCreate name check (which rejects
+            # ``@``) and by AgentInvite's one-borrow-per-agent-per-team
+            # rule.
+            leader_agent = await self._storage.get_agent(
+                self._user_id,
+                leader_session.agent_id,
+            )
+            leader_name = (
+                leader_agent.data.name
+                if leader_agent is not None
+                else leader_session.agent_id
+            )
+            directory: dict[str, tuple[str, str]] = {
+                leader_name: (leader_session.id, leader_session.agent_id),
+            }
+            members = await _ensure_team_members(
+                self._storage,
+                self._user_id,
+                team,
+            )
+            for member in members:
+                member_agent = await self._storage.get_agent(
+                    member.owner_id,
+                    member.agent_id,
+                )
+                if member_agent is None:
+                    continue
+                if member.role == "invited":
+                    display = (
+                        f"{member_agent.data.name}"
+                        f"@{member.agent_id[:HANDLE_LEN]}"
+                    )
+                else:
+                    display = member_agent.data.name
+                directory[display] = (member.session_id, member.agent_id)
+
+            own_session_ids = {sid for sid, _aid in directory.values()}
+            if self._session_id not in own_session_ids:
+                return ToolChunk(
+                    content=[
+                        TextBlock(
+                            text=(
+                                f"TeamSay: this session "
+                                f"({self._session_id}) is not part of "
+                                f"team {team.id}."
+                            ),
+                        ),
+                    ],
+                    state=ToolResultState.ERROR,
+                )
+
+            if to is None:
+                recipients: list[tuple[str, str]] = [
+                    (sid, aid)
+                    for sid, aid in directory.values()
+                    if sid != self._session_id
+                ]
+            else:
+                resolved = directory.get(to)
+                if resolved is None:
+                    known = sorted(directory.keys())
+                    return ToolChunk(
+                        content=[
+                            TextBlock(
+                                text=(
+                                    f"TeamSay: no team member is named "
+                                    f"{to!r}. Known members: {known}."
+                                ),
+                            ),
+                        ],
+                        state=ToolResultState.ERROR,
+                    )
+                target_session_id, target_agent_id = resolved
+                if target_session_id == self._session_id:
+                    return ToolChunk(
+                        content=[
+                            TextBlock(
+                                text=(
+                                    "TeamSay: cannot send a message to "
+                                    "yourself; talk to yourself in your "
+                                    "own reasoning instead."
+                                ),
+                            ),
+                        ],
+                        state=ToolResultState.ERROR,
+                    )
+                recipients = [(target_session_id, target_agent_id)]
+
+            # Resolve sender display name once.
+            sender_agent = await self._storage.get_agent(
+                self._user_id,
+                self._agent_id,
+            )
+            sender_name = (
+                sender_agent.data.name
+                if sender_agent is not None
+                else self._agent_id
+            )
+
+            hint = HintBlock(
+                hint=(
+                    f'<team-message from="{sender_name}">\n'
+                    f"{content}\n"
+                    f"</team-message>"
+                ),
+                source=sender_name,
+            )
+            payload = hint.model_dump(mode="json")
+
+            for sid, aid in recipients:
+                await self._message_bus.queue_push(
+                    MessageBusKeys.inbox(sid),
+                    payload,
+                )
+                await enqueue_run_trigger(
+                    self._message_bus,
+                    user_id=self._user_id,
+                    session_id=sid,
+                    agent_id=aid,
+                )
+
+            count = len(recipients)
+            target = "broadcast" if to is None else f"member {to!r}"
+            return ToolChunk(
+                content=[
+                    TextBlock(
+                        text=(
+                            f"Delivered to {count} recipient(s) "
+                            f"({target})."
+                        ),
+                    ),
+                ],
+            )
+        except Exception as e:  # pylint: disable=broad-except
+            return ToolChunk(
+                content=[TextBlock(text=f"TeamSay failed: {e}")],
+                state=ToolResultState.ERROR,
+            )
diff --git a/src/agentscope/app/_tool/_team_tool_base.py b/src/agentscope/app/_tool/_team_tool_base.py
new file mode 100644
index 0000000..04100bc
--- /dev/null
+++ b/src/agentscope/app/_tool/_team_tool_base.py
@@ -0,0 +1,99 @@
+# -*- coding: utf-8 -*-
+"""Base class shared by the team tools."""
+from typing import Any, TYPE_CHECKING
+
+from ...permission import (
+    PermissionBehavior,
+    PermissionContext,
+    PermissionDecision,
+)
+from ...tool import ToolBase
+
+if TYPE_CHECKING:
+    from ..message_bus import MessageBus
+    from ..storage import StorageBase
+    from ..workspace_manager import WorkspaceManagerBase
+
+
+class _TeamToolBase(ToolBase):
+    """Shared base for the team tools.
+
+    All team tools are constructed at agent assembly time (in
+    :func:`get_toolkit`) with the request-scoped ``user_id``,
+    ``session_id``, and ``agent_id`` plus ``storage`` + ``message_bus``
+    + ``workspace_manager`` references. Each tool's ``__call__`` does
+    its work directly via those dependencies — there is no intermediate
+    service layer.
+
+    Permissions: all team tools allow themselves unconditionally — the
+    agent's authority to call them is already gated by the
+    role/source-aware logic inside :func:`get_toolkit` that decides
+    which team tools to attach in the first place.
+    """
+
+    name: str
+    description: str
+    input_schema: dict[str, Any]
+    is_concurrency_safe: bool = False
+    is_read_only: bool = True
+    is_state_injected: bool = False
+    is_external_tool: bool = False
+    is_mcp: bool = False
+    mcp_name: str | None = None
+
+    def __init__(
+        self,
+        storage: "StorageBase",
+        message_bus: "MessageBus",
+        workspace_manager: "WorkspaceManagerBase",
+        user_id: str,
+        session_id: str,
+        agent_id: str,
+    ) -> None:
+        """Bind request-scoped identifiers and shared dependencies.
+
+        Args:
+            storage (`StorageBase`):
+                Application storage.
+            message_bus (`MessageBus`):
+                Application message bus for inter-session delivery.
+            workspace_manager (`WorkspaceManagerBase`):
+                Workspace manager, consulted by tools that provision
+                brand-new sessions (e.g. ``AgentInvite``) to honour
+                the deployment's isolation policy.
+            user_id (`str`):
+                The owner user id of the calling agent.
+            session_id (`str`):
+                The current session id of the calling agent.
+            agent_id (`str`):
+                The id of the agent invoking the tool.
+        """
+        self._storage = storage
+        self._message_bus = message_bus
+        self._workspace_manager = workspace_manager
+        self._user_id = user_id
+        self._session_id = session_id
+        self._agent_id = agent_id
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        """Always allow — gating is done by tool-attachment logic.
+
+        Args:
+            tool_input (`dict[str, Any]`):
+                The arguments the agent passed; ignored here.
+            context (`PermissionContext`):
+                The active permission context; ignored here.
+
+        Returns:
+            `PermissionDecision`:
+                An ``ALLOW`` decision with a brief explanation.
+        """
+        return PermissionDecision(
+            behavior=PermissionBehavior.ALLOW,
+            message=f"{self.name} is always allowed when attached to the "
+            f"agent.",
+        )
diff --git a/src/agentscope/app/_types.py b/src/agentscope/app/_types.py
new file mode 100644
index 0000000..a4180df
--- /dev/null
+++ b/src/agentscope/app/_types.py
@@ -0,0 +1,189 @@
+# -*- coding: utf-8 -*-
+"""Shared type aliases for the agentscope app layer."""
+from collections.abc import Awaitable, Callable
+from typing import TYPE_CHECKING, Protocol
+
+from pydantic import BaseModel, Field
+
+from ..agent import ContextConfig, ReActConfig
+from ..event import AgentEvent
+from ..middleware import MiddlewareBase
+from ..permission import PermissionContext
+from ..state import TaskContext
+from ..tool import ToolBase
+
+if TYPE_CHECKING:
+    from ._service._session_projection import SessionProjection
+    from .storage import AgentRecord, SessionRecord
+
+
+AgentMiddlewareFactory = Callable[
+    [str, str, str],
+    Awaitable[list[MiddlewareBase]],
+]
+# Async factory signature: ``(user_id, agent_id, session_id)`` →
+# awaitable of :class:`~agentscope.middleware.MiddlewareBase` instances.
+
+AgentToolFactory = Callable[
+    [str, str, str],
+    Awaitable[list[ToolBase]],
+]
+#  Async factory signature: ``(user_id, agent_id, session_id)`` →
+#  awaitable of :class:`~agentscope.tool.ToolBase` instances.
+
+
+class EventProjector(Protocol):
+    """Strategy that projects events from one session onto another.
+
+    Each projector owns one cross-session UI feed (HITL, progress,
+    errors, …). :class:`~agentscope.app._service.ChatService` calls
+    every registered projector once per event produced by a run; a
+    projector decides whether the event is relevant and, if so, mirrors
+    it onto the owning session's target via the shared
+    :class:`SessionProjection` primitive. Adding a feed means adding a
+    projector — no new bus wrapper, dispatcher, or manager.
+
+    Service dependencies a projector needs (e.g. storage, to resolve the
+    team a worker belongs to) are its own concern, injected at
+    construction. Only per-run request data is passed to
+    :meth:`maybe_project`.
+    """
+
+    async def maybe_project(
+        self,
+        user_id: str,
+        session_record: "SessionRecord",
+        agent_record: "AgentRecord",
+        event: AgentEvent,
+        projection: "SessionProjection",
+    ) -> None:
+        """Project ``event`` if it is relevant to this feed.
+
+        Implementations must be a no-op for irrelevant events and
+        sessions. They should not raise for ordinary "not applicable"
+        cases; ``ChatService`` guards the call with a catch-all so a
+        projection failure never tears down the producing run, but
+        projectors should not rely on that for control flow.
+
+        Args:
+            user_id (`str`):
+                The owner of the running session.
+            session_record (`SessionRecord`):
+                The currently-running session's record.
+            agent_record (`AgentRecord`):
+                The currently-running agent's record.
+            event (`AgentEvent`):
+                The event just published to this session's channel.
+            projection (`SessionProjection`):
+                Shared primitive used to write the durable entry and the
+                live notification.
+        """
+
+
+class SubAgentTemplate(BaseModel):
+    """A reusable blueprint for sub-agent creation within a team.
+
+    Developers register one or more templates at the ``create_app`` entry
+    point. When the leader agent calls ``AgentCreate`` with a matching
+    ``subagent_type``, the template's configuration is used instead of the
+    built-in defaults.
+
+    The :attr:`type` field serves as the routing key — it becomes an enum
+    value of the ``subagent_type`` parameter exposed to the LLM.  This is
+    distinct from the ``name`` parameter in ``AgentCreate``, which is the
+    per-instance identifier the leader assigns to each worker (used for
+    ``TeamSay(to=name)``).
+
+    All fields are pure data (no callables), so the template is fully
+    serializable for future config-driven startup.
+    """
+
+    type: str = Field(
+        description=(
+            "Template type identifier, e.g. ``'researcher'`` or "
+            "``'coder'``. Used as the enum value for the "
+            "``subagent_type`` parameter in ``AgentCreate``."
+        ),
+    )
+
+    description: str = Field(
+        description=(
+            "Agent-readable description of this sub-agent type. "
+            "Exposed to the LLM in the ``AgentCreate`` tool schema "
+            "so it can choose the appropriate type."
+        ),
+    )
+
+    system_prompt_template: str = Field(
+        description=(
+            "A Python format string for the worker's system prompt. "
+            "Available placeholders: ``{team_name}``, "
+            "``{team_description}``, ``{member_name}``, "
+            "``{member_description}``, ``{leader_name}``."
+        ),
+    )
+
+    context_config: ContextConfig = Field(
+        default_factory=ContextConfig,
+        description="Context configuration for the sub-agent.",
+    )
+
+    react_config: ReActConfig = Field(
+        default_factory=ReActConfig,
+        description="ReAct loop configuration for the sub-agent.",
+    )
+
+    permission_context: PermissionContext = Field(
+        default_factory=PermissionContext,
+        description=(
+            "Permission context applied to the sub-agent at "
+            "creation time. Controls what the worker is allowed "
+            "to do (e.g. read-only vs. full access)."
+        ),
+    )
+
+    override_leader_mode: bool = Field(
+        default=False,
+        description=(
+            "Whether the template's :attr:`permission_context.mode` "
+            "should override the leader session's mode for the worker. "
+            "``True`` — the worker runs in the template's mode "
+            "(typical for templates that pin a specific posture, e.g. "
+            "a read-only research worker). ``False`` (default) — the "
+            "worker inherits the leader's current mode."
+        ),
+    )
+
+    extend_leader_permission_rules: bool = Field(
+        default=True,
+        description=(
+            "Whether the leader session's allow/deny/ask permission "
+            "rules should be merged on top of the template's. "
+            "``True`` (default) — leader rules are appended after "
+            "the template's rules for each tool, so the worker "
+            "doesn't re-prompt for permissions the user has already "
+            "confirmed; the template's rules take precedence on "
+            "evaluation order. ``False`` — the template's rules are "
+            "the worker's complete rule set."
+        ),
+    )
+
+    extend_leader_working_directories: bool = Field(
+        default=True,
+        description=(
+            "Whether the leader session's working directories should "
+            "be merged into the template's. ``True`` (default) — "
+            "leader directories are added for keys not already in the "
+            "template (template wins on key collisions). ``False`` — "
+            "the template's working directories are the worker's "
+            "complete set."
+        ),
+    )
+
+    tasks_context: TaskContext = Field(
+        default_factory=TaskContext,
+        description=(
+            "Pre-defined task context for the sub-agent, allowing "
+            "the template to seed an initial workflow."
+        ),
+    )
diff --git a/src/agentscope/app/access/__init__.py b/src/agentscope/app/access/__init__.py
new file mode 100644
index 0000000..7d62dba
--- /dev/null
+++ b/src/agentscope/app/access/__init__.py
@@ -0,0 +1,30 @@
+# -*- coding: utf-8 -*-
+"""Public resource access policy extension points.
+
+Import from this package when customizing cross-owner resource access:
+
+.. code-block:: python
+
+    from agentscope.app.access import (
+        ResourceAccessPolicyBase,
+        ResourceKind,
+        ResourcePermission,
+        ResourceRef,
+    )
+"""
+
+from ._policy import (
+    DenyAllResourceAccessPolicy,
+    ResourceAccessPolicyBase,
+    ResourceKind,
+    ResourcePermission,
+    ResourceRef,
+)
+
+__all__ = [
+    "DenyAllResourceAccessPolicy",
+    "ResourceAccessPolicyBase",
+    "ResourceKind",
+    "ResourcePermission",
+    "ResourceRef",
+]
diff --git a/src/agentscope/app/access/_policy.py b/src/agentscope/app/access/_policy.py
new file mode 100644
index 0000000..5a934ae
--- /dev/null
+++ b/src/agentscope/app/access/_policy.py
@@ -0,0 +1,163 @@
+# -*- coding: utf-8 -*-
+"""Resource access policy primitives for cross-owner resource reads.
+
+This module defines the extension point used by the app service layer to
+decide whether a viewer can access resources owned by another user. The
+default policy denies all cross-owner access, preserving the historical
+owner-isolated behavior.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from enum import StrEnum
+
+from pydantic import BaseModel, Field
+
+from ..storage import StorageBase
+
+
+class ResourceKind(StrEnum):
+    """Resource kinds that can be resolved through the access policy."""
+
+    CREDENTIAL = "credential"
+    """A stored credential record."""
+
+    AGENT = "agent"
+    """A stored agent configuration."""
+
+    KNOWLEDGE_BASE = "knowledge_base"
+    """A stored knowledge base."""
+
+
+class ResourcePermission(StrEnum):
+    """Permission level granted for a referenced resource.
+
+    Values:
+        READ: The viewer can see and use the resource. Credentials remain
+            masked in API responses and can only be used by runtime code.
+        EDIT: The viewer can read/use the resource and also mutate it. This
+            is equivalent to co-owner access for the specific resource.
+
+    ``EDIT`` implies ``READ``.
+    """
+
+    READ = "read"
+    """Read/use access."""
+
+    EDIT = "edit"
+    """Read/use access plus mutation rights."""
+
+
+class ResourceRef(BaseModel):
+    """Reference to a resource owned by a specific user.
+
+    Policies return ``ResourceRef`` objects to describe cross-owner resources
+    that a viewer may access. Routers and runtime services then load the
+    concrete record through the existing owner-scoped storage APIs using
+    ``(owner_id, resource_id)``.
+    """
+
+    kind: ResourceKind = Field(
+        description="Resource kind: credential, agent, or knowledge_base.",
+    )
+    owner_id: str = Field(
+        description=(
+            "Resource owner user id, matching the storage record's user_id."
+        ),
+    )
+    resource_id: str = Field(
+        description=(
+            "Resource id under the owner, such as credential_id or agent_id."
+        ),
+    )
+    permission: ResourcePermission = Field(
+        default=ResourcePermission.READ,
+        description="Granted permission level. Defaults to read.",
+    )
+
+
+class ResourceAccessPolicyBase(ABC):
+    """Base class for cross-owner resource access policies.
+
+    Applications subclass this policy to read access rules from configuration,
+    external IAM systems, LDAP, request-scoped context, or any other source.
+
+    The policy intentionally does not manage users, groups, memberships, or
+    resource-share records in AgentScope storage. It only maps a ``viewer_id``
+    to resource references.
+    """
+
+    @abstractmethod
+    async def list_accessible(
+        self,
+        viewer_id: str,
+        kind: ResourceKind,
+        storage: StorageBase,
+    ) -> list[ResourceRef]:
+        """List cross-owner resources of ``kind`` accessible by ``viewer_id``.
+
+        The returned refs should not include resources owned by ``viewer_id``.
+        Callers merge the viewer's own resources from storage with these
+        cross-owner refs.
+
+        Args:
+            viewer_id (`str`): The current viewer's user id.
+            kind (`ResourceKind`): The resource kind to list.
+            storage (`StorageBase`): The owner-scoped storage backend. Policy
+                subclasses may use it for read-only lookups.
+
+        Returns:
+            `list[ResourceRef]`: The accessible cross-owner resource
+            references.
+        """
+
+    async def can_edit(
+        self,
+        viewer_id: str,
+        kind: ResourceKind,
+        owner_id: str,
+        resource_id: str,
+        storage: StorageBase,
+    ) -> bool:
+        """Return whether ``viewer_id`` may mutate the given resource.
+
+        Owners can always edit their own resources. For cross-owner access,
+        the default implementation falls back to :meth:`list_accessible` and
+        grants mutation only when a matching ref has
+        ``ResourcePermission.EDIT``. Subclasses may override this method to
+        perform a more efficient direct authorization check.
+
+        Args:
+            viewer_id (`str`): The current viewer's user id.
+            kind (`ResourceKind`): The resource kind.
+            owner_id (`str`): The resource owner's user id.
+            resource_id (`str`): The resource id under ``owner_id``.
+            storage (`StorageBase`): The owner-scoped storage backend.
+
+        Returns:
+            `bool`: ``True`` when mutation is allowed, otherwise ``False``.
+        """
+        if viewer_id == owner_id:
+            return True
+
+        refs = await self.list_accessible(viewer_id, kind, storage)
+        return any(
+            ref.kind == kind
+            and ref.owner_id == owner_id
+            and ref.resource_id == resource_id
+            and ref.permission == ResourcePermission.EDIT
+            for ref in refs
+        )
+
+
+class DenyAllResourceAccessPolicy(ResourceAccessPolicyBase):
+    """Default policy that denies all cross-owner resource access."""
+
+    async def list_accessible(
+        self,
+        viewer_id: str,
+        kind: ResourceKind,
+        storage: StorageBase,
+    ) -> list[ResourceRef]:
+        """Return no cross-owner resources."""
+        return []
diff --git a/src/agentscope/app/deps.py b/src/agentscope/app/deps.py
new file mode 100644
index 0000000..b26dcfe
--- /dev/null
+++ b/src/agentscope/app/deps.py
@@ -0,0 +1,315 @@
+# -*- coding: utf-8 -*-
+"""Shared FastAPI dependencies for the agentscope app."""
+from fastapi import Header, HTTPException, Request, status
+
+from .workspace_manager import WorkspaceManagerBase
+from ._manager import (
+    BackgroundTaskManager,
+    ChatRunRegistry,
+    SchedulerManager,
+)
+from ._service import (
+    ChatService,
+    KnowledgeBaseService,
+    ResourceAccessService,
+    SessionService,
+)
+from ._types import AgentMiddlewareFactory, AgentToolFactory
+from .message_bus import MessageBus
+from .rag.blob_store import BlobStoreBase
+from .rag.knowledge_base_manager import KnowledgeBaseManagerBase
+from .storage import StorageBase
+from ..rag import ParserBase
+
+
+async def get_current_user_id(
+    x_user_id: str = Header(
+        description="Caller's user ID. "
+        "Temporary header-based identity; will be replaced by JWT auth.",
+    ),
+) -> str:
+    """Return the caller's user ID from the ``X-User-ID`` request header.
+
+    Args:
+        x_user_id (`str`): Value of the ``X-User-ID`` header.
+
+    Returns:
+        `str`: The authenticated user ID.
+
+    Raises:
+        `HTTPException`: 401 if the header is missing or empty.
+    """
+    if not x_user_id:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="X-User-ID header is required.",
+        )
+    return x_user_id
+
+
+async def get_storage(request: Request) -> StorageBase:
+    """Return the application-wide storage backend.
+
+    Args:
+        request (`Request`): The incoming FastAPI request.
+
+    Returns:
+        `StorageBase`: The storage instance stored in ``app.state``.
+    """
+    return request.app.state.storage
+
+
+async def get_message_bus(request: Request) -> MessageBus:
+    """Return the application-wide message bus.
+
+    Args:
+        request (`Request`): The incoming FastAPI request.
+
+    Returns:
+        `MessageBus`: The message bus instance stored in ``app.state``.
+    """
+    return request.app.state.message_bus
+
+
+async def get_chat_service(request: Request) -> ChatService:
+    """Return the application-wide chat service.
+
+    Args:
+        request (`Request`): The incoming FastAPI request.
+
+    Returns:
+        `ChatService`: The chat service instance stored in ``app.state``.
+    """
+    return request.app.state.chat_service
+
+
+async def get_resource_access_service(
+    request: Request,
+) -> ResourceAccessService:
+    """Return the application-wide resource access service.
+
+    Args:
+        request (`Request`): The incoming FastAPI request.
+
+    Returns:
+        `ResourceAccessService`:
+            The access service stored in ``app.state`` — the single
+            entry point routers should use to resolve
+            credential / agent / knowledge base records.
+    """
+    return request.app.state.resource_access_service
+
+
+async def get_session_service(request: Request) -> SessionService:
+    """Return the application-wide session service.
+
+    Args:
+        request (`Request`): The incoming FastAPI request.
+
+    Returns:
+        `SessionService`: The session service instance stored in
+        ``app.state``.
+    """
+    return request.app.state.session_service
+
+
+async def get_chat_run_registry(request: Request) -> ChatRunRegistry:
+    """Return the per-process chat-run registry.
+
+    Args:
+        request (`Request`): The incoming FastAPI request.
+
+    Returns:
+        `ChatRunRegistry`: The registry stored in ``app.state``.
+    """
+    return request.app.state.chat_run_registry
+
+
+async def get_scheduler_manager(request: Request) -> SchedulerManager:
+    """Return the application-wide scheduler manager.
+
+    Args:
+        request (`Request`): The incoming FastAPI request.
+
+    Returns:
+        `SchedulerManager`: The scheduler manager stored in ``app.state``.
+    """
+    return request.app.state.scheduler_manager
+
+
+async def get_background_task_manager(
+    request: Request,
+) -> BackgroundTaskManager:
+    """Return the application-wide background task manager.
+
+    Args:
+        request (`Request`): The incoming FastAPI request.
+
+    Returns:
+        `BackgroundTaskManager`: The background task manager stored in
+        ``app.state``.
+    """
+    return request.app.state.background_task_manager
+
+
+async def get_workspace_manager(request: Request) -> WorkspaceManagerBase:
+    """Return the application-wide workspace manager.
+
+    Args:
+        request (`Request`): The incoming FastAPI request.
+
+    Returns:
+        `WorkspaceManagerBase`: The workspace manager stored in ``app.state``.
+    """
+    return request.app.state.workspace_manager
+
+
+async def get_extra_agent_middlewares(
+    request: Request,
+) -> AgentMiddlewareFactory | None:
+    """Return the caller-supplied agent middleware factory, if any.
+
+    Args:
+        request (`Request`): The incoming FastAPI request.
+
+    Returns:
+        `AgentMiddlewareFactory | None`: The factory passed to
+        :func:`~agentscope.app.create_app`, or ``None`` if not configured.
+    """
+    return request.app.state.extra_agent_middlewares
+
+
+async def get_extra_agent_tools(
+    request: Request,
+) -> AgentToolFactory | None:
+    """Return the caller-supplied agent tool factory, if any.
+
+    Args:
+        request (`Request`): The incoming FastAPI request.
+
+    Returns:
+        `AgentToolFactory | None`: The factory passed to
+        :func:`~agentscope.app.create_app`, or ``None`` if not configured.
+    """
+    return request.app.state.extra_agent_tools
+
+
+async def get_knowledge_base_service(
+    request: Request,
+) -> KnowledgeBaseService:
+    """Return the application-wide knowledge base service.
+
+    Args:
+        request (`Request`):
+            The incoming FastAPI request.
+
+    Returns:
+        `KnowledgeBaseService`:
+            The service stored in ``app.state``.
+
+    Raises:
+        `HTTPException`:
+            ``503`` when the app was created without a
+            ``knowledge_base_manager`` and therefore exposes no
+            knowledge base endpoints.
+    """
+    service = getattr(request.app.state, "knowledge_base_service", None)
+    if service is None:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail=(
+                "Knowledge base feature is disabled — pass a "
+                "knowledge_base_manager to create_app() to enable it."
+            ),
+        )
+    return service
+
+
+async def get_knowledge_base_manager(
+    request: Request,
+) -> KnowledgeBaseManagerBase:
+    """Return the application-wide knowledge base manager.
+
+    Args:
+        request (`Request`):
+            The incoming FastAPI request.
+
+    Returns:
+        `KnowledgeBaseManagerBase`:
+            The manager stored in ``app.state``.
+
+    Raises:
+        `HTTPException`:
+            ``503`` when the app was created without a
+            ``knowledge_base_manager``.
+    """
+    manager = getattr(request.app.state, "knowledge_base_manager", None)
+    if manager is None:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail=(
+                "Knowledge base feature is disabled — pass a "
+                "knowledge_base_manager to create_app() to enable it."
+            ),
+        )
+    return manager
+
+
+async def get_blob_store(request: Request) -> BlobStoreBase:
+    """Return the application-wide blob store.
+
+    Args:
+        request (`Request`):
+            The incoming FastAPI request.
+
+    Returns:
+        `BlobStoreBase`:
+            The blob store instance stored in ``app.state``.
+
+    Raises:
+        `HTTPException`:
+            ``503`` when no blob store is configured (e.g. the KB
+            feature was disabled at app-creation time).
+    """
+    blob_store = getattr(request.app.state, "blob_store", None)
+    if blob_store is None:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail=(
+                "Blob store is not configured — pass a "
+                "knowledge_base_manager (and optionally a blob_store) "
+                "to create_app() to enable knowledge base features."
+            ),
+        )
+    return blob_store
+
+
+async def get_knowledge_parsers(
+    request: Request,
+) -> list[ParserBase] | dict[str, ParserBase]:
+    """Return the parser registry configured on the app.
+
+    Args:
+        request (`Request`):
+            The incoming FastAPI request.
+
+    Returns:
+        `list[ParserBase] | dict[str, ParserBase]`:
+            The parser registry stored in ``app.state.knowledge_parsers``
+            — the same value the index worker uses to dispatch uploads.
+
+    Raises:
+        `HTTPException`:
+            ``503`` when the KB feature is disabled (no parsers
+            configured).
+    """
+    parsers = getattr(request.app.state, "knowledge_parsers", None)
+    if not parsers:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail=(
+                "Knowledge base feature is disabled — pass a "
+                "knowledge_base_manager to create_app() to enable it."
+            ),
+        )
+    return parsers
diff --git a/src/agentscope/app/message_bus/__init__.py b/src/agentscope/app/message_bus/__init__.py
new file mode 100644
index 0000000..780e006
--- /dev/null
+++ b/src/agentscope/app/message_bus/__init__.py
@@ -0,0 +1,14 @@
+# -*- coding: utf-8 -*-
+"""The message bus module — live transport for cross-session messages."""
+
+from ._base import MessageBus
+from ._in_memory_message_bus import InMemoryMessageBus
+from ._keys import MessageBusKeys
+from ._redis_message_bus import RedisMessageBus
+
+__all__ = [
+    "InMemoryMessageBus",
+    "MessageBus",
+    "MessageBusKeys",
+    "RedisMessageBus",
+]
diff --git a/src/agentscope/app/message_bus/_base.py b/src/agentscope/app/message_bus/_base.py
new file mode 100644
index 0000000..eb80823
--- /dev/null
+++ b/src/agentscope/app/message_bus/_base.py
@@ -0,0 +1,810 @@
+# -*- coding: utf-8 -*-
+"""The message bus abstract base class.
+
+The message bus is the *live* transport layer used to coordinate work
+across sessions and processes. It is intentionally separate from
+:class:`StorageBase`, which owns *persistent* records: storage may live
+on a relational database while the bus stays on a push-capable backend
+(Redis, NATS, …) where waking idle consumers and fanning out events is
+cheap.
+
+The interface is grouped by **consumption semantics** — i.e. how a
+payload's lifetime ends — rather than by business use case. Callers map
+their own concepts (agent inbox, session SSE replay, idle wake-up, …)
+onto the right mode plus a key naming convention they own.
+
+Three orthogonal modes are exposed:
+
+============================  ===========================================
+Mode A — drain queue          Mode C — replay log
+``queue_push`` /              ``log_append`` /
+``queue_drain``               ``log_read`` / ``log_trim``
+
+Single-consumer, ack-on-read. Multi-consumer, externally bounded.
+Each entry returned at most       Each reader tracks its own cursor;
+once; storage drops it the        entries persist until trimmed,
+moment it is read. TTL bounds     ``max_len`` truncates from the head,
+orphaned data when the consumer   or TTL expires the whole key.
+disappears.
+============================  ===========================================
+
+Mode D — transient broadcast: ``publish`` / ``subscribe``. Fire-and-forget
+pub/sub; only currently-subscribed listeners receive a payload, no
+history. Use for wake-up signals where missed-while-offline is fine.
+
+Counted broadcast (one entry consumed by N distinct readers) is
+intentionally not exposed as a primitive: in practice it requires
+consumer-group coordination (Redis Streams' XREADGROUP/XACK semantics)
+and adds substantial state. Producers wanting "fan out to N members"
+should fan out at write time — push one entry per recipient inbox using
+Mode A. The bus stays simple; deduplication is the producer's
+responsibility.
+"""
+from abc import ABC, abstractmethod
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from typing import Any, Callable, Self
+
+from typing_extensions import deprecated
+
+from ._keys import MessageBusKeys
+
+
+class MessageBus(ABC):  # pylint: disable=too-many-public-methods
+    """Abstract base class for live message transport.
+
+    Implementations expose three consumption modes (drain queue, replay
+    log, transient broadcast) over arbitrary string keys and JSON-style
+    dict payloads. Callers own key naming and payload schemas.
+    """
+
+    async def __aenter__(self) -> Self:
+        """Open underlying transport resources (connection pools, …).
+
+        Returns:
+            `Self`:
+                The bus instance, for use as an async context manager.
+        """
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: Any,
+    ) -> None:
+        """Release transport resources on context exit.
+
+        Args:
+            exc_type (`type[BaseException] | None`):
+                The exception class raised inside the context, if any.
+            exc_value (`BaseException | None`):
+                The exception instance raised inside the context, if any.
+            traceback (`Any`):
+                The traceback associated with the exception, if any.
+        """
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        """Release underlying transport resources. Default is a no-op."""
+
+    # ------------------------------------------------------------------
+    # Mode A — drain queue (single consumer, ack-on-read)
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    async def queue_push(
+        self,
+        key: str,
+        payload: dict,
+        *,
+        ttl_secs: int | None = None,
+    ) -> str:
+        """Append ``payload`` to the drain queue at ``key``.
+
+        Drain queues are single-consumer, ack-on-read: a subsequent
+        :meth:`queue_drain` returns each entry exactly once and then
+        deletes it. ``ttl_secs`` bounds the queue's lifetime so a key
+        whose consumer disappears does not accumulate entries forever.
+
+        Args:
+            key (`str`):
+                Queue identifier. Caller-defined naming convention; the
+                bus treats it as opaque.
+            payload (`dict`):
+                JSON-serializable dict to enqueue. Schema is the
+                caller's responsibility.
+            ttl_secs (`int | None`, optional):
+                If set, refresh the queue key's expiry to this many
+                seconds on every push (sliding TTL). When ``None``, the
+                key never expires and must be drained or deleted
+                explicitly.
+
+        Returns:
+            `str`:
+                Transport-level entry id (e.g. the Redis Stream entry
+                id). Useful for tracing; not required for normal
+                consumption.
+        """
+
+    @abstractmethod
+    async def queue_drain(
+        self,
+        key: str,
+        max_count: int = 100,
+    ) -> list[tuple[str, dict]]:
+        """Drain up to ``max_count`` entries from the queue at ``key``.
+
+        Returned entries are removed from the queue in the same
+        operation, so a subsequent call returns only entries that
+        arrived after this one. Safe under the single-consumer-per-key
+        invariant.
+
+        Args:
+            key (`str`):
+                Queue identifier.
+            max_count (`int`, defaults to ``100``):
+                Maximum number of entries to return in one call.
+                Older entries are returned first; remaining entries
+                stay in the queue for the next call.
+
+        Returns:
+            `list[tuple[str, dict]]`:
+                ``(entry_id, payload)`` pairs in arrival order. Empty
+                list when the queue is empty.
+        """
+
+    @abstractmethod
+    async def queue_delete(self, key: str) -> None:
+        """Delete the drain queue at ``key`` and all of its entries.
+
+        Idempotent: a no-op when the key does not exist. Used by
+        :meth:`session_purge` to drop a session's inbox during
+        cascade-delete.
+
+        Args:
+            key (`str`):
+                Queue identifier.
+        """
+
+    # ------------------------------------------------------------------
+    # Mode C — replay log (multi-consumer, externally bounded)
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    async def log_append(
+        self,
+        key: str,
+        payload: dict,
+        *,
+        ttl_secs: int | None = None,
+        max_len: int | None = None,
+    ) -> str:
+        """Append ``payload`` to the replay log at ``key``.
+
+        Replay logs are append-only; readers track their own cursor and
+        may join at any time. Lifetime is bounded externally: by
+        ``ttl_secs`` (whole key expires), by ``max_len`` (oldest
+        entries trimmed once the log exceeds the cap), or by explicit
+        :meth:`log_trim`.
+
+        Args:
+            key (`str`):
+                Log identifier.
+            payload (`dict`):
+                JSON-serializable dict to append.
+            ttl_secs (`int | None`, optional):
+                If set, refresh the key's expiry to this many seconds
+                on every append (sliding TTL). ``None`` means no TTL.
+            max_len (`int | None`, optional):
+                If set, cap the log at approximately this many entries
+                — older entries are trimmed when the cap is exceeded.
+                The cap is approximate so the operation can use the
+                backend's efficient near-trim mode (e.g. ``XADD MAXLEN
+                ~N``). ``None`` means no cap.
+
+        Returns:
+            `str`:
+                Transport-level entry id, useful as a cursor for
+                subsequent :meth:`log_read` calls.
+        """
+
+    @abstractmethod
+    async def log_read(
+        self,
+        key: str,
+        since: str | None = None,
+        max_count: int = 100,
+    ) -> list[tuple[str, dict]]:
+        """Read up to ``max_count`` entries from the replay log at
+        ``key``, starting after ``since``.
+
+        Reads are non-destructive: the same entries can be returned to
+        any number of readers, or to the same reader on retry. Each
+        reader is responsible for tracking its own cursor.
+
+        Args:
+            key (`str`):
+                Log identifier.
+            since (`str | None`, optional):
+                Cursor — return entries strictly newer than this id.
+                Pass the last ``entry_id`` from the previous read.
+                ``None`` reads from the beginning of the log.
+            max_count (`int`, defaults to ``100``):
+                Maximum number of entries to return.
+
+        Returns:
+            `list[tuple[str, dict]]`:
+                ``(entry_id, payload)`` pairs in append order. Empty
+                list when no entries are newer than ``since``.
+        """
+
+    @abstractmethod
+    async def log_trim(
+        self,
+        key: str,
+        before_id: str | None = None,
+    ) -> None:
+        """Trim the replay log at ``key``.
+
+        Args:
+            key (`str`):
+                Log identifier.
+            before_id (`str | None`, optional):
+                Drop all entries with id strictly older than this.
+                ``None`` drops the entire log (i.e. deletes the key).
+        """
+
+    # ------------------------------------------------------------------
+    # Mode D — transient broadcast (fire-and-forget)
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    async def publish(
+        self,
+        key: str,
+        payload: dict,
+    ) -> None:
+        """Publish ``payload`` on the broadcast channel ``key``.
+
+        Only subscribers connected at the moment of publish receive the
+        payload — no history is retained. Use for wake-up signals or
+        short-lived notifications where missed-while-offline is
+        acceptable.
+
+        Args:
+            key (`str`):
+                Channel identifier.
+            payload (`dict`):
+                JSON-serializable dict delivered as-is to subscribers.
+        """
+
+    @abstractmethod
+    async def subscribe(
+        self,
+        key: str,
+        *,
+        on_ready: Callable[[], None] | None = None,
+    ) -> AsyncGenerator[dict, None]:
+        """Yield broadcast payloads for ``key`` until the consumer
+        closes the generator.
+
+        Subscriptions are best-effort: only payloads published *after*
+        the subscription is established are delivered. Callers own the
+        generator's lifetime — closing it releases the underlying
+        subscription.
+
+        Args:
+            key (`str`):
+                Channel identifier.
+            on_ready (`Callable[[], None] | None`, optional):
+                If supplied, invoked exactly once after the underlying
+                subscription is established and before any payload is
+                yielded. Used by callers that need to block a
+                bootstrapping step (e.g.
+                ``SessionTriggerListenerManager.start``) until the
+                subscription is live, so a publish-immediately-after
+                race is impossible.
+
+        Yields:
+            `dict`:
+                Each payload originally passed to :meth:`publish`.
+        """
+        # The empty `yield` makes Python treat this as an async generator
+        # function (return type AsyncGenerator) rather than a coroutine
+        # returning an AsyncGenerator. Subclasses override it; this body
+        # never runs.
+        if False:  # pylint: disable=using-constant-test
+            yield  # pylint: disable=unreachable
+
+    # ------------------------------------------------------------------
+    # Mode E — distributed lock (cluster-wide mutex)
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    @asynccontextmanager
+    async def acquire_lock(
+        self,
+        key: str,
+        *,
+        ttl_secs: int = 600,
+    ) -> AsyncGenerator[None, None]:
+        """Acquire a distributed mutex on ``key``.
+
+        Blocks until the lock is acquired, then yields. The
+        implementation maintains the lock across long-running
+        bodies (typically with a heartbeat task that renews the
+        TTL) so the lease only expires if the holding process
+        actually crashes — at which point another acquirer may
+        take over after at most ``ttl_secs``.
+
+        Args:
+            key (`str`):
+                Lock identifier.
+            ttl_secs (`int`, defaults to ``600``):
+                Lease duration in seconds. The implementation
+                should renew this periodically while the body
+                runs; callers do not need to.
+
+        Yields:
+            `None`: while the lock is held.
+        """
+        # The decorator-based abstract method requires a body for
+        # @asynccontextmanager to work; subclasses override it.
+        if False:  # pylint: disable=using-constant-test
+            yield  # pylint: disable=unreachable
+
+    @abstractmethod
+    async def is_locked(self, key: str) -> bool:
+        """Return whether ``key`` currently holds a lock.
+
+        Args:
+            key (`str`):
+                Lock identifier (same key passed to
+                :meth:`acquire_lock`).
+
+        Returns:
+            `bool`:
+                ``True`` if some process holds the lock right now.
+        """
+
+    # ------------------------------------------------------------------
+    # Mode F — registry map (hash-keyed namespace)
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    async def registry_set(
+        self,
+        namespace: str,
+        field: str,
+        value: str,
+        *,
+        ttl_secs: int | None = None,
+    ) -> None:
+        """Set ``field`` to ``value`` in the registry at ``namespace``.
+
+        If the namespace does not exist it is created. When
+        ``ttl_secs`` is supplied, the namespace's TTL is refreshed
+        (sliding) — individual fields do not carry independent TTLs.
+
+        Args:
+            namespace (`str`):
+                Registry key (e.g. ``"agentscope:bg_tasks:sess123"``).
+            field (`str`):
+                Field name within the registry.
+            value (`str`):
+                Serialized value to store.
+            ttl_secs (`int | None`, optional):
+                Refresh the namespace expiry to this many seconds.
+        """
+
+    @abstractmethod
+    async def registry_del(self, namespace: str, field: str) -> None:
+        """Remove ``field`` from the registry at ``namespace``.
+
+        A no-op when the field or namespace does not exist.
+
+        Args:
+            namespace (`str`):
+                Registry key.
+            field (`str`):
+                Field to remove.
+        """
+
+    @abstractmethod
+    async def registry_exists(self, namespace: str, field: str) -> bool:
+        """Return whether ``field`` exists in the registry at
+        ``namespace``.
+
+        Args:
+            namespace (`str`):
+                Registry key.
+            field (`str`):
+                Field to check.
+
+        Returns:
+            `bool`:
+                ``True`` if the field is present.
+        """
+
+    @abstractmethod
+    async def registry_getall(
+        self,
+        namespace: str,
+    ) -> dict[str, str]:
+        """Return all field-value pairs in the registry at
+        ``namespace``.
+
+        Args:
+            namespace (`str`):
+                Registry key.
+
+        Returns:
+            `dict[str, str]`:
+                All entries. Empty dict when the namespace is absent.
+        """
+
+    @abstractmethod
+    async def registry_drop(self, namespace: str) -> None:
+        """Delete the entire registry at ``namespace``.
+
+        Idempotent: a no-op when the namespace does not exist.
+
+        Args:
+            namespace (`str`):
+                Registry key to delete.
+        """
+
+    # ==================================================================
+    # Deprecated domain helpers
+    #
+    # These thin shells delegate to the generic primitives above. They
+    # exist so that code written against the old API keeps working for
+    # one release cycle; new code should use the primitives + MessageBusKeys
+    # (or the standalone functions in agentscope.app._service) directly.
+    #
+    # The _XXX_KEY class-level constants are kept as well — some tests
+    # reference them — but new code should use MessageBusKeys instead.
+    # ==================================================================
+
+    # Key constants (kept for backward compat) -------------------------
+
+    _SESSION_LOCK_KEY = "agentscope:session:lock:{sid}"
+    _SESSION_EVENTS_KEY = "agentscope:session:events:{sid}"
+    _SESSION_CANCEL_KEY = "agentscope:session:cancel"
+    _SESSION_RUN_TTL_SECS = 600
+    _SESSION_REPLAY_MAX_LEN = 1000
+    _INBOX_KEY = "agentscope:inbox:{sid}"
+    _WAKEUP_QUEUE_KEY = "agentscope:wakeups"
+    _WAKEUP_SIGNAL_KEY = "agentscope:wakeup_signal"
+    _BG_TASKS_KEY = "agentscope:bg_tasks:{sid}"
+    _BG_TASKS_TTL_SECS = 86400
+    _TASK_CANCEL_KEY = "agentscope:task:cancel"
+
+    # Session run coordination -----------------------------------------
+
+    @deprecated(
+        "Use acquire_lock(MessageBusKeys.session_lock(sid), ...) directly.",
+    )
+    @asynccontextmanager
+    async def session_run(self, session_id: str) -> AsyncGenerator[None, None]:
+        """Acquire the session lock, yield, then trim the replay log."""
+        async with self.acquire_lock(
+            self._SESSION_LOCK_KEY.format(sid=session_id),
+            ttl_secs=self._SESSION_RUN_TTL_SECS,
+        ):
+            try:
+                yield
+            finally:
+                await self.log_trim(
+                    self._SESSION_EVENTS_KEY.format(sid=session_id),
+                )
+
+    @deprecated(
+        "Use is_locked(MessageBusKeys.session_lock(sid)) directly.",
+    )
+    async def session_is_running(self, session_id: str) -> bool:
+        """Check whether some process holds the session lock."""
+        return await self.is_locked(
+            self._SESSION_LOCK_KEY.format(sid=session_id),
+        )
+
+    @deprecated(
+        "Use publish_session_event(bus, sid, event) from "
+        "agentscope.app._bus_ops directly.",
+    )
+    async def session_publish_event(
+        self,
+        session_id: str,
+        event: dict,
+    ) -> str:
+        """Append + fan-out a session event."""
+        key = self._SESSION_EVENTS_KEY.format(sid=session_id)
+        entry_id = await self.log_append(
+            key,
+            event,
+            max_len=self._SESSION_REPLAY_MAX_LEN,
+        )
+        await self.publish(key, {**event, "_entry_id": entry_id})
+        return entry_id
+
+    @deprecated(
+        "Use log_read(MessageBusKeys.session_events(sid), ...) directly.",
+    )
+    async def session_read_events(
+        self,
+        session_id: str,
+        since: str | None = None,
+        max_count: int = 1000,
+    ) -> list[tuple[str, dict]]:
+        """Read events from the session's replay log."""
+        return await self.log_read(
+            self._SESSION_EVENTS_KEY.format(sid=session_id),
+            since=since,
+            max_count=max_count,
+        )
+
+    @deprecated(
+        "Use subscribe(MessageBusKeys.session_events(sid), ...) directly, "
+        "stripping _entry_id from each payload.",
+    )
+    async def session_subscribe_events(
+        self,
+        session_id: str,
+        *,
+        on_ready: Callable[[], None] | None = None,
+    ) -> AsyncGenerator[dict, None]:
+        """Live-subscribe to session events, stripping _entry_id."""
+        key = self._SESSION_EVENTS_KEY.format(sid=session_id)
+        async for payload in self.subscribe(key, on_ready=on_ready):
+            yield {k: v for k, v in payload.items() if k != "_entry_id"}
+
+    # Cross-process cancel ---------------------------------------------
+
+    @deprecated(
+        "Use publish(MessageBusKeys.session_cancel_channel(), "
+        "{'session_id': sid}) directly.",
+    )
+    async def session_publish_cancel(self, session_id: str) -> None:
+        """Broadcast a session cancel request."""
+        await self.publish(
+            self._SESSION_CANCEL_KEY,
+            {"session_id": session_id},
+        )
+
+    @deprecated(
+        "Use subscribe(MessageBusKeys.session_cancel_channel(), ...) "
+        "directly, extracting session_id from the payload.",
+    )
+    async def session_subscribe_cancel(
+        self,
+        *,
+        on_ready: Callable[[], None] | None = None,
+    ) -> AsyncGenerator[str, None]:
+        """Subscribe to session cancel broadcasts, yielding session ids."""
+        async for payload in self.subscribe(
+            self._SESSION_CANCEL_KEY,
+            on_ready=on_ready,
+        ):
+            sid = payload.get("session_id")
+            if isinstance(sid, str):
+                yield sid
+
+    # Purge -------------------------------------------------------------
+
+    @deprecated(
+        "Call log_trim / queue_delete / registry_drop with "
+        "MessageBusKeys directly.",
+    )
+    async def session_purge(self, session_id: str) -> None:
+        """Delete all per-session bus state."""
+        await self.log_trim(self._SESSION_EVENTS_KEY.format(sid=session_id))
+        await self.queue_delete(self._INBOX_KEY.format(sid=session_id))
+        await self.registry_drop(self._BG_TASKS_KEY.format(sid=session_id))
+
+    # Inbox -----------------------------------------------------------
+
+    @deprecated(
+        "Use queue_push(MessageBusKeys.inbox(sid), ...) directly.",
+    )
+    async def inbox_push(
+        self,
+        session_id: str,
+        msg: dict,
+        *,
+        ttl_secs: int | None = None,
+    ) -> str:
+        """Push a message to a session's inbox."""
+        return await self.queue_push(
+            self._INBOX_KEY.format(sid=session_id),
+            msg,
+            ttl_secs=ttl_secs,
+        )
+
+    @deprecated(
+        "Use queue_drain(MessageBusKeys.inbox(sid), ...) directly.",
+    )
+    async def inbox_drain(
+        self,
+        session_id: str,
+        max_count: int = 100,
+    ) -> list[tuple[str, dict]]:
+        """Drain pending inbox messages for a session."""
+        return await self.queue_drain(
+            self._INBOX_KEY.format(sid=session_id),
+            max_count=max_count,
+        )
+
+    # Wakeup ----------------------------------------------------------
+
+    @deprecated(
+        "Use enqueue_run_trigger(bus, ...) from "
+        "agentscope.app._bus_ops directly.",
+    )
+    async def enqueue_wakeup(
+        self,
+        user_id: str,
+        session_id: str,
+        agent_id: str,
+    ) -> None:
+        """Enqueue an idle-session wake-up."""
+        await self.queue_push(
+            self._WAKEUP_QUEUE_KEY,
+            {
+                "user_id": user_id,
+                "session_id": session_id,
+                "agent_id": agent_id,
+                "kind": MessageBusKeys.WAKEUP_KIND_WAKE,
+                "input": None,
+            },
+        )
+        await self.publish(self._WAKEUP_SIGNAL_KEY, {})
+
+    @deprecated(
+        "Use enqueue_run_trigger(bus, ...) from "
+        "agentscope.app._bus_ops directly.",
+    )
+    async def enqueue_input(
+        self,
+        user_id: str,
+        session_id: str,
+        agent_id: str,
+        *,
+        kind: str,
+        inputs: dict | None = None,
+    ) -> None:
+        """Enqueue a typed run trigger."""
+        await self.queue_push(
+            self._WAKEUP_QUEUE_KEY,
+            {
+                "user_id": user_id,
+                "session_id": session_id,
+                "agent_id": agent_id,
+                "kind": kind,
+                "input": inputs,
+            },
+        )
+        await self.publish(self._WAKEUP_SIGNAL_KEY, {})
+
+    @deprecated(
+        "Use queue_drain(MessageBusKeys.wakeup_queue(), ...) directly.",
+    )
+    async def dequeue_wakeups(
+        self,
+        max_count: int = 64,
+    ) -> list[dict]:
+        """Drain pending run-trigger entries."""
+        entries = await self.queue_drain(
+            self._WAKEUP_QUEUE_KEY,
+            max_count=max_count,
+        )
+        return [payload for _entry_id, payload in entries]
+
+    @deprecated(
+        "Use subscribe(MessageBusKeys.wakeup_signal(), ...) directly.",
+    )
+    async def subscribe_wakeup_signal(
+        self,
+        *,
+        on_ready: Callable[[], None] | None = None,
+    ) -> AsyncGenerator[dict, None]:
+        """Subscribe to the shared wake-up signal channel."""
+        async for payload in self.subscribe(
+            self._WAKEUP_SIGNAL_KEY,
+            on_ready=on_ready,
+        ):
+            yield payload
+
+    # Background task registry -------------------------------------------
+
+    @deprecated(
+        "Use registry_set(MessageBusKeys.bg_tasks(sid), ...) directly.",
+    )
+    async def bg_task_register(
+        self,
+        session_id: str,
+        task_id: str,
+        metadata: str,
+    ) -> None:
+        """Register a background task."""
+        await self.registry_set(
+            self._BG_TASKS_KEY.format(sid=session_id),
+            task_id,
+            metadata,
+            ttl_secs=self._BG_TASKS_TTL_SECS,
+        )
+
+    @deprecated(
+        "Use registry_del(MessageBusKeys.bg_tasks(sid), tid) directly.",
+    )
+    async def bg_task_unregister(
+        self,
+        session_id: str,
+        task_id: str,
+    ) -> None:
+        """Unregister a background task."""
+        await self.registry_del(
+            self._BG_TASKS_KEY.format(sid=session_id),
+            task_id,
+        )
+
+    @deprecated(
+        "Use registry_exists(MessageBusKeys.bg_tasks(sid), tid) directly.",
+    )
+    async def bg_task_exists(
+        self,
+        session_id: str,
+        task_id: str,
+    ) -> bool:
+        """Check whether a background task is registered."""
+        return await self.registry_exists(
+            self._BG_TASKS_KEY.format(sid=session_id),
+            task_id,
+        )
+
+    @deprecated(
+        "Use registry_getall(MessageBusKeys.bg_tasks(sid)) directly.",
+    )
+    async def bg_task_list(
+        self,
+        session_id: str,
+    ) -> dict[str, str]:
+        """List all background tasks for a session."""
+        return await self.registry_getall(
+            self._BG_TASKS_KEY.format(sid=session_id),
+        )
+
+    @deprecated(
+        "Use registry_drop(MessageBusKeys.bg_tasks(sid)) directly.",
+    )
+    async def bg_task_purge(self, session_id: str) -> None:
+        """Delete all background task entries for a session."""
+        await self.registry_drop(
+            self._BG_TASKS_KEY.format(sid=session_id),
+        )
+
+    @deprecated(
+        "Use publish(MessageBusKeys.task_cancel_channel(), "
+        "{'task_id': tid}) directly.",
+    )
+    async def task_publish_cancel(self, task_id: str) -> None:
+        """Broadcast a cancel request for a single background task."""
+        await self.publish(self._TASK_CANCEL_KEY, {"task_id": task_id})
+
+    @deprecated(
+        "Use subscribe(MessageBusKeys.task_cancel_channel(), ...) "
+        "directly, extracting task_id from the payload.",
+    )
+    async def task_subscribe_cancel(
+        self,
+        *,
+        on_ready: Callable[[], None] | None = None,
+    ) -> AsyncGenerator[str, None]:
+        """Subscribe to task cancel broadcasts, yielding task ids."""
+        async for payload in self.subscribe(
+            self._TASK_CANCEL_KEY,
+            on_ready=on_ready,
+        ):
+            tid = payload.get("task_id")
+            if isinstance(tid, str):
+                yield tid
diff --git a/src/agentscope/app/message_bus/_in_memory_message_bus.py b/src/agentscope/app/message_bus/_in_memory_message_bus.py
new file mode 100644
index 0000000..3b09ea1
--- /dev/null
+++ b/src/agentscope/app/message_bus/_in_memory_message_bus.py
@@ -0,0 +1,470 @@
+# -*- coding: utf-8 -*-
+"""In-memory message bus implementation.
+
+A pure-Python :class:`MessageBus` backed by :mod:`asyncio` primitives,
+Python dicts and lists.  Designed for **single-process** use — local
+development, unit tests, and examples that want to avoid a Redis
+dependency.
+
+.. note::
+
+   **Not suitable for production multiprocess deployments.** All state
+   lives inside the process; there is no persistence, no cross-process
+   pub/sub, and the "distributed" lock is just an :class:`asyncio.Lock`.
+   For real deployments use :class:`RedisMessageBus` (or another
+   networked backend).
+"""
+from __future__ import annotations
+
+import asyncio
+import uuid
+from collections import defaultdict
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from typing import Callable, Self
+
+from ._base import MessageBus
+
+
+class InMemoryMessageBus(MessageBus):
+    """In-memory implementation of :class:`MessageBus`.
+
+    Mapping of bus modes to in-memory structures:
+
+    - **Mode A (drain queue)** — each key maps to a
+      :class:`list[tuple[str, dict]]` of ``(entry_id, payload)`` pairs.
+      ``queue_push`` appends; ``queue_drain`` pops from the front (FIFO)
+      and deletes the returned entries.
+    - **Mode C (replay log)** — same underlying list structure, but
+      ``log_read`` is non-destructive.  ``log_trim`` removes entries
+      in-place.
+    - **Mode D (transient broadcast)** — each channel keeps a set of
+      :class:`asyncio.Queue` subscribers.  ``publish`` pushes to all
+      currently-subscribed queues; ``subscribe`` yields from one.
+    - **Mode E (distributed lock)** — :class:`asyncio.Lock` per key,
+      suitable only for single-process concurrency.
+    - **Mode F (registry map)** — ``dict[str, dict[str, str]]``, one
+      nested dict per namespace.
+
+    Entry ids are monotonic ``"<seq>-0"`` strings (e.g. ``"1-0"``,
+    ``"2-0"``, …).  They are **not** lexicographically sortable once
+    the sequence exceeds single digits; comparison must parse the
+    numeric prefix (as :meth:`log_read` does internally).
+    """
+
+    def __init__(self) -> None:
+        """Initialise empty in-memory stores."""
+        # Global auto-increment counter for entry ids.
+        self._seq: int = 0
+
+        # Mode A — drain queues: key -> [(entry_id, payload), ...]
+        self._queues: dict[str, list[tuple[str, dict]]] = defaultdict(list)
+
+        # Mode C — replay logs: key -> [(entry_id, payload), ...]
+        self._logs: dict[str, list[tuple[str, dict]]] = defaultdict(list)
+
+        # Mode D — pub/sub: channel -> set of asyncio.Queue subscribers
+        self._subscribers: dict[
+            str,
+            set[asyncio.Queue[dict | None]],
+        ] = defaultdict(set)
+
+        # Mode E — locks: key -> asyncio.Lock
+        self._locks: dict[str, asyncio.Lock] = defaultdict(asyncio.Lock)
+        # Track which key is currently held so is_locked() works.
+        self._lock_holders: dict[str, str] = {}
+
+        # Mode F — registry maps: namespace -> {field: value}
+        self._registries: dict[str, dict[str, str]] = defaultdict(dict)
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def __aenter__(self) -> Self:
+        """No-op — nothing to open for in-memory transport.
+
+        Returns:
+            `Self`:
+                The bus, ready for use.
+        """
+        return self
+
+    async def aclose(self) -> None:
+        """Signal all open subscribers so their generators terminate."""
+        for subs in self._subscribers.values():
+            for q in subs:
+                q.put_nowait(None)
+        self._subscribers.clear()
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _next_id(self) -> str:
+        """Return a monotonic ``"<seq>-0"`` id.
+
+        The format matches Redis Stream entry ids so callers that parse
+        ids (e.g. ``_exclusive_start``) keep working.
+
+        Returns:
+            `str`:
+                A unique, monotonically increasing entry id.
+        """
+        self._seq += 1
+        return f"{self._seq}-0"
+
+    # ------------------------------------------------------------------
+    # Mode A — drain queue
+    # ------------------------------------------------------------------
+
+    async def queue_push(
+        self,
+        key: str,
+        payload: dict,
+        *,
+        ttl_secs: int | None = None,
+    ) -> str:
+        """Append ``payload`` to the in-memory drain queue at ``key``.
+
+        ``ttl_secs`` is accepted for API compatibility but ignored — the
+        in-memory implementation does not expire keys.
+
+        Args:
+            key (`str`):
+                Queue identifier.
+            payload (`dict`):
+                JSON-serializable dict to enqueue.
+            ttl_secs (`int | None`, optional):
+                Ignored (no-op).
+
+        Returns:
+            `str`:
+                The synthetic entry id assigned to this entry.
+        """
+        entry_id = self._next_id()
+        self._queues[key].append((entry_id, payload))
+        return entry_id
+
+    async def queue_drain(
+        self,
+        key: str,
+        max_count: int = 100,
+    ) -> list[tuple[str, dict]]:
+        """Drain up to ``max_count`` entries from the queue at ``key``.
+
+        Returned entries are removed from the internal list.
+
+        Args:
+            key (`str`):
+                Queue identifier.
+            max_count (`int`, defaults to ``100``):
+                Maximum entries to return.
+
+        Returns:
+            `list[tuple[str, dict]]`:
+                ``(entry_id, payload)`` pairs in arrival order.
+        """
+        q = self._queues.get(key)
+        if not q:
+            return []
+        drained = q[:max_count]
+        del q[:max_count]
+        return drained
+
+    async def queue_delete(self, key: str) -> None:
+        """Delete the drain queue at ``key``.
+
+        Args:
+            key (`str`):
+                Queue identifier.
+        """
+        self._queues.pop(key, None)
+
+    # ------------------------------------------------------------------
+    # Mode C — replay log
+    # ------------------------------------------------------------------
+
+    async def log_append(
+        self,
+        key: str,
+        payload: dict,
+        *,
+        ttl_secs: int | None = None,
+        max_len: int | None = None,
+    ) -> str:
+        """Append ``payload`` to the replay log at ``key``.
+
+        Args:
+            key (`str`):
+                Log identifier.
+            payload (`dict`):
+                JSON-serializable dict to append.
+            ttl_secs (`int | None`, optional):
+                Ignored (no-op — in-memory does not expire keys).
+            max_len (`int | None`, optional):
+                If set, trim the log to approximately this many entries
+                after appending.
+
+        Returns:
+            `str`:
+                The entry id assigned to the new entry.
+        """
+        entry_id = self._next_id()
+        log = self._logs[key]
+        log.append((entry_id, payload))
+        if max_len is not None and len(log) > max_len:
+            del log[: len(log) - max_len]
+        return entry_id
+
+    async def log_read(
+        self,
+        key: str,
+        since: str | None = None,
+        max_count: int = 100,
+    ) -> list[tuple[str, dict]]:
+        """Read up to ``max_count`` entries newer than ``since``.
+
+        Reads are non-destructive.
+
+        Args:
+            key (`str`):
+                Log identifier.
+            since (`str | None`, optional):
+                Exclusive cursor — return entries whose id is strictly
+                greater than ``since``.  ``None`` reads from the start.
+            max_count (`int`, defaults to ``100``):
+                Maximum entries to return.
+
+        Returns:
+            `list[tuple[str, dict]]`:
+                ``(entry_id, payload)`` pairs in append order.
+        """
+        log = self._logs.get(key)
+        if not log:
+            return []
+        if since is None:
+            return log[:max_count]
+        # Find the first entry with id > since.  Entry ids are
+        # "<seq>-0" strings; integer comparison on the seq prefix is
+        # sufficient because our ids are monotonic.
+        since_seq = int(since.split("-")[0])
+        start = 0
+        for i, (eid, _) in enumerate(log):
+            if int(eid.split("-")[0]) > since_seq:
+                start = i
+                break
+        else:
+            # All entries are <= since.
+            return []
+        return log[start : start + max_count]
+
+    async def log_trim(
+        self,
+        key: str,
+        before_id: str | None = None,
+    ) -> None:
+        """Trim the replay log at ``key``.
+
+        Args:
+            key (`str`):
+                Log identifier.
+            before_id (`str | None`, optional):
+                Drop all entries with id strictly older than this.
+                ``None`` drops the entire log.
+        """
+        if before_id is None:
+            self._logs.pop(key, None)
+            return
+        log = self._logs.get(key)
+        if not log:
+            return
+        before_seq = int(before_id.split("-")[0])
+        self._logs[key] = [
+            (eid, p) for eid, p in log if int(eid.split("-")[0]) >= before_seq
+        ]
+
+    # ------------------------------------------------------------------
+    # Mode D — transient broadcast
+    # ------------------------------------------------------------------
+
+    async def publish(
+        self,
+        key: str,
+        payload: dict,
+    ) -> None:
+        """Publish ``payload`` to all current subscribers of ``key``.
+
+        Args:
+            key (`str`):
+                Channel identifier.
+            payload (`dict`):
+                JSON-serializable dict delivered to each subscriber.
+        """
+        for q in self._subscribers.get(key, set()):
+            q.put_nowait(payload)
+
+    async def subscribe(
+        self,
+        key: str,
+        *,
+        on_ready: Callable[[], None] | None = None,
+    ) -> AsyncGenerator[dict, None]:
+        """Yield broadcast payloads for ``key`` until the consumer
+        closes the generator.
+
+        Args:
+            key (`str`):
+                Channel identifier.
+            on_ready (`Callable[[], None] | None`, optional):
+                Called once after the subscription is established and
+                before any payload is yielded.
+
+        Yields:
+            `dict`:
+                Each payload from :meth:`publish`.
+        """
+        q: asyncio.Queue[dict | None] = asyncio.Queue()
+        self._subscribers[key].add(q)
+        try:
+            if on_ready is not None:
+                on_ready()
+            while True:
+                item = await q.get()
+                if item is None:
+                    # Sentinel from aclose() — shut down gracefully.
+                    break
+                yield item
+        finally:
+            self._subscribers[key].discard(q)
+
+    # ------------------------------------------------------------------
+    # Mode E — distributed lock (process-local asyncio.Lock)
+    # ------------------------------------------------------------------
+
+    @asynccontextmanager
+    async def acquire_lock(
+        self,
+        key: str,
+        *,
+        ttl_secs: int = 600,
+    ) -> AsyncGenerator[None, None]:
+        """Acquire a process-local mutex on ``key``.
+
+        In-memory equivalent of a distributed lock.  ``ttl_secs`` is
+        accepted for API compatibility but does **not** expire the lock
+        automatically — the lock is held until the context exits.
+
+        Args:
+            key (`str`):
+                Lock identifier.
+            ttl_secs (`int`, defaults to ``600``):
+                Ignored (no automatic expiry).
+
+        Yields:
+            `None`: while the lock is held.
+        """
+        lock = self._locks[key]
+        token = uuid.uuid4().hex
+        async with lock:
+            self._lock_holders[key] = token
+            try:
+                yield
+            finally:
+                self._lock_holders.pop(key, None)
+
+    async def is_locked(self, key: str) -> bool:
+        """Return whether ``key`` currently holds a lock.
+
+        Args:
+            key (`str`):
+                Lock identifier.
+
+        Returns:
+            `bool`:
+                ``True`` if some coroutine holds the lock.
+        """
+        return key in self._lock_holders
+
+    # ------------------------------------------------------------------
+    # Mode F — registry map
+    # ------------------------------------------------------------------
+
+    async def registry_set(
+        self,
+        namespace: str,
+        field: str,
+        value: str,
+        *,
+        ttl_secs: int | None = None,
+    ) -> None:
+        """Set ``field`` to ``value`` in the registry at ``namespace``.
+
+        ``ttl_secs`` is accepted for API compatibility but ignored.
+
+        Args:
+            namespace (`str`):
+                Registry key.
+            field (`str`):
+                Field name.
+            value (`str`):
+                Value to store.
+            ttl_secs (`int | None`, optional):
+                Ignored (no TTL support).
+        """
+        self._registries[namespace][field] = value
+
+    async def registry_del(self, namespace: str, field: str) -> None:
+        """Remove ``field`` from the registry at ``namespace``.
+
+        Args:
+            namespace (`str`):
+                Registry key.
+            field (`str`):
+                Field to remove.
+        """
+        reg = self._registries.get(namespace)
+        if reg is not None:
+            reg.pop(field, None)
+
+    async def registry_exists(self, namespace: str, field: str) -> bool:
+        """Return whether ``field`` exists in the registry at
+        ``namespace``.
+
+        Args:
+            namespace (`str`):
+                Registry key.
+            field (`str`):
+                Field to check.
+
+        Returns:
+            `bool`:
+                ``True`` if the field is present.
+        """
+        return field in self._registries.get(namespace, {})
+
+    async def registry_getall(
+        self,
+        namespace: str,
+    ) -> dict[str, str]:
+        """Return all field-value pairs in the registry at
+        ``namespace``.
+
+        Args:
+            namespace (`str`):
+                Registry key.
+
+        Returns:
+            `dict[str, str]`:
+                All entries (shallow copy). Empty dict when absent.
+        """
+        return dict(self._registries.get(namespace, {}))
+
+    async def registry_drop(self, namespace: str) -> None:
+        """Delete the entire registry at ``namespace``.
+
+        Args:
+            namespace (`str`):
+                Registry key to delete.
+        """
+        self._registries.pop(namespace, None)
diff --git a/src/agentscope/app/message_bus/_keys.py b/src/agentscope/app/message_bus/_keys.py
new file mode 100644
index 0000000..d1d336b
--- /dev/null
+++ b/src/agentscope/app/message_bus/_keys.py
@@ -0,0 +1,240 @@
+# -*- coding: utf-8 -*-
+"""Centralised registry of message-bus key/namespace conventions used
+by application-layer services.
+
+:class:`~agentscope.app.message_bus.MessageBus` itself stays
+domain-agnostic — it exposes only generic primitives
+(``publish`` / ``subscribe`` / ``queue_*`` / ``log_*`` / ``registry_*``
+/ ``acquire_lock``). All business-specific key formats live here so
+they can be audited, migrated, and (eventually) ported off from the
+current scattered ``_BASE_…_KEY`` constants on ``MessageBus``.
+
+Add new business keys here as needed. As legacy keys are migrated off
+``MessageBus``, they should move into this class as well.
+"""
+
+from typing import Final
+
+
+class MessageBusKeys:
+    """Application-layer key conventions for the message bus."""
+
+    # ------------------------------------------------------------------
+    # Run-trigger queue — the discriminator carried by each entry on the
+    # shared trigger queue, telling the dispatcher how to spawn the run.
+    # Centralised here (rather than on ``MessageBus``) so the bus stays
+    # free of business vocabulary.
+    # ------------------------------------------------------------------
+
+    WAKEUP_KIND_WAKE: Final = "wake"
+    """Trigger kind: wake an *idle* session to drain pending inbox
+    content. The dispatcher spawns the run with ``input_msg=None`` and
+    skips the session entirely while it is already running."""
+
+    WAKEUP_KIND_RESUME: Final = "resume"
+    """Trigger kind: resume a session parked on an awaiting tool call by
+    feeding it a human-in-the-loop result. The dispatcher spawns the run
+    with the carried ``input`` event and — unlike ``wake`` — must *not*
+    drop the entry while the session is running; it re-queues until the
+    parked run releases its lock."""
+
+    # ------------------------------------------------------------------
+    # Cross-session UI projection — a generic per-session Redis-hash
+    # store onto which one session can project UI cards owned by another
+    # (e.g. a team member's pending HITL request projected onto its
+    # leader). The ``kind`` prefix on each field lets a single target
+    # session carry several independent projection feeds without key
+    # collisions, so new projection features reuse this store rather
+    # than minting their own.
+    # ------------------------------------------------------------------
+
+    _PROJECTION_NS = "agentscope:session:projection:{sid}"
+    """Redis-hash namespace key template (per *target* session id)."""
+
+    @classmethod
+    def projection_namespace(cls, target_session_id: str) -> str:
+        """Return the registry namespace for a session's projections.
+
+        Args:
+            target_session_id (`str`):
+                The session the entries are projected onto (the session
+                whose UI renders them).
+
+        Returns:
+            `str`:
+                The Redis-hash namespace key.
+        """
+        return cls._PROJECTION_NS.format(sid=target_session_id)
+
+    @staticmethod
+    def projection_field(kind: str, entry_id: str) -> str:
+        """Return the hash field key for a single projected entry.
+
+        The ``kind`` prefix namespaces the field so different projection
+        feeds sharing one target session never collide, and so a feed
+        can be listed/purged by scanning for its prefix.
+
+        Args:
+            kind (`str`):
+                The projection feed this entry belongs to (e.g.
+                ``"subagent_hitl"``).
+            entry_id (`str`):
+                The entry's identity within the feed, unique per
+                ``kind`` (e.g. ``"{worker_session_id}:{reply_id}"``).
+
+        Returns:
+            `str`:
+                The hash field key, ``"{kind}:{entry_id}"``.
+        """
+        return f"{kind}:{entry_id}"
+
+    @staticmethod
+    def projection_field_prefix(kind: str) -> str:
+        """Return the field-key prefix that identifies one feed.
+
+        Used to filter :meth:`MessageBus.registry_getall` down to a
+        single ``kind`` when listing or purging.
+
+        Args:
+            kind (`str`):
+                The projection feed.
+
+        Returns:
+            `str`:
+                The field-key prefix, ``"{kind}:"``.
+        """
+        return f"{kind}:"
+
+    # ------------------------------------------------------------------
+    # Session event stream (replay log + live pub/sub)
+    # ------------------------------------------------------------------
+
+    _SESSION_EVENTS = "agentscope:session:events:{sid}"
+
+    SESSION_REPLAY_MAX_LEN = 1000
+    """Replay log length cap; older events are trimmed on append."""
+
+    @classmethod
+    def session_events(cls, session_id: str) -> str:
+        """Replay log + live pub/sub channel key for a session."""
+        return cls._SESSION_EVENTS.format(sid=session_id)
+
+    # ------------------------------------------------------------------
+    # Session run lock
+    # ------------------------------------------------------------------
+
+    _SESSION_LOCK = "agentscope:session:lock:{sid}"
+
+    SESSION_RUN_TTL_SECS = 600
+    """Default lock lease for a chat run (10 minutes)."""
+
+    @classmethod
+    def session_lock(cls, session_id: str) -> str:
+        """Per-session distributed-lock key."""
+        return cls._SESSION_LOCK.format(sid=session_id)
+
+    # ------------------------------------------------------------------
+    # Session inbox
+    # ------------------------------------------------------------------
+
+    _INBOX = "agentscope:inbox:{sid}"
+
+    @classmethod
+    def inbox(cls, session_id: str) -> str:
+        """Per-session inbox drain-queue key."""
+        return cls._INBOX.format(sid=session_id)
+
+    # ------------------------------------------------------------------
+    # Run trigger queue (wakeup / resume)
+    # ------------------------------------------------------------------
+
+    _WAKEUP_QUEUE = "agentscope:wakeups"
+    _WAKEUP_SIGNAL = "agentscope:wakeup_signal"
+
+    @classmethod
+    def wakeup_queue(cls) -> str:
+        """Shared run-trigger queue key."""
+        return cls._WAKEUP_QUEUE
+
+    @classmethod
+    def wakeup_signal(cls) -> str:
+        """Shared signal channel that nudges dispatchers to drain."""
+        return cls._WAKEUP_SIGNAL
+
+    # ------------------------------------------------------------------
+    # Cross-process cancel
+    # ------------------------------------------------------------------
+
+    _SESSION_CANCEL = "agentscope:session:cancel"
+    _TASK_CANCEL = "agentscope:task:cancel"
+    _SESSION_INTERRUPT = "agentscope:session:interrupt"
+
+    @classmethod
+    def session_cancel_channel(cls) -> str:
+        """Global session-cancel broadcast channel."""
+        return cls._SESSION_CANCEL
+
+    @classmethod
+    def task_cancel_channel(cls) -> str:
+        """Single-task cancel broadcast channel."""
+        return cls._TASK_CANCEL
+
+    @classmethod
+    def session_interrupt_channel(cls) -> str:
+        """Global session-interrupt broadcast channel.
+
+        Used by the interrupt API endpoint to request graceful
+        interruption of a running agent.  Separate from
+        ``session_cancel_channel`` (which is used for hard-cancel on
+        session deletion).
+        """
+        return cls._SESSION_INTERRUPT
+
+    # ------------------------------------------------------------------
+    # Background task registry
+    # ------------------------------------------------------------------
+
+    _BG_TASKS = "agentscope:bg_tasks:{sid}"
+
+    BG_TASKS_TTL_SECS = 86400
+    """Fallback TTL for the per-session BG task registry (24 h)."""
+
+    @classmethod
+    def bg_tasks(cls, session_id: str) -> str:
+        """Per-session background task registry key."""
+        return cls._BG_TASKS.format(sid=session_id)
+
+    # ------------------------------------------------------------------
+    # Knowledge-base indexing pipeline
+    # ------------------------------------------------------------------
+
+    _INDEX_TASKS_QUEUE = "agentscope:index:tasks"
+    _INDEX_TASKS_SIGNAL = "agentscope:index:tasks:wake"
+
+    @classmethod
+    def index_tasks_queue(cls) -> str:
+        """Shared, durable index-task queue.
+
+        The producer-side
+        :class:`~agentscope.app._service.KnowledgeBaseService`
+        ``queue_push``\\ es here through
+        :func:`~agentscope.app._bus_ops.enqueue_index_task`; the
+        consumer-side
+        :class:`~agentscope.app._service.IndexTaskConsumer`
+        ``queue_drain``\\ s it on each signal — plus once eagerly on
+        consumer start-up so tasks queued while every worker was down
+        are picked up immediately.
+        """
+        return cls._INDEX_TASKS_QUEUE
+
+    @classmethod
+    def index_tasks_signal(cls) -> str:
+        """Shared pub/sub channel that nudges every running index-task
+        consumer to drain the queue.
+
+        Payload is opaque — only its arrival matters. Redis pub/sub is
+        fire-and-forget, so a published signal does not guarantee
+        delivery; the durable queue keeps work safe in case every
+        subscriber happens to be offline.
+        """
+        return cls._INDEX_TASKS_SIGNAL
diff --git a/src/agentscope/app/message_bus/_redis_message_bus.py b/src/agentscope/app/message_bus/_redis_message_bus.py
new file mode 100644
index 0000000..5734114
--- /dev/null
+++ b/src/agentscope/app/message_bus/_redis_message_bus.py
@@ -0,0 +1,641 @@
+# -*- coding: utf-8 -*-
+"""The Redis-backed message bus implementation."""
+import asyncio
+import json
+import uuid
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from typing import Any, Callable, Self, TYPE_CHECKING
+
+from ._base import MessageBus
+
+if TYPE_CHECKING:
+    from redis.asyncio import ConnectionPool, Redis
+else:
+    ConnectionPool = Any
+    Redis = Any
+
+
+class RedisMessageBus(MessageBus):
+    """Redis-backed implementation of :class:`MessageBus`.
+
+    Mapping of bus modes to Redis primitives:
+
+    - **Mode A (drain queue)** uses a Redis Stream per key. ``XADD``
+      appends a payload whose single field ``payload`` carries the
+      JSON-serialised dict. ``queue_drain`` performs ``XRANGE`` followed
+      by per-id ``XDEL`` so the read is destructive and idempotent
+      under the single-consumer-per-key invariant. ``ttl_secs`` is
+      enforced via ``EXPIRE`` after each push (sliding TTL).
+    - **Mode C (replay log)** also uses a Redis Stream, but never
+      ``XDEL``s on read. Trimming happens via ``XADD … MAXLEN ~N``
+      (approximate, for performance) on append, via the ``ttl_secs``
+      ``EXPIRE`` on the whole key, or explicitly via
+      :meth:`log_trim`. ``log_read`` uses ``XRANGE`` with an exclusive
+      start id derived from ``since``.
+    - **Mode D (transient broadcast)** rides Redis Pub/Sub. Wake-ups
+      are best-effort: payloads published before a subscription exists
+      are not delivered.
+
+    The bus owns its own connection pool by default; an external pool
+    may be supplied for tests or for sharing a pool across services.
+    """
+
+    def __init__(
+        self,
+        host: str = "localhost",
+        port: int = 6379,
+        db: int = 0,
+        password: str | None = None,
+        connection_pool: ConnectionPool | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Store connection parameters; the actual pool is created in
+        :meth:`__aenter__`.
+
+        Args:
+            host (`str`, defaults to ``"localhost"``):
+                Redis server host.
+            port (`int`, defaults to ``6379``):
+                Redis server port.
+            db (`int`, defaults to ``0``):
+                Redis logical database index.
+            password (`str | None`, optional):
+                Redis password if required by the server.
+            connection_pool (`ConnectionPool | None`, optional):
+                An externally managed connection pool. When provided
+                the pool is used as-is and **not** closed by
+                :meth:`aclose` — the caller retains ownership of its
+                lifecycle. When omitted a pool is created from
+                *host*/*port*/*db*/*password* on :meth:`__aenter__`
+                and closed on :meth:`aclose`.
+            **kwargs (`Any`):
+                Extra keyword arguments forwarded to
+                ``redis.asyncio.ConnectionPool`` when the pool is
+                created internally (e.g. ``max_connections=20``,
+                ``socket_timeout=5``).
+        """
+        self._host = host
+        self._port = port
+        self._db = db
+        self._password = password
+        self._external_pool: ConnectionPool | None = connection_pool
+        self._kwargs = kwargs
+
+        # Populated in __aenter__; None until the context is entered.
+        self._client: Redis | None = None
+        self._owned_pool: ConnectionPool | None = None
+
+    async def __aenter__(self) -> Self:
+        """Create the connection pool and Redis client.
+
+        If an external pool was supplied at construction time it is
+        used directly and its lifecycle remains the caller's
+        responsibility. Otherwise, an internal pool is created from the
+        stored host/port/db parameters and will be closed by
+        :meth:`aclose`.
+
+        Returns:
+            `Self`:
+                The bus, ready for use as an async context manager.
+        """
+        try:
+            import redis.asyncio as aioredis
+        except ImportError as e:
+            raise ImportError(
+                "The 'redis' package is required for RedisMessageBus. "
+                "Install it with: pip install redis[async]",
+            ) from e
+
+        if self._external_pool is not None:
+            pool = self._external_pool
+        else:
+            self._owned_pool = aioredis.ConnectionPool(
+                host=self._host,
+                port=self._port,
+                db=self._db,
+                password=self._password,
+                decode_responses=True,
+                **self._kwargs,
+            )
+            pool = self._owned_pool
+
+        self._client = aioredis.Redis(connection_pool=pool)
+        return self
+
+    async def aclose(self) -> None:
+        """Close the connection pool if it was created internally.
+
+        Externally supplied pools are left open — the caller owns them.
+        """
+        if self._owned_pool is not None:
+            await self._owned_pool.aclose()
+            self._owned_pool = None
+        self._client = None
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: Any,
+    ) -> None:
+        """Exit the async context manager and release resources.
+
+        Args:
+            exc_type (`type[BaseException] | None`):
+                Exception class raised inside the context, if any.
+            exc_value (`BaseException | None`):
+                Exception instance raised inside the context, if any.
+            traceback (`Any`):
+                Traceback associated with the exception, if any.
+        """
+        await self.aclose()
+
+    def get_client(self) -> Redis:
+        """Return the underlying Redis client.
+
+        Only valid inside the async context (between :meth:`__aenter__`
+        and :meth:`aclose`).
+
+        Returns:
+            `Redis`:
+                The asyncio Redis client instance.
+        """
+        return self._client
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _exclusive_start(since: str | None) -> str:
+        """Compute the exclusive start id for ``XRANGE`` given a cursor.
+
+        Redis Streams 6.2+ support the ``(`` prefix for exclusive
+        ranges, so the simplest portable encoding of "after ``since``"
+        is ``f"({since}"``. ``None`` resolves to ``"-"`` (the absolute
+        minimum id).
+
+        Args:
+            since (`str | None`):
+                The previous cursor returned by :meth:`log_read`, or
+                ``None`` to read from the beginning.
+
+        Returns:
+            `str`:
+                The start argument for ``XRANGE``.
+        """
+        if since is None:
+            return "-"
+        return f"({since}"
+
+    # ------------------------------------------------------------------
+    # Mode A — drain queue
+    # ------------------------------------------------------------------
+
+    async def queue_push(
+        self,
+        key: str,
+        payload: dict,
+        *,
+        ttl_secs: int | None = None,
+    ) -> str:
+        """Append ``payload`` to the drain queue at ``key``.
+
+        Args:
+            key (`str`):
+                Stream key for this drain queue.
+            payload (`dict`):
+                JSON-serializable dict; encoded into the ``payload``
+                field of a Redis Stream entry.
+            ttl_secs (`int | None`, optional):
+                If set, refresh the key's expiry on every push
+                (sliding TTL). ``None`` means no TTL — the queue
+                persists until drained or deleted explicitly.
+
+        Returns:
+            `str`:
+                The Redis Stream entry id assigned by ``XADD``.
+        """
+        entry_id = await self._client.xadd(
+            key,
+            {"payload": json.dumps(payload, ensure_ascii=False)},
+        )
+        if ttl_secs is not None:
+            await self._client.expire(key, ttl_secs)
+        return entry_id
+
+    async def queue_drain(
+        self,
+        key: str,
+        max_count: int = 100,
+    ) -> list[tuple[str, dict]]:
+        """Drain up to ``max_count`` entries from the queue at ``key``.
+
+        Implementation: ``XRANGE`` followed by ``XDEL`` of the
+        returned ids, so the operation is destructive in a single
+        round-trip pair. Entries that arrive between ``XRANGE`` and
+        ``XDEL`` are not affected.
+
+        Args:
+            key (`str`):
+                Stream key for the drain queue.
+            max_count (`int`, defaults to ``100``):
+                Maximum entries to return in one call.
+
+        Returns:
+            `list[tuple[str, dict]]`:
+                ``(entry_id, payload)`` pairs in arrival order. Empty
+                list when the queue is empty or absent.
+        """
+        entries = await self._client.xrange(key, count=max_count)
+        if not entries:
+            return []
+
+        results: list[tuple[str, dict]] = []
+        ids_to_delete: list[str] = []
+        for entry_id, fields in entries:
+            ids_to_delete.append(entry_id)
+            raw = fields.get("payload")
+            if raw is None:
+                continue
+            results.append((entry_id, json.loads(raw)))
+
+        if ids_to_delete:
+            await self._client.xdel(key, *ids_to_delete)
+
+        return results
+
+    async def queue_delete(self, key: str) -> None:
+        """Delete the drain queue at ``key``.
+
+        Args:
+            key (`str`):
+                Stream key for the drain queue. ``DEL`` is a no-op
+                when the key does not exist.
+        """
+        await self._client.delete(key)
+
+    # ------------------------------------------------------------------
+    # Mode C — replay log
+    # ------------------------------------------------------------------
+
+    async def log_append(
+        self,
+        key: str,
+        payload: dict,
+        *,
+        ttl_secs: int | None = None,
+        max_len: int | None = None,
+    ) -> str:
+        """Append ``payload`` to the replay log at ``key``.
+
+        Args:
+            key (`str`):
+                Stream key for this replay log.
+            payload (`dict`):
+                JSON-serializable dict; encoded into the ``payload``
+                field of a Redis Stream entry.
+            ttl_secs (`int | None`, optional):
+                If set, refresh the key's expiry on every append
+                (sliding TTL). ``None`` means no TTL.
+            max_len (`int | None`, optional):
+                If set, cap the log at approximately this many entries
+                using ``XADD MAXLEN ~N``. The cap is approximate so
+                Redis can use its O(1) trim-by-radix-tree-node mode.
+                ``None`` means no cap.
+
+        Returns:
+            `str`:
+                The Redis Stream entry id, suitable as a cursor for
+                later :meth:`log_read` calls.
+        """
+        kwargs: dict[str, Any] = {}
+        if max_len is not None:
+            kwargs["maxlen"] = max_len
+            kwargs["approximate"] = True
+        entry_id = await self._client.xadd(
+            key,
+            {"payload": json.dumps(payload, ensure_ascii=False)},
+            **kwargs,
+        )
+        if ttl_secs is not None:
+            await self._client.expire(key, ttl_secs)
+        return entry_id
+
+    async def log_read(
+        self,
+        key: str,
+        since: str | None = None,
+        max_count: int = 100,
+    ) -> list[tuple[str, dict]]:
+        """Read up to ``max_count`` entries newer than ``since``.
+
+        Args:
+            key (`str`):
+                Stream key for the replay log.
+            since (`str | None`, optional):
+                Exclusive cursor — return entries strictly newer than
+                this id (typically the last id from a previous read).
+                ``None`` reads from the beginning.
+            max_count (`int`, defaults to ``100``):
+                Maximum entries to return.
+
+        Returns:
+            `list[tuple[str, dict]]`:
+                ``(entry_id, payload)`` pairs in append order.
+        """
+        start = self._exclusive_start(since)
+        entries = await self._client.xrange(
+            key,
+            min=start,
+            count=max_count,
+        )
+        results: list[tuple[str, dict]] = []
+        for entry_id, fields in entries:
+            raw = fields.get("payload")
+            if raw is None:
+                continue
+            results.append((entry_id, json.loads(raw)))
+        return results
+
+    async def log_trim(
+        self,
+        key: str,
+        before_id: str | None = None,
+    ) -> None:
+        """Trim the replay log at ``key``.
+
+        Args:
+            key (`str`):
+                Stream key for the replay log.
+            before_id (`str | None`, optional):
+                Drop all entries with id strictly older than this.
+                ``None`` deletes the entire key.
+        """
+        if before_id is None:
+            await self._client.delete(key)
+            return
+        # XTRIM MINID drops entries with id < before_id.
+        await self._client.xtrim(key, minid=before_id)
+
+    # ------------------------------------------------------------------
+    # Mode F — registry map (hash-keyed namespace)
+    # ------------------------------------------------------------------
+
+    async def registry_set(
+        self,
+        namespace: str,
+        field: str,
+        value: str,
+        *,
+        ttl_secs: int | None = None,
+    ) -> None:
+        """Set ``field`` in the Redis Hash at ``namespace``.
+
+        Args:
+            namespace (`str`):
+                Hash key.
+            field (`str`):
+                Hash field.
+            value (`str`):
+                Value to store.
+            ttl_secs (`int | None`, optional):
+                Refresh the key's expiry (sliding TTL).
+        """
+        await self._client.hset(namespace, field, value)
+        if ttl_secs is not None:
+            await self._client.expire(namespace, ttl_secs)
+
+    async def registry_del(self, namespace: str, field: str) -> None:
+        """Remove ``field`` from the Redis Hash at ``namespace``.
+
+        Args:
+            namespace (`str`):
+                Hash key.
+            field (`str`):
+                Hash field to remove.
+        """
+        await self._client.hdel(namespace, field)
+
+    async def registry_exists(self, namespace: str, field: str) -> bool:
+        """Return whether ``field`` exists in the Hash at ``namespace``.
+
+        Args:
+            namespace (`str`):
+                Hash key.
+            field (`str`):
+                Hash field to check.
+
+        Returns:
+            `bool`:
+                ``True`` if the field exists.
+        """
+        return bool(await self._client.hexists(namespace, field))
+
+    async def registry_getall(
+        self,
+        namespace: str,
+    ) -> dict[str, str]:
+        """Return all field-value pairs from the Hash at ``namespace``.
+
+        Args:
+            namespace (`str`):
+                Hash key.
+
+        Returns:
+            `dict[str, str]`:
+                All entries. Empty dict when the key is absent.
+        """
+        return await self._client.hgetall(namespace) or {}
+
+    async def registry_drop(self, namespace: str) -> None:
+        """Delete the entire Hash at ``namespace``.
+
+        Args:
+            namespace (`str`):
+                Hash key to delete.
+        """
+        await self._client.delete(namespace)
+
+    # ------------------------------------------------------------------
+    # Mode D — transient broadcast
+    # ------------------------------------------------------------------
+
+    # Poll interval for the pub/sub read loop. Bounding each read keeps
+    # long-lived idle subscriptions resilient: an idle ``socket_timeout``
+    # read (raised when the connection defines one, or when the server
+    # drops idle connections) surfaces as a benign per-poll timeout that
+    # we ignore, instead of a fatal error that tears down the generator.
+    _SUBSCRIBE_POLL_TIMEOUT_SECS = 1.0
+
+    async def publish(
+        self,
+        key: str,
+        payload: dict,
+    ) -> None:
+        """Publish ``payload`` on the broadcast channel ``key``.
+
+        Args:
+            key (`str`):
+                Pub/Sub channel name.
+            payload (`dict`):
+                JSON-serializable dict; encoded as the channel
+                message body.
+        """
+        await self._client.publish(
+            key,
+            json.dumps(payload, ensure_ascii=False),
+        )
+
+    async def subscribe(
+        self,
+        key: str,
+        *,
+        on_ready: Callable[[], None] | None = None,
+    ) -> AsyncGenerator[dict, None]:
+        """Yield broadcast payloads on ``key`` until the consumer
+        closes the generator.
+
+        Args:
+            key (`str`):
+                Pub/Sub channel name.
+            on_ready (`Callable[[], None] | None`, optional):
+                Called once after ``SUBSCRIBE`` has been issued (and
+                before any payload is yielded). Lets callers block on
+                a "subscription is live" event so they can publish
+                immediately after starting a subscriber without losing
+                the first message to a SUBSCRIBE/PUBLISH race.
+
+        Yields:
+            `dict`:
+                Each payload originally passed to :meth:`publish`.
+        """
+        from redis import exceptions as redis_exceptions
+
+        pubsub = self._client.pubsub()
+        try:
+            await pubsub.subscribe(key)
+            if on_ready is not None:
+                on_ready()
+            while True:
+                try:
+                    message = await pubsub.get_message(
+                        ignore_subscribe_messages=True,
+                        timeout=self._SUBSCRIBE_POLL_TIMEOUT_SECS,
+                    )
+                except redis_exceptions.TimeoutError:
+                    # Idle read timeout (e.g. the connection defines a
+                    # ``socket_timeout`` or the server drops idle
+                    # connections). No message arrived in this window;
+                    # keep listening rather than crashing the loop.
+                    continue
+                if message is None:
+                    # No payload within the poll window — keep waiting.
+                    continue
+                if message.get("type") != "message":
+                    # Skip ``subscribe`` ack and similar control frames.
+                    continue
+                data = message.get("data")
+                if data is None:
+                    continue
+                yield json.loads(data)
+        finally:
+            await pubsub.unsubscribe(key)
+            await pubsub.aclose()
+
+    # ------------------------------------------------------------------
+    # Mode E — distributed lock
+    # ------------------------------------------------------------------
+
+    # Poll interval while waiting for a contested lock.
+    _LOCK_RETRY_DELAY_SECS = 0.1
+
+    @asynccontextmanager
+    async def acquire_lock(
+        self,
+        key: str,
+        *,
+        ttl_secs: int = 600,
+    ) -> AsyncGenerator[None, None]:
+        """Acquire ``key`` as a distributed mutex.
+
+        Implementation:
+
+        - ``SET key <random-token> NX EX ttl_secs`` to claim the
+          lock atomically. Retries every
+          ``_LOCK_RETRY_DELAY_SECS`` until acquired.
+        - A heartbeat task renews the TTL every ``ttl_secs / 2``
+          seconds while the body runs, so a long-running holder
+          does not lose the lease.
+        - On exit, the heartbeat is cancelled and the lock is
+          released by GET-then-DEL guarded on the random token —
+          we never delete a key whose value isn't ours, so a
+          process whose lease has already expired (and been re-
+          acquired by someone else) cannot accidentally release
+          the new holder's lock. The non-atomic GET+DEL race
+          window opens only after the heartbeat is cancelled, in
+          a sub-millisecond span; the ``ttl_secs`` lease still has
+          plenty of time left so the race effectively never
+          materialises.
+
+        Args:
+            key (`str`):
+                Lock identifier.
+            ttl_secs (`int`, defaults to ``600``):
+                Lease duration; auto-renewed via heartbeat.
+
+        Yields:
+            `None`: while the lock is held.
+        """
+        token = uuid.uuid4().hex
+        # Acquire (poll until success).
+        while True:
+            ok = await self._client.set(key, token, nx=True, ex=ttl_secs)
+            if ok:
+                break
+            await asyncio.sleep(self._LOCK_RETRY_DELAY_SECS)
+
+        # Heartbeat: renew TTL every ttl/2 seconds.
+        async def _heartbeat() -> None:
+            while True:
+                await asyncio.sleep(max(1.0, ttl_secs / 2))
+                await self._client.expire(key, ttl_secs)
+
+        hb_task = asyncio.create_task(
+            _heartbeat(),
+            name=f"lock-heartbeat:{key}",
+        )
+
+        try:
+            yield
+        finally:
+            hb_task.cancel()
+            try:
+                await hb_task
+            except asyncio.CancelledError:
+                pass
+            # Release: only delete if the value still matches our
+            # token. Failures are swallowed (the lease may have
+            # expired naturally, in which case there is nothing to
+            # do).
+            try:
+                current = await self._client.get(key)
+                if current == token:
+                    await self._client.delete(key)
+            except Exception:  # pylint: disable=broad-except
+                pass
+
+    async def is_locked(self, key: str) -> bool:
+        """Return whether ``key`` currently holds a lock.
+
+        Args:
+            key (`str`):
+                Lock identifier.
+
+        Returns:
+            `bool`:
+                ``True`` if Redis has a value at this key.
+        """
+        result = await self._client.exists(key)
+        return bool(result)
diff --git a/src/agentscope/app/middleware/__init__.py b/src/agentscope/app/middleware/__init__.py
new file mode 100644
index 0000000..640d8a8
--- /dev/null
+++ b/src/agentscope/app/middleware/__init__.py
@@ -0,0 +1,16 @@
+# -*- coding: utf-8 -*-
+"""The middlewares module."""
+
+from ._inbox_middleware import InboxMiddleware
+from ._protocol import ProtocolMiddlewareBase, AGUIProtocolMiddleware
+from ._state_change_middleware import StateChangeMiddleware
+from ._tool_offload_middleware import ToolOffloadMiddleware
+
+
+__all__ = [
+    "InboxMiddleware",
+    "ProtocolMiddlewareBase",
+    "AGUIProtocolMiddleware",
+    "StateChangeMiddleware",
+    "ToolOffloadMiddleware",
+]
diff --git a/src/agentscope/app/middleware/_inbox_middleware.py b/src/agentscope/app/middleware/_inbox_middleware.py
new file mode 100644
index 0000000..a494cb0
--- /dev/null
+++ b/src/agentscope/app/middleware/_inbox_middleware.py
@@ -0,0 +1,136 @@
+# -*- coding: utf-8 -*-
+"""Generic middleware that drains the message bus inbox before reasoning.
+
+Producers push :class:`~agentscope.message.HintBlock` payloads into
+the per-session inbox via :class:`~agentscope.app._message_bus.MessageBus`.
+This middleware drains the inbox at the start of each reasoning step
+and injects the HintBlocks into ``agent.state.context`` — appended to
+the last assistant message's content list (same pattern as
+:class:`ToolOffloadMiddleware`).
+
+Each injected HintBlock also yields a one-shot ``HintBlockEvent``
+so the front-end SSE stream can render it in real time.
+"""
+from typing import Any, AsyncGenerator, Callable
+
+from ..message_bus import MessageBus, MessageBusKeys
+from ..._logging import logger
+from ...agent import Agent
+from ...event import HintBlockEvent
+from ...message import AssistantMsg, HintBlock
+from ...middleware import MiddlewareBase
+
+
+class InboxMiddleware(MiddlewareBase):  # pylint: disable=abstract-method
+    """Drain the session's inbox and inject HintBlocks before each
+    reasoning step.
+
+    Each entry in the inbox is a serialised
+    :class:`~agentscope.message.HintBlock`. The middleware
+    deserializes them, appends to the last assistant message in
+    ``agent.state.context``, and yields a one-shot ``HintBlockEvent``
+    for each so the front-end sees them.
+
+    Args:
+        message_bus (`MessageBus`):
+            The application message bus to read from.
+        max_count (`int`, defaults to ``100``):
+            Maximum number of entries drained per reasoning step.
+    """
+
+    def __init__(
+        self,
+        message_bus: MessageBus,
+        max_count: int = 100,
+    ) -> None:
+        """Initialise the middleware.
+
+        Args:
+            message_bus (`MessageBus`):
+                The application-level message bus.
+            max_count (`int`, defaults to ``100``):
+                Maximum entries drained per reasoning step.
+        """
+        self._bus = message_bus
+        self._max_count = max_count
+
+    async def on_reasoning(  # type: ignore[override]
+        self,
+        agent: Agent,
+        input_kwargs: dict,
+        next_handler: Callable[..., AsyncGenerator],
+    ) -> AsyncGenerator[Any, None]:
+        """Drain the inbox, inject HintBlocks into context, yield
+        events, then continue with downstream reasoning.
+
+        Args:
+            agent (`Agent`):
+                The executing agent. ``agent.state.session_id`` selects
+                the inbox to drain.
+            input_kwargs (`dict`):
+                Reasoning input kwargs (contains ``tool_choice``);
+                forwarded unchanged to ``next_handler``.
+            next_handler (`Callable[..., AsyncGenerator]`):
+                The downstream middleware or core reasoning logic.
+
+        Yields:
+            `Any`:
+                One ``HintBlockEvent`` per drained inbox entry,
+                followed by events from downstream.
+        """
+        entries = await self._bus.queue_drain(
+            MessageBusKeys.inbox(agent.state.session_id),
+            max_count=self._max_count,
+        )
+
+        if entries:
+            hint_blocks = [
+                HintBlock.model_validate(payload)
+                for _entry_id, payload in entries
+            ]
+
+            logger.info(
+                "InboxMiddleware: injecting %d HintBlock(s) into context "
+                "for session %s",
+                len(hint_blocks),
+                agent.state.session_id,
+            )
+
+            # Inject into agent context (same pattern as
+            # ToolOffloadMiddleware).
+            if len(agent.state.context) > 0:
+                last_msg = agent.state.context[-1]
+                if (
+                    last_msg.role == "assistant"
+                    and last_msg.name == agent.name
+                ):
+                    last_msg.content.extend(hint_blocks)
+                else:
+                    agent.state.context.append(
+                        AssistantMsg(
+                            id=agent.state.reply_id,
+                            name=agent.name,
+                            content=list(hint_blocks),
+                        ),
+                    )
+            else:
+                agent.state.context.append(
+                    AssistantMsg(
+                        id=agent.state.reply_id,
+                        name=agent.name,
+                        content=list(hint_blocks),
+                    ),
+                )
+
+            # Yield one-shot events so the front-end SSE stream sees
+            # each HintBlock.
+            for hint in hint_blocks:
+                yield HintBlockEvent(
+                    reply_id=agent.state.reply_id,
+                    block_id=hint.id,
+                    source=hint.source,
+                    hint=hint.hint,
+                )
+
+        async for evt in next_handler(**input_kwargs):
+            yield evt
diff --git a/src/agentscope/app/middleware/_protocol/__init__.py b/src/agentscope/app/middleware/_protocol/__init__.py
new file mode 100644
index 0000000..0a2fda5
--- /dev/null
+++ b/src/agentscope/app/middleware/_protocol/__init__.py
@@ -0,0 +1,10 @@
+# -*- coding: utf-8 -*-
+"""The middleware used for agent protocol."""
+
+from ._base import ProtocolMiddlewareBase
+from ._agui import AGUIProtocolMiddleware
+
+__all__ = [
+    "ProtocolMiddlewareBase",
+    "AGUIProtocolMiddleware",
+]
diff --git a/src/agentscope/app/middleware/_protocol/_agui.py b/src/agentscope/app/middleware/_protocol/_agui.py
new file mode 100644
index 0000000..48730ca
--- /dev/null
+++ b/src/agentscope/app/middleware/_protocol/_agui.py
@@ -0,0 +1,257 @@
+# -*- coding: utf-8 -*-
+"""The AGUI middleware class."""
+from typing import TYPE_CHECKING, Any
+
+from starlette.types import ASGIApp
+
+from ._base import ProtocolMiddlewareBase
+from ....event import (
+    AgentEvent,
+    DataBlockDeltaEvent,
+    DataBlockEndEvent,
+    DataBlockStartEvent,
+    ExceedMaxItersEvent,
+    ExternalExecutionResultEvent,
+    ModelCallEndEvent,
+    ModelCallStartEvent,
+    ReplyEndEvent,
+    ReplyStartEvent,
+    RequireExternalExecutionEvent,
+    RequireUserConfirmEvent,
+    TextBlockDeltaEvent,
+    TextBlockEndEvent,
+    TextBlockStartEvent,
+    ThinkingBlockDeltaEvent,
+    ThinkingBlockEndEvent,
+    ThinkingBlockStartEvent,
+    ToolCallDeltaEvent,
+    ToolCallEndEvent,
+    ToolCallStartEvent,
+    ToolResultDataDeltaEvent,
+    ToolResultEndEvent,
+    ToolResultStartEvent,
+    ToolResultTextDeltaEvent,
+    UserConfirmResultEvent,
+)
+
+if TYPE_CHECKING:
+    from ag_ui.core.events import BaseEvent as AGUIBaseEvent
+else:
+    AGUIBaseEvent = Any
+
+
+class AGUIProtocolMiddleware(ProtocolMiddlewareBase):
+    """The middleware that converts the AgentScope events into AGUI
+    protocol."""
+
+    def __init__(self, app: ASGIApp) -> None:
+        """Initialize the AGUI protocol middleware.
+
+        Args:
+            app: The ASGI application to wrap.
+        """
+        super().__init__(app)
+        # Per-instance state; safe under typical single-stream usage
+        # but not across concurrent requests.  Use contextvars if
+        # concurrency is needed.
+        self._last_model_name: str = "model_call"
+        self._tool_result_buffers: dict[str, list[str]] = {}
+
+    def _convert_to_protocol(self, event: AgentEvent) -> dict:
+        """Convert the AgentScope events into AGUI protocol."""
+        agui_event = self._to_agui_event(event)
+        return agui_event.model_dump(
+            mode="json",
+            exclude_none=True,
+            by_alias=True,
+        )
+
+    # pylint: disable=too-many-return-statements
+    def _to_agui_event(  # noqa: C901
+        self,
+        event: AgentEvent,
+    ) -> "AGUIBaseEvent":
+        """Convert an AgentScope event to an AGUI event."""
+
+        from ag_ui.core.events import (
+            CustomEvent as AGUICustomEvent,
+            ReasoningMessageContentEvent as AGUIReasoningMessageContentEvent,
+            ReasoningMessageEndEvent as AGUIReasoningMessageEndEvent,
+            ReasoningMessageStartEvent as AGUIReasoningMessageStartEvent,
+            RunErrorEvent as AGUIRunErrorEvent,
+            RunFinishedEvent as AGUIRunFinishedEvent,
+            RunStartedEvent as AGUIRunStartedEvent,
+            StepFinishedEvent as AGUIStepFinishedEvent,
+            StepStartedEvent as AGUIStepStartedEvent,
+            TextMessageContentEvent as AGUITextMessageContentEvent,
+            TextMessageEndEvent as AGUITextMessageEndEvent,
+            TextMessageStartEvent as AGUITextMessageStartEvent,
+            ToolCallArgsEvent as AGUIToolCallArgsEvent,
+            ToolCallEndEvent as AGUIToolCallEndEvent,
+            ToolCallResultEvent as AGUIToolCallResultEvent,
+            ToolCallStartEvent as AGUIToolCallStartEvent,
+        )
+
+        if isinstance(event, ReplyStartEvent):
+            return AGUIRunStartedEvent(
+                thread_id=event.session_id,
+                run_id=event.reply_id,
+            )
+
+        if isinstance(event, ReplyEndEvent):
+            return AGUIRunFinishedEvent(
+                thread_id=event.session_id,
+                run_id=event.reply_id,
+            )
+
+        if isinstance(event, ExceedMaxItersEvent):
+            return AGUIRunErrorEvent(
+                message=(f"Agent '{event.name}' exceeded max iterations"),
+                code="exceed_max_iters",
+            )
+
+        if isinstance(event, ModelCallStartEvent):
+            self._last_model_name = event.model_name
+            return AGUIStepStartedEvent(
+                step_name=event.model_name,
+            )
+
+        if isinstance(event, ModelCallEndEvent):
+            return AGUIStepFinishedEvent(
+                step_name=self._last_model_name,
+            )
+
+        if isinstance(event, TextBlockStartEvent):
+            return AGUITextMessageStartEvent(
+                message_id=event.block_id,
+            )
+
+        if isinstance(event, TextBlockDeltaEvent):
+            return AGUITextMessageContentEvent(
+                message_id=event.block_id,
+                delta=event.delta,
+            )
+
+        if isinstance(event, TextBlockEndEvent):
+            return AGUITextMessageEndEvent(
+                message_id=event.block_id,
+            )
+
+        # AGUI has a two-level reasoning structure (ReasoningStart/End wrapping
+        # ReasoningMessage*), but _convert_to_protocol returns a single dict
+        # per input event, so only the inner ReasoningMessage* events are
+        # emitted.  Most AGUI consumers render correctly with message-level
+        # events alone.
+        if isinstance(event, ThinkingBlockStartEvent):
+            return AGUIReasoningMessageStartEvent(
+                message_id=event.block_id,
+                role="reasoning",
+            )
+
+        if isinstance(event, ThinkingBlockDeltaEvent):
+            return AGUIReasoningMessageContentEvent(
+                message_id=event.block_id,
+                delta=event.delta,
+            )
+
+        if isinstance(event, ThinkingBlockEndEvent):
+            return AGUIReasoningMessageEndEvent(
+                message_id=event.block_id,
+            )
+
+        if isinstance(event, ToolCallStartEvent):
+            return AGUIToolCallStartEvent(
+                tool_call_id=event.tool_call_id,
+                tool_call_name=event.tool_call_name,
+                parent_message_id=event.reply_id,
+            )
+
+        if isinstance(event, ToolCallDeltaEvent):
+            return AGUIToolCallArgsEvent(
+                tool_call_id=event.tool_call_id,
+                delta=event.delta,
+            )
+
+        if isinstance(event, ToolCallEndEvent):
+            return AGUIToolCallEndEvent(
+                tool_call_id=event.tool_call_id,
+            )
+
+        if isinstance(event, ToolResultStartEvent):
+            return AGUICustomEvent(
+                name="tool_result_start",
+                value=event.model_dump(exclude_none=True),
+            )
+
+        if isinstance(event, ToolResultTextDeltaEvent):
+            self._tool_result_buffers.setdefault(
+                event.tool_call_id,
+                [],
+            ).append(event.delta)
+            return AGUICustomEvent(
+                name="tool_result_text_delta",
+                value=event.model_dump(exclude_none=True),
+            )
+
+        if isinstance(event, ToolResultDataDeltaEvent):
+            return AGUICustomEvent(
+                name="tool_result_data_delta",
+                value=event.model_dump(exclude_none=True),
+            )
+
+        if isinstance(event, ToolResultEndEvent):
+            content = "".join(
+                self._tool_result_buffers.pop(event.tool_call_id, []),
+            )
+            return AGUIToolCallResultEvent(
+                tool_call_id=event.tool_call_id,
+                message_id=event.reply_id,
+                content=content or str(event.state),
+            )
+
+        if isinstance(event, DataBlockStartEvent):
+            return AGUICustomEvent(
+                name="data_block_start",
+                value=event.model_dump(exclude_none=True),
+            )
+
+        if isinstance(event, DataBlockDeltaEvent):
+            return AGUICustomEvent(
+                name="data_block_delta",
+                value=event.model_dump(exclude_none=True),
+            )
+
+        if isinstance(event, DataBlockEndEvent):
+            return AGUICustomEvent(
+                name="data_block_end",
+                value=event.model_dump(exclude_none=True),
+            )
+
+        if isinstance(event, RequireUserConfirmEvent):
+            return AGUICustomEvent(
+                name="require_user_confirm",
+                value=event.model_dump(exclude_none=True),
+            )
+
+        if isinstance(event, RequireExternalExecutionEvent):
+            return AGUICustomEvent(
+                name="require_external_execution",
+                value=event.model_dump(exclude_none=True),
+            )
+
+        if isinstance(event, UserConfirmResultEvent):
+            return AGUICustomEvent(
+                name="user_confirm_result",
+                value=event.model_dump(exclude_none=True),
+            )
+
+        if isinstance(event, ExternalExecutionResultEvent):
+            return AGUICustomEvent(
+                name="external_execution_result",
+                value=event.model_dump(exclude_none=True),
+            )
+
+        return AGUICustomEvent(
+            name="unknown",
+            value=event.model_dump(exclude_none=True),
+        )
diff --git a/src/agentscope/app/middleware/_protocol/_base.py b/src/agentscope/app/middleware/_protocol/_base.py
new file mode 100644
index 0000000..691836b
--- /dev/null
+++ b/src/agentscope/app/middleware/_protocol/_base.py
@@ -0,0 +1,244 @@
+# -*- coding: utf-8 -*-
+"""Protocol middleware base class for converting AgentEvent stream to
+various protocols."""
+
+import json
+from abc import ABC, abstractmethod
+from typing import AsyncGenerator, Callable
+
+from fastapi import Request, Response
+from fastapi.responses import StreamingResponse
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.types import ASGIApp
+
+from agentscope.event import AgentEvent
+
+
+class ProtocolMiddlewareBase(BaseHTTPMiddleware, ABC):
+    """Base middleware for converting AgentEvent stream to protocol format.
+
+    This middleware intercepts ``text/event-stream`` responses, deserializes
+    AgentEvent objects from SSE ``data:`` frames, and converts them to a
+    specific protocol format.
+
+    Subclasses should implement the `_convert_to_protocol` method to define
+    the conversion logic for their specific protocol (e.g., AGUI, A2A).
+
+    Example:
+        ```python
+        class AGUIMiddleware(ProtocolMiddlewareBase):
+            def _convert_to_protocol(self, event: AgentEvent) -> dict:
+                # Implement AGUI-specific conversion logic
+                return {...}
+
+        app = FastAPI()
+        app.add_middleware(AGUIMiddleware)
+        ```
+    """
+
+    def __init__(self, app: ASGIApp) -> None:
+        """Initialize the protocol middleware.
+
+        Args:
+            app: The ASGI application to wrap.
+        """
+        super().__init__(app)
+
+    async def dispatch(
+        self,
+        request: Request,
+        call_next: Callable,
+    ) -> Response:
+        """Process the request and convert AgentEvent stream to protocol
+        format.
+
+        Args:
+            request: The incoming HTTP request.
+            call_next: The next middleware or endpoint handler.
+
+        Returns:
+            The response, potentially with converted stream content.
+        """
+        # Call the next middleware or endpoint
+        response = await call_next(request)
+
+        content_type = response.headers.get("content-type", "")
+        body_iterator = getattr(response, "body_iterator", None)
+
+        if (
+            content_type.startswith("text/event-stream")
+            and body_iterator is not None
+        ):
+            # Wrap the original stream with our conversion logic
+            converted_stream = self._convert_stream(body_iterator)
+
+            # Create a new StreamingResponse with the converted stream
+            return StreamingResponse(
+                content=converted_stream,
+                status_code=response.status_code,
+                headers=dict(response.headers),
+                media_type=response.media_type,
+            )
+
+        return response
+
+    async def _convert_stream(
+        self,
+        original_stream: AsyncGenerator,
+    ) -> AsyncGenerator[bytes, None]:
+        """Convert AgentEvent stream to protocol format.
+
+        Args:
+            original_stream: The original stream yielding serialized
+                AgentEvent objects.
+
+        Yields:
+            Bytes in protocol format.
+        """
+        async for chunk in original_stream:
+            if isinstance(chunk, bytes):
+                chunk_str = chunk.decode("utf-8")
+            else:
+                chunk_str = chunk
+
+            converted = self._convert_sse_frame(chunk_str)
+            if converted is not None:
+                yield converted
+                continue
+
+            # Fallback for subclasses that may override dispatch() to handle
+            # non-SSE streams while still reusing this converter.
+            converted = self._convert_event_json(chunk_str)
+            if converted is not None:
+                yield converted
+                continue
+
+            if isinstance(chunk, bytes):
+                yield chunk
+            else:
+                yield chunk.encode("utf-8")
+
+    def _convert_sse_frame(self, frame: str) -> bytes | None:
+        """Convert AgentEvent payloads inside an SSE frame.
+
+        Note:
+            This method targets the AgentScope service's SSE stream shape:
+            each ``data:`` line contains a complete JSON payload, and each
+            input ``frame`` contains one or more complete SSE frames. SSE
+            multi-line ``data:`` concatenation and cross-chunk frame
+            reassembly are intentionally out of scope here.
+
+        Args:
+            frame: A server-sent event frame.
+
+        Returns:
+            Converted frame bytes if at least one ``data:`` payload was
+            converted, otherwise ``None``.
+        """
+        lines = frame.splitlines(keepends=True)
+        converted_lines: list[str] = []
+        converted_any = False
+
+        for line in lines:
+            if not line.startswith("data:"):
+                converted_lines.append(line)
+                continue
+
+            line_content, line_ending = self._split_line_ending(line)
+            payload = line_content.removeprefix("data:")
+            if payload.startswith(" "):
+                payload = payload[1:]
+
+            converted = self._convert_event_json(payload)
+            if converted is None:
+                converted_lines.append(line)
+                continue
+
+            converted_json = converted.decode("utf-8").rstrip("\n")
+            converted_lines.append(f"data: {converted_json}{line_ending}")
+            converted_any = True
+
+        if not converted_any:
+            return None
+
+        return "".join(converted_lines).encode("utf-8")
+
+    @staticmethod
+    def _split_line_ending(line: str) -> tuple[str, str]:
+        """Split a line into content and its original line ending."""
+        if line.endswith("\r\n"):
+            return line[:-2], "\r\n"
+        if line.endswith("\n"):
+            return line[:-1], "\n"
+        if line.endswith("\r"):
+            return line[:-1], "\r"
+        return line, ""
+
+    def _convert_event_json(self, chunk_str: str) -> bytes | None:
+        """Convert a serialized AgentEvent JSON string.
+
+        Args:
+            chunk_str: Serialized AgentEvent JSON.
+
+        Returns:
+            Converted protocol JSON bytes with trailing newline, or ``None``
+            when ``chunk_str`` is not a valid AgentEvent payload.
+        """
+        try:
+            event_dict = json.loads(chunk_str)
+            agent_event = self._deserialize_event(event_dict)
+            protocol_data = self._convert_to_protocol(agent_event)
+            return (
+                json.dumps(protocol_data, ensure_ascii=False).encode(
+                    "utf-8",
+                )
+                + b"\n"
+            )
+        except (json.JSONDecodeError, KeyError, TypeError, ValueError):
+            return None
+
+    def _deserialize_event(self, event_dict: dict) -> AgentEvent:
+        """Deserialize event dictionary to AgentEvent object.
+
+        Args:
+            event_dict: Dictionary containing event data with 'type' field.
+
+        Returns:
+            Deserialized AgentEvent object.
+
+        Raises:
+            ValueError: If event type is unknown or deserialization fails.
+        """
+        from pydantic import Field, TypeAdapter
+        from typing import Annotated
+
+        # Use Pydantic's discriminated union to automatically deserialize
+        # based on the 'type' field
+        adapter = TypeAdapter(
+            Annotated[AgentEvent, Field(discriminator="type")],
+        )
+        return adapter.validate_python(event_dict)
+
+    @abstractmethod
+    def _convert_to_protocol(self, event: AgentEvent) -> dict:
+        """Convert AgentEvent to protocol format.
+
+        This is an abstract method that must be implemented by subclasses
+        to define the conversion logic for their specific protocol.
+
+        Args:
+            event: The AgentEvent object to convert.
+
+        Returns:
+            Dictionary in the target protocol format.
+
+        Example:
+            ```python
+            class AGUIMiddleware(ProtocolMiddlewareBase):
+                def _convert_to_protocol(self, event: AgentEvent) -> dict:
+                    # Convert to AGUI format
+                    agui_data = event.model_dump()
+                    agui_data["agui_version"] = "1.0"
+                    return agui_data
+            ```
+        """
diff --git a/src/agentscope/app/middleware/_state_change_middleware.py b/src/agentscope/app/middleware/_state_change_middleware.py
new file mode 100644
index 0000000..7e56695
--- /dev/null
+++ b/src/agentscope/app/middleware/_state_change_middleware.py
@@ -0,0 +1,196 @@
+# -*- coding: utf-8 -*-
+"""Middleware that detects agent state / team changes after each tool
+call and pushes a :class:`CustomEvent` notification to the session's
+event stream.
+
+Two kinds of change are detected:
+
+- **State change** — ``tasks_context`` or ``permission_context``
+  modified (detected via hash comparison). Checked both around each
+  tool call (``on_acting``, for incremental updates during a turn)
+  and around the whole reply (``on_reply``, to catch changes made
+  outside the tool-execution window — e.g. permission rules added
+  while handling a user confirmation). Pushes
+  ``CustomEvent(name="state_updated", value={...})``.
+- **Team change** — the tool that just ran is one of the team tools
+  (``TeamCreate``, ``AgentCreate``, ``AgentInvite``, ``TeamDelete``).
+  These tools directly mutate storage (``TeamRecord``,
+  ``SessionRecord.team_id``), so we don't need to check storage; the
+  fact that the tool ran is the trigger. Pushes
+  ``CustomEvent(name="team_updated", value={})``.
+
+Both events are published directly to the bus (via
+``session_publish_event``) instead of being yielded through the agent's
+event chain, because ``on_acting`` yields ``ToolChunk | ToolResponse``
+— not ``AgentEvent``. The SSE ``/stream`` endpoint picks them up from
+the bus like any other session event.
+"""
+import hashlib
+from typing import Any, AsyncGenerator, Callable
+
+from ..message_bus import MessageBus
+from .._bus_ops import publish_session_event
+from ...event import CustomEvent
+from ...middleware import MiddlewareBase
+
+_TEAM_TOOL_NAMES = frozenset(
+    {"TeamCreate", "AgentCreate", "AgentInvite", "TeamDelete"},
+)
+# Tool names whose execution implies a team membership change.
+
+
+class StateChangeMiddleware(MiddlewareBase):  # pylint: disable=abstract-method
+    """Detect state / team changes after each tool call and push
+    notifications to the session event stream.
+
+    Args:
+        message_bus (`MessageBus`):
+            Used to publish ``CustomEvent`` to the session's event
+            stream via :meth:`MessageBus.session_publish_event`.
+        session_id (`str`):
+            The session whose event stream to publish to.
+    """
+
+    def __init__(
+        self,
+        message_bus: MessageBus,
+        session_id: str,
+    ) -> None:
+        """Initialise the middleware.
+
+        Args:
+            message_bus (`MessageBus`):
+                Application message bus.
+            session_id (`str`):
+                The session id to publish events for.
+        """
+        self._bus = message_bus
+        self._session_id = session_id
+
+    @staticmethod
+    def _state_hash(agent: Any) -> str:
+        """Compute a fast hash of the state fields we track.
+
+        Only ``tasks_context`` and ``permission_context`` are included;
+        ``context`` (the message history) is intentionally excluded
+        because it changes on every reasoning step and is not what
+        this middleware cares about.
+
+        Args:
+            agent: The agent instance.
+
+        Returns:
+            `str`: A hex digest that changes when the tracked fields
+            change.
+        """
+        raw = (
+            agent.state.tasks_context.model_dump_json()
+            + agent.state.permission_context.model_dump_json()
+        )
+        return hashlib.md5(raw.encode()).hexdigest()
+
+    async def _publish_state(self, agent: Any) -> None:
+        """Push a ``state_updated`` event with the current tracked state.
+
+        Args:
+            agent: The agent instance whose state to publish.
+        """
+        event = CustomEvent(
+            name="state_updated",
+            value={
+                "tasks_context": agent.state.tasks_context.model_dump(
+                    mode="json",
+                ),
+                "permission_context": (
+                    agent.state.permission_context.model_dump(
+                        mode="json",
+                    )
+                ),
+            },
+        )
+        await publish_session_event(
+            self._bus,
+            self._session_id,
+            event.model_dump(mode="json"),
+        )
+
+    async def on_reply(
+        self,
+        agent: Any,
+        input_kwargs: dict,
+        next_handler: Callable[..., AsyncGenerator],
+    ) -> AsyncGenerator:
+        """Wrap the whole reply turn to catch state changes that happen
+        **outside** the ``on_acting`` tool-execution window.
+
+        Permission rules added while handling a
+        ``UserConfirmResultEvent`` (the user's "always allow" choice)
+        mutate ``permission_context`` in ``_handle_incoming_event`` —
+        which runs at the *start* of the reply turn, before the
+        confirmed tool's ``on_acting`` snapshot is taken. ``on_acting``
+        therefore sees no diff (the rule is already present in both its
+        before- and after-hash) and never pushes. Snapshotting around
+        the entire reply closes that gap.
+
+        Args:
+            agent: The executing agent.
+            input_kwargs (`dict`):
+                The reply inputs (new message(s) or a resumption event).
+            next_handler (`Callable[..., AsyncGenerator]`):
+                The downstream middleware or core reply logic.
+
+        Yields:
+            ``AgentEvent | Msg`` — unchanged from downstream.
+        """
+        hash_before = self._state_hash(agent)
+
+        async for item in next_handler(**input_kwargs):
+            yield item
+
+        hash_after = self._state_hash(agent)
+        if hash_before != hash_after:
+            await self._publish_state(agent)
+
+    async def on_acting(
+        self,
+        agent: Any,
+        input_kwargs: dict,
+        next_handler: Callable[..., AsyncGenerator],
+    ) -> AsyncGenerator:
+        """Wrap tool execution: snapshot state hash before, compare
+        after, and push notifications if anything changed.
+
+        Args:
+            agent: The executing agent.
+            input_kwargs (`dict`):
+                Contains ``tool_call`` (``ToolCallBlock``).
+            next_handler (`Callable[..., AsyncGenerator]`):
+                The downstream middleware or core acting logic.
+
+        Yields:
+            ``ToolChunk | ToolResponse`` — unchanged from downstream.
+        """
+        tool_call = input_kwargs.get("tool_call")
+        tool_name = tool_call.name if tool_call else ""
+
+        hash_before = self._state_hash(agent)
+
+        async for item in next_handler(**input_kwargs):
+            yield item
+
+        # Check 1: state fields changed?
+        hash_after = self._state_hash(agent)
+        if hash_before != hash_after:
+            await self._publish_state(agent)
+
+        # Check 2: team tool ran?
+        if tool_name in _TEAM_TOOL_NAMES:
+            event = CustomEvent(
+                name="team_updated",
+                value={},
+            )
+            await publish_session_event(
+                self._bus,
+                self._session_id,
+                event.model_dump(mode="json"),
+            )
diff --git a/src/agentscope/app/middleware/_tool_offload_middleware.py b/src/agentscope/app/middleware/_tool_offload_middleware.py
new file mode 100644
index 0000000..3c58459
--- /dev/null
+++ b/src/agentscope/app/middleware/_tool_offload_middleware.py
@@ -0,0 +1,397 @@
+# -*- coding: utf-8 -*-
+"""Middleware that offloads long-running tool calls to background tasks.
+
+When a tool times out, this middleware:
+
+- Lets the underlying asyncio task keep running via
+  :class:`BackgroundTaskManager` (the task is **never cancelled**).
+- Yields a synthetic placeholder :class:`ToolResponse` so the agent
+  loop unblocks immediately.
+- On task completion, pushes the real result as a
+  :class:`HintBlock` to the session's inbox via the message bus and
+  enqueues a wakeup. From there the result follows the same path as a
+  team message: :class:`InboxMiddleware` drains it into context on
+  the next reasoning step (same run or a fresh wakeup-driven run),
+  and :class:`WakeupDispatcher` ensures an idle session is started by
+  some process.
+
+The middleware no longer keeps its own pending-result store or
+retrigger callback — both responsibilities now live in the
+bus/wakeup infrastructure, which works correctly across processes.
+"""
+import asyncio
+import json
+from copy import deepcopy
+from typing import AsyncGenerator, Callable
+
+from .._manager import BackgroundTaskManager
+from ...middleware import MiddlewareBase
+from ...tool import ToolChunk, ToolResponse
+from ...message import (
+    DataBlock,
+    HintBlock,
+    TextBlock,
+    ToolResultState,
+)
+from ...agent import Agent
+from ..message_bus import MessageBus, MessageBusKeys
+from .._bus_ops import enqueue_run_trigger
+from ..._logging import logger
+
+
+# Sentinel object used to signal end-of-stream in the drain queue.
+_QUEUE_SENTINEL = object()
+
+
+class ToolOffloadMiddleware(MiddlewareBase):  # pylint: disable=abstract-method
+    """Middleware that offloads timed-out tool calls to background tasks.
+
+    .. note::
+        Tools with ``is_state_injected=True`` receive the live
+        ``agent.state`` object. Offloading them could race on shared
+        state, so they are always executed synchronously instead.
+
+    Args:
+        bg_manager (`BackgroundTaskManager`):
+            Application-level background task manager. Used to register
+            the running asyncio task so :class:`ToolStop` can target it.
+        message_bus (`MessageBus`):
+            Application message bus. The completion callback uses it to
+            push the result HintBlock to the session's inbox and to
+            enqueue a wakeup so an idle session is woken on any process.
+        user_id (`str`):
+            User id of the current request — included in the wakeup
+            payload so the dispatcher can re-invoke ``ChatService.run``.
+        agent_id (`str`):
+            Agent record id (not the display name) — same purpose as
+            ``user_id``.
+        timeout_secs (`float`, defaults to ``10.0``):
+            Maximum seconds to wait for a tool execution before
+            offloading it to the background.
+    """
+
+    def __init__(
+        self,
+        bg_manager: BackgroundTaskManager,
+        message_bus: MessageBus,
+        user_id: str,
+        agent_id: str,
+        timeout_secs: float = 10.0,
+    ) -> None:
+        """Bind dependencies.
+
+        Args:
+            bg_manager (`BackgroundTaskManager`):
+                Application background task manager.
+            message_bus (`MessageBus`):
+                Application message bus.
+            user_id (`str`):
+                User id of the current request.
+            agent_id (`str`):
+                Agent record id (not the display name).
+            timeout_secs (`float`, defaults to ``10.0``):
+                Tool execution timeout before offloading to background.
+        """
+        self._bg_manager = bg_manager
+        self._message_bus = message_bus
+        self._user_id = user_id
+        self._agent_id = agent_id
+        self._timeout_secs = timeout_secs
+
+    # ------------------------------------------------------------------
+    # Middleware hooks
+    # ------------------------------------------------------------------
+
+    async def on_acting(  # type:ignore[override]
+        self,
+        agent: Agent,
+        input_kwargs: dict,
+        next_handler: Callable[..., AsyncGenerator],
+    ) -> AsyncGenerator:
+        """Execute a tool with timeout; offload to background on expiry.
+
+        The inner ``next_handler`` generator is wrapped in an
+        :mod:`asyncio` task whose output is fed through a
+        :class:`asyncio.Queue`.  Items are consumed with a rolling
+        deadline.  If the deadline fires before the tool finishes:
+
+        - The running task is **not** cancelled.
+        - It is registered with :attr:`_bg_manager` so that
+          :class:`ToolStop` can target it and shutdown can cancel it.
+        - A separate watcher coroutine is spawned to await the task's
+          completion and then push the result as a
+          :class:`HintBlock` to the session inbox + enqueue a wakeup.
+        - A synthetic :class:`~agentscope.tool.ToolResponse` notifying
+          the agent of the background task id is yielded instead.
+
+        .. note::
+            Tools with ``is_state_injected=True`` or ``is_external_tool=True``
+            bypass this logic and are always executed synchronously.
+
+        Args:
+            agent (`Agent`):
+                The executing agent.
+            input_kwargs (`dict`):
+                Acting input kwargs (contains ``tool_call``).
+            next_handler (`Callable[..., AsyncGenerator]`):
+                The downstream middleware or ``_acting_impl``.
+
+        Yields:
+            `ToolChunk | ToolResponse`:
+                Normal results when the tool finishes in time, or a
+                synthetic ``ToolResponse`` when offloaded.
+        """
+        tool_call = input_kwargs["tool_call"]
+
+        # ----------------------------------------------------------------
+        # Guard: state-injected tools and external tools are never offloaded.
+        # - is_state_injected: the tool receives the live agent.state object;
+        #   running it concurrently in a background task could cause race
+        #   conditions on agent.state. For now, we fall back to synchronous
+        #   execution. Once background tasks can be given an isolated state
+        #   snapshot this guard should become a hard RuntimeError instead.
+        # - is_external_tool: external tools wait for a human/external system
+        #   to push a result back; offloading them makes no sense because the
+        #   agent would lose track of the pending confirmation.
+        tool = await agent.toolkit.get_tool(tool_call.name)
+        if tool is not None and (
+            tool.is_state_injected or tool.is_external_tool
+        ):
+            async for item in next_handler(**input_kwargs):
+                yield item
+            return
+
+        # ----------------------------------------------------------------
+        # Wrap next_handler in a Task, draining output into a Queue
+        # ----------------------------------------------------------------
+        queue: asyncio.Queue = asyncio.Queue()
+
+        async def _drain_to_queue() -> None:
+            """Drain next_handler output into *queue*."""
+            try:
+                async for item in next_handler(**input_kwargs):
+                    await queue.put(item)
+            except Exception as exc:  # pylint: disable=broad-except
+                await queue.put(exc)
+            finally:
+                await queue.put(_QUEUE_SENTINEL)
+
+        drain_task: asyncio.Task = asyncio.create_task(_drain_to_queue())
+
+        # ----------------------------------------------------------------
+        # Consume items until the deadline or normal completion
+        # ----------------------------------------------------------------
+        loop = asyncio.get_event_loop()
+        deadline = loop.time() + self._timeout_secs
+        pre_collected: list = []
+        completed = False
+
+        while True:
+            remaining = deadline - loop.time()
+            if remaining <= 0:
+                break
+
+            try:
+                item = await asyncio.wait_for(
+                    queue.get(),
+                    timeout=remaining,
+                )
+            except asyncio.TimeoutError:
+                break
+
+            if item is _QUEUE_SENTINEL:
+                completed = True
+                break
+
+            if isinstance(item, BaseException):
+                drain_task.cancel()
+                raise item
+
+            pre_collected.append(item)
+
+            # ToolResponse is always the terminal item from _acting_impl
+            if isinstance(item, ToolResponse):
+                completed = True
+                break
+
+        if completed:
+            for item in pre_collected:
+                yield item
+            drain_task.cancel()
+            return
+
+        # ----------------------------------------------------------------
+        # Timeout path: spawn deliverer, register drain_task, yield synthetic
+        # ----------------------------------------------------------------
+        session_id = agent.state.session_id
+        tool_name = tool_call.name
+        snapshot = list(pre_collected)
+
+        logger.info(
+            "Tool '%s' timed out after %.1fs, offloading to background: "
+            "session_id=%s, agent_id=%s",
+            tool_name,
+            self._timeout_secs,
+            session_id,
+            agent.name,
+        )
+
+        async def _deliver_when_done() -> None:
+            """Wait for the offloaded tool to finish, then push its
+            result to the session inbox + enqueue a wakeup.
+
+            On cancellation (e.g. ``ToolStop``) or unhandled exception
+            no result is delivered — the agent is left without a
+            completion notification in those edge cases.
+            """
+            try:
+                await drain_task
+            except asyncio.CancelledError:
+                logger.info(
+                    "Background tool '%s' cancelled, skipping delivery: "
+                    "session_id=%s",
+                    tool_name,
+                    session_id,
+                )
+                return
+            except Exception:  # pylint: disable=broad-except
+                logger.warning(
+                    "Background tool '%s' failed, skipping delivery: "
+                    "session_id=%s",
+                    tool_name,
+                    session_id,
+                    exc_info=True,
+                )
+                return
+
+            remaining_items: list = []
+            while not queue.empty():
+                try:
+                    item = queue.get_nowait()
+                    if isinstance(item, ToolResponse):
+                        remaining_items.append(item)
+                        break
+                except asyncio.QueueEmpty:
+                    break
+
+            all_items = snapshot + remaining_items
+            response: ToolResponse | None = next(
+                (i for i in all_items if isinstance(i, ToolResponse)),
+                None,
+            )
+
+            tool_call_id = tool_call.id
+
+            hint_source = json.dumps(
+                {
+                    "label": "tool_output",
+                    "sublabel": f"{tool_name} · {tool_call_id}",
+                },
+                ensure_ascii=False,
+            )
+
+            if response is None or len(response.content) == 0:
+                hint = HintBlock(
+                    hint=(
+                        f"<system-notification>"
+                        f"Tool '{tool_name}' running in background "
+                        f"(id={tool_call_id}) has completed with no output."
+                        f"</system-notification>"
+                    ),
+                    source=hint_source,
+                )
+
+            else:
+                # Preserve all content blocks (text + multimodal) from
+                # the tool response so nothing is lost.
+                content_blocks: list[TextBlock | DataBlock] = deepcopy(
+                    response.content,
+                )
+
+                prefix = (
+                    f"<system-notification>"
+                    f"Tool '{tool_name}' running in background "
+                    f"(id={tool_call_id}) has completed.\n\n"
+                    f"Result:\n\n"
+                )
+
+                if isinstance(content_blocks[0], TextBlock):
+                    content_blocks[0].text = prefix + content_blocks[0].text
+
+                else:
+                    content_blocks.insert(0, TextBlock(text=prefix))
+
+                suffix = "</system-notification>"
+
+                if isinstance(content_blocks[-1], TextBlock):
+                    content_blocks[-1].text += suffix
+                else:
+                    content_blocks.append(
+                        TextBlock(text=suffix),
+                    )
+
+                hint = HintBlock(
+                    hint=content_blocks,
+                    source=hint_source,
+                )
+
+            # Deliver via inbox + wakeup — same path as a team message.
+            # InboxMiddleware drains the inbox into context on the next
+            # reasoning step, and WakeupDispatcher kicks an idle session
+            # on whichever process picks up the wakeup.
+            logger.info(
+                "Background tool '%s' completed, pushing result to inbox "
+                "and enqueueing wakeup: session_id=%s",
+                tool_name,
+                session_id,
+            )
+            await self._message_bus.queue_push(
+                MessageBusKeys.inbox(session_id),
+                hint.model_dump(mode="json"),
+            )
+            await enqueue_run_trigger(
+                self._message_bus,
+                user_id=self._user_id,
+                session_id=session_id,
+                agent_id=self._agent_id,
+            )
+
+        asyncio.create_task(_deliver_when_done())
+        task_id = await self._bg_manager.register_task(
+            asyncio_task=drain_task,
+            session_id=session_id,
+            agent_id=self._agent_id,
+            user_id=self._user_id,
+            tool_name=tool_name,
+        )
+
+        logger.info(
+            "Synthetic ToolResponse yielded for offloaded tool '%s': "
+            "task_id=%s, session_id=%s, agent_id=%s",
+            tool_name,
+            task_id,
+            session_id,
+            agent.name,
+        )
+
+        placeholder_text = f"""<system-reminder>Tool '{tool_name}' is \
+running in background (id={task_id}) for over {self._timeout_secs}s. \
+You will be notified automatically when it finishes, so **DO NOT** poll, \
+query, or wait for the result yourself. **DO NOT** call any waiting tool \
+such as `bash sleep`. You have exactly two valid options:
+1. Continue with other independent tasks and ignore this tool for now; or
+2. If there is nothing else to do, simply give a text reply without calling \
+any tool, which ends the current reasoning loop — just do nothing and end \
+this run.
+</system-reminder>"""
+
+        yield ToolChunk(
+            content=[TextBlock(text=placeholder_text)],
+            state=ToolResultState.SUCCESS,
+        )
+
+        yield ToolResponse(
+            content=[TextBlock(text=placeholder_text)],
+            state=ToolResultState.SUCCESS,
+            id=tool_call.id,
+        )
diff --git a/src/agentscope/app/rag/__init__.py b/src/agentscope/app/rag/__init__.py
new file mode 100644
index 0000000..3fe4fbc
--- /dev/null
+++ b/src/agentscope/app/rag/__init__.py
@@ -0,0 +1,92 @@
+# -*- coding: utf-8 -*-
+"""Service-layer RAG building blocks.
+
+This subpackage groups every RAG-specific service-layer concept under
+one roof so the user-facing import surface stays compact:
+
+- :mod:`.blob_store` — backends storing uploaded document bytes;
+- :mod:`.knowledge_base_manager` — knowledge base lifecycle and the
+  runtime :class:`~agentscope.rag.KnowledgeBase` handle shared between
+  HTTP and agents;
+- :mod:`.index_worker` — out-of-process indexing worker entry point.
+
+Commonly used symbols are re-exported here so the typical user import
+collapses to a single line::
+
+    from agentscope.app.rag import (
+        LocalBlobStore,
+        S3BlobStore,
+        CollectionPerKbManager,
+        run_worker,
+    )
+
+For type-level imports or rare subclasses, use the submodules directly.
+"""
+from typing import TYPE_CHECKING
+
+from .blob_store import (
+    AsyncReadable,
+    BlobStoreBase,
+    LocalBlobStore,
+    S3BlobStore,
+)
+from .knowledge_base_manager import (
+    CollectionPerKbManager,
+    DimensionPolicy,
+    DimensionPolicyError,
+    DimensionPolicyKind,
+    KnowledgeBaseError,
+    KnowledgeBaseManagerBase,
+    KnowledgeBaseNotFoundError,
+)
+
+if TYPE_CHECKING:
+    # Re-exported lazily at runtime via ``__getattr__`` to break a
+    # package-load import cycle; declared here so static analysers
+    # (pylint, mypy, IDEs) still see the symbol on the package.
+    from .index_worker import run_worker  # noqa: F401
+
+
+def __getattr__(name: str) -> object:
+    """Lazy-load attributes that would cause an import cycle.
+
+    ``run_worker`` is lazy-imported because :mod:`.index_worker` pulls
+    in :mod:`agentscope.app._service`, which itself imports
+    :mod:`agentscope.app.rag` for the middleware — a direct re-export
+    would create an import cycle at package load.  Users who actually
+    want the worker (``from agentscope.app.rag import run_worker``)
+    pay the import cost on first access.
+
+    Args:
+        name (`str`):
+            The attribute name requested by the importer.
+
+    Returns:
+        `object`:
+            The resolved attribute value.
+
+    Raises:
+        `AttributeError`:
+            When ``name`` is not exposed by this package.
+    """
+    if name == "run_worker":
+        from .index_worker import run_worker as _run_worker
+
+        return _run_worker
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    "AsyncReadable",
+    "BlobStoreBase",
+    "CollectionPerKbManager",
+    "DimensionPolicy",
+    "DimensionPolicyError",
+    "DimensionPolicyKind",
+    "KnowledgeBaseError",
+    "KnowledgeBaseManagerBase",
+    "KnowledgeBaseNotFoundError",
+    "LocalBlobStore",
+    "S3BlobStore",
+    "run_worker",
+]
diff --git a/src/agentscope/app/rag/blob_store/__init__.py b/src/agentscope/app/rag/blob_store/__init__.py
new file mode 100644
index 0000000..c2e543d
--- /dev/null
+++ b/src/agentscope/app/rag/blob_store/__init__.py
@@ -0,0 +1,12 @@
+# -*- coding: utf-8 -*-
+"""Blob storage backends for document uploads."""
+from ._base import AsyncReadable, BlobStoreBase
+from ._local import LocalBlobStore
+from ._s3 import S3BlobStore
+
+__all__ = [
+    "AsyncReadable",
+    "BlobStoreBase",
+    "LocalBlobStore",
+    "S3BlobStore",
+]
diff --git a/src/agentscope/app/rag/blob_store/_base.py b/src/agentscope/app/rag/blob_store/_base.py
new file mode 100644
index 0000000..a7c4bed
--- /dev/null
+++ b/src/agentscope/app/rag/blob_store/_base.py
@@ -0,0 +1,158 @@
+# -*- coding: utf-8 -*-
+"""Abstract base class for blob storage backends.
+
+A :class:`BlobStoreBase` is the byte-level home of files uploaded into
+the application — knowledge base documents in v1, potentially other
+binary payloads later.  It is created once at app startup and shared
+across requests, mirroring the lifecycle of
+:class:`~agentscope.app.storage.StorageBase` and
+:class:`~agentscope.rag.VectorStoreBase`.
+
+The abstraction owes its existence to a single hard requirement: bytes
+must never sit in memory for the duration of indexing.  The upload
+endpoint streams the request body into ``write_stream``; the indexing
+worker streams the bytes back out via ``open``.  Implementations decide
+where those bytes physically live (local disk, S3-compatible object
+store, etc.) — neither caller cares.
+"""
+from abc import ABC, abstractmethod
+from contextlib import AbstractAsyncContextManager
+from typing import IO, Any, Protocol, Self
+
+
+class AsyncReadable(Protocol):
+    """Minimal async-read protocol returned by :meth:`BlobStoreBase.open`.
+
+    Backed by ``aiofiles`` handles for the local store and by streaming
+    response bodies for object-storage backends.  The narrow interface
+    keeps the worker's blob-reading code identical across backends
+    even though no single concrete type implements both shapes.
+    """
+
+    async def read(self, n: int = -1) -> bytes:
+        """Read up to ``n`` bytes (``-1`` reads to EOF).
+
+        Args:
+            n (`int`, defaults to ``-1``):
+                The maximum number of bytes to read; ``-1`` drains the
+                stream.
+
+        Returns:
+            `bytes`:
+                The bytes read; an empty ``bytes`` at EOF.
+        """
+
+
+class BlobStoreBase(ABC):
+    """Abstract base class for blob storage backends.
+
+    Lifecycle is managed via the async context manager protocol so the
+    app lifespan can open / close connection pools or filesystem
+    handles uniformly.
+    """
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def __aenter__(self) -> Self:
+        """Enter the async context — open connections / create dirs.
+
+        The default implementation is a no-op.  Subclasses that need
+        explicit setup should override this.
+
+        Returns:
+            `BlobStoreBase`:
+                ``self``.
+        """
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: Any,
+    ) -> None:
+        """Exit the async context — close connections if needed."""
+
+    # ------------------------------------------------------------------
+    # Byte operations
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    async def write_stream(self, key: str, stream: IO[bytes]) -> str:
+        """Stream-write a blob and return its URI.
+
+        Implementations MUST copy the bytes in chunks (typically ~1 MB)
+        and MUST NOT call ``stream.read()`` without a size argument —
+        the whole point of the abstraction is that the byte payload
+        never lives in memory all at once.
+
+        Args:
+            key (`str`):
+                Backend-relative key, e.g. ``"kb/{kb_id}/{doc_id}"``.
+                The caller picks the key layout; the backend turns it
+                into a backend-native location (filesystem path,
+                ``s3://`` object name, ...).
+            stream (`IO[bytes]`):
+                A readable binary stream.  Synchronous read API
+                (``read(n)``) — ``UploadFile.file`` from FastAPI fits
+                directly, and other binary streams are wrapped via the
+                same protocol.
+
+        Returns:
+            `str`:
+                A scheme-qualified URI (e.g. ``"local://kb/.../uuid"``,
+                ``"s3://bucket/kb/.../uuid"``) that round-trips back
+                through :meth:`open` / :meth:`delete` / :meth:`exists`.
+        """
+
+    @abstractmethod
+    async def open(
+        self,
+        uri: str,
+    ) -> AbstractAsyncContextManager[AsyncReadable]:
+        """Stream-read a blob by URI.
+
+        Returns an async context manager whose ``__aenter__`` yields a
+        stream with an awaitable ``read(n)`` method.  Implementations
+        decide whether the stream is backed by an ``aiofiles`` handle,
+        a streaming response body, or any other async source —
+        callers MUST treat it as forward-only and chunked.
+
+        Args:
+            uri (`str`):
+                A URI produced by :meth:`write_stream`.
+
+        Returns:
+            `AbstractAsyncContextManager[AsyncReadable]`:
+                The byte stream, wrapped so the backend can release
+                handles deterministically on context exit.
+        """
+
+    @abstractmethod
+    async def delete(self, uri: str) -> None:
+        """Delete the blob at ``uri`` if it exists.
+
+        MUST be idempotent — a no-op when the blob is already gone.
+        The caller (document deletion path) treats blob deletion as
+        best-effort cleanup; partial failures are recoverable by
+        re-running the sweep.
+
+        Args:
+            uri (`str`):
+                A URI produced by :meth:`write_stream`.
+        """
+
+    @abstractmethod
+    async def exists(self, uri: str) -> bool:
+        """Return whether the blob at ``uri`` is present.
+
+        Args:
+            uri (`str`):
+                A URI produced by :meth:`write_stream`.
+
+        Returns:
+            `bool`:
+                ``True`` if the blob is currently retrievable.
+        """
diff --git a/src/agentscope/app/rag/blob_store/_local.py b/src/agentscope/app/rag/blob_store/_local.py
new file mode 100644
index 0000000..10ddd28
--- /dev/null
+++ b/src/agentscope/app/rag/blob_store/_local.py
@@ -0,0 +1,145 @@
+# -*- coding: utf-8 -*-
+"""Local filesystem implementation of :class:`BlobStoreBase`.
+
+The backend reserves a single root directory and treats keys as
+relative paths beneath it.  URIs are formatted as ``local://{key}`` —
+the scheme acts as a discriminator so a mixed-deployment app can route
+``local://`` and ``s3://`` URIs to different backends without
+re-parsing the rest of the string.
+"""
+import os
+import shutil
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import IO, AsyncIterator
+
+import aiofiles
+import aiofiles.os
+import aiofiles.ospath
+
+from ._base import AsyncReadable, BlobStoreBase
+
+
+_SCHEME = "local://"
+_CHUNK_SIZE = 1 << 20  # 1 MiB — keep peak memory bounded, match S3 part size.
+
+
+class LocalBlobStore(BlobStoreBase):
+    """Store blobs as files beneath a configurable root directory.
+
+    Intended for single-node deployments and development.  The lifecycle
+    of a blob is bound to the document that owns it, not to the request
+    that uploaded it — this is what distinguishes the store from
+    FastAPI's per-request ``SpooledTemporaryFile`` and is the reason
+    the abstraction exists at all.
+    """
+
+    def __init__(self, root_dir: str | os.PathLike) -> None:
+        """Initialize the local backend.
+
+        Args:
+            root_dir (`str | PathLike`):
+                Directory that holds all blobs for this app.  Created
+                on :meth:`__aenter__` if it does not exist.
+        """
+        self._root = Path(root_dir).resolve()
+
+    async def __aenter__(self) -> "LocalBlobStore":
+        """Ensure the root directory exists."""
+        await aiofiles.os.makedirs(self._root, exist_ok=True)
+        return self
+
+    def _path_for(self, key: str) -> Path:
+        """Resolve a backend-relative key to an absolute filesystem path.
+
+        Rejects keys that try to escape :attr:`_root` via ``..`` or
+        absolute paths.  Callers pick keys server-side so this is
+        defensive rather than a primary trust boundary, but we still
+        refuse to write outside the root.
+
+        Args:
+            key (`str`):
+                Backend-relative key.
+
+        Returns:
+            `Path`:
+                The absolute filesystem path within :attr:`_root`.
+        """
+        if not key or key.startswith("/") or ".." in Path(key).parts:
+            raise ValueError(f"Invalid blob key: {key!r}")
+        path = (self._root / key).resolve()
+        if self._root not in path.parents and path != self._root:
+            raise ValueError(f"Blob key {key!r} escapes the root directory.")
+        return path
+
+    def _key_from_uri(self, uri: str) -> str:
+        """Extract the backend-relative key from a ``local://`` URI."""
+        if not uri.startswith(_SCHEME):
+            raise ValueError(f"Not a local blob URI: {uri!r}")
+        return uri[len(_SCHEME) :]
+
+    async def write_stream(self, key: str, stream: IO[bytes]) -> str:
+        """Copy ``stream`` into the blob at ``key`` in 1 MiB chunks.
+
+        Creates intermediate directories as needed.  Existing blobs at
+        the same key are overwritten — keys are generated server-side
+        from document ids, so collisions only happen on intentional
+        re-uploads.
+
+        Args:
+            key (`str`):
+                Backend-relative key.
+            stream (`IO[bytes]`):
+                Synchronous binary source.
+
+        Returns:
+            `str`:
+                The ``local://{key}`` URI.
+        """
+        path = self._path_for(key)
+        await aiofiles.os.makedirs(path.parent, exist_ok=True)
+        async with aiofiles.open(path, "wb") as out:
+            while True:
+                chunk = stream.read(_CHUNK_SIZE)
+                if not chunk:
+                    break
+                await out.write(chunk)
+        return f"{_SCHEME}{key}"
+
+    @asynccontextmanager
+    async def open(  # type: ignore[override]
+        self,
+        uri: str,
+    ) -> AsyncIterator[AsyncReadable]:
+        """Open the blob at ``uri`` for streaming reads."""
+        path = self._path_for(self._key_from_uri(uri))
+        async with aiofiles.open(path, "rb") as fp:
+            yield fp
+
+    async def delete(self, uri: str) -> None:
+        """Remove the blob at ``uri`` if present (idempotent)."""
+        path = self._path_for(self._key_from_uri(uri))
+        try:
+            await aiofiles.os.remove(path)
+        except FileNotFoundError:
+            return
+        # Best-effort cleanup of empty parent directories up to the root.
+        parent = path.parent
+        while parent != self._root and parent.is_relative_to(self._root):
+            try:
+                await aiofiles.os.rmdir(parent)
+            except OSError:
+                break
+            parent = parent.parent
+
+    async def exists(self, uri: str) -> bool:
+        """Return whether the blob at ``uri`` is present."""
+        path = self._path_for(self._key_from_uri(uri))
+        return await aiofiles.ospath.isfile(path)
+
+    # Synchronous helper used by tests / cleanup scripts; not part of
+    # the public abstraction.
+    def _wipe(self) -> None:
+        """Delete the entire root directory.  Test-only."""
+        if self._root.exists():
+            shutil.rmtree(self._root)
diff --git a/src/agentscope/app/rag/blob_store/_s3.py b/src/agentscope/app/rag/blob_store/_s3.py
new file mode 100644
index 0000000..0c21a71
--- /dev/null
+++ b/src/agentscope/app/rag/blob_store/_s3.py
@@ -0,0 +1,276 @@
+# -*- coding: utf-8 -*-
+"""S3-compatible implementation of :class:`BlobStoreBase`.
+
+Works against any service that implements the S3 wire protocol —
+AWS S3, MinIO, Cloudflare R2, Aliyun OSS (S3-compatible), Tencent yun COS, etc.
+The discriminator is ``endpoint_url``: ``None`` means real AWS S3
+(``aioboto3`` resolves the regional endpoint); any other value points
+at the compatible service's S3 endpoint.
+
+URIs are formatted as ``s3://{bucket}/{key}``. The bucket is baked
+into the URI (rather than carried out-of-band) so a single deployment
+can read blobs that were written under a different bucket — for
+example, after a bucket migration — without breaking existing
+document records.
+
+The implementation is intentionally minimal: this is a byte store,
+not a multipart upload optimiser. Production-scale uploads (>5 GiB)
+would need the multipart API explicitly, but our documents are
+bounded by ``UPLOAD_MAX_BYTES`` well below that ceiling, so a single
+``upload_fileobj`` call (which uses multipart internally when the
+body is large enough) is sufficient.
+"""
+from contextlib import asynccontextmanager
+from typing import IO, Any, AsyncIterator
+
+from ._base import AsyncReadable, BlobStoreBase
+
+
+_SCHEME = "s3://"
+
+
+class _StreamingBody:
+    """Adapter that exposes :class:`AsyncReadable` over an aioboto3 body.
+
+    ``aioboto3`` returns ``aiohttp``-backed streaming bodies that
+    already expose ``read(n)`` — but ``n=-1`` is "read until EOF"
+    which our ``IndexWorker._read_blob`` does not want; it asks for
+    a bounded chunk every iteration. We wrap the body in a thin
+    object so the adapter contract is explicit and so the underlying
+    body type can change without the worker noticing.
+    """
+
+    def __init__(self, body: Any) -> None:
+        """Initialize the body."""
+        self._body = body
+
+    async def read(self, n: int = -1) -> bytes:
+        """Read up to *n* bytes; ``-1`` reads to EOF."""
+        if n == -1:
+            return await self._body.read()
+        # aiohttp's StreamReader.read(n) returns up to n bytes; if
+        # the server-side stream is bursty, we may get a short read,
+        # which is exactly the contract we want for chunked indexing.
+        return await self._body.read(n)
+
+
+class S3BlobStore(BlobStoreBase):
+    """Store blobs in an S3-compatible bucket."""
+
+    def __init__(
+        self,
+        bucket: str,
+        *,
+        region_name: str | None = None,
+        endpoint_url: str | None = None,
+        aws_access_key_id: str | None = None,
+        aws_secret_access_key: str | None = None,
+        session_token: str | None = None,
+        use_ssl: bool = True,
+        config: Any = None,
+    ) -> None:
+        """Initialize an S3-compatible bucket.
+
+        Args:
+            bucket (`str`):
+                Bucket name. The bucket MUST exist; this store will not
+                create it. Production deployments commonly provision the
+                bucket out-of-band via Terraform / CloudFormation so the
+                app's IAM role does not need ``s3:CreateBucket``.
+            region_name (`str | None`, optional):
+                AWS region for AWS S3. Required for AWS, ignored for
+                MinIO / R2 / other services that locate the bucket via
+                ``endpoint_url``.
+            endpoint_url (`str | None`, optional):
+                Full URL of the S3-compatible service. ``None`` selects
+                real AWS S3. Examples: ``http://minio:9000``,
+                ``https://<account>.r2.cloudflarestorage.com``,
+                ``https://oss-cn-hangzhou.aliyuncs.com``.
+            aws_access_key_id (`str | None`, optional):
+                Static credential. Prefer leaving this ``None`` and letting
+                the IAM role / environment chain resolve credentials when
+                running on AWS infrastructure.
+            aws_secret_access_key (`str | None`, optional):
+                Paired with ``aws_access_key_id``.
+            session_token (`str | None`, optional):
+                For STS-issued temporary credentials.
+            use_ssl (`bool`, defaults to ``True``):
+                Force HTTPS. Production deployments must keep this on;
+                local MinIO with self-signed certs is the only place
+                ``False`` is reasonable.
+            config (`Any | None`, optional):
+                ``aiobotocore.config.AioConfig`` instance for users who
+                need to tune timeouts, retry mode, signature version
+                (e.g. ``s3v4`` for Aliyun OSS), or addressing style.
+                Path-style addressing is needed for MinIO; pass
+                ``AioConfig(s3={"addressing_style": "path"})``.
+        """
+        try:
+            import aioboto3
+        except ImportError as e:
+            raise ImportError(
+                "S3BlobStore requires the optional dependency ``aioboto3``. "
+                "Install it with ``uv pip install aioboto3`` or with the "
+                "``[s3]`` extra.",
+            ) from e
+
+        self._bucket = bucket
+        self._region_name = region_name
+        self._endpoint_url = endpoint_url
+        self._aws_access_key_id = aws_access_key_id
+        self._aws_secret_access_key = aws_secret_access_key
+        self._session_token = session_token
+        self._use_ssl = use_ssl
+        self._config = config
+
+        # Session is cheap; the actual transport is the ``client``
+        # context manager opened per call. We deliberately do NOT
+        # cache a long-lived client across the lifespan: aiobotocore
+        # clients hold an aiohttp connection pool tied to a loop, and
+        # the per-call cost is negligible compared to the network
+        # round-trip.
+        self._session: (
+            aioboto3.Session | None
+        ) = None  # type: ignore[name-defined]
+
+    async def __aenter__(self) -> "S3BlobStore":
+        try:
+            import aioboto3
+        except ImportError as e:
+            raise ImportError(
+                "S3BlobStore requires the optional dependency ``aioboto3``. "
+                "Install it with ``uv pip install aioboto3`` or with the "
+                "``[s3]`` extra.",
+            ) from e
+
+        self._session = aioboto3.Session()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: Any,
+    ) -> None:
+        self._session = None
+
+    def _client(self) -> Any:
+        """Open a fresh S3 client context manager for one call."""
+        if self._session is None:
+            raise RuntimeError(
+                "S3BlobStore is not entered; use it inside "
+                "``async with`` before calling blob methods.",
+            )
+        return self._session.client(
+            "s3",
+            region_name=self._region_name,
+            endpoint_url=self._endpoint_url,
+            aws_access_key_id=self._aws_access_key_id,
+            aws_secret_access_key=self._aws_secret_access_key,
+            aws_session_token=self._session_token,
+            use_ssl=self._use_ssl,
+            config=self._config,
+        )
+
+    @staticmethod
+    def _parse_uri(uri: str) -> tuple[str, str]:
+        """Split an ``s3://{bucket}/{key}`` URI into ``(bucket, key)``."""
+        if not uri.startswith(_SCHEME):
+            raise ValueError(f"Not an S3 blob URI: {uri!r}")
+        rest = uri[len(_SCHEME) :]
+        bucket, _, key = rest.partition("/")
+        if not bucket or not key:
+            raise ValueError(f"Malformed S3 blob URI: {uri!r}")
+        return bucket, key
+
+    @classmethod
+    def _key_from_uri(cls, uri: str, expected_bucket: str) -> str:
+        """Return the object key, asserting the bucket matches.
+
+        Used by mutating operations (``delete``, ``exists``) where
+        crossing into another bucket would be a bug — the configured
+        bucket is the only place the store owns objects.
+        """
+        bucket, key = cls._parse_uri(uri)
+        if bucket != expected_bucket:
+            raise ValueError(
+                f"Bucket {bucket!r} in URI {uri!r} does not match "
+                f"configured bucket {expected_bucket!r}.",
+            )
+        return key
+
+    async def write_stream(self, key: str, stream: IO[bytes]) -> str:
+        """Stream-write a blob and return its ``s3://{bucket}/{key}`` URI.
+
+        Uses ``upload_fileobj`` so aioboto3 picks multipart upload
+        automatically for bodies above the multipart threshold
+        (8 MiB by default in botocore). For smaller bodies it
+        promotes to a single ``PutObject`` call.
+        """
+        async with self._client() as s3:
+            await s3.upload_fileobj(stream, self._bucket, key)
+        return f"{_SCHEME}{self._bucket}/{key}"
+
+    @asynccontextmanager
+    async def open(  # type: ignore[override]
+        self,
+        uri: str,
+    ) -> AsyncIterator[AsyncReadable]:
+        """Stream-read a blob by URI.
+
+        Yields an :class:`AsyncReadable` backed by the response
+        ``Body``. The S3 GET response is held open for the duration
+        of the ``async with`` block — exit promptly so the connection
+        returns to the pool.
+
+        The bucket is read from the URI rather than the configured
+        bucket so post-migration deployments can still resolve
+        document records that were written under the previous bucket.
+        The IAM role must grant ``s3:GetObject`` on the legacy bucket
+        for this to actually succeed at the wire level.
+        """
+        bucket, key = self._parse_uri(uri)
+        async with self._client() as s3:
+            response = await s3.get_object(Bucket=bucket, Key=key)
+            body = response["Body"]
+            try:
+                yield _StreamingBody(body)
+            finally:
+                # aiobotocore's body has a ``close`` coroutine; call
+                # it explicitly so the connection is released rather
+                # than waiting for GC.
+                close = getattr(body, "close", None)
+                if close is not None:
+                    result = close()
+                    if hasattr(result, "__await__"):
+                        await result
+
+    async def delete(self, uri: str) -> None:
+        """Delete the object at ``uri``. Idempotent."""
+        key = self._key_from_uri(uri, self._bucket)
+        async with self._client() as s3:
+            # S3 ``DeleteObject`` is idempotent on a missing key —
+            # no special handling needed for the "already gone" case.
+            await s3.delete_object(Bucket=self._bucket, Key=key)
+
+    async def exists(self, uri: str) -> bool:
+        """Return whether the object at ``uri`` is present."""
+        key = self._key_from_uri(uri, self._bucket)
+        async with self._client() as s3:
+            try:
+                await s3.head_object(Bucket=self._bucket, Key=key)
+                return True
+            except Exception as exc:  # noqa: BLE001
+                # botocore's ClientError has ``response["Error"]["Code"]``
+                # of "404" or "NoSuchKey" for missing objects; we
+                # treat anything that isn't a successful HEAD as
+                # "missing" rather than re-raising, matching the
+                # local backend's permissive contract. A genuinely
+                # broken backend (auth failure, network) will surface
+                # on the next read/write.
+                code = (
+                    getattr(exc, "response", {}).get("Error", {}).get("Code")
+                )
+                if code in {"404", "NoSuchKey", "NotFound"}:
+                    return False
+                raise
diff --git a/src/agentscope/app/rag/index_worker/__init__.py b/src/agentscope/app/rag/index_worker/__init__.py
new file mode 100644
index 0000000..bb4612b
--- /dev/null
+++ b/src/agentscope/app/rag/index_worker/__init__.py
@@ -0,0 +1,198 @@
+# -*- coding: utf-8 -*-
+"""Out-of-process index worker entry point.
+
+A worker process owns:
+
+- a :class:`~agentscope.app._service.IndexWorker` instance, which
+  runs the parse → chunk → embed pipeline for one document at a time;
+- an :class:`~agentscope.app._service.IndexTaskConsumer`, which
+  subscribes to the shared task channel on the message bus and
+  feeds the worker.
+
+It does NOT own the sweeper — the API process keeps running the
+sweeper so that documents stuck in ``pending`` (because the API
+crashed between the storage write and the dispatcher publish) still
+recover, even if every worker process happens to be offline at the
+moment the publish was attempted.
+
+This module is a library: a deployment wires its concrete backends
+through :func:`run_worker` from whatever bootstrap script it uses
+(systemd unit, Kubernetes Deployment + container entrypoint,
+docker-compose ``command``, ...). The shape mirrors
+:func:`agentscope.app.create_app` — pass already-constructed
+backend instances, the worker manages their lifecycle through an
+:class:`AsyncExitStack`.
+
+Example::
+
+    import asyncio
+    import socket
+    import uuid
+
+    from agentscope.app.rag.blob_store import S3BlobStore
+    from agentscope.app.rag.knowledge_base_manager import (
+        DefaultKnowledgeBaseManager,
+    )
+    from agentscope.app.message_bus import RedisMessageBus
+    from agentscope.app.storage import RedisStorage
+    from agentscope.app.rag.index_worker import run_worker
+    from agentscope.rag import ApproxTokenChunker, TextParser, ...
+
+    async def main() -> None:
+        storage = RedisStorage(url=os.environ["REDIS_URL"])
+        message_bus = RedisMessageBus(url=os.environ["REDIS_URL"])
+        blob_store = S3BlobStore(
+            bucket=os.environ["S3_BUCKET"],
+            endpoint_url=os.environ.get("S3_ENDPOINT"),
+        )
+        kb_manager = DefaultKnowledgeBaseManager(...)
+        parsers = [TextParser()]
+        chunker = ApproxTokenChunker()
+        await run_worker(
+            storage=storage,
+            message_bus=message_bus,
+            blob_store=blob_store,
+            knowledge_base_manager=kb_manager,
+            parsers=parsers,
+            chunker=chunker,
+        )
+
+    if __name__ == "__main__":
+        asyncio.run(main())
+"""
+import asyncio
+import signal
+import socket
+import uuid
+from concurrent.futures import ProcessPoolExecutor
+from contextlib import AsyncExitStack
+from typing import TYPE_CHECKING
+
+from ..._service import IndexTaskConsumer, IndexWorker
+from ...._logging import logger
+
+if TYPE_CHECKING:
+    from ..blob_store import BlobStoreBase
+    from ..knowledge_base_manager import KnowledgeBaseManagerBase
+    from ...message_bus import MessageBus
+    from ...storage import StorageBase
+    from ....rag import ChunkerBase, ParserBase
+
+
+async def run_worker(
+    *,
+    storage: "StorageBase",
+    message_bus: "MessageBus",
+    blob_store: "BlobStoreBase",
+    knowledge_base_manager: "KnowledgeBaseManagerBase",
+    parsers: "list[ParserBase] | dict[str, ParserBase]",
+    chunker: "ChunkerBase",
+    node_id: str | None = None,
+    worker_max_concurrency: int = 4,
+    consumer_max_batch: int = 32,
+    parser_executor: ProcessPoolExecutor | None = None,
+) -> None:
+    """Run the out-of-process index worker until cancelled.
+
+    Manages the lifecycle of every passed-in backend through a single
+    :class:`AsyncExitStack`. The function returns when SIGINT or
+    SIGTERM is delivered (deployment-controlled shutdown).
+
+    Args:
+        storage (`StorageBase`):
+            Persistent storage backend. Lifecycle managed here.
+        message_bus (`MessageBus`):
+            Live message bus subscribed to for index-task signals.
+            Lifecycle managed here.
+        blob_store (`BlobStoreBase`):
+            Backend the worker reads document bytes from. Lifecycle
+            managed here.
+        knowledge_base_manager (`KnowledgeBaseManagerBase`):
+            Resolves :class:`KnowledgeBase` runtimes for embedding +
+            vector store writes. Lifecycle managed here.
+        parsers (`list[ParserBase] | dict[str, ParserBase]`):
+            Parsers used to dispatch uploads by IANA media type.
+            Pass the same registry both to ``create_app`` and to the
+            worker — list mode expands each parser's
+            ``supported_media_types`` (later entries override earlier
+            ones, with a warning); dict mode is used verbatim for
+            explicit routing.
+        chunker (`ChunkerBase`):
+            Shared chunker.
+        node_id (`str | None`, optional):
+            Stable identifier for this worker process used on the
+            storage lease. Defaults to
+            ``"{hostname}:{uuid-prefix}"`` — good enough for
+            distinguishing two workers running on the same host;
+            override when your orchestrator has a more meaningful
+            id (Kubernetes pod name, ECS task id, ...).
+        worker_max_concurrency (`int`, defaults to ``4``):
+            Maximum number of documents the worker processes
+            concurrently. See
+            :class:`~agentscope.app._service.IndexWorker`.
+        consumer_max_batch (`int`, defaults to ``32``):
+            Maximum entries the consumer drains per signal. See
+            :class:`~agentscope.app._service.IndexTaskConsumer`.
+        parser_executor (`ProcessPoolExecutor | None`, optional):
+            Process pool for CPU-bound parses. ``None`` runs parses
+            inline (fine for text-only deployments).
+    """
+    resolved_node_id = (
+        node_id or f"{socket.gethostname()}:{uuid.uuid4().hex[:8]}"
+    )
+
+    async with AsyncExitStack() as stack:
+        await stack.enter_async_context(storage)
+        await stack.enter_async_context(message_bus)
+        await stack.enter_async_context(blob_store)
+        await stack.enter_async_context(knowledge_base_manager)
+
+        worker = IndexWorker(
+            storage=storage,
+            blob_store=blob_store,
+            knowledge_base_manager=knowledge_base_manager,
+            parsers=parsers,
+            chunker=chunker,
+            node_id=resolved_node_id,
+            max_concurrency=worker_max_concurrency,
+            parser_executor=parser_executor,
+        )
+        await stack.enter_async_context(
+            IndexTaskConsumer(
+                message_bus=message_bus,
+                worker=worker,
+                max_batch=consumer_max_batch,
+            ),
+        )
+
+        logger.info(
+            "Index worker %s ready (max_concurrency=%d, max_batch=%d)",
+            resolved_node_id,
+            worker_max_concurrency,
+            consumer_max_batch,
+        )
+
+        # Block until a signal arrives. We install handlers on the
+        # running loop rather than using ``signal.signal`` so the
+        # interaction with asyncio is well-defined (the default
+        # handler would raise KeyboardInterrupt at an arbitrary
+        # await point, which is awkward to clean up).
+        loop = asyncio.get_running_loop()
+        stop = loop.create_future()
+
+        def _request_stop() -> None:
+            if not stop.done():
+                stop.set_result(None)
+
+        for sig in (signal.SIGINT, signal.SIGTERM):
+            try:
+                loop.add_signal_handler(sig, _request_stop)
+            except NotImplementedError:
+                # Windows event loop does not implement add_signal_handler;
+                # tests and Linux/macOS deployments are unaffected.
+                pass
+
+        try:
+            await stop
+        finally:
+            logger.info("Index worker %s shutting down", resolved_node_id)
diff --git a/src/agentscope/app/rag/index_worker/__main__.py b/src/agentscope/app/rag/index_worker/__main__.py
new file mode 100644
index 0000000..8053912
--- /dev/null
+++ b/src/agentscope/app/rag/index_worker/__main__.py
@@ -0,0 +1,108 @@
+# -*- coding: utf-8 -*-
+"""Entry point for ``python -m agentscope.app.rag.index_worker``.
+
+Resolves a deployment-supplied bootstrap callable from the
+``AGENTSCOPE_WORKER_BOOTSTRAP`` environment variable, calls it to
+obtain the concrete backends, and hands them to :func:`run_worker`.
+
+The deployment owns the bootstrap because backend selection is a
+deployment concern — there is no one-size-fits-all storage,
+message bus, or blob store. The bootstrap must be importable, must
+take no arguments, and must return a dict whose keys match
+:func:`run_worker`'s keyword arguments.
+
+Example bootstrap (``mydeploy/worker_bootstrap.py``)::
+
+    import os
+
+    from agentscope.app.rag.blob_store import S3BlobStore
+    from agentscope.app.rag.knowledge_base_manager import (
+        DefaultKnowledgeBaseManager,
+    )
+    from agentscope.app.message_bus import RedisMessageBus
+    from agentscope.app.storage import RedisStorage
+    from agentscope.rag import ApproxTokenChunker, TextParser
+
+    def bootstrap() -> dict:
+        return {
+            "storage": RedisStorage(url=os.environ["REDIS_URL"]),
+            "message_bus": RedisMessageBus(url=os.environ["REDIS_URL"]),
+            "blob_store": S3BlobStore(
+                bucket=os.environ["S3_BUCKET"],
+                endpoint_url=os.environ.get("S3_ENDPOINT"),
+            ),
+            "knowledge_base_manager": DefaultKnowledgeBaseManager(...),
+            "parsers": [TextParser()],
+            "chunker": ApproxTokenChunker(),
+        }
+
+And launch::
+
+    AGENTSCOPE_WORKER_BOOTSTRAP=mydeploy.worker_bootstrap:bootstrap \\
+        python -m agentscope.app.rag.index_worker
+"""
+import asyncio
+import importlib
+import logging
+import os
+import sys
+from typing import Any, Callable
+
+from . import run_worker
+
+
+def _resolve(dotted: str) -> Callable[[], dict[str, Any]]:
+    """Import ``module:attribute`` and return the attribute.
+
+    Args:
+        dotted (`str`):
+            A ``module:attribute`` reference; must contain a colon.
+
+    Returns:
+        `Callable[[], dict[str, Any]]`:
+            The resolved attribute — expected to be a zero-arg
+            callable that returns the kwargs dict for
+            :func:`run_worker`.
+
+    Raises:
+        `ValueError`:
+            When ``dotted`` does not contain a colon.
+    """
+    if ":" not in dotted:
+        raise ValueError(
+            f"AGENTSCOPE_WORKER_BOOTSTRAP must be in 'module:attr' "
+            f"form, got {dotted!r}.",
+        )
+    module_name, _, attr = dotted.partition(":")
+    module = importlib.import_module(module_name)
+    return getattr(module, attr)
+
+
+def main() -> None:
+    """Resolve the bootstrap callable from the environment and run the worker.
+
+    Reads ``AGENTSCOPE_WORKER_BOOTSTRAP`` (``module:attr`` form),
+    imports the target, calls it for the kwargs dict, and forwards
+    them to :func:`run_worker`.  Exits with code ``2`` when the
+    environment variable is missing — the deployment must supply it
+    because backend selection is a deployment concern.
+    """
+    logging.basicConfig(
+        level=os.environ.get("LOG_LEVEL", "INFO"),
+        format="%(asctime)s %(levelname)s %(name)s %(message)s",
+    )
+    bootstrap_path = os.environ.get("AGENTSCOPE_WORKER_BOOTSTRAP")
+    if not bootstrap_path:
+        sys.stderr.write(
+            "AGENTSCOPE_WORKER_BOOTSTRAP is required — set it to "
+            "'package.module:callable' that returns a kwargs dict for "
+            "run_worker.\n",
+        )
+        sys.exit(2)
+    factory = _resolve(bootstrap_path)
+    kwargs = factory()
+    asyncio.run(run_worker(**kwargs))
+
+
+if __name__ == "__main__":
+    main()
diff --git a/src/agentscope/app/rag/knowledge_base_manager/__init__.py b/src/agentscope/app/rag/knowledge_base_manager/__init__.py
new file mode 100644
index 0000000..3ed9f77
--- /dev/null
+++ b/src/agentscope/app/rag/knowledge_base_manager/__init__.py
@@ -0,0 +1,33 @@
+# -*- coding: utf-8 -*-
+"""Knowledge base manager classes.
+
+The manager owns the lifecycle of knowledge bases:
+
+- creation / deletion / listing of :class:`KnowledgeBaseRecord` rows,
+- allocation / drop of the matching vector store storage,
+- construction of :class:`~agentscope.rag.KnowledgeBase` runtime handles
+  used by both the HTTP service and the agent runtime.
+
+The MVP ships a single isolation strategy
+(:class:`CollectionPerKbManager`); future strategies will live
+alongside it.
+"""
+
+from ._base import KnowledgeBaseManagerBase
+from ._collection_per_kb import CollectionPerKbManager
+from ._dimension_policy import DimensionPolicy, DimensionPolicyKind
+from ._errors import (
+    DimensionPolicyError,
+    KnowledgeBaseError,
+    KnowledgeBaseNotFoundError,
+)
+
+__all__ = [
+    "CollectionPerKbManager",
+    "DimensionPolicy",
+    "DimensionPolicyError",
+    "DimensionPolicyKind",
+    "KnowledgeBaseError",
+    "KnowledgeBaseManagerBase",
+    "KnowledgeBaseNotFoundError",
+]
diff --git a/src/agentscope/app/rag/knowledge_base_manager/_base.py b/src/agentscope/app/rag/knowledge_base_manager/_base.py
new file mode 100644
index 0000000..d3557a2
--- /dev/null
+++ b/src/agentscope/app/rag/knowledge_base_manager/_base.py
@@ -0,0 +1,302 @@
+# -*- coding: utf-8 -*-
+"""Abstract knowledge base manager.
+
+The manager is the **lifecycle owner** of knowledge bases:
+
+- it creates / lists / deletes :class:`KnowledgeBaseRecord` rows in
+  storage,
+- it allocates / drops the matching vector store collections,
+- it resolves an embedding model from the record's credential and
+  hands a ready-to-use :class:`KnowledgeBase` runtime back to callers.
+
+Different subclasses encode different *isolation strategies*: one
+collection per knowledge base, a single shared collection scoped by
+metadata, native VDB namespaces, etc.  All of them share the same
+:class:`KnowledgeBaseManagerBase` interface so the rest of the
+application can stay strategy-agnostic.
+
+The manager is created once at application startup and stored on
+``app.state.knowledge_base_manager``.  See
+:func:`~agentscope.app.create_app` for the wiring.
+"""
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Self
+
+from ._dimension_policy import DimensionPolicy
+
+if TYPE_CHECKING:
+    from types import TracebackType
+
+    from ...storage import (
+        EmbeddingModelConfig,
+        KnowledgeBaseRecord,
+        StorageBase,
+    )
+    from ....rag import KnowledgeBase, VectorStoreBase
+
+
+class KnowledgeBaseManagerBase(ABC):
+    """Abstract base for knowledge base managers.
+
+    Subclasses implement a specific isolation strategy by overriding
+    :meth:`create_knowledge_base`, :meth:`delete_knowledge_base`, and
+    :meth:`get_knowledge`.  The bookkeeping methods
+    (:meth:`get_knowledge_base`, :meth:`list_knowledge_bases`) have
+    default implementations that delegate to the bound storage.
+    """
+
+    def __init__(
+        self,
+        storage: "StorageBase",
+        vector_store: "VectorStoreBase",
+    ) -> None:
+        """Initialize the manager.
+
+        Args:
+            storage (`StorageBase`):
+                The application-wide storage backend used to persist
+                :class:`KnowledgeBaseRecord` rows and resolve
+                credentials.
+            vector_store (`VectorStoreBase`):
+                The application-wide vector store instance shared by
+                every knowledge base allocated by this manager.
+        """
+        self._storage = storage
+        self._vector_store = vector_store
+
+    # ------------------------------------------------------------------
+    # Lifecycle hooks
+    # ------------------------------------------------------------------
+
+    async def __aenter__(self) -> Self:
+        """Enter the manager's lifetime.
+
+        Enters the bound vector store's async context so a single
+        ``create_app`` parameter (the manager) covers the vector store's
+        lifecycle too. Subclasses that override this MUST call
+        ``await super().__aenter__()`` first to keep the vector store
+        ready before subclass-specific setup runs.
+        """
+        await self._vector_store.__aenter__()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: "TracebackType | None",
+    ) -> None:
+        """Exit the manager's lifetime, releasing the vector store.
+
+        Args:
+            exc_type (`type[BaseException] | None`):
+                The exception type raised inside the with-block, if any.
+            exc (`BaseException | None`):
+                The exception instance raised inside the with-block,
+                if any.
+            tb (`TracebackType | None`):
+                The traceback for the raised exception, if any.
+        """
+        await self._vector_store.__aexit__(exc_type, exc, tb)
+
+    # ------------------------------------------------------------------
+    # Capability discovery
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    async def get_dimension_policy(self) -> DimensionPolicy:
+        """Return the embedding-dimension policy this manager enforces.
+
+        Surfaced over HTTP so the front-end can soft-filter
+        incompatible models / dimensions before submission and show a
+        helpful banner.
+
+        Returns:
+            `DimensionPolicy`:
+                The current dimension policy.
+        """
+
+    # ------------------------------------------------------------------
+    # CRUD
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    async def create_knowledge_base(
+        self,
+        user_id: str,
+        name: str,
+        description: str,
+        embedding_model_config: "EmbeddingModelConfig",
+    ) -> "KnowledgeBaseRecord":
+        """Create a new knowledge base for the given user.
+
+        Implementations must:
+
+        1. validate ``embedding_model_config.dimensions`` against
+           :meth:`get_dimension_policy`;
+        2. allocate the vector store collection (or namespace) the
+           strategy uses;
+        3. persist a :class:`KnowledgeBaseRecord` and return it.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+            name (`str`):
+                Display name.
+            description (`str`):
+                Free-form description.
+            embedding_model_config (`EmbeddingModelConfig`):
+                Embedding model configuration; pinned to the record.
+
+        Returns:
+            `KnowledgeBaseRecord`:
+                The newly persisted record.
+
+        Raises:
+            `DimensionPolicyError`:
+                If the requested dimension violates the manager's
+                dimension policy.
+        """
+
+    async def get_knowledge_base(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+    ) -> "KnowledgeBaseRecord | None":
+        """Fetch a knowledge base record by id (delegates to storage).
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+            knowledge_base_id (`str`):
+                The knowledge base id.
+
+        Returns:
+            `KnowledgeBaseRecord | None`:
+                The record, or ``None`` if not found / not owned by
+                the user.
+        """
+        return await self._storage.get_knowledge_base(
+            user_id,
+            knowledge_base_id,
+        )
+
+    async def list_knowledge_bases(
+        self,
+        user_id: str,
+    ) -> "list[KnowledgeBaseRecord]":
+        """List all knowledge base records owned by the given user.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+
+        Returns:
+            `list[KnowledgeBaseRecord]`:
+                All knowledge base records belonging to the user.
+        """
+        return await self._storage.list_knowledge_bases(user_id)
+
+    async def update_knowledge_base(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+        name: str | None = None,
+        description: str | None = None,
+    ) -> "KnowledgeBaseRecord | None":
+        """Update mutable fields on an existing knowledge base record.
+
+        Only ``name`` and ``description`` are mutable.  The embedding
+        model configuration and the underlying collection are pinned
+        for the lifetime of the record because changing either would
+        invalidate every previously inserted vector.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+            knowledge_base_id (`str`):
+                The knowledge base id.
+            name (`str | None`, optional):
+                New display name; ``None`` leaves the name unchanged.
+            description (`str | None`, optional):
+                New description; ``None`` leaves the description
+                unchanged.
+
+        Returns:
+            `KnowledgeBaseRecord | None`:
+                The updated record, or ``None`` if the record was not
+                found / not owned by the user.
+        """
+        record = await self._storage.get_knowledge_base(
+            user_id,
+            knowledge_base_id,
+        )
+        if record is None:
+            return None
+        if name is not None:
+            record.name = name
+        if description is not None:
+            record.description = description
+        return await self._storage.upsert_knowledge_base(user_id, record)
+
+    @abstractmethod
+    async def delete_knowledge_base(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+    ) -> bool:
+        """Delete a knowledge base record and its underlying storage.
+
+        Implementations must:
+
+        1. authorise the call by looking the record up first;
+        2. drop the vector store collection (or scope) the strategy
+           uses;
+        3. remove the :class:`KnowledgeBaseRecord` from storage.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+            knowledge_base_id (`str`):
+                The id of the knowledge base to delete.
+
+        Returns:
+            `bool`:
+                ``True`` if the record existed and was deleted,
+                ``False`` if it was not found.
+        """
+
+    # ------------------------------------------------------------------
+    # KnowledgeBase runtime
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    async def get_knowledge(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+    ) -> "KnowledgeBase":
+        """Resolve a runtime :class:`KnowledgeBase` handle for one KB.
+
+        Implementations are responsible for:
+
+        - looking the record up in storage (authorisation);
+        - resolving the embedding model from the record's credential;
+        - constructing the :class:`KnowledgeBase` with the strategy's
+          collection name and metadata filter.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+            knowledge_base_id (`str`):
+                The knowledge base id.
+
+        Returns:
+            `KnowledgeBase`:
+                A runtime handle bound to this knowledge base.
+
+        Raises:
+            `KnowledgeBaseNotFoundError`:
+                If the record does not exist or does not belong to
+                the authenticated user.
+        """
diff --git a/src/agentscope/app/rag/knowledge_base_manager/_collection_per_kb.py b/src/agentscope/app/rag/knowledge_base_manager/_collection_per_kb.py
new file mode 100644
index 0000000..34f033b
--- /dev/null
+++ b/src/agentscope/app/rag/knowledge_base_manager/_collection_per_kb.py
@@ -0,0 +1,202 @@
+# -*- coding: utf-8 -*-
+"""Collection-per-knowledge-base isolation strategy.
+
+The simplest correct implementation: every knowledge base gets its own
+vector store collection sized to the chosen embedding model.  No
+cross-KB co-location, no namespace gymnastics — collection names are
+the isolation key.
+
+Because each knowledge base owns its collection outright, the
+dimension policy reported by this manager is always
+:attr:`DimensionPolicyKind.ANY`: the user is free to pick any
+dimension supported by their embedding model.
+
+The collection name is generated as ``kb_<uuid_hex>`` (no user id is
+encoded, since storage does the user-scoped authorisation).
+"""
+from typing import TYPE_CHECKING
+
+from ._base import KnowledgeBaseManagerBase
+from ._dimension_policy import DimensionPolicy, DimensionPolicyKind
+from ._errors import KnowledgeBaseNotFoundError
+from ...._logging import logger
+from ....rag import KnowledgeBase
+from ..._service._embedding import build_embedding_model
+from ...storage import KnowledgeBaseRecord
+
+if TYPE_CHECKING:
+    from ...storage import EmbeddingModelConfig
+
+
+class CollectionPerKbManager(KnowledgeBaseManagerBase):
+    """One-collection-per-KB knowledge base manager.
+
+    Each knowledge base maps to one collection in the bound
+    :class:`~agentscope.rag.VectorStoreBase`.  The collection is
+    created at :meth:`create_knowledge_base` time and dropped at
+    :meth:`delete_knowledge_base` time.
+    """
+
+    async def get_dimension_policy(self) -> DimensionPolicy:
+        """Return :attr:`DimensionPolicyKind.ANY` — every KB picks freely.
+
+        Returns:
+            `DimensionPolicy`:
+                The dimension policy ``(ANY, None)``.
+        """
+        return DimensionPolicy(
+            kind=DimensionPolicyKind.ANY,
+            dimension=None,
+        )
+
+    async def create_knowledge_base(
+        self,
+        user_id: str,
+        name: str,
+        description: str,
+        embedding_model_config: "EmbeddingModelConfig",
+    ) -> KnowledgeBaseRecord:
+        """Allocate a new collection and persist the knowledge base record.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+            name (`str`):
+                Display name.
+            description (`str`):
+                Free-form description.
+            embedding_model_config (`EmbeddingModelConfig`):
+                Embedding model configuration; pinned to the record.
+
+        Returns:
+            `KnowledgeBaseRecord`:
+                The newly persisted record.
+        """
+        record = KnowledgeBaseRecord(
+            user_id=user_id,
+            name=name,
+            description=description,
+            embedding_model_config=embedding_model_config,
+            collection_name="",
+        )
+        record.collection_name = f"kb_{record.id}"
+
+        await self._vector_store.create_collection(
+            name=record.collection_name,
+            dimensions=embedding_model_config.dimensions,
+        )
+        try:
+            return await self._storage.upsert_knowledge_base(user_id, record)
+        except Exception:
+            # Compensating delete must not shadow the original exception:
+            # if the delete itself raises, the caller would be misdirected
+            # to investigate the wrong error and the orphan collection
+            # would leave no trace.
+            try:
+                await self._vector_store.delete_collection(
+                    record.collection_name,
+                )
+            except Exception:  # noqa: BLE001 — best-effort cleanup
+                logger.exception(
+                    "Failed to drop orphan collection %r after "
+                    "upsert_knowledge_base failed; collection leaked.",
+                    record.collection_name,
+                )
+            raise
+
+    async def delete_knowledge_base(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+    ) -> bool:
+        """Drop the underlying collection and remove the record.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+            knowledge_base_id (`str`):
+                The id of the knowledge base to delete.
+
+        Returns:
+            `bool`:
+                ``True`` if the record existed and was deleted,
+                ``False`` if it was not found.
+        """
+        record = await self._storage.get_knowledge_base(
+            user_id,
+            knowledge_base_id,
+        )
+        if record is None:
+            return False
+
+        if await self._vector_store.has_collection(record.collection_name):
+            await self._vector_store.delete_collection(record.collection_name)
+        return await self._storage.delete_knowledge_base(
+            user_id,
+            knowledge_base_id,
+        )
+
+    async def get_knowledge(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+    ) -> KnowledgeBase:
+        """Resolve a :class:`KnowledgeBase` runtime for one knowledge base.
+
+        Looks the record up in storage (raising
+        :class:`KnowledgeBaseNotFoundError` for unknown / un-owned
+        ids), constructs the embedding model from the pinned
+        credential, and returns a ready-to-use handle bound to the
+        record's collection.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+            knowledge_base_id (`str`):
+                The knowledge base id.
+
+        Returns:
+            `KnowledgeBase`:
+                A runtime handle bound to this knowledge base.
+
+        Raises:
+            `KnowledgeBaseNotFoundError`:
+                If the record does not exist or does not belong to
+                the authenticated user.
+        """
+        record = await self._storage.get_knowledge_base(
+            user_id,
+            knowledge_base_id,
+        )
+        if record is None:
+            raise KnowledgeBaseNotFoundError(
+                f"Knowledge base {knowledge_base_id!r} not found.",
+            )
+
+        # KB manager is an owner-internal path: the credential lives
+        # under the same owner as the knowledge base, so we read it
+        # directly from storage rather than routing through the access
+        # service (which is only relevant when the viewer differs from
+        # the owner).
+        credential_record = await self._storage.get_credential(
+            record.user_id,
+            record.embedding_model_config.credential_id,
+        )
+        if credential_record is None:
+            raise KnowledgeBaseNotFoundError(
+                f"Credential "
+                f"{record.embedding_model_config.credential_id!r} for "
+                f"knowledge base {knowledge_base_id!r} not found.",
+            )
+        embedding_model = build_embedding_model(
+            credential_record=credential_record,
+            config=record.embedding_model_config,
+        )
+        return KnowledgeBase(
+            name=record.name,
+            description=record.description,
+            embedding_model=embedding_model,
+            vector_store=self._vector_store,
+            collection=record.collection_name,
+            metadata_filter=None,
+        )
diff --git a/src/agentscope/app/rag/knowledge_base_manager/_dimension_policy.py b/src/agentscope/app/rag/knowledge_base_manager/_dimension_policy.py
new file mode 100644
index 0000000..d83c6fe
--- /dev/null
+++ b/src/agentscope/app/rag/knowledge_base_manager/_dimension_policy.py
@@ -0,0 +1,154 @@
+# -*- coding: utf-8 -*-
+"""Dimension policy advertised by a knowledge base manager.
+
+The policy tells the front-end which embedding-model dimensions are
+acceptable when creating a new knowledge base.  It is the *capability*
+side of the contract; the server still hard-validates every create
+call against the same rules.
+
+Three kinds are modelled:
+
+- ``ANY`` — any positive dimension is acceptable.  The user picks
+  freely from the list of supported dimensions on the chosen
+  embedding model card.  This is the case for one-collection-per-KB
+  isolation strategies.
+- ``FIXED`` — the dimension is fixed by the server (e.g. a single
+  shared collection sized to a specific dimension).  The front-end
+  hides incompatible models / dimensions.
+- ``LOCKED_BY_EXISTING`` — semantically identical to ``FIXED`` from
+  the front-end's perspective, but communicates *why* the dimension
+  is fixed: a previously created knowledge base in the same shared
+  collection has pinned it.
+"""
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel, Field, model_validator
+
+if TYPE_CHECKING:
+    from ....embedding import EmbeddingModelCard
+
+
+class DimensionPolicyKind(str, Enum):
+    """The kind of dimension policy the manager publishes."""
+
+    ANY = "any"
+    """Any positive dimension is acceptable.
+
+    Used by isolation strategies that allocate a fresh collection per
+    knowledge base (each one sized to its own embedding model)."""
+
+    FIXED = "fixed"
+    """A specific dimension is required by the manager configuration.
+
+    Used by isolation strategies that share a single collection across
+    knowledge bases — every record must agree on the dimension."""
+
+    LOCKED_BY_EXISTING = "locked_by_existing"
+    """A specific dimension was locked in by a previously created
+    knowledge base.
+
+    Identical to ``FIXED`` for clients; the distinction lets the UI
+    show *why* the dimension is fixed (e.g. "the first KB pinned the
+    dimension to 768 — switch isolation strategy to use 1536").
+    """
+
+
+class DimensionPolicy(BaseModel):
+    """The dimension policy a manager exposes to the front-end."""
+
+    kind: DimensionPolicyKind = Field(
+        description="What constraint applies to the chosen dimension.",
+    )
+    """The kind of constraint."""
+
+    dimension: int | None = Field(
+        default=None,
+        description=(
+            "The required dimension when ``kind`` is ``FIXED`` or "
+            "``LOCKED_BY_EXISTING``.  Always ``None`` for ``ANY``."
+        ),
+    )
+    """The required dimension, or ``None`` when any dimension is fine."""
+
+    @model_validator(mode="after")
+    def _enforce_kind_dimension_invariant(self) -> "DimensionPolicy":
+        """Reject states like ``ANY + dimension=768`` or ``FIXED + None``.
+
+        Without this guard, downstream code silently produces wrong
+        results (``ANY`` ignores a stray dimension) or crashes
+        (``FIXED`` with ``None`` makes ``filter_card`` raise
+        ``TypeError`` on ``target not in card.supported_dimensions``).
+        """
+        if self.kind is DimensionPolicyKind.ANY:
+            if self.dimension is not None:
+                raise ValueError(
+                    "DimensionPolicy: kind=ANY requires dimension=None, "
+                    f"got dimension={self.dimension!r}.",
+                )
+        else:
+            if self.dimension is None or self.dimension <= 0:
+                raise ValueError(
+                    f"DimensionPolicy: kind={self.kind.value} requires a "
+                    f"positive dimension, got dimension={self.dimension!r}.",
+                )
+        return self
+
+    def accepts(self, dimensions: int) -> bool:
+        """Check whether a candidate dimension satisfies this policy.
+
+        Args:
+            dimensions (`int`):
+                The candidate output dimension.
+
+        Returns:
+            `bool`:
+                ``True`` if the dimension is acceptable.
+        """
+        if self.kind is DimensionPolicyKind.ANY:
+            return dimensions > 0
+        return dimensions == self.dimension
+
+    def filter_card(
+        self,
+        card: "EmbeddingModelCard",
+    ) -> "EmbeddingModelCard | None":
+        """Project an embedding model card through this policy.
+
+        Used by the knowledge base router to pre-filter the embedding
+        model catalogue exposed at KB-creation time:
+
+        - ``ANY`` returns the card unchanged.
+        - ``FIXED`` / ``LOCKED_BY_EXISTING``:
+
+          - fixed-dim cards (``supported_dimensions is None``) are
+            kept iff their default ``dimensions`` matches the locked
+            value;
+          - matryoshka cards are kept iff the locked dimension is in
+            ``supported_dimensions``, and a copy is returned with
+            ``supported_dimensions`` narrowed to the locked value and
+            ``dimensions`` set accordingly.  This guarantees the
+            front-end cannot pick an incompatible dimension.
+
+        Args:
+            card (`EmbeddingModelCard`):
+                The candidate embedding model card.
+
+        Returns:
+            `EmbeddingModelCard | None`:
+                The (possibly narrowed) card, or ``None`` if the card
+                cannot satisfy this policy.
+        """
+        if self.kind is DimensionPolicyKind.ANY:
+            return card
+        target = self.dimension
+        if card.supported_dimensions is None:
+            return card if card.dimensions == target else None
+        if target not in card.supported_dimensions:
+            return None
+        return card.model_copy(
+            update={
+                "dimensions": target,
+                "supported_dimensions": [target],
+            },
+        )
diff --git a/src/agentscope/app/rag/knowledge_base_manager/_errors.py b/src/agentscope/app/rag/knowledge_base_manager/_errors.py
new file mode 100644
index 0000000..529f51f
--- /dev/null
+++ b/src/agentscope/app/rag/knowledge_base_manager/_errors.py
@@ -0,0 +1,59 @@
+# -*- coding: utf-8 -*-
+"""Knowledge base manager exception hierarchy.
+
+The router maps each exception to an HTTP status code in
+:mod:`agentscope.app._router._knowledge_base`:
+
+- :class:`KnowledgeBaseNotFoundError` → ``404``
+- :class:`DimensionPolicyError`       → ``409``
+
+Keeping the mapping inside the router (and not raising
+``HTTPException`` from the manager) lets the same manager be reused by
+non-HTTP entry points (e.g. CLI tools, the agent middleware) without
+pulling in FastAPI.
+"""
+
+
+class KnowledgeBaseError(Exception):
+    """Base class for knowledge base manager errors."""
+
+
+class KnowledgeBaseNotFoundError(KnowledgeBaseError):
+    """Raised when a knowledge base record cannot be located.
+
+    The record is missing entirely, or it exists but does not belong
+    to the authenticated user.  The two are reported identically to
+    avoid leaking existence of other users' knowledge bases.
+    """
+
+
+class DimensionPolicyError(KnowledgeBaseError):
+    """Raised when a create-time embedding model violates the manager's
+    dimension policy.
+
+    Carries both the offending dimension and the manager's policy so
+    the router can surface a precise error message without having to
+    re-derive either side.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        requested_dimension: int,
+        policy_dimension: int | None,
+    ) -> None:
+        """Initialize the error.
+
+        Args:
+            message (`str`):
+                Human-readable error message.
+            requested_dimension (`int`):
+                The dimension the caller asked for.
+            policy_dimension (`int | None`):
+                The dimension the policy enforces, or ``None`` if the
+                policy admits any dimension.
+        """
+        super().__init__(message)
+        self.requested_dimension = requested_dimension
+        self.policy_dimension = policy_dimension
diff --git a/src/agentscope/app/storage/__init__.py b/src/agentscope/app/storage/__init__.py
new file mode 100644
index 0000000..661203f
--- /dev/null
+++ b/src/agentscope/app/storage/__init__.py
@@ -0,0 +1,57 @@
+# -*- coding: utf-8 -*-
+"""The storage module in agentscope."""
+
+from ._base import StorageBase
+from ._redis_storage import RedisStorage
+from ._model import (
+    AgentData,
+    AgentRecord,
+    CredentialRecord,
+    KnowledgeBaseRecord,
+    KnowledgeDocumentData,
+    KnowledgeDocumentRecord,
+    KnowledgeDocumentStatus,
+    ScheduleData,
+    ScheduleRecord,
+    ScheduleSource,
+    SessionConfig,
+    SessionKnowledgeConfig,
+    SessionRecord,
+    SessionSource,
+    ChatModelConfig,
+    TTSModelConfig,
+    EmbeddingModelConfig,
+    TeamData,
+    TeamRecord,
+    UserRecord,
+    TeamMember,
+    InviteConfig,
+)
+
+__all__ = [
+    "StorageBase",
+    "RedisStorage",
+    # The ORM models
+    "InviteConfig",
+    "AgentData",
+    "AgentRecord",
+    "CredentialRecord",
+    "KnowledgeBaseRecord",
+    "KnowledgeDocumentData",
+    "KnowledgeDocumentRecord",
+    "KnowledgeDocumentStatus",
+    "SessionConfig",
+    "SessionKnowledgeConfig",
+    "SessionRecord",
+    "SessionSource",
+    "ChatModelConfig",
+    "TTSModelConfig",
+    "EmbeddingModelConfig",
+    "TeamMember",
+    "TeamData",
+    "TeamRecord",
+    "UserRecord",
+    "ScheduleData",
+    "ScheduleRecord",
+    "ScheduleSource",
+]
diff --git a/src/agentscope/app/storage/_base.py b/src/agentscope/app/storage/_base.py
new file mode 100644
index 0000000..6c5b944
--- /dev/null
+++ b/src/agentscope/app/storage/_base.py
@@ -0,0 +1,920 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=too-many-public-methods
+"""The storage base class."""
+from abc import ABC, abstractmethod
+from datetime import datetime, timedelta
+from typing import Any, Self
+
+
+from ._model import (
+    AgentRecord,
+    CredentialRecord,
+    KnowledgeBaseRecord,
+    KnowledgeDocumentRecord,
+    KnowledgeDocumentStatus,
+    ScheduleRecord,
+    SessionRecord,
+    SessionConfig,
+    SessionSource,
+    TeamRecord,
+)
+from ...credential import CredentialBase
+from ...message import Msg
+from ...state import AgentState
+
+
+class StorageBase(ABC):
+    """The storage abstract base class."""
+
+    async def __aenter__(self) -> Self:
+        """Start the storage backend (open connection pool, etc.)."""
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: Any,
+    ) -> None:
+        """Shut down the storage backend."""
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        """Release underlying connection resources. Default is a no-op."""
+
+    @abstractmethod
+    async def upsert_credential(
+        self,
+        user_id: str,
+        credential_data: CredentialBase,
+    ) -> str:
+        """Create or update a credential in the storage.
+
+        Args:
+            user_id (`str`):
+                The user id.
+            credential_data (`CredentialBase`):
+                The credential data.
+
+        Returns:
+            `str`:
+                The credential id.
+        """
+
+    @abstractmethod
+    async def list_credentials(self, user_id: str) -> list[CredentialRecord]:
+        """List all credentials for a given user.
+
+        Args:
+            user_id (`str`):
+                The user id.
+
+        Returns:
+            `list[CredentialRecord]`:
+                List of all credentials for a given user.
+        """
+
+    @abstractmethod
+    async def get_credential(
+        self,
+        user_id: str,
+        credential_id: str,
+    ) -> CredentialRecord | None:
+        """Fetch a single credential record by id.
+
+        Args:
+            user_id (`str`): The owner user id.
+            credential_id (`str`): The credential id.
+
+        Returns:
+            `CredentialRecord | None`: The record, or ``None`` if not found.
+        """
+
+    @abstractmethod
+    async def delete_credential(
+        self,
+        user_id: str,
+        credential_id: str,
+    ) -> bool:
+        """Delete a credential.
+
+        Args:
+            user_id (`str`):
+                The user id.
+            credential_id (`str`):
+                The credential id.
+
+        Returns:
+            `bool`:
+                True if deleted, False if not found.
+        """
+
+    @abstractmethod
+    async def upsert_agent(
+        self,
+        user_id: str,
+        agent_record: AgentRecord,
+    ) -> str:
+        """Create an agent record in the storage.
+
+        Args:
+            user_id (`str`):
+                The user id.
+            agent_record (`AgentRecord`):
+                The agent record.
+
+        Returns:
+            `str`:
+                The agent id.
+        """
+
+    @abstractmethod
+    async def list_agents(self, user_id: str) -> list[AgentRecord]:
+        """List all agents for a given user.
+
+        Args:
+            user_id (`str`):
+                The user id.
+
+        Returns:
+            `list[AgentRecord]`:
+                List of all agents for a given user.
+        """
+
+    @abstractmethod
+    async def get_agent(
+        self,
+        user_id: str,
+        agent_id: str,
+    ) -> AgentRecord | None:
+        """Fetch a single agent record by id.
+
+        Args:
+            user_id (`str`): The owner user id.
+            agent_id (`str`): The agent id.
+
+        Returns:
+            `AgentRecord | None`: The record, or ``None`` if not found.
+        """
+
+    @abstractmethod
+    async def delete_agent(self, user_id: str, agent_id: str) -> bool:
+        """Delete an agent record.
+
+        Args:
+            user_id (`str`):
+                The user id.
+            agent_id (`str`):
+                The agent id.
+
+        Returns:
+            `bool`:
+                True if deleted, False if not found.
+        """
+
+    @abstractmethod
+    async def upsert_session(
+        self,
+        user_id: str,
+        agent_id: str,
+        config: SessionConfig,
+        state: AgentState | None = None,
+        session_id: str | None = None,
+        source: SessionSource = SessionSource.USER,
+        source_schedule_id: str | None = None,
+    ) -> SessionRecord:
+        """Create or update a session for a (user, agent) pair.
+
+        Args:
+            user_id (`str`): The owner user id.
+            agent_id (`str`): The agent id.
+            config (`SessionConfig`): Immutable session configuration
+                (model, workspace). Required on create; passed unchanged on
+                state-only updates.
+            state (`AgentState | None`, optional): Runtime state to persist.
+                Defaults to a fresh ``AgentState()`` when ``None``.
+            session_id (`str | None`, optional): If provided, update the
+                existing session with this id. If ``None``, create a new
+                session.
+            source (`SessionSource`, optional): The source that created this
+                session. Defaults to ``SessionSource.USER``.
+            source_schedule_id (`str | None`, optional): The schedule that
+                created this session. When set, the session is indexed under
+                the schedule for execution history queries.
+
+        Returns:
+            `SessionRecord`: The created or updated record.
+        """
+
+    @abstractmethod
+    async def set_session_team_id(
+        self,
+        user_id: str,
+        session_id: str,
+        team_id: str | None,
+    ) -> None:
+        """Set or clear ``team_id`` on an existing session record.
+
+        Bypasses :meth:`upsert_session` because that method does not
+        write ``team_id``. Used by team operations (create/dissolve/
+        leave) to keep the leader/worker → team relationship consistent.
+        Idempotent: a no-op if the session does not exist or already
+        holds the given value.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+            session_id (`str`):
+                The session whose ``team_id`` should be updated.
+            team_id (`str | None`):
+                The new value. ``None`` detaches the session from any
+                team.
+        """
+
+    @abstractmethod
+    async def update_session_state(
+        self,
+        user_id: str,
+        agent_id: str,
+        session_id: str,
+        state: AgentState,
+    ) -> None:
+        """Update only the mutable state of an existing session.
+
+        Convenience method for the hot path (post-chat-turn persistence).
+        Raises ``KeyError`` if the session does not exist.
+
+        Args:
+            user_id (`str`): The owner user id.
+            agent_id (`str`): The agent id.
+            session_id (`str`): The session id.
+            state (`AgentState`): The new agent state to persist.
+        """
+
+    @abstractmethod
+    async def list_sessions(
+        self,
+        user_id: str,
+        agent_id: str,
+    ) -> list[SessionRecord]:
+        """List all sessions for a given user and agent entity.
+
+        Args:
+            user_id (`str`): The user id.
+            agent_id (`str`): The agent id.
+
+        Returns:
+            `list[SessionRecord]`: List of all sessions for the (user, agent).
+        """
+
+    @abstractmethod
+    async def delete_session(
+        self,
+        user_id: str,
+        agent_id: str,
+        session_id: str,
+    ) -> bool:
+        """Delete a session.
+
+        Args:
+            user_id (`str`): The user id.
+            agent_id (`str`): The agent id.
+            session_id (`str`): The session id.
+
+        Returns:
+            `bool`: True if deleted, False if not found.
+        """
+
+    @abstractmethod
+    async def get_session(
+        self,
+        user_id: str,
+        agent_id: str,
+        session_id: str,
+    ) -> SessionRecord | None:
+        """Fetch a single session record by id.
+
+        Args:
+            user_id (`str`): The owner user id.
+            agent_id (`str`): The agent id.
+            session_id (`str`): The session id.
+
+        Returns:
+            `SessionRecord | None`: The record, or ``None`` if not found.
+        """
+
+    @abstractmethod
+    async def list_sessions_by_schedule(
+        self,
+        user_id: str,
+        schedule_id: str,
+    ) -> list[SessionRecord]:
+        """Return all sessions created by a given schedule.
+
+        Args:
+            user_id (`str`): The owner user id.
+            schedule_id (`str`): The schedule id.
+
+        Returns:
+            `list[SessionRecord]`: Sessions triggered by this schedule,
+            ordered by creation time (newest first).
+        """
+
+    @abstractmethod
+    async def upsert_schedule(
+        self,
+        user_id: str,
+        record: ScheduleRecord,
+    ) -> str:
+        """Persist a cron task record and register it in the user's index.
+
+        Args:
+            user_id (`str`): The owner user id.
+            record (`ScheduleRecord`): The fully-populated record to store.
+
+        Returns:
+            `str`: The id of the stored record.
+        """
+
+    @abstractmethod
+    async def get_schedule(
+        self,
+        user_id: str,
+        schedule_id: str,
+    ) -> ScheduleRecord | None:
+        """Fetch a single cron task record by id.
+
+        Args:
+            user_id (`str`): The owner user id.
+            schedule_id (`str`): The task id.
+
+        Returns:
+            `ScheduleRecord | None`: The record, or ``None`` if not found.
+        """
+
+    @abstractmethod
+    async def list_schedules(
+        self,
+        user_id: str,
+    ) -> list[ScheduleRecord]:
+        """Return all cron task records belonging to the given user.
+
+        Args:
+            user_id (`str`): The owner user id.
+
+        Returns:
+            `list[ScheduleRecord]`: All cron task records for the user.
+        """
+
+    @abstractmethod
+    async def delete_schedule(
+        self,
+        user_id: str,
+        schedule_id: str,
+    ) -> bool:
+        """Delete a cron task record and remove it from the user's index.
+
+        Args:
+            user_id (`str`): The owner user id.
+            schedule_id (`str`): The id of the task to delete.
+
+        Returns:
+            `bool`: ``True`` if deleted, ``False`` if not found.
+        """
+
+    @abstractmethod
+    async def list_all_schedules(self) -> list[ScheduleRecord]:
+        """Return every schedule record across all users.
+
+        Used on startup to restore the in-memory scheduler from persisted
+        state.  Normal per-user listing should use :meth:`list_schedules`.
+
+        Returns:
+            `list[ScheduleRecord]`: All schedule records in the store.
+        """
+
+    # ------------------------------------------------------------------
+    # Message persistence
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    async def upsert_message(
+        self,
+        user_id: str,
+        session_id: str,
+        msg: Msg,
+    ) -> None:
+        """Persist a message to the session's message list.
+
+        If the last message in the list has the same ``id`` as *msg*, it is
+        replaced (merge/overwrite for the same reply_id across continuation
+        calls).  Otherwise, *msg* is appended as a new entry.
+
+        Args:
+            user_id (`str`): The owner user id.
+            session_id (`str`): The session id.
+            msg (`Msg`): The message to persist.
+        """
+
+    @abstractmethod
+    async def get_message(
+        self,
+        user_id: str,
+        session_id: str,
+        message_id: str,
+    ) -> Msg | None:
+        """Fetch a single message by id from the session's message list.
+
+        Args:
+            user_id (`str`): The owner user id.
+            session_id (`str`): The session id.
+            message_id (`str`): The message id to look up.
+
+        Returns:
+            `Msg | None`: The message, or ``None`` if not found.
+        """
+
+    @abstractmethod
+    async def list_messages(
+        self,
+        user_id: str,
+        session_id: str,
+        offset: int = 0,
+        limit: int = 50,
+    ) -> list[Msg]:
+        """Return messages for a session with pagination.
+
+        Args:
+            user_id (`str`): The owner user id.
+            session_id (`str`): The session id.
+            offset (`int`): Starting index (0-based). Defaults to 0.
+            limit (`int`): Maximum number of messages to return.
+
+        Returns:
+            `list[Msg]`: Messages in chronological order.
+        """
+
+    # ------------------------------------------------------------------
+    # Team persistence
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    async def upsert_team(
+        self,
+        user_id: str,
+        record: TeamRecord,
+    ) -> TeamRecord:
+        """Create or update a team record.
+
+        Args:
+            user_id (`str`): The owner user id.
+            record (`TeamRecord`): The team record to persist. The record's
+                ``id`` is used as the primary key; if a record with the same
+                id already exists it is overwritten.
+
+        Returns:
+            `TeamRecord`: The stored record (with ``updated_at`` refreshed).
+        """
+
+    @abstractmethod
+    async def get_team(
+        self,
+        user_id: str,
+        team_id: str,
+    ) -> TeamRecord | None:
+        """Fetch a single team record by id.
+
+        Args:
+            user_id (`str`): The owner user id.
+            team_id (`str`): The team id.
+
+        Returns:
+            `TeamRecord | None`: The record, or ``None`` if not found.
+        """
+
+    @abstractmethod
+    async def list_teams(self, user_id: str) -> list[TeamRecord]:
+        """List all teams owned by a given user.
+
+        Args:
+            user_id (`str`): The user id.
+
+        Returns:
+            `list[TeamRecord]`: All team records belonging to the user.
+        """
+
+    @abstractmethod
+    async def delete_team(self, user_id: str, team_id: str) -> bool:
+        """Delete a team record and cascade-clean its members by role.
+
+        The cascade is role-aware — the two team-membership modes
+        (created vs invited, see :class:`TeamMember`) must be handled
+        differently:
+
+        1. For each :class:`TeamMember` in the team's roster (resolved
+           via the ``ensure_team_members`` helper so legacy
+           ``member_ids``-only records are migrated on first read):
+
+           - ``role == "created"`` — call :meth:`delete_agent`
+             (which cascades that worker's session). The agent record
+             is fully removed because it was spawned solely for this
+             team.
+           - ``role == "invited"`` — call :meth:`delete_session` for
+             the borrowed team-scoped session only. The invited
+             agent's :class:`AgentRecord` and any other sessions it
+             owns survive the team's dissolution.
+        2. Clear ``team_id`` on the leader session referenced by
+           :attr:`TeamRecord.session_id` (``ON DELETE SET NULL`` for
+           the leader's back-reference). Idempotent if the session has
+           already been deleted.
+        3. Delete the :class:`TeamRecord` key and the per-user team
+           index entry.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+            team_id (`str`):
+                The id of the team to delete.
+
+        Returns:
+            `bool`:
+                ``True`` if the team record existed and was deleted,
+                ``False`` if not found.
+        """
+
+    # ------------------------------------------------------------------
+    # Knowledge base persistence
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    async def upsert_knowledge_base(
+        self,
+        user_id: str,
+        record: KnowledgeBaseRecord,
+    ) -> KnowledgeBaseRecord:
+        """Create or update a knowledge base record.
+
+        The caller is responsible for constructing the full
+        :class:`KnowledgeBaseRecord` (including ``id`` and
+        ``collection_name``).  If a record with the same id already
+        exists it is overwritten and ``updated_at`` refreshed.
+
+        Args:
+            user_id (`str`):
+                The owner user id. Must match ``record.user_id``.
+            record (`KnowledgeBaseRecord`):
+                The fully-populated record to persist.
+
+        Returns:
+            `KnowledgeBaseRecord`:
+                The stored record (with ``updated_at`` refreshed).
+        """
+
+    @abstractmethod
+    async def get_knowledge_base(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+    ) -> KnowledgeBaseRecord | None:
+        """Fetch a single knowledge base record by id.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+            knowledge_base_id (`str`):
+                The knowledge base id.
+
+        Returns:
+            `KnowledgeBaseRecord | None`:
+                The record, or ``None`` if not found or not owned by
+                the given user.
+        """
+
+    @abstractmethod
+    async def list_knowledge_bases(
+        self,
+        user_id: str,
+    ) -> list[KnowledgeBaseRecord]:
+        """List all knowledge base records owned by the given user.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+
+        Returns:
+            `list[KnowledgeBaseRecord]`:
+                All knowledge base records belonging to the user.
+        """
+
+    @abstractmethod
+    async def delete_knowledge_base(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+    ) -> bool:
+        """Delete a knowledge base record and remove it from the user index.
+
+        Note: this only removes the metadata record; deletion of the
+        underlying vector store collection is the caller's
+        responsibility (typically the knowledge base manager).
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+            knowledge_base_id (`str`):
+                The id of the record to delete.
+
+        Returns:
+            `bool`:
+                ``True`` if the record existed and was deleted,
+                ``False`` if not found.
+        """
+
+    # ------------------------------------------------------------------
+    # Knowledge document persistence
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    async def upsert_knowledge_document(
+        self,
+        user_id: str,
+        record: KnowledgeDocumentRecord,
+    ) -> KnowledgeDocumentRecord:
+        """Create or update a knowledge document record.
+
+        Used by the upload endpoint to register a freshly arrived
+        document (``status='pending'``) and by other code paths that
+        need to overwrite the full record.  Phase transitions during
+        indexing should go through :meth:`update_knowledge_document_status`
+        instead, which is cheaper and atomic w.r.t. the lease fields.
+
+        Args:
+            user_id (`str`):
+                The owner user id.  Must match ``record.user_id``.
+            record (`KnowledgeDocumentRecord`):
+                The fully-populated record to persist.
+
+        Returns:
+            `KnowledgeDocumentRecord`:
+                The stored record (with ``updated_at`` refreshed).
+        """
+
+    @abstractmethod
+    async def get_knowledge_document(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+        document_id: str,
+    ) -> KnowledgeDocumentRecord | None:
+        """Fetch a single knowledge document record by id.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+            knowledge_base_id (`str`):
+                The parent knowledge base id.
+            document_id (`str`):
+                The document id.
+
+        Returns:
+            `KnowledgeDocumentRecord | None`:
+                The record, or ``None`` if not found.
+        """
+
+    @abstractmethod
+    async def list_knowledge_documents(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+    ) -> list[KnowledgeDocumentRecord]:
+        """List all documents in a knowledge base.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+            knowledge_base_id (`str`):
+                The parent knowledge base id.
+
+        Returns:
+            `list[KnowledgeDocumentRecord]`:
+                All document records belonging to the knowledge base,
+                in arbitrary order.
+        """
+
+    @abstractmethod
+    async def delete_knowledge_document(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+        document_id: str,
+    ) -> bool:
+        """Delete a knowledge document record.
+
+        Only removes the metadata record; cleanup of the underlying
+        blob and vector store records is the caller's responsibility.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+            knowledge_base_id (`str`):
+                The parent knowledge base id.
+            document_id (`str`):
+                The id of the record to delete.
+
+        Returns:
+            `bool`:
+                ``True`` if the record existed and was deleted,
+                ``False`` if not found.
+        """
+
+    @abstractmethod
+    async def update_knowledge_document_status(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+        document_id: str,
+        status: KnowledgeDocumentStatus,
+        error: str | None = None,
+        chunk_count: int | None = None,
+    ) -> None:
+        """Update only the status-related fields of a document record.
+
+        Used by the indexing worker as it walks the lifecycle
+        transitions (``parsing`` → ``chunking`` → ``indexing`` →
+        ``ready`` / ``error``).  Cheaper than a full upsert and avoids
+        races with concurrent lease writes by touching only the status
+        / error / chunk_count fields.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+            knowledge_base_id (`str`):
+                The parent knowledge base id.
+            document_id (`str`):
+                The document being updated.
+            status (`KnowledgeDocumentStatus`):
+                The new lifecycle state.
+            error (`str | None`, optional):
+                Failure reason, set when ``status == 'error'``.
+                Ignored otherwise.  ``None`` leaves the existing
+                value unchanged.
+            chunk_count (`int | None`, optional):
+                The final chunk count, set when ``status == 'ready'``.
+                ``None`` leaves the existing value unchanged.
+        """
+
+    @abstractmethod
+    async def acquire_knowledge_document_lease(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+        document_id: str,
+        processing_node: str,
+        lease_ttl: timedelta,
+        now: datetime | None = None,
+    ) -> bool:
+        """Compare-and-swap acquisition of the document processing lease.
+
+        Succeeds only if no other worker currently holds a live lease —
+        i.e. ``processing_node`` is unset or ``lease_expires_at`` is in
+        the past relative to ``now``.  On success the record's
+        ``processing_node`` and ``data.lease_expires_at`` fields are
+        updated.  The CAS is what makes the sweeper safe to run on
+        multiple nodes at once: even if two sweepers redispatch the
+        same document, only one worker can acquire its lease.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+            knowledge_base_id (`str`):
+                The parent knowledge base id.
+            document_id (`str`):
+                The document whose lease is being acquired.
+            processing_node (`str`):
+                Stable identifier of the calling worker (e.g.
+                ``hostname:pid:uuid``).  Persisted as
+                ``processing_node`` on success.
+            lease_ttl (`timedelta`):
+                How long the lease should live from ``now``.
+            now (`datetime | None`, optional):
+                Reference time for the comparison.  Defaults to
+                ``datetime.now()``.  Injectable for testing.
+
+        Returns:
+            `bool`:
+                ``True`` when the lease was acquired by this caller,
+                ``False`` when another worker already holds it.
+        """
+
+    @abstractmethod
+    async def renew_knowledge_document_lease(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+        document_id: str,
+        processing_node: str,
+        lease_ttl: timedelta,
+        now: datetime | None = None,
+    ) -> bool:
+        """Extend an existing lease this worker already holds.
+
+        Required for long-running parses that exceed ``lease_ttl`` —
+        the worker calls this periodically so the sweeper does not
+        mistake it for a crash.  Updates ``lease_expires_at`` to
+        ``now + lease_ttl`` only when ``processing_node`` matches the
+        caller; otherwise returns ``False`` so the worker can abandon
+        cleanly (its lease was stolen).
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+            knowledge_base_id (`str`):
+                The parent knowledge base id.
+            document_id (`str`):
+                The document being renewed.
+            processing_node (`str`):
+                The caller's processing node id; must match the
+                record's current ``processing_node`` for renewal to
+                succeed.
+            lease_ttl (`timedelta`):
+                The new lease duration relative to ``now``.
+            now (`datetime | None`, optional):
+                Reference time.  Defaults to ``datetime.now()``.
+
+        Returns:
+            `bool`:
+                ``True`` when the renewal succeeded, ``False`` when
+                the lease no longer belongs to the caller.
+        """
+
+    @abstractmethod
+    async def release_knowledge_document_lease(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+        document_id: str,
+        processing_node: str,
+    ) -> None:
+        """Release the processing lease this worker holds.
+
+        Clears ``processing_node`` and ``data.lease_expires_at`` only
+        if the current holder matches ``processing_node`` — a stolen
+        lease (e.g. after sweep) is left untouched.  Idempotent: a
+        no-op when the document is missing or already free.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+            knowledge_base_id (`str`):
+                The parent knowledge base id.
+            document_id (`str`):
+                The document whose lease is being released.
+            processing_node (`str`):
+                The caller's processing node id; must match the
+                record's current holder.
+        """
+
+    @abstractmethod
+    async def list_knowledge_documents_with_expired_lease(
+        self,
+        now: datetime | None = None,
+    ) -> list[KnowledgeDocumentRecord]:
+        """Return non-terminal documents whose lease has expired.
+
+        Scans every user / knowledge base — used by the sweeper, not
+        by user-facing endpoints.  A document is "expired" when
+        ``data.status`` is not terminal (``ready`` / ``error``),
+        ``processing_node`` is set, and ``data.lease_expires_at`` is
+        in the past.  Implementations are free to skip records that
+        match no work and return an unspecified order.
+
+        Args:
+            now (`datetime | None`, optional):
+                Reference time.  Defaults to ``datetime.now()``.
+
+        Returns:
+            `list[KnowledgeDocumentRecord]`:
+                Documents to redispatch.
+        """
+
+    @abstractmethod
+    async def list_knowledge_documents_pending_since(
+        self,
+        threshold: datetime,
+    ) -> list[KnowledgeDocumentRecord]:
+        """Return documents stuck in ``pending`` older than ``threshold``.
+
+        Catches the corner case where the upload endpoint persisted a
+        record but the dispatcher (or the process holding it) died
+        before any worker picked the document up — a crashed lease
+        sweep would miss it because no lease was ever written.
+
+        Args:
+            threshold (`datetime`):
+                Cut-off creation time; only ``pending`` records
+                ``created_at < threshold`` are returned.
+
+        Returns:
+            `list[KnowledgeDocumentRecord]`:
+                Orphan ``pending`` documents to redispatch.
+        """
diff --git a/src/agentscope/app/storage/_model/__init__.py b/src/agentscope/app/storage/_model/__init__.py
new file mode 100644
index 0000000..14f2581
--- /dev/null
+++ b/src/agentscope/app/storage/_model/__init__.py
@@ -0,0 +1,48 @@
+# -*- coding: utf-8 -*-
+"""Storage models for persisted resources."""
+
+from ._agent import AgentRecord, AgentData, InviteConfig
+from ._credential import CredentialRecord
+from ._knowledge_base import KnowledgeBaseRecord
+from ._knowledge_document import (
+    KnowledgeDocumentData,
+    KnowledgeDocumentRecord,
+    KnowledgeDocumentStatus,
+)
+from ._schedule import ScheduleData, ScheduleRecord, ScheduleSource
+from ._session import (
+    SessionRecord,
+    SessionConfig,
+    SessionKnowledgeConfig,
+    ChatModelConfig,
+    TTSModelConfig,
+    EmbeddingModelConfig,
+    SessionSource,
+)
+from ._team import TeamRecord, TeamData, TeamMember
+from ._user import UserRecord
+
+__all__ = [
+    "AgentData",
+    "AgentRecord",
+    "CredentialRecord",
+    "KnowledgeBaseRecord",
+    "KnowledgeDocumentData",
+    "KnowledgeDocumentRecord",
+    "KnowledgeDocumentStatus",
+    "ScheduleData",
+    "ScheduleRecord",
+    "ScheduleSource",
+    "SessionConfig",
+    "SessionKnowledgeConfig",
+    "SessionRecord",
+    "SessionSource",
+    "ChatModelConfig",
+    "TTSModelConfig",
+    "EmbeddingModelConfig",
+    "TeamData",
+    "TeamRecord",
+    "TeamMember",
+    "UserRecord",
+    "InviteConfig",
+]
diff --git a/src/agentscope/app/storage/_model/_agent.py b/src/agentscope/app/storage/_model/_agent.py
new file mode 100644
index 0000000..412c046
--- /dev/null
+++ b/src/agentscope/app/storage/_model/_agent.py
@@ -0,0 +1,130 @@
+# -*- coding: utf-8 -*-
+"""The agent storage class."""
+from typing import Literal, Self
+
+from pydantic import Field, BaseModel, model_validator
+from pydantic.json_schema import SkipJsonSchema
+
+from ...._utils._common import _generate_id
+from ._base import _RecordBase
+from ....agent import ContextConfig, ReActConfig
+
+
+class InviteConfig(BaseModel):
+    """User-editable invite settings for :class:`AgentData`.
+
+    Kept in its own sub-model so the frontend's schema-driven form —
+    which renders any nested-object property as its own fieldset —
+    picks it up as a dedicated section without a per-field allowlist.
+    Also keeps the cross-field ``invitable ⇒ non-empty description``
+    invariant local to this model.
+    """
+
+    invitable: bool = Field(
+        default=False,
+        description=(
+            "Whether this agent may be borrowed into another agent's team "
+            "via the ``AgentInvite`` tool. Independent from "
+            ":attr:`invite_description` so the user can preserve an "
+            "authored blurb while temporarily disabling the toggle. "
+            "``invitable=True`` requires a non-empty "
+            ":attr:`invite_description` (enforced by validator)."
+        ),
+        title="Invitable",
+    )
+
+    invite_description: str | None = Field(
+        default=None,
+        description=(
+            "Free-text blurb shown to a leader LLM in the ``AgentInvite`` "
+            "tool description — used by the leader to decide whether to "
+            "borrow this agent. Persisted across toggle off/on so the "
+            "user's authored draft is not lost when :attr:`invitable` "
+            "is temporarily disabled."
+        ),
+        title="Invite Description",
+        json_schema_extra={"format": "textarea"},
+    )
+
+    @model_validator(mode="after")
+    def _check_invitable_has_description(self) -> Self:
+        """Reject ``invitable=True`` without a non-empty description.
+
+        The blurb is what the leader LLM sees when it inspects the
+        ``AgentInvite`` tool; without it, the LLM cannot make a sensible
+        choice. Rejecting at the model boundary (rather than in the
+        service layer) means PATCH / POST return HTTP 422 automatically.
+        """
+        if self.invitable and not (self.invite_description or "").strip():
+            raise ValueError(
+                "invite_description must be non-empty when invitable=True",
+            )
+        return self
+
+
+class AgentData(BaseModel):
+    """The agent data model."""
+
+    id: SkipJsonSchema[str] = Field(
+        description="Unique agent id",
+        default_factory=_generate_id,
+    )
+    """The agent id.
+
+    Server-assigned; never edited via the create / update form.
+    Annotated with :class:`SkipJsonSchema` so it is dropped from
+    ``AgentData.model_json_schema()`` (the frontend renders the form
+    off that schema) while still being serialised in normal JSON
+    dumps (so persisted records keep the id).
+    """
+
+    name: str = Field(
+        description="The name of the agent.",
+        title="Name",
+    )
+
+    system_prompt: str = Field(
+        default="You're a helpful assistant.",
+        description="The system prompt for the agent.",
+        title="System Prompt",
+        # Hint for schema-driven UI renderers; see ``ContextConfig`` for
+        # the same pattern on long-form prompts.
+        json_schema_extra={"format": "textarea"},
+    )
+
+    context_config: ContextConfig = Field(
+        description="The context config for the agent.",
+        title="Context Config",
+    )
+
+    react_config: ReActConfig = Field(
+        description="The react config for the agent.",
+        title="React Config",
+    )
+
+    invite_config: InviteConfig = Field(
+        default_factory=InviteConfig,
+        description="The invite config for the agent.",
+        title="Invite Config",
+    )
+
+
+class AgentRecord(_RecordBase):
+    """The agent ORM model."""
+
+    user_id: str
+    """The user id"""
+
+    source: Literal["user", "team"] = "user"
+    """How this agent was created.
+
+    - ``"user"``: created directly by the user (default). Can have multiple
+      sessions and is listed in the user's regular agent list.
+    - ``"team"``: spawned as a team worker by another agent's
+      ``create_team`` / ``team_add_member`` tool. Has exactly one session.
+      Team membership itself is session-level and stored on
+      :class:`SessionRecord.team_id`.
+    """
+
+    data: AgentData
+    """The agent data"""
diff --git a/src/agentscope/app/storage/_model/_base.py b/src/agentscope/app/storage/_model/_base.py
new file mode 100644
index 0000000..f9a5b76
--- /dev/null
+++ b/src/agentscope/app/storage/_model/_base.py
@@ -0,0 +1,26 @@
+# -*- coding: utf-8 -*-
+"""The base attributes used in storage."""
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+from ...._utils._common import _generate_id
+
+
+class _RecordBase(BaseModel):
+    """The base class for all records."""
+
+    id: str = Field(
+        default_factory=_generate_id,
+        description="Unique identifier for the credential.",
+    )
+
+    updated_at: datetime = Field(
+        default_factory=datetime.now,
+    )
+    """The updated time."""
+
+    created_at: datetime = Field(
+        default_factory=datetime.now,
+    )
+    """The created time."""
diff --git a/src/agentscope/app/storage/_model/_credential.py b/src/agentscope/app/storage/_model/_credential.py
new file mode 100644
index 0000000..6462e6a
--- /dev/null
+++ b/src/agentscope/app/storage/_model/_credential.py
@@ -0,0 +1,17 @@
+# -*- coding: utf-8 -*-
+"""The credential record."""
+from pydantic import Field
+
+from ...._utils._common import _generate_id
+from ._base import _RecordBase
+
+
+class CredentialRecord(_RecordBase):
+    """The credential model used for storing credentials."""
+
+    user_id: str = Field(
+        default_factory=_generate_id,
+    )
+
+    data: dict
+    """The credential data."""
diff --git a/src/agentscope/app/storage/_model/_knowledge_base.py b/src/agentscope/app/storage/_model/_knowledge_base.py
new file mode 100644
index 0000000..cdeba3f
--- /dev/null
+++ b/src/agentscope/app/storage/_model/_knowledge_base.py
@@ -0,0 +1,46 @@
+# -*- coding: utf-8 -*-
+"""The knowledge base record."""
+from pydantic import Field
+
+from ._base import _RecordBase
+from ._session import EmbeddingModelConfig
+
+
+class KnowledgeBaseRecord(_RecordBase):
+    """A persisted knowledge base record.
+
+    Stores per-user metadata for a knowledge base; the actual chunks
+    and vectors live in the configured ``VectorStoreBase`` backend.
+    Each record is the canonical authorisation gate: HTTP handlers and
+    middleware look the record up by ``(user_id, id)`` before talking
+    to the vector store.
+    """
+
+    user_id: str = Field(description="The owner user id.")
+    """The user id that owns this knowledge base."""
+
+    name: str = Field(description="Display name of the knowledge base.")
+    """Display name shown in the UI."""
+
+    description: str = Field(
+        default="",
+        description="Free-form description of the knowledge base purpose.",
+    )
+    """Free-form description shown in the UI."""
+
+    embedding_model_config: EmbeddingModelConfig = Field(
+        description=(
+            "Embedding model configuration pinned at creation time. "
+            "Cannot change for the lifetime of the record because the "
+            "underlying collection is sized to its dimension."
+        ),
+    )
+    """Embedding model configuration pinned at creation time."""
+
+    collection_name: str = Field(
+        description=(
+            "The vector store collection that physically backs this "
+            "knowledge base. Generated server-side; opaque to clients."
+        ),
+    )
+    """The vector store collection name (e.g. ``kb_<uuid_hex>``)."""
diff --git a/src/agentscope/app/storage/_model/_knowledge_document.py b/src/agentscope/app/storage/_model/_knowledge_document.py
new file mode 100644
index 0000000..f3c7b9f
--- /dev/null
+++ b/src/agentscope/app/storage/_model/_knowledge_document.py
@@ -0,0 +1,139 @@
+# -*- coding: utf-8 -*-
+"""The knowledge document record.
+
+A :class:`KnowledgeDocumentRecord` is the canonical source of truth
+for one uploaded file inside a knowledge base.  It owns the document's
+**lifecycle** (status, error, lease) and **byte handle** (``blob_uri``)
+before any chunks reach the vector store, which is exactly the state
+the vector store cannot represent on its own (no chunks means no
+``document_id`` to aggregate from).
+
+Top-level fields are the relational keys (``user_id`` /
+``knowledge_base_id`` / ``processing_node``) that the storage backend
+indexes on; everything else lives inside ``data`` per the project
+record convention.
+"""
+from datetime import datetime
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from ._base import _RecordBase
+
+
+KnowledgeDocumentStatus = Literal[
+    "pending",
+    "parsing",
+    "chunking",
+    "indexing",
+    "ready",
+    "error",
+]
+# The six lifecycle states of a knowledge document.
+#
+# ``pending`` — bytes are in the blob store, waiting for a worker to
+# pick the document up. ``parsing`` / ``chunking`` / ``indexing`` are
+# worker-owned transitions; ``ready`` and ``error`` are terminal.
+
+
+class KnowledgeDocumentData(BaseModel):
+    """The mutable payload of a knowledge document record."""
+
+    filename: str = Field(
+        description="Original filename supplied by the uploader.",
+    )
+    """The original filename — used both for citation and as the
+    ``source`` field on every chunk produced from this document."""
+
+    size: int = Field(
+        ge=0,
+        description="Document size in bytes as observed at upload time.",
+    )
+    """Byte length recorded at upload time.  Used by quota checks and
+    the UI; not authoritative for parsing (the worker reopens the
+    blob)."""
+
+    content_type: str | None = Field(
+        default=None,
+        description="IANA media type used to route the upload to a parser.",
+    )
+    """IANA media type.  ``None`` lets the worker fall back to
+    ``mimetypes.guess_type(filename)``."""
+
+    blob_uri: str = Field(
+        description=(
+            "URI returned by the blob store after the upload was "
+            "streamed in (e.g. ``local://kb/.../uuid``)."
+        ),
+    )
+    """Scheme-qualified URI handed back by
+    :class:`~agentscope.app.rag.blob_store.BlobStoreBase`.  The worker
+    streams bytes back through the same blob store."""
+
+    status: KnowledgeDocumentStatus = Field(
+        default="pending",
+        description="Current lifecycle state.",
+    )
+    """Current lifecycle state.  Read by the polling endpoint, written
+    by the worker as it transitions phases."""
+
+    error: str | None = Field(
+        default=None,
+        description=(
+            "Human-readable failure reason when ``status == 'error'``. "
+            "MUST NOT include stack traces or filesystem paths — it is "
+            "rendered verbatim in the UI."
+        ),
+    )
+    """Human-readable failure reason.  Surfaced directly to the user;
+    keep it short and free of sensitive content."""
+
+    chunk_count: int = Field(
+        default=0,
+        ge=0,
+        description="Number of chunks successfully indexed.",
+    )
+    """The final chunk count, written by the worker when the document
+    reaches ``ready``."""
+
+    lease_expires_at: datetime | None = Field(
+        default=None,
+        description=(
+            "Wall-clock deadline for the worker that currently holds "
+            "this document.  ``None`` if no worker is processing it."
+        ),
+    )
+    """Lease deadline.  Together with ``processing_node`` lets the
+    sweeper detect crashed workers and reassign their documents."""
+
+
+class KnowledgeDocumentRecord(_RecordBase):
+    """A persisted knowledge document record.
+
+    Top-level fields are relational keys the storage backend needs to
+    index on directly (per-user listing, per-KB listing, per-node lease
+    sweeps); the mutable payload lives in :attr:`data`.
+    """
+
+    user_id: str = Field(description="The owner user id.")
+    """The user id that owns the parent knowledge base."""
+
+    knowledge_base_id: str = Field(
+        description="The id of the knowledge base this document belongs to.",
+    )
+    """The knowledge base the document is being indexed into."""
+
+    processing_node: str | None = Field(
+        default=None,
+        description=(
+            "Identifier of the worker process that currently holds the "
+            "lease on this document.  ``None`` if no worker is "
+            "processing it."
+        ),
+    )
+    """The current lease holder.  Promoted to the top level so the
+    storage backend can look up "documents owned by node X" or
+    "documents with no owner" without deserialising every payload."""
+
+    data: KnowledgeDocumentData
+    """The mutable document payload."""
diff --git a/src/agentscope/app/storage/_model/_schedule.py b/src/agentscope/app/storage/_model/_schedule.py
new file mode 100644
index 0000000..523b5c1
--- /dev/null
+++ b/src/agentscope/app/storage/_model/_schedule.py
@@ -0,0 +1,117 @@
+# -*- coding: utf-8 -*-
+"""The schedule storage model."""
+from datetime import datetime
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+from ._base import _RecordBase
+from ._session import ChatModelConfig
+from ....permission import PermissionMode
+
+
+class ScheduleSource(str, Enum):
+    """The source that created the schedule.
+
+    Attributes:
+        USER: Created manually by the user via the UI.
+        AGENT: Created automatically by an agent, e.g. via a tool call.
+    """
+
+    USER = "USER"
+    AGENT = "AGENT"
+
+
+def _get_local_timezone() -> str:
+    """Get the local timezone.
+
+    Returns:
+        `str`:
+            The local timezone.
+    """
+    try:
+        from tzlocal import get_localzone
+
+        return str(get_localzone())
+    except Exception:
+        return "UTC"
+
+
+class ScheduleData(BaseModel):
+    """The schedule configuration data."""
+
+    name: str = Field(description="Display name of the schedule.")
+
+    description: str = Field(
+        default="",
+        description="The description of the schedule, including its purpose, "
+        "trigger conditions, etc.",
+    )
+
+    enabled: bool = Field(
+        default=True,
+        description="Whether the schedule is active. Disabled schedules are "
+        "retained but will not trigger.",
+    )
+
+    timezone: str = Field(
+        default=_get_local_timezone(),
+        description="IANA timezone name used to evaluate the cron expression, "
+        "e.g. 'America/New_York' or 'Asia/Shanghai'.",
+    )
+
+    cron_expression: str = Field(
+        description="Standard 5-field cron expression, e.g. '0 9 * * 1-5'.",
+    )
+
+    started_at: datetime = Field(
+        description="The date and time the schedule was started.",
+        default_factory=datetime.now,
+    )
+
+    ended_at: datetime | None = Field(
+        default=None,
+        description="The date and time the schedule was ended.",
+    )
+
+    chat_model_config: ChatModelConfig = Field(
+        description="Model configuration for the auto-created session.",
+    )
+
+    stateful: bool = Field(
+        title="Stateful",
+        default=False,
+        description="Whether consecutive executions share the same session "
+        "context. If not, each execution will have its own state.",
+    )
+
+    permission_mode: PermissionMode = Field(
+        title="Permission mode",
+        default=PermissionMode.DONT_ASK,
+        description="Permission level for the agent during scheduled "
+        "execution. Defaults to DONT_ASK since no user is present to "
+        "answer prompts.",
+    )
+
+    source: ScheduleSource = Field(
+        default=ScheduleSource.USER,
+        description="Indicates how this schedule was created.",
+    )
+
+    source_session_id: str = Field(
+        default="",
+        description="The source session identifier, used for resource "
+        "retrieval.",
+    )
+
+
+class ScheduleRecord(_RecordBase):
+    """Persisted schedule record."""
+
+    user_id: str = Field(description="Owner user id.")
+
+    agent_id: str = Field(
+        description="The agent id that will execute the schedule.",
+    )
+
+    data: ScheduleData = Field(description="Schedule configuration.")
diff --git a/src/agentscope/app/storage/_model/_session.py b/src/agentscope/app/storage/_model/_session.py
new file mode 100644
index 0000000..af30db1
--- /dev/null
+++ b/src/agentscope/app/storage/_model/_session.py
@@ -0,0 +1,176 @@
+# -*- coding: utf-8 -*-
+"""The session data class for storage."""
+from datetime import datetime
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+from ._base import _RecordBase
+from ....state import AgentState
+
+
+class SessionSource(str, Enum):
+    """The source that created the session."""
+
+    USER = "user"
+    SCHEDULE = "schedule"
+
+
+class ChatModelConfig(BaseModel):
+    """The model configuration class."""
+
+    type: str
+    """The provider type."""
+
+    credential_id: str
+    """The credential id."""
+
+    model: str
+    """The model name."""
+
+    parameters: dict
+    """The model parameters."""
+
+
+class TTSModelConfig(BaseModel):
+    """The TTS model configuration class."""
+
+    type: str
+    """The provider type."""
+
+    credential_id: str
+    """The credential id."""
+
+    model: str
+    """The TTS model name."""
+
+    parameters: dict
+    """TTS parameters (voice, language, etc.)."""
+
+
+class EmbeddingModelConfig(BaseModel):
+    """Configuration for constructing an embedding model from a credential.
+
+    Mirrors :class:`ChatModelConfig` but targets
+    :class:`~agentscope.embedding.EmbeddingModelBase` subclasses.
+    Used by :class:`KnowledgeBaseRecord` to persist the user's
+    embedding model selection.
+    """
+
+    type: str
+    """The provider type (e.g. ``"openai_credential"``)."""
+
+    credential_id: str
+    """The credential id to use for authentication."""
+
+    model: str
+    """The embedding model name (e.g. ``"text-embedding-3-small"``)."""
+
+    dimensions: int = Field(..., gt=0)
+    """The output embedding vector dimensions.
+
+    Required and first-class — chosen at config-creation time and
+    pinned to the resulting :class:`KnowledgeBaseRecord` so subsequent
+    indexing / retrieval calls are dim-deterministic without any
+    fallback lookup.
+    """
+
+    parameters: dict = Field(default_factory=dict)
+    """The provider-specific non-dimensional parameters.
+
+    Does **not** carry ``dimensions`` — that field is promoted to a
+    top-level attribute above.
+    """
+
+
+class SessionKnowledgeConfig(BaseModel):
+    """Session-level knowledge base attachment.
+
+    Persists which knowledge bases the agent should retrieve from for
+    this session and how the
+    :class:`~agentscope.middleware.RAGMiddleware` should be
+    configured.  ``parameters`` carries the user-tunable middleware
+    fields verbatim (mirrors :attr:`ChatModelConfig.parameters`); the
+    accepted keys and value types are described by
+    :meth:`RAGMiddleware.Config.model_json_schema`.
+    """
+
+    knowledge_base_ids: list[str] = Field(default_factory=list)
+    """Ids of the knowledge bases attached to this session.
+
+    Empty list means no knowledge base is wired and the middleware is
+    not installed.
+    """
+
+    parameters: dict = Field(default_factory=dict)
+    """Middleware parameters keyed by ``RAGMiddleware``'s
+    :class:`Config` model fields (``mode``, ``top_k``,
+    ``score_threshold``, ``emit_hint_event``, ``persist_hint``,
+    ``hint_template``).
+    """
+
+
+class SessionConfig(BaseModel):
+    """Session configuration — set at creation, updatable via PATCH."""
+
+    workspace_id: str
+    """Authoritative workspace binding for the session.
+
+    Populated at session creation — either from an explicit
+    ``workspace_id`` on ``CreateSessionRequest`` (used by team
+    invite/borrow flows) or from
+    :meth:`WorkspaceManagerBase.assign_workspace_id` under the
+    manager's isolation policy. Consumed verbatim by chat,
+    ``list_mcps``, and team tools; also the cache key for
+    :meth:`WorkspaceManagerBase.get_workspace`."""
+
+    name: str = Field(
+        default_factory=lambda: datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
+        description="Display name for the session.",
+    )
+    """The session display name."""
+
+    chat_model_config: ChatModelConfig | None = None
+    """The chat model config. None means no model has been configured yet."""
+
+    fallback_chat_model_config: ChatModelConfig | None = None
+    """The fallback chat model config. Used as a backup when the primary
+    model fails. None means no fallback configured."""
+
+    tts_model_config: TTSModelConfig | None = None
+    """The TTS model config. None means TTS is not enabled."""
+
+    knowledge_config: SessionKnowledgeConfig | None = None
+    """Knowledge bases attached to this session and the corresponding
+    :class:`~agentscope.middleware.RAGMiddleware` parameters.
+    ``None`` means no knowledge base is wired."""
+
+
+class SessionRecord(_RecordBase):
+    """The session record."""
+
+    user_id: str
+    """The user id."""
+
+    agent_id: str
+    """The agent id."""
+
+    source: SessionSource = SessionSource.USER
+    """The source that created this session."""
+
+    source_schedule_id: str | None = None
+    """The source schedule Id."""
+
+    team_id: str | None = None
+    """The team this session participates in, if any.
+
+    Team membership is session-level: a user agent can lead multiple teams
+    across different sessions, and each worker session belongs to exactly
+    one team. ``None`` means the session is not part of any team.
+    """
+
+    config: SessionConfig
+    """Session configuration (workspace, name, model)."""
+
+    state: AgentState = Field(default_factory=AgentState)
+    """Mutable runtime state, updated after each chat turn."""
diff --git a/src/agentscope/app/storage/_model/_team.py b/src/agentscope/app/storage/_model/_team.py
new file mode 100644
index 0000000..48fd32b
--- /dev/null
+++ b/src/agentscope/app/storage/_model/_team.py
@@ -0,0 +1,122 @@
+# -*- coding: utf-8 -*-
+"""The team storage class."""
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from ._base import _RecordBase
+
+
+class TeamMember(BaseModel):
+    """An entry in a team's member roster.
+
+    Unlike the legacy :attr:`TeamData.member_ids`, this carries both the
+    agent id AND the session id — required because an *invited* member's
+    agent (e.g. Monday) can have multiple sessions of its own; the team
+    only wants the one it created when the leader called ``AgentInvite``.
+    The ``role`` tag then drives cascade behavior (see
+    :meth:`SessionService.delete_team`): ``created`` members are fully
+    deleted with the team, ``invited`` members only lose the borrowed
+    session while their :class:`AgentRecord` survives.
+    """
+
+    owner_id: str = Field(
+        description=(
+            "Owner of the member's agent. Always equals the team owner "
+            "in today's user-only invite pool, but is stored explicitly "
+            "so a future admin-share layer (agents borrowed across users) "
+            "can slot in without a schema migration. Distinct name from "
+            ":attr:`TeamRecord.user_id` on purpose — the surrounding "
+            "team already carries the team owner in context, so calling "
+            "this field ``user_id`` too would be ambiguous."
+        ),
+    )
+
+    agent_id: str = Field(
+        description="The member agent's id.",
+    )
+
+    session_id: str = Field(
+        description=(
+            "The team-scoped session id for this member. For ``created`` "
+            "members this is the sole session (1:1 with the agent). For "
+            "``invited`` members this is the freshly-minted session that "
+            "``AgentInvite`` created — the agent's other sessions are "
+            "unrelated to this team."
+        ),
+    )
+
+    role: Literal["created", "invited"] = Field(
+        description=(
+            "How this member joined the team. ``created`` — spawned "
+            "from a :class:`SubAgentTemplate` via ``AgentCreate``, "
+            "deleted with the team. ``invited`` — a pre-existing "
+            "user-owned agent borrowed via ``AgentInvite``, retains its "
+            ":class:`AgentRecord` when the team is dissolved."
+        ),
+    )
+
+
+class TeamData(BaseModel):
+    """The team data model."""
+
+    name: str = Field(
+        description="Display name of the team.",
+        title="Name",
+    )
+
+    description: str = Field(
+        default="",
+        description=(
+            "What the team is for — its overall goal or shared context. "
+            "Wired into every member's system prompt so all members share "
+            "the same high-level understanding of why the team exists."
+        ),
+        title="Description",
+    )
+
+    member_ids: list[str] = Field(
+        default_factory=list,
+        description=(
+            "**Deprecated** — legacy roster of worker agent ids from "
+            "before the ``AgentInvite`` era, when every member was "
+            "team-spawned (``source='team'``) with a 1:1 agent-session "
+            "mapping. New code should read :attr:`members` via the "
+            "``ensure_team_members`` helper, which migrates any records "
+            "still using this field to the richer schema on first read."
+        ),
+        title="Member Ids",
+        deprecated=True,
+    )
+
+    members: list[TeamMember] = Field(
+        default_factory=list,
+        description=(
+            "Explicit member roster with role + session id per entry. "
+            "Read this via the ``ensure_team_members`` helper so legacy "
+            "records with only :attr:`member_ids` populated are migrated "
+            "transparently."
+        ),
+        title="Members",
+    )
+
+
+class TeamRecord(_RecordBase):
+    """The team ORM model.
+
+    Team membership is session-level: the leader is identified by its
+    ``session_id`` (since a user agent can lead multiple teams across
+    different sessions). Workers are identified by
+    :class:`TeamMember` entries in :attr:`TeamData.members`, accessed
+    via the ``ensure_team_members`` helper which handles migration from
+    the legacy :attr:`TeamData.member_ids` shape.
+    """
+
+    user_id: str
+    """The user id."""
+
+    session_id: str
+    """The leader session id — the session that called ``create_team``."""
+
+    data: TeamData
+    """The team data."""
diff --git a/src/agentscope/app/storage/_model/_user.py b/src/agentscope/app/storage/_model/_user.py
new file mode 100644
index 0000000..7b89bd3
--- /dev/null
+++ b/src/agentscope/app/storage/_model/_user.py
@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+"""The user record for storage."""
+
+from ._base import _RecordBase
+
+
+class UserRecord(_RecordBase):
+    """The user record."""
diff --git a/src/agentscope/app/storage/_redis_storage.py b/src/agentscope/app/storage/_redis_storage.py
new file mode 100644
index 0000000..57e43bd
--- /dev/null
+++ b/src/agentscope/app/storage/_redis_storage.py
@@ -0,0 +1,1770 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=too-many-public-methods
+"""The Redis storage implementation."""
+
+from datetime import datetime, timedelta
+from typing import Any, TYPE_CHECKING, Self
+
+from pydantic import BaseModel
+
+from ._base import StorageBase
+from ._model import (
+    AgentRecord,
+    CredentialRecord,
+    KnowledgeBaseRecord,
+    KnowledgeDocumentRecord,
+    KnowledgeDocumentStatus,
+    ScheduleRecord,
+    SessionRecord,
+    SessionConfig,
+    SessionSource,
+    TeamRecord,
+)
+from ._utils import _dump_with_secrets
+from ...credential import CredentialBase
+from ...message import Msg
+from ...state import AgentState
+
+if TYPE_CHECKING:
+    from redis.asyncio import ConnectionPool, Redis
+else:
+    ConnectionPool = Any
+    Redis = Any
+
+
+def _watch_error() -> type[BaseException]:
+    """Return the ``WatchError`` class from ``redis.exceptions``.
+
+    Lazy-imported so ``redis`` stays an optional dependency at module
+    load time — same trick the storage class uses in ``__aenter__``.
+    """
+    from redis.exceptions import WatchError
+
+    return WatchError
+
+
+class RedisStorage(StorageBase):
+    """The Redis storage implementation."""
+
+    class KeyConfig(BaseModel):
+        """Key templates for all Redis keys used by :class:`RedisStorage`.
+
+        Nested on :class:`RedisStorage` because customising key prefixes
+        is meaningful only for this backend; users tweak them via
+        ``RedisStorage(key_config=RedisStorage.KeyConfig(...))``.
+        """
+
+        # Record keys
+        credential: str = (
+            "agentscope:user:{user_id}:credential:{credential_id}"
+        )
+        agent: str = "agentscope:user:{user_id}:agent:{agent_id}"
+        session: str = "agentscope:user:{user_id}:session:{session_id}"
+
+        # Index keys (Redis Sets — store all IDs for a given scope)
+        credential_index: str = "agentscope:user:{user_id}:credentials"
+        agent_index: str = "agentscope:user:{user_id}:agents"
+        session_index: str = (
+            "agentscope:user:{user_id}:agent:{agent_id}:sessions"
+        )
+
+        # Lookup key: maps (user_id, agent_id) → session_id
+        session_lookup: str = (
+            "agentscope:user:{user_id}:agent:{agent_id}:session"
+        )
+
+        # Message list key (Redis List — ordered message history per session)
+        messages: str = (
+            "agentscope:user:{user_id}:session:{session_id}:messages"
+        )
+
+        schedule: str = "agentscope:user:{user_id}:schedule:{schedule_id}"
+        schedule_index: str = "agentscope:user:{user_id}:schedules"
+        schedule_global_index: str = "agentscope:schedules"
+        schedule_session_index: str = (
+            "agentscope:user:{user_id}:schedule:{schedule_id}:sessions"
+        )
+
+        team: str = "agentscope:user:{user_id}:team:{team_id}"
+        team_index: str = "agentscope:user:{user_id}:teams"
+
+        knowledge_base: str = (
+            "agentscope:user:{user_id}:knowledge_base:{knowledge_base_id}"
+        )
+        knowledge_base_index: str = "agentscope:user:{user_id}:knowledge_bases"
+
+        # Knowledge document keys
+        knowledge_document: str = (
+            "agentscope:user:{user_id}"
+            ":knowledge_base:{knowledge_base_id}"
+            ":document:{document_id}"
+        )
+        knowledge_document_index: str = (
+            "agentscope:user:{user_id}"
+            ":knowledge_base:{knowledge_base_id}:documents"
+        )
+        # Global index of every document key as ``user_id:kb_id:doc_id``;
+        # used by the lease sweeper, never by per-user listing.
+        knowledge_document_global_index: str = "agentscope:knowledge_documents"
+
+    def __init__(
+        self,
+        host: str = "localhost",
+        port: int = 6379,
+        db: int = 0,
+        password: str | None = None,
+        connection_pool: ConnectionPool | None = None,
+        key_ttl: int | None = None,
+        key_config: "RedisStorage.KeyConfig | None" = None,
+        **kwargs: Any,
+    ) -> None:
+        """Store connection parameters; the actual pool is created in
+        :meth:`__aenter__`.
+
+        Args:
+            host (`str`, defaults to `"localhost"`): Redis server host.
+            port (`int`, defaults to `6379`): Redis server port.
+            db (`int`, defaults to `0`): Redis database index.
+            password (`str | None`, optional): Redis password if required.
+            connection_pool (`ConnectionPool | None`, optional):
+                An externally managed connection pool.  When provided the pool
+                is used as-is and **not** closed by :meth:`aclose` — the
+                caller retains ownership of its lifecycle.  When omitted a
+                pool is created from *host*/*port*/*db*/*password* on
+                :meth:`__aenter__` and closed on :meth:`aclose`.
+                Extra ``**kwargs`` (e.g. ``max_connections``) are forwarded to
+                the pool constructor only when the pool is created internally.
+            key_ttl (`int | None`, optional):
+                Expire time in seconds for record keys. Refreshed on every
+                write (sliding TTL). If `None`, keys do not expire.
+            key_config (`RedisStorage.KeyConfig | None`, optional):
+                Key template configuration. Defaults to
+                ``RedisStorage.KeyConfig()``.
+            **kwargs (`Any`):
+                Extra keyword arguments forwarded to
+                ``redis.asyncio.ConnectionPool`` when the pool is created
+                internally (e.g. ``max_connections=20``, ``socket_timeout=5``).
+        """
+        self._host = host
+        self._port = port
+        self._db = db
+        self._password = password
+        self._external_pool: ConnectionPool | None = connection_pool
+        self._kwargs = kwargs
+        self.key_ttl = key_ttl
+        self.key_config = key_config or RedisStorage.KeyConfig()
+
+        # Populated in __aenter__; None until the context is entered.
+        self._client: Redis | None = None
+        self._owned_pool: ConnectionPool | None = None
+
+    def _key(self, template: str, **kwargs: str) -> str:
+        """Format a key template with the given keyword arguments."""
+        return template.format(**kwargs)
+
+    async def _set_with_ttl(self, key: str, value: str) -> None:
+        """SET a key and optionally apply the sliding TTL."""
+        await self._client.set(key, value)
+        await self._refresh_key_ttl(key)
+
+    async def _refresh_key_ttl(self, key: str) -> None:
+        """Apply the sliding TTL to a key, if configured."""
+        if self.key_ttl is not None:
+            await self._client.expire(key, self.key_ttl)
+
+    async def __aenter__(self) -> Self:
+        """Create the connection pool and Redis client.
+
+        If an external pool was supplied at construction time it is used
+        directly and its lifecycle remains the caller's responsibility.
+        Otherwise, an internal pool is created from the stored host/port/db
+        parameters and will be closed by :meth:`aclose`.
+        """
+        try:
+            import redis.asyncio as aioredis
+        except ImportError as e:
+            raise ImportError(
+                "The 'redis' package is required for RedisStorage. "
+                "Install it with: pip install redis[async]",
+            ) from e
+
+        if self._external_pool is not None:
+            pool = self._external_pool
+        else:
+            self._owned_pool = aioredis.ConnectionPool(
+                host=self._host,
+                port=self._port,
+                db=self._db,
+                password=self._password,
+                decode_responses=True,
+                **self._kwargs,
+            )
+            pool = self._owned_pool
+
+        self._client = aioredis.Redis(connection_pool=pool)
+        return self
+
+    async def aclose(self) -> None:
+        """Close the connection pool if it was created internally.
+
+        Externally supplied pools are left open — the caller owns them.
+        """
+        if self._owned_pool is not None:
+            await self._owned_pool.aclose()
+            self._owned_pool = None
+        self._client = None
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: Any,
+    ) -> None:
+        """Exit the async context manager."""
+        await self.aclose()
+
+    def get_client(self) -> Redis:
+        """Get the underlying Redis client instance."""
+        return self._client
+
+    async def _generate_credential_name(
+        self,
+        user_id: str,
+        credential_data: CredentialBase,
+    ) -> str:
+        """Auto-generate a display name for a credential based on its type.
+
+        Produces names like "OpenAI", "OpenAI (2)", "OpenAI (3)", etc.
+        """
+        cred_type = getattr(credential_data, "type", "")
+        base_name = (
+            cred_type.removesuffix("_credential").replace("_", " ").title()
+        )
+        if not base_name:
+            base_name = "Credential"
+
+        existing = await self.list_credentials(user_id)
+        same_type_names = [
+            c.data.get("name", "")
+            for c in existing
+            if c.data.get("type") == cred_type and c.id != credential_data.id
+        ]
+
+        if base_name not in same_type_names:
+            return base_name
+
+        idx = 2
+        while f"{base_name} ({idx})" in same_type_names:
+            idx += 1
+        return f"{base_name} ({idx})"
+
+    async def upsert_credential(
+        self,
+        user_id: str,
+        credential_data: CredentialBase,
+    ) -> str:
+        """Create or update a credential record for the given user.
+
+        If `credential_data.id` is set and the record already exists, the
+        existing record's `data` field is updated in place (preserving
+        `created_at`). If the id is set but no record exists, a new record is
+        created with that id. If `credential_data.id` is ``None``, a new
+        record with a generated id is always created.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+            credential_data (`CredentialBase`):
+                Input data containing an optional `id` and the credential
+                `data` dict.
+
+        Returns:
+            `str`:
+                The id of the created or updated credential record.
+        """
+        if not credential_data.name:
+            credential_data.name = await self._generate_credential_name(
+                user_id,
+                credential_data,
+            )
+
+        data_dump = _dump_with_secrets(credential_data)
+
+        if credential_data.id:
+            key = self._key(
+                self.key_config.credential,
+                user_id=user_id,
+                credential_id=credential_data.id,
+            )
+            raw = await self._client.get(key)
+            if raw:
+                record = CredentialRecord.model_validate_json(raw)
+                record.data = data_dump
+                record.updated_at = datetime.now()
+            else:
+                record = CredentialRecord(
+                    id=credential_data.id,
+                    user_id=user_id,
+                    data=data_dump,
+                )
+        else:
+            record = CredentialRecord(
+                user_id=user_id,
+                data=data_dump,
+            )
+
+        key = self._key(
+            self.key_config.credential,
+            user_id=user_id,
+            credential_id=record.id,
+        )
+        index_key = self._key(
+            self.key_config.credential_index,
+            user_id=user_id,
+        )
+        await self._set_with_ttl(key, record.model_dump_json())
+        await self._client.sadd(index_key, record.id)
+        return record.id
+
+    async def list_credentials(self, user_id: str) -> list[CredentialRecord]:
+        """Return all credential records belonging to the given user.
+
+        Reads the per-user credential index Set to obtain all ids, then
+        fetches each record individually. Records whose keys have expired or
+        been deleted externally are silently skipped.
+
+        Args:
+            user_id (`str`): The owner user id.
+
+        Returns:
+            `list[CredentialRecord]`: All credential records for the user.
+        """
+        index_key = self._key(
+            self.key_config.credential_index,
+            user_id=user_id,
+        )
+        ids = await self._client.smembers(index_key)
+        records = []
+        for cred_id in ids:
+            raw = await self._client.get(
+                self._key(
+                    self.key_config.credential,
+                    user_id=user_id,
+                    credential_id=cred_id,
+                ),
+            )
+            if raw:
+                records.append(CredentialRecord.model_validate_json(raw))
+        return records
+
+    async def get_credential(
+        self,
+        user_id: str,
+        credential_id: str,
+    ) -> CredentialRecord | None:
+        """Fetch a single credential record by id."""
+        key = self._key(
+            self.key_config.credential,
+            user_id=user_id,
+            credential_id=credential_id,
+        )
+        raw = await self._client.get(key)
+        return CredentialRecord.model_validate_json(raw) if raw else None
+
+    async def delete_credential(
+        self,
+        user_id: str,
+        credential_id: str,
+    ) -> bool:
+        """Delete a credential record and remove it from the user's index.
+
+        Args:
+            user_id (`str`): The owner user id.
+            credential_id (`str`): The id of the credential to delete.
+
+        Returns:
+            `bool`: ``True`` if the record existed and was deleted,
+            ``False`` if it did not exist.
+        """
+        key = self._key(
+            self.key_config.credential,
+            user_id=user_id,
+            credential_id=credential_id,
+        )
+        index_key = self._key(
+            self.key_config.credential_index,
+            user_id=user_id,
+        )
+        deleted = await self._client.delete(key)
+        await self._client.srem(index_key, credential_id)
+        return deleted > 0
+
+    async def upsert_agent(
+        self,
+        user_id: str,
+        agent_record: AgentRecord,
+    ) -> str:
+        """Persist an agent record and register it in the user's agent index.
+
+        The caller is responsible for constructing the full `AgentRecord`
+        (including its `id`). If a record with the same id already exists it
+        will be overwritten.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+            agent_record (`AgentRecord`):
+                The fully-populated agent record to store.
+
+        Returns:
+            `str`:
+                The id of the stored agent record.
+        """
+        key = self._key(
+            self.key_config.agent,
+            user_id=user_id,
+            agent_id=agent_record.id,
+        )
+        index_key = self._key(self.key_config.agent_index, user_id=user_id)
+        await self._set_with_ttl(key, agent_record.model_dump_json())
+        await self._client.sadd(index_key, agent_record.id)
+        return agent_record.id
+
+    async def list_agents(self, user_id: str) -> list[AgentRecord]:
+        """Return user-facing agent records (``source='user'``).
+
+        Reads the per-user agent index Set to obtain all ids, fetches
+        each record individually, and **filters out team-spawned
+        workers** (``source='team'``) — those are scoped to a team
+        and only addressable via team detail / direct id lookup, not
+        enumerated as part of the user's regular agent list.
+
+        Records whose keys have expired or been deleted externally
+        are silently skipped.
+
+        Args:
+            user_id (`str`): The owner user id.
+
+        Returns:
+            `list[AgentRecord]`:
+                All ``source='user'`` agent records for the user.
+        """
+        index_key = self._key(self.key_config.agent_index, user_id=user_id)
+        ids = await self._client.smembers(index_key)
+        records = []
+        for agent_id in ids:
+            raw = await self._client.get(
+                self._key(
+                    self.key_config.agent,
+                    user_id=user_id,
+                    agent_id=agent_id,
+                ),
+            )
+            if raw:
+                record = AgentRecord.model_validate_json(raw)
+                if record.source == "user":
+                    records.append(record)
+        return records
+
+    async def get_agent(
+        self,
+        user_id: str,
+        agent_id: str,
+    ) -> AgentRecord | None:
+        """Fetch a single agent record by id."""
+        key = self._key(
+            self.key_config.agent,
+            user_id=user_id,
+            agent_id=agent_id,
+        )
+        raw = await self._client.get(key)
+        return AgentRecord.model_validate_json(raw) if raw else None
+
+    async def delete_agent(self, user_id: str, agent_id: str) -> bool:
+        """Delete an agent record and cascade-delete its sessions,
+        schedules, and any team back-references.
+
+        Cascade order:
+
+        1. **Sessions** — every session belonging to this agent is
+           deleted via :meth:`delete_session` (which itself cascades
+           message log, schedule-session index, and — if a session leads
+           a team — the team).
+        2. **Schedules** — every schedule whose ``data.agent_id`` matches
+           is deleted via :meth:`delete_schedule`.
+        3. **Team back-references (defensive)** — if the caller chose to
+           delete the agent directly instead of going through
+           :meth:`delete_team`, scan the user's teams and remove the
+           agent id from both the legacy :attr:`TeamData.member_ids`
+           list *and* the current :attr:`TeamData.members` list. The
+           normal path (``delete_team`` iterates members and calls
+           ``delete_agent`` / ``delete_session`` for each) does not
+           need this scan, but it keeps team records consistent if a
+           caller bypasses it. Applies to invited members too — a stale
+           entry pointing at a removed agent would otherwise poison
+           ``TeamSay`` routing.
+        4. **Agent record + index** — finally delete the agent key and
+           remove from the per-user agent index.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+            agent_id (`str`):
+                The id of the agent to delete.
+
+        Returns:
+            `bool`:
+                ``True`` if the agent record existed and was deleted,
+                ``False`` if it did not exist.
+        """
+        # Cascade: sessions
+        sessions = await self.list_sessions(user_id, agent_id)
+        for session in sessions:
+            await self.delete_session(user_id, agent_id, session.id)
+
+        # Cascade: schedules owned by this agent
+        schedules = await self.list_schedules(user_id)
+        for schedule in schedules:
+            if schedule.agent_id == agent_id:
+                await self.delete_schedule(user_id, schedule.id)
+
+        # Defensive: scrub agent_id from any team's member roster.
+        # Covers both the legacy ``member_ids`` field and the current
+        # ``members`` list (which additionally holds invited entries).
+        # The common path (delete_team -> delete_agent / delete_session)
+        # is unaffected because the team is being torn down anyway.
+        teams = await self.list_teams(user_id)
+        for team in teams:
+            dirty = False
+            if agent_id in team.data.member_ids:
+                team.data.member_ids = [
+                    mid for mid in team.data.member_ids if mid != agent_id
+                ]
+                dirty = True
+            filtered_members = [
+                m for m in team.data.members if m.agent_id != agent_id
+            ]
+            if len(filtered_members) != len(team.data.members):
+                team.data.members = filtered_members
+                dirty = True
+            if dirty:
+                await self.upsert_team(user_id, team)
+
+        key = self._key(
+            self.key_config.agent,
+            user_id=user_id,
+            agent_id=agent_id,
+        )
+        index_key = self._key(self.key_config.agent_index, user_id=user_id)
+        deleted = await self._client.delete(key)
+        await self._client.srem(index_key, agent_id)
+        return deleted > 0
+
+    async def upsert_session(
+        self,
+        user_id: str,
+        agent_id: str,
+        config: SessionConfig,
+        state: AgentState | None = None,
+        session_id: str | None = None,
+        source: SessionSource = SessionSource.USER,
+        source_schedule_id: str | None = None,
+    ) -> SessionRecord:
+        """Create or update a session for a (user, agent) pair.
+
+        When *session_id* is provided the existing session is updated.
+        When *session_id* is ``None`` a new session is always created.
+        """
+        if session_id:
+            key = self._key(
+                self.key_config.session,
+                user_id=user_id,
+                session_id=session_id,
+            )
+            raw = await self._client.get(key)
+            if raw:
+                record = SessionRecord.model_validate_json(raw)
+                record.config = config
+                if state is not None:
+                    record.state = state
+                record.updated_at = datetime.now()
+                await self._set_with_ttl(key, record.model_dump_json())
+                return record
+
+        # Use the caller-provided ``session_id`` when given so a
+        # "create-if-missing under this id" call (e.g. scheduler's
+        # stateful-mode session) lands at the expected key.
+        new_id_kwargs = {"id": session_id} if session_id else {}
+        record = SessionRecord(
+            user_id=user_id,
+            agent_id=agent_id,
+            config=config,
+            source=source,
+            source_schedule_id=source_schedule_id,
+            state=state if state is not None else AgentState(),
+            **new_id_kwargs,
+        )
+        key = self._key(
+            self.key_config.session,
+            user_id=user_id,
+            session_id=record.id,
+        )
+        index_key = self._key(
+            self.key_config.session_index,
+            user_id=user_id,
+            agent_id=agent_id,
+        )
+        await self._set_with_ttl(key, record.model_dump_json())
+        await self._client.sadd(index_key, record.id)
+
+        if source_schedule_id:
+            schedule_session_key = self._key(
+                self.key_config.schedule_session_index,
+                user_id=user_id,
+                schedule_id=source_schedule_id,
+            )
+            await self._client.sadd(schedule_session_key, record.id)
+
+        return record
+
+    async def update_session_state(
+        self,
+        user_id: str,
+        agent_id: str,
+        session_id: str,
+        state: AgentState,
+    ) -> None:
+        """Update only the mutable state of an existing session.
+
+        Raises:
+            KeyError: If the session does not exist.
+        """
+        key = self._key(
+            self.key_config.session,
+            user_id=user_id,
+            session_id=session_id,
+        )
+        raw = await self._client.get(key)
+        if not raw:
+            raise KeyError(f"Session {session_id!r} not found.")
+        record = SessionRecord.model_validate_json(raw)
+        record.state = state
+        record.updated_at = datetime.now()
+        await self._set_with_ttl(key, record.model_dump_json())
+
+    async def list_sessions(
+        self,
+        user_id: str,
+        agent_id: str,
+    ) -> list[SessionRecord]:
+        """Return all session records for a given (user, agent) pair.
+
+        Reads the per-agent session index Set to obtain all session ids, then
+        fetches each record individually. Records whose keys have expired or
+        been deleted externally are silently skipped.
+
+        Args:
+            user_id (`str`): The owner user id.
+            agent_id (`str`): The agent id whose sessions to list.
+
+        Returns:
+            `list[SessionRecord]`: All session records for the (user, agent)
+            pair.
+        """
+        index_key = self._key(
+            self.key_config.session_index,
+            user_id=user_id,
+            agent_id=agent_id,
+        )
+        ids = await self._client.smembers(index_key)
+        records = []
+        for session_id in ids:
+            raw = await self._client.get(
+                self._key(
+                    self.key_config.session,
+                    user_id=user_id,
+                    session_id=session_id,
+                ),
+            )
+            if raw:
+                records.append(SessionRecord.model_validate_json(raw))
+        records.sort(key=lambda r: r.created_at, reverse=True)
+        return records
+
+    async def get_session(
+        self,
+        user_id: str,
+        agent_id: str,
+        session_id: str,
+    ) -> SessionRecord | None:
+        """Fetch a single session record by id."""
+        key = self._key(
+            self.key_config.session,
+            user_id=user_id,
+            session_id=session_id,
+        )
+        raw = await self._client.get(key)
+        if not raw:
+            return None
+        return SessionRecord.model_validate_json(raw)
+
+    async def delete_session(
+        self,
+        user_id: str,
+        agent_id: str,
+        session_id: str,
+    ) -> bool:
+        """Delete a session record and cascade clean-up.
+
+        Cascades:
+
+        - Existing: per-session message log, schedule-session index entry.
+        - **NEW**: if this session is the leader of a team (``team_id``
+          set AND a :class:`TeamRecord` exists with
+          ``session_id == this session_id``), call :meth:`delete_team`
+          first. ``delete_team`` will recursively cascade workers and
+          clear ``team_id`` on this session — that clear is idempotent
+          and the session itself is deleted right after, so the order is
+          safe.
+
+        Worker sessions (``team_id`` set, but the team's
+        ``leader_session_id`` is **not** this session) are deleted
+        without dissolving the team — the team and the surviving leader
+        keep their member_ids list pointing to the now-orphaned worker
+        agent. This intentional asymmetry mirrors SQL: there is no FK
+        from :class:`SessionRecord` back to the agent that owns it, so
+        deleting a session doesn't automatically delete the agent.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+            agent_id (`str`):
+                The id of the agent that owns the session (used to
+                clean up the per-agent session index).
+            session_id (`str`):
+                The id of the session to delete.
+
+        Returns:
+            `bool`:
+                ``True`` if the session existed and was deleted,
+                ``False`` if no record was found.
+        """
+        key = self._key(
+            self.key_config.session,
+            user_id=user_id,
+            session_id=session_id,
+        )
+        raw = await self._client.get(key)
+        if not raw:
+            return False
+
+        record = SessionRecord.model_validate_json(raw)
+
+        # Cascade: if this session leads a team, dissolve it first.
+        if record.team_id:
+            team = await self.get_team(user_id, record.team_id)
+            if team is not None and team.session_id == session_id:
+                await self.delete_team(user_id, record.team_id)
+
+        index_key = self._key(
+            self.key_config.session_index,
+            user_id=user_id,
+            agent_id=agent_id,
+        )
+        msg_key = self._key(
+            self.key_config.messages,
+            user_id=user_id,
+            session_id=session_id,
+        )
+        await self._client.delete(key)
+        await self._client.srem(index_key, session_id)
+        await self._client.delete(msg_key)
+
+        if record.source_schedule_id:
+            schedule_session_key = self._key(
+                self.key_config.schedule_session_index,
+                user_id=user_id,
+                schedule_id=record.source_schedule_id,
+            )
+            await self._client.srem(schedule_session_key, session_id)
+
+        return True
+
+    async def list_sessions_by_schedule(
+        self,
+        user_id: str,
+        schedule_id: str,
+    ) -> list[SessionRecord]:
+        """Return all sessions created by a given schedule."""
+        schedule_session_key = self._key(
+            self.key_config.schedule_session_index,
+            user_id=user_id,
+            schedule_id=schedule_id,
+        )
+        ids = await self._client.smembers(schedule_session_key)
+        records = []
+        for session_id in ids:
+            raw = await self._client.get(
+                self._key(
+                    self.key_config.session,
+                    user_id=user_id,
+                    session_id=session_id,
+                ),
+            )
+            if raw:
+                records.append(SessionRecord.model_validate_json(raw))
+        records.sort(key=lambda r: r.created_at, reverse=True)
+        return records
+
+    async def upsert_schedule(
+        self,
+        user_id: str,
+        record: ScheduleRecord,
+    ) -> str:
+        """Persist a cron task record and register it in the user and global
+        indexes."""
+        key = self._key(
+            self.key_config.schedule,
+            user_id=user_id,
+            schedule_id=record.id,
+        )
+        index_key = self._key(self.key_config.schedule_index, user_id=user_id)
+        await self._set_with_ttl(key, record.model_dump_json())
+        await self._client.sadd(index_key, record.id)
+        await self._client.sadd(
+            self.key_config.schedule_global_index,
+            f"{user_id}:{record.id}",
+        )
+        return record.id
+
+    async def get_schedule(
+        self,
+        user_id: str,
+        schedule_id: str,
+    ) -> ScheduleRecord | None:
+        """Fetch a single cron task record by id."""
+        key = self._key(
+            self.key_config.schedule,
+            user_id=user_id,
+            schedule_id=schedule_id,
+        )
+        raw = await self._client.get(key)
+        if not raw:
+            return None
+        return ScheduleRecord.model_validate_json(raw)
+
+    async def list_schedules(self, user_id: str) -> list[ScheduleRecord]:
+        """Return all cron task records belonging to the given user."""
+        index_key = self._key(
+            self.key_config.schedule_index,
+            user_id=user_id,
+        )
+        ids = await self._client.smembers(index_key)
+        records = []
+        for schedule_id in ids:
+            raw = await self._client.get(
+                self._key(
+                    self.key_config.schedule,
+                    user_id=user_id,
+                    schedule_id=schedule_id,
+                ),
+            )
+            if raw:
+                records.append(ScheduleRecord.model_validate_json(raw))
+        return records
+
+    async def delete_schedule(self, user_id: str, schedule_id: str) -> bool:
+        """Delete a cron task record, cascade-delete its execution sessions,
+        and remove it from the user and global indexes."""
+        key = self._key(
+            self.key_config.schedule,
+            user_id=user_id,
+            schedule_id=schedule_id,
+        )
+        raw = await self._client.get(key)
+        if not raw:
+            return False
+
+        record = ScheduleRecord.model_validate_json(raw)
+
+        # Cascade: delete all sessions created by this schedule
+        sessions = await self.list_sessions_by_schedule(user_id, schedule_id)
+        for session in sessions:
+            await self.delete_session(
+                user_id,
+                record.agent_id,
+                session.id,
+            )
+
+        # Clean up the schedule session index key itself
+        schedule_session_key = self._key(
+            self.key_config.schedule_session_index,
+            user_id=user_id,
+            schedule_id=schedule_id,
+        )
+        await self._client.delete(schedule_session_key)
+
+        # Delete the schedule record and its index entries
+        index_key = self._key(self.key_config.schedule_index, user_id=user_id)
+        await self._client.delete(key)
+        await self._client.srem(index_key, schedule_id)
+        await self._client.srem(
+            self.key_config.schedule_global_index,
+            f"{user_id}:{schedule_id}",
+        )
+        return True
+
+    async def list_all_schedules(self) -> list[ScheduleRecord]:
+        """Return every schedule record across all users.
+
+        Reads the global schedule index (a Redis Set of ``user_id:schedule_id``
+        pairs) and fetches each record individually.  Records whose keys have
+        expired or been deleted externally are silently skipped.
+
+        Returns:
+            `list[ScheduleRecord]`: All schedule records in the store.
+        """
+        entries = await self._client.smembers(
+            self.key_config.schedule_global_index,
+        )
+        records = []
+        for entry in entries:
+            user_id, schedule_id = entry.split(":", 1)
+            raw = await self._client.get(
+                self._key(
+                    self.key_config.schedule,
+                    user_id=user_id,
+                    schedule_id=schedule_id,
+                ),
+            )
+            if raw:
+                records.append(ScheduleRecord.model_validate_json(raw))
+        return records
+
+    # ------------------------------------------------------------------
+    # Message persistence
+    # ------------------------------------------------------------------
+
+    def _message_key(self, user_id: str, session_id: str) -> str:
+        """Return the Redis List key for a session's messages."""
+        return self._key(
+            self.key_config.messages,
+            user_id=user_id,
+            session_id=session_id,
+        )
+
+    async def upsert_message(
+        self,
+        user_id: str,
+        session_id: str,
+        msg: Msg,
+    ) -> None:
+        """Persist a message to the session's message list."""
+        key = self._message_key(user_id, session_id)
+        last_raw = await self._client.lindex(key, -1)
+        if last_raw:
+            last_msg = Msg.model_validate_json(last_raw)
+            if last_msg.id == msg.id:
+                await self._client.lset(key, -1, msg.model_dump_json())
+                await self._refresh_key_ttl(key)
+                return
+        await self._client.rpush(key, msg.model_dump_json())
+        await self._refresh_key_ttl(key)
+
+    async def get_message(
+        self,
+        user_id: str,
+        session_id: str,
+        message_id: str,
+    ) -> Msg | None:
+        """Fetch a single message by id from the session's message list."""
+        key = self._message_key(user_id, session_id)
+        length = await self._client.llen(key)
+        for i in range(length - 1, -1, -1):
+            raw = await self._client.lindex(key, i)
+            if raw:
+                msg = Msg.model_validate_json(raw)
+                if msg.id == message_id:
+                    return msg
+        return None
+
+    async def list_messages(
+        self,
+        user_id: str,
+        session_id: str,
+        offset: int = 0,
+        limit: int = 50,
+    ) -> list[Msg]:
+        """Return messages for a session with pagination."""
+        key = self._message_key(user_id, session_id)
+        raw_list = await self._client.lrange(key, offset, offset + limit - 1)
+        return [Msg.model_validate_json(raw) for raw in raw_list]
+
+    # ------------------------------------------------------------------
+    # Team persistence
+    # ------------------------------------------------------------------
+
+    async def upsert_team(
+        self,
+        user_id: str,
+        record: TeamRecord,
+    ) -> TeamRecord:
+        """Persist a team record and register it in the user's team index.
+
+        Args:
+            user_id (`str`):
+                The owner user id. Used to scope both the record key and
+                the per-user team index.
+            record (`TeamRecord`):
+                The team record to persist. Its ``id`` is used as the
+                primary key; an existing record with the same id is
+                overwritten. ``updated_at`` is refreshed to ``datetime.now()``
+                before writing.
+
+        Returns:
+            `TeamRecord`:
+                The stored record (with refreshed ``updated_at``).
+        """
+        record.updated_at = datetime.now()
+        key = self._key(
+            self.key_config.team,
+            user_id=user_id,
+            team_id=record.id,
+        )
+        index_key = self._key(self.key_config.team_index, user_id=user_id)
+        await self._set_with_ttl(key, record.model_dump_json())
+        await self._client.sadd(index_key, record.id)
+        return record
+
+    async def get_team(
+        self,
+        user_id: str,
+        team_id: str,
+    ) -> TeamRecord | None:
+        """Fetch a single team record by id.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+            team_id (`str`):
+                The team id to look up.
+
+        Returns:
+            `TeamRecord | None`:
+                The record, or ``None`` if no record exists at the
+                ``(user_id, team_id)`` key (e.g. expired or never created).
+        """
+        key = self._key(
+            self.key_config.team,
+            user_id=user_id,
+            team_id=team_id,
+        )
+        raw = await self._client.get(key)
+        if not raw:
+            return None
+        return TeamRecord.model_validate_json(raw)
+
+    async def list_teams(self, user_id: str) -> list[TeamRecord]:
+        """Return all team records belonging to the given user.
+
+        Reads the per-user team index (a Redis Set of team ids) and fetches
+        each record individually. Records whose keys have expired or been
+        deleted externally are silently skipped.
+
+        Args:
+            user_id (`str`):
+                The owner user id whose teams to list.
+
+        Returns:
+            `list[TeamRecord]`:
+                All team records for the user, in arbitrary order (the
+                index is a Set).
+        """
+        index_key = self._key(self.key_config.team_index, user_id=user_id)
+        ids = await self._client.smembers(index_key)
+        records: list[TeamRecord] = []
+        for team_id in ids:
+            raw = await self._client.get(
+                self._key(
+                    self.key_config.team,
+                    user_id=user_id,
+                    team_id=team_id,
+                ),
+            )
+            if raw:
+                records.append(TeamRecord.model_validate_json(raw))
+        return records
+
+    async def set_session_team_id(
+        self,
+        user_id: str,
+        session_id: str,
+        team_id: str | None,
+    ) -> None:
+        """Set or clear ``team_id`` on an existing session record.
+
+        Bypasses :meth:`upsert_session` because that method does not
+        allow writing ``team_id`` (which is a relation column the
+        application normally only mutates via team operations).
+        Idempotent: a no-op if the session does not exist or already
+        holds the given value.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+            session_id (`str`):
+                The session whose ``team_id`` should be updated.
+            team_id (`str | None`):
+                The new value. ``None`` detaches the session from any
+                team (used by :meth:`delete_team` and by the team
+                service when a session leaves a team).
+        """
+        key = self._key(
+            self.key_config.session,
+            user_id=user_id,
+            session_id=session_id,
+        )
+        raw = await self._client.get(key)
+        if not raw:
+            return
+        record = SessionRecord.model_validate_json(raw)
+        if record.team_id == team_id:
+            return
+        record.team_id = team_id
+        record.updated_at = datetime.now()
+        await self._set_with_ttl(key, record.model_dump_json())
+
+    async def delete_team(self, user_id: str, team_id: str) -> bool:
+        """Delete a team record and cascade-clean its members by role.
+
+        Cascade order (mirrors what SQL's ``ON DELETE CASCADE`` would do
+        for the same set of foreign keys, but role-aware to honour the
+        ``AgentInvite`` semantics — see :class:`TeamMember`):
+
+        1. Materialise the member roster via
+           :func:`ensure_team_members` (which migrates legacy
+           ``member_ids``-only records on first read). For each entry:
+
+           - ``role == "created"`` — the member was spawned by
+             ``AgentCreate`` and lives only for this team. Delete it in
+             full via :meth:`delete_agent`, which cascades that
+             worker's session.
+           - ``role == "invited"`` — the member is a pre-existing
+             user-owned agent that was borrowed via ``AgentInvite``.
+             Only remove the team-scoped session via
+             :meth:`delete_session`; the underlying
+             :class:`AgentRecord` and its other sessions must survive.
+
+        2. Clear ``team_id`` on the leader session (referenced by
+           :attr:`TeamRecord.session_id`) — semantically equivalent to
+           ``ON DELETE SET NULL`` for that direction of the relationship.
+           Idempotent if the session has already been deleted (no-op).
+        3. Delete the :class:`TeamRecord` key and remove it from the
+           per-user team index.
+
+        The cascade is best-effort: Redis has no cross-key transaction,
+        so a process crash mid-cascade may leave residue. Each step is
+        idempotent so retries are safe.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+            team_id (`str`):
+                The id of the team to delete.
+
+        Returns:
+            `bool`:
+                ``True`` if the team record existed and was deleted,
+                ``False`` if no record was found at the
+                ``(user_id, team_id)`` key.
+        """
+        # Local import to avoid a top-level cycle between _utils (which
+        # imports TeamMember from _model) and _base (which imports the
+        # abstract StorageBase from this module hierarchy).
+        from ._utils import _ensure_team_members
+
+        team = await self.get_team(user_id, team_id)
+        if team is None:
+            # Make sure the index is also clean if the record vanished
+            # for any reason.
+            index_key = self._key(self.key_config.team_index, user_id=user_id)
+            await self._client.srem(index_key, team_id)
+            return False
+
+        # Role-aware member cleanup — see docstring above.
+        members = await _ensure_team_members(self, user_id, team)
+        for member in members:
+            if member.role == "created":
+                await self.delete_agent(member.owner_id, member.agent_id)
+            else:  # invited
+                await self.delete_session(
+                    member.owner_id,
+                    member.agent_id,
+                    member.session_id,
+                )
+
+        # Clear team_id on the leader session (idempotent)
+        await self.set_session_team_id(user_id, team.session_id, None)
+
+        # Delete the TeamRecord key + index entry
+        key = self._key(
+            self.key_config.team,
+            user_id=user_id,
+            team_id=team_id,
+        )
+        existed = await self._client.delete(key)
+        index_key = self._key(self.key_config.team_index, user_id=user_id)
+        await self._client.srem(index_key, team_id)
+        return bool(existed)
+
+    # ------------------------------------------------------------------
+    # Knowledge base persistence
+    # ------------------------------------------------------------------
+
+    async def upsert_knowledge_base(
+        self,
+        user_id: str,
+        record: KnowledgeBaseRecord,
+    ) -> KnowledgeBaseRecord:
+        """Persist a knowledge base record and register it in the user index.
+
+        If a record with the same ``id`` already exists it is overwritten
+        and ``updated_at`` is refreshed; ``created_at`` is preserved.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+            record (`KnowledgeBaseRecord`):
+                The fully-populated record to store.
+
+        Returns:
+            `KnowledgeBaseRecord`:
+                The stored record (with ``updated_at`` refreshed).
+        """
+        if record.user_id != user_id:
+            raise ValueError(
+                "record.user_id does not match the given user_id.",
+            )
+
+        key = self._key(
+            self.key_config.knowledge_base,
+            user_id=user_id,
+            knowledge_base_id=record.id,
+        )
+        existing_raw = await self._client.get(key)
+        if existing_raw:
+            existing = KnowledgeBaseRecord.model_validate_json(existing_raw)
+            record.created_at = existing.created_at
+        record.updated_at = datetime.now()
+
+        index_key = self._key(
+            self.key_config.knowledge_base_index,
+            user_id=user_id,
+        )
+        await self._set_with_ttl(key, record.model_dump_json())
+        await self._client.sadd(index_key, record.id)
+        return record
+
+    async def get_knowledge_base(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+    ) -> KnowledgeBaseRecord | None:
+        """Fetch a single knowledge base record by id.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+            knowledge_base_id (`str`):
+                The knowledge base id.
+
+        Returns:
+            `KnowledgeBaseRecord | None`:
+                The record, or ``None`` if not found.
+        """
+        key = self._key(
+            self.key_config.knowledge_base,
+            user_id=user_id,
+            knowledge_base_id=knowledge_base_id,
+        )
+        raw = await self._client.get(key)
+        return KnowledgeBaseRecord.model_validate_json(raw) if raw else None
+
+    async def list_knowledge_bases(
+        self,
+        user_id: str,
+    ) -> list[KnowledgeBaseRecord]:
+        """List all knowledge base records belonging to the given user.
+
+        Reads the per-user knowledge base index Set to obtain all ids,
+        then fetches each record individually. Records whose keys have
+        expired or been deleted externally are silently skipped.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+
+        Returns:
+            `list[KnowledgeBaseRecord]`:
+                All knowledge base records for the user.
+        """
+        index_key = self._key(
+            self.key_config.knowledge_base_index,
+            user_id=user_id,
+        )
+        ids = await self._client.smembers(index_key)
+        records: list[KnowledgeBaseRecord] = []
+        for kb_id in ids:
+            raw = await self._client.get(
+                self._key(
+                    self.key_config.knowledge_base,
+                    user_id=user_id,
+                    knowledge_base_id=kb_id,
+                ),
+            )
+            if raw:
+                records.append(
+                    KnowledgeBaseRecord.model_validate_json(raw),
+                )
+        return records
+
+    async def delete_knowledge_base(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+    ) -> bool:
+        """Delete a knowledge base record and remove it from the index.
+
+        Cascades the per-knowledge-base document index: every
+        :class:`KnowledgeDocumentRecord` indexed under the KB is
+        removed from storage so no orphan documents survive the KB
+        deletion.  Cleanup of the underlying vector store collection
+        and blob payloads remains the caller's responsibility (the
+        manager + the blob store, respectively).
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+            knowledge_base_id (`str`):
+                The id of the record to delete.
+
+        Returns:
+            `bool`:
+                ``True`` if the record existed and was deleted,
+                ``False`` if not found.
+        """
+        # Cascade: drop every document record so the sweeper does not
+        # later try to redispatch leases for a KB that no longer exists.
+        documents = await self.list_knowledge_documents(
+            user_id,
+            knowledge_base_id,
+        )
+        for document in documents:
+            await self.delete_knowledge_document(
+                user_id,
+                knowledge_base_id,
+                document.id,
+            )
+
+        key = self._key(
+            self.key_config.knowledge_base,
+            user_id=user_id,
+            knowledge_base_id=knowledge_base_id,
+        )
+        index_key = self._key(
+            self.key_config.knowledge_base_index,
+            user_id=user_id,
+        )
+        deleted = await self._client.delete(key)
+        await self._client.srem(index_key, knowledge_base_id)
+        return deleted > 0
+
+    # ------------------------------------------------------------------
+    # Knowledge document persistence
+    # ------------------------------------------------------------------
+
+    def _document_key(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+        document_id: str,
+    ) -> str:
+        """Format the Redis key for one document record."""
+        return self._key(
+            self.key_config.knowledge_document,
+            user_id=user_id,
+            knowledge_base_id=knowledge_base_id,
+            document_id=document_id,
+        )
+
+    def _document_index_key(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+    ) -> str:
+        """Format the per-KB document index Set key."""
+        return self._key(
+            self.key_config.knowledge_document_index,
+            user_id=user_id,
+            knowledge_base_id=knowledge_base_id,
+        )
+
+    def _document_global_token(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+        document_id: str,
+    ) -> str:
+        """Encode (user_id, kb_id, doc_id) for the global sweeper index."""
+        return f"{user_id}:{knowledge_base_id}:{document_id}"
+
+    async def upsert_knowledge_document(
+        self,
+        user_id: str,
+        record: KnowledgeDocumentRecord,
+    ) -> KnowledgeDocumentRecord:
+        """Persist a document record and update its indexes.
+
+        If a record with the same ``id`` already exists it is
+        overwritten and ``updated_at`` refreshed; ``created_at`` is
+        preserved.
+
+        Args:
+            user_id (`str`):
+                The owner user id.  Must match ``record.user_id``.
+            record (`KnowledgeDocumentRecord`):
+                The fully-populated record to persist.
+
+        Returns:
+            `KnowledgeDocumentRecord`:
+                The stored record (with ``updated_at`` refreshed).
+        """
+        if record.user_id != user_id:
+            raise ValueError(
+                "record.user_id does not match the given user_id.",
+            )
+
+        key = self._document_key(
+            user_id,
+            record.knowledge_base_id,
+            record.id,
+        )
+        existing_raw = await self._client.get(key)
+        if existing_raw:
+            existing = KnowledgeDocumentRecord.model_validate_json(
+                existing_raw,
+            )
+            record.created_at = existing.created_at
+        record.updated_at = datetime.now()
+
+        await self._set_with_ttl(key, record.model_dump_json())
+        await self._client.sadd(
+            self._document_index_key(user_id, record.knowledge_base_id),
+            record.id,
+        )
+        await self._client.sadd(
+            self.key_config.knowledge_document_global_index,
+            self._document_global_token(
+                user_id,
+                record.knowledge_base_id,
+                record.id,
+            ),
+        )
+        return record
+
+    async def get_knowledge_document(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+        document_id: str,
+    ) -> KnowledgeDocumentRecord | None:
+        """Fetch a single knowledge document record by id."""
+        raw = await self._client.get(
+            self._document_key(user_id, knowledge_base_id, document_id),
+        )
+        return (
+            KnowledgeDocumentRecord.model_validate_json(raw) if raw else None
+        )
+
+    async def list_knowledge_documents(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+    ) -> list[KnowledgeDocumentRecord]:
+        """List all documents in a knowledge base.
+
+        Reads the per-KB document index Set and fetches each record.
+        Records whose keys have expired or been deleted externally are
+        silently skipped.
+        """
+        ids = await self._client.smembers(
+            self._document_index_key(user_id, knowledge_base_id),
+        )
+        records: list[KnowledgeDocumentRecord] = []
+        for document_id in ids:
+            raw = await self._client.get(
+                self._document_key(user_id, knowledge_base_id, document_id),
+            )
+            if raw:
+                records.append(
+                    KnowledgeDocumentRecord.model_validate_json(raw),
+                )
+        return records
+
+    async def delete_knowledge_document(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+        document_id: str,
+    ) -> bool:
+        """Delete a document record and remove it from the indexes."""
+        key = self._document_key(user_id, knowledge_base_id, document_id)
+        deleted = await self._client.delete(key)
+        await self._client.srem(
+            self._document_index_key(user_id, knowledge_base_id),
+            document_id,
+        )
+        await self._client.srem(
+            self.key_config.knowledge_document_global_index,
+            self._document_global_token(
+                user_id,
+                knowledge_base_id,
+                document_id,
+            ),
+        )
+        return deleted > 0
+
+    async def update_knowledge_document_status(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+        document_id: str,
+        status: KnowledgeDocumentStatus,
+        error: str | None = None,
+        chunk_count: int | None = None,
+    ) -> None:
+        """Update only the status-related fields of a document record.
+
+        Reads the record, mutates the status fields in memory, and
+        writes it back.  Not atomic across multiple writers — relies
+        on the indexing worker holding the lease, which serialises
+        status transitions for a single document.
+        """
+        key = self._document_key(user_id, knowledge_base_id, document_id)
+        raw = await self._client.get(key)
+        if not raw:
+            return
+        record = KnowledgeDocumentRecord.model_validate_json(raw)
+        record.data.status = status
+        if error is not None:
+            record.data.error = error
+        if chunk_count is not None:
+            record.data.chunk_count = chunk_count
+        record.updated_at = datetime.now()
+        await self._set_with_ttl(key, record.model_dump_json())
+
+    async def acquire_knowledge_document_lease(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+        document_id: str,
+        processing_node: str,
+        lease_ttl: timedelta,
+        now: datetime | None = None,
+    ) -> bool:
+        """Compare-and-swap acquisition of the processing lease.
+
+        Implementation is a read-modify-write under a per-document
+        ``WATCH`` so two workers racing on the same document cannot
+        both win.  Redis ``WATCH`` aborts the transaction if the key
+        changes between WATCH and EXEC; we retry a few times on
+        ``WatchError`` and otherwise give up (treating the contention
+        as "someone else already holds the lease").
+        """
+        now = now or datetime.now()
+        new_deadline = now + lease_ttl
+
+        async with self._client.pipeline(transaction=True) as pipe:
+            for _ in range(3):
+                try:
+                    key = self._document_key(
+                        user_id,
+                        knowledge_base_id,
+                        document_id,
+                    )
+                    await pipe.watch(key)
+                    raw = await pipe.get(key)
+                    if not raw:
+                        await pipe.unwatch()
+                        return False
+                    record = KnowledgeDocumentRecord.model_validate_json(raw)
+                    holder = record.processing_node
+                    deadline = record.data.lease_expires_at
+                    if (
+                        holder is not None
+                        and deadline is not None
+                        and deadline > now
+                    ):
+                        await pipe.unwatch()
+                        return False
+                    record.processing_node = processing_node
+                    record.data.lease_expires_at = new_deadline
+                    record.updated_at = now
+                    pipe.multi()
+                    pipe.set(key, record.model_dump_json())
+                    if self.key_ttl is not None:
+                        pipe.expire(key, self.key_ttl)
+                    await pipe.execute()
+                    return True
+                except _watch_error():
+                    # Another writer touched the key between WATCH and
+                    # EXEC; loop and re-read.
+                    continue
+            return False
+
+    async def renew_knowledge_document_lease(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+        document_id: str,
+        processing_node: str,
+        lease_ttl: timedelta,
+        now: datetime | None = None,
+    ) -> bool:
+        """Extend the lease this worker already holds."""
+        now = now or datetime.now()
+        new_deadline = now + lease_ttl
+
+        async with self._client.pipeline(transaction=True) as pipe:
+            for _ in range(3):
+                try:
+                    key = self._document_key(
+                        user_id,
+                        knowledge_base_id,
+                        document_id,
+                    )
+                    await pipe.watch(key)
+                    raw = await pipe.get(key)
+                    if not raw:
+                        await pipe.unwatch()
+                        return False
+                    record = KnowledgeDocumentRecord.model_validate_json(raw)
+                    if record.processing_node != processing_node:
+                        await pipe.unwatch()
+                        return False
+                    record.data.lease_expires_at = new_deadline
+                    record.updated_at = now
+                    pipe.multi()
+                    pipe.set(key, record.model_dump_json())
+                    if self.key_ttl is not None:
+                        pipe.expire(key, self.key_ttl)
+                    await pipe.execute()
+                    return True
+                except _watch_error():
+                    continue
+            return False
+
+    async def release_knowledge_document_lease(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+        document_id: str,
+        processing_node: str,
+    ) -> None:
+        """Release the lease only if this worker still owns it."""
+        async with self._client.pipeline(transaction=True) as pipe:
+            for _ in range(3):
+                try:
+                    key = self._document_key(
+                        user_id,
+                        knowledge_base_id,
+                        document_id,
+                    )
+                    await pipe.watch(key)
+                    raw = await pipe.get(key)
+                    if not raw:
+                        await pipe.unwatch()
+                        return
+                    record = KnowledgeDocumentRecord.model_validate_json(raw)
+                    if record.processing_node != processing_node:
+                        await pipe.unwatch()
+                        return
+                    record.processing_node = None
+                    record.data.lease_expires_at = None
+                    record.updated_at = datetime.now()
+                    pipe.multi()
+                    pipe.set(key, record.model_dump_json())
+                    if self.key_ttl is not None:
+                        pipe.expire(key, self.key_ttl)
+                    await pipe.execute()
+                    return
+                except _watch_error():
+                    continue
+
+    async def list_knowledge_documents_with_expired_lease(
+        self,
+        now: datetime | None = None,
+    ) -> list[KnowledgeDocumentRecord]:
+        """Return non-terminal documents whose lease has expired.
+
+        Reads the global document index and filters in-memory — there
+        is no Redis-side filter primitive that knows about our nested
+        ``data.lease_expires_at`` field.  For production deployments
+        with very large document counts a secondary index would pay
+        off, but for the v1 workload the global scan is acceptable
+        because the sweep runs on a slow cadence (minutes) and only
+        cares about the small subset of non-terminal documents.
+        """
+        now = now or datetime.now()
+        terminal = {"ready", "error"}
+        tokens = await self._client.smembers(
+            self.key_config.knowledge_document_global_index,
+        )
+        records: list[KnowledgeDocumentRecord] = []
+        for token in tokens:
+            try:
+                user_id, kb_id, document_id = token.split(":", 2)
+            except ValueError:
+                continue
+            raw = await self._client.get(
+                self._document_key(user_id, kb_id, document_id),
+            )
+            if not raw:
+                continue
+            record = KnowledgeDocumentRecord.model_validate_json(raw)
+            if record.data.status in terminal:
+                continue
+            if record.processing_node is None:
+                continue
+            if (
+                record.data.lease_expires_at is not None
+                and record.data.lease_expires_at < now
+            ):
+                records.append(record)
+        return records
+
+    async def list_knowledge_documents_pending_since(
+        self,
+        threshold: datetime,
+    ) -> list[KnowledgeDocumentRecord]:
+        """Return documents stuck in ``pending`` since before ``threshold``."""
+        tokens = await self._client.smembers(
+            self.key_config.knowledge_document_global_index,
+        )
+        records: list[KnowledgeDocumentRecord] = []
+        for token in tokens:
+            try:
+                user_id, kb_id, document_id = token.split(":", 2)
+            except ValueError:
+                continue
+            raw = await self._client.get(
+                self._document_key(user_id, kb_id, document_id),
+            )
+            if not raw:
+                continue
+            record = KnowledgeDocumentRecord.model_validate_json(raw)
+            if record.data.status != "pending":
+                continue
+            if record.created_at < threshold:
+                records.append(record)
+        return records
diff --git a/src/agentscope/app/storage/_utils.py b/src/agentscope/app/storage/_utils.py
new file mode 100644
index 0000000..40bf22f
--- /dev/null
+++ b/src/agentscope/app/storage/_utils.py
@@ -0,0 +1,107 @@
+# -*- coding: utf-8 -*-
+"""The utils for storage."""
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel, SecretStr
+
+from ._model import TeamMember
+
+if TYPE_CHECKING:
+    from ._base import StorageBase
+    from ._model import TeamRecord
+
+
+def _dump_with_secrets(model: BaseModel) -> dict:
+    """Dump the BaseModel instance with SecretStr fields. Used for
+    storage.
+
+    Args:
+        model (`BaseModel`):
+            The model instance to dump.
+
+    Returns:
+        `dict`:
+            The dumped JSON with secrets included.
+    """
+    # Use mode='json' so that Pydantic converts non-JSON-native types
+    # (e.g. datetime, UUID) to their JSON-compatible representations.
+    # SecretStr fields will be masked at this step.
+    result = model.model_dump(mode="json")
+
+    for field_name, _ in model.__class__.model_fields.items():
+        value = getattr(model, field_name)
+        if isinstance(value, SecretStr):
+            result[field_name] = value.get_secret_value()
+
+    return result
+
+
+async def _ensure_team_members(
+    storage: "StorageBase",
+    user_id: str,
+    team: "TeamRecord",
+) -> list[TeamMember]:
+    """Return the team's members, lazily migrating legacy ``member_ids``.
+
+    Before ``AgentInvite`` existed, ``TeamData`` only stored a flat list
+    of worker agent ids in :attr:`~TeamData.member_ids`; each such worker
+    was ``source='team'`` with a 1:1 agent-to-session mapping, so the
+    session could be recovered on demand via ``list_sessions``. With
+    invited members the shape no longer fits: an invited agent has
+    multiple sessions of its own, only one of which belongs to the team.
+
+    This helper is the single read path. If :attr:`TeamData.members` is
+    already populated it is returned verbatim (idempotent fast path).
+    Otherwise, it rebuilds the roster from ``member_ids`` — each legacy
+    entry is tagged ``role="created"`` — persists it back via
+    :meth:`StorageBase.upsert_team`, and returns the new list. A
+    ``member_id`` whose sole session has been deleted out from under
+    the team is dropped from the migrated roster (nothing to route to
+    anyway).
+
+    Args:
+        storage (`StorageBase`):
+            Storage backend used for the session lookups and the
+            optional writeback.
+        user_id (`str`):
+            The team owner.
+        team (`TeamRecord`):
+            The team record to inspect (and mutate in place on migration).
+
+    Returns:
+        `list[TeamMember]`:
+            The team's current roster.
+    """
+    if team.data.members:
+        return team.data.members
+
+    if not team.data.member_ids:
+        return []
+
+    migrated: list[TeamMember] = []
+    for agent_id in team.data.member_ids:
+        sessions = await storage.list_sessions(user_id, agent_id)
+        if not sessions:
+            # Session already deleted — nothing sensible to route to.
+            continue
+        migrated.append(
+            TeamMember(
+                owner_id=user_id,
+                agent_id=agent_id,
+                session_id=sessions[0].id,
+                role="created",
+            ),
+        )
+
+    team.data.members = migrated
+    # Sync the legacy list to match. Dropping entries with no surviving
+    # session from ``members`` without also removing them from
+    # ``member_ids`` would leave the two disagreeing, and would cause
+    # this migration to re-run on every future read whenever the
+    # migrated result is empty (empty ``members`` fails the fast-path
+    # truthiness check, so we would fall through here again). Writing
+    # ``member_ids`` to match ``migrated`` keeps the record consistent
+    # and terminates the migration.
+    team.data.member_ids = [m.agent_id for m in migrated]
+    await storage.upsert_team(user_id, team)
+    return migrated
diff --git a/src/agentscope/app/workspace_manager/__init__.py b/src/agentscope/app/workspace_manager/__init__.py
new file mode 100644
index 0000000..dcd6bef
--- /dev/null
+++ b/src/agentscope/app/workspace_manager/__init__.py
@@ -0,0 +1,20 @@
+# -*- coding: utf-8 -*-
+"""The workspace manager classes, responsible for managing the resources
+and their lifecycles, and filesystem isolation."""
+
+from ._base import IsolationPolicy, WorkspaceManagerBase
+from ._local_workspace_manager import LocalWorkspaceManager
+from ._docker_workspace_manager import DockerWorkspaceManager
+from ._e2b_workspace_manager import E2BWorkspaceManager
+from ._k8s_workspace_manager import K8sWorkspaceManager
+from ._opensandbox_workspace_manager import OpenSandboxWorkspaceManager
+
+__all__ = [
+    "IsolationPolicy",
+    "WorkspaceManagerBase",
+    "LocalWorkspaceManager",
+    "DockerWorkspaceManager",
+    "E2BWorkspaceManager",
+    "K8sWorkspaceManager",
+    "OpenSandboxWorkspaceManager",
+]
diff --git a/src/agentscope/app/workspace_manager/_base.py b/src/agentscope/app/workspace_manager/_base.py
new file mode 100644
index 0000000..2a6ba1e
--- /dev/null
+++ b/src/agentscope/app/workspace_manager/_base.py
@@ -0,0 +1,138 @@
+# -*- coding: utf-8 -*-
+"""Workspace manager implementations."""
+
+import hashlib
+from abc import ABC, abstractmethod
+from enum import StrEnum
+from typing import Self
+
+from ..._utils._common import _generate_id
+from ...workspace import WorkspaceBase
+
+
+class IsolationPolicy(StrEnum):
+    """Workspace isolation grain for
+    :meth:`WorkspaceManagerBase.assign_workspace_id`.
+    """
+
+    PER_SESSION = "per_session"
+    PER_AGENT = "per_agent"
+    PER_USER = "per_user"
+
+
+class WorkspaceManagerBase(ABC):
+    """Abstract base for workspace managers.
+
+    Subclasses are expected to be used as async context managers — entering
+    the context activates any background machinery the subclass needs (e.g.
+    a TTL sweeper task) and exiting it tears that machinery down and closes
+    every cached workspace via :meth:`close_all`.
+
+    The default ``__aenter__`` / ``__aexit__`` cover the common case where a
+    subclass has no background machinery: enter is a no-op, exit just calls
+    :meth:`close_all`. Subclasses that own background tasks should override
+    both.
+    """
+
+    def __init__(
+        self,
+        *,
+        isolation: IsolationPolicy = IsolationPolicy.PER_AGENT,
+    ) -> None:
+        """Bind the isolation policy for :meth:`assign_workspace_id`.
+
+        Subclasses MUST forward ``isolation`` here via
+        ``super().__init__(isolation=isolation)``.
+
+        Args:
+            isolation (`IsolationPolicy`, defaults to `PER_AGENT`):
+                Isolation grain for the manager.
+        """
+        self._isolation: IsolationPolicy = isolation
+
+    def assign_workspace_id(
+        self,
+        *,
+        user_id: str,
+        agent_id: str,
+        session_id: str,
+    ) -> str:
+        """Mint a workspace id under :attr:`_isolation`.
+
+        Pure function — no I/O, no storage access. Called by the
+        session-creation flow when the caller did not supply an
+        explicit ``workspace_id``.
+
+        * ``PER_SESSION`` → fresh UUID.
+        * ``PER_AGENT`` → deterministic BLAKE2b of ``user::agent``.
+        * ``PER_USER`` → deterministic BLAKE2b of ``user::``.
+
+        Args:
+            user_id (`str`):
+                The owning user id.
+            agent_id (`str`):
+                The agent the session belongs to.
+            session_id (`str`):
+                The session id being provisioned (only used by the
+                per-session grain to underline its randomness).
+
+        Returns:
+            `str`:
+                A workspace id.
+        """
+        del session_id
+        if self._isolation is IsolationPolicy.PER_AGENT:
+            return hashlib.blake2b(
+                f"{user_id}::{agent_id}".encode("utf-8"),
+                digest_size=8,
+            ).hexdigest()
+        if self._isolation is IsolationPolicy.PER_USER:
+            return hashlib.blake2b(
+                f"user::{user_id}".encode("utf-8"),
+                digest_size=8,
+            ).hexdigest()
+        return _generate_id()
+
+    @abstractmethod
+    async def get_workspace(
+        self,
+        user_id: str,
+        agent_id: str,
+        session_id: str,
+        workspace_id: str | None = None,
+    ) -> WorkspaceBase:
+        """Return an initialized workspace.
+
+        Args:
+            user_id (`str`):
+                The user id.
+            agent_id (`str`):
+                The agent id.
+            session_id (`str`):
+                The session id.
+            workspace_id (`str | None`, optional):
+                Explicit workspace binding. ``None`` triggers
+                :meth:`assign_workspace_id` fallback — expected only
+                for callers without a persisted binding.
+        """
+
+    @abstractmethod
+    async def close(self, workspace_id: str) -> None:
+        """Close and evict a single workspace from the cache."""
+
+    @abstractmethod
+    async def close_all(self) -> None:
+        """Close every cached workspace.
+
+        Pure "close all currently tracked workspaces" semantics — does not
+        imply the manager itself is being torn down. Use ``async with`` (or
+        :meth:`__aexit__` directly) for full manager shutdown.
+        """
+
+    async def __aenter__(self) -> Self:
+        """Enter the manager's lifetime. Default is a no-op."""
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        """Exit the manager's lifetime — closes all cached workspaces."""
+        await self.close_all()
diff --git a/src/agentscope/app/workspace_manager/_docker_workspace_manager.py b/src/agentscope/app/workspace_manager/_docker_workspace_manager.py
new file mode 100644
index 0000000..ca7e144
--- /dev/null
+++ b/src/agentscope/app/workspace_manager/_docker_workspace_manager.py
@@ -0,0 +1,397 @@
+# -*- coding: utf-8 -*-
+"""DockerWorkspaceManager — lifecycle manager for :class:`DockerWorkspace`.
+
+Mirrors :class:`LocalWorkspaceManager` 1:1 in its public surface
+(``get_workspace`` / ``create_workspace`` / ``close`` / ``close_all``)
+so that callers — notably :class:`agentscope.app._service.ChatService` —
+do not branch on backend.
+
+Differences from the local manager (allowed to surface only via the
+constructor):
+
+* Workdir layout is two levels — ``<basedir>/<user_id>/<agent_id>`` —
+  and is bind-mounted to ``/workspace`` inside each container, so the
+  agent always sees a flat ``/workspace`` regardless of host layout.
+* ``workspace_id`` is forwarded into :class:`DockerWorkspace` so the
+  container name (``as_ws_<workspace_id>``) is stable across process
+  restarts. A cache miss after a restart deterministically re-attaches
+  to the same container slot via ``containers.create_or_replace``.
+* Idle workspaces are evicted by a dedicated background sweeper task
+  started in :meth:`__aenter__` and cancelled in :meth:`__aexit__` —
+  not lazily on each :meth:`get_workspace` call. This keeps idle
+  resource consumption bounded even when no traffic is arriving.
+* ``close_all`` shuts containers down in parallel
+  (:func:`asyncio.gather`) — Docker ``kill + delete`` is slow enough
+  that linear teardown on shutdown is noticeable.
+"""
+
+import asyncio
+import os
+import time
+from typing import Self
+
+from typing_extensions import deprecated
+
+from ..._logging import logger
+from ...mcp import MCPClient
+from ...workspace import DockerWorkspace
+from ...workspace._docker._make_dockerfile import (
+    DEFAULT_BASE_IMAGE,
+    DEFAULT_GATEWAY_PORT,
+)
+from ._base import WorkspaceManagerBase, IsolationPolicy
+
+DEFAULT_SWEEP_INTERVAL = 300.0
+
+
+class DockerWorkspaceManager(WorkspaceManagerBase):
+    """Manages :class:`DockerWorkspace` instances with TTL-based caching.
+
+    The manager owns a single set of image-build parameters
+    (``base_image`` / ``node_version`` / ``extra_pip``) shared by every
+    workspace it produces; the resulting image is content-hashed so
+    rebuilds are skipped on cache hits.
+
+    Use the manager as an ``async with`` context manager: entering it
+    starts the TTL sweeper task, exiting it stops the sweeper and then
+    closes every cached workspace via :meth:`close_all`.
+    """
+
+    def __init__(
+        self,
+        basedir: str,
+        *,
+        isolation: IsolationPolicy = IsolationPolicy.PER_AGENT,
+        base_image: str = DEFAULT_BASE_IMAGE,
+        node_version: str = "20",
+        extra_pip: list[str] | None = None,
+        gateway_port: int = DEFAULT_GATEWAY_PORT,
+        env: dict[str, str] | None = None,
+        default_mcps: list[MCPClient] | None = None,
+        skill_paths: list[str] | None = None,
+        ttl: float = 3600.0,
+        sweep_interval: float = DEFAULT_SWEEP_INTERVAL,
+    ) -> None:
+        """Initialize the docker workspace manager.
+
+        Args:
+            basedir (`str`):
+                Host root under which per-user/per-agent workdir are
+                created (``<basedir>/<user_id>/<agent_id>``). Each
+                workdir is bind-mounted to ``/workspace`` inside its
+                container.
+            isolation (`IsolationPolicy`, defaults to `PER_AGENT`):
+                Isolation grain for :meth:`assign_workspace_id`.
+                ``PER_SESSION`` → fresh UUID (one workspace per
+                session); ``PER_AGENT`` / ``PER_USER`` → deterministic
+                hash so sessions of the same (user, agent) or same
+                user share a workspace. Explicit ``workspace_id`` on
+                session creation always wins over this policy.
+            base_image (`str`, defaults to `DEFAULT_BASE_IMAGE`):
+                Base Docker image; must provide ``python3``.
+            node_version (`str`, defaults to `"20"`):
+                Major Node.js version (e.g. ``"20"``) to bake into
+                the image.
+            extra_pip (`list[str] | None`, optional):
+                Extra Python packages to install into the gateway
+                venv at image-build time.
+            gateway_port (`int`, defaults to `DEFAULT_GATEWAY_PORT`):
+                TCP port the in-container gateway listens on (always
+                exposed to a randomly assigned host port).
+            env (`dict[str, str] | None`, optional):
+                Environment variables to set inside every workspace's
+                container.
+            default_mcps (`list[MCPClient] | None`, optional):
+                MCP clients seeded into brand-new workspaces. Ignored
+                on subsequent restarts of a workdir that already
+                persists ``.mcp``.
+            skill_paths (`list[str] | None`, optional):
+                Skill directories seeded into brand-new workspaces.
+            ttl (`float`, defaults to `3600.0`):
+                Seconds before an idle cached workspace is evicted
+                and its container torn down.
+            sweep_interval (`float`, defaults to `DEFAULT_SWEEP_INTERVAL`):
+                How often (seconds) the background sweeper wakes up
+                to look for idle workspaces. Defaults to 5 minutes.
+        """
+        self._basedir = os.path.abspath(basedir)
+        self._base_image = base_image
+        self._node_version = node_version
+        self._extra_pip = list(extra_pip or [])
+        self._gateway_port = gateway_port
+        self._env = dict(env or {})
+        self._default_mcps = list(default_mcps or [])
+        self._skill_paths = list(skill_paths or [])
+        super().__init__(isolation=isolation)
+        self._ttl = ttl
+        self._sweep_interval = sweep_interval
+
+        # workspace_id → (workspace, last_access_monotonic)
+        self._cache: dict[str, tuple[DockerWorkspace, float]] = {}
+        self._lock = asyncio.Lock()
+        self._sweep_task: asyncio.Task | None = None
+
+    # ── isolation helpers ─────────────────────────────────────────
+
+    def _workdir_for(self, user_id: str, agent_id: str) -> str:
+        """Resolve the host workdir for ``(user_id, agent_id)``.
+
+        Two-level layout — ``<basedir>/<user_id>/<agent_id>`` — so
+        different users never share a bind-mount even when their
+        ``agent_id`` collides.
+        """
+        return os.path.join(self._basedir, user_id, agent_id)
+
+    # ── workspace construction ────────────────────────────────────
+
+    async def _build_and_start(
+        self,
+        *,
+        workspace_id: str,
+        user_id: str,
+        agent_id: str,
+    ) -> DockerWorkspace:
+        """Create a :class:`DockerWorkspace` for ``(user_id, agent_id)``
+        and run its full ``initialize``.
+
+        ``workspace_id`` is forwarded so the container name is
+        deterministic and the same id round-trips through the cache.
+        """
+        workdir = self._workdir_for(user_id, agent_id)
+        os.makedirs(workdir, exist_ok=True)
+        ws = DockerWorkspace(
+            workspace_id=workspace_id,
+            workdir=workdir,
+            base_image=self._base_image,
+            node_version=self._node_version,
+            extra_pip=self._extra_pip,
+            gateway_port=self._gateway_port,
+            env=self._env,
+            default_mcps=self._default_mcps,
+            skill_paths=self._skill_paths,
+        )
+        await ws.initialize()
+        return ws
+
+    # ── public API ────────────────────────────────────────────────
+
+    async def get_workspace(
+        self,
+        user_id: str,
+        agent_id: str,
+        session_id: str,
+        workspace_id: str | None = None,
+    ) -> DockerWorkspace:
+        """Return an initialised workspace, building one on cache miss.
+
+        On miss the manager calls ``DockerWorkspace(workspace_id=…)``
+        with a deterministic workdir derived from ``(user_id,
+        agent_id)``. Image build, container creation and gateway
+        startup all happen inside the workspace's ``initialize``.
+
+        Eviction of idle workspaces is *not* performed here — the
+        background sweeper started by :meth:`__aenter__` handles that.
+
+        Args:
+            user_id (`str`):
+                Owning user identifier.
+            agent_id (`str`):
+                Agent identifier (controls the workdir).
+            session_id (`str`):
+                Session identifier (unused for isolation; sessions
+                share a workdir and partition under
+                ``sessions/<session_id>/``).
+            workspace_id (`str | None`, optional):
+                Stable workspace identifier — used both as the cache
+                key and the container name suffix. When ``None`` the
+                manager falls back to :meth:`assign_workspace_id`;
+                the session flow should pre-resolve this so container
+                names stay stable across restarts.
+
+        Returns:
+            `DockerWorkspace`:
+                A live, initialised workspace.
+        """
+        del session_id  # accepted for interface parity; not used here
+
+        if workspace_id is None:
+            workspace_id = self.assign_workspace_id(
+                user_id=user_id,
+                agent_id=agent_id,
+                session_id="",
+            )
+
+        async with self._lock:
+            cached = self._cache.get(workspace_id)
+            if cached is not None:
+                ws, _ = cached
+                self._cache[workspace_id] = (ws, time.monotonic())
+                return ws
+
+        # Cache miss: build under the lock to prevent two concurrent
+        # get_workspace(workspace_id=X) calls from creating two
+        # workspaces for the same id.
+        async with self._lock:
+            cached = self._cache.get(workspace_id)
+            if cached is not None:
+                ws, _ = cached
+                self._cache[workspace_id] = (ws, time.monotonic())
+                return ws
+
+            ws = await self._build_and_start(
+                workspace_id=workspace_id,
+                user_id=user_id,
+                agent_id=agent_id,
+            )
+            self._cache[workspace_id] = (ws, time.monotonic())
+            return ws
+
+    @deprecated(
+        "DockerWorkspaceManager.create_workspace is deprecated; "
+        "use get_workspace(workspace_id=None) instead.",
+        category=None,
+    )
+    async def create_workspace(
+        self,
+        user_id: str,
+        agent_id: str,
+        session_id: str,
+    ) -> DockerWorkspace:
+        """Build a brand-new workspace and track it.
+
+        .. deprecated::
+            Use :meth:`get_workspace` with ``workspace_id=None`` — it
+            falls back to :meth:`assign_workspace_id` under the
+            manager's isolation policy and reuses the cache path.
+
+        Args:
+            user_id (`str`):
+                Owning user identifier.
+            agent_id (`str`):
+                Agent identifier (controls the workdir).
+            session_id (`str`):
+                Session identifier (accepted for parity; not used
+                here).
+
+        Returns:
+            `DockerWorkspace`:
+                The newly built workspace, already initialised.
+        """
+        del session_id  # accepted for interface parity; not used here
+
+        workdir = self._workdir_for(user_id, agent_id)
+        os.makedirs(workdir, exist_ok=True)
+        ws = DockerWorkspace(
+            host_workdir=workdir,
+            base_image=self._base_image,
+            node_version=self._node_version,
+            extra_pip=self._extra_pip,
+            gateway_port=self._gateway_port,
+            env=self._env,
+            default_mcps=self._default_mcps,
+            skill_paths=self._skill_paths,
+        )
+        await ws.initialize()
+        async with self._lock:
+            self._cache[ws.workspace_id] = (ws, time.monotonic())
+        return ws
+
+    async def close(self, workspace_id: str) -> None:
+        """Close and evict a single workspace from the cache.
+
+        No-op when the workspace_id is not tracked.
+
+        Args:
+            workspace_id (`str`):
+                The workspace to close.
+        """
+        async with self._lock:
+            entry = self._cache.pop(workspace_id, None)
+        if entry is None:
+            return
+        ws, _ = entry
+        await self._safe_close(ws)
+
+    async def close_all(self) -> None:
+        """Close every cached workspace in parallel.
+
+        Docker ``kill + delete`` is slow per container; doing it
+        sequentially on app shutdown produces a noticeable stall, so
+        we fan the calls out with :func:`asyncio.gather`.
+        """
+        async with self._lock:
+            entries = list(self._cache.values())
+            self._cache.clear()
+        if not entries:
+            return
+        await asyncio.gather(
+            *(self._safe_close(ws) for ws, _ in entries),
+            return_exceptions=True,
+        )
+
+    # ── async context manager ─────────────────────────────────────
+
+    async def __aenter__(self) -> Self:
+        """Start the TTL sweeper task."""
+        if self._sweep_task is None:
+            self._sweep_task = asyncio.create_task(self._sweep_loop())
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        """Stop the TTL sweeper task, then close every cached workspace."""
+        if self._sweep_task is not None:
+            self._sweep_task.cancel()
+            try:
+                await self._sweep_task
+            except (asyncio.CancelledError, Exception):
+                pass
+            self._sweep_task = None
+        await self.close_all()
+
+    # ── background sweeper ───────────────────────────────────────
+
+    async def _sweep_loop(self) -> None:
+        """Periodically evict idle workspaces.
+
+        Runs forever until cancelled. Each tick pops every cache entry
+        whose last-access is older than ``ttl`` and closes it outside
+        the lock; exceptions during close are logged and swallowed so
+        one bad container does not poison the sweeper.
+        """
+        while True:
+            try:
+                await asyncio.sleep(self._sweep_interval)
+            except asyncio.CancelledError:
+                return
+            try:
+                await self._sweep_once()
+            except Exception:
+                logger.exception("Docker workspace sweeper tick failed")
+
+    async def _sweep_once(self) -> None:
+        """One sweeper tick: evict expired entries and close them."""
+        now = time.monotonic()
+        async with self._lock:
+            expired_ids = [
+                wid
+                for wid, (_, ts) in self._cache.items()
+                if now - ts > self._ttl
+            ]
+            evicted = [self._cache.pop(wid)[0] for wid in expired_ids]
+        if not evicted:
+            return
+        await asyncio.gather(
+            *(self._safe_close(ws) for ws in evicted),
+            return_exceptions=True,
+        )
+
+    @staticmethod
+    async def _safe_close(ws: DockerWorkspace) -> None:
+        """Close a workspace, logging any failure instead of raising."""
+        try:
+            await ws.close()
+        except Exception:
+            logger.exception(
+                "Failed to close DockerWorkspace %s",
+                ws.workspace_id,
+            )
diff --git a/src/agentscope/app/workspace_manager/_e2b_workspace_manager.py b/src/agentscope/app/workspace_manager/_e2b_workspace_manager.py
new file mode 100644
index 0000000..0c641c3
--- /dev/null
+++ b/src/agentscope/app/workspace_manager/_e2b_workspace_manager.py
@@ -0,0 +1,408 @@
+# -*- coding: utf-8 -*-
+"""E2BWorkspaceManager — lifecycle manager for :class:`E2BWorkspace`.
+
+Mirrors :class:`DockerWorkspaceManager` 1:1 in its public surface
+(``get_workspace`` / ``create_workspace`` / ``close`` / ``close_all``)
+so callers — notably :class:`agentscope.app._service.ChatService` —
+do not branch on backend.
+
+Differences from the Docker manager:
+
+* No ``basedir`` / ``_workdir_for`` — E2B sandboxes carry their own
+  filesystem state across pause/resume, so there is nothing to
+  bind-mount and nothing to lay out on the host.
+* No image build parameters (``base_image`` / ``node_version``); E2B
+  attaches to a pre-built template plus a runtime bootstrap.
+* Reattachment uses E2B sandbox metadata. The ``workspace_id`` is
+  written into the sandbox's metadata at create time and looked up via
+  ``AsyncSandbox.list(query=...)`` inside
+  :meth:`E2BWorkspace.initialize`. The manager itself is metadata-blind
+  — it just forwards ``workspace_id`` and lets the workspace handle the
+  reattach.
+* ``user_id`` / ``agent_id`` are surfaced as extra sandbox metadata
+  (``agentscope.user.id`` / ``agentscope.agent.id``) so users can
+  filter their own sandboxes in the E2B dashboard. They do **not**
+  participate in cache key resolution; the cache is keyed strictly on
+  ``workspace_id`` (same as Docker).
+* Idle workspaces are evicted by a dedicated background sweeper task
+  started in :meth:`__aenter__` and cancelled in :meth:`__aexit__` —
+  not lazily on each :meth:`get_workspace` call.
+* ``close_all`` fans calls out with :func:`asyncio.gather` because
+  ``sandbox.pause()`` is a remote round-trip per sandbox; sequentialising
+  it on app shutdown produces a noticeable stall.
+"""
+
+import asyncio
+import time
+from typing import Self
+
+from typing_extensions import deprecated
+
+from ..._logging import logger
+from ...mcp import MCPClient
+from ...workspace import E2BWorkspace
+from ...workspace._e2b._constants import (
+    DEFAULT_GATEWAY_PORT,
+    DEFAULT_TEMPLATE,
+    DEFAULT_TIMEOUT,
+)
+from ._base import WorkspaceManagerBase, IsolationPolicy
+
+DEFAULT_SWEEP_INTERVAL = 300.0
+
+
+class E2BWorkspaceManager(WorkspaceManagerBase):
+    """Manages :class:`E2BWorkspace` instances with TTL-based caching.
+
+    Use the manager as an ``async with`` context manager: entering it
+    starts the TTL sweeper task, exiting it stops the sweeper and then
+    closes every cached workspace via :meth:`close_all`.
+    """
+
+    def __init__(
+        self,
+        *,
+        isolation: IsolationPolicy = IsolationPolicy.PER_AGENT,
+        template: str = DEFAULT_TEMPLATE,
+        api_key: str = "",
+        domain: str = "",
+        timeout_seconds: int = DEFAULT_TIMEOUT,
+        gateway_port: int = DEFAULT_GATEWAY_PORT,
+        env: dict[str, str] | None = None,
+        sandbox_metadata: dict[str, str] | None = None,
+        extra_pip: list[str] | None = None,
+        default_mcps: list[MCPClient] | None = None,
+        skill_paths: list[str] | None = None,
+        ttl: float = 3600.0,
+        sweep_interval: float = DEFAULT_SWEEP_INTERVAL,
+    ) -> None:
+        """Initialize the E2B workspace manager.
+
+        Args:
+            isolation (`IsolationPolicy`, defaults to `PER_AGENT`):
+                Isolation grain for :meth:`assign_workspace_id`. See
+                :class:`DockerWorkspaceManager` for semantics.
+            template (`str`, defaults to `DEFAULT_TEMPLATE`):
+                E2B template id passed to every workspace this
+                manager produces. Defaults to ``"base"``.
+            api_key (`str`, defaults to `""`):
+                E2B API key. ``""`` falls back to the ``E2B_API_KEY``
+                env var on the SDK side.
+            domain (`str`, defaults to `""`):
+                Optional custom E2B domain (self-hosted etc.).
+            timeout_seconds (`int`, defaults to `DEFAULT_TIMEOUT`):
+                Sandbox keep-alive timeout passed to
+                ``AsyncSandbox.create`` / ``AsyncSandbox.connect``.
+            gateway_port (`int`, defaults to `DEFAULT_GATEWAY_PORT`):
+                TCP port the in-sandbox gateway listens on.
+            env (`dict[str, str] | None`, optional):
+                Environment variables baked into the sandbox at
+                create time.
+            sandbox_metadata (`dict[str, str] | None`, optional):
+                Extra metadata merged with the per-workspace
+                ``agentscope.workspace.id`` / ``agentscope.user.id`` /
+                ``agentscope.agent.id`` keys. Useful for downstream
+                E2B dashboard filtering.
+            extra_pip (`list[str] | None`, optional):
+                Extra Python packages to install into the gateway
+                venv during bootstrap.
+            default_mcps (`list[MCPClient] | None`, optional):
+                MCP clients seeded into brand-new workspaces. Ignored
+                on subsequent reattachments — the sandbox's persisted
+                ``.mcp`` file wins.
+            skill_paths (`list[str] | None`, optional):
+                Skill directories seeded into brand-new workspaces.
+            ttl (`float`, defaults to `3600.0`):
+                Seconds before an idle cached workspace is evicted
+                and its sandbox paused.
+            sweep_interval (`float`, defaults to `DEFAULT_SWEEP_INTERVAL`):
+                How often (seconds) the background sweeper wakes up
+                to look for idle workspaces. Defaults to 5 minutes.
+        """
+        self._template = template
+        self._api_key = api_key
+        self._domain = domain
+        self._timeout_seconds = timeout_seconds
+        self._gateway_port = gateway_port
+        self._env = dict(env or {})
+        self._sandbox_metadata = dict(sandbox_metadata or {})
+        self._extra_pip = list(extra_pip or [])
+        self._default_mcps = list(default_mcps or [])
+        self._skill_paths = list(skill_paths or [])
+        self._ttl = ttl
+        self._sweep_interval = sweep_interval
+        super().__init__(isolation=isolation)
+
+        # workspace_id → (workspace, last_access_monotonic)
+        self._cache: dict[str, tuple[E2BWorkspace, float]] = {}
+        self._lock = asyncio.Lock()
+        self._sweep_task: asyncio.Task | None = None
+
+    # ── metadata helper ───────────────────────────────────────────
+
+    def _metadata_for(
+        self,
+        user_id: str,
+        agent_id: str,
+    ) -> dict[str, str]:
+        """Build the extra sandbox metadata for ``(user_id, agent_id)``.
+
+        ``E2BWorkspace`` always sets ``agentscope.workspace.id`` itself;
+        we add the user/agent keys here so they show up alongside it
+        in the E2B dashboard's metadata filter UI.
+        """
+        return {
+            "agentscope.user.id": user_id,
+            "agentscope.agent.id": agent_id,
+            **self._sandbox_metadata,
+        }
+
+    # ── workspace construction ────────────────────────────────────
+
+    async def _build_and_start(
+        self,
+        *,
+        workspace_id: str | None,
+        user_id: str,
+        agent_id: str,
+    ) -> E2BWorkspace:
+        """Construct an :class:`E2BWorkspace` and run its full ``initialize``.
+
+        ``workspace_id=None`` lets :class:`WorkspaceBase` allocate a
+        fresh UUID — used by :meth:`create_workspace`. Otherwise the
+        provided id is forwarded so reattachment by metadata works on
+        the second call.
+        """
+        ws = E2BWorkspace(
+            workspace_id=workspace_id,
+            template=self._template,
+            api_key=self._api_key,
+            domain=self._domain,
+            timeout_seconds=self._timeout_seconds,
+            gateway_port=self._gateway_port,
+            env=self._env,
+            sandbox_metadata=self._metadata_for(user_id, agent_id),
+            extra_pip=self._extra_pip,
+            default_mcps=self._default_mcps,
+            skill_paths=self._skill_paths,
+        )
+        await ws.initialize()
+        return ws
+
+    # ── public API ────────────────────────────────────────────────
+
+    async def get_workspace(
+        self,
+        user_id: str,
+        agent_id: str,
+        session_id: str,
+        workspace_id: str | None = None,
+    ) -> E2BWorkspace:
+        """Return an initialised workspace, reattaching on cache miss.
+
+        On miss the manager calls ``E2BWorkspace(workspace_id=…)`` and
+        relies on its ``initialize`` to find any existing sandbox via
+        ``AsyncSandbox.list(query=SandboxQuery(metadata=...))`` and
+        ``connect`` to it (auto-resuming if paused) — or to ``create``
+        a fresh sandbox otherwise.
+
+        Eviction of idle workspaces is *not* performed here — the
+        background sweeper started by :meth:`__aenter__` handles that.
+
+        Args:
+            user_id (`str`):
+                Owning user identifier (forwarded as sandbox metadata
+                only — not part of the cache key).
+            agent_id (`str`):
+                Agent identifier (forwarded as sandbox metadata only
+                — not part of the cache key).
+            session_id (`str`):
+                Session identifier (unused; sandboxes are
+                per-workspace, sessions partition under
+                ``sessions/<session_id>/``).
+            workspace_id (`str | None`, optional):
+                Stable workspace identifier — the cache key and the
+                value stored in the sandbox's
+                ``agentscope.workspace.id`` metadata. When ``None``
+                the manager falls back to
+                :meth:`assign_workspace_id`.
+
+        Returns:
+            `E2BWorkspace`:
+                A live, initialised workspace.
+        """
+        del session_id  # accepted for interface parity; not used here
+
+        if workspace_id is None:
+            workspace_id = self.assign_workspace_id(
+                user_id=user_id,
+                agent_id=agent_id,
+                session_id="",
+            )
+
+        async with self._lock:
+            cached = self._cache.get(workspace_id)
+            if cached is not None:
+                ws, _ = cached
+                self._cache[workspace_id] = (ws, time.monotonic())
+                return ws
+
+        # Cache miss: build under the lock to prevent two concurrent
+        # get_workspace(workspace_id=X) calls from creating two
+        # workspaces (and thus two sandboxes) for the same id.
+        async with self._lock:
+            cached = self._cache.get(workspace_id)
+            if cached is not None:
+                ws, _ = cached
+                self._cache[workspace_id] = (ws, time.monotonic())
+                return ws
+
+            ws = await self._build_and_start(
+                workspace_id=workspace_id,
+                user_id=user_id,
+                agent_id=agent_id,
+            )
+            self._cache[workspace_id] = (ws, time.monotonic())
+            return ws
+
+    @deprecated(
+        "E2BWorkspaceManager.create_workspace is deprecated; "
+        "use get_workspace(workspace_id=None) instead.",
+        category=None,
+    )
+    async def create_workspace(
+        self,
+        user_id: str,
+        agent_id: str,
+        session_id: str,
+    ) -> E2BWorkspace:
+        """Build a brand-new workspace and track it.
+
+        .. deprecated::
+            Use :meth:`get_workspace` with ``workspace_id=None`` — it
+            falls back to :meth:`assign_workspace_id` under the
+            manager's isolation policy and reuses the cache path.
+
+        Args:
+            user_id (`str`):
+                Owning user identifier (forwarded as sandbox metadata).
+            agent_id (`str`):
+                Agent identifier (forwarded as sandbox metadata).
+            session_id (`str`):
+                Session identifier (accepted for parity; not used
+                here).
+
+        Returns:
+            `E2BWorkspace`:
+                The newly built workspace, already initialised.
+        """
+        del session_id  # accepted for interface parity; not used here
+
+        ws = await self._build_and_start(
+            workspace_id=None,
+            user_id=user_id,
+            agent_id=agent_id,
+        )
+        async with self._lock:
+            self._cache[ws.workspace_id] = (ws, time.monotonic())
+        return ws
+
+    async def close(self, workspace_id: str) -> None:
+        """Close (= pause the sandbox) and evict a single workspace.
+
+        No-op when the workspace_id is not tracked.
+
+        Args:
+            workspace_id (`str`):
+                The workspace to close.
+        """
+        async with self._lock:
+            entry = self._cache.pop(workspace_id, None)
+        if entry is None:
+            return
+        ws, _ = entry
+        await self._safe_close(ws)
+
+    async def close_all(self) -> None:
+        """Close every cached workspace in parallel.
+
+        ``sandbox.pause()`` is a remote round-trip per sandbox; doing
+        it sequentially on app shutdown produces a noticeable stall,
+        so we fan the calls out with :func:`asyncio.gather`.
+        """
+        async with self._lock:
+            entries = list(self._cache.values())
+            self._cache.clear()
+        if not entries:
+            return
+        await asyncio.gather(
+            *(self._safe_close(ws) for ws, _ in entries),
+            return_exceptions=True,
+        )
+
+    # ── async context manager ─────────────────────────────────────
+
+    async def __aenter__(self) -> Self:
+        """Start the TTL sweeper task."""
+        if self._sweep_task is None:
+            self._sweep_task = asyncio.create_task(self._sweep_loop())
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        """Stop the TTL sweeper task, then close every cached workspace."""
+        if self._sweep_task is not None:
+            self._sweep_task.cancel()
+            try:
+                await self._sweep_task
+            except (asyncio.CancelledError, Exception):
+                pass
+            self._sweep_task = None
+        await self.close_all()
+
+    # ── background sweeper ───────────────────────────────────────
+
+    async def _sweep_loop(self) -> None:
+        """Periodically pause idle workspaces.
+
+        Runs forever until cancelled. Each tick pops every cache entry
+        whose last-access is older than ``ttl`` and closes it outside
+        the lock; exceptions during close are logged and swallowed so
+        one bad sandbox does not poison the sweeper.
+        """
+        while True:
+            try:
+                await asyncio.sleep(self._sweep_interval)
+            except asyncio.CancelledError:
+                return
+            try:
+                await self._sweep_once()
+            except Exception:
+                logger.exception("E2B workspace sweeper tick failed")
+
+    async def _sweep_once(self) -> None:
+        """One sweeper tick: evict expired entries and close them."""
+        now = time.monotonic()
+        async with self._lock:
+            expired_ids = [
+                wid
+                for wid, (_, ts) in self._cache.items()
+                if now - ts > self._ttl
+            ]
+            evicted = [self._cache.pop(wid)[0] for wid in expired_ids]
+        if not evicted:
+            return
+        await asyncio.gather(
+            *(self._safe_close(ws) for ws in evicted),
+            return_exceptions=True,
+        )
+
+    @staticmethod
+    async def _safe_close(ws: E2BWorkspace) -> None:
+        """Close a workspace, logging any failure instead of raising."""
+        try:
+            await ws.close()
+        except Exception:
+            logger.exception(
+                "Failed to close E2BWorkspace %s",
+                ws.workspace_id,
+            )
diff --git a/src/agentscope/app/workspace_manager/_k8s_workspace_manager.py b/src/agentscope/app/workspace_manager/_k8s_workspace_manager.py
new file mode 100644
index 0000000..ffdb49f
--- /dev/null
+++ b/src/agentscope/app/workspace_manager/_k8s_workspace_manager.py
@@ -0,0 +1,354 @@
+# -*- coding: utf-8 -*-
+"""K8sWorkspaceManager — lifecycle manager for :class:`K8sWorkspace`.
+
+Mirrors :class:`E2BWorkspaceManager` 1:1 in its public surface
+(``get_workspace`` / ``create_workspace`` / ``close`` / ``close_all``)
+so callers do not branch on backend.
+
+Differences from the E2B manager:
+
+* Reattachment uses a deterministic Pod/PVC name derived from
+  ``workspace_id`` (via ``_k8s_safe_name``).
+  :meth:`K8sWorkspace.initialize` handles rediscovery.
+* ``close()`` deletes the Pod; PVC deletion is governed by the
+  workspace's ``_delete_pvc_on_close`` attribute.
+* Idle workspaces are evicted by a dedicated background sweeper task.
+"""
+
+import asyncio
+import time
+from typing import Any, Self
+
+from typing_extensions import deprecated
+
+from ..._logging import logger
+from ...mcp import MCPClient
+from ...workspace import K8sWorkspace
+from ...workspace._k8s._constants import (
+    DEFAULT_GATEWAY_PORT,
+    DEFAULT_IMAGE,
+)
+from ._base import WorkspaceManagerBase, IsolationPolicy
+
+DEFAULT_SWEEP_INTERVAL = 300.0
+
+
+class K8sWorkspaceManager(WorkspaceManagerBase):
+    """Manages :class:`K8sWorkspace` instances with TTL-based caching.
+
+    Use as an ``async with`` context manager: entering starts the TTL
+    sweeper, exiting stops it and closes every cached workspace.
+    """
+
+    def __init__(
+        self,
+        *,
+        isolation: IsolationPolicy = IsolationPolicy.PER_AGENT,
+        namespace: str = "agentscope",
+        kubeconfig: str | None = None,
+        image: str = DEFAULT_IMAGE,
+        image_pull_policy: str = "IfNotPresent",
+        image_pull_secrets: list[str] | None = None,
+        resources: dict[str, Any] | None = None,
+        node_selector: dict[str, str] | None = None,
+        tolerations: list[dict[str, Any]] | None = None,
+        service_account: str | None = None,
+        gateway_port: int = DEFAULT_GATEWAY_PORT,
+        extra_pip: list[str] | None = None,
+        storage_class: str | None = None,
+        storage_size: str = "1Gi",
+        env: dict[str, str] | None = None,
+        default_mcps: list[MCPClient] | None = None,
+        skill_paths: list[str] | None = None,
+        ttl: float = 3600.0,
+        sweep_interval: float = DEFAULT_SWEEP_INTERVAL,
+        delete_pvc_on_close: bool = False,
+    ) -> None:
+        """Initialize the K8s workspace manager.
+
+        Args:
+            isolation (`IsolationPolicy`, defaults to `PER_AGENT`):
+                Isolation grain for :meth:`assign_workspace_id`. See
+                :class:`DockerWorkspaceManager` for semantics.
+            namespace (`str`, defaults to ``"agentscope"``):
+                K8s namespace for workspace Pods and PVCs.
+            kubeconfig (`str | None`, optional):
+                Path to kubeconfig file. ``None`` uses in-cluster
+                config.
+            image (`str`, defaults to ``"python:3.11-slim"``):
+                Container image for workspace Pods.
+            image_pull_policy (`str`, defaults to ``"IfNotPresent"``):
+                K8s imagePullPolicy.
+            image_pull_secrets (`list[str] | None`, optional):
+                Names of K8s image pull secrets.
+            resources (`dict[str, Any] | None`, optional):
+                K8s ResourceRequirements dict.
+            node_selector (`dict[str, str] | None`, optional):
+                K8s nodeSelector.
+            tolerations (`list[dict[str, Any]] | None`, optional):
+                K8s tolerations list.
+            service_account (`str | None`, optional):
+                K8s serviceAccountName.
+            gateway_port (`int`, defaults to `5600`):
+                Port the gateway listens on inside the Pod.
+            extra_pip (`list[str] | None`, optional):
+                Extra packages for the gateway venv.
+            storage_class (`str | None`, optional):
+                K8s StorageClass name.
+            storage_size (`str`, defaults to ``"1Gi"``):
+                PVC size.
+            env (`dict[str, str] | None`, optional):
+                Environment variables for workspace containers.
+            default_mcps (`list[MCPClient] | None`, optional):
+                MCPs seeded into new workspaces.
+            skill_paths (`list[str] | None`, optional):
+                Skill directories seeded into new workspaces.
+            ttl (`float`, defaults to `3600.0`):
+                Seconds before an idle workspace is evicted.
+            sweep_interval (`float`, defaults to `300.0`):
+                How often the sweeper runs.
+            delete_pvc_on_close (`bool`, defaults to ``False``):
+                Default ``delete_pvc_on_close`` value for newly
+                created workspaces.
+        """
+        self._namespace = namespace
+        self._kubeconfig = kubeconfig
+        self._image = image
+        self._image_pull_policy = image_pull_policy
+        self._image_pull_secrets = list(image_pull_secrets or [])
+        self._resources = resources
+        self._node_selector = node_selector
+        self._tolerations = tolerations
+        self._service_account = service_account
+        self._gateway_port = gateway_port
+        self._extra_pip = list(extra_pip or [])
+        self._storage_class = storage_class
+        self._storage_size = storage_size
+        self._env = dict(env or {})
+        self._default_mcps = list(default_mcps or [])
+        self._skill_paths = list(skill_paths or [])
+        self._ttl = ttl
+        self._sweep_interval = sweep_interval
+        self._delete_pvc_on_close = delete_pvc_on_close
+        super().__init__(isolation=isolation)
+
+        # workspace_id → (workspace, last_access_monotonic)
+        self._cache: dict[str, tuple[K8sWorkspace, float]] = {}
+        self._lock = asyncio.Lock()
+        self._sweep_task: asyncio.Task[None] | None = None
+
+    # ── workspace construction ────────────────────────────────────
+
+    async def _build_and_start(
+        self,
+        *,
+        workspace_id: str | None,
+    ) -> K8sWorkspace:
+        """Construct a :class:`K8sWorkspace` and run ``initialize``."""
+        ws = K8sWorkspace(
+            workspace_id=workspace_id,
+            kubeconfig=self._kubeconfig,
+            namespace=self._namespace,
+            image=self._image,
+            image_pull_policy=self._image_pull_policy,
+            image_pull_secrets=self._image_pull_secrets,
+            resources=self._resources,
+            node_selector=self._node_selector,
+            tolerations=self._tolerations,
+            service_account=self._service_account,
+            gateway_port=self._gateway_port,
+            extra_pip=self._extra_pip,
+            storage_class=self._storage_class,
+            storage_size=self._storage_size,
+            delete_pvc_on_close=self._delete_pvc_on_close,
+            env=self._env,
+            default_mcps=self._default_mcps,
+            skill_paths=self._skill_paths,
+        )
+        await ws.initialize()
+        return ws
+
+    # ── public API ────────────────────────────────────────────────
+
+    async def get_workspace(
+        self,
+        user_id: str,
+        agent_id: str,
+        session_id: str,
+        workspace_id: str | None = None,
+    ) -> K8sWorkspace:
+        """Return an initialised workspace, reattaching on cache miss.
+
+        Args:
+            user_id (`str`):
+                Owning user identifier.
+            agent_id (`str`):
+                Agent identifier.
+            session_id (`str`):
+                Session identifier (unused; Pods are per-workspace).
+            workspace_id (`str | None`, optional):
+                Stable workspace identifier — the cache key. When
+                ``None`` the manager falls back to
+                :meth:`assign_workspace_id`.
+
+        Returns:
+            `K8sWorkspace`:
+                A live, initialised workspace.
+        """
+        del session_id
+
+        if workspace_id is None:
+            workspace_id = self.assign_workspace_id(
+                user_id=user_id,
+                agent_id=agent_id,
+                session_id="",
+            )
+
+        async with self._lock:
+            cached = self._cache.get(workspace_id)
+            if cached is not None:
+                ws, _ = cached
+                self._cache[workspace_id] = (ws, time.monotonic())
+                return ws
+
+        async with self._lock:
+            cached = self._cache.get(workspace_id)
+            if cached is not None:
+                ws, _ = cached
+                self._cache[workspace_id] = (ws, time.monotonic())
+                return ws
+
+            ws = await self._build_and_start(
+                workspace_id=workspace_id,
+            )
+            self._cache[workspace_id] = (ws, time.monotonic())
+            return ws
+
+    @deprecated(
+        "K8sWorkspaceManager.create_workspace is deprecated; "
+        "use get_workspace(workspace_id=None) instead.",
+        category=None,
+    )
+    async def create_workspace(
+        self,
+        user_id: str,
+        agent_id: str,
+        session_id: str,
+    ) -> K8sWorkspace:
+        """Build a brand-new workspace and track it.
+
+        .. deprecated::
+            Use :meth:`get_workspace` with ``workspace_id=None`` — it
+            falls back to :meth:`assign_workspace_id` under the
+            manager's isolation policy and reuses the cache path.
+
+        Args:
+            user_id (`str`):
+                Owning user identifier.
+            agent_id (`str`):
+                Agent identifier.
+            session_id (`str`):
+                Session identifier (unused).
+
+        Returns:
+            `K8sWorkspace`:
+                The newly built workspace, already initialised.
+        """
+        del session_id, user_id, agent_id
+
+        ws = await self._build_and_start(workspace_id=None)
+        async with self._lock:
+            self._cache[ws.workspace_id] = (ws, time.monotonic())
+        return ws
+
+    async def close(self, workspace_id: str) -> None:
+        """Close and evict a single workspace.
+
+        Args:
+            workspace_id (`str`):
+                The workspace to close.
+        """
+        async with self._lock:
+            entry = self._cache.pop(workspace_id, None)
+        if entry is None:
+            return
+        ws, _ = entry
+        await self._safe_close(ws)
+
+    async def close_all(self) -> None:
+        """Close every cached workspace in parallel."""
+        async with self._lock:
+            entries = list(self._cache.values())
+            self._cache.clear()
+        if not entries:
+            return
+        await asyncio.gather(
+            *(self._safe_close(ws) for ws, _ in entries),
+            return_exceptions=True,
+        )
+
+    # ── async context manager ─────────────────────────────────────
+
+    async def __aenter__(self) -> Self:
+        """Start the TTL sweeper task."""
+        if self._sweep_task is None:
+            self._sweep_task = asyncio.create_task(self._sweep_loop())
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        """Stop the TTL sweeper, then close every cached workspace."""
+        if self._sweep_task is not None:
+            self._sweep_task.cancel()
+            try:
+                await self._sweep_task
+            except (asyncio.CancelledError, Exception):
+                pass
+            self._sweep_task = None
+        await self.close_all()
+
+    # ── background sweeper ───────────────────────────────────────
+
+    async def _sweep_loop(self) -> None:
+        """Periodically evict idle workspaces."""
+        while True:
+            try:
+                await asyncio.sleep(self._sweep_interval)
+            except asyncio.CancelledError:
+                return
+            try:
+                await self._sweep_once()
+            except Exception:
+                logger.exception("K8s workspace sweeper tick failed")
+
+    async def _sweep_once(self) -> None:
+        """One sweeper tick: evict expired entries and close them."""
+        now = time.monotonic()
+        async with self._lock:
+            expired_ids = [
+                wid
+                for wid, (_, ts) in self._cache.items()
+                if now - ts > self._ttl
+            ]
+            evicted = [self._cache.pop(wid)[0] for wid in expired_ids]
+        if not evicted:
+            return
+        await asyncio.gather(
+            *(self._safe_close(ws) for ws in evicted),
+            return_exceptions=True,
+        )
+
+    @staticmethod
+    async def _safe_close(ws: K8sWorkspace) -> None:
+        """Close a workspace, logging any failure instead of raising.
+
+        Args:
+            ws (`K8sWorkspace`):
+                The workspace to close.
+        """
+        try:
+            await ws.close()
+        except Exception:
+            logger.exception(
+                "Failed to close K8sWorkspace %s",
+                ws.workspace_id,
+            )
diff --git a/src/agentscope/app/workspace_manager/_local_workspace_manager.py b/src/agentscope/app/workspace_manager/_local_workspace_manager.py
new file mode 100644
index 0000000..1a4e08a
--- /dev/null
+++ b/src/agentscope/app/workspace_manager/_local_workspace_manager.py
@@ -0,0 +1,210 @@
+# -*- coding: utf-8 -*-
+"""The local workspace manager."""
+
+import asyncio
+import os
+import time
+
+from typing_extensions import deprecated
+
+from ..._logging import logger
+from ...workspace import LocalWorkspace
+from ._base import WorkspaceManagerBase, IsolationPolicy
+
+
+class LocalWorkspaceManager(WorkspaceManagerBase):
+    """Manages LocalWorkspace instances with TTL-based lazy lifecycle.
+
+    Workspaces are keyed by ``workspace_id`` in the cache. On cache miss
+    the manager reconstructs the workspace from ``basedir/agent_id`` — the
+    workdir is deterministic for local workspaces so no storage lookup is
+    needed.
+    """
+
+    def __init__(
+        self,
+        basedir: str,
+        *,
+        isolation: IsolationPolicy = IsolationPolicy.PER_AGENT,
+        default_mcps: list | None = None,
+        skill_paths: list[str] | None = None,
+        ttl: float = 3600.0,
+    ) -> None:
+        """Initialize the local workspace manager.
+
+        Args:
+            basedir (`str`):
+                Root directory under which per-agent workdir are
+                created.
+            isolation (`IsolationPolicy`, defaults to `PER_AGENT`):
+                Isolation grain for :meth:`assign_workspace_id`. See
+                :class:`DockerWorkspaceManager` for semantics.
+            default_mcps (`list | None`, optional):
+                MCP clients seeded into brand-new workspaces.
+            skill_paths (`list[str] | None`, optional):
+                Skill directories seeded into brand-new workspaces.
+            ttl (`float`, defaults to `3600.0`):
+                Seconds before an idle cached workspace is evicted.
+        """
+        self._basedir = os.path.abspath(basedir)
+        self._default_mcps = default_mcps or []
+        self._skill_paths = skill_paths or []
+        self._ttl = ttl
+        # workspace_id → (workspace, last_access_monotonic)
+        self._cache: dict[str, tuple[LocalWorkspace, float]] = {}
+        self._lock = asyncio.Lock()
+        super().__init__(isolation=isolation)
+
+    def _pop_expired(self, now: float) -> list[LocalWorkspace]:
+        """Pop every cache entry whose last-access exceeds ``ttl``.
+
+        Caller is responsible for closing the returned workspaces
+        *outside* the manager lock so a slow ``close()`` does not stall
+        unrelated ``get_workspace`` callers.
+        """
+        expired_ids = [
+            wid for wid, (_, ts) in self._cache.items() if now - ts > self._ttl
+        ]
+        return [self._cache.pop(wid)[0] for wid in expired_ids]
+
+    async def get_workspace(
+        self,
+        user_id: str,
+        agent_id: str,
+        session_id: str,
+        workspace_id: str | None = None,
+    ) -> LocalWorkspace:
+        """Return an initialized workspace, reconstructing from
+        disk on cache miss.
+
+        Mirrors the Docker / E2B managers' double-check pattern: a
+        first lock acquisition handles the cache-hit fast path and
+        collects expired entries; expired entries are then closed in
+        parallel *outside* the lock; on a miss a second acquisition
+        runs ``initialize()`` while holding the lock so two concurrent
+        cache misses for the same ``workspace_id`` cannot create two
+        workspaces.
+        """
+        del user_id  # accepted for interface parity; not used here
+
+        if workspace_id is None:
+            workspace_id = self.assign_workspace_id(
+                user_id="",
+                agent_id=agent_id,
+                session_id="",
+            )
+
+        # Phase 1: cache hit + collect expired.
+        async with self._lock:
+            now = time.monotonic()
+            expired = self._pop_expired(now)
+            cached = self._cache.get(workspace_id)
+            if cached is not None:
+                ws, _ = cached
+                self._cache[workspace_id] = (ws, now)
+                hit: LocalWorkspace | None = ws
+            else:
+                hit = None
+
+        # Phase 2: close expired entries outside the lock, in parallel,
+        # so a slow stdio MCP shutdown does not block unrelated callers.
+        if expired:
+            await asyncio.gather(
+                *(self._safe_close(ws) for ws in expired),
+                return_exceptions=True,
+            )
+
+        if hit is not None:
+            return hit
+
+        # Phase 3: build under the lock to prevent two concurrent
+        # get_workspace(workspace_id=X) calls from creating two
+        # workspaces for the same id.
+        async with self._lock:
+            cached = self._cache.get(workspace_id)
+            if cached is not None:
+                ws, _ = cached
+                self._cache[workspace_id] = (ws, time.monotonic())
+                return ws
+
+            # Workdir is deterministic for local workspaces — no storage needed
+            workdir = os.path.join(self._basedir, agent_id)
+            ws = LocalWorkspace(
+                workspace_id=workspace_id,
+                workdir=workdir,
+                default_mcps=self._default_mcps,
+                skill_paths=self._skill_paths,
+            )
+            await ws.initialize()
+            self._cache[workspace_id] = (ws, time.monotonic())
+            return ws
+
+    @deprecated(
+        "LocalWorkspaceManager.create_workspace is deprecated; "
+        "use get_workspace(workspace_id=None) instead.",
+        category=None,
+    )
+    async def create_workspace(
+        self,
+        user_id: str,
+        agent_id: str,
+        session_id: str,
+    ) -> LocalWorkspace:
+        """Create a new workspace for the given agent and return it.
+
+        .. deprecated::
+            Use :meth:`get_workspace` with ``workspace_id=None`` — it
+            falls back to :meth:`assign_workspace_id` under the
+            manager's isolation policy and reuses the cache path.
+        """
+        del user_id, session_id  # accepted for interface parity
+
+        workdir = os.path.join(self._basedir, agent_id)
+        os.makedirs(workdir, exist_ok=True)
+        ws = LocalWorkspace(
+            workdir=workdir,
+            default_mcps=self._default_mcps,
+            skill_paths=self._skill_paths,
+        )
+        await ws.initialize()
+        async with self._lock:
+            self._cache[ws.workspace_id] = (ws, time.monotonic())
+        return ws
+
+    async def close(self, workspace_id: str) -> None:
+        """Close and evict a single workspace from the cache."""
+        async with self._lock:
+            entry = self._cache.pop(workspace_id, None)
+        if entry is None:
+            return
+        ws, _ = entry
+        await self._safe_close(ws)
+
+    async def close_all(self) -> None:
+        """Close every cached workspace in parallel.
+
+        Stdio MCP shutdown can be slow per workspace; doing it
+        sequentially on app shutdown produces a noticeable stall, so
+        we fan the calls out with :func:`asyncio.gather` (mirrors the
+        Docker / E2B managers).
+        """
+        async with self._lock:
+            entries = list(self._cache.values())
+            self._cache.clear()
+        if not entries:
+            return
+        await asyncio.gather(
+            *(self._safe_close(ws) for ws, _ in entries),
+            return_exceptions=True,
+        )
+
+    @staticmethod
+    async def _safe_close(ws: LocalWorkspace) -> None:
+        """Close a workspace, logging any failure instead of raising."""
+        try:
+            await ws.close()
+        except Exception:
+            logger.exception(
+                "Failed to close LocalWorkspace %s",
+                ws.workspace_id,
+            )
diff --git a/src/agentscope/app/workspace_manager/_opensandbox_workspace_manager.py b/src/agentscope/app/workspace_manager/_opensandbox_workspace_manager.py
new file mode 100644
index 0000000..c9fd286
--- /dev/null
+++ b/src/agentscope/app/workspace_manager/_opensandbox_workspace_manager.py
@@ -0,0 +1,356 @@
+# -*- coding: utf-8 -*-
+"""OpenSandboxWorkspaceManager -- lifecycle manager for OpenSandbox.
+
+Mirrors :class:`DockerWorkspaceManager` and :class:`E2BWorkspaceManager`
+in its public surface (``get_workspace`` / ``close`` / ``close_all``) so
+callers do not branch on backend.
+
+Differences from the Docker manager:
+
+* No ``basedir`` / host workdir layout: OpenSandbox sandboxes carry
+  their own filesystem state across pause/resume, so there is nothing
+  to bind-mount on the host.
+* No image build step: the manager passes an image name plus runtime
+  bootstrap options to :class:`OpenSandboxWorkspace`.
+* Reattachment uses OpenSandbox sandbox metadata. The workspace writes
+  ``agentscope.workspace.id`` at create time and looks it up via
+  ``SandboxManager.list_sandbox_infos`` inside
+  :meth:`OpenSandboxWorkspace.initialize`. The manager itself stays
+  metadata-blind and just forwards ``workspace_id``.
+* ``user_id`` / ``agent_id`` are surfaced as extra sandbox metadata so
+  operators can filter sandboxes in OpenSandbox. They do not
+  participate in cache key resolution; the cache is keyed strictly by
+  ``workspace_id``.
+* Idle workspaces are evicted by a background sweeper task started in
+  :meth:`__aenter__` and cancelled in :meth:`__aexit__`.
+* ``close_all`` fans calls out with :func:`asyncio.gather` because
+  ``sandbox.pause()`` is a remote round-trip per sandbox.
+"""
+
+import asyncio
+import time
+from typing import Any, Literal, Self
+
+from ..._logging import logger
+from ...mcp import MCPClient
+from ...workspace._opensandbox._constants import (
+    DEFAULT_GATEWAY_PORT,
+    DEFAULT_IMAGE,
+    DEFAULT_REQUEST_TIMEOUT,
+    DEFAULT_TIMEOUT,
+)
+from ...workspace import OpenSandboxWorkspace
+
+from ._base import IsolationPolicy, WorkspaceManagerBase
+
+DEFAULT_SWEEP_INTERVAL = 300.0
+
+
+class OpenSandboxWorkspaceManager(WorkspaceManagerBase):
+    """Manages OpenSandbox workspaces with TTL-based caching.
+
+    Use the manager as an ``async with`` context manager: entering it
+    starts the TTL sweeper task, exiting it stops the sweeper and then
+    closes every cached workspace via :meth:`close_all`.
+    """
+
+    def __init__(
+        self,
+        *,
+        isolation: IsolationPolicy = IsolationPolicy.PER_AGENT,
+        image: str = DEFAULT_IMAGE,
+        api_key: str = "",
+        domain: str = "",
+        protocol: Literal["http", "https"] = "http",
+        request_timeout_seconds: float | None = DEFAULT_REQUEST_TIMEOUT,
+        timeout_seconds: int = DEFAULT_TIMEOUT,
+        gateway_port: int = DEFAULT_GATEWAY_PORT,
+        env: dict[str, str] | None = None,
+        sandbox_metadata: dict[str, str] | None = None,
+        resource: dict[str, str] | None = None,
+        entrypoint: list[str] | None = None,
+        network_policy: Any | None = None,
+        extra_pip: list[str] | None = None,
+        default_mcps: list[MCPClient] | None = None,
+        skill_paths: list[str] | None = None,
+        ttl: float = 3600.0,
+        sweep_interval: float = DEFAULT_SWEEP_INTERVAL,
+    ) -> None:
+        """Initialize the OpenSandbox workspace manager.
+
+        Args:
+            isolation (`IsolationPolicy`, defaults to `PER_AGENT`):
+                Isolation grain for :meth:`assign_workspace_id`, used
+                when :meth:`get_workspace` is called without an explicit
+                ``workspace_id``.
+            image (`str`, defaults to `DEFAULT_IMAGE`):
+                OpenSandbox image passed to every workspace this manager
+                produces.
+            api_key (`str`, defaults to `""`):
+                OpenSandbox API key. ``""`` lets the SDK fall back to
+                its environment-based configuration.
+            domain (`str`, defaults to `""`):
+                Optional OpenSandbox domain, for local or self-hosted
+                deployments.
+            protocol (`str`, defaults to `"http"`):
+                Scheme used when OpenSandbox returns endpoint values as
+                ``host:port`` without a protocol.
+            request_timeout_seconds (`float | None`, optional):
+                HTTP request timeout forwarded through
+                ``ConnectionConfig``. Defaults to 600 seconds so the
+                SDK HTTP streaming layer is not shorter than bootstrap
+                command timeout.
+            timeout_seconds (`int`, defaults to `DEFAULT_TIMEOUT`):
+                Sandbox keep-alive / resume timeout.
+            gateway_port (`int`, defaults to `DEFAULT_GATEWAY_PORT`):
+                TCP port the in-sandbox gateway listens on.
+            env (`dict[str, str] | None`, optional):
+                Environment variables applied when creating a sandbox.
+            sandbox_metadata (`dict[str, str] | None`, optional):
+                Extra metadata merged with the per-workspace
+                ``agentscope.workspace.id`` / ``agentscope.user.id`` /
+                ``agentscope.agent.id`` keys.
+            resource (`dict[str, str] | None`, optional):
+                Resource limits forwarded to OpenSandbox create.
+            entrypoint (`list[str] | None`, optional):
+                Optional sandbox entrypoint forwarded to OpenSandbox
+                create.
+            network_policy (`Any | None`, optional):
+                Creation-time OpenSandbox network policy. Runtime egress
+                patching is intentionally left for a follow-up.
+            extra_pip (`list[str] | None`, optional):
+                Extra Python packages installed into the gateway venv
+                during bootstrap.
+            default_mcps (`list[MCPClient] | None`, optional):
+                MCP clients seeded into brand-new workspaces. On
+                reattach, the sandbox's persisted ``.mcp`` file wins.
+            skill_paths (`list[str] | None`, optional):
+                Skill directories seeded into brand-new workspaces.
+            ttl (`float`, defaults to `3600.0`):
+                Seconds before an idle cached workspace is evicted and
+                its sandbox paused.
+            sweep_interval (`float`, defaults to `DEFAULT_SWEEP_INTERVAL`):
+                How often the background sweeper wakes up to look for
+                idle workspaces.
+        """
+        self._image = image
+        self._api_key = api_key
+        self._domain = domain
+        self._protocol = protocol
+        self._request_timeout_seconds = request_timeout_seconds
+        self._timeout_seconds = timeout_seconds
+        self._gateway_port = gateway_port
+        self._env = dict(env or {})
+        self._sandbox_metadata = dict(sandbox_metadata or {})
+        self._resource = dict(resource or {})
+        self._entrypoint = list(entrypoint or [])
+        self._network_policy = network_policy
+        self._extra_pip = list(extra_pip or [])
+        self._default_mcps = list(default_mcps or [])
+        self._skill_paths = list(skill_paths or [])
+        self._ttl = ttl
+        self._sweep_interval = sweep_interval
+        super().__init__(isolation=isolation)
+
+        # workspace_id -> (workspace, last_access_monotonic)
+        self._cache: dict[str, tuple[OpenSandboxWorkspace, float]] = {}
+        self._lock = asyncio.Lock()
+        self._sweep_task: asyncio.Task | None = None
+
+    async def _build_and_start(
+        self,
+        *,
+        workspace_id: str,
+        user_id: str,
+        agent_id: str,
+    ) -> OpenSandboxWorkspace:
+        """Construct an OpenSandbox workspace and run full initialize.
+
+        ``workspace_id`` is always concrete here — :meth:`get_workspace`
+        resolves ``None`` via :meth:`assign_workspace_id` before calling
+        — and is forwarded so metadata-based reattachment works on the
+        next cache miss.
+        """
+        ws = OpenSandboxWorkspace(
+            workspace_id=workspace_id,
+            image=self._image,
+            api_key=self._api_key,
+            domain=self._domain,
+            protocol=self._protocol,
+            request_timeout_seconds=self._request_timeout_seconds,
+            timeout_seconds=self._timeout_seconds,
+            gateway_port=self._gateway_port,
+            env=self._env,
+            sandbox_metadata={
+                "agentscope.user.id": user_id,
+                "agentscope.agent.id": agent_id,
+                **self._sandbox_metadata,
+            },
+            resource=self._resource,
+            entrypoint=self._entrypoint,
+            network_policy=self._network_policy,
+            extra_pip=self._extra_pip,
+            default_mcps=self._default_mcps,
+            skill_paths=self._skill_paths,
+        )
+        await ws.initialize()
+        return ws
+
+    async def get_workspace(
+        self,
+        user_id: str,
+        agent_id: str,
+        session_id: str,
+        workspace_id: str | None = None,
+    ) -> OpenSandboxWorkspace:
+        """Return an initialized workspace, reattaching on cache miss.
+
+        On miss, the manager constructs ``OpenSandboxWorkspace`` with
+        the requested ``workspace_id`` and relies on its ``initialize``
+        method to find an existing sandbox by metadata, connect or
+        resume it depending on state, or create a fresh sandbox
+        otherwise.
+
+        Idle eviction is not performed here; the background sweeper
+        started by :meth:`__aenter__` handles that.
+
+        Args:
+            user_id (`str`):
+                Owning user identifier (forwarded as sandbox metadata
+                only — not part of the cache key).
+            agent_id (`str`):
+                Agent identifier (forwarded as sandbox metadata only —
+                not part of the cache key).
+            session_id (`str`):
+                Session identifier (unused; sandboxes are per-workspace,
+                sessions partition under ``sessions/<session_id>/``).
+            workspace_id (`str | None`, optional):
+                Stable workspace identifier — the cache key and the
+                value stored in the sandbox's ``agentscope.workspace.id``
+                metadata. When ``None`` the manager falls back to
+                :meth:`assign_workspace_id` under its isolation policy.
+
+        Returns:
+            `OpenSandboxWorkspace`:
+                A live, initialized workspace.
+        """
+        del session_id  # accepted for interface parity; not used here
+
+        if workspace_id is None:
+            workspace_id = self.assign_workspace_id(
+                user_id=user_id,
+                agent_id=agent_id,
+                session_id="",
+            )
+
+        async with self._lock:
+            cached = self._cache.get(workspace_id)
+            if cached is not None:
+                ws, _ = cached
+                self._cache[workspace_id] = (ws, time.monotonic())
+                return ws
+
+        # Cache miss: build under the lock to prevent two concurrent
+        # get_workspace(workspace_id=X) calls from creating two
+        # workspaces (and thus two sandboxes) for the same id.
+        async with self._lock:
+            cached = self._cache.get(workspace_id)
+            if cached is not None:
+                ws, _ = cached
+                self._cache[workspace_id] = (ws, time.monotonic())
+                return ws
+
+            ws = await self._build_and_start(
+                workspace_id=workspace_id,
+                user_id=user_id,
+                agent_id=agent_id,
+            )
+            self._cache[workspace_id] = (ws, time.monotonic())
+            return ws
+
+    async def close(self, workspace_id: str) -> None:
+        """Close (= pause the sandbox) and evict a single workspace."""
+        async with self._lock:
+            entry = self._cache.pop(workspace_id, None)
+        if entry is None:
+            return
+        ws, _ = entry
+        await self._safe_close(ws)
+
+    async def close_all(self) -> None:
+        """Close every cached workspace in parallel.
+
+        ``sandbox.pause()`` is a remote round-trip per sandbox; doing
+        it sequentially on shutdown would produce unnecessary latency.
+        """
+        async with self._lock:
+            entries = list(self._cache.values())
+            self._cache.clear()
+        if not entries:
+            return
+        await asyncio.gather(
+            *(self._safe_close(ws) for ws, _ in entries),
+            return_exceptions=True,
+        )
+
+    async def __aenter__(self) -> Self:
+        """Start the TTL sweeper task."""
+        if self._sweep_task is None:
+            self._sweep_task = asyncio.create_task(self._sweep_loop())
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        """Stop the TTL sweeper task, then close all cached workspaces."""
+        if self._sweep_task is not None:
+            self._sweep_task.cancel()
+            try:
+                await self._sweep_task
+            except (asyncio.CancelledError, Exception):
+                pass
+            self._sweep_task = None
+        await self.close_all()
+
+    async def _sweep_loop(self) -> None:
+        """Periodically close idle workspaces.
+
+        Runs until cancelled. Each tick pops expired entries and closes
+        them outside the lock; failures are logged and swallowed so one
+        bad sandbox does not poison the sweeper.
+        """
+        while True:
+            try:
+                await asyncio.sleep(self._sweep_interval)
+            except asyncio.CancelledError:
+                return
+            try:
+                await self._sweep_once()
+            except Exception:
+                logger.exception("OpenSandbox workspace sweeper tick failed")
+
+    async def _sweep_once(self) -> None:
+        """One sweeper tick: evict expired entries and close them."""
+        now = time.monotonic()
+        async with self._lock:
+            expired_ids = [
+                wid
+                for wid, (_, ts) in self._cache.items()
+                if now - ts > self._ttl
+            ]
+            evicted = [self._cache.pop(wid)[0] for wid in expired_ids]
+        if not evicted:
+            return
+        await asyncio.gather(
+            *(self._safe_close(ws) for ws in evicted),
+            return_exceptions=True,
+        )
+
+    @staticmethod
+    async def _safe_close(ws: OpenSandboxWorkspace) -> None:
+        """Close a workspace, logging failures instead of raising."""
+        try:
+            await ws.close()
+        except Exception:
+            logger.exception(
+                "Failed to close OpenSandboxWorkspace %s",
+                ws.workspace_id,
+            )
diff --git a/src/agentscope/credential/__init__.py b/src/agentscope/credential/__init__.py
new file mode 100644
index 0000000..7368f3b
--- /dev/null
+++ b/src/agentscope/credential/__init__.py
@@ -0,0 +1,27 @@
+# -*- coding: utf-8 -*-
+"""The credential module."""
+
+from ._base import CredentialBase
+from ._anthropic import AnthropicCredential
+from ._dashscope import DashScopeCredential
+from ._deepseek import DeepSeekCredential
+from ._gemini import GeminiCredential
+from ._moonshot import MoonshotCredential
+from ._ollama import OllamaCredential
+from ._openai import OpenAICredential
+from ._xai import XAICredential
+from ._factory import CredentialFactory
+
+
+__all__ = [
+    "CredentialBase",
+    "AnthropicCredential",
+    "DashScopeCredential",
+    "DeepSeekCredential",
+    "GeminiCredential",
+    "MoonshotCredential",
+    "OllamaCredential",
+    "OpenAICredential",
+    "XAICredential",
+    "CredentialFactory",
+]
diff --git a/src/agentscope/credential/_anthropic.py b/src/agentscope/credential/_anthropic.py
new file mode 100644
index 0000000..df5dd89
--- /dev/null
+++ b/src/agentscope/credential/_anthropic.py
@@ -0,0 +1,39 @@
+# -*- coding: utf-8 -*-
+"""The Anthropic credential."""
+from typing import Literal, Type, TYPE_CHECKING
+
+from pydantic import Field, SecretStr, ConfigDict
+
+from ._base import CredentialBase
+
+if TYPE_CHECKING:
+    from ..model import ChatModelBase
+
+
+class AnthropicCredential(CredentialBase):
+    """The Anthropic credential model."""
+
+    model_config = ConfigDict(
+        title="Anthropic API",
+    )
+
+    type: Literal["anthropic_credential"] = "anthropic_credential"
+    """The credential type."""
+
+    api_key: SecretStr = Field(
+        description="The Anthropic API key",
+    )
+    """The API key."""
+
+    base_url: str | None = Field(
+        description="The base URL for the Anthropic API.",
+        default=None,
+    )
+    """The base URL for the Anthropic API."""
+
+    @classmethod
+    def get_chat_model_class(cls) -> Type["ChatModelBase"]:
+        """Return the AnthropicChatModel class."""
+        from ..model import AnthropicChatModel
+
+        return AnthropicChatModel
diff --git a/src/agentscope/credential/_base.py b/src/agentscope/credential/_base.py
new file mode 100644
index 0000000..906beab
--- /dev/null
+++ b/src/agentscope/credential/_base.py
@@ -0,0 +1,96 @@
+# -*- coding: utf-8 -*-
+"""The credential base class."""
+from typing import TYPE_CHECKING, Type
+
+from pydantic import BaseModel, Field
+
+from .._utils._common import _generate_id
+
+if TYPE_CHECKING:
+    from ..embedding import EmbeddingModelBase
+    from ..model import ChatModelBase, ModelCard
+    from ..tts import TTSModelBase
+    from ..tts._tts_model_card import TTSModelCard
+
+
+class CredentialBase(BaseModel):
+    """The credential base class."""
+
+    id: str = Field(
+        default_factory=_generate_id,
+        description="The credential id",
+    )
+
+    name: str = Field(
+        default="",
+        description="User-facing display name for this credential.",
+    )
+
+    @classmethod
+    def get_chat_model_class(cls) -> Type["ChatModelBase"]:
+        """Return the :class:`ChatModelBase` subclass that consumes this
+        credential. Subclasses must override this method to return the
+        corresponding chat model class.
+
+        Returns:
+            `Type[ChatModelBase]`:
+                The chat model class that uses this credential.
+        """
+        raise NotImplementedError(
+            f"{cls.__name__} must implement ``get_chat_model_class``.",
+        )
+
+    @classmethod
+    def get_tts_model_classes(cls) -> list[Type["TTSModelBase"]]:
+        """Return the TTS model classes supported by this credential.
+
+        Subclasses that support TTS should override this to return one or
+        more :class:`TTSModelBase` subclasses. The default returns an empty
+        list (provider does not support TTS).
+
+        Returns:
+            `list[Type[TTSModelBase]]`:
+                The TTS model classes, or an empty list.
+        """
+        return []
+
+    @classmethod
+    def list_tts_models(cls) -> list["TTSModelCard"]:
+        """List the candidate TTS models available under this credential.
+
+        Returns:
+            `list[TTSModelCard]`:
+                A list of TTS model cards, or empty if TTS is not supported.
+        """
+        cards: list["TTSModelCard"] = []
+        for tts_cls in cls.get_tts_model_classes():
+            cards.extend(tts_cls.list_models())
+        return cards
+
+    @classmethod
+    def list_models(cls) -> list["ModelCard"]:
+        """List the candidate chat models that are available under this
+        credential. The default implementation delegates to the
+        :meth:`ChatModelBase.list_models` of the class returned by
+        :meth:`get_chat_model_class`.
+
+        Returns:
+            `list[ModelCard]`:
+                A list of candidate models described by their model cards.
+        """
+        return cls.get_chat_model_class().list_models()
+
+    @classmethod
+    def get_embedding_model_class(cls) -> Type["EmbeddingModelBase"] | None:
+        """Return the :class:`EmbeddingModelBase` subclass that consumes
+        this credential, or ``None`` if this provider does not support
+        embedding models.
+
+        Subclasses that have a matching embedding implementation should
+        override this method. The default returns ``None``.
+
+        Returns:
+            `Type[EmbeddingModelBase] | None`:
+                The embedding model class, or ``None``.
+        """
+        return None
diff --git a/src/agentscope/credential/_dashscope.py b/src/agentscope/credential/_dashscope.py
new file mode 100644
index 0000000..11e6ab5
--- /dev/null
+++ b/src/agentscope/credential/_dashscope.py
@@ -0,0 +1,67 @@
+# -*- coding: utf-8 -*-
+"""The DashScope credential."""
+from typing import Literal, Type, TYPE_CHECKING
+
+from pydantic import ConfigDict, Field, SecretStr
+
+from ._base import CredentialBase
+
+if TYPE_CHECKING:
+    from ..embedding import EmbeddingModelBase
+    from ..model import ChatModelBase
+    from ..tts import TTSModelBase
+
+_DASHSCOPE_BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1"
+
+
+class DashScopeCredential(CredentialBase):
+    """The credential for DashScope API."""
+
+    model_config = ConfigDict(
+        title="DashScope API",
+    )
+
+    type: Literal["dashscope_credential"] = "dashscope_credential"
+    """The type of the credential."""
+
+    api_key: SecretStr = Field(
+        description="The DashScope API key.",
+        title="API Key",
+    )
+
+    base_url: str = Field(
+        default=_DASHSCOPE_BASE_URL,
+        title="API Base URL",
+        description=(
+            "The base URL for the DashScope OpenAI-compatible API endpoint."
+        ),
+    )
+
+    @classmethod
+    def get_chat_model_class(cls) -> Type["ChatModelBase"]:
+        """Return the DashScopeChatModel class."""
+        from ..model import DashScopeChatModel
+
+        return DashScopeChatModel
+
+    @classmethod
+    def get_tts_model_classes(cls) -> list[Type["TTSModelBase"]]:
+        """Return the DashScope TTS model classes."""
+        from ..tts import (
+            DashScopeCosyVoiceTTSModel,
+            DashScopeRealtimeTTSModel,
+            DashScopeTTSModel,
+        )
+
+        return [
+            DashScopeTTSModel,
+            DashScopeRealtimeTTSModel,
+            DashScopeCosyVoiceTTSModel,
+        ]
+
+    @classmethod
+    def get_embedding_model_class(cls) -> Type["EmbeddingModelBase"]:
+        """Return the DashScopeEmbeddingModel class."""
+        from ..embedding import DashScopeEmbeddingModel
+
+        return DashScopeEmbeddingModel
diff --git a/src/agentscope/credential/_deepseek.py b/src/agentscope/credential/_deepseek.py
new file mode 100644
index 0000000..d12088c
--- /dev/null
+++ b/src/agentscope/credential/_deepseek.py
@@ -0,0 +1,41 @@
+# -*- coding: utf-8 -*-
+"""The DeepSeek credential."""
+from typing import Literal, Type, TYPE_CHECKING
+
+from pydantic import ConfigDict, Field, SecretStr
+
+from ._base import CredentialBase
+
+if TYPE_CHECKING:
+    from ..model import ChatModelBase
+
+_DEEPSEEK_BASE_URL = "https://api.deepseek.com"
+
+
+class DeepSeekCredential(CredentialBase):
+    """The DeepSeek credential model."""
+
+    model_config = ConfigDict(
+        title="DeepSeek API",
+    )
+
+    type: Literal["deepseek_credential"] = "deepseek_credential"
+    """The credential type."""
+
+    api_key: SecretStr = Field(
+        description="The DeepSeek API key.",
+    )
+    """The API key."""
+
+    base_url: str = Field(
+        default=_DEEPSEEK_BASE_URL,
+        description="The base URL for the DeepSeek API.",
+    )
+    """The base URL for the DeepSeek API."""
+
+    @classmethod
+    def get_chat_model_class(cls) -> Type["ChatModelBase"]:
+        """Return the DeepSeekChatModel class."""
+        from ..model import DeepSeekChatModel
+
+        return DeepSeekChatModel
diff --git a/src/agentscope/credential/_factory.py b/src/agentscope/credential/_factory.py
new file mode 100644
index 0000000..7af1ab3
--- /dev/null
+++ b/src/agentscope/credential/_factory.py
@@ -0,0 +1,116 @@
+# -*- coding: utf-8 -*-
+"""The credential factory class."""
+from typing import Annotated, Type, Union, get_args, get_type_hints
+
+from pydantic import TypeAdapter, Field
+
+from ._anthropic import AnthropicCredential
+from ._dashscope import DashScopeCredential
+from ._deepseek import DeepSeekCredential
+from ._gemini import GeminiCredential
+from ._moonshot import MoonshotCredential
+from ._ollama import OllamaCredential
+from ._openai import OpenAICredential
+from ._xai import XAICredential
+from ._base import CredentialBase
+
+
+class CredentialFactory:
+    """Registry and deserializer for :class:`CredentialBase` subclasses.
+
+    Built-in credential types are pre-registered.  Call
+    :meth:`register_credential` to add custom types before starting the app.
+
+    Usage::
+
+        # Deserialize from storage
+        credential = CredentialFactory.from_dict(record.data)
+
+        # Register a custom type
+        CredentialFactory.register_credential(MyCredential)
+
+        # List schemas for the frontend form
+        schemas = CredentialFactory.list_schemas()
+    """
+
+    _classes: list[Type[CredentialBase]] = [
+        AnthropicCredential,
+        DashScopeCredential,
+        DeepSeekCredential,
+        GeminiCredential,
+        MoonshotCredential,
+        OllamaCredential,
+        OpenAICredential,
+        XAICredential,
+    ]
+    _adapter: TypeAdapter[CredentialBase] | None = None
+
+    @classmethod
+    def _get_adapter(cls) -> TypeAdapter[CredentialBase]:
+        if cls._adapter is None:
+            union = Annotated[  # type: ignore[valid-type]
+                Union[tuple(cls._classes)],
+                Field(discriminator="type"),
+            ]
+            cls._adapter = TypeAdapter(union)
+        return cls._adapter
+
+    @classmethod
+    def register_credential(cls, credential_cls: Type[CredentialBase]) -> None:
+        """Register a custom :class:`CredentialBase` subclass.
+
+        The class must define a ``type`` field with a unique ``Literal``
+        default so Pydantic can use it as a discriminator.
+
+        Args:
+            credential_cls: The subclass to register.
+        """
+        if credential_cls in cls._classes:
+            return
+        cls._classes.append(credential_cls)
+        cls._adapter = None  # invalidate so it's rebuilt on next use
+
+    @classmethod
+    def from_dict(cls, data: dict) -> CredentialBase:
+        """Deserialize a credential dict (from storage) to a typed instance.
+
+        Args:
+            data: Raw dict containing a ``"type"`` key.
+
+        Returns:
+            A typed :class:`CredentialBase` subclass instance.
+        """
+        return cls._get_adapter().validate_python(data)
+
+    @classmethod
+    def get_credential_class(
+        cls,
+        provider: str,
+    ) -> Type[CredentialBase] | None:
+        """Return the credential class for the given provider type, or None.
+
+        Args:
+            provider: The ``type`` discriminator value (e.g. ``"openai"``).
+
+        Returns:
+            The matching :class:`CredentialBase` subclass, or ``None`` if not
+            found.
+        """
+        for c in cls._classes:
+            hints = get_type_hints(c)
+            type_hint = hints.get("type")
+            if type_hint is None:
+                continue
+            args = get_args(type_hint)
+
+            if args and args[0] == provider:
+                return c
+        return None
+
+    @classmethod
+    def list_schemas(cls) -> list[dict]:
+        """Return JSON schemas for all registered credential types.
+
+        Used by the frontend to render credential forms dynamically.
+        """
+        return [c.model_json_schema() for c in cls._classes]
diff --git a/src/agentscope/credential/_gemini.py b/src/agentscope/credential/_gemini.py
new file mode 100644
index 0000000..43775cc
--- /dev/null
+++ b/src/agentscope/credential/_gemini.py
@@ -0,0 +1,41 @@
+# -*- coding: utf-8 -*-
+"""The Google Gemini credential."""
+from typing import Literal, Type, TYPE_CHECKING
+
+from pydantic import ConfigDict, Field, SecretStr
+
+from ._base import CredentialBase
+
+if TYPE_CHECKING:
+    from ..embedding import EmbeddingModelBase
+    from ..model import ChatModelBase
+
+
+class GeminiCredential(CredentialBase):
+    """The Google Gemini credential model."""
+
+    model_config = ConfigDict(
+        title="Gemini API",
+    )
+
+    type: Literal["gemini_credential"] = "gemini_credential"
+    """The credential type."""
+
+    api_key: SecretStr = Field(
+        description="The Google Gemini API key.",
+    )
+    """The API key."""
+
+    @classmethod
+    def get_chat_model_class(cls) -> Type["ChatModelBase"]:
+        """Return the GeminiChatModel class."""
+        from ..model import GeminiChatModel
+
+        return GeminiChatModel
+
+    @classmethod
+    def get_embedding_model_class(cls) -> Type["EmbeddingModelBase"]:
+        """Return the GeminiEmbeddingModel class."""
+        from ..embedding import GeminiEmbeddingModel
+
+        return GeminiEmbeddingModel
diff --git a/src/agentscope/credential/_kimi.py b/src/agentscope/credential/_kimi.py
new file mode 100644
index 0000000..e69de29
diff --git a/src/agentscope/credential/_moonshot.py b/src/agentscope/credential/_moonshot.py
new file mode 100644
index 0000000..0ce5728
--- /dev/null
+++ b/src/agentscope/credential/_moonshot.py
@@ -0,0 +1,41 @@
+# -*- coding: utf-8 -*-
+"""The Moonshot AI credential."""
+from typing import Literal, Type, TYPE_CHECKING
+
+from pydantic import ConfigDict, Field, SecretStr
+
+from ._base import CredentialBase
+
+if TYPE_CHECKING:
+    from ..model import ChatModelBase
+
+_MOONSHOT_BASE_URL = "https://api.moonshot.cn/v1"
+
+
+class MoonshotCredential(CredentialBase):
+    """The Moonshot AI credential model."""
+
+    model_config = ConfigDict(
+        title="Moonshot API",
+    )
+
+    type: Literal["moonshot_credential"] = "moonshot_credential"
+    """The credential type."""
+
+    api_key: SecretStr = Field(
+        description="The Moonshot AI API key.",
+    )
+    """The API key."""
+
+    base_url: str = Field(
+        default=_MOONSHOT_BASE_URL,
+        description="The base URL for the Moonshot AI API.",
+    )
+    """The base URL for the Moonshot AI API."""
+
+    @classmethod
+    def get_chat_model_class(cls) -> Type["ChatModelBase"]:
+        """Return the MoonshotChatModel class."""
+        from ..model import MoonshotChatModel
+
+        return MoonshotChatModel
diff --git a/src/agentscope/credential/_ollama.py b/src/agentscope/credential/_ollama.py
new file mode 100644
index 0000000..c2c27f9
--- /dev/null
+++ b/src/agentscope/credential/_ollama.py
@@ -0,0 +1,45 @@
+# -*- coding: utf-8 -*-
+"""The Ollama credential."""
+from typing import Literal, Type, TYPE_CHECKING
+
+from pydantic import ConfigDict, Field
+
+from ._base import CredentialBase
+
+if TYPE_CHECKING:
+    from ..embedding import EmbeddingModelBase
+    from ..model import ChatModelBase
+
+
+class OllamaCredential(CredentialBase):
+    """The Ollama credential model (connection settings)."""
+
+    model_config = ConfigDict(
+        title="Ollama API",
+    )
+
+    type: Literal["ollama_credential"] = "ollama_credential"
+    """The credential type."""
+
+    host: str | None = Field(
+        default=None,
+        description=(
+            "The Ollama server host URL. "
+            "Defaults to http://localhost:11434 if not specified."
+        ),
+    )
+    """The Ollama server host URL."""
+
+    @classmethod
+    def get_chat_model_class(cls) -> Type["ChatModelBase"]:
+        """Return the OllamaChatModel class."""
+        from ..model import OllamaChatModel
+
+        return OllamaChatModel
+
+    @classmethod
+    def get_embedding_model_class(cls) -> Type["EmbeddingModelBase"]:
+        """Return the OllamaEmbeddingModel class."""
+        from ..embedding import OllamaEmbeddingModel
+
+        return OllamaEmbeddingModel
diff --git a/src/agentscope/credential/_openai.py b/src/agentscope/credential/_openai.py
new file mode 100644
index 0000000..ec746ce
--- /dev/null
+++ b/src/agentscope/credential/_openai.py
@@ -0,0 +1,64 @@
+# -*- coding: utf-8 -*-
+"""The OpenAI credential."""
+from typing import Literal, Type, TYPE_CHECKING
+
+from pydantic import ConfigDict, Field, SecretStr
+
+from ._base import CredentialBase
+
+if TYPE_CHECKING:
+    from ..embedding import EmbeddingModelBase
+    from ..model import ChatModelBase
+    from ..tts import TTSModelBase
+
+
+class OpenAICredential(CredentialBase):
+    """The OpenAI credential model."""
+
+    model_config = ConfigDict(
+        title="OpenAI API",
+    )
+
+    type: Literal["openai_credential"] = "openai_credential"
+    """The credential type."""
+
+    api_key: SecretStr = Field(
+        description="The OpenAI API key.",
+    )
+    """The API key."""
+
+    organization: str | None = Field(
+        default=None,
+        description="The OpenAI organization ID.",
+    )
+    """The OpenAI organization ID."""
+
+    base_url: str | None = Field(
+        default=None,
+        description=(
+            "The base URL for the OpenAI API. "
+            "Can be used for OpenAI-compatible endpoints."
+        ),
+    )
+    """Custom base URL for OpenAI-compatible endpoints."""
+
+    @classmethod
+    def get_chat_model_class(cls) -> Type["ChatModelBase"]:
+        """Return the OpenAIChatModel class."""
+        from ..model import OpenAIChatModel
+
+        return OpenAIChatModel
+
+    @classmethod
+    def get_embedding_model_class(cls) -> Type["EmbeddingModelBase"]:
+        """Return the OpenAIEmbeddingModel class."""
+        from ..embedding import OpenAIEmbeddingModel
+
+        return OpenAIEmbeddingModel
+
+    @classmethod
+    def get_tts_model_classes(cls) -> list[Type["TTSModelBase"]]:
+        """Return the OpenAI TTS model classes."""
+        from ..tts import OpenAITTSModel
+
+        return [OpenAITTSModel]
diff --git a/src/agentscope/credential/_xai.py b/src/agentscope/credential/_xai.py
new file mode 100644
index 0000000..ec0df64
--- /dev/null
+++ b/src/agentscope/credential/_xai.py
@@ -0,0 +1,43 @@
+# -*- coding: utf-8 -*-
+"""The xAI credential."""
+from typing import Literal, Type, TYPE_CHECKING
+
+from pydantic import ConfigDict, Field, SecretStr
+
+from ._base import CredentialBase
+
+if TYPE_CHECKING:
+    from ..model import ChatModelBase
+
+
+class XAICredential(CredentialBase):
+    """The xAI credential model."""
+
+    model_config = ConfigDict(
+        title="xAI API",
+    )
+
+    type: Literal["xai_credential"] = "xai_credential"
+    """The credential type."""
+
+    api_key: SecretStr = Field(
+        description="The xAI API key.",
+    )
+    """The xAI API key."""
+
+    api_host: str = Field(
+        default="api.x.ai",
+        title="API Host",
+        description=(
+            "The xAI API host (without scheme). Override to point at a "
+            "compatible/self-hosted endpoint."
+        ),
+    )
+    """The xAI API host."""
+
+    @classmethod
+    def get_chat_model_class(cls) -> Type["ChatModelBase"]:
+        """Return the XAIChatModel class."""
+        from ..model import XAIChatModel
+
+        return XAIChatModel
diff --git a/src/agentscope/embedding/__init__.py b/src/agentscope/embedding/__init__.py
new file mode 100644
index 0000000..43731f1
--- /dev/null
+++ b/src/agentscope/embedding/__init__.py
@@ -0,0 +1,27 @@
+# -*- coding: utf-8 -*-
+"""The embedding module in agentscope."""
+
+from ._embedding_base import EmbeddingModelBase
+from ._embedding_model_card import EmbeddingModelCard
+from ._embedding_usage import EmbeddingUsage
+from ._embedding_response import EmbeddingResponse
+from ._dashscope import DashScopeEmbeddingModel
+from ._openai import OpenAIEmbeddingModel
+from ._gemini import GeminiEmbeddingModel
+from ._ollama import OllamaEmbeddingModel
+from ._cache_base import EmbeddingCacheBase
+from ._file_cache import FileEmbeddingCache
+
+
+__all__ = [
+    "EmbeddingModelBase",
+    "EmbeddingModelCard",
+    "EmbeddingUsage",
+    "EmbeddingResponse",
+    "DashScopeEmbeddingModel",
+    "OpenAIEmbeddingModel",
+    "GeminiEmbeddingModel",
+    "OllamaEmbeddingModel",
+    "EmbeddingCacheBase",
+    "FileEmbeddingCache",
+]
diff --git a/src/agentscope/embedding/_cache_base.py b/src/agentscope/embedding/_cache_base.py
new file mode 100644
index 0000000..da27b5b
--- /dev/null
+++ b/src/agentscope/embedding/_cache_base.py
@@ -0,0 +1,63 @@
+# -*- coding: utf-8 -*-
+"""The embedding cache base class."""
+from abc import abstractmethod
+from typing import List, Any
+
+from ..types import (
+    JSONSerializableObject,
+    Embedding,
+)
+
+
+class EmbeddingCacheBase:
+    """Base class for embedding caches, which is responsible for storing and
+    retrieving embeddings."""
+
+    @abstractmethod
+    async def store(
+        self,
+        embeddings: List[Embedding],
+        identifier: JSONSerializableObject,
+        overwrite: bool = False,
+        **kwargs: Any,
+    ) -> None:
+        """Store the embeddings with the given identifier.
+
+        Args:
+            embeddings (`List[Embedding]`):
+                The embeddings to store.
+            identifier (`JSONSerializableObject`):
+                The identifier to distinguish the embeddings.
+            overwrite (`bool`, defaults to `False`):
+                Whether to overwrite existing embeddings with the same
+                identifier. If `True`, existing embeddings will be replaced.
+        """
+
+    @abstractmethod
+    async def retrieve(
+        self,
+        identifier: JSONSerializableObject,
+    ) -> List[Embedding] | None:
+        """Retrieve the embeddings with the given identifier. If not
+        found, return `None`.
+
+        Args:
+            identifier (`JSONSerializableObject`):
+                The identifier to retrieve the embeddings.
+        """
+
+    @abstractmethod
+    async def remove(
+        self,
+        identifier: JSONSerializableObject,
+    ) -> None:
+        """Remove the embeddings with the given identifier.
+
+        Args:
+            identifier (`JSONSerializableObject`):
+                The identifier to remove the embeddings.
+        """
+
+    @abstractmethod
+    async def clear(self) -> None:
+        """Clear all cached embeddings."""
diff --git a/src/agentscope/embedding/_dashscope/__init__.py b/src/agentscope/embedding/_dashscope/__init__.py
new file mode 100644
index 0000000..37f3c96
--- /dev/null
+++ b/src/agentscope/embedding/_dashscope/__init__.py
@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+"""The DashScope embedding API modules."""
+
+from ._model import DashScopeEmbeddingModel
+
+__all__ = [
+    "DashScopeEmbeddingModel",
+]
diff --git a/src/agentscope/embedding/_dashscope/_model.py b/src/agentscope/embedding/_dashscope/_model.py
new file mode 100644
index 0000000..81f1b08
--- /dev/null
+++ b/src/agentscope/embedding/_dashscope/_model.py
@@ -0,0 +1,529 @@
+# -*- coding: utf-8 -*-
+"""The DashScope embedding model.
+
+Handles both text-only and multimodal models under a single class.
+Text models (``text-embedding-v3``, ``text-embedding-v4``) accept
+``list[str | TextBlock]``.  Multimodal models (``qwen*-vl-embedding``,
+``multimodal-embedding-*``, ``tongyi-embedding-vision-*``)
+additionally accept :class:`~agentscope.message.DataBlock`.
+The model name determines which DashScope API endpoint is used.
+
+Text payloads may be passed either as bare ``str`` or as
+:class:`~agentscope.message.TextBlock` — the latter is unpacked to its
+``.text`` field on entry so the rest of the pipeline only deals with
+``str`` and ``DataBlock``.
+"""
+from __future__ import annotations
+
+import asyncio
+from datetime import datetime
+from dataclasses import dataclass
+from typing import Any
+
+from .._cache_base import EmbeddingCacheBase
+from .._embedding_response import EmbeddingResponse
+from .._embedding_usage import EmbeddingUsage
+from .._embedding_base import EmbeddingModelBase
+from ..._logging import logger
+from ...credential import CredentialBase
+from ...message import DataBlock, Base64Source, TextBlock, URLSource
+
+#: Model name prefixes that route to the multimodal API.
+_MULTIMODAL_PREFIXES = (
+    "multimodal-embedding-",
+    "tongyi-embedding-vision-",
+    "qwen3-vl-embedding",
+    "qwen2.5-vl-embedding",
+)
+
+
+@dataclass
+class _MultimodalLimits:
+    """Per-request constraints for a multimodal embedding model."""
+
+    max_elements: int = 20
+    """Maximum total content elements per API call."""
+
+    max_images: int = 5
+    """Maximum image elements per API call."""
+
+    max_videos: int = 1
+    """Maximum video elements per API call."""
+
+
+#: Known per-model multimodal constraints (from DashScope docs).
+_MODEL_LIMITS: dict[str, _MultimodalLimits] = {
+    "qwen3-vl-embedding": _MultimodalLimits(
+        max_elements=20,
+        max_images=5,
+        max_videos=1,
+    ),
+    "qwen2.5-vl-embedding": _MultimodalLimits(
+        max_elements=20,
+        max_images=5,
+        max_videos=1,
+    ),
+    "tongyi-embedding-vision-plus": _MultimodalLimits(
+        max_elements=20,
+        max_images=64,
+        max_videos=8,
+    ),
+    "tongyi-embedding-vision-flash": _MultimodalLimits(
+        max_elements=20,
+        max_images=64,
+        max_videos=8,
+    ),
+    "multimodal-embedding-v1": _MultimodalLimits(
+        max_elements=20,
+        max_images=1,
+        max_videos=1,
+    ),
+}
+
+#: Fallback for unknown multimodal models — safest constraints.
+_DEFAULT_LIMITS = _MultimodalLimits(
+    max_elements=20,
+    max_images=1,
+    max_videos=1,
+)
+
+
+class DashScopeEmbeddingModel(EmbeddingModelBase[str | TextBlock | DataBlock]):
+    """Unified DashScope embedding model.
+
+    Routes to the text or multimodal DashScope API based on the model
+    name.
+
+    - **Text mode** (``text-embedding-*``): uses the base class's
+      simple batch splitting + concurrent retry.
+    - **Multimodal mode** (``qwen*-vl-*``, ``multimodal-*``,
+      ``tongyi-embedding-vision-*``): overrides ``__call__`` to
+      perform content-aware batching that respects per-model limits
+      on total elements, images, and videos per request.
+    """
+
+    #: Text-mode batch size (from DashScope docs: 10 for v3/v4, 25 for
+    #: v1/v2).  Multimodal models use :data:`_MODEL_LIMITS` instead.
+    _TEXT_BATCH_SIZE: int = 10
+
+    def __init__(
+        self,
+        credential: CredentialBase,
+        model: str,
+        dimensions: int | None,
+        parameters: "DashScopeEmbeddingModel.Parameters | None" = None,
+        embedding_cache: EmbeddingCacheBase | None = None,
+        context_size: int = 8192,
+        max_retries: int = 3,
+        retry_delay: float = 1.0,
+    ) -> None:
+        """Initialize the DashScope embedding model.
+
+        Args:
+            credential (`CredentialBase`):
+                A :class:`~agentscope.credential.DashScopeCredential`
+                instance providing the API key.
+            model (`str`):
+                The embedding model name (e.g.
+                ``"text-embedding-v4"`` or
+                ``"qwen3-vl-embedding"``).
+            dimensions (`int | None`):
+                The output embedding vector dimensions.  Required at
+                the contract level — see :class:`EmbeddingModelBase`
+                for the rationale.  ``None`` is accepted only for
+                backward compatibility with legacy configs that
+                persisted ``dimensions`` inside ``parameters``.
+            parameters (`DashScopeEmbeddingModel.Parameters | None`, \
+            defaults to ``None``):
+                Provider-specific non-dimensional parameters.  Currently
+                empty for DashScope.
+            embedding_cache (`EmbeddingCacheBase | None`, defaults to \
+            ``None``):
+                Optional embedding cache.
+            context_size (`int`, defaults to ``8192``):
+                Maximum input tokens per text.
+            max_retries (`int`, defaults to ``3``):
+                Number of retries on transient failures.
+            retry_delay (`float`, defaults to ``1.0``):
+                Seconds between retry attempts.
+        """
+        self._is_multimodal: bool = model.startswith(_MULTIMODAL_PREFIXES)
+
+        super().__init__(
+            credential=credential,
+            model=model,
+            dimensions=dimensions,
+            parameters=parameters,
+            context_size=context_size,
+            batch_size=self._TEXT_BATCH_SIZE,
+            max_retries=max_retries,
+            retry_delay=retry_delay,
+        )
+        self.api_key: str = credential.api_key.get_secret_value()
+        self.embedding_cache: EmbeddingCacheBase | None = embedding_cache
+
+        # Resolve multimodal constraints.
+        if self._is_multimodal:
+            self._limits = _MODEL_LIMITS.get(model, _DEFAULT_LIMITS)
+
+    @classmethod
+    def _get_retryable_exceptions(cls) -> tuple[type[Exception], ...]:
+        """Return retryable exception types.
+
+        DashScope SDK does not expose typed exception classes.  We
+        retry on ``RuntimeError``, which is raised when the API
+        returns a non-200 status code.
+        """
+        return (RuntimeError,)
+
+    # ------------------------------------------------------------------
+    # __call__ — override for multimodal content-aware batching
+    # ------------------------------------------------------------------
+
+    async def __call__(
+        self,
+        inputs: list[str | TextBlock | DataBlock],
+        **kwargs: Any,
+    ) -> EmbeddingResponse:
+        """Embed inputs with batching and retry.
+
+        For text models, delegates to the base class (simple
+        ``batch_size`` splitting).  For multimodal models, performs
+        content-aware batching that respects per-model limits on
+        total elements, images, and videos per request.
+
+        Args:
+            inputs (`list[str | TextBlock | DataBlock]`):
+                The input data to embed.  ``TextBlock`` items are
+                unpacked to their ``.text`` field on entry, so the
+                remainder of the pipeline only sees ``str`` and
+                ``DataBlock``.
+            **kwargs:
+                Forwarded to the DashScope API.
+
+        Returns:
+            `EmbeddingResponse`: Merged response for all inputs.
+        """
+        normalized: list[str | DataBlock] = [
+            item.text if isinstance(item, TextBlock) else item
+            for item in inputs
+        ]
+
+        if not self._is_multimodal:
+            # Text mode — use base class batching.
+            return await super().__call__(normalized, **kwargs)
+
+        # Multimodal mode — content-aware batching.
+        batches = self._split_multimodal_batches(normalized)
+
+        if len(batches) > 1:
+            logger.info(
+                "Embedding %d multimodal inputs in %d batches for "
+                "model %s (limits: elements=%d, images=%d, videos=%d).",
+                len(normalized),
+                len(batches),
+                self.model,
+                self._limits.max_elements,
+                self._limits.max_images,
+                self._limits.max_videos,
+            )
+
+        results: list[EmbeddingResponse] = await asyncio.gather(
+            *(self._call_with_retry(batch, **kwargs) for batch in batches),
+        )
+
+        return self._merge_responses(results)
+
+    def _split_multimodal_batches(
+        self,
+        inputs: list[str | DataBlock],
+    ) -> list[list[str | DataBlock]]:
+        """Split inputs into batches that satisfy multimodal limits.
+
+        Greedy algorithm: keep adding items to the current batch
+        until adding the next item would violate any constraint,
+        then start a new batch.
+
+        Args:
+            inputs (`list[str | DataBlock]`):
+                All inputs to split.
+
+        Returns:
+            `list[list[str | DataBlock]]`: List of batches.
+        """
+        limits = self._limits
+        batches: list[list[str | DataBlock]] = []
+        current_batch: list[str | DataBlock] = []
+        n_elements = 0
+        n_images = 0
+        n_videos = 0
+
+        for item in inputs:
+            # Determine what this item contributes.
+            is_image = False
+            is_video = False
+            if isinstance(item, DataBlock):
+                media_type = item.source.media_type
+                is_image = media_type.startswith("image/")
+                is_video = media_type.startswith("video/")
+
+            # Check if adding this item would exceed any limit.
+            would_exceed = (
+                n_elements + 1 > limits.max_elements
+                or (is_image and n_images + 1 > limits.max_images)
+                or (is_video and n_videos + 1 > limits.max_videos)
+            )
+
+            if would_exceed and current_batch:
+                batches.append(current_batch)
+                current_batch = []
+                n_elements = 0
+                n_images = 0
+                n_videos = 0
+
+            current_batch.append(item)
+            n_elements += 1
+            if is_image:
+                n_images += 1
+            if is_video:
+                n_videos += 1
+
+        if current_batch:
+            batches.append(current_batch)
+
+        return batches
+
+    # ------------------------------------------------------------------
+    # _call_api — single batch dispatch
+    # ------------------------------------------------------------------
+
+    async def _call_api(
+        self,
+        inputs: list[str | DataBlock],
+        **kwargs: Any,
+    ) -> EmbeddingResponse:
+        """Route to the text or multimodal DashScope API.
+
+        Args:
+            inputs (`list[str | DataBlock]`):
+                A single batch.  For text models every element must be
+                ``str``; for multimodal models elements may also be
+                :class:`~agentscope.message.DataBlock`.
+            **kwargs:
+                Forwarded to the DashScope API.
+
+        Returns:
+            `EmbeddingResponse`: Embedding vectors and usage info.
+        """
+        if self._is_multimodal:
+            return await self._call_multimodal(inputs, **kwargs)
+        return await self._call_text(inputs, **kwargs)
+
+    # ------------------------------------------------------------------
+    # Text API
+    # ------------------------------------------------------------------
+
+    async def _call_text(
+        self,
+        inputs: list[str | DataBlock],
+        **kwargs: Any,
+    ) -> EmbeddingResponse:
+        """Call the DashScope text embedding API for a single batch.
+
+        Args:
+            inputs (`list[str | DataBlock]`):
+                Must all be ``str``; raises ``ValueError`` otherwise.
+            **kwargs:
+                Forwarded to the API.
+
+        Returns:
+            `EmbeddingResponse`: Embedding vectors and usage info.
+        """
+        texts: list[str] = []
+        for item in inputs:
+            if not isinstance(item, str):
+                raise ValueError(
+                    f"Text embedding model {self.model!r} only accepts "
+                    f"str inputs, got {type(item).__name__}.",
+                )
+            texts.append(item)
+
+        api_kwargs: dict[str, Any] = {
+            "input": texts,
+            "model": self.model,
+            "dimension": self.dimensions,
+            **kwargs,
+        }
+
+        if self.embedding_cache:
+            cached = await self.embedding_cache.retrieve(
+                identifier=api_kwargs,
+            )
+            if cached:
+                return EmbeddingResponse(
+                    embeddings=cached,
+                    usage=EmbeddingUsage(tokens=0, time=0),
+                    source="cache",
+                )
+
+        import dashscope
+
+        start_time = datetime.now()
+        response = dashscope.embeddings.TextEmbedding.call(
+            api_key=self.api_key,
+            **api_kwargs,
+        )
+        time = (datetime.now() - start_time).total_seconds()
+
+        if response.status_code != 200:
+            raise RuntimeError(
+                f"DashScope text embedding API error: {response}",
+            )
+
+        embeddings = [
+            entry["embedding"] for entry in response.output["embeddings"]
+        ]
+        if self.embedding_cache:
+            await self.embedding_cache.store(
+                identifier=api_kwargs,
+                embeddings=embeddings,
+            )
+        return EmbeddingResponse(
+            embeddings=embeddings,
+            usage=EmbeddingUsage(
+                tokens=response.usage["total_tokens"],
+                time=time,
+            ),
+        )
+
+    # ------------------------------------------------------------------
+    # Multimodal API
+    # ------------------------------------------------------------------
+
+    async def _call_multimodal(
+        self,
+        inputs: list[str | DataBlock],
+        **kwargs: Any,
+    ) -> EmbeddingResponse:
+        """Call the DashScope multimodal embedding API for a single batch.
+
+        Args:
+            inputs (`list[str | DataBlock]`):
+                ``str`` for text, ``DataBlock`` for images / videos.
+            **kwargs:
+                Forwarded to the API.
+
+        Returns:
+            `EmbeddingResponse`: Embedding vectors and usage info.
+        """
+        formatted: list[dict[str, str]] = []
+        for item in inputs:
+            if isinstance(item, str):
+                formatted.append({"text": item})
+            elif isinstance(item, DataBlock):
+                formatted.append(self._format_data_block(item))
+            else:
+                raise ValueError(
+                    f"Invalid input: {item!r}. Expected str or DataBlock.",
+                )
+
+        api_kwargs: dict[str, Any] = {
+            "input": formatted,
+            "model": self.model,
+            "api_key": self.api_key,
+            **kwargs,
+        }
+
+        # Exclude api_key from cache identifier to avoid persisting secrets
+        # and to keep cache valid across key rotations.
+        cache_identifier = {
+            k: v for k, v in api_kwargs.items() if k != "api_key"
+        }
+
+        if self.embedding_cache:
+            cached = await self.embedding_cache.retrieve(
+                identifier=cache_identifier,
+            )
+            if cached:
+                return EmbeddingResponse(
+                    embeddings=cached,
+                    usage=EmbeddingUsage(tokens=0, time=0),
+                    source="cache",
+                )
+
+        import dashscope
+
+        start_time = datetime.now()
+        res = dashscope.MultiModalEmbedding.call(**api_kwargs)
+        time = (datetime.now() - start_time).total_seconds()
+
+        if res.status_code != 200:
+            raise RuntimeError(
+                f"DashScope multimodal embedding API error: {res}",
+            )
+
+        embeddings = [entry["embedding"] for entry in res.output["embeddings"]]
+        if self.embedding_cache:
+            await self.embedding_cache.store(
+                identifier=cache_identifier,
+                embeddings=embeddings,
+            )
+        return EmbeddingResponse(
+            embeddings=embeddings,
+            usage=EmbeddingUsage(
+                tokens=res.usage.get("image_tokens", 0)
+                + res.usage.get("input_tokens", 0),
+                time=time,
+            ),
+            source="api",
+        )
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _format_data_block(block: DataBlock) -> dict[str, str]:
+        """Convert a :class:`~agentscope.message.DataBlock` to the dict
+        format expected by the DashScope multimodal embedding API.
+
+        The ``DataBlock.source.media_type`` determines whether the
+        block is treated as an image or video.
+
+        Args:
+            block (`DataBlock`):
+                A data block with a ``Base64Source`` or ``URLSource``.
+
+        Returns:
+            `dict[str, str]`: E.g.
+            ``{"image": "data:image/png;base64,..."}`` or
+            ``{"video": "https://..."}``.
+
+        Raises:
+            `ValueError`: If the media type is unsupported or a video
+                block uses a non-URL source.
+        """
+
+        source = block.source
+        media_type = source.media_type
+
+        if media_type.startswith("video/"):
+            if not isinstance(source, URLSource):
+                raise ValueError(
+                    "Multimodal embedding API only supports URL input "
+                    f"for video data, got {type(source).__name__}.",
+                )
+            return {"video": str(source.url)}
+
+        if media_type.startswith("image/"):
+            if isinstance(source, Base64Source):
+                return {
+                    "image": f"data:{media_type};" f"base64,{source.data}",
+                }
+            if isinstance(source, URLSource):
+                return {"image": str(source.url)}
+
+        raise ValueError(
+            f"Unsupported media type {media_type!r} in DataBlock. "
+            f"Expected image/* or video/*.",
+        )
diff --git a/src/agentscope/embedding/_dashscope/_models/multimodal-embedding-v1.yaml b/src/agentscope/embedding/_dashscope/_models/multimodal-embedding-v1.yaml
new file mode 100644
index 0000000..58cefd6
--- /dev/null
+++ b/src/agentscope/embedding/_dashscope/_models/multimodal-embedding-v1.yaml
@@ -0,0 +1,16 @@
+name: multimodal-embedding-v1
+label: Multimodal Embedding v1
+status: active
+
+input_types:
+  - text/plain
+  - image/jpeg
+  - image/png
+  - image/bmp
+
+output_types:
+  - application/x-embedding
+
+context_size: 512
+
+dimensions: 1024
diff --git a/src/agentscope/embedding/_dashscope/_models/qwen2.5-vl-embedding.yaml b/src/agentscope/embedding/_dashscope/_models/qwen2.5-vl-embedding.yaml
new file mode 100644
index 0000000..b5ebec7
--- /dev/null
+++ b/src/agentscope/embedding/_dashscope/_models/qwen2.5-vl-embedding.yaml
@@ -0,0 +1,20 @@
+name: qwen2.5-vl-embedding
+label: Qwen2.5 VL Embedding
+status: active
+
+input_types:
+  - text/plain
+  - image/jpeg
+  - image/png
+  - image/webp
+  - image/bmp
+  - image/tiff
+  - video/mp4
+
+output_types:
+  - application/x-embedding
+
+context_size: 32000
+
+dimensions: 1024
+supported_dimensions: [2048, 1024, 768, 512]
diff --git a/src/agentscope/embedding/_dashscope/_models/qwen3-vl-embedding.yaml b/src/agentscope/embedding/_dashscope/_models/qwen3-vl-embedding.yaml
new file mode 100644
index 0000000..900c6fb
--- /dev/null
+++ b/src/agentscope/embedding/_dashscope/_models/qwen3-vl-embedding.yaml
@@ -0,0 +1,20 @@
+name: qwen3-vl-embedding
+label: Qwen3 VL Embedding
+status: active
+
+input_types:
+  - text/plain
+  - image/jpeg
+  - image/png
+  - image/webp
+  - image/bmp
+  - image/tiff
+  - video/mp4
+
+output_types:
+  - application/x-embedding
+
+context_size: 32000
+
+dimensions: 2560
+supported_dimensions: [2560, 2048, 1536, 1024, 768, 512, 256]
diff --git a/src/agentscope/embedding/_dashscope/_models/text-embedding-v3.yaml b/src/agentscope/embedding/_dashscope/_models/text-embedding-v3.yaml
new file mode 100644
index 0000000..c344d32
--- /dev/null
+++ b/src/agentscope/embedding/_dashscope/_models/text-embedding-v3.yaml
@@ -0,0 +1,14 @@
+name: text-embedding-v3
+label: Text Embedding v3
+status: active
+
+input_types:
+  - text/plain
+
+output_types:
+  - application/x-embedding
+
+context_size: 8192
+
+dimensions: 1024
+supported_dimensions: [1024, 768, 512, 256, 128, 64]
diff --git a/src/agentscope/embedding/_dashscope/_models/text-embedding-v4.yaml b/src/agentscope/embedding/_dashscope/_models/text-embedding-v4.yaml
new file mode 100644
index 0000000..11a8fff
--- /dev/null
+++ b/src/agentscope/embedding/_dashscope/_models/text-embedding-v4.yaml
@@ -0,0 +1,14 @@
+name: text-embedding-v4
+label: Text Embedding v4
+status: active
+
+input_types:
+  - text/plain
+
+output_types:
+  - application/x-embedding
+
+context_size: 8192
+
+dimensions: 1024
+supported_dimensions: [2048, 1536, 1024, 768, 512, 256, 128, 64]
diff --git a/src/agentscope/embedding/_dashscope/_models/tongyi-embedding-vision-flash.yaml b/src/agentscope/embedding/_dashscope/_models/tongyi-embedding-vision-flash.yaml
new file mode 100644
index 0000000..ec20655
--- /dev/null
+++ b/src/agentscope/embedding/_dashscope/_models/tongyi-embedding-vision-flash.yaml
@@ -0,0 +1,21 @@
+name: tongyi-embedding-vision-flash
+label: Tongyi Embedding Vision Flash
+status: active
+
+input_types:
+  - text/plain
+  - image/jpeg
+  - image/png
+  - image/webp
+  - image/bmp
+  - image/tiff
+  - video/mp4
+  - video/mpeg
+
+output_types:
+  - application/x-embedding
+
+context_size: 1024
+
+dimensions: 768
+supported_dimensions: [768, 512, 256, 128, 64]
diff --git a/src/agentscope/embedding/_dashscope/_models/tongyi-embedding-vision-plus.yaml b/src/agentscope/embedding/_dashscope/_models/tongyi-embedding-vision-plus.yaml
new file mode 100644
index 0000000..9fe2eca
--- /dev/null
+++ b/src/agentscope/embedding/_dashscope/_models/tongyi-embedding-vision-plus.yaml
@@ -0,0 +1,21 @@
+name: tongyi-embedding-vision-plus
+label: Tongyi Embedding Vision Plus
+status: active
+
+input_types:
+  - text/plain
+  - image/jpeg
+  - image/png
+  - image/webp
+  - image/bmp
+  - image/tiff
+  - video/mp4
+  - video/mpeg
+
+output_types:
+  - application/x-embedding
+
+context_size: 1024
+
+dimensions: 1152
+supported_dimensions: [1152, 1024, 512, 256, 128, 64]
diff --git a/src/agentscope/embedding/_embedding_base.py b/src/agentscope/embedding/_embedding_base.py
new file mode 100644
index 0000000..966d481
--- /dev/null
+++ b/src/agentscope/embedding/_embedding_base.py
@@ -0,0 +1,449 @@
+# -*- coding: utf-8 -*-
+"""The embedding model base class."""
+from __future__ import annotations
+
+import asyncio
+import inspect
+from abc import abstractmethod
+from pathlib import Path
+from typing import Any, Generic, TypeVar, Type, Union
+
+from pydantic import BaseModel, ConfigDict
+
+from ._embedding_model_card import EmbeddingModelCard
+from ._embedding_response import EmbeddingResponse
+from ._embedding_usage import EmbeddingUsage
+from .._logging import logger
+from ..credential import CredentialBase
+from ..message import DataBlock, TextBlock
+
+#: Type variable for embedding input elements.
+#:
+#: Bound to the union of all element shapes the framework supports;
+#: each concrete subclass narrows it to its accepted input via
+#: ``class Foo(EmbeddingModelBase[str | TextBlock]): ...`` so callers
+#: get accurate IDE completion and type-checking on ``__call__``.
+#:
+#: ``__call__`` accepts ``TextBlock`` and unpacks it to ``.text``
+#: before invoking :meth:`_call_api`; therefore ``_call_api``'s input
+#: type is intentionally decoupled from :data:`InputT` (it is typed
+#: ``list[Any]`` on the base and narrowed by each subclass).
+InputT = TypeVar("InputT", bound=Union[str, TextBlock, DataBlock])
+
+
+class EmbeddingModelBase(Generic[InputT]):
+    """Base class for embedding models.
+
+    Generic over :data:`InputT` so that text-only subclasses
+    (``EmbeddingModelBase[str]``) and multimodal subclasses
+    (``EmbeddingModelBase[str | TextBlock | DataBlock]``) expose the
+    correct ``inputs`` type to the IDE.
+
+    Follows the same pattern as :class:`~agentscope.model.ChatModelBase`:
+
+    - ``__call__`` splits inputs into batches of size
+      :attr:`batch_size`, calls :meth:`_call_api` for each batch
+      **concurrently** via :func:`asyncio.gather`, and merges the
+      results.  Each batch call is wrapped with retry logic.
+    - Subclasses only implement :meth:`_call_api` for a **single
+      batch** — no batching or retry code needed.
+    - Each subclass may override :meth:`_get_retryable_exceptions` to
+      declare provider-specific retriable errors.
+    """
+
+    class Parameters(BaseModel):
+        """Provider-specific tunables for embedding models.
+
+        Intentionally empty in the base — ``dimensions`` is a contract
+        property of an embedding model (its output vector size), not a
+        tunable knob, so it lives directly on the instance via the
+        required :paramref:`__init__.dimensions` argument.  Subclasses
+        extend this class to expose **non-dimensional** knobs (e.g.
+        Gemini's ``task_type``, Dashscope's ``text_type``).
+
+        ``extra="allow"`` is set so old persisted configs (where
+        ``dimensions`` lived in ``parameters``) keep deserialising
+        without raising; :meth:`EmbeddingModelBase.__init__` extracts
+        it back out for backward compatibility.
+        """
+
+        model_config = ConfigDict(extra="allow")
+
+    credential: CredentialBase
+    """The API credential."""
+
+    model: str
+    """The embedding model name."""
+
+    dimensions: int
+    """The output embedding vector dimensions.
+
+    Set directly from the :paramref:`__init__.dimensions` argument —
+    a required, first-class field rather than something derived from
+    :attr:`parameters`.
+    """
+
+    context_size: int
+    """Maximum input length (in tokens) per single input item."""
+
+    batch_size: int
+    """Maximum number of input items per API call."""
+
+    max_retries: int
+    """The maximum number of retries for the underlying API."""
+
+    retry_delay: float
+    """Seconds to sleep between retry attempts."""
+
+    supports_multimodal: bool = False
+    """Whether this model instance accepts :class:`DataBlock` inputs in
+    addition to text.  Text-only models keep the default ``False``;
+    multimodal subclasses must set it to ``True`` (per instance when
+    routing depends on the model name)."""
+
+    def __init__(
+        self,
+        credential: CredentialBase,
+        model: str,
+        dimensions: int | None,
+        parameters: BaseModel | None,
+        context_size: int,
+        batch_size: int,
+        max_retries: int,
+        retry_delay: float,
+    ) -> None:
+        """Initialize the embedding model base class.
+
+        Args:
+            credential (`CredentialBase`):
+                The API credential used for authentication.
+            model (`str`):
+                The name of the embedding model.
+            dimensions (`int | None`):
+                The output embedding vector dimensions for this
+                instance.  Required and first-class — see the class
+                docstring for the rationale of keeping ``dimensions``
+                outside :class:`Parameters`.  For backward compatibility
+                with older configs that stored ``dimensions`` inside
+                :class:`Parameters`, ``None`` is accepted at the
+                signature level and is back-filled from
+                ``parameters.dimensions`` when present.
+            parameters (`BaseModel | None`):
+                Provider-specific non-dimensional parameters.  When
+                ``None``, the default ``Parameters()`` is used.
+            context_size (`int`):
+                Maximum input length (in tokens) per single input item.
+            batch_size (`int`):
+                Maximum number of input items per API call.  When
+                ``__call__`` receives more items, it splits them into
+                batches and calls :meth:`_call_api` concurrently.
+            max_retries (`int`):
+                The maximum number of retries for each batch API call.
+                Only exceptions listed in
+                :meth:`_get_retryable_exceptions` count against this
+                budget.
+            retry_delay (`float`):
+                Seconds to sleep between retry attempts.
+        """
+        resolved_parameters = parameters or self.Parameters()
+        # Backward-compat: older session/KB configs persisted
+        # ``dimensions`` inside ``parameters``.  Promote it to the
+        # constructor argument when the caller did not pass one
+        # explicitly, then strip it from the parameters object so it
+        # never reaches provider-specific request payloads.
+        param_dump = resolved_parameters.model_dump()
+        legacy_dimensions = param_dump.pop("dimensions", None)
+        if dimensions is None:
+            if legacy_dimensions is None:
+                raise ValueError(
+                    "dimensions is required: pass it explicitly to "
+                    "EmbeddingModelBase.__init__ or include it in the "
+                    "legacy `parameters` mapping.",
+                )
+            dimensions = int(legacy_dimensions)
+            resolved_parameters = type(resolved_parameters)(**param_dump)
+        elif legacy_dimensions is not None:
+            # Both routes set it — explicit constructor wins, strip the
+            # legacy mirror so it can't drift.
+            resolved_parameters = type(resolved_parameters)(**param_dump)
+
+        if dimensions <= 0:
+            raise ValueError(
+                f"dimensions must be a positive integer, got {dimensions}.",
+            )
+
+        self.credential = credential
+        self.model = model
+        self.dimensions = dimensions
+        self.parameters = resolved_parameters
+        self.context_size = context_size
+        self.batch_size = batch_size
+        self.max_retries = max_retries
+        self.retry_delay = retry_delay
+
+    @classmethod
+    def _get_retryable_exceptions(cls) -> tuple[Type[Exception], ...]:
+        """Return exception types that should trigger a retry.
+
+        Defaults to an empty tuple (no retries).  Subclasses can
+        override to declare provider-specific retryable exceptions.
+        """
+        return ()
+
+    # ------------------------------------------------------------------
+    # Public API — batching + concurrent retry
+    # ------------------------------------------------------------------
+
+    async def __call__(
+        self,
+        inputs: list[InputT],
+        **kwargs: Any,
+    ) -> EmbeddingResponse:
+        """Embed a list of inputs with automatic batching and retry.
+
+        The inputs are split into chunks of :attr:`batch_size`.  All
+        chunks are dispatched **concurrently** via
+        :func:`asyncio.gather`.  Each chunk is individually retried up
+        to ``max_retries`` times on retryable errors.  Results are
+        merged into a single :class:`EmbeddingResponse` preserving the
+        original input order.
+
+        Args:
+            inputs (`list[InputT]`):
+                The input data to embed.  For text-only models this is
+                ``list[str]``; for multimodal models it is
+                ``list[str | TextBlock | DataBlock]``.  Any
+                :class:`TextBlock` items are transparently unpacked to
+                their ``.text`` field on entry, so subclasses' batching
+                and ``_call_api`` only have to handle ``str`` (and
+                ``DataBlock`` for multimodal variants).
+            **kwargs:
+                Additional keyword arguments forwarded to
+                :meth:`_call_api`.
+
+        Returns:
+            `EmbeddingResponse`:
+                A merged response containing embeddings for all inputs.
+        """
+        if not inputs:
+            return EmbeddingResponse(
+                embeddings=[],
+                usage=EmbeddingUsage(tokens=0, time=0),
+            )
+
+        normalized: list[Any] = [
+            item.text if isinstance(item, TextBlock) else item
+            for item in inputs
+        ]
+
+        # Split into batches.
+        batches = [
+            normalized[i : i + self.batch_size]
+            for i in range(0, len(normalized), self.batch_size)
+        ]
+
+        if len(batches) > 1:
+            logger.info(
+                "Embedding %d inputs in %d batches (batch_size=%d) "
+                "for model %s.",
+                len(normalized),
+                len(batches),
+                self.batch_size,
+                self.model,
+            )
+
+        # Dispatch all batches concurrently, each with retry.
+        results: list[EmbeddingResponse] = await asyncio.gather(
+            *(self._call_with_retry(batch, **kwargs) for batch in batches),
+        )
+
+        return self._merge_responses(results)
+
+    # ------------------------------------------------------------------
+    # Internal — merge multiple batch responses
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _merge_responses(
+        responses: list[EmbeddingResponse],
+    ) -> EmbeddingResponse:
+        """Merge multiple batch :class:`EmbeddingResponse` objects into
+        one, preserving input order.
+
+        Args:
+            responses (`list[EmbeddingResponse]`):
+                Batch responses to merge.
+
+        Returns:
+            `EmbeddingResponse`: The merged response.
+        """
+        if len(responses) == 1:
+            return responses[0]
+
+        all_embeddings: list = []
+        total_tokens = 0
+        total_time = 0.0
+
+        for resp in responses:
+            all_embeddings.extend(resp.embeddings)
+            if resp.usage:
+                total_time += resp.usage.time
+                if resp.usage.tokens:
+                    total_tokens += resp.usage.tokens
+
+        return EmbeddingResponse(
+            embeddings=all_embeddings,
+            usage=EmbeddingUsage(
+                tokens=total_tokens,
+                time=total_time,
+            ),
+            source="api",
+        )
+
+    # ------------------------------------------------------------------
+    # Internal — retry wrapper for a single batch
+    # ------------------------------------------------------------------
+
+    async def _call_with_retry(
+        self,
+        inputs: list[Any],
+        **kwargs: Any,
+    ) -> EmbeddingResponse:
+        """Call :meth:`_call_api` with retry logic for a single batch.
+
+        Args:
+            inputs (`list[Any]`):
+                A single batch of inputs (size ≤ ``batch_size``), already
+                normalised by :meth:`__call__` (any :class:`TextBlock`
+                items unpacked to their ``.text``). Typed as
+                ``list[Any]`` because the concrete element shape depends
+                on the subclass — see :meth:`_call_api`.
+            **kwargs:
+                Forwarded to :meth:`_call_api`.
+        """
+        retryable = tuple(self._get_retryable_exceptions())
+        last_error: Exception | None = None
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                return await self._call_api(inputs, **kwargs)
+            except Exception as e:
+                if not isinstance(e, retryable):
+                    raise
+                last_error = e
+                if attempt < self.max_retries:
+                    logger.warning(
+                        "Batch attempt %d failed for embedding model "
+                        "%s: %s. Retrying in %.1fs...",
+                        attempt + 1,
+                        self.model,
+                        str(e),
+                        self.retry_delay,
+                    )
+                    await asyncio.sleep(self.retry_delay)
+                else:
+                    logger.warning(
+                        "All %d attempt(s) failed for a batch of "
+                        "embedding model %s.",
+                        self.max_retries + 1,
+                        self.model,
+                    )
+
+        if last_error is not None:
+            raise last_error
+        raise RuntimeError(
+            f"Failed to call embedding model {self.model} after "
+            f"{self.max_retries + 1} retries.",
+        )
+
+    # ------------------------------------------------------------------
+    # Abstract — subclasses implement this for a single batch
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    async def _call_api(
+        self,
+        inputs: list[Any],
+        **kwargs: Any,
+    ) -> EmbeddingResponse:
+        """Call the underlying embedding API for a **single batch**.
+
+        Subclasses must implement this method.  The batch splitting,
+        concurrency, and retry logic are handled by :meth:`__call__`
+        — this method only needs to handle one API call.
+
+        .. note::
+            The parameter is typed ``list[Any]`` rather than
+            ``list[InputT]`` because :meth:`__call__` unpacks
+            :class:`TextBlock` items to their ``.text`` field *before*
+            dispatching to this method.  The element shape this method
+            actually receives is therefore subclass-specific
+            (:data:`InputT` minus :class:`TextBlock`).  Subclasses
+            should override with their concrete narrower type, e.g.
+            ``list[str]`` for text-only models or
+            ``list[str | DataBlock]`` for multimodal ones.
+
+        Args:
+            inputs (`list[Any]`):
+                A batch of inputs (guaranteed ``len(inputs) <=
+                self.batch_size``).
+            **kwargs:
+                Additional keyword arguments.
+
+        Returns:
+            `EmbeddingResponse`:
+                The embedding response for this batch.
+        """
+
+    # ------------------------------------------------------------------
+    # Model card discovery
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def list_models(
+        cls,
+        custom_yaml_dir: str | None = None,
+    ) -> list[EmbeddingModelCard]:
+        """List candidate embedding models from YAML files.
+
+        Each concrete subclass should live in its own provider
+        subdirectory (e.g. ``embedding/_openai/_model.py``) with a
+        sibling ``_models/`` directory containing YAML files — identical
+        to the layout used by :class:`~agentscope.model.ChatModelBase`.
+
+        Args:
+            custom_yaml_dir (`str | None`):
+                Override the YAML directory.
+
+        Returns:
+            `list[EmbeddingModelCard]`:
+                A list of embedding model cards.
+        """
+        if custom_yaml_dir is None:
+            subclass_file = Path(inspect.getfile(cls))
+            yaml_dir = subclass_file.parent / "_models"
+        else:
+            yaml_dir = Path(custom_yaml_dir)
+
+        if not yaml_dir.is_dir():
+            return []
+
+        yaml_files = list(yaml_dir.glob("*.yaml"))
+
+        model_cards = []
+        for yaml_file in yaml_files:
+            try:
+                card = EmbeddingModelCard.from_yaml(
+                    yaml_path=str(yaml_file),
+                    parameter_class=cls.Parameters,
+                )
+                model_cards.append(card)
+            except Exception as e:
+                logger.warning(
+                    "Failed to load embedding model card %s: %s",
+                    yaml_file,
+                    str(e),
+                )
+                continue
+
+        return model_cards
diff --git a/src/agentscope/embedding/_embedding_model_card.py b/src/agentscope/embedding/_embedding_model_card.py
new file mode 100644
index 0000000..04de52d
--- /dev/null
+++ b/src/agentscope/embedding/_embedding_model_card.py
@@ -0,0 +1,179 @@
+# -*- coding: utf-8 -*-
+"""The embedding model card class."""
+from __future__ import annotations
+
+import copy
+from typing import Literal, Self, Type
+
+import yaml
+from pydantic import BaseModel, Field
+
+
+class EmbeddingModelCard(BaseModel):
+    """A card describing an embedding model's capabilities.
+
+    Mirrors :class:`~agentscope.model.ModelCard` but tailored for
+    embedding models.  Uses ``input_types`` / ``output_types`` to
+    describe model capabilities, and ``parameter_schema`` (built from
+    the embedding class's ``Parameters`` + YAML ``parameter_overrides``)
+    to tell the frontend which knobs the user can adjust.
+
+    The output type ``application/x-embedding`` indicates that the
+    model produces dense vector embeddings.
+    """
+
+    type: Literal["embedding_model"] = "embedding_model"
+    """The card type, always ``"embedding_model"``."""
+
+    name: str = Field(description="The model name used in API calls.")
+    """The model name (e.g. ``"text-embedding-3-small"``)."""
+
+    label: str = Field(description="Human-readable label for the frontend.")
+    """Display label (e.g. ``"Text Embedding 3 Small"``)."""
+
+    status: Literal["active", "deprecated", "sunset"] = Field(
+        default="active",
+        description="The model lifecycle status.",
+    )
+    """The model status."""
+
+    input_types: list[str] = Field(
+        default=["text/plain"],
+        description="Supported input media types.",
+    )
+    """Supported input types (e.g. ``["text/plain"]``,
+    ``["text/plain", "image/jpeg", "image/png"]``)."""
+
+    output_types: list[str] = Field(
+        default=["application/x-embedding"],
+        description="Supported output media types.",
+    )
+    """Output types. ``application/x-embedding`` for vector output."""
+
+    dimensions: int = Field(
+        ...,
+        description="Default output vector dimensions for this model.",
+        gt=0,
+    )
+    """The default output dimensions for this model.
+
+    First-class top-level field — kept outside of
+    :attr:`parameter_schema` so that callers can rely on a strongly
+    typed ``int`` rather than the soft ``parameter_schema['properties']
+    ['dimensions']['default']`` lookup.
+    """
+
+    supported_dimensions: list[int] | None = Field(
+        default=None,
+        description=(
+            "If set, the only dimensions this model can produce. "
+            "``None`` means dimensions are fixed at "
+            ":attr:`dimensions` and cannot be overridden."
+        ),
+    )
+    """Optional set of allowed output dimensions.
+
+    Set for Matryoshka-style models (e.g. OpenAI's
+    ``text-embedding-3-*``) that can be truncated to a smaller size.
+    ``None`` indicates a fixed-dimension model.
+    """
+
+    context_size: int | None = Field(
+        default=None,
+        description="Maximum input length (in tokens) per request.",
+        gt=0,
+    )
+    """Maximum input context size, if known."""
+
+    parameter_schema: dict = Field(
+        default_factory=dict,
+        description=(
+            "JSON Schema for user-configurable parameters "
+            "(built from the Parameters class + YAML overrides)."
+        ),
+    )
+    """The parameter schema sent to the frontend for form rendering.
+    Empty ``properties`` means nothing to configure (e.g. fixed
+    dimensions)."""
+
+    parameter_overrides: dict[str, dict] = Field(
+        default_factory=dict,
+        description="Raw parameter overrides from the YAML file.",
+    )
+    """The raw parameter overrides, preserved for reference."""
+
+    @classmethod
+    def from_yaml(
+        cls,
+        yaml_path: str,
+        parameter_class: Type[BaseModel],
+    ) -> Self:
+        """Load an embedding model card from a YAML file.
+
+        Merges the base ``parameter_class`` JSON Schema with
+        ``parameter_overrides`` from the YAML — identical to the
+        approach used by :meth:`~agentscope.model.ModelCard.from_yaml`.
+
+        Args:
+            yaml_path (`str`):
+                Path to the YAML file.
+            parameter_class (`Type[BaseModel]`):
+                The ``Parameters`` class from the embedding model subclass.
+
+        Returns:
+            `EmbeddingModelCard`: The loaded model card.
+        """
+        with open(yaml_path, "r", encoding="utf-8") as f:
+            config = yaml.safe_load(f)
+
+        if "dimensions" not in config:
+            raise ValueError(
+                f"Embedding model card {yaml_path!r} is missing the "
+                f"required top-level 'dimensions' field.",
+            )
+
+        # Build parameter schema from the Parameters class
+        base_schema = parameter_class.model_json_schema()
+        properties = copy.deepcopy(base_schema.get("properties", {}))
+
+        # Apply parameter_overrides (same logic as ModelCard.from_yaml)
+        overrides = config.get("parameter_overrides", {})
+        for param_name, override in overrides.items():
+            if override is None:
+                # null means remove
+                properties.pop(param_name, None)
+                continue
+
+            if isinstance(override, dict):
+                if override.get("hidden"):
+                    properties.pop(param_name, None)
+                    continue
+
+                # Simple dict merge
+                if param_name in properties:
+                    properties[param_name] = {
+                        **properties[param_name],
+                        **override,
+                    }
+
+        final_schema = {
+            "type": "object",
+            "properties": properties,
+            "required": base_schema.get("required", []),
+        }
+
+        return cls(
+            name=config["name"],
+            label=config["label"],
+            status=config.get("status", "active"),
+            input_types=config.get("input_types", ["text/plain"]),
+            output_types=config.get(
+                "output_types",
+                ["application/x-embedding"],
+            ),
+            dimensions=config["dimensions"],
+            supported_dimensions=config.get("supported_dimensions"),
+            context_size=config.get("context_size"),
+            parameter_schema=final_schema,
+            parameter_overrides=overrides,
+        )
diff --git a/src/agentscope/embedding/_embedding_response.py b/src/agentscope/embedding/_embedding_response.py
new file mode 100644
index 0000000..1a026bf
--- /dev/null
+++ b/src/agentscope/embedding/_embedding_response.py
@@ -0,0 +1,32 @@
+# -*- coding: utf-8 -*-
+"""The embedding response class."""
+from dataclasses import dataclass, field
+from typing import Literal, List
+
+from ._embedding_usage import EmbeddingUsage
+from .._utils._common import _get_timestamp
+from .._utils._mixin import DictMixin
+from ..types import Embedding
+
+
+@dataclass
+class EmbeddingResponse(DictMixin):
+    """The embedding response class."""
+
+    embeddings: List[Embedding]
+    """The embedding data"""
+
+    id: str = field(default_factory=lambda: _get_timestamp(True))
+    """The identity of the embedding response"""
+
+    created_at: str = field(default_factory=_get_timestamp)
+    """The timestamp of the embedding response creation"""
+
+    type: Literal["embedding"] = field(default_factory=lambda: "embedding")
+    """The type of the response, must be `embedding`."""
+
+    usage: EmbeddingUsage | None = field(default_factory=lambda: None)
+    """The usage of the embedding model API invocation, if available."""
+
+    source: Literal["cache", "api"] = field(default_factory=lambda: "api")
+    """If the response comes from the cache or the API."""
diff --git a/src/agentscope/embedding/_embedding_usage.py b/src/agentscope/embedding/_embedding_usage.py
new file mode 100644
index 0000000..3f3cb67
--- /dev/null
+++ b/src/agentscope/embedding/_embedding_usage.py
@@ -0,0 +1,20 @@
+# -*- coding: utf-8 -*-
+"""The embedding usage class in agentscope."""
+from dataclasses import dataclass, field
+from typing import Literal
+
+from .._utils._mixin import DictMixin
+
+
+@dataclass
+class EmbeddingUsage(DictMixin):
+    """The usage of an embedding model API invocation."""
+
+    time: float
+    """The time used in seconds."""
+
+    tokens: int | None = field(default_factory=lambda: None)
+    """The number of tokens used, if available."""
+
+    type: Literal["embedding"] = field(default_factory=lambda: "embedding")
+    """The type of the usage, must be `embedding`."""
diff --git a/src/agentscope/embedding/_file_cache.py b/src/agentscope/embedding/_file_cache.py
new file mode 100644
index 0000000..11b6f8d
--- /dev/null
+++ b/src/agentscope/embedding/_file_cache.py
@@ -0,0 +1,187 @@
+# -*- coding: utf-8 -*-
+"""A file embedding cache implementation for storing and retrieving
+embeddings in binary files."""
+import hashlib
+import json
+import os
+from typing import Any, List
+
+import numpy as np
+
+from ._cache_base import EmbeddingCacheBase
+from .._logging import logger
+from ..types import (
+    Embedding,
+    JSONSerializableObject,
+)
+
+
+class FileEmbeddingCache(EmbeddingCacheBase):
+    """The embedding cache class that stores each embeddings vector in
+    binary files."""
+
+    def __init__(
+        self,
+        cache_dir: str = "./.cache/embeddings",
+        max_file_number: int | None = None,
+        max_cache_size: int | None = None,
+    ) -> None:
+        """Initialize the file embedding cache class.
+
+        Args:
+            cache_dir (`str`, defaults to `"./.cache/embeddings"`):
+                The directory to store the embedding files.
+            max_file_number (`int | None`, defaults to `None`):
+                The maximum number of files to keep in the cache directory. If
+                exceeded, the oldest files will be removed.
+            max_cache_size (`int | None`, defaults to `None`):
+                The maximum size of the cache directory in MB. If exceeded,
+                the oldest files will be removed until the size is within the
+                limit.
+        """
+        self._cache_dir = os.path.abspath(cache_dir)
+        self.max_file_number = max_file_number
+        self.max_cache_size = max_cache_size
+
+    @property
+    def cache_dir(self) -> str:
+        """The cache directory where the embedding files are stored."""
+        if not os.path.exists(self._cache_dir):
+            os.makedirs(self._cache_dir, exist_ok=True)
+        return self._cache_dir
+
+    async def store(
+        self,
+        embeddings: List[Embedding],
+        identifier: JSONSerializableObject,
+        overwrite: bool = False,
+        **kwargs: Any,
+    ) -> None:
+        """Store the embeddings with the given identifier.
+
+        Args:
+            embeddings (`List[Embedding]`):
+                The embeddings to store.
+            identifier (`JSONSerializableObject`):
+                The identifier to distinguish the embeddings, which will be
+                used to generate a hashable filename, so it should be
+                JSON serializable (e.g. a string, number, list, dict).
+            overwrite (`bool`, defaults to `False`):
+                Whether to overwrite existing embeddings with the same
+                identifier. If `True`, existing embeddings will be replaced.
+        """
+        filename = self._get_filename(identifier)
+        path_file = os.path.join(self.cache_dir, filename)
+
+        if os.path.exists(path_file):
+            if not os.path.isfile(path_file):
+                raise RuntimeError(
+                    f"Path {path_file} exists but is not a file.",
+                )
+
+            if overwrite:
+                np.save(path_file, embeddings)
+                await self._maintain_cache_dir()
+        else:
+            np.save(path_file, embeddings)
+            await self._maintain_cache_dir()
+
+    async def retrieve(
+        self,
+        identifier: JSONSerializableObject,
+    ) -> List[Embedding] | None:
+        """Retrieve the embeddings with the given identifier. If not found,
+        return `None`.
+
+        Args:
+            identifier (`JSONSerializableObject`):
+                The identifier to retrieve the embeddings, which will be
+                used to generate a hashable filename, so it should be
+                JSON serializable (e.g. a string, number, list, dict).
+        """
+        filename = self._get_filename(identifier)
+        path_file = os.path.join(self.cache_dir, filename)
+
+        if os.path.exists(path_file):
+            return np.load(os.path.join(self.cache_dir, filename)).tolist()
+        return None
+
+    async def remove(self, identifier: JSONSerializableObject) -> None:
+        """Remove the embeddings with the given identifier.
+
+        Args:
+            identifier (`JSONSerializableObject`):
+                The identifiers to remove the embeddings, which will be
+                used to generate a hashable filename, so it should be
+                JSON serializable (e.g. a string, number, list, dict).
+        """
+        filename = self._get_filename(identifier)
+        path_file = os.path.join(self.cache_dir, filename)
+
+        if os.path.exists(path_file):
+            os.remove(path_file)
+        else:
+            raise FileNotFoundError(f"File {path_file} does not exist.")
+
+    async def clear(self) -> None:
+        """Clear the cache directory by removing all files."""
+        for filename in os.listdir(self.cache_dir):
+            if filename.endswith(".npy"):
+                os.remove(os.path.join(self.cache_dir, filename))
+
+    def _get_cache_size(self) -> float:
+        """Get the current size of the cache directory in MB."""
+        total_size = 0
+        for filename in os.listdir(self.cache_dir):
+            if filename.endswith(".npy"):
+                path_file = os.path.join(self.cache_dir, filename)
+                if os.path.isfile(path_file):
+                    total_size += os.path.getsize(path_file)
+        return total_size / (1024.0 * 1024.0)
+
+    @staticmethod
+    def _get_filename(identifier: JSONSerializableObject) -> str:
+        """Generate a filename based on the identifier."""
+        json_str = json.dumps(identifier, ensure_ascii=False)
+        return hashlib.sha256(json_str.encode("utf-8")).hexdigest() + ".npy"
+
+    async def _maintain_cache_dir(self) -> None:
+        """Maintain the cache directory by removing old files if the number of
+        files exceeds the maximum limit or if the cache size exceeds the
+        maximum size."""
+        files = [
+            (_.name, _.stat().st_mtime)
+            for _ in os.scandir(self.cache_dir)
+            if _.is_file() and _.name.endswith(".npy")
+        ]
+        files.sort(key=lambda x: x[1])
+
+        if self.max_file_number and len(files) > self.max_file_number:
+            for file_name, _ in files[: 0 - self.max_file_number]:
+                os.remove(os.path.join(self.cache_dir, file_name))
+                logger.info(
+                    "Remove cached embedding file %s for limited number "
+                    "of files (%d).",
+                    file_name,
+                    self.max_file_number,
+                )
+            files = files[0 - self.max_file_number :]
+
+        if (
+            self.max_cache_size is not None
+            and self._get_cache_size() > self.max_cache_size
+        ):
+            removed_files = []
+            for filename, _ in files:
+                os.remove(os.path.join(self.cache_dir, filename))
+                removed_files.append(filename)
+                if self._get_cache_size() <= self.max_cache_size:
+                    break
+
+            if removed_files:
+                logger.info(
+                    "Remove %d cached embedding file(s) for limited "
+                    "cache size (%d MB).",
+                    len(removed_files),
+                    self.max_cache_size,
+                )
diff --git a/src/agentscope/embedding/_gemini/__init__.py b/src/agentscope/embedding/_gemini/__init__.py
new file mode 100644
index 0000000..e0cf50b
--- /dev/null
+++ b/src/agentscope/embedding/_gemini/__init__.py
@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+"""The Gemini embedding API modules."""
+
+from ._model import GeminiEmbeddingModel
+
+__all__ = [
+    "GeminiEmbeddingModel",
+]
diff --git a/src/agentscope/embedding/_gemini/_model.py b/src/agentscope/embedding/_gemini/_model.py
new file mode 100644
index 0000000..89cb8a4
--- /dev/null
+++ b/src/agentscope/embedding/_gemini/_model.py
@@ -0,0 +1,485 @@
+# -*- coding: utf-8 -*-
+"""The Google Gemini embedding model.
+
+Handles both text-only and multimodal models under a single class.
+``gemini-embedding-001`` accepts ``list[str | TextBlock]``.
+``gemini-embedding-2`` additionally accepts
+:class:`~agentscope.message.DataBlock` (images, video, audio, PDF).
+The model name determines the API call style.
+
+Text payloads may be passed either as bare ``str`` or as
+:class:`~agentscope.message.TextBlock` — the latter is unpacked to its
+``.text`` field on entry so the rest of the pipeline only deals with
+``str`` and ``DataBlock``.
+"""
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any
+
+from .._cache_base import EmbeddingCacheBase
+from .._embedding_response import EmbeddingResponse
+from .._embedding_usage import EmbeddingUsage
+from .._embedding_base import EmbeddingModelBase
+from ..._logging import logger
+from ...credential import CredentialBase
+from ...message import DataBlock, TextBlock
+
+#: Model name prefixes that use the multimodal API path.
+_MULTIMODAL_PREFIXES = ("gemini-embedding-2",)
+
+
+@dataclass
+class _MultimodalLimits:
+    """Per-request constraints for Gemini multimodal embedding."""
+
+    max_elements: int = 20
+    """Maximum total content elements per API call."""
+
+    max_images: int = 6
+    """Maximum image elements per API call."""
+
+    max_videos: int = 1
+    """Maximum video elements per API call."""
+
+    max_audios: int = 1
+    """Maximum audio elements per API call."""
+
+    max_pdfs: int = 1
+    """Maximum PDF documents per API call."""
+
+
+_MODEL_LIMITS: dict[str, _MultimodalLimits] = {
+    "gemini-embedding-2": _MultimodalLimits(
+        max_elements=20,
+        max_images=6,
+        max_videos=1,
+        max_audios=1,
+        max_pdfs=1,
+    ),
+}
+
+_DEFAULT_LIMITS = _MultimodalLimits()
+
+
+class GeminiEmbeddingModel(EmbeddingModelBase[str | TextBlock | DataBlock]):
+    """Unified Google Gemini embedding model.
+
+    Routes to the text-only or multimodal Gemini API based on the
+    model name.
+
+    - **Text mode** (``gemini-embedding-001``): uses the base class's
+      simple batch splitting + concurrent retry.  The Gemini API
+      accepts a list of strings and returns individual embeddings.
+    - **Multimodal mode** (``gemini-embedding-2``): overrides
+      ``__call__`` with content-aware batching (respecting per-model
+      limits on images, videos, audios, PDFs).  Each input is wrapped
+      in a ``Content`` object so the API returns separate embeddings.
+
+    Key API differences from other providers:
+
+    - Dimensions are controlled via ``output_dimensionality`` in the
+      ``config`` parameter (not a top-level ``dimensions`` field).
+    - ``gemini-embedding-001`` supports ``task_type`` in config;
+      ``gemini-embedding-2`` uses prompt prefixes instead.
+    """
+
+    #: Text-mode batch size.  Gemini docs don't specify an explicit
+    #: limit; we use a conservative default.
+    _TEXT_BATCH_SIZE: int = 100
+
+    def __init__(
+        self,
+        credential: CredentialBase,
+        model: str,
+        dimensions: int | None,
+        parameters: "GeminiEmbeddingModel.Parameters | None" = None,
+        embedding_cache: EmbeddingCacheBase | None = None,
+        context_size: int = 8192,
+        max_retries: int = 3,
+        retry_delay: float = 1.0,
+    ) -> None:
+        """Initialize the Gemini embedding model.
+
+        Args:
+            credential (`CredentialBase`):
+                A :class:`~agentscope.credential.GeminiCredential`
+                instance providing the API key.
+            model (`str`):
+                The embedding model name (e.g.
+                ``"gemini-embedding-001"`` or
+                ``"gemini-embedding-2"``).
+            dimensions (`int | None`):
+                The output embedding vector dimensions.  Required at
+                the contract level — see :class:`EmbeddingModelBase`
+                for the rationale.  ``None`` is accepted only for
+                backward compatibility with legacy configs that
+                persisted ``dimensions`` inside ``parameters``.
+            parameters (`GeminiEmbeddingModel.Parameters | None`, \
+            defaults to ``None``):
+                Provider-specific non-dimensional parameters.  Currently
+                empty for Gemini.
+            embedding_cache (`EmbeddingCacheBase | None`, defaults to \
+            ``None``):
+                Optional embedding cache.
+            context_size (`int`, defaults to ``8192``):
+                Maximum input tokens.  2048 for ``gemini-embedding-001``,
+                8192 for ``gemini-embedding-2``.
+            max_retries (`int`, defaults to ``3``):
+                Number of retries on transient failures.
+            retry_delay (`float`, defaults to ``1.0``):
+                Seconds between retry attempts.
+        """
+        from google import genai
+
+        self._is_multimodal: bool = model.startswith(_MULTIMODAL_PREFIXES)
+
+        super().__init__(
+            credential=credential,
+            model=model,
+            dimensions=dimensions,
+            parameters=parameters,
+            context_size=context_size,
+            batch_size=self._TEXT_BATCH_SIZE,
+            max_retries=max_retries,
+            retry_delay=retry_delay,
+        )
+        self.supports_multimodal = self._is_multimodal
+
+        self.client: genai.Client = genai.Client(
+            api_key=credential.api_key.get_secret_value(),
+        )
+        self.embedding_cache: EmbeddingCacheBase | None = embedding_cache
+
+        if self._is_multimodal:
+            self._limits = _MODEL_LIMITS.get(model, _DEFAULT_LIMITS)
+
+    # ------------------------------------------------------------------
+    # __call__ — override for multimodal content-aware batching
+    # ------------------------------------------------------------------
+
+    async def __call__(
+        self,
+        inputs: list[str | TextBlock | DataBlock],
+        **kwargs: Any,
+    ) -> EmbeddingResponse:
+        """Embed inputs with batching and retry.
+
+        For text models, delegates to the base class.  For multimodal
+        models, performs content-aware batching that respects per-model
+        limits on images, videos, audios, and PDFs.
+
+        Args:
+            inputs (`list[str | TextBlock | DataBlock]`):
+                The input data to embed.  ``TextBlock`` items are
+                unpacked to their ``.text`` field on entry, so the
+                remainder of the pipeline only sees ``str`` and
+                ``DataBlock``.
+            **kwargs:
+                Forwarded to the Gemini API config.
+
+        Returns:
+            `EmbeddingResponse`: Merged response for all inputs.
+        """
+        normalized: list[str | DataBlock] = [
+            item.text if isinstance(item, TextBlock) else item
+            for item in inputs
+        ]
+
+        if not self._is_multimodal:
+            return await super().__call__(normalized, **kwargs)
+
+        batches = self._split_multimodal_batches(normalized)
+
+        if len(batches) > 1:
+            logger.info(
+                "Embedding %d multimodal inputs in %d batches "
+                "for model %s.",
+                len(normalized),
+                len(batches),
+                self.model,
+            )
+
+        results: list[EmbeddingResponse] = await asyncio.gather(
+            *(self._call_with_retry(batch, **kwargs) for batch in batches),
+        )
+
+        return self._merge_responses(results)
+
+    def _split_multimodal_batches(
+        self,
+        inputs: list[str | DataBlock],
+    ) -> list[list[str | DataBlock]]:
+        """Split inputs into batches respecting Gemini multimodal limits.
+
+        Greedy: keep adding items until any constraint would be
+        violated, then start a new batch.
+
+        Args:
+            inputs (`list[str | DataBlock]`):
+                All inputs to split.
+
+        Returns:
+            `list[list[str | DataBlock]]`: List of batches.
+        """
+        limits = self._limits
+        batches: list[list[str | DataBlock]] = []
+        current: list[str | DataBlock] = []
+        n_elem = 0
+        n_img = 0
+        n_vid = 0
+        n_aud = 0
+        n_pdf = 0
+
+        for item in inputs:
+            is_img = is_vid = is_aud = is_pdf = False
+            if isinstance(item, DataBlock):
+                mt = item.source.media_type
+                is_img = mt.startswith("image/")
+                is_vid = mt.startswith("video/")
+                is_aud = mt.startswith("audio/")
+                is_pdf = mt == "application/pdf"
+
+            would_exceed = (
+                n_elem + 1 > limits.max_elements
+                or (is_img and n_img + 1 > limits.max_images)
+                or (is_vid and n_vid + 1 > limits.max_videos)
+                or (is_aud and n_aud + 1 > limits.max_audios)
+                or (is_pdf and n_pdf + 1 > limits.max_pdfs)
+            )
+
+            if would_exceed and current:
+                batches.append(current)
+                current = []
+                n_elem = n_img = n_vid = n_aud = n_pdf = 0
+
+            current.append(item)
+            n_elem += 1
+            n_img += is_img
+            n_vid += is_vid
+            n_aud += is_aud
+            n_pdf += is_pdf
+
+        if current:
+            batches.append(current)
+
+        return batches
+
+    # ------------------------------------------------------------------
+    # _call_api — single batch
+    # ------------------------------------------------------------------
+
+    async def _call_api(
+        self,
+        inputs: list[str | DataBlock],
+        **kwargs: Any,
+    ) -> EmbeddingResponse:
+        """Route to text or multimodal Gemini API for a single batch.
+
+        Args:
+            inputs (`list[str | DataBlock]`):
+                A single batch of inputs.
+            **kwargs:
+                Extra keyword arguments merged into the Gemini
+                ``EmbedContentConfig``.
+
+        Returns:
+            `EmbeddingResponse`: Embedding vectors and usage info.
+        """
+        if self._is_multimodal:
+            return await self._call_multimodal(inputs, **kwargs)
+        return await self._call_text(inputs, **kwargs)
+
+    # ------------------------------------------------------------------
+    # Text API (gemini-embedding-001)
+    # ------------------------------------------------------------------
+
+    async def _call_text(
+        self,
+        inputs: list[str | DataBlock],
+        **kwargs: Any,
+    ) -> EmbeddingResponse:
+        """Call the Gemini text embedding API for a single batch.
+
+        Passes the list of strings directly to ``embed_content``,
+        which returns one embedding per string.
+
+        Args:
+            inputs (`list[str | DataBlock]`):
+                Must all be ``str``; raises ``ValueError`` otherwise.
+            **kwargs:
+                Merged into ``EmbedContentConfig`` (e.g.
+                ``task_type``).
+
+        Returns:
+            `EmbeddingResponse`: Embedding vectors and usage info.
+        """
+        from google.genai import types
+
+        texts: list[str] = []
+        for item in inputs:
+            if not isinstance(item, str):
+                raise ValueError(
+                    f"Text embedding model {self.model!r} only accepts "
+                    f"str inputs, got {type(item).__name__}.",
+                )
+            texts.append(item)
+
+        config = types.EmbedContentConfig(
+            output_dimensionality=self.dimensions,
+            **kwargs,
+        )
+
+        cache_key = {
+            "model": self.model,
+            "contents": texts,
+            "output_dimensionality": self.dimensions,
+            **kwargs,
+        }
+
+        if self.embedding_cache:
+            cached = await self.embedding_cache.retrieve(
+                identifier=cache_key,
+            )
+            if cached:
+                return EmbeddingResponse(
+                    embeddings=cached,
+                    usage=EmbeddingUsage(tokens=0, time=0),
+                    source="cache",
+                )
+
+        start_time = datetime.now()
+        response = self.client.models.embed_content(
+            model=self.model,
+            contents=texts,
+            config=config,
+        )
+        time = (datetime.now() - start_time).total_seconds()
+
+        embeddings = [item.values for item in response.embeddings]
+
+        if self.embedding_cache:
+            await self.embedding_cache.store(
+                identifier=cache_key,
+                embeddings=embeddings,
+            )
+
+        return EmbeddingResponse(
+            embeddings=embeddings,
+            usage=EmbeddingUsage(time=time),
+        )
+
+    # ------------------------------------------------------------------
+    # Multimodal API (gemini-embedding-2)
+    # ------------------------------------------------------------------
+
+    async def _call_multimodal(
+        self,
+        inputs: list[str | DataBlock],
+        **kwargs: Any,
+    ) -> EmbeddingResponse:
+        """Call the Gemini multimodal embedding API for a single batch.
+
+        Each input is wrapped in a separate ``Content`` object so the
+        API returns one embedding per input (not one aggregated
+        embedding).
+
+        Args:
+            inputs (`list[str | DataBlock]`):
+                ``str`` for text, ``DataBlock`` for images / video /
+                audio / PDF.
+            **kwargs:
+                Merged into ``EmbedContentConfig``.
+
+        Returns:
+            `EmbeddingResponse`: Embedding vectors and usage info.
+        """
+        from google.genai import types
+
+        contents: list[types.Content] = []
+        for item in inputs:
+            if isinstance(item, str):
+                contents.append(
+                    types.Content(
+                        parts=[types.Part.from_text(text=item)],
+                    ),
+                )
+            elif isinstance(item, DataBlock):
+                contents.append(
+                    types.Content(
+                        parts=[self._data_block_to_part(item)],
+                    ),
+                )
+            else:
+                raise ValueError(
+                    f"Invalid input: {item!r}. Expected str or DataBlock.",
+                )
+
+        config = types.EmbedContentConfig(
+            output_dimensionality=self.dimensions,
+            **kwargs,
+        )
+
+        start_time = datetime.now()
+        response = self.client.models.embed_content(
+            model=self.model,
+            contents=contents,
+            config=config,
+        )
+        time = (datetime.now() - start_time).total_seconds()
+
+        embeddings = [item.values for item in response.embeddings]
+
+        return EmbeddingResponse(
+            embeddings=embeddings,
+            usage=EmbeddingUsage(time=time),
+        )
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _data_block_to_part(block: DataBlock) -> Any:
+        """Convert a :class:`~agentscope.message.DataBlock` to a Gemini
+        ``Part`` object.
+
+        Args:
+            block (`DataBlock`):
+                A data block with ``Base64Source`` or ``URLSource``.
+
+        Returns:
+            A ``google.genai.types.Part`` instance.
+
+        Raises:
+            `ValueError`: If the source type is unsupported.
+        """
+        from google.genai import types
+        from ...message import Base64Source, URLSource
+
+        source = block.source
+
+        if isinstance(source, Base64Source):
+            import base64
+
+            return types.Part.from_bytes(
+                data=base64.b64decode(source.data),
+                mime_type=source.media_type,
+            )
+
+        if isinstance(source, URLSource):
+            # Gemini SDK doesn't have a direct from_url for
+            # embed_content; download or use File API.
+            # For now, raise — callers should use Base64Source.
+            raise ValueError(
+                "Gemini embedding API requires inline data "
+                "(Base64Source). URLSource is not directly supported "
+                f"for embedding. Got URL: {source.url}",
+            )
+
+        raise ValueError(
+            f"Unsupported source type {type(source).__name__} "
+            f"in DataBlock.",
+        )
diff --git a/src/agentscope/embedding/_gemini/_models/gemini-embedding-001.yaml b/src/agentscope/embedding/_gemini/_models/gemini-embedding-001.yaml
new file mode 100644
index 0000000..402ca46
--- /dev/null
+++ b/src/agentscope/embedding/_gemini/_models/gemini-embedding-001.yaml
@@ -0,0 +1,14 @@
+name: gemini-embedding-001
+label: Gemini Embedding 001
+status: active
+
+input_types:
+  - text/plain
+
+output_types:
+  - application/x-embedding
+
+context_size: 2048
+
+dimensions: 3072
+supported_dimensions: [3072, 1536, 768, 512, 256, 128]
diff --git a/src/agentscope/embedding/_gemini/_models/gemini-embedding-2.yaml b/src/agentscope/embedding/_gemini/_models/gemini-embedding-2.yaml
new file mode 100644
index 0000000..17aa3cc
--- /dev/null
+++ b/src/agentscope/embedding/_gemini/_models/gemini-embedding-2.yaml
@@ -0,0 +1,20 @@
+name: gemini-embedding-2
+label: Gemini Embedding 2
+status: active
+
+input_types:
+  - text/plain
+  - image/png
+  - image/jpeg
+  - video/mp4
+  - audio/mpeg
+  - audio/wav
+  - application/pdf
+
+output_types:
+  - application/x-embedding
+
+context_size: 8192
+
+dimensions: 3072
+supported_dimensions: [3072, 1536, 768]
diff --git a/src/agentscope/embedding/_ollama/__init__.py b/src/agentscope/embedding/_ollama/__init__.py
new file mode 100644
index 0000000..efd4c8d
--- /dev/null
+++ b/src/agentscope/embedding/_ollama/__init__.py
@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+"""The Ollama embedding API modules."""
+
+from ._model import OllamaEmbeddingModel
+
+__all__ = [
+    "OllamaEmbeddingModel",
+]
diff --git a/src/agentscope/embedding/_ollama/_model.py b/src/agentscope/embedding/_ollama/_model.py
new file mode 100644
index 0000000..9210ac2
--- /dev/null
+++ b/src/agentscope/embedding/_ollama/_model.py
@@ -0,0 +1,132 @@
+# -*- coding: utf-8 -*-
+"""The Ollama embedding model."""
+
+from datetime import datetime
+from typing import Any
+
+from .._embedding_response import EmbeddingResponse
+from .._embedding_usage import EmbeddingUsage
+from .._cache_base import EmbeddingCacheBase
+from .._embedding_base import EmbeddingModelBase
+from ...credential import CredentialBase
+from ...message import TextBlock
+
+
+class OllamaEmbeddingModel(EmbeddingModelBase[str | TextBlock]):
+    """Ollama text embedding model.
+
+    Wraps locally-hosted embedding models served by Ollama (e.g.
+    ``nomic-embed-text``, ``mxbai-embed-large``).  Inherits batching
+    and retry logic from :class:`EmbeddingModelBase`.  ``TextBlock``
+    items in the input list are unpacked to their ``.text`` field by
+    the base class before ``_call_api`` runs, so this subclass only
+    has to handle plain ``str``.
+    """
+
+    _TEXT_BATCH_SIZE: int = 512
+
+    def __init__(
+        self,
+        credential: CredentialBase,
+        model: str,
+        dimensions: int | None,
+        parameters: "OllamaEmbeddingModel.Parameters | None" = None,
+        embedding_cache: EmbeddingCacheBase | None = None,
+        context_size: int = 8192,
+        max_retries: int = 3,
+        retry_delay: float = 1.0,
+    ) -> None:
+        """Initialize the Ollama embedding model.
+
+        Args:
+            credential (`CredentialBase`):
+                An :class:`~agentscope.credential.OllamaCredential`
+                instance providing the host URL.
+            model (`str`):
+                The embedding model name (e.g.
+                ``"nomic-embed-text"``).
+            dimensions (`int | None`):
+                The output embedding vector dimensions.  Required at
+                the contract level — see :class:`EmbeddingModelBase`
+                for the rationale.  ``None`` is accepted only for
+                backward compatibility with legacy configs that
+                persisted ``dimensions`` inside ``parameters``.
+            parameters (`OllamaEmbeddingModel.Parameters | None`, \
+            defaults to ``None``):
+                Provider-specific non-dimensional parameters.  Currently
+                empty for Ollama.
+            embedding_cache (`EmbeddingCacheBase | None`, defaults to \
+            ``None``):
+                Optional embedding cache.
+            context_size (`int`, defaults to ``8192``):
+                Maximum input tokens per text.
+            max_retries (`int`, defaults to ``3``):
+                Number of retries on transient failures.
+            retry_delay (`float`, defaults to ``1.0``):
+                Seconds between retry attempts.
+        """
+        super().__init__(
+            credential=credential,
+            model=model,
+            dimensions=dimensions,
+            parameters=parameters,
+            context_size=context_size,
+            batch_size=self._TEXT_BATCH_SIZE,
+            max_retries=max_retries,
+            retry_delay=retry_delay,
+        )
+        self.host: str | None = getattr(credential, "host", None)
+        self.embedding_cache: EmbeddingCacheBase | None = embedding_cache
+
+    async def _call_api(
+        self,
+        inputs: list[str],
+        **kwargs: Any,
+    ) -> EmbeddingResponse:
+        """Call the Ollama embedding API for a single batch.
+
+        Args:
+            inputs (`list[str]`):
+                A batch of texts to embed.
+            **kwargs:
+                Extra keyword arguments forwarded to the Ollama API.
+
+        Returns:
+            `EmbeddingResponse`: Embedding vectors and usage info.
+        """
+        api_kwargs: dict[str, Any] = {
+            "input": inputs,
+            "model": self.model,
+            "dimensions": self.dimensions,
+            **kwargs,
+        }
+
+        if self.embedding_cache:
+            cached = await self.embedding_cache.retrieve(
+                identifier=api_kwargs,
+            )
+            if cached:
+                return EmbeddingResponse(
+                    embeddings=cached,
+                    usage=EmbeddingUsage(tokens=0, time=0),
+                    source="cache",
+                )
+
+        import ollama
+
+        client = ollama.AsyncClient(host=self.host)
+
+        start_time = datetime.now()
+        response = await client.embed(**api_kwargs)
+        time = (datetime.now() - start_time).total_seconds()
+
+        if self.embedding_cache:
+            await self.embedding_cache.store(
+                identifier=api_kwargs,
+                embeddings=response.embeddings,
+            )
+
+        return EmbeddingResponse(
+            embeddings=response.embeddings,
+            usage=EmbeddingUsage(time=time),
+        )
diff --git a/src/agentscope/embedding/_openai/__init__.py b/src/agentscope/embedding/_openai/__init__.py
new file mode 100644
index 0000000..0a460ba
--- /dev/null
+++ b/src/agentscope/embedding/_openai/__init__.py
@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+"""The OpenAI embedding API modules."""
+
+from ._model import OpenAIEmbeddingModel
+
+__all__ = [
+    "OpenAIEmbeddingModel",
+]
diff --git a/src/agentscope/embedding/_openai/_model.py b/src/agentscope/embedding/_openai/_model.py
new file mode 100644
index 0000000..ee39019
--- /dev/null
+++ b/src/agentscope/embedding/_openai/_model.py
@@ -0,0 +1,179 @@
+# -*- coding: utf-8 -*-
+"""The OpenAI embedding model."""
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Type
+
+from .._embedding_response import EmbeddingResponse
+from .._embedding_usage import EmbeddingUsage
+from .._cache_base import EmbeddingCacheBase
+from .._embedding_base import EmbeddingModelBase
+from ...credential import CredentialBase
+from ...message import TextBlock
+
+
+class OpenAIEmbeddingModel(EmbeddingModelBase[str | TextBlock]):
+    """OpenAI text embedding model.
+
+    Supports ``text-embedding-3-small``, ``text-embedding-3-large``,
+    and other OpenAI-compatible embedding models.  Inherits batching
+    and retry logic from :class:`EmbeddingModelBase`.  ``TextBlock``
+    items in the input list are unpacked to their ``.text`` field by
+    the base class before ``_call_api`` runs, so this subclass only
+    has to handle plain ``str``.
+    """
+
+    #: OpenAI does not document an explicit per-request item limit;
+    #: the constraint is on total tokens.  We use a conservative
+    #: default that works well in practice.
+    _TEXT_BATCH_SIZE: int = 2048
+
+    def __init__(
+        self,
+        credential: CredentialBase,
+        model: str,
+        dimensions: int | None,
+        parameters: "OpenAIEmbeddingModel.Parameters | None" = None,
+        pass_dimensions: bool = True,
+        embedding_cache: EmbeddingCacheBase | None = None,
+        context_size: int = 8191,
+        max_retries: int = 3,
+        retry_delay: float = 1.0,
+    ) -> None:
+        """Initialize the OpenAI embedding model.
+
+        Args:
+            credential (`CredentialBase`):
+                An :class:`~agentscope.credential.OpenAICredential`
+                instance providing the API key and optional base URL /
+                organization.
+            model (`str`):
+                The embedding model name (e.g.
+                ``"text-embedding-3-small"``).
+            dimensions (`int | None`):
+                The output embedding vector dimensions.  Required at
+                the contract level — see :class:`EmbeddingModelBase`
+                for the rationale.  ``None`` is accepted only for
+                backward compatibility with legacy configs that
+                persisted ``dimensions`` inside ``parameters``.
+            parameters (`OpenAIEmbeddingModel.Parameters | None`, \
+            defaults to ``None``):
+                Provider-specific non-dimensional parameters.  Currently
+                empty for OpenAI.
+            pass_dimensions (`bool`, defaults to `True`):
+                Whether to pass the ``dimensions`` parameter to the API.
+                Some OpenAI-compatible providers do not support it.
+            embedding_cache (`EmbeddingCacheBase | None`, defaults to \
+            ``None``):
+                Optional embedding cache.
+            context_size (`int`, defaults to ``8191``):
+                Maximum input tokens per text.
+            max_retries (`int`, defaults to ``3``):
+                Number of retries on transient failures.
+            retry_delay (`float`, defaults to ``1.0``):
+                Seconds between retry attempts.
+        """
+        import openai
+
+        super().__init__(
+            credential=credential,
+            model=model,
+            dimensions=dimensions,
+            parameters=parameters,
+            context_size=context_size,
+            batch_size=self._TEXT_BATCH_SIZE,
+            max_retries=max_retries,
+            retry_delay=retry_delay,
+        )
+
+        client_kwargs: dict[str, Any] = {}
+        if getattr(credential, "base_url", None) is not None:
+            client_kwargs["base_url"] = credential.base_url
+        if getattr(credential, "organization", None) is not None:
+            client_kwargs["organization"] = credential.organization
+
+        self.client: openai.AsyncClient = openai.AsyncClient(
+            api_key=credential.api_key.get_secret_value(),
+            **client_kwargs,
+        )
+        self.pass_dimensions = pass_dimensions
+        self.embedding_cache: EmbeddingCacheBase | None = embedding_cache
+
+    @classmethod
+    def _get_retryable_exceptions(cls) -> tuple[Type[Exception], ...]:
+        """Return OpenAI exceptions that warrant a retry."""
+        import openai
+
+        return (
+            openai.APIConnectionError,
+            openai.APITimeoutError,
+            openai.RateLimitError,
+            openai.InternalServerError,
+        )
+
+    async def _call_api(
+        self,
+        inputs: list[str],
+        **kwargs: Any,
+    ) -> EmbeddingResponse:
+        """Call the OpenAI embedding API for a single batch.
+
+        Args:
+            inputs (`list[str]`):
+                A batch of texts to embed.
+            **kwargs:
+                Extra keyword arguments forwarded to the OpenAI API.
+
+        Returns:
+            `EmbeddingResponse`: Embedding vectors and usage info.
+        """
+        api_kwargs: dict[str, Any] = {
+            "input": inputs,
+            "model": self.model,
+            "encoding_format": "float",
+            **kwargs,
+        }
+        if self.pass_dimensions:
+            api_kwargs["dimensions"] = self.dimensions
+
+        if self.embedding_cache:
+            cached = await self.embedding_cache.retrieve(
+                identifier=api_kwargs,
+            )
+            if cached:
+                return EmbeddingResponse(
+                    embeddings=cached,
+                    usage=EmbeddingUsage(tokens=0, time=0),
+                    source="cache",
+                )
+
+        start_time = datetime.now()
+        response = await self.client.embeddings.create(**api_kwargs)
+        time = (datetime.now() - start_time).total_seconds()
+
+        embeddings: list[Any] = [None] * len(inputs)
+        for pos, item in enumerate(response.data):
+            index = getattr(item, "index", pos)
+            if not isinstance(index, int):
+                index = pos
+            if 0 <= index < len(inputs):
+                embeddings[index] = item.embedding or getattr(
+                    item,
+                    "dense_embedding",
+                    None,
+                )
+
+        if self.embedding_cache:
+            await self.embedding_cache.store(
+                identifier=api_kwargs,
+                embeddings=embeddings,
+            )
+
+        return EmbeddingResponse(
+            embeddings=embeddings,
+            usage=EmbeddingUsage(
+                tokens=response.usage.total_tokens,
+                time=time,
+            ),
+        )
diff --git a/src/agentscope/embedding/_openai/_models/text-embedding-3-large.yaml b/src/agentscope/embedding/_openai/_models/text-embedding-3-large.yaml
new file mode 100644
index 0000000..6ddfc9e
--- /dev/null
+++ b/src/agentscope/embedding/_openai/_models/text-embedding-3-large.yaml
@@ -0,0 +1,14 @@
+name: text-embedding-3-large
+label: Text Embedding 3 Large
+status: active
+
+input_types:
+  - text/plain
+
+output_types:
+  - application/x-embedding
+
+context_size: 8191
+
+dimensions: 3072
+supported_dimensions: [3072, 1536, 1024, 768, 512, 256]
diff --git a/src/agentscope/embedding/_openai/_models/text-embedding-3-small.yaml b/src/agentscope/embedding/_openai/_models/text-embedding-3-small.yaml
new file mode 100644
index 0000000..b74c281
--- /dev/null
+++ b/src/agentscope/embedding/_openai/_models/text-embedding-3-small.yaml
@@ -0,0 +1,14 @@
+name: text-embedding-3-small
+label: Text Embedding 3 Small
+status: active
+
+input_types:
+  - text/plain
+
+output_types:
+  - application/x-embedding
+
+context_size: 8191
+
+dimensions: 1536
+supported_dimensions: [1536, 1024, 768, 512, 256]
diff --git a/src/agentscope/event/__init__.py b/src/agentscope/event/__init__.py
new file mode 100644
index 0000000..a7b0b55
--- /dev/null
+++ b/src/agentscope/event/__init__.py
@@ -0,0 +1,75 @@
+# -*- coding: utf-8 -*-
+"""The event module of agentscope."""
+
+from ._event import (
+    EventType,
+    EventBase,
+    ReplyStartEvent,
+    ReplyEndReason,
+    ReplyEndEvent,
+    ModelCallStartEvent,
+    ModelCallEndEvent,
+    TextBlockStartEvent,
+    TextBlockDeltaEvent,
+    TextBlockEndEvent,
+    DataBlockStartEvent,
+    DataBlockDeltaEvent,
+    DataBlockEndEvent,
+    ThinkingBlockStartEvent,
+    ThinkingBlockDeltaEvent,
+    ThinkingBlockEndEvent,
+    HintBlockEvent,
+    ToolCallStartEvent,
+    ToolCallDeltaEvent,
+    ToolCallEndEvent,
+    ToolResultStartEvent,
+    ToolResultTextDeltaEvent,
+    ToolResultDataDeltaEvent,
+    ToolResultEndEvent,
+    ExceedMaxItersEvent,
+    RequireUserConfirmEvent,
+    RequireExternalExecutionEvent,
+    UserConfirmResultEvent,
+    UserInterruptEvent,
+    ExternalExecutionResultEvent,
+    CustomEvent,
+    AgentEvent,
+    ConfirmResult,
+)
+
+
+__all__ = [
+    "EventType",
+    "EventBase",
+    "ReplyStartEvent",
+    "ReplyEndReason",
+    "ReplyEndEvent",
+    "ModelCallStartEvent",
+    "ModelCallEndEvent",
+    "TextBlockStartEvent",
+    "TextBlockDeltaEvent",
+    "TextBlockEndEvent",
+    "DataBlockStartEvent",
+    "DataBlockDeltaEvent",
+    "DataBlockEndEvent",
+    "ThinkingBlockStartEvent",
+    "ThinkingBlockDeltaEvent",
+    "ThinkingBlockEndEvent",
+    "HintBlockEvent",
+    "ToolCallStartEvent",
+    "ToolCallDeltaEvent",
+    "ToolCallEndEvent",
+    "ToolResultStartEvent",
+    "ToolResultTextDeltaEvent",
+    "ToolResultDataDeltaEvent",
+    "ToolResultEndEvent",
+    "ExceedMaxItersEvent",
+    "RequireUserConfirmEvent",
+    "RequireExternalExecutionEvent",
+    "UserConfirmResultEvent",
+    "UserInterruptEvent",
+    "ExternalExecutionResultEvent",
+    "CustomEvent",
+    "AgentEvent",
+    "ConfirmResult",
+]
diff --git a/src/agentscope/event/_event.py b/src/agentscope/event/_event.py
new file mode 100644
index 0000000..2104b69
--- /dev/null
+++ b/src/agentscope/event/_event.py
@@ -0,0 +1,548 @@
+# -*- coding: utf-8 -*-
+"""Event types for agent execution."""
+from datetime import datetime
+from enum import StrEnum
+from typing import Any, Dict, Literal, List, TypeAlias
+
+from pydantic import BaseModel, Field, ConfigDict
+
+from .._utils._common import _generate_id
+from ..message import (
+    DataBlock,
+    TextBlock,
+    ToolCallBlock,
+    ToolResultBlock,
+    ToolResultState,
+)
+from ..model import FinishedReason
+from ..permission import PermissionRule
+
+
+class EventType(StrEnum):
+    """Event type enumeration."""
+
+    REPLY_START = "REPLY_START"
+    REPLY_END = "REPLY_END"
+
+    MODEL_CALL_START = "MODEL_CALL_START"
+    MODEL_CALL_END = "MODEL_CALL_END"
+
+    TEXT_BLOCK_START = "TEXT_BLOCK_START"
+    TEXT_BLOCK_DELTA = "TEXT_BLOCK_DELTA"
+    TEXT_BLOCK_END = "TEXT_BLOCK_END"
+
+    DATA_BLOCK_START = "DATA_BLOCK_START"
+    DATA_BLOCK_DELTA = "DATA_BLOCK_DELTA"
+    DATA_BLOCK_END = "DATA_BLOCK_END"
+
+    THINKING_BLOCK_START = "THINKING_BLOCK_START"
+    THINKING_BLOCK_DELTA = "THINKING_BLOCK_DELTA"
+    THINKING_BLOCK_END = "THINKING_BLOCK_END"
+
+    HINT_BLOCK = "HINT_BLOCK"
+
+    TOOL_CALL_START = "TOOL_CALL_START"
+    TOOL_CALL_DELTA = "TOOL_CALL_DELTA"
+    TOOL_CALL_END = "TOOL_CALL_END"
+
+    TOOL_RESULT_START = "TOOL_RESULT_START"
+    TOOL_RESULT_TEXT_DELTA = "TOOL_RESULT_TEXT_DELTA"
+    TOOL_RESULT_DATA_DELTA = "TOOL_RESULT_DATA_DELTA"
+    TOOL_RESULT_END = "TOOL_RESULT_END"
+
+    EXCEED_MAX_ITERS = "EXCEED_MAX_ITERS"
+
+    REQUIRE_USER_CONFIRM = "REQUIRE_USER_CONFIRM"
+    REQUIRE_EXTERNAL_EXECUTION = "REQUIRE_EXTERNAL_EXECUTION"
+
+    USER_CONFIRM_RESULT = "USER_CONFIRM_RESULT"
+    USER_INTERRUPT = "USER_INTERRUPT"
+    EXTERNAL_EXECUTION_RESULT = "EXTERNAL_EXECUTION_RESULT"
+
+    CUSTOM = "CUSTOM"
+
+
+class EventBase(BaseModel):
+    """Base event class."""
+
+    model_config = ConfigDict(use_enum_values=True)
+
+    id: str = Field(default_factory=_generate_id)
+    """Unique event identifier."""
+    created_at: str = Field(default_factory=lambda: datetime.now().isoformat())
+    """ISO 8601 timestamp of when the event was created."""
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+    """Optional metadata attached to the event."""
+
+
+class ReplyStartEvent(EventBase):
+    """Reply start event."""
+
+    type: Literal[EventType.REPLY_START] = EventType.REPLY_START
+    """Event type."""
+    session_id: str
+    """ID of the session this reply belongs to."""
+    reply_id: str
+    """ID of the reply message produced by this reply."""
+    name: str
+    """Name of the agent."""
+    role: Literal["user", "assistant", "system"] = "assistant"
+    """Role of the agent."""
+
+
+class ReplyEndReason(StrEnum):
+    """The reason for reply ended."""
+
+    COMPLETED = "completed"
+    INTERRUPTED = "interrupted"
+    EXCEED_MAX_ITERS = "exceed_max_iters"
+
+
+class ReplyEndEvent(EventBase):
+    """Reply end event."""
+
+    type: Literal[EventType.REPLY_END] = EventType.REPLY_END
+    """Event type."""
+    session_id: str
+    """ID of the session this reply belongs to."""
+    reply_id: str
+    """ID of the reply message produced by this reply."""
+    finished_reason: ReplyEndReason = ReplyEndReason.COMPLETED
+    """The finished reason of this reply."""
+
+
+class ModelCallStartEvent(EventBase):
+    """Model call start event."""
+
+    type: Literal[EventType.MODEL_CALL_START] = EventType.MODEL_CALL_START
+    """Event type."""
+    reply_id: str
+    """ID of the reply message this model call belongs to."""
+    model_name: str
+    """Name of the model being called."""
+
+
+class ModelCallEndEvent(EventBase):
+    """Model call end event."""
+
+    type: Literal[EventType.MODEL_CALL_END] = EventType.MODEL_CALL_END
+    """Event type."""
+    reply_id: str
+    """ID of the reply message this model call belongs to."""
+    input_tokens: int
+    """Number of input tokens consumed."""
+    output_tokens: int
+    """Number of output tokens generated."""
+    finished_reason: FinishedReason = Field(
+        default=FinishedReason.COMPLETED,
+    )
+    """The finished reason of this model call."""
+
+
+class TextBlockStartEvent(EventBase):
+    """Text block start event."""
+
+    type: Literal[EventType.TEXT_BLOCK_START] = EventType.TEXT_BLOCK_START
+    """Event type."""
+    reply_id: str
+    """ID of the reply message this block belongs to."""
+    block_id: str
+    """Unique identifier of the text block."""
+
+
+class TextBlockDeltaEvent(EventBase):
+    """Text block delta event."""
+
+    type: Literal[EventType.TEXT_BLOCK_DELTA] = EventType.TEXT_BLOCK_DELTA
+    """Event type."""
+    reply_id: str
+    """ID of the reply message this block belongs to."""
+    block_id: str
+    """Unique identifier of the text block."""
+    delta: str
+    """Incremental text content."""
+
+
+class TextBlockEndEvent(EventBase):
+    """Text block end event."""
+
+    type: Literal[EventType.TEXT_BLOCK_END] = EventType.TEXT_BLOCK_END
+    """Event type."""
+    reply_id: str
+    """ID of the reply message this block belongs to."""
+    block_id: str
+    """Unique identifier of the text block."""
+
+
+class DataBlockStartEvent(EventBase):
+    """Data block start event."""
+
+    type: Literal[EventType.DATA_BLOCK_START] = EventType.DATA_BLOCK_START
+    """Event type."""
+    reply_id: str
+    """ID of the reply message this block belongs to."""
+    block_id: str
+    """Unique identifier of the data block."""
+    media_type: str
+    """MIME type of the data content (e.g. "image/png")."""
+
+
+class DataBlockDeltaEvent(EventBase):
+    """Data block delta event."""
+
+    type: Literal[EventType.DATA_BLOCK_DELTA] = EventType.DATA_BLOCK_DELTA
+    """Event type."""
+    reply_id: str
+    """ID of the reply message this block belongs to."""
+    block_id: str
+    """Unique identifier of the data block."""
+    data: str
+    """Incremental base64-encoded data."""
+    media_type: str
+    """MIME type of the data content."""
+
+
+class DataBlockEndEvent(EventBase):
+    """Data block end event."""
+
+    type: Literal[EventType.DATA_BLOCK_END] = EventType.DATA_BLOCK_END
+    """Event type."""
+    reply_id: str
+    """ID of the reply message this block belongs to."""
+    block_id: str
+    """Unique identifier of the data block."""
+
+
+class ThinkingBlockStartEvent(EventBase):
+    """Thinking block start event."""
+
+    type: Literal[
+        EventType.THINKING_BLOCK_START
+    ] = EventType.THINKING_BLOCK_START
+    """Event type."""
+    reply_id: str
+    """ID of the reply message this block belongs to."""
+    block_id: str
+    """Unique identifier of the thinking block."""
+
+
+class ThinkingBlockDeltaEvent(EventBase):
+    """Thinking block delta event."""
+
+    type: Literal[
+        EventType.THINKING_BLOCK_DELTA
+    ] = EventType.THINKING_BLOCK_DELTA
+    """Event type."""
+    reply_id: str
+    """ID of the reply message this block belongs to."""
+    block_id: str
+    """Unique identifier of the thinking block."""
+    delta: str
+    """Incremental thinking text content."""
+
+
+class ThinkingBlockEndEvent(EventBase):
+    """Thinking block end event."""
+
+    type: Literal[EventType.THINKING_BLOCK_END] = EventType.THINKING_BLOCK_END
+    """Event type."""
+    reply_id: str
+    """ID of the reply message this block belongs to."""
+    block_id: str
+    """Unique identifier of the thinking block."""
+
+
+class HintBlockEvent(EventBase):
+    """One-shot hint block event.
+
+    Unlike text/thinking blocks, hint blocks are not streamed — the
+    full content is available at creation time (team messages,
+    background tool results, user interruptions, …). A single event
+    carries the complete :class:`~agentscope.message.HintBlock`.
+
+    The ``hint`` field mirrors :attr:`HintBlock.hint` and may be a
+    plain string or a list of :class:`TextBlock` / :class:`DataBlock`
+    for multimodal content.
+    """
+
+    type: Literal[EventType.HINT_BLOCK] = EventType.HINT_BLOCK
+    """Event type."""
+    reply_id: str
+    """ID of the reply message this block belongs to."""
+    block_id: str
+    """Unique identifier of the hint block."""
+    source: str | None = None
+    """Sender or origin of this hint (e.g. ``"alice"``, ``"system"``)."""
+    hint: str | List[TextBlock | DataBlock]
+    """Complete hint content — ``str`` or ``list[TextBlock | DataBlock]``."""
+
+
+class ToolCallStartEvent(EventBase):
+    """Tool call start event."""
+
+    type: Literal[EventType.TOOL_CALL_START] = EventType.TOOL_CALL_START
+    """Event type."""
+    reply_id: str
+    """ID of the reply message this tool call belongs to."""
+    tool_call_id: str
+    """Unique identifier of the tool call."""
+    tool_call_name: str
+    """Name of the tool being called."""
+
+
+class ToolCallDeltaEvent(EventBase):
+    """Tool call delta event."""
+
+    type: Literal[EventType.TOOL_CALL_DELTA] = EventType.TOOL_CALL_DELTA
+    """Event type."""
+    reply_id: str
+    """ID of the reply message this tool call belongs to."""
+    tool_call_id: str
+    """Unique identifier of the tool call."""
+    delta: str
+    """Incremental tool call arguments (JSON fragment)."""
+
+
+class ToolCallEndEvent(EventBase):
+    """Tool call end event."""
+
+    type: Literal[EventType.TOOL_CALL_END] = EventType.TOOL_CALL_END
+    """Event type."""
+    reply_id: str
+    """ID of the reply message this tool call belongs to."""
+    tool_call_id: str
+    """Unique identifier of the tool call."""
+
+
+class ToolResultStartEvent(EventBase):
+    """Tool result start event."""
+
+    type: Literal[EventType.TOOL_RESULT_START] = EventType.TOOL_RESULT_START
+    """Event type."""
+    reply_id: str
+    """ID of the reply message this tool result belongs to."""
+    tool_call_id: str
+    """ID of the corresponding tool call."""
+    tool_call_name: str
+    """Name of the tool that was called."""
+
+
+class ToolResultTextDeltaEvent(EventBase):
+    """Tool result text delta event."""
+
+    type: Literal[
+        EventType.TOOL_RESULT_TEXT_DELTA
+    ] = EventType.TOOL_RESULT_TEXT_DELTA
+    """Event type."""
+    reply_id: str
+    """ID of the reply message this tool result belongs to."""
+    tool_call_id: str
+    """ID of the corresponding tool call."""
+    delta: str
+    """Incremental text content of the tool result."""
+
+
+class ToolResultDataDeltaEvent(EventBase):
+    """Tool result data delta event."""
+
+    type: Literal[
+        EventType.TOOL_RESULT_DATA_DELTA
+    ] = EventType.TOOL_RESULT_DATA_DELTA
+    """Event type."""
+    reply_id: str
+    """ID of the reply message this tool result belongs to."""
+    tool_call_id: str
+    """ID of the corresponding tool call."""
+    block_id: str = Field(default_factory=_generate_id)
+    """Unique identifier of the data block created by this event."""
+    media_type: str
+    """MIME type of the binary content."""
+    data: str | None = None
+    """Base64-encoded binary data, mutually exclusive with `url`."""
+    url: str | None = None
+    """URL pointing to the binary content, mutually exclusive with `data`."""
+
+
+class ToolResultEndEvent(EventBase):
+    """Tool result end event."""
+
+    model_config = ConfigDict(use_enum_values=True)
+
+    type: Literal[EventType.TOOL_RESULT_END] = EventType.TOOL_RESULT_END
+    """Event type."""
+    reply_id: str
+    """ID of the reply message this tool result belongs to."""
+    tool_call_id: str
+    """ID of the corresponding tool call."""
+    state: ToolResultState
+    """Final execution state of the tool call."""
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    """Optional metadata attached to the tool result event."""
+
+
+class ExceedMaxItersEvent(EventBase):
+    """Exceeded max iteration event."""
+
+    type: Literal[EventType.EXCEED_MAX_ITERS] = EventType.EXCEED_MAX_ITERS
+    """Event type."""
+    reply_id: str
+    """ID of the reply message associated with this run."""
+    name: str
+    """Name of the agent."""
+
+
+class RequireUserConfirmEvent(EventBase):
+    """Require user confirm event."""
+
+    type: Literal[
+        EventType.REQUIRE_USER_CONFIRM
+    ] = EventType.REQUIRE_USER_CONFIRM
+    """Event type."""
+    reply_id: str
+    """ID of the reply message associated with this run."""
+    tool_calls: List[ToolCallBlock]
+    """Tool calls pending user confirmation."""
+
+
+class RequireExternalExecutionEvent(EventBase):
+    """Require external execution event."""
+
+    type: Literal[
+        EventType.REQUIRE_EXTERNAL_EXECUTION
+    ] = EventType.REQUIRE_EXTERNAL_EXECUTION
+    """Event type."""
+    reply_id: str
+    """ID of the reply message associated with this run."""
+    tool_calls: List[ToolCallBlock]
+    """Tool calls to be executed externally."""
+
+
+class ConfirmResult(BaseModel):
+    """Confirm result for a tool call."""
+
+    confirmed: bool
+    """Whether the user confirmed the tool call."""
+    tool_call: ToolCallBlock
+    """The tool call that was confirmed or rejected."""
+    rules: list[PermissionRule] | None = None
+    """The allowed permission rules for this tool call. This field is only
+    applicable when ``confirmed`` is True. In case user modification is
+    needed, complete permission rules are used here instead of references to
+    the suggested rules in ``RequireUserConfirmEvent``."""
+
+
+class UserConfirmResultEvent(EventBase):
+    """User confirm result event."""
+
+    type: Literal[
+        EventType.USER_CONFIRM_RESULT
+    ] = EventType.USER_CONFIRM_RESULT
+    """Event type."""
+    reply_id: str
+    """ID of the reply message associated with this run."""
+    confirm_results: list[ConfirmResult]
+    """Confirmation results for each pending tool call."""
+
+
+class UserInterruptEvent(EventBase):
+    """User-initiated interrupt targeting a parked reply.
+
+    Delivered to :meth:`Agent.reply_stream` (or :meth:`Agent.reply`) to
+    abort a reply that is currently waiting on external input — either
+    user confirmation (:class:`RequireUserConfirmEvent`) or external
+    execution (:class:`RequireExternalExecutionEvent`).
+
+    On receipt, the agent closes every pending tool call with an
+    interrupted tool result, emits a fallback assistant message, ends
+    the reply with :attr:`ReplyEndReason.INTERRUPTED`, and does **not**
+    enter the reasoning-acting loop.
+
+    .. note:: This event is only meaningful for parked replies. To
+        interrupt a running (actively-generating) reply, cancel the
+        underlying task instead — the agent handles that path via its
+        own ``CancelledError`` cleanup.
+    """
+
+    type: Literal[EventType.USER_INTERRUPT] = EventType.USER_INTERRUPT
+    """Event type."""
+    reply_id: str
+    """ID of the reply message this interrupt targets."""
+
+
+class ExternalExecutionResultEvent(EventBase):
+    """External execution result event."""
+
+    type: Literal[
+        EventType.EXTERNAL_EXECUTION_RESULT
+    ] = EventType.EXTERNAL_EXECUTION_RESULT
+    """Event type."""
+    reply_id: str
+    """ID of the reply message associated with this run."""
+    execution_results: List[ToolResultBlock]
+    """Results returned by the external executor."""
+
+
+class CustomEvent(EventBase):
+    """Generic extensible event for signals that don't fit a specific
+    ``AgentEvent`` subtype.
+
+    Used by service-layer middleware to notify front-end subscribers
+    about state changes (task progress, team membership, permission
+    updates, …) without polluting the core agent event enum with
+    application-specific types.
+
+    Front-end implementations should handle unknown ``name`` values
+    gracefully — skip with no error.
+
+    Attributes:
+        name (`str`):
+            Identifies the kind of notification. Well-known values:
+
+            - ``"state_updated"`` — agent state (tasks / permission)
+              changed during a tool call.
+            - ``"team_updated"`` — team membership changed (member
+              added / team created or dissolved).
+
+        value (`dict`):
+            Arbitrary JSON-serializable payload whose schema depends
+            on ``name``. May be empty.
+    """
+
+    type: Literal[EventType.CUSTOM] = EventType.CUSTOM
+    """Event type discriminator."""
+    name: str
+    """Kind of notification — see class docstring for well-known values."""
+    value: dict = Field(default_factory=dict)
+    """Arbitrary payload."""
+
+
+AgentEvent: TypeAlias = (
+    ReplyStartEvent
+    | ReplyEndEvent
+    | ExceedMaxItersEvent
+    | RequireUserConfirmEvent
+    | RequireExternalExecutionEvent
+    | ModelCallStartEvent
+    | ModelCallEndEvent
+    | TextBlockStartEvent
+    | TextBlockDeltaEvent
+    | TextBlockEndEvent
+    | DataBlockStartEvent
+    | DataBlockDeltaEvent
+    | DataBlockEndEvent
+    | ThinkingBlockStartEvent
+    | ThinkingBlockDeltaEvent
+    | ThinkingBlockEndEvent
+    | HintBlockEvent
+    | ToolCallStartEvent
+    | ToolCallDeltaEvent
+    | ToolCallEndEvent
+    | ToolResultStartEvent
+    | ToolResultTextDeltaEvent
+    | ToolResultDataDeltaEvent
+    | ToolResultEndEvent
+    | UserConfirmResultEvent
+    | UserInterruptEvent
+    | ExternalExecutionResultEvent
+    | CustomEvent
+)
diff --git a/src/agentscope/exception/__init__.py b/src/agentscope/exception/__init__.py
new file mode 100644
index 0000000..83be2bf
--- /dev/null
+++ b/src/agentscope/exception/__init__.py
@@ -0,0 +1,22 @@
+# -*- coding: utf-8 -*-
+"""The exception module in agentscope."""
+
+from ._base import (
+    AgentOrientedException,
+    DeveloperOrientedException,
+)
+from ._tool import (
+    ToolInterruptedError,
+    ToolNotFoundError,
+    ToolJSONDecodeError,
+    ToolGroupInactiveError,
+)
+
+__all__ = [
+    "AgentOrientedException",
+    "DeveloperOrientedException",
+    "ToolInterruptedError",
+    "ToolNotFoundError",
+    "ToolJSONDecodeError",
+    "ToolGroupInactiveError",
+]
diff --git a/src/agentscope/exception/_base.py b/src/agentscope/exception/_base.py
new file mode 100644
index 0000000..a96a945
--- /dev/null
+++ b/src/agentscope/exception/_base.py
@@ -0,0 +1,27 @@
+# -*- coding: utf-8 -*-
+"""The base exception class in agentscope."""
+
+
+class AgentOrientedException(Exception):
+    """The base class for all agent-oriented exceptions. These exceptions are
+    expect to the captured and exposed to the agent during runtime, so that
+    agents can handle the error appropriately during the runtime.
+    """
+
+    def __init__(self, message: str):
+        """Initialize the exception with a message."""
+        super().__init__(message)
+        self.message = message
+
+    def __str__(self) -> str:
+        """Return the string representation of the exception."""
+        return f"{self.__class__.__name__}: {self.message}"
+
+
+class DeveloperOrientedException(Exception):
+    """The exception should be raised to the developers."""
+
+    def __init__(self, message: str):
+        """Initialize the exception with a message."""
+        super().__init__(message)
+        self.message = message
diff --git a/src/agentscope/exception/_tool.py b/src/agentscope/exception/_tool.py
new file mode 100644
index 0000000..730b9be
--- /dev/null
+++ b/src/agentscope/exception/_tool.py
@@ -0,0 +1,20 @@
+# -*- coding: utf-8 -*-
+"""The tool-related exceptions in agentscope."""
+
+from ._base import AgentOrientedException
+
+
+class ToolNotFoundError(AgentOrientedException):
+    """Exception raised when a tool was not found."""
+
+
+class ToolInterruptedError(AgentOrientedException):
+    """Exception raised when a tool calling was interrupted by the user."""
+
+
+class ToolJSONDecodeError(AgentOrientedException):
+    """Exception raised when tool arguments fail JSON decoding or repair."""
+
+
+class ToolGroupInactiveError(AgentOrientedException):
+    """Exception raised when a tool group is inactive."""
diff --git a/src/agentscope/formatter/__init__.py b/src/agentscope/formatter/__init__.py
new file mode 100644
index 0000000..0594040
--- /dev/null
+++ b/src/agentscope/formatter/__init__.py
@@ -0,0 +1,62 @@
+# -*- coding: utf-8 -*-
+"""The formatter module in agentscope."""
+
+from ._formatter_base import FormatterBase
+from ._dashscope_formatter import (
+    DashScopeChatFormatter,
+    DashScopeMultiAgentFormatter,
+)
+from ._anthropic_formatter import (
+    AnthropicChatFormatter,
+    AnthropicMultiAgentFormatter,
+)
+from ._openai_formatter import (
+    OpenAIChatFormatter,
+    OpenAIMultiAgentFormatter,
+)
+from ._gemini_formatter import (
+    GeminiChatFormatter,
+    GeminiMultiAgentFormatter,
+)
+from ._ollama_formatter import (
+    OllamaChatFormatter,
+    OllamaMultiAgentFormatter,
+)
+from ._deepseek_formatter import (
+    DeepSeekChatFormatter,
+    DeepSeekMultiAgentFormatter,
+)
+from ._openai_response_formatter import (
+    OpenAIResponseFormatter,
+    OpenAIResponseMultiAgentFormatter,
+)
+from ._moonshot_formatter import (
+    MoonshotChatFormatter,
+    MoonshotMultiAgentFormatter,
+)
+from ._xai_formatter import (
+    XAIChatFormatter,
+    XAIMultiAgentFormatter,
+)
+
+__all__ = [
+    "FormatterBase",
+    "DashScopeChatFormatter",
+    "DashScopeMultiAgentFormatter",
+    "OpenAIChatFormatter",
+    "OpenAIMultiAgentFormatter",
+    "AnthropicChatFormatter",
+    "AnthropicMultiAgentFormatter",
+    "GeminiChatFormatter",
+    "GeminiMultiAgentFormatter",
+    "OllamaChatFormatter",
+    "OllamaMultiAgentFormatter",
+    "DeepSeekChatFormatter",
+    "DeepSeekMultiAgentFormatter",
+    "OpenAIResponseFormatter",
+    "OpenAIResponseMultiAgentFormatter",
+    "MoonshotChatFormatter",
+    "MoonshotMultiAgentFormatter",
+    "XAIChatFormatter",
+    "XAIMultiAgentFormatter",
+]
diff --git a/src/agentscope/formatter/_anthropic_formatter.py b/src/agentscope/formatter/_anthropic_formatter.py
new file mode 100644
index 0000000..42c9ba7
--- /dev/null
+++ b/src/agentscope/formatter/_anthropic_formatter.py
@@ -0,0 +1,533 @@
+# -*- coding: utf-8 -*-
+"""The Anthropic formatter module."""
+import base64
+import fnmatch
+from abc import ABC
+from typing import Any
+
+import requests
+from pydantic import Field
+
+from ._formatter_base import FormatterBase
+from .._logging import logger
+from .._utils._common import _json_loads_with_repair
+from ..message import (
+    Msg,
+    TextBlock,
+    ThinkingBlock,
+    HintBlock,
+    DataBlock,
+    ToolCallBlock,
+    ToolResultBlock,
+    URLSource,
+    Base64Source,
+)
+
+
+class _AnthropicFormatterBase(FormatterBase, ABC):
+    """Mixin for formatting Anthropic formatters to avoid duplication between
+    AnthropicChatFormatter and AnthropicMultiAgentFormatter."""
+
+    # pylint: disable=too-many-branches
+    async def _format_messages(
+        self,
+        msgs: list[Msg],
+    ) -> list[dict[str, Any]]:
+        """Format message objects into Anthropic API format.
+
+        Args:
+            msgs (`list[Msg]`):
+                The list of message objects to format.
+
+        Returns:
+            `list[dict[str, Any]]`:
+                The formatted messages as a list of dictionaries.
+
+        .. note:: Anthropic suggests always passing all previous thinking
+         blocks back to the API in subsequent calls to maintain reasoning
+         continuity. For more details, please refer to
+         `Anthropic's documentation
+         <https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking#preserving-thinking-blocks>`_.
+        """
+        self.assert_list_of_msgs(msgs)
+
+        messages: list[dict] = []
+        for msg in msgs:  # pylint: disable=too-many-nested-blocks
+            content_blocks: list = []
+            has_tool_result = False
+
+            for block in msg.get_content_blocks():
+                if (
+                    has_tool_result
+                    and content_blocks
+                    and not isinstance(
+                        block,
+                        ToolResultBlock,
+                    )
+                ):
+                    messages.append(
+                        {"role": "user", "content": content_blocks},
+                    )
+                    content_blocks = []
+                    has_tool_result = False
+
+                if isinstance(block, TextBlock):
+                    # Anthropic rejects empty text blocks with a 400
+                    # ("text blocks must be non-empty"). Empty TextBlocks
+                    # occur after a tool-call-only assistant turn whose
+                    # streamed text is empty, so drop them here.
+                    if block.text:
+                        content_blocks.append(
+                            {"type": "text", "text": block.text},
+                        )
+
+                elif isinstance(block, ThinkingBlock):
+                    # Anthropic rejects thinking blocks without a valid
+                    # signature ("Invalid `signature` in `thinking` block").
+                    # ThinkingBlocks from other providers (OpenAI, DeepSeek,
+                    # ...) carry no signature, so drop them instead of
+                    # forwarding an empty one.
+                    signature = getattr(block, "signature", None)
+                    if signature:
+                        content_blocks.append(
+                            {
+                                "type": "thinking",
+                                "thinking": block.thinking,
+                                "signature": signature,
+                            },
+                        )
+                    else:
+                        logger.debug(
+                            "Dropping ThinkingBlock without signature; "
+                            "Anthropic requires a valid signature.",
+                        )
+
+                elif isinstance(block, HintBlock):
+                    if content_blocks:
+                        role = "user" if has_tool_result else msg.role
+                        messages.append(
+                            {"role": role, "content": content_blocks},
+                        )
+                        content_blocks = []
+                        has_tool_result = False
+
+                    if isinstance(block.hint, str):
+                        messages.append(
+                            {
+                                "role": "user",
+                                "content": [
+                                    {"type": "text", "text": block.hint},
+                                ],
+                            },
+                        )
+                    else:
+                        hint_parts: list[dict] = []
+                        for sub in block.hint:
+                            if isinstance(sub, TextBlock):
+                                hint_parts.append(
+                                    {"type": "text", "text": sub.text},
+                                )
+                            elif isinstance(sub, DataBlock):
+                                formatted_sub = (
+                                    self._format_anthropic_data_block(sub)
+                                )
+                                if formatted_sub:
+                                    hint_parts.append(formatted_sub)
+                        if hint_parts:
+                            messages.append(
+                                {"role": "user", "content": hint_parts},
+                            )
+
+                elif isinstance(block, DataBlock):
+                    formatted_block = self._format_anthropic_data_block(block)
+                    if formatted_block:
+                        content_blocks.append(formatted_block)
+
+                elif isinstance(block, ToolCallBlock):
+                    content_blocks.append(
+                        {
+                            "type": "tool_use",
+                            "id": block.id,
+                            "name": block.name,
+                            # Anthropic API expects input as a dict, not a
+                            # JSON string. Use the repair helper so a
+                            # truncated input (from interrupted streaming or
+                            # context compression) degrades to {} instead of
+                            # raising JSONDecodeError.
+                            "input": _json_loads_with_repair(
+                                block.input or "{}",
+                            ),
+                        },
+                    )
+
+                elif isinstance(block, ToolResultBlock):
+                    # Only flush when we have non-tool-result content
+                    # (i.e. the preceding assistant turn). Once
+                    # `has_tool_result` is True we are already accumulating
+                    # tool_results into the current user message, so we must
+                    # NOT flush on each additional ToolResultBlock — doing so
+                    # would split parallel results into separate user messages
+                    # which strict endpoints (e.g. DeepSeek) reject with 400.
+                    if content_blocks and not has_tool_result:
+                        role = "user" if has_tool_result else msg.role
+                        messages.append(
+                            {"role": role, "content": content_blocks},
+                        )
+                        content_blocks = []
+
+                    tool_result_content: list[dict] = []
+                    output = block.output
+                    if isinstance(output, str):
+                        if output:
+                            tool_result_content.append(
+                                {"type": "text", "text": output},
+                            )
+                    else:
+                        for out_block in output:
+                            if isinstance(out_block, TextBlock):
+                                # Skip empty text — Anthropic rejects
+                                # {"type": "text", "text": ""}.
+                                if out_block.text:
+                                    tool_result_content.append(
+                                        {
+                                            "type": "text",
+                                            "text": out_block.text,
+                                        },
+                                    )
+                            elif isinstance(out_block, DataBlock):
+                                fmt_block = self._format_anthropic_data_block(
+                                    out_block,
+                                )
+                                if fmt_block:
+                                    tool_result_content.append(fmt_block)
+                                else:
+                                    source = out_block.source
+                                    main_type = source.media_type.split("/")[0]
+                                    if isinstance(source, URLSource):
+                                        fallback = (
+                                            f"[{main_type} file returned, "
+                                            f"URL: {source.url}]"
+                                        )
+                                    else:
+                                        fallback = (
+                                            f"[{main_type} file returned, "
+                                            f"type: {source.media_type}]"
+                                        )
+                                    tool_result_content.append(
+                                        {"type": "text", "text": fallback},
+                                    )
+
+                    # Anthropic rejects a tool_result whose content list is
+                    # empty. If every output block was an empty text (or the
+                    # output was an empty string), fall back to a placeholder
+                    # so the tool_result remains valid.
+                    if not tool_result_content:
+                        tool_result_content.append(
+                            {"type": "text", "text": "(empty tool output)"},
+                        )
+
+                    content_blocks.append(
+                        {
+                            "type": "tool_result",
+                            "tool_use_id": block.id,
+                            "content": tool_result_content,
+                        },
+                    )
+                    # Anthropic requires tool_result to be in a "user" message.
+                    has_tool_result = True
+
+                else:
+                    logger.warning(
+                        "Unsupported block type %s in the message, skipped.",
+                        type(block),
+                    )
+
+            if content_blocks:
+                # Anthropic requires `tool_result` blocks to be in a `user`
+                # message regardless of the containing Msg's role.
+                role = "user" if has_tool_result else msg.role
+                messages.append(
+                    {
+                        "role": role,
+                        "content": content_blocks,
+                    },
+                )
+
+        return messages
+
+    def _format_anthropic_data_block(
+        self,
+        block: DataBlock,
+    ) -> dict[str, Any] | None:
+        """Format a DataBlock into Anthropic API format.
+
+        Args:
+            block (`DataBlock`):
+                The data block to format.
+
+        Returns:
+            `dict[str, Any] | None`:
+                The formatted data block, or None if the media type is not
+                supported.
+        """
+        source = block.source
+        media_type = source.media_type
+
+        # Check if media type is supported
+        if not any(
+            fnmatch.fnmatch(media_type, pattern)
+            for pattern in self.supported_input_media_types
+        ):
+            logger.warning(
+                "Media type %s is not supported, skipped.",
+                media_type,
+            )
+            return None
+
+        # Anthropic only supports images
+        if not media_type.startswith("image/"):
+            logger.warning(
+                "Anthropic only supports image data, got %s, skipped.",
+                media_type,
+            )
+            return None
+
+        return self._format_image_source(source)
+
+    @staticmethod
+    def _format_image_source(
+        source: URLSource | Base64Source,
+    ) -> dict[str, Any]:
+        """Format an image source into Anthropic API format.
+
+        Args:
+            source (`URLSource | Base64Source`):
+                The image source to format.
+
+        Returns:
+            `dict[str, Any]`:
+                The formatted image source.
+        """
+        if isinstance(source, Base64Source):
+            return {
+                "type": "image",
+                "source": {
+                    "type": "base64",
+                    "media_type": source.media_type,
+                    "data": source.data,
+                },
+            }
+        elif isinstance(source, URLSource):
+            url = str(source.url)
+            if url.startswith("file://"):
+                # Local file - read and convert to base64
+                file_path = url.removeprefix("file://")
+                with open(file_path, "rb") as f:
+                    data = base64.b64encode(f.read()).decode("utf-8")
+                return {
+                    "type": "image",
+                    "source": {
+                        "type": "base64",
+                        "media_type": source.media_type,
+                        "data": data,
+                    },
+                }
+            else:
+                # Remote URL - download and convert to base64
+                response = requests.get(url, timeout=30)
+                response.raise_for_status()
+                data = base64.b64encode(response.content).decode("utf-8")
+                return {
+                    "type": "image",
+                    "source": {
+                        "type": "base64",
+                        "media_type": source.media_type,
+                        "data": data,
+                    },
+                }
+        else:
+            raise ValueError(f"Unsupported source type: {type(source)}")
+
+
+class AnthropicChatFormatter(_AnthropicFormatterBase):
+    """The Anthropic formatter class for chatbot scenario, where only a user
+    and an agent are involved. We use the `role` field to identify different
+    entities in the conversation.
+    """
+
+    input_types: list[str] = Field(
+        default_factory=lambda: ["text/plain", "image/*"],
+        description=(
+            "The supported input types. "
+            'Defaults to ``["text/plain", "image/*"]``.'
+        ),
+    )
+
+    async def format(
+        self,
+        msgs: list[Msg],
+    ) -> list[dict[str, Any]]:
+        """Format message objects into Anthropic API format.
+
+        Args:
+            msgs (`list[Msg]`):
+                The list of message objects to format.
+
+        Returns:
+            `list[dict[str, Any]]`:
+                The formatted messages as a list of dictionaries.
+
+        .. note:: Anthropic suggests always passing all previous thinking
+         blocks back to the API in subsequent calls to maintain reasoning
+         continuity. For more details, please refer to
+         `Anthropic's documentation
+         <https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking#preserving-thinking-blocks>`_.
+        """
+        return await self._format_messages(msgs)
+
+
+class AnthropicMultiAgentFormatter(_AnthropicFormatterBase):
+    """Anthropic formatter for multi-agent conversations, where more than
+    a user and an agent are involved.
+    """
+
+    conversation_history_prompt: str = Field(
+        default=(
+            "# Conversation History\n"
+            "The content between <history></history> tags contains "
+            "your conversation history\n"
+        ),
+        description="The prompt to use for the conversation history section.",
+    )
+
+    input_types: list[str] = Field(
+        default_factory=lambda: ["text/plain", "image/*"],
+        description=(
+            "The supported input types. "
+            'Defaults to ``["text/plain", "image/*"]``.'
+        ),
+    )
+
+    async def format(self, msgs: list[Msg]) -> list[dict[str, Any]]:
+        """Format input messages into the structure required by the Anthropic
+        API for multi-agent conversations."""
+        self.assert_list_of_msgs(msgs)
+
+        formatted_msgs = []
+        start_index = 0
+        if len(msgs) > 0 and msgs[0].role == "system":
+            formatted_msgs.append(
+                await self._format_system_message(msgs[0]),
+            )
+            start_index = 1
+
+        is_first_agent_message = True
+        async for typ, group in self._group_messages(msgs[start_index:]):
+            match typ:
+                case "tool_sequence":
+                    formatted_msgs.extend(
+                        await self._format_messages(group),
+                    )
+                case "agent_message":
+                    formatted_msgs.extend(
+                        await self._format_agent_message(
+                            group,
+                            is_first_agent_message,
+                        ),
+                    )
+                    is_first_agent_message = False
+
+        return formatted_msgs
+
+    async def _format_agent_message(
+        self,
+        msgs: list[Msg],
+        is_first: bool,
+    ) -> list[dict[str, Any]]:
+        """Format agent messages into conversation history."""
+        conversation_blocks = []
+        accumulated_text = []
+
+        for msg in msgs:
+            agent_name = msg.name or "Agent"
+            agent_text_parts = []
+
+            for block in msg.get_content_blocks():
+                if isinstance(block, TextBlock):
+                    agent_text_parts.append(block.text)
+                elif isinstance(block, DataBlock):
+                    formatted_block = self._format_anthropic_data_block(block)
+                    if formatted_block:
+                        if accumulated_text:
+                            conversation_blocks.append(
+                                {
+                                    "type": "text",
+                                    "text": "\n".join(accumulated_text),
+                                },
+                            )
+                            accumulated_text = []
+                        conversation_blocks.append(formatted_block)
+
+            if agent_text_parts:
+                agent_message = f"{agent_name}: {' '.join(agent_text_parts)}"
+                accumulated_text.append(agent_message)
+
+        if accumulated_text:
+            conversation_blocks.append(
+                {
+                    "type": "text",
+                    "text": "\n".join(accumulated_text),
+                },
+            )
+
+        if conversation_blocks and is_first:
+            if conversation_blocks[0].get("text"):
+                conversation_blocks[0]["text"] = (
+                    self.conversation_history_prompt
+                    + "<history>\n"
+                    + conversation_blocks[0]["text"]
+                )
+            else:
+                conversation_blocks.insert(
+                    0,
+                    {
+                        "type": "text",
+                        "text": self.conversation_history_prompt
+                        + "<history>\n",
+                    },
+                )
+
+            if conversation_blocks[-1].get("text"):
+                conversation_blocks[-1]["text"] += "\n</history>"
+            else:
+                conversation_blocks.append(
+                    {"type": "text", "text": "</history>"},
+                )
+
+        if conversation_blocks:
+            return [
+                {
+                    "role": "user",
+                    "content": conversation_blocks,
+                },
+            ]
+
+        return []
+
+    @staticmethod
+    async def _format_system_message(msg: Msg) -> dict[str, Any]:
+        """Format a system message."""
+        text_parts = []
+        for block in msg.get_content_blocks():
+            if isinstance(block, TextBlock):
+                text_parts.append(block.text)
+
+        return {
+            "role": "system",
+            "content": [
+                {
+                    "type": "text",
+                    "text": "\n".join(text_parts),
+                },
+            ],
+        }
diff --git a/src/agentscope/formatter/_dashscope_formatter.py b/src/agentscope/formatter/_dashscope_formatter.py
new file mode 100644
index 0000000..dcd0a1b
--- /dev/null
+++ b/src/agentscope/formatter/_dashscope_formatter.py
@@ -0,0 +1,563 @@
+# -*- coding: utf-8 -*-
+"""The DashScope formatter module (OpenAI-compatible format)."""
+
+import base64
+from typing import Any
+from fnmatch import fnmatch
+from abc import ABC
+
+from pydantic import Field
+
+from ._formatter_base import FormatterBase
+from .._logging import logger
+from ..message import (
+    Msg,
+    TextBlock,
+    ThinkingBlock,
+    ToolResultBlock,
+    URLSource,
+    DataBlock,
+    ToolCallBlock,
+    Base64Source,
+    HintBlock,
+)
+
+
+class _DashScopeFormatterBase(FormatterBase, ABC):
+    """Base class for DashScope formatters (OpenAI-compatible format),
+    providing shared data block formatting logic."""
+
+    input_types: list[str] = Field(
+        default_factory=lambda: [
+            "text/plain",
+            "image/*",
+            "audio/*",
+            "video/*",
+        ],
+        description=(
+            "The supported input types, aligned with the model card's "
+            "``input_types`` field. Media types (non ``text/plain`` / "
+            "``application/x-thinking`` entries) are used to filter "
+            "``DataBlock``\\s; ``application/x-thinking`` enables passing "
+            "``reasoning_content`` back to the API."
+        ),
+    )
+
+    @property
+    def supported_input_media_types(self) -> list[str]:
+        """Derive supported media types from :attr:`input_types`, excluding
+        ``text/plain`` and ``application/x-thinking``."""
+        return [
+            t
+            for t in self.input_types
+            if t not in ("text/plain", "application/x-thinking")
+        ]
+
+    @property
+    def supports_thinking_input(self) -> bool:
+        """Return ``True`` if ``application/x-thinking`` is listed in
+        :attr:`input_types`, meaning the model accepts ``reasoning_content``
+        in the conversation history."""
+        return "application/x-thinking" in self.input_types
+
+    def _format_dashscope_data_block(
+        self,
+        block: DataBlock,
+    ) -> dict[str, Any] | None:
+        """Format a DataBlock into the OpenAI-compatible format for
+        DashScope API.
+
+        Supports:
+        - Images: ``{"type": "image_url", "image_url": {"url": ...}}``
+        - Videos: ``{"type": "video_url", "video_url": {"url": ...}}``
+        - Audio: ``{"type": "input_audio", "input_audio": {...}}``
+
+        Args:
+            block (`DataBlock`):
+                The DataBlock to format.
+
+        Returns:
+            `dict[str, Any] | None`:
+                A dictionary representing the formatted DataBlock, or ``None``
+                if the media type is unsupported.
+        """
+        if not any(
+            fnmatch(block.source.media_type, pattern)
+            for pattern in self.supported_input_media_types
+        ):
+            logger.warning(
+                "Unsupported media type %s for DashScope API. Supported "
+                "types: %s. This block will be skipped.",
+                block.source.media_type,
+                ", ".join(self.supported_input_media_types),
+            )
+            return None
+
+        main_type = block.source.media_type.split("/")[0]
+
+        if main_type == "image":
+            return self._format_image_source(block.source)
+
+        if main_type == "video":
+            return self._format_video_source(block.source)
+
+        if main_type == "audio":
+            return self._format_audio_source(block.source)
+
+        logger.warning(
+            "Unsupported main media type %s for DashScope API. "
+            "This block will be skipped.",
+            main_type,
+        )
+        return None
+
+    @staticmethod
+    def _format_image_source(
+        source: URLSource | Base64Source,
+    ) -> dict[str, Any]:
+        """Convert an image source to OpenAI-compatible ``image_url`` format.
+
+        Local ``file://`` URLs are read from disk and converted to base64
+        data URIs. Remote URLs are passed through unchanged.
+        """
+        if isinstance(source, Base64Source):
+            url = f"data:{source.media_type};base64,{source.data}"
+        elif isinstance(source, URLSource):
+            url_str = str(source.url)
+            if url_str.startswith("file://"):
+                local_path = url_str.removeprefix("file://")
+                with open(local_path, "rb") as f:
+                    encoded = base64.b64encode(f.read()).decode("utf-8")
+                url = f"data:{source.media_type};base64,{encoded}"
+            else:
+                url = url_str
+        else:
+            raise ValueError(f"Unsupported image source type: {type(source)}")
+
+        return {
+            "type": "image_url",
+            "image_url": {"url": url},
+        }
+
+    @staticmethod
+    def _format_video_source(
+        source: URLSource | Base64Source,
+    ) -> dict[str, Any]:
+        """Convert a video source to DashScope's ``video_url`` format
+        (OpenAI-compatible extension).
+
+        Local ``file://`` URLs are read from disk and converted to base64
+        data URIs. Remote URLs are passed through unchanged.
+        """
+        if isinstance(source, Base64Source):
+            url = f"data:{source.media_type};base64,{source.data}"
+        elif isinstance(source, URLSource):
+            url_str = str(source.url)
+            if url_str.startswith("file://"):
+                local_path = url_str.removeprefix("file://")
+                with open(local_path, "rb") as f:
+                    encoded = base64.b64encode(f.read()).decode("utf-8")
+                url = f"data:{source.media_type};base64,{encoded}"
+            else:
+                url = url_str
+        else:
+            raise ValueError(f"Unsupported video source type: {type(source)}")
+
+        return {
+            "type": "video_url",
+            "video_url": {"url": url},
+        }
+
+    @staticmethod
+    def _format_audio_source(
+        source: URLSource | Base64Source,
+    ) -> dict[str, Any]:
+        """Convert an audio source to DashScope ``input_audio`` format.
+
+        DashScope's compatible API accepts URLs directly in the ``data``
+        field (unlike standard OpenAI which requires base64). Local files
+        are still read and base64-encoded.
+        """
+        if isinstance(source, Base64Source):
+            fmt = source.media_type.split("/")[-1]
+            return {
+                "type": "input_audio",
+                "input_audio": {
+                    "data": source.data,
+                    "format": fmt,
+                },
+            }
+
+        if isinstance(source, URLSource):
+            url_str = str(source.url)
+            fmt = source.media_type.split("/")[-1]
+            if url_str.startswith("file://"):
+                local_path = url_str.removeprefix("file://")
+                with open(local_path, "rb") as f:
+                    data = base64.b64encode(f.read()).decode("utf-8")
+                return {
+                    "type": "input_audio",
+                    "input_audio": {
+                        "data": data,
+                        "format": fmt,
+                    },
+                }
+            else:
+                return {
+                    "type": "input_audio",
+                    "input_audio": {
+                        "data": url_str,
+                        "format": fmt,
+                    },
+                }
+
+        raise ValueError(f"Unsupported audio source type: {type(source)}")
+
+
+class DashScopeChatFormatter(_DashScopeFormatterBase):
+    """The DashScope formatter class for chatbot scenario (OpenAI-compatible
+    format), where only a user and an agent are involved. We use the ``role``
+    field to identify different entities in the conversation.
+
+    This formatter outputs messages in the OpenAI Chat Completions format,
+    with DashScope-specific extensions for video (``video_url``) and
+    thinking (``reasoning_content``).
+    """
+
+    # pylint: disable=too-many-branches
+    async def format(
+        self,
+        msgs: list[Msg],
+    ) -> list[dict[str, Any]]:
+        """Format message objects into DashScope OpenAI-compatible format.
+
+        Args:
+            msgs (`list[Msg]`):
+                The list of message objects to format.
+
+        Returns:
+            `list[dict[str, Any]]`:
+                The formatted messages as a list of dictionaries.
+        """
+        self.assert_list_of_msgs(msgs)
+
+        formatted_msgs: list[dict] = []
+        i = 0
+        while i < len(msgs):
+            msg = msgs[i]
+            content_blocks: list[dict] = []
+            tool_calls = []
+            thinking_parts: list[str] = []
+
+            for block in msg.get_content_blocks():
+                if isinstance(block, TextBlock):
+                    content_blocks.append({"type": "text", "text": block.text})
+
+                elif isinstance(block, DataBlock):
+                    formatted_block = self._format_dashscope_data_block(
+                        block,
+                    )
+                    if formatted_block:
+                        content_blocks.append(formatted_block)
+
+                elif isinstance(block, HintBlock):
+                    if content_blocks or tool_calls or thinking_parts:
+                        msg_openai: dict[str, Any] = {
+                            "role": msg.role,
+                            "content": content_blocks or None,
+                        }
+                        if tool_calls:
+                            msg_openai["tool_calls"] = tool_calls
+                        if thinking_parts:
+                            msg_openai["reasoning_content"] = "\n".join(
+                                thinking_parts,
+                            )
+                        formatted_msgs.append(msg_openai)
+                        content_blocks = []
+                        tool_calls = []
+                        thinking_parts = []
+
+                    if isinstance(block.hint, str):
+                        formatted_msgs.append(
+                            {
+                                "role": "user",
+                                "content": [
+                                    {"type": "text", "text": block.hint},
+                                ],
+                            },
+                        )
+                    else:
+                        hint_parts: list[dict] = []
+                        for sub in block.hint:
+                            if isinstance(sub, TextBlock):
+                                hint_parts.append(
+                                    {"type": "text", "text": sub.text},
+                                )
+                            elif isinstance(sub, DataBlock):
+                                formatted_sub = (
+                                    self._format_dashscope_data_block(
+                                        sub,
+                                    )
+                                )
+                                if formatted_sub:
+                                    hint_parts.append(formatted_sub)
+                        if hint_parts:
+                            formatted_msgs.append(
+                                {"role": "user", "content": hint_parts},
+                            )
+
+                elif isinstance(block, ToolCallBlock):
+                    tool_calls.append(
+                        {
+                            "id": block.id,
+                            "type": "function",
+                            "function": {
+                                "name": block.name,
+                                "arguments": block.input,
+                            },
+                        },
+                    )
+
+                elif isinstance(block, ThinkingBlock):
+                    if self.supports_thinking_input:
+                        thinking_parts.append(block.thinking)
+
+                elif isinstance(block, ToolResultBlock):
+                    if content_blocks or tool_calls or thinking_parts:
+                        msg_flush: dict[str, Any] = {
+                            "role": msg.role,
+                            "content": content_blocks or None,
+                        }
+                        if tool_calls:
+                            msg_flush["tool_calls"] = tool_calls
+                        if thinking_parts:
+                            msg_flush["reasoning_content"] = "\n".join(
+                                thinking_parts,
+                            )
+                        formatted_msgs.append(msg_flush)
+                        content_blocks = []
+                        tool_calls = []
+                        thinking_parts = []
+
+                    (
+                        textual_output,
+                        multimodal_data,
+                    ) = self.convert_tool_result_to_string(block.output)
+
+                    formatted_msgs.append(
+                        {
+                            "role": "tool",
+                            "tool_call_id": block.id,
+                            "content": textual_output,
+                            "name": block.name,
+                        },
+                    )
+
+                    if multimodal_data:
+                        promo_content = []
+                        for item in multimodal_data:
+                            if isinstance(item, TextBlock):
+                                promo_content.append(
+                                    {"type": "text", "text": item.text},
+                                )
+                            elif isinstance(item, DataBlock):
+                                fmt_item = self._format_dashscope_data_block(
+                                    item,
+                                )
+                                if fmt_item is not None:
+                                    promo_content.append(fmt_item)
+                        if promo_content:
+                            formatted_msgs.append(
+                                {
+                                    "role": "user",
+                                    "content": promo_content,
+                                },
+                            )
+
+                else:
+                    logger.warning(
+                        "Unsupported block type %s in the message, skipped.",
+                        type(block),
+                    )
+
+            msg_dashscope: dict[str, Any] = {
+                "role": msg.role,
+                "content": content_blocks or None,
+            }
+
+            if tool_calls:
+                msg_dashscope["tool_calls"] = tool_calls
+
+            if thinking_parts:
+                msg_dashscope["reasoning_content"] = "\n".join(thinking_parts)
+
+            if (
+                msg_dashscope["content"]
+                or msg_dashscope.get("tool_calls")
+                or msg_dashscope.get("reasoning_content")
+            ):
+                formatted_msgs.append(msg_dashscope)
+
+            i += 1
+
+        return formatted_msgs
+
+
+class DashScopeMultiAgentFormatter(_DashScopeFormatterBase):
+    """DashScope formatter for multi-agent conversations (OpenAI-compatible
+    format), where more than a user and an agent are involved.
+
+    .. note:: This formatter will combine previous messages (except tool
+     calls/results) into a history section in the first system message with
+     the conversation history prompt.
+
+    .. note:: For tool calls/results, they will be presented as separate
+     messages as required by the API. Therefore, the tool calls/results
+     messages are expected to be placed at the end of the input messages.
+
+    .. tip:: Telling the assistant's name in the system prompt is very
+     important in multi-agent conversations. So that LLM can know who it
+     is playing as.
+    """
+
+    conversation_history_prompt: str = Field(
+        description="The conversation history prompt.",
+        default=(
+            "# Conversation History\n"
+            "The content between <history></history> tags contains "
+            "your conversation history\n"
+        ),
+    )
+
+    async def format(self, msgs: list[Msg]) -> list[dict]:
+        """Format input messages into the structure required by the DashScope
+        OpenAI-compatible API.
+
+        To support multi-agent conversations, this formatter processes messages
+        as follows:
+
+        - Prepends an instruction before the first conversation history
+         section.
+        - Combines conversation turns into a history section, where each entry
+         is formatted as ``{name}: {content}``.
+        - Wraps the conversation history with ``<history>`` and ``</history>``
+         tags.
+
+        Returns:
+            `list[dict[str, Any]]`:
+                A list of dictionaries formatted for the DashScope API.
+        """
+
+        formatted_msgs = []
+        start_index = 0
+        if len(msgs) > 0 and msgs[0].role == "system":
+            formatted_msgs.append(
+                await self._format_system_message(msgs[0]),
+            )
+            start_index = 1
+
+        is_first_agent_message = True
+        async for typ, group in self._group_messages(msgs[start_index:]):
+            match typ:
+                case "tool_sequence":
+                    formatted_msgs.extend(
+                        await self._format_tool_sequence(group),
+                    )
+                case "agent_message":
+                    formatted_msgs.extend(
+                        await self._format_agent_message(
+                            group,
+                            is_first_agent_message,
+                        ),
+                    )
+                    is_first_agent_message = False
+
+        return formatted_msgs
+
+    async def _format_tool_sequence(
+        self,
+        msgs: list[Msg],
+    ) -> list[dict[str, Any]]:
+        """Given a sequence of tool call/result messages, format them into
+        the required format for the DashScope API."""
+        return await DashScopeChatFormatter(
+            input_types=self.input_types,
+        ).format(msgs)
+
+    async def _format_agent_message(
+        self,
+        msgs: list[Msg],
+        is_first: bool = True,
+    ) -> list[dict[str, Any]]:
+        """Given a sequence of messages without tool calls/results, format
+        them into a user message with conversation history tags."""
+        if is_first:
+            conversation_history_prompt = self.conversation_history_prompt
+        else:
+            conversation_history_prompt = ""
+
+        formatted_msgs: list[dict] = []
+        conversation_blocks: list = []
+        accumulated_text = []
+        media_blocks: list[dict] = []
+
+        for msg in msgs:
+            for block in msg.get_content_blocks():
+                if isinstance(block, TextBlock):
+                    accumulated_text.append(f"{msg.name}: {block.text}")
+
+                elif isinstance(block, DataBlock):
+                    formatted_block = self._format_dashscope_data_block(
+                        block,
+                    )
+                    if formatted_block is not None:
+                        media_blocks.append(formatted_block)
+
+        if accumulated_text:
+            conversation_blocks.append(
+                {"text": "\n".join(accumulated_text)},
+            )
+
+        if conversation_blocks:
+            if conversation_blocks[0].get("text"):
+                conversation_blocks[0]["text"] = (
+                    conversation_history_prompt
+                    + "<history>\n"
+                    + conversation_blocks[0]["text"]
+                )
+            else:
+                conversation_blocks.insert(
+                    0,
+                    {"text": conversation_history_prompt + "<history>\n"},
+                )
+
+            if conversation_blocks[-1].get("text"):
+                conversation_blocks[-1]["text"] += "\n</history>"
+            else:
+                conversation_blocks.append({"text": "</history>"})
+
+        conversation_blocks_text = "\n".join(
+            b.get("text", "") for b in conversation_blocks
+        )
+
+        content_list: list[dict[str, Any]] = []
+        if conversation_blocks_text:
+            content_list.append(
+                {"type": "text", "text": conversation_blocks_text},
+            )
+        content_list.extend(media_blocks)
+
+        if content_list:
+            formatted_msgs.append({"role": "user", "content": content_list})
+
+        return formatted_msgs
+
+    @staticmethod
+    async def _format_system_message(
+        msg: Msg,
+    ) -> dict[str, Any]:
+        """Format system message for DashScope API."""
+        return {
+            "role": "system",
+            "content": msg.get_text_content(),
+        }
diff --git a/src/agentscope/formatter/_deepseek_formatter.py b/src/agentscope/formatter/_deepseek_formatter.py
new file mode 100644
index 0000000..fba0eb0
--- /dev/null
+++ b/src/agentscope/formatter/_deepseek_formatter.py
@@ -0,0 +1,313 @@
+# -*- coding: utf-8 -*-
+"""The DeepSeek formatter module."""
+from typing import Any
+
+from pydantic import Field
+
+from ._formatter_base import FormatterBase
+from .._logging import logger
+from ..message import (
+    Msg,
+    TextBlock,
+    DataBlock,
+    ThinkingBlock,
+    HintBlock,
+    ToolCallBlock,
+    ToolResultBlock,
+)
+
+
+class DeepSeekChatFormatter(FormatterBase):
+    """The DeepSeek formatter class for chatbot scenario, where only a user
+    and an agent are involved. We use the `role` field to identify different
+    entities in the conversation.
+    """
+
+    input_types: list[str] = Field(
+        default_factory=lambda: ["text/plain"],
+        description=(
+            'The supported input types. Defaults to ``["text/plain"]`` '
+            "(DeepSeek does not support multimodal input)."
+        ),
+    )
+
+    async def format(
+        self,
+        msgs: list[Msg],
+    ) -> list[dict[str, Any]]:
+        """Format message objects into DeepSeek API format.
+
+        Args:
+            msgs (`list[Msg]`):
+                The list of message objects to format.
+
+        Returns:
+            `list[dict[str, Any]]`:
+                The formatted messages as a list of dictionaries.
+        """
+        self.assert_list_of_msgs(msgs)
+
+        messages: list[dict] = []
+        for msg in msgs:
+            content_blocks: list = []
+            reasoning_content_blocks: list = []
+            tool_calls = []
+
+            for block in msg.get_content_blocks():
+                if isinstance(block, TextBlock):
+                    content_blocks.append({"type": "text", "text": block.text})
+
+                elif isinstance(block, ThinkingBlock):
+                    reasoning_content_blocks.append(block.thinking)
+
+                elif isinstance(block, HintBlock):
+                    if (
+                        content_blocks
+                        or tool_calls
+                        or reasoning_content_blocks
+                    ):
+                        content_text = "\n".join(
+                            b.get("text", "") for b in content_blocks
+                        )
+                        msg_flush_hint: dict[str, Any] = {
+                            "role": msg.role,
+                            "content": content_text
+                            or (None if tool_calls else ""),
+                        }
+                        if msg.role == "assistant":
+                            msg_flush_hint["reasoning_content"] = (
+                                "\n".join(reasoning_content_blocks)
+                                if reasoning_content_blocks
+                                else ""
+                            )
+                        if tool_calls:
+                            msg_flush_hint["tool_calls"] = tool_calls
+                        messages.append(msg_flush_hint)
+                        content_blocks = []
+                        reasoning_content_blocks = []
+                        tool_calls = []
+
+                    if isinstance(block.hint, str):
+                        messages.append(
+                            {"role": "user", "content": block.hint},
+                        )
+                    else:
+                        hint_text_parts: list[str] = []
+                        for sub in block.hint:
+                            if isinstance(sub, TextBlock):
+                                hint_text_parts.append(sub.text)
+                            elif isinstance(sub, DataBlock):
+                                hint_text_parts.append(
+                                    f"[{sub.source.media_type} attached, "
+                                    "not supported by this provider]",
+                                )
+                        if hint_text_parts:
+                            messages.append(
+                                {
+                                    "role": "user",
+                                    "content": "\n".join(hint_text_parts),
+                                },
+                            )
+
+                elif isinstance(block, ToolCallBlock):
+                    tool_calls.append(
+                        {
+                            "id": block.id,
+                            "type": "function",
+                            "function": {
+                                "name": block.name,
+                                "arguments": block.input,
+                            },
+                        },
+                    )
+
+                elif isinstance(block, ToolResultBlock):
+                    if (
+                        content_blocks
+                        or tool_calls
+                        or reasoning_content_blocks
+                    ):
+                        content_text = "\n".join(
+                            b.get("text", "") for b in content_blocks
+                        )
+                        msg_flush: dict[str, Any] = {
+                            "role": msg.role,
+                            "content": content_text
+                            or (None if tool_calls else ""),
+                        }
+                        if msg.role == "assistant":
+                            msg_flush["reasoning_content"] = (
+                                "\n".join(reasoning_content_blocks)
+                                if reasoning_content_blocks
+                                else ""
+                            )
+                        if tool_calls:
+                            msg_flush["tool_calls"] = tool_calls
+                        messages.append(msg_flush)
+                        content_blocks = []
+                        reasoning_content_blocks = []
+                        tool_calls = []
+
+                    textual_output, _ = self.convert_tool_result_to_string(
+                        block.output,
+                    )
+                    messages.append(
+                        {
+                            "role": "tool",
+                            "tool_call_id": block.id,
+                            "content": textual_output,
+                            "name": block.name,
+                        },
+                    )
+
+                else:
+                    logger.warning(
+                        "Unsupported block type %s in the message, skipped.",
+                        type(block),
+                    )
+
+            content_msg = "\n".join(b.get("text", "") for b in content_blocks)
+
+            msg_deepseek: dict[str, Any] = {
+                "role": msg.role,
+                "content": content_msg or (None if tool_calls else ""),
+            }
+
+            # DeepSeek requires `reasoning_content` to be present on ALL
+            # assistant messages in multi-turn conversations that use thinking
+            # mode.  When switching from a non-thinking model, historical
+            # messages will have no ThinkingBlock, so we always include the
+            # field (as None) for assistant messages to keep the context valid.
+            if msg.role == "assistant":
+                msg_deepseek["reasoning_content"] = (
+                    "\n".join(reasoning_content_blocks)
+                    if reasoning_content_blocks
+                    else ""
+                )
+
+            if tool_calls:
+                msg_deepseek["tool_calls"] = tool_calls
+
+            if (
+                msg_deepseek["content"]
+                or msg_deepseek.get("tool_calls")
+                or reasoning_content_blocks
+            ):
+                messages.append(msg_deepseek)
+
+        return messages
+
+
+class DeepSeekMultiAgentFormatter(FormatterBase):
+    """
+    DeepSeek formatter for multi-agent conversations, where more than
+    a user and an agent are involved.
+    """
+
+    conversation_history_prompt: str = Field(
+        default=(
+            "# Conversation History\n"
+            "The content between <history></history> tags contains "
+            "your conversation history\n"
+        ),
+        description="The prompt to use for the conversation history section.",
+    )
+
+    input_types: list[str] = Field(
+        default_factory=lambda: ["text/plain"],
+        description=(
+            'The supported input types. Defaults to ``["text/plain"]`` '
+            "(DeepSeek does not support multimodal input)."
+        ),
+    )
+
+    async def format(self, msgs: list[Msg]) -> list[dict[str, Any]]:
+        """Format input messages into the structure required by the DeepSeek
+        API for multi-agent conversations."""
+        self.assert_list_of_msgs(msgs)
+
+        formatted_msgs = []
+        start_index = 0
+        if len(msgs) > 0 and msgs[0].role == "system":
+            formatted_msgs.append(
+                await self._format_system_message(msgs[0]),
+            )
+            start_index = 1
+
+        is_first_agent_message = True
+        async for typ, group in self._group_messages(msgs[start_index:]):
+            match typ:
+                case "tool_sequence":
+                    formatted_msgs.extend(
+                        await self._format_tool_sequence(group),
+                    )
+                case "agent_message":
+                    formatted_msgs.extend(
+                        await self._format_agent_message(
+                            group,
+                            is_first_agent_message,
+                        ),
+                    )
+                    is_first_agent_message = False
+
+        return formatted_msgs
+
+    async def _format_tool_sequence(
+        self,
+        msgs: list[Msg],
+    ) -> list[dict[str, Any]]:
+        """Given a sequence of tool call/result messages, format them into
+        the required format for the DeepSeek API."""
+        return await DeepSeekChatFormatter(
+            input_types=self.input_types,
+        ).format(msgs)
+
+    async def _format_agent_message(
+        self,
+        msgs: list[Msg],
+        is_first: bool = True,
+    ) -> list[dict[str, Any]]:
+        """Given a sequence of messages without tool calls/results, format
+        them into the required format for the DeepSeek API."""
+
+        if is_first:
+            conversation_history_prompt = self.conversation_history_prompt
+        else:
+            conversation_history_prompt = ""
+
+        formatted_msgs: list[dict] = []
+        accumulated_text = []
+
+        for msg in msgs:
+            for block in msg.get_content_blocks():
+                if isinstance(block, TextBlock):
+                    accumulated_text.append(f"{msg.name}: {block.text}")
+
+        conversation_blocks_text = ""
+        if accumulated_text:
+            conversation_blocks_text = (
+                conversation_history_prompt
+                + "<history>\n"
+                + "\n".join(accumulated_text)
+                + "\n</history>"
+            )
+
+        if conversation_blocks_text:
+            formatted_msgs.append(
+                {
+                    "role": "user",
+                    "content": conversation_blocks_text,
+                },
+            )
+
+        return formatted_msgs
+
+    @staticmethod
+    async def _format_system_message(
+        msg: Msg,
+    ) -> dict[str, Any]:
+        """Format system message for DeepSeek API."""
+        return {
+            "role": "system",
+            "content": msg.get_text_content(),
+        }
diff --git a/src/agentscope/formatter/_formatter_base.py b/src/agentscope/formatter/_formatter_base.py
new file mode 100644
index 0000000..102451c
--- /dev/null
+++ b/src/agentscope/formatter/_formatter_base.py
@@ -0,0 +1,217 @@
+# -*- coding: utf-8 -*-
+"""The formatter module."""
+import base64
+import mimetypes
+import tempfile
+from abc import abstractmethod
+from fnmatch import fnmatch
+from typing import Any, List, AsyncGenerator
+
+import shortuuid
+from pydantic import BaseModel, Field
+
+from ..message import (
+    Msg,
+    DataBlock,
+    TextBlock,
+    URLSource,
+    Base64Source,
+)
+
+
+class FormatterBase(BaseModel):
+    """The base class for formatters."""
+
+    input_types: list[str] = Field(
+        default_factory=lambda: ["text/plain"],
+        description=(
+            "The supported input types, aligned with the model card's "
+            "``input_types`` field. Entries other than ``text/plain`` and "
+            "``application/x-thinking`` are treated as media-type patterns "
+            "(glob-style, e.g. ``image/*``, ``audio/mp3``) that control which "
+            "``DataBlock``\\s are forwarded to the API."
+        ),
+    )
+    """The supported input types for this formatter, aligned with the model
+    card's ``input_types`` field."""
+
+    @property
+    def supported_input_media_types(self) -> list[str]:
+        """Derive the accepted media-type patterns from :attr:`input_types` by
+        excluding ``text/plain`` and ``application/x-thinking``."""
+        return [
+            t
+            for t in self.input_types
+            if t not in ("text/plain", "application/x-thinking")
+        ]
+
+    @abstractmethod
+    async def format(self, *args: Any, **kwargs: Any) -> list[dict[str, Any]]:
+        """Format the Msg objects to a list of dictionaries that satisfy the
+        API requirements."""
+
+    @staticmethod
+    def assert_list_of_msgs(msgs: list[Msg]) -> None:
+        """Assert that the input is a list of Msg objects.
+
+        Args:
+            msgs (`list[Msg]`):
+                A list of Msg objects to be validated.
+        """
+        if not isinstance(msgs, list):
+            raise TypeError("Input must be a list of Msg objects.")
+
+        for msg in msgs:
+            if not isinstance(msg, Msg):
+                raise TypeError(
+                    f"Expected Msg object, got {type(msg)} instead.",
+                )
+
+    def convert_tool_result_to_string(
+        self,
+        output: str | List[TextBlock | DataBlock],
+    ) -> tuple[str, list[TextBlock | DataBlock]]:
+        """Turn the tool result list into a textual output to be compatible
+        with the LLM API that doesn't support multimodal data in the tool
+        result.
+
+        For URL-based images, the URL is included in the list. For
+        base64-encoded images, the local file path where the image is saved
+        is included in the returned list.
+
+        Args:
+            output (`str | List[TextBlock | DataBlock]`):
+                The output of the tool response, including text and multimodal
+                data like images and audio.
+
+        Returns:
+            `tuple[str, list[TextBlock | DataBlock]]`:
+                A tuple containing the textual representation of the tool
+                result and a list of blocks to be promoted as a user message.
+        """
+
+        if isinstance(output, str):
+            return output, []
+
+        textual_output = []
+        multimodal_data: list = []
+
+        for block in output:
+            if isinstance(block, TextBlock):
+                textual_output.append(block.text)
+
+            elif isinstance(block, DataBlock):
+                main_type = block.source.media_type.split("/")[0]
+
+                if any(
+                    fnmatch(block.source.media_type, _)
+                    for _ in self.supported_input_media_types
+                ):
+                    # If supported, promote the block
+
+                    # Create an identifier for such multimodal data for
+                    # accurate reference (in terms of order, position, etc.)
+                    identifier = shortuuid.uuid()
+
+                    textual_output.append(
+                        f"<system-reminder>A(n) {main_type} file is returned "
+                        f"and will be presented to you with the identifier "
+                        f"[{identifier}].</system-reminder>",
+                    )
+                    multimodal_data.extend(
+                        [
+                            TextBlock(
+                                text=f"- {identifier} ({main_type} file): ",
+                            ),
+                            block,
+                        ],
+                    )
+
+                # For unsupported media types, if it's a URL, include it in
+                # the textual output; if it's base64 data, save it locally
+                # and include the file path in the textual output.
+                # Note if you don't want to save the local file, you should
+                # transform the base64 data in the tool execution hook
+                # rather than changing the formatter.
+                elif isinstance(block.source, URLSource):
+                    textual_output.append(
+                        f"<system-reminder>A(n) {main_type} file is returned "
+                        f"and can be accessed at the URL: {block.source.url}."
+                        f"</system-reminder>",
+                    )
+
+                elif isinstance(block.source, Base64Source):
+                    # Have to save the base64 data locally
+                    extension = mimetypes.guess_extension(
+                        block.source.media_type,
+                    )
+                    with tempfile.NamedTemporaryFile(
+                        suffix=extension,
+                        delete=False,
+                    ) as temp_file:
+                        decoded_data = base64.b64decode(block.source.data)
+                        temp_file.write(decoded_data)
+                        textual_output.append(
+                            f"<system-reminder>A(n) {main_type} file is "
+                            f"returned and saved locally at: {temp_file.name}."
+                            f"</system-reminder>",
+                        )
+
+        # Add system reminder tags if there is multimodal data to be promoted
+        if multimodal_data:
+            multimodal_data = [
+                TextBlock(
+                    text="<system-reminder>The multimodal data and their "
+                    "identifiers are listed as follows:",
+                ),
+                *multimodal_data,
+                TextBlock(
+                    text="</system-reminder>",
+                ),
+            ]
+
+        return "\n".join(textual_output), multimodal_data
+
+    @staticmethod
+    async def _group_messages(msgs: list[Msg]) -> AsyncGenerator:
+        """Group messages into tool sequences and agent messages.
+
+        Args:
+            msgs (`list[Msg]`):
+                A list of Msg objects to be grouped.
+        """
+        group_type = None
+        group = []
+        for msg in msgs:
+            if group_type is None:
+                if msg.get_content_blocks(
+                    "tool_call",
+                ) or msg.get_content_blocks("tool_result"):
+                    group_type = "tool_sequence"
+                else:
+                    group_type = "agent_message"
+                group.append(msg)
+                continue
+
+            if group_type == "tool_sequence":
+                if msg.has_content_blocks(
+                    "tool_call",
+                ) or msg.has_content_blocks("tool_result"):
+                    group.append(msg)
+                else:
+                    yield group_type, group
+                    group = [msg]
+                    group_type = "agent_message"
+
+            elif group_type == "agent_message":
+                if msg.has_content_blocks(
+                    "tool_call",
+                ) or msg.has_content_blocks("tool_result"):
+                    yield group_type, group
+                    group = [msg]
+                    group_type = "tool_sequence"
+                else:
+                    group.append(msg)
+
+        if group_type:
+            yield group_type, group
diff --git a/src/agentscope/formatter/_gemini_formatter.py b/src/agentscope/formatter/_gemini_formatter.py
new file mode 100644
index 0000000..bf77638
--- /dev/null
+++ b/src/agentscope/formatter/_gemini_formatter.py
@@ -0,0 +1,445 @@
+# -*- coding: utf-8 -*-
+"""Google Gemini API formatter in agentscope."""
+import base64
+import fnmatch
+from abc import ABC
+from typing import Any
+
+import requests
+from pydantic import Field
+
+from ._formatter_base import FormatterBase
+from .._logging import logger
+from .._utils._common import _json_loads_with_repair
+from ..message import (
+    Msg,
+    TextBlock,
+    ThinkingBlock,
+    HintBlock,
+    DataBlock,
+    ToolCallBlock,
+    ToolResultBlock,
+    URLSource,
+    Base64Source,
+)
+
+
+class _GeminiFormatterBase(FormatterBase, ABC):
+    """Base class for Gemini formatters, providing shared data block
+    formatting logic."""
+
+    def _format_gemini_data_block(
+        self,
+        block: DataBlock,
+    ) -> dict[str, Any] | None:
+        """Format a DataBlock into Gemini API format.
+
+        Args:
+            block (`DataBlock`):
+                The data block to format.
+
+        Returns:
+            `dict[str, Any] | None`:
+                The formatted data block in Gemini ``inline_data`` format,
+                or None if the media type is not supported.
+        """
+        source = block.source
+        media_type = source.media_type
+
+        # Check if media type is supported
+        if not any(
+            fnmatch.fnmatch(media_type, pattern)
+            for pattern in self.supported_input_media_types
+        ):
+            logger.warning(
+                "Media type %s is not supported, skipped.",
+                media_type,
+            )
+            return None
+
+        return self._format_media_source(source)
+
+    @staticmethod
+    def _format_media_source(
+        source: URLSource | Base64Source,
+    ) -> dict[str, Any]:
+        """Format a media source into Gemini API ``inline_data`` format.
+
+        Args:
+            source (`URLSource | Base64Source`):
+                The media source to format.
+
+        Returns:
+            `dict[str, Any]`:
+                The formatted media source.
+        """
+        if isinstance(source, Base64Source):
+            return {
+                "inline_data": {
+                    "data": source.data,
+                    "mime_type": source.media_type,
+                },
+            }
+        elif isinstance(source, URLSource):
+            url = str(source.url)
+            if url.startswith("file://"):
+                # Local file - read and convert to base64
+                file_path = url.removeprefix("file://")
+                with open(file_path, "rb") as f:
+                    data = base64.b64encode(f.read()).decode("utf-8")
+                return {
+                    "inline_data": {
+                        "data": data,
+                        "mime_type": source.media_type,
+                    },
+                }
+            else:
+                # Remote URL - download and convert to base64
+                response = requests.get(url, timeout=30)
+                response.raise_for_status()
+                data = base64.b64encode(response.content).decode("utf-8")
+                return {
+                    "inline_data": {
+                        "data": data,
+                        "mime_type": source.media_type,
+                    },
+                }
+        else:
+            raise ValueError(f"Unsupported source type: {type(source)}")
+
+
+class GeminiChatFormatter(_GeminiFormatterBase):
+    """The Gemini formatter class for chatbot scenario, where only a user
+    and an agent are involved. We use the `role` field to identify different
+    entities in the conversation.
+    """
+
+    input_types: list[str] = Field(
+        default_factory=lambda: [
+            "text/plain",
+            "image/*",
+            "audio/*",
+            "video/*",
+        ],
+        description=(
+            "The supported input types. "
+            'Defaults to ``["text/plain", "image/*", "audio/*", "video/*"]``.'
+        ),
+    )
+
+    async def format(
+        self,
+        msgs: list[Msg],
+    ) -> list[dict[str, Any]]:
+        """Format message objects into Gemini API required format.
+
+        Args:
+            msgs (`list[Msg]`):
+                The list of message objects to format.
+
+        Returns:
+            `list[dict[str, Any]]`:
+                The formatted messages as a list of dictionaries.
+        """
+        self.assert_list_of_msgs(msgs)
+
+        messages: list[dict] = []
+        i = 0
+        while i < len(msgs):
+            msg = msgs[i]
+            parts: list = []
+
+            for block in msg.get_content_blocks():
+                if isinstance(block, TextBlock):
+                    parts.append({"text": block.text})
+
+                elif isinstance(block, ThinkingBlock):
+                    # Gemini API requires `thought: true` to mark a part as a
+                    # thinking/reasoning block so the model can distinguish it
+                    # from normal text and maintain reasoning continuity.
+                    # Skip empty thinking — Gemini rejects a thought part
+                    # whose text is empty with a 400
+                    # ("contents.parts must not be empty"). Empty thinking
+                    # occurs when a reasoning model returns no summary.
+                    if block.thinking:
+                        parts.append(
+                            {"thought": True, "text": block.thinking},
+                        )
+
+                elif isinstance(block, HintBlock):
+                    if parts:
+                        role = "model" if msg.role == "assistant" else "user"
+                        messages.append({"role": role, "parts": parts})
+                        parts = []
+
+                    if isinstance(block.hint, str):
+                        messages.append(
+                            {
+                                "role": "user",
+                                "parts": [{"text": block.hint}],
+                            },
+                        )
+                    else:
+                        hint_parts: list[dict] = []
+                        for sub in block.hint:
+                            if isinstance(sub, TextBlock):
+                                hint_parts.append({"text": sub.text})
+                            elif isinstance(sub, DataBlock):
+                                formatted_sub = self._format_gemini_data_block(
+                                    sub,
+                                )
+                                if formatted_sub:
+                                    hint_parts.append(formatted_sub)
+                        if hint_parts:
+                            messages.append(
+                                {"role": "user", "parts": hint_parts},
+                            )
+
+                elif isinstance(block, DataBlock):
+                    formatted = self._format_gemini_data_block(block)
+                    if formatted:
+                        parts.append(formatted)
+
+                elif isinstance(block, ToolCallBlock):
+                    parts.append(
+                        {
+                            "function_call": {
+                                "id": block.id,
+                                "name": block.name,
+                                # Use the repair helper so a truncated input
+                                # (from interrupted streaming or context
+                                # compression) degrades to {} instead of
+                                # raising JSONDecodeError.
+                                "args": _json_loads_with_repair(
+                                    block.input or "{}",
+                                ),
+                            },
+                        },
+                    )
+
+                elif isinstance(block, ToolResultBlock):
+                    if parts:
+                        role = "model" if msg.role == "assistant" else "user"
+                        messages.append({"role": role, "parts": parts})
+                        parts = []
+
+                    (
+                        textual_output,
+                        multimodal_data,
+                    ) = self.convert_tool_result_to_string(block.output)
+
+                    messages.append(
+                        {
+                            "role": "user",
+                            "parts": [
+                                {
+                                    "function_response": {
+                                        "id": block.id,
+                                        "name": block.name,
+                                        "response": {
+                                            "output": textual_output,
+                                        },
+                                    },
+                                },
+                            ],
+                        },
+                    )
+
+                    if multimodal_data:
+                        promo_parts = []
+                        for item in multimodal_data:
+                            if isinstance(item, TextBlock):
+                                promo_parts.append({"text": item.text})
+                            elif isinstance(item, DataBlock):
+                                fmt_item = self._format_gemini_data_block(
+                                    item,
+                                )
+                                if fmt_item is not None:
+                                    promo_parts.append(fmt_item)
+                        if promo_parts:
+                            messages.append(
+                                {"role": "user", "parts": promo_parts},
+                            )
+
+                else:
+                    logger.warning(
+                        "Unsupported block type %s in the message, skipped.",
+                        type(block),
+                    )
+
+            # Gemini uses "model" instead of "assistant"
+            role = "model" if msg.role == "assistant" else "user"
+
+            if parts:
+                messages.append(
+                    {
+                        "role": role,
+                        "parts": parts,
+                    },
+                )
+
+            i += 1
+
+        return messages
+
+
+class GeminiMultiAgentFormatter(_GeminiFormatterBase):
+    """The multi-agent formatter for Google Gemini API, where more than a
+    user and an agent are involved.
+
+    .. note:: This formatter will combine previous messages (except tool
+     calls/results) into a history section in the first system message with
+     the conversation history prompt.
+
+    .. note:: For tool calls/results, they will be presented as separate
+     messages as required by the Gemini API. Therefore, the tool calls/
+     results messages are expected to be placed at the end of the input
+     messages.
+
+    .. tip:: Telling the assistant's name in the system prompt is very
+     important in multi-agent conversations. So that LLM can know who it
+     is playing as.
+
+    """
+
+    conversation_history_prompt: str = Field(
+        default=(
+            "# Conversation History\n"
+            "The content between <history></history> tags contains "
+            "your conversation history\n"
+        ),
+        description="The prompt to use for the conversation history section.",
+    )
+
+    input_types: list[str] = Field(
+        default_factory=lambda: [
+            "text/plain",
+            "image/*",
+            "audio/*",
+            "video/*",
+        ],
+        description=(
+            "The supported input types. "
+            'Defaults to ``["text/plain", "image/*", "audio/*", "video/*"]``.'
+        ),
+    )
+
+    async def format(self, msgs: list[Msg]) -> list[dict[str, Any]]:
+        """Format input messages into the structure required by the Gemini
+        API for multi-agent conversations."""
+        self.assert_list_of_msgs(msgs)
+
+        formatted_msgs = []
+        start_index = 0
+        if len(msgs) > 0 and msgs[0].role == "system":
+            formatted_msgs.append(
+                await self._format_system_message(msgs[0]),
+            )
+            start_index = 1
+
+        is_first_agent_message = True
+        async for typ, group in self._group_messages(msgs[start_index:]):
+            match typ:
+                case "tool_sequence":
+                    formatted_msgs.extend(
+                        await self._format_tool_sequence(group),
+                    )
+                case "agent_message":
+                    formatted_msgs.extend(
+                        await self._format_agent_message(
+                            group,
+                            is_first_agent_message,
+                        ),
+                    )
+                    is_first_agent_message = False
+
+        return formatted_msgs
+
+    async def _format_tool_sequence(
+        self,
+        msgs: list[Msg],
+    ) -> list[dict[str, Any]]:
+        """Given a sequence of tool call/result messages, format them into
+        the required format for the Gemini API."""
+        return await GeminiChatFormatter(
+            input_types=self.input_types,
+        ).format(msgs)
+
+    async def _format_agent_message(
+        self,
+        msgs: list[Msg],
+        is_first: bool = True,
+    ) -> list[dict[str, Any]]:
+        """Given a sequence of messages without tool calls/results, format
+        them into the required format for the Gemini API."""
+
+        if is_first:
+            conversation_history_prompt = self.conversation_history_prompt
+        else:
+            conversation_history_prompt = ""
+
+        formatted_msgs: list[dict] = []
+        conversation_parts: list[dict] = []
+        accumulated_text: list[str] = []
+
+        for msg in msgs:
+            for block in msg.get_content_blocks():
+                if isinstance(block, TextBlock):
+                    accumulated_text.append(f"{msg.name}: {block.text}")
+
+                elif isinstance(block, DataBlock):
+                    # Flush accumulated text first
+                    if accumulated_text:
+                        conversation_parts.append(
+                            {"text": "\n".join(accumulated_text)},
+                        )
+                        accumulated_text = []
+
+                    formatted = self._format_gemini_data_block(block)
+                    if formatted:
+                        conversation_parts.append(formatted)
+
+        if accumulated_text:
+            conversation_parts.append(
+                {"text": "\n".join(accumulated_text)},
+            )
+
+        # Add prompt and <history></history> tags around conversation history
+        if conversation_parts:
+            if conversation_parts[0].get("text"):
+                conversation_parts[0]["text"] = (
+                    conversation_history_prompt
+                    + "<history>\n"
+                    + conversation_parts[0]["text"]
+                )
+            else:
+                conversation_parts.insert(
+                    0,
+                    {"text": conversation_history_prompt + "<history>\n"},
+                )
+
+            if conversation_parts[-1].get("text"):
+                conversation_parts[-1]["text"] += "\n</history>"
+            else:
+                conversation_parts.append({"text": "</history>"})
+
+            formatted_msgs.append(
+                {
+                    "role": "user",
+                    "parts": conversation_parts,
+                },
+            )
+
+        return formatted_msgs
+
+    @staticmethod
+    async def _format_system_message(msg: Msg) -> dict[str, Any]:
+        """Format system message for the Gemini API."""
+        return {
+            "role": "user",
+            "parts": [
+                {
+                    "text": msg.get_text_content(),
+                },
+            ],
+        }
diff --git a/src/agentscope/formatter/_moonshot_formatter.py b/src/agentscope/formatter/_moonshot_formatter.py
new file mode 100644
index 0000000..7d05b51
--- /dev/null
+++ b/src/agentscope/formatter/_moonshot_formatter.py
@@ -0,0 +1,417 @@
+# -*- coding: utf-8 -*-
+"""The Moonshot AI formatter for agentscope."""
+import base64
+from typing import Any
+
+import requests
+from pydantic import Field
+
+from ._openai_formatter import _OpenAIFormatterBase
+from .._logging import logger
+from ..message import (
+    Msg,
+    URLSource,
+    Base64Source,
+    TextBlock,
+    DataBlock,
+    ThinkingBlock,
+    HintBlock,
+    ToolCallBlock,
+    ToolResultBlock,
+)
+
+
+def _moonshot_format_image_source(
+    source: URLSource | Base64Source,
+) -> dict[str, Any]:
+    """Convert an image source to Moonshot ``image_url`` format.
+
+    Moonshot's vision API only accepts base64 data URIs or file IDs — raw
+    remote URLs are rejected. This helper downloads remote ``http(s)://``
+    URLs and converts them to base64 data URIs, while ``file://`` URLs and
+    ``Base64Source`` go through the same conversion as the OpenAI base.
+    """
+    if isinstance(source, Base64Source):
+        url = f"data:{source.media_type};base64,{source.data}"
+
+    elif isinstance(source, URLSource):
+        url_str = str(source.url)
+        if url_str.startswith("file://"):
+            local_path = url_str.removeprefix("file://")
+            with open(local_path, "rb") as f:
+                encoded = base64.b64encode(f.read()).decode("utf-8")
+            url = f"data:{source.media_type};base64,{encoded}"
+        else:
+            response = requests.get(url_str, timeout=30)
+            response.raise_for_status()
+            encoded = base64.b64encode(response.content).decode("utf-8")
+            url = f"data:{source.media_type};base64,{encoded}"
+
+    else:
+        raise ValueError(f"Unsupported image source type: {type(source)}")
+
+    return {
+        "type": "image_url",
+        "image_url": {"url": url},
+    }
+
+
+class MoonshotChatFormatter(_OpenAIFormatterBase):
+    """The Moonshot AI formatter for chatbot scenario.
+
+    Moonshot's API is OpenAI-compatible, but thinking models (``kimi-k2.6``,
+    ``kimi-k2-thinking``) return a ``reasoning_content`` field alongside
+    ``content`` in assistant messages.  This formatter preserves that field
+    when re-sending assistant messages back to the API so that the
+    *Preserved Thinking* feature works correctly in multi-turn conversations.
+    """
+
+    input_types: list[str] = Field(
+        default_factory=lambda: ["text/plain", "image/*", "audio/*"],
+        description=(
+            "The supported input types. "
+            'Defaults to ``["text/plain", "image/*", "audio/*"]``.'
+        ),
+    )
+
+    def _format_image_source(
+        self,
+        source: URLSource | Base64Source,
+    ) -> dict[str, Any]:
+        return _moonshot_format_image_source(source)
+
+    # pylint: disable=too-many-branches
+    async def format(
+        self,
+        msgs: list[Msg],
+    ) -> list[dict[str, Any]]:
+        """Format messages into the Moonshot / OpenAI-compatible API format.
+
+        Behaves identically to :class:`OpenAIChatFormatter` except that
+        :class:`ThinkingBlock` content is placed into the ``reasoning_content``
+        field of the assistant message dict (required for Preserved Thinking).
+
+        Args:
+            msgs (`list[Msg]`):
+                The list of message objects to format.
+
+        Returns:
+            `list[dict[str, Any]]`:
+                The formatted messages as a list of dictionaries.
+        """
+        self.assert_list_of_msgs(msgs)
+
+        messages: list[dict] = []
+        i = 0
+        while i < len(msgs):
+            msg = msgs[i]
+            content_blocks: list[dict] = []
+            reasoning_parts: list[str] = []
+            tool_calls: list[dict] = []
+
+            for block in msg.get_content_blocks():
+                if isinstance(block, ThinkingBlock):
+                    # Preserve reasoning_content for multi-turn
+                    # Preserved Thinking (kimi-k2.6 / kimi-k2-thinking)
+                    reasoning_parts.append(block.thinking)
+
+                elif isinstance(block, TextBlock):
+                    content_blocks.append({"type": "text", "text": block.text})
+
+                elif isinstance(block, DataBlock):
+                    formatted = self._format_openai_data_block(block)
+                    if formatted is not None:
+                        content_blocks.append(formatted)
+
+                elif isinstance(block, HintBlock):
+                    if content_blocks or tool_calls or reasoning_parts:
+                        msg_moonshot = {
+                            "role": msg.role,
+                            "name": msg.name,
+                            "content": content_blocks or None,
+                        }
+                        if msg.role == "assistant":
+                            msg_moonshot["reasoning_content"] = (
+                                "\n".join(reasoning_parts)
+                                if reasoning_parts
+                                else ""
+                            )
+                        if tool_calls:
+                            msg_moonshot["tool_calls"] = tool_calls
+                        messages.append(msg_moonshot)
+                        content_blocks = []
+                        reasoning_parts = []
+                        tool_calls = []
+
+                    if isinstance(block.hint, str):
+                        messages.append(
+                            {
+                                "role": "user",
+                                "content": [
+                                    {"type": "text", "text": block.hint},
+                                ],
+                            },
+                        )
+                    else:
+                        hint_parts: list[dict] = []
+                        for sub in block.hint:
+                            if isinstance(sub, TextBlock):
+                                hint_parts.append(
+                                    {"type": "text", "text": sub.text},
+                                )
+                            elif isinstance(sub, DataBlock):
+                                formatted_sub = self._format_openai_data_block(
+                                    sub,
+                                )
+                                if formatted_sub is not None:
+                                    hint_parts.append(formatted_sub)
+                        if hint_parts:
+                            messages.append(
+                                {"role": "user", "content": hint_parts},
+                            )
+
+                elif isinstance(block, ToolCallBlock):
+                    tool_calls.append(
+                        {
+                            "id": block.id,
+                            "type": "function",
+                            "function": {
+                                "name": block.name,
+                                "arguments": block.input,
+                            },
+                        },
+                    )
+
+                elif isinstance(block, ToolResultBlock):
+                    if content_blocks or tool_calls or reasoning_parts:
+                        msg_flush = {
+                            "role": msg.role,
+                            "name": msg.name,
+                            "content": content_blocks or None,
+                        }
+                        if msg.role == "assistant":
+                            msg_flush["reasoning_content"] = (
+                                "\n".join(reasoning_parts)
+                                if reasoning_parts
+                                else ""
+                            )
+                        if tool_calls:
+                            msg_flush["tool_calls"] = tool_calls
+                        messages.append(msg_flush)
+                        content_blocks = []
+                        reasoning_parts = []
+                        tool_calls = []
+
+                    (
+                        textual_output,
+                        multimodal_data,
+                    ) = self.convert_tool_result_to_string(block.output)
+
+                    messages.append(
+                        {
+                            "role": "tool",
+                            "tool_call_id": block.id,
+                            "content": textual_output,
+                            "name": block.name,
+                        },
+                    )
+
+                    if multimodal_data:
+                        promo_content = []
+                        for item in multimodal_data:
+                            if isinstance(item, TextBlock):
+                                promo_content.append(
+                                    {"type": "text", "text": item.text},
+                                )
+                            elif isinstance(item, DataBlock):
+                                fmt_item = self._format_openai_data_block(
+                                    item,
+                                )
+                                if fmt_item is not None:
+                                    promo_content.append(fmt_item)
+                        if promo_content:
+                            messages.append(
+                                {
+                                    "role": "user",
+                                    "name": "system-reminder",
+                                    "content": promo_content,
+                                },
+                            )
+
+                else:
+                    logger.warning(
+                        "Unsupported block type %s in the message, skipped.",
+                        type(block),
+                    )
+
+            msg_moonshot = {
+                "role": msg.role,
+                "name": msg.name,
+                "content": content_blocks or None,
+            }
+
+            # Moonshot's Preserved Thinking requires `reasoning_content` on ALL
+            # assistant messages in multi-turn conversations (None when no
+            # thinking took place), so that the model can continue its chain
+            # of thought correctly.
+            if msg.role == "assistant":
+                msg_moonshot["reasoning_content"] = (
+                    "\n".join(reasoning_parts) if reasoning_parts else ""
+                )
+
+            if tool_calls:
+                msg_moonshot["tool_calls"] = tool_calls
+
+            if (
+                msg_moonshot["content"]
+                or msg_moonshot.get("tool_calls")
+                or reasoning_parts
+            ):
+                messages.append(msg_moonshot)
+
+            i += 1
+
+        return messages
+
+
+class MoonshotMultiAgentFormatter(_OpenAIFormatterBase):
+    """Formatter for the Moonshot AI API in multi-agent conversations.
+
+    Moonshot's API is OpenAI-compatible, so the multi-agent history collapsing
+    strategy is the same as :class:`OpenAIMultiAgentFormatter`.  Tool
+    sequences are delegated to :class:`MoonshotChatFormatter` so that
+    ``reasoning_content`` is preserved correctly for multi-turn
+    *Preserved Thinking* conversations.
+
+    .. note:: Telling the assistant's name in the system prompt is important
+        in multi-agent conversations so that the model knows which role it
+        is playing.
+    """
+
+    conversation_history_prompt: str = Field(
+        default=(
+            "# Conversation History\n"
+            "The content between <history></history> tags contains "
+            "your conversation history\n"
+        ),
+        description="The prompt to use for the conversation history section.",
+    )
+
+    input_types: list[str] = Field(
+        default_factory=lambda: ["text/plain", "image/*", "audio/*"],
+        description=(
+            "The supported input types. "
+            'Defaults to ``["text/plain", "image/*", "audio/*"]``.'
+        ),
+    )
+
+    def _format_image_source(
+        self,
+        source: URLSource | Base64Source,
+    ) -> dict[str, Any]:
+        return _moonshot_format_image_source(source)
+
+    async def format(self, msgs: list[Msg]) -> list[dict[str, Any]]:
+        """Format input messages into the Moonshot AI API format for
+        multi-agent conversations.
+
+        Non-tool messages from all agents are collapsed into a single user
+        message with ``<history></history>`` tags.  Tool call / result
+        sequences are delegated to :class:`MoonshotChatFormatter`.
+
+        Args:
+            msgs (`list[Msg]`):
+                The list of message objects to format.
+
+        Returns:
+            `list[dict[str, Any]]`:
+                The formatted messages as a list of dictionaries.
+        """
+        self.assert_list_of_msgs(msgs)
+
+        formatted_msgs: list[dict] = []
+        start_index = 0
+        if msgs and msgs[0].role == "system":
+            formatted_msgs.append(
+                await self._format_system_message(msgs[0]),
+            )
+            start_index = 1
+
+        is_first_agent_message = True
+        async for typ, group in self._group_messages(msgs[start_index:]):
+            if typ == "tool_sequence":
+                formatted_msgs.extend(
+                    await MoonshotChatFormatter(
+                        input_types=self.input_types,
+                    ).format(group),
+                )
+            elif typ == "agent_message":
+                formatted_msgs.extend(
+                    await self._format_agent_message(
+                        group,
+                        is_first_agent_message,
+                    ),
+                )
+                is_first_agent_message = False
+
+        return formatted_msgs
+
+    async def _format_tool_sequence(
+        self,
+        msgs: list[Msg],
+    ) -> list[dict[str, Any]]:
+        """Format a sequence of tool-related messages using
+        MoonshotChatFormatter."""
+        return await MoonshotChatFormatter(
+            input_types=self.input_types,
+        ).format(msgs)
+
+    async def _format_agent_message(
+        self,
+        msgs: list[Msg],
+        is_first: bool = True,
+    ) -> list[dict[str, Any]]:
+        """Collapse agent messages into a ``<history>`` user message."""
+        if is_first:
+            conversation_history_prompt = self.conversation_history_prompt
+        else:
+            conversation_history_prompt = ""
+
+        accumulated_text: list[str] = []
+        media_blocks: list[dict] = []
+
+        for msg in msgs:
+            for block in msg.get_content_blocks():
+                if isinstance(block, TextBlock):
+                    accumulated_text.append(f"{msg.name}: {block.text}")
+                elif isinstance(block, DataBlock):
+                    formatted = self._format_openai_data_block(block)
+                    if formatted is not None:
+                        media_blocks.append(formatted)
+
+        if not accumulated_text and not media_blocks:
+            return []
+
+        history_text = "\n".join(accumulated_text)
+        if history_text:
+            history_text = (
+                conversation_history_prompt
+                + "<history>\n"
+                + history_text
+                + "\n</history>"
+            )
+
+        content_list: list[dict[str, Any]] = []
+        if history_text:
+            content_list.append({"type": "text", "text": history_text})
+        content_list.extend(media_blocks)
+
+        return [{"role": "user", "content": content_list}]
+
+    @staticmethod
+    async def _format_system_message(msg: Msg) -> dict[str, Any]:
+        """Format a system message for the Moonshot AI API."""
+        return {
+            "role": "system",
+            "content": msg.get_text_content(),
+        }
diff --git a/src/agentscope/formatter/_ollama_formatter.py b/src/agentscope/formatter/_ollama_formatter.py
new file mode 100644
index 0000000..afee357
--- /dev/null
+++ b/src/agentscope/formatter/_ollama_formatter.py
@@ -0,0 +1,452 @@
+# -*- coding: utf-8 -*-
+"""The Ollama formatter module."""
+import base64
+import fnmatch
+from abc import ABC
+from typing import Any
+
+import requests
+from pydantic import Field
+
+from ._formatter_base import FormatterBase
+from .._logging import logger
+from .._utils._common import _json_loads_with_repair
+from ..message import (
+    Msg,
+    TextBlock,
+    HintBlock,
+    DataBlock,
+    ToolCallBlock,
+    ToolResultBlock,
+    ThinkingBlock,
+    URLSource,
+    Base64Source,
+)
+
+
+class _OllamaFormatterBase(FormatterBase, ABC):
+    """Base class for Ollama formatters, providing shared data block
+    formatting logic."""
+
+    def _format_ollama_data_block(
+        self,
+        block: DataBlock,
+    ) -> str | None:
+        """Format a DataBlock into Ollama API format (base64 string).
+
+        Args:
+            block (`DataBlock`):
+                The data block to format.
+
+        Returns:
+            `str | None`:
+                Base64 encoded data as a string, or None if the media type
+                is not supported.
+        """
+        source = block.source
+        media_type = source.media_type
+
+        # Check if media type is supported
+        if not any(
+            fnmatch.fnmatch(media_type, pattern)
+            for pattern in self.supported_input_media_types
+        ):
+            logger.warning(
+                "Media type %s is not supported, skipped.",
+                media_type,
+            )
+            return None
+
+        # Ollama only supports images
+        if not media_type.startswith("image/"):
+            logger.warning(
+                "Ollama only supports image data, got %s, skipped.",
+                media_type,
+            )
+            return None
+
+        return self._format_image_source(source)
+
+    @staticmethod
+    def _format_image_source(source: URLSource | Base64Source) -> str:
+        """Format an image source into Ollama API format (base64 string).
+
+        Args:
+            source (`URLSource | Base64Source`):
+                The image source to format.
+
+        Returns:
+            `str`:
+                Base64 encoded image data.
+        """
+        if isinstance(source, Base64Source):
+            return source.data
+        elif isinstance(source, URLSource):
+            url = str(source.url)
+            if url.startswith("file://"):
+                # Local file - read and convert to base64
+                file_path = url.removeprefix("file://")
+                with open(file_path, "rb") as f:
+                    data = base64.b64encode(f.read()).decode("utf-8")
+                return data
+            else:
+                # Remote URL - download and convert to base64
+                response = requests.get(url, timeout=30)
+                response.raise_for_status()
+                data = base64.b64encode(response.content).decode("utf-8")
+                return data
+        else:
+            raise ValueError(f"Unsupported source type: {type(source)}")
+
+
+class OllamaChatFormatter(_OllamaFormatterBase):
+    """The Ollama formatter class for chatbot scenario, where only a user
+    and an agent are involved. We use the `role` field to identify different
+    participants in the conversation.
+    """
+
+    input_types: list[str] = Field(
+        default_factory=lambda: ["text/plain", "image/*"],
+        description=(
+            "The supported input types. "
+            'Defaults to ``["text/plain", "image/*"]``.'
+        ),
+    )
+
+    async def format(
+        self,
+        msgs: list[Msg],
+    ) -> list[dict[str, Any]]:
+        """Format message objects into Ollama API format.
+
+        Args:
+            msgs (`list[Msg]`):
+                The list of message objects to format.
+
+        Returns:
+            `list[dict[str, Any]]`:
+                The formatted messages as a list of dictionaries.
+        """
+        self.assert_list_of_msgs(msgs)
+
+        messages: list[dict] = []
+        for msg in msgs:
+            content_parts = []
+            images = []
+
+            for block in msg.get_content_blocks():
+                if isinstance(block, TextBlock):
+                    content_parts.append(block.text)
+
+                elif isinstance(block, HintBlock):
+                    if content_parts or images:
+                        msg_flush = {
+                            "role": msg.role,
+                            "content": "\n".join(content_parts),
+                        }
+                        if images:
+                            msg_flush["images"] = images
+                        messages.append(msg_flush)
+                        content_parts = []
+                        images = []
+
+                    if isinstance(block.hint, str):
+                        messages.append(
+                            {"role": "user", "content": block.hint},
+                        )
+                    else:
+                        hint_text_parts: list[str] = []
+                        hint_images: list[str] = []
+                        for sub in block.hint:
+                            if isinstance(sub, TextBlock):
+                                hint_text_parts.append(sub.text)
+                            elif isinstance(sub, DataBlock):
+                                formatted_sub = self._format_ollama_data_block(
+                                    sub,
+                                )
+                                if formatted_sub:
+                                    hint_images.append(formatted_sub)
+                        if hint_text_parts or hint_images:
+                            hint_msg: dict[str, Any] = {
+                                "role": "user",
+                                "content": "\n".join(hint_text_parts),
+                            }
+                            if hint_images:
+                                hint_msg["images"] = hint_images
+                            messages.append(hint_msg)
+
+                elif isinstance(block, DataBlock):
+                    formatted_image = self._format_ollama_data_block(block)
+                    if formatted_image:
+                        images.append(formatted_image)
+
+                elif isinstance(block, ThinkingBlock):
+                    # Ollama does not use reasoning content in the context
+                    # — skip thinking blocks silently.
+                    pass
+
+                elif isinstance(block, ToolCallBlock):
+                    messages.append(
+                        {
+                            "role": msg.role,
+                            "content": "\n".join(content_parts)
+                            if content_parts
+                            else "",
+                            "tool_calls": [
+                                {
+                                    "function": {
+                                        "name": block.name,
+                                        # Ollama SDK expects a dict, not a
+                                        # JSON string. Use the repair helper
+                                        # so a truncated input (from
+                                        # interrupted streaming or context
+                                        # compression) degrades to {} instead
+                                        # of raising JSONDecodeError.
+                                        "arguments": _json_loads_with_repair(
+                                            block.input or "{}",
+                                        ),
+                                    },
+                                },
+                            ],
+                        },
+                    )
+                    content_parts = []
+                    images = []
+
+                elif isinstance(block, ToolResultBlock):
+                    if content_parts or images:
+                        msg_flush = {
+                            "role": msg.role,
+                            "content": "\n".join(content_parts),
+                        }
+                        if images:
+                            msg_flush["images"] = images
+                        messages.append(msg_flush)
+                        content_parts = []
+                        images = []
+
+                    (
+                        textual_output,
+                        multimodal_data,
+                    ) = self.convert_tool_result_to_string(block.output)
+
+                    # Ollama expects tool results as a separate "tool" role
+                    # message, regardless of the containing Msg's role.
+                    # Per the Ollama tool-calling spec, the "tool" message
+                    # must carry a "tool_name" field (not the OpenAI-style
+                    # "tool_call_id") so the model can correlate the result
+                    # with the function that produced it — see
+                    # https://docs.ollama.com/capabilities/tool-calling
+                    messages.append(
+                        {
+                            "role": "tool",
+                            "tool_name": block.name,
+                            "content": textual_output,
+                        },
+                    )
+
+                    # If there's multimodal data, append an extra user message.
+                    if multimodal_data:
+                        user_images = []
+                        user_content_parts = []
+                        for data_block in multimodal_data:
+                            if isinstance(data_block, DataBlock):
+                                formatted_image = (
+                                    self._format_ollama_data_block(
+                                        data_block,
+                                    )
+                                )
+                                if formatted_image:
+                                    user_images.append(formatted_image)
+                            elif isinstance(data_block, TextBlock):
+                                user_content_parts.append(data_block.text)
+
+                        user_msg = {
+                            "role": "user",
+                            "content": "\n".join(user_content_parts)
+                            if user_content_parts
+                            else textual_output,
+                        }
+                        if user_images:
+                            user_msg["images"] = user_images
+                        messages.append(user_msg)
+
+                else:
+                    logger.warning(
+                        "Unsupported block type %s in the message, skipped.",
+                        type(block),
+                    )
+
+            # Add the message if there's content or images
+            if content_parts or images:
+                msg_ollama: dict[str, Any] = {
+                    "role": msg.role,
+                    "content": "\n".join(content_parts)
+                    if content_parts
+                    else "",
+                }
+                if images:
+                    msg_ollama["images"] = images
+                messages.append(msg_ollama)
+
+        return messages
+
+
+class OllamaMultiAgentFormatter(_OllamaFormatterBase):
+    """
+    Ollama formatter for multi-agent conversations, where more than
+    a user and an agent are involved.
+    """
+
+    conversation_history_prompt: str = Field(
+        default=(
+            "# Conversation History\n"
+            "The content between <history></history> tags contains "
+            "your conversation history\n"
+        ),
+        description="The prompt to use for the conversation history section.",
+    )
+
+    input_types: list[str] = Field(
+        default_factory=lambda: ["text/plain", "image/*"],
+        description=(
+            "The supported input types. "
+            'Defaults to ``["text/plain", "image/*"]``.'
+        ),
+    )
+
+    async def format(self, msgs: list[Msg]) -> list[dict[str, Any]]:
+        """Format input messages into the structure required by the Ollama
+        API for multi-agent conversations."""
+        self.assert_list_of_msgs(msgs)
+
+        formatted_msgs = []
+        start_index = 0
+        if len(msgs) > 0 and msgs[0].role == "system":
+            formatted_msgs.append(
+                await self._format_system_message(msgs[0]),
+            )
+            start_index = 1
+
+        is_first_agent_message = True
+        async for typ, group in self._group_messages(msgs[start_index:]):
+            match typ:
+                case "tool_sequence":
+                    formatted_msgs.extend(
+                        await self._format_tool_sequence(group),
+                    )
+                case "agent_message":
+                    formatted_msgs.extend(
+                        await self._format_agent_message(
+                            group,
+                            is_first_agent_message,
+                        ),
+                    )
+                    is_first_agent_message = False
+
+        return formatted_msgs
+
+    async def _format_tool_sequence(
+        self,
+        msgs: list[Msg],
+    ) -> list[dict[str, Any]]:
+        """Format a sequence of tool-related messages."""
+        return await OllamaChatFormatter(
+            input_types=self.input_types,
+        ).format(msgs)
+
+    async def _format_agent_message(
+        self,
+        msgs: list[Msg],
+        is_first: bool,
+    ) -> list[dict[str, Any]]:
+        """Format agent messages into conversation history format."""
+        conversation_blocks: list[dict] = []
+        accumulated_text: list[str] = []
+        images: list[str] = []
+
+        for msg in msgs:
+            msg_text_parts = []
+            if msg.name:
+                msg_text_parts.append(f"{msg.name}:")
+
+            for block in msg.get_content_blocks():
+                if isinstance(block, TextBlock):
+                    msg_text_parts.append(block.text)
+                elif isinstance(block, DataBlock):
+                    formatted_image = self._format_ollama_data_block(block)
+                    if formatted_image:
+                        images.append(formatted_image)
+                elif isinstance(block, (HintBlock, ThinkingBlock)):
+                    pass  # Ollama does not use hint/thinking blocks
+                else:
+                    logger.warning(
+                        "Unsupported block type %s in agent message, skipped.",
+                        type(block),
+                    )
+
+            if msg_text_parts:
+                accumulated_text.append("\n".join(msg_text_parts))
+
+        if accumulated_text:
+            conversation_blocks.append(
+                {"text": "\n".join(accumulated_text)},
+            )
+
+        if conversation_blocks and is_first:
+            if conversation_blocks[0].get("text"):
+                conversation_blocks[0]["text"] = (
+                    self.conversation_history_prompt
+                    + "<history>\n"
+                    + conversation_blocks[0]["text"]
+                )
+
+            else:
+                conversation_blocks.insert(
+                    0,
+                    {
+                        "text": self.conversation_history_prompt
+                        + "<history>\n",
+                    },
+                )
+
+            if conversation_blocks[-1].get("text"):
+                conversation_blocks[-1]["text"] += "\n</history>"
+
+            else:
+                conversation_blocks.append({"text": "</history>"})
+
+        conversation_blocks_text = "\n".join(
+            conversation_block.get("text", "")
+            for conversation_block in conversation_blocks
+        )
+
+        user_message: dict[str, Any] = {
+            "role": "user",
+            "content": conversation_blocks_text,
+        }
+        if images:
+            user_message["images"] = images
+
+        formatted_msgs = []
+        if conversation_blocks:
+            formatted_msgs.append(user_message)
+
+        return formatted_msgs
+
+    @staticmethod
+    async def _format_system_message(msg: Msg) -> dict[str, Any]:
+        """Format a system message."""
+        text_parts = []
+        for block in msg.get_content_blocks():
+            if isinstance(block, TextBlock):
+                text_parts.append(block.text)
+            else:
+                logger.warning(
+                    "Unsupported block type %s in system message, skipped.",
+                    type(block),
+                )
+        return {
+            "role": "system",
+            "content": "\n".join(text_parts),
+        }
diff --git a/src/agentscope/formatter/_openai_formatter.py b/src/agentscope/formatter/_openai_formatter.py
new file mode 100644
index 0000000..245fc62
--- /dev/null
+++ b/src/agentscope/formatter/_openai_formatter.py
@@ -0,0 +1,513 @@
+# -*- coding: utf-8 -*-
+"""The OpenAI formatter for agentscope."""
+import base64
+from abc import ABC
+from fnmatch import fnmatch
+from typing import Any
+from urllib.parse import urlparse
+
+import requests
+from pydantic import Field
+
+from ._formatter_base import FormatterBase
+from .._logging import logger
+from ..message import (
+    Msg,
+    URLSource,
+    TextBlock,
+    DataBlock,
+    Base64Source,
+    ToolCallBlock,
+    ToolResultBlock,
+    HintBlock,
+    ThinkingBlock,
+)
+
+
+class _OpenAIFormatterBase(FormatterBase, ABC):
+    """Base class for OpenAI formatters, providing shared data block
+    formatting logic."""
+
+    def _format_openai_data_block(
+        self,
+        block: DataBlock,
+    ) -> dict[str, Any] | None:
+        """Format a DataBlock into the required format for OpenAI API.
+
+        For image blocks, URLs are returned as-is (or converted to base64 for
+        local ``file://`` paths). For audio blocks, data is always converted
+        to base64 as required by the OpenAI input_audio format.
+
+        Args:
+            block (`DataBlock`):
+                The DataBlock to format.
+
+        Returns:
+            `dict[str, Any] | None`:
+                A dictionary in OpenAI API format, or ``None`` if the block
+                should be skipped.
+        """
+        if not any(
+            fnmatch(block.source.media_type, pattern)
+            for pattern in self.supported_input_media_types
+        ):
+            logger.warning(
+                "Unsupported media type %s for OpenAI API. "
+                "Supported types: %s. This block will be skipped.",
+                block.source.media_type,
+                ", ".join(self.supported_input_media_types),
+            )
+            return None
+
+        main_type = block.source.media_type.split("/")[0]
+
+        if main_type == "image":
+            return self._format_image_source(block.source)
+
+        if main_type == "audio":
+            return self._format_audio_source(block.source)
+
+        logger.warning(
+            "Unsupported main media type %s for OpenAI API. "
+            "This block will be skipped.",
+            main_type,
+        )
+        return None
+
+    def _format_image_source(
+        self,
+        source: URLSource | Base64Source,
+    ) -> dict[str, Any]:
+        """Convert an image source to OpenAI image_url format.
+
+        Local ``file://`` URLs are read from disk and converted to base64
+        data URIs. Remote URLs are passed through unchanged. Subclasses may
+        override this to apply provider-specific handling (e.g. forcing
+        remote URLs to be downloaded and base64-encoded for APIs that don't
+        accept raw HTTPS URLs).
+
+        Args:
+            source (`URLSource | Base64Source`):
+                The image source to convert.
+
+        Returns:
+            `dict[str, Any]`:
+                A dictionary with ``"type": "image_url"`` in OpenAI format.
+        """
+        if isinstance(source, Base64Source):
+            url = f"data:{source.media_type};base64,{source.data}"
+
+        elif isinstance(source, URLSource):
+            url_str = str(source.url)
+            if url_str.startswith("file://"):
+                # Local file — read and encode as base64 data URI
+                local_path = url_str.removeprefix("file://")
+                with open(local_path, "rb") as f:
+                    encoded = base64.b64encode(f.read()).decode("utf-8")
+                url = f"data:{source.media_type};base64,{encoded}"
+            else:
+                # Remote URL — pass through as-is
+                url = url_str
+
+        else:
+            raise ValueError(f"Unsupported image source type: {type(source)}")
+
+        return {
+            "type": "image_url",
+            "image_url": {"url": url},
+        }
+
+    @staticmethod
+    def _format_audio_source(
+        source: URLSource | Base64Source,
+    ) -> dict[str, Any]:
+        """Convert an audio source to OpenAI input_audio format.
+
+        Local ``file://`` URLs are read from disk. Remote URLs are downloaded.
+        Only ``wav`` and ``mp3`` formats are supported by the OpenAI API.
+
+        Args:
+            source (`URLSource | Base64Source`):
+                The audio source to convert.
+
+        Returns:
+            `dict[str, Any]`:
+                A dictionary with ``"type": "input_audio"`` in OpenAI format.
+        """
+        if isinstance(source, Base64Source):
+            media_type = source.media_type
+            if media_type not in ["audio/wav", "audio/mp3"]:
+                raise TypeError(
+                    f"Unsupported audio media type: {media_type}, "
+                    "only audio/wav and audio/mp3 are supported.",
+                )
+            return {
+                "type": "input_audio",
+                "input_audio": {
+                    "data": source.data,
+                    "format": media_type.split("/")[-1],
+                },
+            }
+
+        if isinstance(source, URLSource):
+            url_str = str(source.url)
+            if url_str.startswith("file://"):
+                # Local file
+                local_path = url_str.removeprefix("file://")
+                extension = local_path.rsplit(".", 1)[-1].lower()
+                if extension not in ["wav", "mp3"]:
+                    raise TypeError(
+                        f"Unsupported audio file extension: {extension}, "
+                        "wav and mp3 are supported.",
+                    )
+                with open(local_path, "rb") as f:
+                    data = base64.b64encode(f.read()).decode("utf-8")
+            else:
+                # Remote URL — download and encode
+                parsed = urlparse(url_str)
+                extension = parsed.path.rsplit(".", 1)[-1].lower()
+                if extension not in ["wav", "mp3"]:
+                    raise TypeError(
+                        f"Unsupported audio file extension: {extension}, "
+                        "wav and mp3 are supported.",
+                    )
+                response = requests.get(url_str, timeout=30)
+                response.raise_for_status()
+                data = base64.b64encode(response.content).decode("utf-8")
+
+            return {
+                "type": "input_audio",
+                "input_audio": {
+                    "data": data,
+                    "format": extension,
+                },
+            }
+
+        raise TypeError(f"Unsupported audio source type: {type(source)}.")
+
+
+class OpenAIChatFormatter(_OpenAIFormatterBase):
+    """The OpenAI formatter class for chatbot scenario, where only a user
+    and an agent are involved. We use the `name` field in OpenAI API to
+    identify different entities in the conversation.
+    """
+
+    input_types: list[str] = Field(
+        default_factory=lambda: ["text/plain", "image/*", "audio/*"],
+        description=(
+            "The supported input types. "
+            'Defaults to ``["text/plain", "image/*", "audio/*"]``.'
+        ),
+    )
+
+    async def format(
+        self,
+        msgs: list[Msg],
+    ) -> list[dict[str, Any]]:
+        """Format message objects into OpenAI API required format.
+
+        Args:
+            msgs (`list[Msg]`):
+                The list of Msg objects to format.
+
+        Returns:
+            `list[dict[str, Any]]`:
+                A list of dictionaries, where each dictionary has "name",
+                "role", and "content" keys.
+        """
+        self.assert_list_of_msgs(msgs)
+
+        messages: list[dict] = []
+        i = 0
+        while i < len(msgs):
+            msg = msgs[i]
+            content_blocks = []
+            tool_calls = []
+
+            for block in msg.get_content_blocks():
+                if isinstance(block, TextBlock):
+                    content_blocks.append({"type": "text", "text": block.text})
+
+                elif isinstance(block, DataBlock):
+                    formatted = self._format_openai_data_block(
+                        block,
+                    )
+                    if formatted is not None:
+                        content_blocks.append(formatted)
+
+                elif isinstance(block, HintBlock):
+                    if content_blocks or tool_calls:
+                        msg_openai = {
+                            "role": msg.role,
+                            "name": msg.name,
+                            "content": content_blocks or None,
+                        }
+                        if tool_calls:
+                            msg_openai["tool_calls"] = tool_calls
+                        messages.append(msg_openai)
+                        content_blocks = []
+                        tool_calls = []
+
+                    if isinstance(block.hint, str):
+                        messages.append(
+                            {
+                                "role": "user",
+                                "content": [
+                                    {"type": "text", "text": block.hint},
+                                ],
+                            },
+                        )
+                    else:
+                        hint_parts: list[dict] = []
+                        for sub in block.hint:
+                            if isinstance(sub, TextBlock):
+                                hint_parts.append(
+                                    {"type": "text", "text": sub.text},
+                                )
+                            elif isinstance(sub, DataBlock):
+                                formatted_sub = self._format_openai_data_block(
+                                    sub,
+                                )
+                                if formatted_sub is not None:
+                                    hint_parts.append(formatted_sub)
+                        if hint_parts:
+                            messages.append(
+                                {"role": "user", "content": hint_parts},
+                            )
+
+                elif isinstance(block, ToolCallBlock):
+                    tool_calls.append(
+                        {
+                            "id": block.id,
+                            "type": "function",
+                            "function": {
+                                "name": block.name,
+                                "arguments": block.input,
+                            },
+                        },
+                    )
+
+                elif isinstance(block, ToolResultBlock):
+                    if content_blocks or tool_calls:
+                        msg_openai_flush = {
+                            "role": msg.role,
+                            "name": msg.name,
+                            "content": content_blocks or None,
+                        }
+                        if tool_calls:
+                            msg_openai_flush["tool_calls"] = tool_calls
+                        messages.append(msg_openai_flush)
+                        content_blocks = []
+                        tool_calls = []
+
+                    (
+                        textual_output,
+                        multimodal_data,
+                    ) = self.convert_tool_result_to_string(block.output)
+
+                    messages.append(
+                        {
+                            "role": "tool",
+                            "tool_call_id": block.id,
+                            "content": textual_output,
+                            "name": block.name,
+                        },
+                    )
+
+                    if multimodal_data:
+                        promo_content = []
+                        for item in multimodal_data:
+                            if isinstance(item, TextBlock):
+                                promo_content.append(
+                                    {"type": "text", "text": item.text},
+                                )
+                            elif isinstance(item, DataBlock):
+                                fmt_item = self._format_openai_data_block(
+                                    item,
+                                )
+                                if fmt_item is not None:
+                                    promo_content.append(fmt_item)
+                        if promo_content:
+                            messages.append(
+                                {
+                                    "role": "user",
+                                    "name": "system-reminder",
+                                    "content": promo_content,
+                                },
+                            )
+
+                elif isinstance(block, ThinkingBlock):
+                    # OpenAI API does not accept reasoning/thinking content
+                    # in conversation history — skip thinking blocks silently.
+                    pass
+
+                else:
+                    logger.warning(
+                        "Unsupported block type %s in the message, skipped.",
+                        type(block),
+                    )
+
+            msg_openai = {
+                "role": msg.role,
+                "name": msg.name,
+                "content": content_blocks or None,
+            }
+
+            if tool_calls:
+                msg_openai["tool_calls"] = tool_calls
+
+            # When both content and tool_calls are None, skipped
+            if msg_openai["content"] or msg_openai.get("tool_calls"):
+                messages.append(msg_openai)
+
+            # Move to next message
+            i += 1
+
+        return messages
+
+
+class OpenAIMultiAgentFormatter(_OpenAIFormatterBase):
+    """
+    OpenAI formatter for multi-agent conversations, where more than
+    a user and an agent are involved.
+
+    .. tip:: This formatter is compatible with OpenAI API and
+        OpenAI-compatible services like vLLM, Azure OpenAI, and others.
+    """
+
+    conversation_history_prompt: str = Field(
+        default=(
+            "# Conversation History\n"
+            "The content between <history></history> tags contains "
+            "your conversation history\n"
+        ),
+        description="The prompt to use for the conversation history section.",
+    )
+
+    input_types: list[str] = Field(
+        default_factory=lambda: ["text/plain", "image/*", "audio/*"],
+        description=(
+            "The supported input types. "
+            'Defaults to ``["text/plain", "image/*", "audio/*"]``.'
+        ),
+    )
+
+    async def format(self, msgs: list[Msg]) -> list[dict[str, Any]]:
+        """Format input messages into the structure required by the OpenAI API
+        for multi-agent conversations."""
+        self.assert_list_of_msgs(msgs)
+
+        formatted_msgs = []
+        start_index = 0
+        if len(msgs) > 0 and msgs[0].role == "system":
+            formatted_msgs.append(
+                await self._format_system_message(msgs[0]),
+            )
+            start_index = 1
+
+        is_first_agent_message = True
+        async for typ, group in self._group_messages(msgs[start_index:]):
+            match typ:
+                case "tool_sequence":
+                    formatted_msgs.extend(
+                        await self._format_tool_sequence(group),
+                    )
+                case "agent_message":
+                    formatted_msgs.extend(
+                        await self._format_agent_message(
+                            group,
+                            is_first_agent_message,
+                        ),
+                    )
+                    is_first_agent_message = False
+
+        return formatted_msgs
+
+    async def _format_tool_sequence(
+        self,
+        msgs: list[Msg],
+    ) -> list[dict[str, Any]]:
+        """Given a sequence of tool call/result messages, format them into
+        the required format for the OpenAI API."""
+        return await OpenAIChatFormatter(
+            input_types=self.input_types,
+        ).format(msgs)
+
+    async def _format_agent_message(
+        self,
+        msgs: list[Msg],
+        is_first: bool = True,
+    ) -> list[dict[str, Any]]:
+        """Given a sequence of messages without tool calls/results, format
+        them into the required format for the OpenAI API."""
+
+        if is_first:
+            conversation_history_prompt = self.conversation_history_prompt
+        else:
+            conversation_history_prompt = ""
+
+        formatted_msgs: list[dict] = []
+        conversation_blocks: list = []
+        accumulated_text = []
+        media_blocks: list[dict] = []
+
+        for msg in msgs:
+            for block in msg.get_content_blocks():
+                if isinstance(block, TextBlock):
+                    accumulated_text.append(f"{msg.name}: {block.text}")
+
+                elif isinstance(block, DataBlock):
+                    formatted = self._format_openai_data_block(
+                        block,
+                    )
+                    if formatted is not None:
+                        media_blocks.append(formatted)
+
+        if accumulated_text:
+            conversation_blocks.append(
+                {"text": "\n".join(accumulated_text)},
+            )
+
+        if conversation_blocks:
+            if conversation_blocks[0].get("text"):
+                conversation_blocks[0]["text"] = (
+                    conversation_history_prompt
+                    + "<history>\n"
+                    + conversation_blocks[0]["text"]
+                )
+            else:
+                conversation_blocks.insert(
+                    0,
+                    {"text": conversation_history_prompt + "<history>\n"},
+                )
+
+            if conversation_blocks[-1].get("text"):
+                conversation_blocks[-1]["text"] += "\n</history>"
+            else:
+                conversation_blocks.append({"text": "</history>"})
+
+        conversation_blocks_text = "\n".join(
+            b.get("text", "") for b in conversation_blocks
+        )
+
+        content_list: list[dict[str, Any]] = []
+        if conversation_blocks_text:
+            content_list.append(
+                {"type": "text", "text": conversation_blocks_text},
+            )
+        content_list.extend(media_blocks)
+
+        if content_list:
+            formatted_msgs.append({"role": "user", "content": content_list})
+
+        return formatted_msgs
+
+    @staticmethod
+    async def _format_system_message(
+        msg: Msg,
+    ) -> dict[str, Any]:
+        """Format system message for OpenAI API."""
+        return {
+            "role": "system",
+            "content": msg.get_text_content(),
+        }
diff --git a/src/agentscope/formatter/_openai_response_formatter.py b/src/agentscope/formatter/_openai_response_formatter.py
new file mode 100644
index 0000000..2d9a370
--- /dev/null
+++ b/src/agentscope/formatter/_openai_response_formatter.py
@@ -0,0 +1,480 @@
+# -*- coding: utf-8 -*-
+"""Formatters for the OpenAI Responses API."""
+from abc import ABC
+from typing import Any
+
+from pydantic import Field
+
+from ._openai_formatter import _OpenAIFormatterBase
+from .._logging import logger
+from ..message import (
+    Msg,
+    TextBlock,
+    DataBlock,
+    ToolCallBlock,
+    ToolResultBlock,
+    HintBlock,
+    ThinkingBlock,
+)
+
+
+class _OpenAIResponseFormatterBase(_OpenAIFormatterBase, ABC):
+    """Base class for OpenAI Responses API formatters.
+
+    Provides the shared ``_format_response_data_block`` helper used by both
+    :class:`OpenAIResponseFormatter` (chat) and
+    :class:`OpenAIResponseMultiAgentFormatter` (multi-agent).
+    """
+
+    input_types: list[str] = Field(
+        default_factory=lambda: ["text/plain", "image/*"],
+        description=(
+            "The supported input types. "
+            'Defaults to ``["text/plain", "image/*"]``. '
+            "Audio is not supported by the Responses API."
+        ),
+    )
+
+    def _format_response_data_block(
+        self,
+        block: DataBlock,
+    ) -> dict[str, Any] | None:
+        """Format a DataBlock into the Response API format.
+
+        The Responses API uses different content types from the Chat
+        Completions API:
+
+        * ``image_url`` → ``input_image``
+        * ``input_audio`` → skipped (the Responses API does not support
+          audio input yet; use Chat Completions API instead). See
+          https://developers.openai.com/api/docs/guides/audio
+
+        Args:
+            block (`DataBlock`):
+                The DataBlock to format.
+
+        Returns:
+            `dict[str, Any] | None`:
+                A dictionary in the Responses API format, or ``None`` when the
+                block type is unsupported.
+        """
+        # Intercept audio blocks before the generic formatter rejects them
+        # with a less helpful "Unsupported media type" warning. The Responses
+        # API does not support audio input yet; use Chat Completions API with
+        # an audio-capable model instead.
+        # https://developers.openai.com/api/docs/guides/audio
+        media_type = getattr(block.source, "media_type", "") or ""
+        if media_type.split("/", 1)[0] == "audio":
+            logger.warning(
+                "Audio input is not supported by the OpenAI Responses API. "
+                "Use OpenAIChatModel with an audio-capable model instead. "
+                "This audio block will be skipped.",
+            )
+            return None
+
+        base_result = self._format_openai_data_block(block)
+        if base_result is None:
+            return None
+
+        if base_result.get("type") == "image_url":
+            return {
+                "type": "input_image",
+                "image_url": base_result["image_url"]["url"],
+            }
+
+        return base_result
+
+
+class OpenAIResponseFormatter(_OpenAIResponseFormatterBase):
+    """Formatter for the OpenAI Responses API in chat (single-agent) mode.
+
+    Produces input items compatible with ``client.responses.create(
+    input=...)``.
+    Compared with the Chat Completions format, the key differences are:
+
+    * Text content blocks use ``input_text`` instead of ``text``.
+    * Image content blocks use ``input_image`` instead of ``image_url``.
+    * Assistant tool-call messages become top-level ``function_call`` items.
+    * Tool result messages become ``function_call_output`` items.
+    * Reasoning items (``ThinkingBlock`` with ``reasoning_item_id``) are
+      echoed back verbatim as required by reasoning models (e.g. ``o1``).
+    """
+
+    # pylint: disable=too-many-branches
+    async def format(
+        self,
+        msgs: list[Msg],
+    ) -> list[dict[str, Any]]:
+        """Format message objects into OpenAI Response API input items.
+
+        Args:
+            msgs (`list[Msg]`):
+                The list of Msg objects to format.
+
+        Returns:
+            `list[dict[str, Any]]`:
+                A list of input items for ``client.responses.create``.
+        """
+        self.assert_list_of_msgs(msgs)
+
+        items: list[dict] = []
+        i = 0
+        while i < len(msgs):
+            msg = msgs[i]
+            content_parts: list[dict] = []
+            function_calls: list[dict] = []
+
+            for block in msg.get_content_blocks():
+                if isinstance(block, TextBlock):
+                    text_type = (
+                        "output_text"
+                        if msg.role == "assistant"
+                        else "input_text"
+                    )
+                    content_parts.append(
+                        {"type": text_type, "text": block.text},
+                    )
+
+                elif isinstance(block, DataBlock):
+                    formatted = self._format_response_data_block(block)
+                    if formatted is not None:
+                        content_parts.append(formatted)
+
+                elif isinstance(block, HintBlock):
+                    if function_calls:
+                        if content_parts:
+                            items.append(
+                                {
+                                    "role": msg.role,
+                                    "content": content_parts,
+                                },
+                            )
+                            content_parts = []
+                        items.extend(function_calls)
+                        function_calls = []
+                    elif content_parts:
+                        items.append(
+                            {
+                                "role": msg.role,
+                                "content": content_parts,
+                            },
+                        )
+                        content_parts = []
+
+                    if isinstance(block.hint, str):
+                        items.append(
+                            {
+                                "role": "user",
+                                "content": [
+                                    {
+                                        "type": "input_text",
+                                        "text": block.hint,
+                                    },
+                                ],
+                            },
+                        )
+                    else:
+                        hint_parts: list[dict] = []
+                        for sub in block.hint:
+                            if isinstance(sub, TextBlock):
+                                hint_parts.append(
+                                    {
+                                        "type": "input_text",
+                                        "text": sub.text,
+                                    },
+                                )
+                            elif isinstance(sub, DataBlock):
+                                formatted_sub = (
+                                    self._format_response_data_block(
+                                        sub,
+                                    )
+                                )
+                                if formatted_sub is not None:
+                                    hint_parts.append(formatted_sub)
+                        if hint_parts:
+                            items.append(
+                                {"role": "user", "content": hint_parts},
+                            )
+
+                elif isinstance(block, ThinkingBlock):
+                    # When reasoning_item_id is present the block originated
+                    # from a Responses API "reasoning" output item.  The API
+                    # requires that such items are echoed back verbatim in
+                    # multi-turn history (especially when they precede a
+                    # function_call).  Without the ID we skip silently.
+                    reasoning_item_id = getattr(
+                        block,
+                        "reasoning_item_id",
+                        None,
+                    )
+                    if reasoning_item_id:
+                        if content_parts:
+                            items.append(
+                                {
+                                    "role": msg.role,
+                                    "content": content_parts,
+                                },
+                            )
+                            content_parts = []
+                        # summary may be empty when the model did not produce
+                        # reasoning summary text (e.g. o4-mini with streaming)
+                        summary = (
+                            [{"type": "summary_text", "text": block.thinking}]
+                            if block.thinking
+                            else []
+                        )
+                        items.append(
+                            {
+                                "type": "reasoning",
+                                "id": reasoning_item_id,
+                                "summary": summary,
+                                "content": [],
+                            },
+                        )
+
+                elif isinstance(block, ToolCallBlock):
+                    function_calls.append(
+                        {
+                            "type": "function_call",
+                            "call_id": block.id,
+                            "name": block.name,
+                            "arguments": block.input,
+                        },
+                    )
+
+                elif isinstance(block, ToolResultBlock):
+                    if function_calls:
+                        if content_parts:
+                            items.append(
+                                {
+                                    "role": msg.role,
+                                    "content": content_parts,
+                                },
+                            )
+                            content_parts = []
+                        items.extend(function_calls)
+                        function_calls = []
+                    elif content_parts:
+                        items.append(
+                            {
+                                "role": msg.role,
+                                "content": content_parts,
+                            },
+                        )
+                        content_parts = []
+
+                    (
+                        textual_output,
+                        multimodal_data,
+                    ) = self.convert_tool_result_to_string(block.output)
+
+                    items.append(
+                        {
+                            "type": "function_call_output",
+                            "call_id": block.id,
+                            "output": textual_output,
+                        },
+                    )
+
+                    if multimodal_data:
+                        promo_content = []
+                        for item in multimodal_data:
+                            if isinstance(item, TextBlock):
+                                promo_content.append(
+                                    {
+                                        "type": "input_text",
+                                        "text": item.text,
+                                    },
+                                )
+                            elif isinstance(item, DataBlock):
+                                fmt_item = self._format_response_data_block(
+                                    item,
+                                )
+                                if fmt_item is not None:
+                                    promo_content.append(fmt_item)
+                        if promo_content:
+                            items.append(
+                                {
+                                    "role": "user",
+                                    "content": promo_content,
+                                },
+                            )
+
+                else:
+                    logger.warning(
+                        "Unsupported block type %s in the message, skipped.",
+                        type(block),
+                    )
+
+            if function_calls:
+                if content_parts:
+                    items.append(
+                        {
+                            "role": msg.role,
+                            "content": content_parts,
+                        },
+                    )
+                items.extend(function_calls)
+            elif content_parts:
+                items.append(
+                    {
+                        "role": msg.role,
+                        "content": content_parts,
+                    },
+                )
+
+            i += 1
+
+        return items
+
+
+class OpenAIResponseMultiAgentFormatter(_OpenAIResponseFormatterBase):
+    """Formatter for the OpenAI Responses API in multi-agent mode.
+
+    Handles conversations where more than a user and a single agent are
+    involved.  Tool call/result sequences are formatted with the Responses API
+    ``function_call`` / ``function_call_output`` items (delegated to
+    :class:`OpenAIResponseFormatter`).  Agent conversation history messages
+    are wrapped inside ``<history></history>`` tags and presented as a single
+    ``user`` input item.
+    """
+
+    conversation_history_prompt: str = Field(
+        default=(
+            "# Conversation History\n"
+            "The content between <history></history> tags contains "
+            "your conversation history\n"
+        ),
+        description="The prompt to use for the conversation history section.",
+    )
+
+    async def format(
+        self,
+        msgs: list[Msg],
+    ) -> list[dict[str, Any]]:
+        """Format messages for multi-agent Responses API conversations.
+
+        Args:
+            msgs (`list[Msg]`):
+                The list of Msg objects to format.
+
+        Returns:
+            `list[dict[str, Any]]`:
+                A list of input items for ``client.responses.create``.
+        """
+        self.assert_list_of_msgs(msgs)
+
+        formatted_msgs: list[dict] = []
+        start_index = 0
+        if len(msgs) > 0 and msgs[0].role == "system":
+            formatted_msgs.append(
+                await self._format_system_message(msgs[0]),
+            )
+            start_index = 1
+
+        is_first_agent_message = True
+        async for typ, group in self._group_messages(msgs[start_index:]):
+            if typ == "tool_sequence":
+                formatted_msgs.extend(
+                    await self._format_tool_sequence(group),
+                )
+            elif typ == "agent_message":
+                formatted_msgs.extend(
+                    await self._format_agent_message(
+                        group,
+                        is_first_agent_message,
+                    ),
+                )
+                is_first_agent_message = False
+
+        return formatted_msgs
+
+    async def _format_tool_sequence(
+        self,
+        msgs: list[Msg],
+    ) -> list[dict[str, Any]]:
+        """Format a sequence of tool call/result messages using the Responses
+        API format.
+
+        Args:
+            msgs (`list[Msg]`):
+                The tool call/result messages to format.
+
+        Returns:
+            `list[dict[str, Any]]`:
+                A list of Responses API input items.
+        """
+        return await OpenAIResponseFormatter(
+            input_types=self.input_types,
+        ).format(msgs)
+
+    async def _format_agent_message(
+        self,
+        msgs: list[Msg],
+        is_first: bool = True,
+    ) -> list[dict[str, Any]]:
+        """Format a sequence of agent messages as a history-wrapped user item.
+
+        Args:
+            msgs (`list[Msg]`):
+                The agent messages to format.
+            is_first (`bool`, defaults to ``True``):
+                Whether this is the first agent message group, which triggers
+                the conversation history prompt.
+
+        Returns:
+            `list[dict[str, Any]]`:
+                A list containing at most one user input item.
+        """
+        conversation_history_prompt = (
+            self.conversation_history_prompt if is_first else ""
+        )
+
+        accumulated_text: list[str] = []
+        media_blocks: list[dict] = []
+
+        for msg in msgs:
+            for block in msg.get_content_blocks():
+                if isinstance(block, TextBlock):
+                    accumulated_text.append(f"{msg.name}: {block.text}")
+                elif isinstance(block, DataBlock):
+                    formatted = self._format_response_data_block(block)
+                    if formatted is not None:
+                        media_blocks.append(formatted)
+
+        if not accumulated_text and not media_blocks:
+            return []
+
+        history_text = "\n".join(accumulated_text)
+        wrapped = (
+            conversation_history_prompt
+            + "<history>\n"
+            + history_text
+            + "\n</history>"
+        )
+
+        content_list: list[dict[str, Any]] = [
+            {"type": "input_text", "text": wrapped},
+        ]
+        content_list.extend(media_blocks)
+
+        return [{"role": "user", "content": content_list}]
+
+    @staticmethod
+    async def _format_system_message(
+        msg: Msg,
+    ) -> dict[str, Any]:
+        """Format a system message for the Responses API.
+
+        Args:
+            msg (`Msg`):
+                The system message to format.
+
+        Returns:
+            `dict[str, Any]`:
+                A dictionary with ``role`` and ``content`` keys.
+        """
+        return {
+            "role": "system",
+            "content": msg.get_text_content(),
+        }
diff --git a/src/agentscope/formatter/_xai_formatter.py b/src/agentscope/formatter/_xai_formatter.py
new file mode 100644
index 0000000..7f55738
--- /dev/null
+++ b/src/agentscope/formatter/_xai_formatter.py
@@ -0,0 +1,485 @@
+# -*- coding: utf-8 -*-
+"""The xAI formatter module.
+
+This formatter converts AgentScope ``Msg`` objects into the protobuf
+``Message`` objects expected by the ``xai_sdk`` gRPC client.  Unlike every
+other formatter, the ``format()`` method returns a list of
+``chat_pb2.Message`` proto objects rather than plain dicts, because the
+``xai_sdk`` chat API accepts proto messages directly.
+"""
+import base64
+from typing import Any, List
+
+from pydantic import Field
+
+from ._formatter_base import FormatterBase
+from .._logging import logger
+from ..message import (
+    Msg,
+    TextBlock,
+    ThinkingBlock,
+    ToolCallBlock,
+    ToolResultBlock,
+    DataBlock,
+    URLSource,
+    Base64Source,
+    HintBlock,
+)
+
+
+class XAIChatFormatter(FormatterBase):
+    """Formatter for the xAI chat model.
+
+    Converts ``Msg`` objects into ``xai_sdk`` protobuf ``Message`` objects
+    that can be appended directly to a ``xai_sdk`` chat session.
+
+    Unlike other formatters whose ``format()`` returns ``list[dict]``, this
+    formatter returns ``list[chat_pb2.Message]``.  The type annotation is
+    intentionally widened to ``list[Any]`` to accommodate this difference.
+    """
+
+    input_types: list[str] = Field(
+        default=["text/plain", "image/jpeg", "image/png"],
+        description=(
+            "The supported input types. "
+            'Defaults to ``["text/plain", "image/jpeg", "image/png"]``.'
+        ),
+    )
+
+    # pylint: disable=too-many-statements, too-many-branches
+    async def format(
+        self,
+        msgs: list[Msg],
+        **kwargs: Any,
+    ) -> List[Any]:
+        """Convert a list of ``Msg`` objects to ``xai_sdk`` proto messages.
+
+        Args:
+            msgs (`list[Msg]`):
+                A list of ``Msg`` objects representing the conversation.
+            **kwargs (`Any`):
+                Unused; retained for interface compatibility.
+
+        Returns:
+            `list[Any]`:
+                A list of ``chat_pb2.Message`` proto objects, ready to be
+                appended to a ``xai_sdk`` chat session via
+                ``chat.append()``.
+        """
+        from xai_sdk.chat import (
+            assistant,
+            image,
+            system,
+            tool_result,
+            user,
+            chat_pb2,
+        )
+
+        self.assert_list_of_msgs(msgs)
+
+        xai_messages: List[Any] = []
+
+        for msg in msgs:
+            blocks = msg.get_content_blocks()
+
+            text_blocks = [b for b in blocks if isinstance(b, TextBlock)]
+
+            if msg.role == "system":
+                text = "\n".join(b.text for b in text_blocks)
+                xai_messages.append(system(text))
+
+            elif msg.role == "user":
+                content_args: list = []
+                for block in blocks:
+                    if isinstance(block, ThinkingBlock):
+                        pass
+                    elif isinstance(block, HintBlock):
+                        if content_args:
+                            xai_messages.append(user(*content_args))
+                            content_args = []
+                        if isinstance(block.hint, str):
+                            xai_messages.append(user(block.hint))
+                        else:
+                            hint_args = self._xai_user_args_from_blocks(
+                                block.hint,
+                                image,
+                            )
+                            if hint_args:
+                                xai_messages.append(user(*hint_args))
+                    elif isinstance(block, TextBlock):
+                        content_args.append(block.text)
+                    elif isinstance(block, DataBlock):
+                        if block.source.media_type.startswith("image/"):
+                            if isinstance(block.source, URLSource):
+                                url_str = str(block.source.url)
+                                if url_str.startswith("file://"):
+                                    # Local file — read and encode as data URI
+                                    local_path = url_str.removeprefix(
+                                        "file://",
+                                    )
+                                    with open(local_path, "rb") as f:
+                                        encoded = base64.b64encode(
+                                            f.read(),
+                                        ).decode("utf-8")
+                                    content_args.append(
+                                        image(
+                                            f"data:{block.source.media_type};"
+                                            f"base64,{encoded}",
+                                        ),
+                                    )
+                                else:
+                                    content_args.append(image(url_str))
+                            elif isinstance(block.source, Base64Source):
+                                content_args.append(
+                                    image(
+                                        f"data:{block.source.media_type};"
+                                        f"base64,{block.source.data}",
+                                    ),
+                                )
+                        else:
+                            logger.warning(
+                                "Unsupported media type %s for xAI API. "
+                                "Only image/jpeg and image/png are supported. "
+                                "This block will be skipped.",
+                                block.source.media_type,
+                            )
+                    else:
+                        logger.warning(
+                            "Unsupported block type %s in user message, "
+                            "skipped.",
+                            type(block).__name__,
+                        )
+
+                if content_args:
+                    xai_messages.append(user(*content_args))
+
+            elif msg.role == "assistant":
+                pending_text: list[TextBlock] = []
+                pending_tool_calls: list[ToolCallBlock] = []
+
+                for block in blocks:
+                    if isinstance(block, ToolResultBlock):
+                        # Convert each ToolResultBlock to a tool_result
+                        # message.
+                        if pending_tool_calls:
+                            msg_proto = chat_pb2.Message()
+                            msg_proto.role = chat_pb2.MessageRole.Value(
+                                "ROLE_ASSISTANT",
+                            )
+                            if pending_text:
+                                c = msg_proto.content.add()
+                                c.text = "\n".join(
+                                    b.text for b in pending_text
+                                )
+                                pending_text = []
+                            for tc in pending_tool_calls:
+                                proto_tc = msg_proto.tool_calls.add()
+                                proto_tc.id = tc.id
+                                proto_tc.type = chat_pb2.ToolCallType.Value(
+                                    "TOOL_CALL_TYPE_CLIENT_SIDE_TOOL",
+                                )
+                                proto_tc.function.name = tc.name
+                                proto_tc.function.arguments = tc.input
+                            xai_messages.append(msg_proto)
+                            pending_tool_calls = []
+                        elif pending_text:
+                            text = "\n".join(b.text for b in pending_text)
+                            if text:
+                                xai_messages.append(assistant(text))
+                            pending_text = []
+
+                        output_text = self._extract_result_text(
+                            block.output,
+                        )
+                        xai_messages.append(
+                            tool_result(
+                                output_text,
+                                tool_call_id=block.id,
+                            ),
+                        )
+
+                    elif isinstance(block, ToolCallBlock):
+                        pending_tool_calls.append(block)
+
+                    elif isinstance(block, TextBlock):
+                        pending_text.append(block)
+
+                    elif isinstance(block, ThinkingBlock):
+                        pass
+
+                    elif isinstance(block, HintBlock):
+                        if pending_tool_calls or pending_text:
+                            if pending_tool_calls:
+                                msg_proto = chat_pb2.Message()
+                                msg_proto.role = chat_pb2.MessageRole.Value(
+                                    "ROLE_ASSISTANT",
+                                )
+                                if pending_text:
+                                    c = msg_proto.content.add()
+                                    c.text = "\n".join(
+                                        b.text for b in pending_text
+                                    )
+                                    pending_text = []
+                                for tc in pending_tool_calls:
+                                    proto_tc = msg_proto.tool_calls.add()
+                                    proto_tc.id = tc.id
+                                    proto_tc.type = (
+                                        chat_pb2.ToolCallType.Value(
+                                            "TOOL_CALL_TYPE_CLIENT_SIDE_TOOL",
+                                        )
+                                    )
+                                    proto_tc.function.name = tc.name
+                                    proto_tc.function.arguments = tc.input
+                                xai_messages.append(msg_proto)
+                                pending_tool_calls = []
+                            elif pending_text:
+                                text = "\n".join(b.text for b in pending_text)
+                                if text:
+                                    xai_messages.append(assistant(text))
+                                pending_text = []
+                        if isinstance(block.hint, str):
+                            xai_messages.append(user(block.hint))
+                        else:
+                            hint_args = self._xai_user_args_from_blocks(
+                                block.hint,
+                                image,
+                            )
+                            if hint_args:
+                                xai_messages.append(user(*hint_args))
+
+                if pending_tool_calls:
+                    # Assistant turn that triggered tool calls (history).
+                    msg_proto = chat_pb2.Message()
+                    msg_proto.role = chat_pb2.MessageRole.Value(
+                        "ROLE_ASSISTANT",
+                    )
+                    if pending_text:
+                        c = msg_proto.content.add()
+                        c.text = "\n".join(b.text for b in pending_text)
+                        pending_text = []
+                    for tc in pending_tool_calls:
+                        proto_tc = msg_proto.tool_calls.add()
+                        proto_tc.id = tc.id
+                        proto_tc.type = chat_pb2.ToolCallType.Value(
+                            "TOOL_CALL_TYPE_CLIENT_SIDE_TOOL",
+                        )
+                        proto_tc.function.name = tc.name
+                        proto_tc.function.arguments = tc.input
+                    xai_messages.append(msg_proto)
+                elif pending_text:
+                    # Regular assistant text message.
+                    text = "\n".join(b.text for b in pending_text)
+                    if text:
+                        xai_messages.append(assistant(text))
+
+            else:
+                logger.warning(
+                    "Unsupported message role '%s', skipped.",
+                    msg.role,
+                )
+
+        return xai_messages
+
+    def _xai_user_args_from_blocks(
+        self,
+        blocks: list,
+        image: Any,
+    ) -> list:
+        """Convert a list of ``TextBlock | DataBlock`` into the positional
+        args expected by ``xai_sdk.chat.user(*args)``.
+
+        DataBlocks that are not images (or use an unsupported media type)
+        are dropped with a warning, matching the existing user-role
+        DataBlock handling above.
+
+        Args:
+            blocks (`list`):
+                The ``hint`` list from a :class:`HintBlock`.
+            image (`Any`):
+                The ``xai_sdk.chat.image`` constructor, passed in to keep
+                the local import contract identical to ``format``.
+
+        Returns:
+            `list`:
+                Positional args for ``user(*args)``; empty if nothing
+                survived.
+        """
+        args: list = []
+        for sub in blocks:
+            if isinstance(sub, TextBlock):
+                args.append(sub.text)
+            elif isinstance(sub, DataBlock):
+                if not sub.source.media_type.startswith("image/"):
+                    logger.warning(
+                        "Unsupported media type %s for xAI API. "
+                        "Only image/jpeg and image/png are supported. "
+                        "This hint sub-block will be skipped.",
+                        sub.source.media_type,
+                    )
+                    continue
+                if isinstance(sub.source, URLSource):
+                    url_str = str(sub.source.url)
+                    if url_str.startswith("file://"):
+                        local_path = url_str.removeprefix("file://")
+                        with open(local_path, "rb") as f:
+                            encoded = base64.b64encode(f.read()).decode(
+                                "utf-8",
+                            )
+                        args.append(
+                            image(
+                                f"data:{sub.source.media_type};"
+                                f"base64,{encoded}",
+                            ),
+                        )
+                    else:
+                        args.append(image(url_str))
+                elif isinstance(sub.source, Base64Source):
+                    args.append(
+                        image(
+                            f"data:{sub.source.media_type};"
+                            f"base64,{sub.source.data}",
+                        ),
+                    )
+        return args
+
+    def _extract_result_text(self, output: Any) -> str:
+        """Extract a plain-text string from a ``ToolResultBlock`` output.
+
+        Args:
+            output (`Any`):
+                The raw output of a ``ToolResultBlock``, which may be a
+                string, a list of blocks, or another type.
+
+        Returns:
+            `str`:
+                A plain-text representation of the output.
+        """
+        if output is None:
+            return ""
+        if isinstance(output, str):
+            return output
+        if isinstance(output, list):
+            parts = []
+            for item in output:
+                if isinstance(item, TextBlock):
+                    parts.append(item.text)
+                elif isinstance(item, str):
+                    parts.append(item)
+                else:
+                    parts.append(str(item))
+            return "\n".join(parts)
+        return str(output)
+
+
+class XAIMultiAgentFormatter(FormatterBase):
+    """Formatter for the xAI chat model in multi-agent conversations.
+
+    Produces ``xai_sdk`` protobuf ``Message`` objects (same as
+    :class:`XAIChatFormatter`).  Prior agent-to-agent messages are collapsed
+    into a single ``user`` message with ``<history></history>`` tags; tool
+    call / result sequences are delegated to :class:`XAIChatFormatter`.
+
+    .. note:: ``format()`` returns ``list[Any]`` (protobuf messages), not
+        ``list[dict]``.
+    """
+
+    conversation_history_prompt: str = Field(
+        default=(
+            "# Conversation History\n"
+            "The content between <history></history> tags contains "
+            "your conversation history\n"
+        ),
+        description="The prompt to use for the conversation history section.",
+    )
+
+    input_types: list[str] = Field(
+        default=["text/plain", "image/jpeg", "image/png"],
+        description=(
+            "The supported input types. "
+            'Defaults to ``["text/plain", "image/jpeg", "image/png"]``.'
+        ),
+    )
+
+    async def format(
+        self,
+        msgs: list[Msg],
+        **kwargs: Any,
+    ) -> List[Any]:
+        """Convert a list of ``Msg`` objects to ``xai_sdk`` proto messages.
+
+        Conversation history (non-tool messages) is collapsed into a single
+        ``user`` protobuf message containing ``<history></history>`` tags.
+        Tool sequences are formatted by :class:`XAIChatFormatter`.
+
+        Args:
+            msgs (`list[Msg]`):
+                A list of ``Msg`` objects representing the conversation.
+            **kwargs (`Any`):
+                Unused; retained for interface compatibility.
+
+        Returns:
+            `list[Any]`:
+                A list of ``chat_pb2.Message`` proto objects.
+        """
+        from xai_sdk.chat import system, user
+
+        self.assert_list_of_msgs(msgs)
+
+        xai_messages: List[Any] = []
+        start_index = 0
+
+        if msgs and msgs[0].role == "system":
+            text = msgs[0].get_text_content()
+            xai_messages.append(system(text))
+            start_index = 1
+
+        is_first_agent_message = True
+        async for typ, group in self._group_messages(msgs[start_index:]):
+            if typ == "tool_sequence":
+                xai_messages.extend(
+                    await XAIChatFormatter(
+                        input_types=self.input_types,
+                    ).format(group),
+                )
+            elif typ == "agent_message":
+                history_text = self._build_history_text(
+                    group,
+                    is_first=is_first_agent_message,
+                )
+                if history_text:
+                    xai_messages.append(user(history_text))
+                is_first_agent_message = False
+
+        return xai_messages
+
+    def _build_history_text(self, msgs: list[Msg], *, is_first: bool) -> str:
+        """Build a ``<history>…</history>`` text block from agent messages.
+
+        Args:
+            msgs (`list[Msg]`):
+                Non-tool messages to collapse into history.
+            is_first (`bool`):
+                When ``True``, prepend
+                :attr:`conversation_history_prompt` before the tag.
+
+        Returns:
+            `str`:
+                The formatted history string, or an empty string when there
+                is no text content.
+        """
+        lines: list[str] = []
+        for msg in msgs:
+            parts: list[str] = []
+            if msg.name:
+                parts.append(f"{msg.name}:")
+            for block in msg.get_content_blocks():
+                if isinstance(block, TextBlock):
+                    parts.append(block.text)
+            if parts:
+                lines.append(" ".join(parts))
+
+        if not lines:
+            return ""
+
+        prefix = self.conversation_history_prompt if is_first else ""
+        return prefix + "<history>\n" + "\n".join(lines) + "\n</history>"
diff --git a/src/agentscope/mcp/__init__.py b/src/agentscope/mcp/__init__.py
new file mode 100644
index 0000000..7e0f555
--- /dev/null
+++ b/src/agentscope/mcp/__init__.py
@@ -0,0 +1,13 @@
+# -*- coding: utf-8 -*-
+"""The MCP module in AgentScope, that provides fine-grained control over
+the MCP servers."""
+
+from ._config import StdioMCPConfig, HttpMCPConfig
+from ._mcp_client import MCPClient
+
+
+__all__ = [
+    "MCPClient",
+    "StdioMCPConfig",
+    "HttpMCPConfig",
+]
diff --git a/src/agentscope/mcp/_config.py b/src/agentscope/mcp/_config.py
new file mode 100644
index 0000000..a076d9e
--- /dev/null
+++ b/src/agentscope/mcp/_config.py
@@ -0,0 +1,64 @@
+# -*- coding: utf-8 -*-
+"""The MCP configurations."""
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class StdioMCPConfig(BaseModel):
+    """The STDIO MCP server configuration."""
+
+    type: Literal["stdio_mcp"] = "stdio_mcp"
+
+    command: str = Field(
+        title="Command",
+        description="The command to start the MCP server.",
+    )
+
+    args: list[str] | None = Field(
+        title="Args",
+        description="The command line arguments to pass to the MCP server.",
+        default=None,
+    )
+
+    env: dict[str, str] | None = Field(
+        title="Environment Variables",
+        default=None,
+        description="The environment variables to pass to the MCP server.",
+    )
+
+    cwd: str | Path | None = Field(
+        default=None,
+        title="CWD",
+        description="The working directory to use when spawning the process.",
+    )
+
+    encoding_error_handler: Literal["strict", "ignore", "replace"] = Field(
+        default="strict",
+        title="Encoding Error Handler",
+        description="The text encoding error handler.",
+    )
+
+
+class HttpMCPConfig(BaseModel):
+    """The HTTP MCP server configuration."""
+
+    type: Literal["http_mcp"] = "http_mcp"
+
+    url: str = Field(
+        title="URL",
+        description="The URL of the MCP server.",
+    )
+
+    headers: dict[str, str] | None = Field(
+        title="Headers",
+        description="The additional headers to include in the HTTP request.",
+        default=None,
+    )
+
+    timeout: float | None = Field(
+        title="Timeout",
+        description="The HTTP request timeout in seconds.",
+        default=30.0,
+    )
diff --git a/src/agentscope/mcp/_mcp_client.py b/src/agentscope/mcp/_mcp_client.py
new file mode 100644
index 0000000..688e6e2
--- /dev/null
+++ b/src/agentscope/mcp/_mcp_client.py
@@ -0,0 +1,438 @@
+# -*- coding: utf-8 -*-
+"""Unified MCP client implementation for AgentScope."""
+import re
+from contextlib import AsyncExitStack, _AsyncGeneratorContextManager
+from typing import Any, TYPE_CHECKING
+
+import httpx
+import mcp.types
+from mcp import ClientSession, stdio_client, StdioServerParameters
+from mcp.client.sse import sse_client
+from mcp.client.streamable_http import streamable_http_client
+from pydantic import Field, BaseModel, PrivateAttr
+
+from ._config import StdioMCPConfig, HttpMCPConfig
+from .._logging import logger
+
+if TYPE_CHECKING:
+    from ..tool import MCPTool, ToolBase
+else:
+    MCPTool = Any
+    ToolBase = Any
+
+
+class MCPClient(BaseModel):
+    """The unified MCP client in AgentScope.
+
+    This class provides a unified interface for MCP connections, handling both
+    stateful (persistent) and stateless (ephemeral) connections.
+
+    - Stateful: Requires explicit connect() and close(), maintains session
+    - Stateless: No connect() needed, creates temporary session per call
+
+    Private attributes:
+    - _client: The underlying MCP client context manager
+    - _session: The MCP ClientSession (for stateful connections only)
+    - _stack: AsyncExitStack for managing connection lifecycle
+    - _is_connected: Connection state flag
+    - _cached_tools: Cached list of tools
+
+    Example:
+
+    .. code-block:: python
+
+        # Stateful connection (STDIO or HTTP)
+        client = MCPClient(
+            name="file_system",
+            is_stateful=True,
+            mcp_config=StdioMCPConfig(
+                command="mcp-server-filesystem"
+            )
+        )
+        await client.connect()
+        tools = await client.list_tools()
+        await client.close()
+
+        # Stateless connection (HTTP only)
+        client = MCPClient(
+            name="weather_search",
+            is_stateful=False,
+            mcp_config=HttpMCPConfig(
+                url="https://api.weather.com/mcp"
+            )
+        )
+        # No connect() needed
+        tools = await client.list_tools()
+
+    """
+
+    name: str = Field(
+        title="MCP Name",
+        description="The MCP name.",
+    )
+
+    is_stateful: bool = Field(
+        title="Stateful",
+        description=(
+            "Whether this is a stateful connection that requires explicit "
+            "connect() and close(). STDIO MCP must be stateful. HTTP MCP "
+            "can be either stateful or stateless."
+        ),
+    )
+
+    mcp_config: StdioMCPConfig | HttpMCPConfig = Field(
+        discriminator="type",
+        title="MCP Config",
+        description="The MCP server configuration.",
+    )
+
+    enable_tools: list[str] | None = None
+    """The tools enabled in this MCP, which will be returned in the
+    `list_tools` function. If `None`, all tools from the MCP server will be
+    returned."""
+
+    disable_tools: list[str] | None = None
+    """The tools disabled in this MCP, which will be filtered out in the
+    `list_tools` function."""
+
+    execution_timeout: float | None = None
+    """The execution timeout in seconds for calling the tools from this MCP."""
+
+    # Private attributes
+    _client: Any = PrivateAttr(default=None)
+    _session: ClientSession | None = PrivateAttr(default=None)
+    _stack: AsyncExitStack | None = PrivateAttr(default=None)
+    _is_connected: bool = PrivateAttr(default=False)
+    _cached_tools: list[mcp.types.Tool] | None = PrivateAttr(default=None)
+
+    @property
+    def is_connected(self) -> bool:
+        """Whether the client is currently connected.
+
+        Returns:
+            True if connected, False otherwise.
+        """
+        return self._is_connected
+
+    def model_post_init(self, __context: Any) -> None:
+        """Validate configuration and initialize client."""
+        # MCP name is used to compose model-facing tool names
+        # (mcp__{name}__{tool}), which must match ^[a-zA-Z0-9_-]+$.
+        if not re.fullmatch(r"[a-zA-Z0-9_-]+", self.name):
+            raise ValueError(
+                f"MCPClient name '{self.name}' contains characters not "
+                f"allowed by LLM providers (only [a-zA-Z0-9_-] are "
+                f"permitted). Please rename it.",
+            )
+
+        # STDIO MCP must be stateful
+        if self.mcp_config.type == "stdio_mcp" and not self.is_stateful:
+            raise ValueError(
+                "STDIO MCP must be stateful (is_stateful=True).",
+            )
+
+        # Check arguments for self.enable_tools and disable_tools
+        if self.enable_tools is not None:
+            if not isinstance(self.enable_tools, list) or any(
+                not isinstance(_, str) for _ in self.enable_tools
+            ):
+                raise ValueError(
+                    "Enable tools should be a list of strings, but got "
+                    f"{self.enable_tools}.",
+                )
+
+        if self.disable_tools is not None:
+            if not isinstance(self.disable_tools, list) or any(
+                not isinstance(_, str) for _ in self.disable_tools
+            ):
+                raise ValueError(
+                    "Disable tools should be a list of strings, but got "
+                    f"{self.disable_tools}.",
+                )
+
+        if self.enable_tools is not None and self.disable_tools is not None:
+            intersection = set(self.enable_tools).intersection(
+                set(self.disable_tools),
+            )
+            if len(intersection) != 0:
+                raise ValueError(
+                    f"The tools in enable_tools and disable_tools "
+                    f"should not overlap, but got {intersection}.",
+                )
+
+        # Initialize the underlying client
+        self._initialize_client()
+
+    def _initialize_client(self) -> None:
+        """Pre-build the stdio client context manager.
+
+        Only the stdio transport is materialised at construction time —
+        ``StdioServerParameters`` carry process-launch details that are
+        cheap to bind upfront. HTTP transports are built lazily inside
+        :meth:`connect` (or per-call inside :meth:`_get_client_gen` for
+        stateless mode), since each ``streamable_http_client`` /
+        ``sse_client`` is a one-shot context manager.
+        """
+        if self.mcp_config.type == "stdio_mcp":
+            config = self.mcp_config
+            self._client = stdio_client(
+                StdioServerParameters(
+                    command=config.command,
+                    args=config.args or [],
+                    env=config.env,
+                    cwd=str(config.cwd) if config.cwd else None,
+                    encoding="utf-8",
+                    encoding_error_handler=config.encoding_error_handler,
+                ),
+            )
+
+    def _create_http_client(
+        self,
+    ) -> _AsyncGeneratorContextManager[Any]:
+        """Create an HTTP MCP client (SSE or streamable HTTP)."""
+        config = self.mcp_config
+
+        # Determine transport from URL
+        if config.url.endswith("/sse") or config.url.endswith("/messages/"):
+            return sse_client(
+                url=config.url,
+                headers=config.headers,
+                timeout=config.timeout,
+            )
+
+        # StreamableHTTP transport
+        http_client = None
+        if config.headers or config.timeout:
+            http_client = httpx.AsyncClient(
+                headers=config.headers,
+                timeout=config.timeout,
+            )
+        return streamable_http_client(
+            url=config.url,
+            http_client=http_client,
+        )
+
+    async def connect(self) -> None:
+        """Connect to the MCP server (for stateful connections only).
+
+        For stateless connections, this method does nothing.
+
+        Raises:
+            RuntimeError: If already connected.
+        """
+        if not self.is_stateful:
+            logger.debug(
+                "Stateless MCP '%s' does not require explicit connect.",
+                self.name,
+            )
+            return
+
+        if self._is_connected:
+            raise RuntimeError(
+                f"MCP '{self.name}' is already connected. "
+                "Call close() before reconnecting.",
+            )
+
+        # Create HTTP client if needed
+        if self._client is None and self.mcp_config.type == "http_mcp":
+            self._client = self._create_http_client()
+
+        self._stack = AsyncExitStack()
+
+        try:
+            context = await self._stack.enter_async_context(self._client)
+            read_stream, write_stream = context[0], context[1]
+            self._session = ClientSession(read_stream, write_stream)
+            await self._stack.enter_async_context(self._session)
+            await self._session.initialize()
+
+            self._is_connected = True
+            logger.info("MCP connected: %s", self.name)
+        except Exception:
+            await self._stack.aclose()
+            self._stack = None
+            raise
+
+    async def close(self, ignore_errors: bool = True) -> None:
+        """Close the MCP connection (for stateful connections only).
+
+        For stateless connections, this method does nothing.
+
+        Args:
+            ignore_errors: Whether to ignore errors during cleanup.
+
+        Raises:
+            RuntimeError: If not connected.
+        """
+        if not self.is_stateful:
+            logger.debug(
+                "Stateless MCP '%s' does not require explicit close.",
+                self.name,
+            )
+            return
+
+        if not self._is_connected:
+            raise RuntimeError(
+                f"MCP '{self.name}' is not connected. "
+                "Call connect() first.",
+            )
+
+        try:
+            await self._stack.aclose()
+        except Exception as e:
+            if not ignore_errors:
+                raise e
+            logger.warning(
+                "Error closing MCP '%s': %s",
+                self.name,
+                str(e),
+            )
+        finally:
+            self._stack = None
+            self._session = None
+            self._is_connected = False
+            logger.info("MCP closed: %s", self.name)
+
+    def _get_client_gen(self) -> _AsyncGeneratorContextManager[Any]:
+        """Get client generator for stateless connections."""
+        if self.mcp_config.type == "stdio_mcp":
+            return self._client
+        else:
+            return self._create_http_client()
+
+    async def list_raw_tools(self) -> list[mcp.types.Tool]:
+        """List available tools from the MCP server in raw
+        :class:`mcp.types.Tool` form, applying ``enable_tools`` and
+        ``disable_tools`` filtering.
+
+        The full (unfiltered) tool list is cached on ``_cached_tools`` so
+        :meth:`get_tool` can resolve names that were filtered out as well.
+
+        Returns:
+            `list[mcp.types.Tool]`:
+                Raw MCP tool descriptors after filtering.
+
+        Raises:
+            RuntimeError: If not connected (for stateful connections).
+        """
+        if not self.is_stateful:
+            # Stateless: create temporary session
+            async with self._get_client_gen() as cli:
+                read_stream, write_stream = cli[0], cli[1]
+                async with ClientSession(
+                    read_stream,
+                    write_stream,
+                ) as session:
+                    await session.initialize()
+                    res = await session.list_tools()
+                    self._cached_tools = res.tools
+        else:
+            # Stateful: use existing session
+            self._validate_connection()
+            res = await self._session.list_tools()
+            self._cached_tools = res.tools
+
+        available_tools: list = self._cached_tools
+        if self.enable_tools is not None:
+            available_tools = [
+                tool
+                for tool in available_tools
+                if tool.name in self.enable_tools
+            ]
+        if self.disable_tools is not None:
+            available_tools = [
+                _ for _ in available_tools if _.name not in self.disable_tools
+            ]
+        return available_tools
+
+    async def list_tools(self) -> list[ToolBase]:
+        """List available tools from the MCP server as wrapped
+        :class:`ToolBase` instances. If `enable_tools` and `disable_tools`
+        are not `None` in the constructor, the returned tools will be
+        filtered accordingly.
+
+        Returns:
+            `list[ToolBase]`:
+                List of available MCP tools.
+
+        Raises:
+            RuntimeError: If not connected (for stateful connections).
+        """
+        raw_tools = await self.list_raw_tools()
+        return [await self.get_tool(_.name) for _ in raw_tools]
+
+    async def get_tool(
+        self,
+        name: str,
+    ) -> MCPTool:
+        """Get a tool by name from the MCP server.
+
+        The returned MCPTool object implements ToolProtocol and can be:
+        - Called directly: `await tool(arg1=val1)`
+        - Registered to toolkit: `toolkit.register_tool(tool)`
+
+        Args:
+            name: The name of the tool function to get.
+
+        Returns:
+            A tool object that implements ToolProtocol.
+
+        Raises:
+            ValueError: If the tool is not found.
+            RuntimeError: If not connected (for stateful connections).
+        """
+        # Avoid circular import by importing here
+        from ..tool import MCPTool
+
+        # Fetch tools if not cached. Use list_raw_tools() to avoid the
+        # recursion list_tools() → get_tool() → list_tools().
+        if self._cached_tools is None:
+            await self.list_raw_tools()
+
+        # Find target tool
+        target_tool = None
+        for tool in self._cached_tools:
+            if tool.name == name:
+                target_tool = tool
+                break
+
+        if target_tool is None:
+            raise ValueError(
+                f"Tool '{name}' not found in MCP server " f"'{self.name}'",
+            )
+
+        # Create MCPTool based on stateful/stateless
+        if not self.is_stateful:
+            # Stateless: pass client generator
+            return MCPTool(
+                mcp_name=self.name,
+                tool=target_tool,
+                client_gen=self._get_client_gen,
+                timeout=self.execution_timeout,
+            )
+        else:
+            # Stateful: pass session
+            self._validate_connection()
+            return MCPTool(
+                mcp_name=self.name,
+                tool=target_tool,
+                session=self._session,
+                timeout=self.execution_timeout,
+            )
+
+    def _validate_connection(self) -> None:
+        """Validate connection state for stateful connections.
+
+        Raises:
+            RuntimeError: If not connected or session not initialized.
+        """
+        if not self._is_connected:
+            raise RuntimeError(
+                f"MCP '{self.name}' is not connected. "
+                "Call connect() first.",
+            )
+        if not self._session:
+            raise RuntimeError(
+                f"MCP '{self.name}' session is not initialized. "
+                "Call connect() first.",
+            )
diff --git a/src/agentscope/message/__init__.py b/src/agentscope/message/__init__.py
new file mode 100644
index 0000000..ccc8760
--- /dev/null
+++ b/src/agentscope/message/__init__.py
@@ -0,0 +1,39 @@
+# -*- coding: utf-8 -*-
+"""The message module in agentscope."""
+
+from ._block import (
+    ContentBlock,
+    ContentBlockTypes,
+    TextBlock,
+    ThinkingBlock,
+    HintBlock,
+    ToolCallBlock,
+    ToolCallState,
+    ToolResultBlock,
+    ToolResultState,
+    DataBlock,
+    Base64Source,
+    URLSource,
+)
+from ._base import Msg, UserMsg, AssistantMsg, SystemMsg, Usage
+
+
+__all__ = [
+    "TextBlock",
+    "ThinkingBlock",
+    "HintBlock",
+    "ToolCallBlock",
+    "ToolCallState",
+    "ToolResultBlock",
+    "ToolResultState",
+    "DataBlock",
+    "Base64Source",
+    "URLSource",
+    "ContentBlock",
+    "ContentBlockTypes",
+    "Msg",
+    "UserMsg",
+    "AssistantMsg",
+    "SystemMsg",
+    "Usage",
+]
diff --git a/src/agentscope/message/_base.py b/src/agentscope/message/_base.py
new file mode 100644
index 0000000..241fb09
--- /dev/null
+++ b/src/agentscope/message/_base.py
@@ -0,0 +1,618 @@
+# -*- coding: utf-8 -*-
+"""The message class in agentscope."""
+import base64
+from datetime import datetime
+from typing import Literal, List, overload, Sequence, Self, TYPE_CHECKING, Any
+
+from pydantic import BaseModel, Field, model_validator
+
+from .._utils._common import _generate_id
+from ._block import (
+    TextBlock,
+    ThinkingBlock,
+    HintBlock,
+    DataBlock,
+    Base64Source,
+    URLSource,
+    ToolCallBlock,
+    ToolCallState,
+    ToolResultBlock,
+    ToolResultState,
+    ContentBlock,
+    ContentBlockTypes,
+)
+from .._logging import logger
+
+if TYPE_CHECKING:
+    from ..event import AgentEvent
+else:
+    AgentEvent = Any
+
+
+def _assert_user_content_blocks(content: Sequence[ContentBlock]) -> None:
+    """Assert that the content blocks in user message are valid."""
+    for block in content:
+        if block.type not in ["text", "data"]:
+            raise ValueError(
+                "User message can only contain text blocks or data blocks.",
+            )
+
+
+def _assert_system_content_blocks(
+    content: Sequence[ContentBlock],
+) -> None:
+    """Assert that the content blocks in system message are valid."""
+    for block in content:
+        if block.type not in ["text"]:
+            raise ValueError("System message can only contain text blocks.")
+
+
+def _to_blocks(content: str | list) -> list:
+    """Convert a plain string to a single-element TextBlock list."""
+    if isinstance(content, str):
+        return [TextBlock(text=content)]
+    return content
+
+
+class Usage(BaseModel):
+    """The token usage information of a message."""
+
+    input_tokens: int
+    """The number of input tokens."""
+    output_tokens: int
+    """The number of output tokens."""
+
+
+class Msg(BaseModel):
+    """The message class in AgentScope, responsible for information storage
+    and transmission among different agents."""
+
+    name: str
+    """The name of the sender."""
+    content: list[ContentBlock]
+    """The message content as a list of content blocks."""
+    role: Literal["user", "assistant", "system"]
+    """The role of the sender."""
+    id: str = Field(default_factory=_generate_id)
+    """The message identifier."""
+    metadata: dict = Field(default_factory=dict)
+    """The metadata of the message"""
+    created_at: str = Field(default_factory=lambda: datetime.now().isoformat())
+    """The creation time of the message"""
+    finished_at: str | None = Field(default=None)
+    """The finished time of the message"""
+    usage: Usage | None = Field(default=None)
+    """The token usage information of the message"""
+
+    @model_validator(mode="after")
+    def validate_role_content(self) -> Self:
+        """Validate content blocks according to the role."""
+        match self.role:
+            case "user":
+                _assert_user_content_blocks(self.content)
+            case "system":
+                _assert_system_content_blocks(self.content)
+            case "assistant":
+                pass
+        return self
+
+    def has_content_blocks(
+        self,
+        block_type: ContentBlockTypes | list[ContentBlockTypes] | None = None,
+    ) -> bool:
+        """Check if the message has content blocks of the given type.
+
+        Args:
+            block_type (`ContentBlockTypes | list[ContentBlockTypes] | None`, \
+            optional):
+                The type of the block to be checked. If `None`, all blocks will
+                be checked. If a list is provided, it checks if there are
+                blocks of any types in the list.
+
+        Returns:
+            `bool`:
+                `True` if there are content blocks of the given type, `False`
+                otherwise.
+        """
+        if block_type is None:
+            return len(self.content) > 0
+
+        typs = [block_type] if isinstance(block_type, str) else block_type
+        return any(b.type in typs for b in self.content)
+
+    def get_text_content(self, separator: str = "\n") -> str | None:
+        """Get the concatenated text from all TextBlocks."""
+        gathered = [b.text for b in self.content if b.type == "text"]
+        return separator.join(gathered) if gathered else None
+
+    @overload
+    def get_content_blocks(
+        self,
+        block_type: Literal["text"],
+    ) -> list[TextBlock]:
+        ...
+
+    @overload
+    def get_content_blocks(
+        self,
+        block_type: Literal["thinking"],
+    ) -> list[ThinkingBlock]:
+        ...
+
+    @overload
+    def get_content_blocks(
+        self,
+        block_type: Literal["tool_call"],
+    ) -> list[ToolCallBlock]:
+        ...
+
+    @overload
+    def get_content_blocks(
+        self,
+        block_type: Literal["tool_result"],
+    ) -> list[ToolResultBlock]:
+        ...
+
+    @overload
+    def get_content_blocks(
+        self,
+        block_type: Literal["data"],
+    ) -> list[DataBlock]:
+        ...
+
+    @overload
+    def get_content_blocks(
+        self,
+        block_type: None = None,
+    ) -> list[ContentBlock]:
+        ...
+
+    @overload
+    def get_content_blocks(
+        self,
+        block_type: Literal["hint"],
+    ) -> list[HintBlock]:
+        ...
+
+    def get_content_blocks(
+        self,
+        block_type: ContentBlockTypes | List[ContentBlockTypes] | None = None,
+    ) -> Sequence[ContentBlock]:
+        """Get content blocks, optionally filtered by type.
+
+        Args:
+            block_type (`ContentBlockTypes | List[ContentBlockTypes] | None`, \
+            optional):
+                The type of the block to be extracted. If `None`, all blocks
+                will be returned.
+
+        Returns:
+            `List[ContentBlock]`:
+                The content blocks.
+        """
+        blocks: list[ContentBlock] = self.content or []
+        if isinstance(block_type, str):
+            blocks = [b for b in blocks if b.type == block_type]
+        elif isinstance(block_type, list):
+            blocks = [b for b in blocks if b.type in block_type]
+        return blocks
+
+    def _find_block(
+        self,
+        block_type: str,
+        block_id: str,
+    ) -> ContentBlock | None:
+        """Find a block in content by type and id."""
+        for block in self.content:
+            if block.type == block_type and block.id == block_id:
+                return block
+        return None
+
+    def append_event(self, event: AgentEvent) -> Self:
+        """Update the message by applying a streaming event.
+
+        Mutates ``self.content``, ``self.finished_at``, and ``self.usage``:
+        content blocks are appended/updated by block-level events,
+        ``finished_at`` is stamped by ``REPLY_END``, and ``usage`` is
+        initialized then accumulated across each ``MODEL_CALL_END``.
+        Events whose ``reply_id`` does not match ``self.id`` are skipped with
+        a warning. Block-level delta/end events whose target block cannot be
+        found are also skipped with a warning.
+
+        Args:
+            event (`AgentEvent`):
+                The event to apply.
+        """
+        from ..event import EventType  # local import to avoid circular dep
+
+        if event.reply_id != self.id:
+            logger.warning(
+                "Event %s with reply_id %r does not match message id %r, "
+                "skipping.",
+                event.__class__.__name__,
+                event.reply_id,
+                self.id,
+            )
+            return self
+
+        match event.type:
+            case EventType.REPLY_END:
+                self.finished_at = event.created_at
+
+            case EventType.MODEL_CALL_END:
+                if self.usage is None:
+                    self.usage = Usage(
+                        input_tokens=event.input_tokens,
+                        output_tokens=event.output_tokens,
+                    )
+                else:
+                    self.usage.input_tokens += event.input_tokens
+                    self.usage.output_tokens += event.output_tokens
+
+            case EventType.TEXT_BLOCK_START:
+                self.content.append(TextBlock(id=event.block_id, text=""))
+
+            case EventType.TEXT_BLOCK_DELTA:
+                block = self._find_block("text", event.block_id)
+                if block is None:
+                    logger.warning(
+                        "TextBlock %r not found, skipping.",
+                        event.block_id,
+                    )
+                else:
+                    block.text += event.delta
+
+            case EventType.TEXT_BLOCK_END:
+                pass
+
+            case EventType.DATA_BLOCK_START:
+                self.content.append(
+                    DataBlock(
+                        id=event.block_id,
+                        source=Base64Source(
+                            data="",
+                            media_type=event.media_type,
+                        ),
+                    ),
+                )
+
+            case EventType.DATA_BLOCK_DELTA:
+                block = self._find_block("data", event.block_id)
+                if block is None:
+                    logger.warning(
+                        "DataBlock %s not found, skipping.",
+                        event.block_id,
+                    )
+                elif event.data:
+                    # Each delta is an independently base64-encoded chunk
+                    # (with its own padding); naive string concat would
+                    # corrupt the byte stream. Decode, concat bytes, re-encode.
+                    existing = (
+                        base64.b64decode(block.source.data)
+                        if block.source.data
+                        else b""
+                    )
+                    incoming = base64.b64decode(event.data)
+                    block.source.data = base64.b64encode(
+                        existing + incoming,
+                    ).decode("ascii")
+
+            case EventType.DATA_BLOCK_END:
+                pass
+
+            case EventType.THINKING_BLOCK_START:
+                self.content.append(
+                    ThinkingBlock(id=event.block_id, thinking=""),
+                )
+
+            case EventType.THINKING_BLOCK_DELTA:
+                block = self._find_block("thinking", event.block_id)
+                if block is None:
+                    logger.warning(
+                        "ThinkingBlock %r not found, skipping.",
+                        event.block_id,
+                    )
+                else:
+                    block.thinking += event.delta
+
+            case EventType.THINKING_BLOCK_END:
+                pass
+
+            case EventType.HINT_BLOCK:
+                # One-shot event — the full HintBlock content arrives in
+                # a single event, so just append it to ``content`` for
+                # persistence and replay.
+                self.content.append(
+                    HintBlock(
+                        id=event.block_id,
+                        source=event.source,
+                        hint=event.hint,
+                    ),
+                )
+
+            case EventType.TOOL_CALL_START:
+                self.content.append(
+                    ToolCallBlock(
+                        id=event.tool_call_id,
+                        name=event.tool_call_name,
+                        input="",
+                    ),
+                )
+
+            case EventType.TOOL_CALL_DELTA:
+                block = self._find_block("tool_call", event.tool_call_id)
+                if block is None:
+                    logger.warning(
+                        "ToolCallBlock %r not found, skipping.",
+                        event.tool_call_id,
+                    )
+                else:
+                    assert isinstance(block, ToolCallBlock)
+                    block.input += event.delta
+
+            case EventType.TOOL_CALL_END:
+                pass
+
+            case EventType.TOOL_RESULT_START:
+                self.content.append(
+                    ToolResultBlock(
+                        id=event.tool_call_id,
+                        name=event.tool_call_name,
+                        output=[],
+                        state=ToolResultState.RUNNING,
+                    ),
+                )
+
+            case EventType.TOOL_RESULT_TEXT_DELTA:
+                block = self._find_block("tool_result", event.tool_call_id)
+                if block is None:
+                    logger.warning(
+                        "ToolResultBlock %r not found, skipping.",
+                        event.tool_call_id,
+                    )
+                else:
+                    assert isinstance(block, ToolResultBlock)
+                    if isinstance(block.output, str):
+                        block.output = [TextBlock(text=block.output)]
+                    # Append the text
+                    if not block.output or block.output[-1].type != "text":
+                        block.output.append(TextBlock(text=event.delta))
+                    else:
+                        block.output[-1].text += event.delta
+
+            case EventType.TOOL_RESULT_DATA_DELTA:
+                block = self._find_block("tool_result", event.tool_call_id)
+                if block is None:
+                    logger.warning(
+                        "ToolResultBlock %r not found, skipping.",
+                        event.tool_call_id,
+                    )
+                else:
+                    assert isinstance(block, ToolResultBlock)
+                    if isinstance(block.output, str):
+                        block.output = [TextBlock(text=block.output)]
+                    src = (
+                        Base64Source(
+                            data=event.data,
+                            media_type=event.media_type,
+                        )
+                        if event.data is not None
+                        else URLSource(
+                            url=str(event.url),
+                            media_type=event.media_type,
+                        )
+                    )
+                    block.output.append(
+                        DataBlock(id=event.block_id, source=src),
+                    )
+
+            case EventType.TOOL_RESULT_END:
+                block = self._find_block("tool_result", event.tool_call_id)
+                if block is None:
+                    logger.warning(
+                        "ToolResultBlock %r not found, skipping.",
+                        event.tool_call_id,
+                    )
+                else:
+                    assert isinstance(block, ToolResultBlock)
+                    block.state = event.state
+                    block.metadata = event.metadata
+                # The paired ToolCallBlock's lifecycle ends with its
+                # result — flip it to FINISHED here so the SSE-rebuilt
+                # reply_msg matches ``agent.state.context``, which
+                # ``_update_tool_call_state`` mutates directly.
+                call_block = self._find_block("tool_call", event.tool_call_id)
+                if call_block is not None:
+                    assert isinstance(call_block, ToolCallBlock)
+                    call_block.state = ToolCallState.FINISHED
+
+            case EventType.REQUIRE_USER_CONFIRM:
+                for tool_call in event.tool_calls:
+                    b = self._find_block("tool_call", tool_call.id)
+                    if b is not None:
+                        assert isinstance(b, ToolCallBlock)
+                        # Update the state
+                        b.state = ToolCallState.ASKING
+                        # Record the suggestions
+                        b.suggested_rules = tool_call.suggested_rules
+
+            case EventType.USER_CONFIRM_RESULT:
+                for result in event.confirm_results:
+                    b = self._find_block("tool_call", result.tool_call.id)
+                    # Only ASKING calls can transition; skip stale results
+                    # (e.g. arriving after an interrupt already resolved the
+                    # tool call).
+                    if b is not None and b.state == ToolCallState.ASKING:
+                        assert isinstance(b, ToolCallBlock)
+                        b.state = (
+                            ToolCallState.ALLOWED
+                            if result.confirmed
+                            else ToolCallState.FINISHED
+                        )
+
+            case EventType.REQUIRE_EXTERNAL_EXECUTION:
+                for tool_call in event.tool_calls:
+                    b = self._find_block("tool_call", tool_call.id)
+                    if b is not None:
+                        assert isinstance(b, ToolCallBlock)
+                        b.state = ToolCallState.SUBMITTED
+
+            case EventType.EXTERNAL_EXECUTION_RESULT:
+                # Skip results whose tool_call already has a tool_result
+                # (e.g. late arrival after an interrupt).
+                existing_ids = {
+                    b.id
+                    for b in self.content
+                    if isinstance(b, ToolResultBlock)
+                }
+                for result in event.execution_results:
+                    if result.id in existing_ids:
+                        continue
+                    self.content.append(result)
+
+        return self
+
+
+def UserMsg(
+    name: str,
+    content: str | list[TextBlock | DataBlock],
+    metadata: dict | None = None,
+    created_at: str | None = None,
+    finished_at: str | None = None,
+    id: str | None = None,  # pylint: disable=redefined-builtin
+) -> Msg:
+    """Create a user message with role ``"user"``.
+
+    Args:
+        name (`str`):
+            The name of the sender.
+        content (`str | list[TextBlock | DataBlock]`):
+            The message content. A plain string will be automatically wrapped
+            in a :class:`TextBlock`. Only :class:`TextBlock` and
+            :class:`DataBlock` are allowed for user messages.
+        metadata (`dict | None`, optional):
+            Arbitrary key-value metadata attached to the message. Defaults to
+            an empty dict when not provided.
+        created_at (`str | None`, optional):
+            ISO-format timestamp for when the message was created. Defaults to
+            the current time when not provided.
+        finished_at (`str | None`, optional):
+            ISO-format timestamp for when the message was finished. Defaults to
+            the same value as ``created_at`` when not provided.
+        id (`str | None`, optional):
+            A unique identifier for the message. A random UUID hex string is
+            generated when not provided.
+
+    Returns:
+        `Msg`:
+            A :class:`Msg` instance with ``role="user"``.
+    """
+    created_at = created_at or datetime.now().isoformat()
+    if finished_at is None:
+        finished_at = created_at
+    return Msg(
+        name=name,
+        content=_to_blocks(content),
+        role="user",
+        metadata=metadata or {},
+        created_at=created_at,
+        finished_at=finished_at,
+        id=id or _generate_id(),
+    )
+
+
+def AssistantMsg(
+    name: str,
+    content: str | list[ContentBlock],
+    metadata: dict | None = None,
+    created_at: str | None = None,
+    finished_at: str | None = None,
+    id: str | None = None,  # pylint: disable=redefined-builtin
+    usage: Usage | None = None,
+) -> Msg:
+    """Create an assistant message with role ``"assistant"``.
+
+    Args:
+        name (`str`):
+            The name of the sender.
+        content (`str | list[ContentBlock]`):
+            The message content. A plain string will be automatically wrapped
+            in a :class:`TextBlock`. Any :class:`ContentBlock` subtype is
+            permitted for assistant messages.
+        metadata (`dict | None`, optional):
+            Arbitrary key-value metadata attached to the message. Defaults to
+            an empty dict when not provided.
+        created_at (`str | None`, optional):
+            ISO-format timestamp for when the message was created. Defaults to
+            the current time when not provided.
+        finished_at (`str | None`, optional):
+            ISO-format timestamp for when the message was finished. Not set by
+            default for assistant messages.
+        id (`str | None`, optional):
+            A unique identifier for the message. A random UUID hex string is
+            generated when not provided.
+        usage (`Usage | None`, optional):
+            The token usage information of the message.
+
+    Returns:
+        `Msg`:
+            A :class:`Msg` instance with ``role="assistant"``.
+    """
+    return Msg(
+        name=name,
+        content=_to_blocks(content),
+        role="assistant",
+        metadata=metadata or {},
+        created_at=created_at or datetime.now().isoformat(),
+        finished_at=finished_at,
+        id=id or _generate_id(),
+        usage=usage,
+    )
+
+
+def SystemMsg(
+    name: str,
+    content: str | list[TextBlock],
+    metadata: dict | None = None,
+    created_at: str | None = None,
+    finished_at: str | None = None,
+    id: str | None = None,  # pylint: disable=redefined-builtin
+) -> Msg:
+    """Create a system message with role ``"system"``.
+
+    Args:
+        name (`str`):
+            The name of the sender.
+        content (`str | list[TextBlock]`):
+            The message content. A plain string will be automatically wrapped
+            in a :class:`TextBlock`. Only :class:`TextBlock` is allowed for
+            system messages.
+        metadata (`dict | None`, optional):
+            Arbitrary key-value metadata attached to the message. Defaults to
+            an empty dict when not provided.
+        created_at (`str | None`, optional):
+            ISO-format timestamp for when the message was created. Defaults to
+            the current time when not provided.
+        finished_at (`str | None`, optional):
+            ISO-format timestamp for when the message was finished. Defaults to
+            the same value as ``created_at`` when not provided.
+        id (`str | None`, optional):
+            A unique identifier for the message. A random UUID hex string is
+            generated when not provided.
+
+    Returns:
+        `Msg`:
+            A :class:`Msg` instance with ``role="system"``.
+    """
+    created_at = created_at or datetime.now().isoformat()
+    if finished_at is None:
+        finished_at = created_at
+    return Msg(
+        name=name,
+        content=_to_blocks(content),
+        role="system",
+        metadata=metadata or {},
+        created_at=created_at,
+        finished_at=finished_at,
+        id=id or _generate_id(),
+    )
diff --git a/src/agentscope/message/_block.py b/src/agentscope/message/_block.py
new file mode 100644
index 0000000..38201ff
--- /dev/null
+++ b/src/agentscope/message/_block.py
@@ -0,0 +1,203 @@
+# -*- coding: utf-8 -*-
+"""The content blocks of messages."""
+from enum import StrEnum
+from typing import Literal, List, TypeAlias, Any
+from pydantic import BaseModel, Field, AnyUrl, field_serializer, ConfigDict
+
+from .._utils._common import _generate_id
+from ..permission import PermissionRule
+
+
+class TextBlock(BaseModel):
+    """The text block."""
+
+    type: Literal["text"] = "text"
+    """The type of the text block, which is always 'text'."""
+    text: str
+    """The text content of the block."""
+    id: str = Field(default_factory=_generate_id)
+    """The unique identifier of the block."""
+
+
+class ThinkingBlock(BaseModel):
+    """The thinking block.
+
+    Allows extra provider-specific fields (e.g. Anthropic's ``signature``)
+    via ``extra="allow"`` so that model implementations can pass
+    arbitrary metadata without subclassing.
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    type: Literal["thinking"] = "thinking"
+    """The type of the thinking block, which is always 'thinking'."""
+    thinking: str
+    """The thinking content of the block."""
+    id: str = Field(default_factory=_generate_id)
+    """The unique identifier of the block."""
+
+
+class Base64Source(BaseModel):
+    """The base64 source."""
+
+    type: Literal["base64"] = "base64"
+    """The type of the base64 source, which is always 'base64'."""
+    data: str
+    """The base64-encoded data."""
+    media_type: str
+    """The media type of the data, e.g., 'image/png', 'audio/mpeg', etc."""
+
+
+class URLSource(BaseModel):
+    """The URL source."""
+
+    type: Literal["url"] = "url"
+    """The type of the URL source, which is always 'url'."""
+    url: AnyUrl
+    """A valid URI string conforming to RFC 3986."""
+    media_type: str
+    """The media type of the data, e.g., 'image/png', 'audio/mpeg', etc."""
+
+    @field_serializer("url")
+    def serialize_url(self, url: AnyUrl) -> str:
+        """Serialize the URL to a string."""
+        return str(url)
+
+
+class DataBlock(BaseModel):
+    """The data block for binary content (images, audio, video, etc.)."""
+
+    type: Literal["data"] = "data"
+    """The type of the data block, which is always 'data'."""
+    id: str = Field(default_factory=_generate_id)
+    """The unique identifier of the block."""
+    source: Base64Source | URLSource
+    """The source of the data, which can be either a base64-encoded string or
+    a URL."""
+    name: str | None = None
+    """The name of the data block, which is optional."""
+
+
+class HintBlock(BaseModel):
+    """A block used to provide instructions or hints to the LLM during the
+    reasoning-acting loop. When passed to the LLM API, the hint block is
+    converted into a user message.
+
+    The ``hint`` field can be a plain string (text-only) or a list of
+    :class:`TextBlock` / :class:`DataBlock` for multimodal content
+    (e.g. a background tool result containing both text and an image).
+    """
+
+    type: Literal["hint"] = "hint"
+    """The type of the hint block, which is always 'hint'."""
+    hint: str | list[TextBlock | DataBlock]
+    """The hint content — plain text or a list of content blocks for
+    multimodal data."""
+    id: str = Field(default_factory=_generate_id)
+    """The unique identifier of the block."""
+    source: str | None = None
+    """The sender or origin of this hint. For team messages this is the
+    sender's display name (e.g. ``"alice"``); for system notifications
+    it may be ``"system"`` or ``None``."""
+
+
+class ToolCallState(StrEnum):
+    """The state of the tool call."""
+
+    PENDING = "pending"
+    ASKING = "asking"
+    ALLOWED = "allowed"
+    SUBMITTED = "submitted"
+    FINISHED = "finished"
+
+
+class ToolCallBlock(BaseModel):
+    """The tool call block."""
+
+    model_config = ConfigDict(use_enum_values=True)
+
+    type: Literal["tool_call"] = "tool_call"
+    """The type of the tool call block, which is always 'tool_call'."""
+    id: str
+    """The unique identifier of the tool call block."""
+    name: str
+    """The name of the tool to be called."""
+    input: str
+    """The raw JSON string input of the tool, accumulated during streaming."""
+    state: ToolCallState = ToolCallState.PENDING
+    """The tool call state
+    - 'pending': the initial state when the tool call hasn't been processed
+     by the permission system
+    - 'asking': the tool call is asking and waiting for user confirmation
+    - 'allowed': allowed by the permission system/user and waits for execution
+    - 'submitted': the tool call has been submitted for external execution
+     and is waiting for results event
+
+    Transitions
+    -----------
+    pending
+      ├── permission DENY / input validation failed ──► finished
+      ├── permission ASK ──────────────────────────── ► asking
+      │       ├── user denied ───────────────────────► finished
+      │       └── user approved ─────────────────────► allowed
+      └── permission ALLOW ────────────────────────── ► allowed
+
+    allowed
+      ├── local tool  ── (execute) ─────────────────► finished
+      └── external tool ──────────────────────────── ► submitted
+
+    submitted
+      └── ExternalExecutionResultEvent received ─────► finished
+    """
+    suggested_rules: list[PermissionRule] = Field(default_factory=list)
+    """The suggestions for this tool call when asking user, used to maintain
+    the suggestions across requests."""
+
+
+class ToolResultState(StrEnum):
+    """The tool result state."""
+
+    SUCCESS = "success"
+    ERROR = "error"
+    INTERRUPTED = "interrupted"
+    DENIED = "denied"
+    RUNNING = "running"
+
+
+class ToolResultBlock(BaseModel):
+    """The tool result block."""
+
+    model_config = ConfigDict(use_enum_values=True)
+
+    type: Literal["tool_result"] = "tool_result"
+    """The type of the tool result block, which is always 'tool_result'."""
+    id: str
+    """The unique identifier of the tool result block."""
+    name: str
+    """The name of the tool."""
+    output: str | List[TextBlock | DataBlock]
+    """The output of the tool, which can be a raw string of a list of
+    text and multimodal blocks."""
+    state: ToolResultState = ToolResultState.RUNNING
+    """The execution state of the tool."""
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    """The metadata of the tool result block."""
+
+
+ContentBlock: TypeAlias = (
+    TextBlock
+    | ThinkingBlock
+    | HintBlock
+    | ToolCallBlock
+    | ToolResultBlock
+    | DataBlock
+)
+
+ContentBlockTypes: TypeAlias = Literal[
+    "text",
+    "thinking",
+    "hint",
+    "tool_call",
+    "tool_result",
+    "data",
+]
diff --git a/src/agentscope/middleware/__init__.py b/src/agentscope/middleware/__init__.py
new file mode 100644
index 0000000..822b56c
--- /dev/null
+++ b/src/agentscope/middleware/__init__.py
@@ -0,0 +1,24 @@
+# -*- coding: utf-8 -*-
+"""Middleware system for AgentScope agents."""
+
+from ._base import MiddlewareBase
+from ._rag import RAGMiddleware
+from ._budget import ReplyBudgetControlMiddleware
+from ._longterm_memory import (
+    AgenticMemoryMiddleware,
+    Mem0Middleware,
+    ReMeMiddleware,
+)
+from ._tracing import TracingMiddleware
+from ._tts_middleware import TTSMiddleware
+
+__all__ = [
+    "MiddlewareBase",
+    "AgenticMemoryMiddleware",
+    "Mem0Middleware",
+    "ReMeMiddleware",
+    "RAGMiddleware",
+    "TracingMiddleware",
+    "ReplyBudgetControlMiddleware",
+    "TTSMiddleware",
+]
diff --git a/src/agentscope/middleware/_base.py b/src/agentscope/middleware/_base.py
new file mode 100644
index 0000000..2fc4de9
--- /dev/null
+++ b/src/agentscope/middleware/_base.py
@@ -0,0 +1,250 @@
+# -*- coding: utf-8 -*-
+"""Base middleware class for AgentScope middleware system."""
+from typing import AsyncGenerator, Awaitable, Callable, TYPE_CHECKING
+
+from ..tool import ToolBase
+
+if TYPE_CHECKING:
+    from ..agent import Agent
+    from ..model import ChatResponse
+
+
+class MiddlewareBase:  # pylint: disable=unused-argument
+    """Base class for all middleware implementations.
+
+    Middleware provides interception mechanisms at 5 key execution points
+    in the Agent lifecycle:
+
+    **Onion Pattern Hooks** (with before/after logic):
+    - `on_reply`: Intercepts the entire reply process
+    - `on_reasoning`: Intercepts the reasoning/model call phase
+    - `on_acting`: Intercepts individual tool call execution
+    - `on_model_call`: Intercepts the raw model API call
+
+    **Transformer Pattern Hook** (sequential pipeline):
+    - `on_system_prompt`: Transforms the system prompt string
+
+    Each hook is optional - only implement the ones you need. The middleware
+    system will automatically detect which hooks are implemented at runtime.
+
+    Example:
+        ```python
+        class LoggingMiddleware(MiddlewareBase):
+            async def on_reasoning(
+                self,
+                agent: Agent,
+                input_kwargs: dict,
+                next_handler: Callable[[], AsyncGenerator],
+            ) -> AsyncGenerator:
+                print(f"Before reasoning for agent {agent.name}")
+                async for event in next_handler():
+                    yield event
+                print(f"After reasoning for agent {agent.name}")
+
+        agent = Agent(
+            ...
+            middlewares=[LoggingMiddleware()],
+            ...
+        )
+        ```
+    """
+
+    def is_implemented(self, hook_name: str) -> bool:
+        """Check if a hook method is implemented in the subclass.
+
+        Args:
+            hook_name: Name of the hook method to check
+
+        Returns:
+            True if the hook is implemented (overridden), False otherwise
+        """
+        base_method = getattr(MiddlewareBase, hook_name, None)
+        sub_method = getattr(type(self), hook_name, None)
+        return base_method is not sub_method
+
+    async def on_reply(
+        self,
+        agent: "Agent",
+        input_kwargs: dict,
+        next_handler: Callable[..., AsyncGenerator],
+    ) -> AsyncGenerator:
+        """Hook for intercepting the reply process.
+
+        Args:
+            agent: The Agent instance executing this middleware
+            input_kwargs: Dictionary containing:
+                - inputs: Msg | list[Msg] | UserConfirmResultEvent |
+                ExternalExecutionResultEvent | None — the unified inputs
+                that trigger this reply (new message(s), a resumption
+                event from a previous outside interaction, or None).
+            next_handler: Callable that executes the next middleware or
+             original method
+
+        Yields:
+            AgentEvent | Msg: Events from the reply process
+        """
+        raise RuntimeError(
+            f"{type(self).__name__} does not implement on_reply",
+        )
+        yield  # pylint: disable=unreachable
+
+    async def on_reasoning(
+        self,
+        agent: "Agent",
+        input_kwargs: dict,
+        next_handler: Callable[..., AsyncGenerator],
+    ) -> AsyncGenerator:
+        """Hook for intercepting the reasoning process.
+
+        Args:
+            agent: The Agent instance executing this middleware
+            input_kwargs: Dictionary containing:
+                - tool_choice: ToolChoice (default None)
+            next_handler: Callable that executes the next middleware or
+            original method
+
+        Yields:
+            Various events from the reasoning process
+        """
+        raise RuntimeError(
+            f"{type(self).__name__} does not implement on_reasoning",
+        )
+        yield  # pylint: disable=unreachable
+
+    async def on_acting(
+        self,
+        agent: "Agent",
+        input_kwargs: dict,
+        next_handler: Callable[..., AsyncGenerator],
+    ) -> AsyncGenerator:
+        """Hook for intercepting the raw tool execution.
+
+        This hook wraps **only** the ``toolkit.call_tool`` call — i.e. the
+        pure I/O execution layer.  Permission checking, input validation, and
+        context writes are handled by the agent **outside** this hook and are
+        therefore not visible here.
+
+        This separation makes it safe to offload the ``next_handler``
+        coroutine to a background task: it will never mutate agent context
+        on its own.
+
+        .. note::
+            Tools with ``is_state_injected=True`` receive the live
+            ``agent.state`` object.  Offloading such tools to a background
+            task may cause concurrent state mutations — guard against this
+            in your middleware implementation.
+
+        Args:
+            agent (`Agent`):
+                The Agent instance executing this middleware.
+            input_kwargs (`dict`):
+                Dictionary containing:
+
+                - ``tool_call`` (``ToolCallBlock``): the tool call to execute.
+                  By the time this hook is invoked the tool call has already
+                  been validated and permitted.
+            next_handler (`Callable[..., AsyncGenerator]`):
+                Callable that executes the next middleware or
+                ``_acting_impl``.
+
+        Yields:
+            `ToolChunk | ToolResponse`:
+                Intermediate ``ToolChunk`` objects followed by a final
+                ``ToolResponse`` produced by the tool.
+        """
+        raise RuntimeError(
+            f"{type(self).__name__} does not implement on_acting",
+        )
+        yield  # pylint: disable=unreachable
+
+    async def on_model_call(
+        self,
+        agent: "Agent",
+        input_kwargs: dict,
+        next_handler: Callable[
+            ...,
+            Awaitable["ChatResponse" | AsyncGenerator["ChatResponse", None]],
+        ],
+    ) -> "ChatResponse" | AsyncGenerator["ChatResponse", None]:
+        """Hook for intercepting the model API call.
+
+        Args:
+            agent: The Agent instance executing this middleware
+            input_kwargs: Dictionary containing:
+                - messages: list[Msg]
+                - tools: list[dict]
+                - tool_choice: ToolChoice
+                - current_model: The model instance used for this call
+            next_handler: Callable that executes the next middleware or
+            original method
+
+        Returns:
+            ChatResponse or AsyncGenerator[ChatResponse, None]
+        """
+        raise RuntimeError(
+            f"{type(self).__name__} does not implement on_model_call",
+        )
+
+    async def on_compress_context(
+        self,
+        agent: "Agent",
+        input_kwargs: dict,
+        next_handler: Callable[..., Awaitable[None]],
+    ) -> None:
+        """Onion hook for `compress_context` function in `Agent` class
+
+        Args:
+            agent (`Agent`):
+                The Agent instance executing this middleware
+            input_kwargs (`dict`):
+                Dictionary containing:
+                - context_config: ContextConfig | None
+                - instructions: HintBlock | None
+            next_handler (`Callable[..., Awaitable[None]]`):
+                Callable that executes the next middleware or
+                original method
+        """
+        raise RuntimeError(
+            f"{type(self).__name__} does not implement on_compress_context",
+        )
+
+    async def on_system_prompt(
+        self,
+        agent: "Agent",
+        current_prompt: str,
+    ) -> str:
+        """Transform the system prompt string.
+
+        This uses a transformer/pipeline pattern rather than onion pattern.
+        Multiple middlewares are applied sequentially, each receiving the
+        output of the previous one.
+
+        Args:
+            agent: The Agent instance executing this middleware
+            current_prompt: The current system prompt string
+
+        Returns:
+            str: The transformed system prompt
+        """
+        raise RuntimeError(
+            f"{type(self).__name__} does not implement on_system_prompt",
+        )
+
+    async def list_tools(self) -> list[ToolBase]:
+        """List available tools provided by this middleware. Optional to
+        implement.
+
+        Returns:
+            `list[ToolBase]`:
+                A list of tools provided by this middleware.
+        """
+        return []
+
+    async def get_middleware_key(self) -> str:
+        """Get the unique key for this middleware, used to save middleware
+        states in `AgentState` instances.
+
+        Optionally, middleware classes can override this method to
+        provide their own unique key.
+        """
+        return self.__class__.__name__
diff --git a/src/agentscope/middleware/_budget.py b/src/agentscope/middleware/_budget.py
new file mode 100644
index 0000000..53c56b3
--- /dev/null
+++ b/src/agentscope/middleware/_budget.py
@@ -0,0 +1,207 @@
+# -*- coding: utf-8 -*-
+"""Budget control middleware for AgentScope agents."""
+from typing import AsyncGenerator, Callable, TYPE_CHECKING
+
+from ..event import ModelCallEndEvent, ReplyStartEvent, ReplyEndEvent
+from ..message import AssistantMsg, HintBlock
+from ..tool import ToolChoice
+from ._base import MiddlewareBase
+
+if TYPE_CHECKING:
+    from ..agent import Agent
+
+_DEFAULT_HINT_MESSAGE = (
+    "<system-reminder>You have reached the maximum token budget set by the "
+    "user. Now you MUST wrap up immediately and provide a final "
+    "concluding response without invoking any tools."
+    "</system-reminder>"
+)
+
+
+class ReplyBudgetControlMiddleware(MiddlewareBase):
+    """Middleware that enforces a weighted token budget per reply.
+
+    Tracks cumulative weighted token usage across all reasoning steps within
+    a single reply. The weighted cost is computed as::
+
+    cost = input_token_weight * input_tokens + output_token_weight * \
+    output_tokens
+
+    Once the accumulated cost reaches ``token_budget``, a hint message is
+    injected into the agent's context before the next reasoning step, and
+    ``tool_choice`` is forced to ``"none"`` so the agent wraps up without
+    invoking any further tools.
+
+    Budget state is stored in
+    :attr:`~agentscope.agent.AgentState.middle_context`
+    keyed by the middleware key, so it persists across human-in-the-loop (HITL)
+    interruptions and resumptions. State is automatically cleaned up when the
+    reply ends via a :class:`~agentscope.event.ReplyEndEvent`.
+
+    .. note::
+        The middleware is stateless on the instance itself — all runtime state
+        lives in ``agent.state.middle_context``. This means the same middleware
+        instance can safely be shared across multiple agents.
+
+    Example::
+
+        from agentscope.middleware import BudgetControlMiddleware
+
+        agent = Agent(
+            ...,
+            middlewares=[
+                BudgetControlMiddleware(
+                    token_budget=10000,
+                    input_token_weight=1.0,
+                    output_token_weight=2.0,
+                )
+            ],
+        )
+
+    """
+
+    def __init__(
+        self,
+        token_budget: float,
+        input_token_weight: float = 1,
+        output_token_weight: float = 1,
+        hint_message: str = _DEFAULT_HINT_MESSAGE,
+    ) -> None:
+        """Initialize the budget control middleware.
+
+        Args:
+            token_budget (`float`):
+                Maximum weighted token cost allowed per reply. The cost for
+                each model call is computed as
+                ``input_token_weight * input_tokens + output_token_weight *
+                output_tokens``. Once the accumulated cost reaches this
+                threshold, the agent is instructed to wrap up without calling
+                any more tools.
+            input_token_weight (`float`, optional):
+                Multiplier applied to input tokens when computing the
+                weighted cost. Defaults to ``1``.
+            output_token_weight (`float`, optional):
+                Multiplier applied to output tokens when computing the
+                weighted cost. Defaults to ``1``. Set this higher than
+                ``input_token_weight`` to reflect that output tokens are
+                typically more expensive.
+            hint_message (`str`, optional):
+                The message injected into the agent's context when the budget
+                is exceeded. Defaults to a built-in wrap-up prompt.
+        """
+        self.token_budget = token_budget
+        self.input_token_weight = input_token_weight
+        self.output_token_weight = output_token_weight
+
+        self.hint_message = hint_message
+
+    async def on_reply(
+        self,
+        agent: "Agent",
+        input_kwargs: dict,
+        next_handler: Callable[..., AsyncGenerator],
+    ) -> AsyncGenerator:
+        """Manage per-reply budget state in ``agent.state.middle_context``.
+
+        Initializes the weighted cost counter for the reply on
+        :class:`~agentscope.event.ReplyStartEvent`, accumulates cost on each
+        :class:`~agentscope.event.ModelCallEndEvent`, and removes the entry on
+        :class:`~agentscope.event.ReplyEndEvent`.
+
+        Args:
+            agent (`Agent`):
+                The agent instance executing this middleware.
+            input_kwargs (`dict`):
+                Reply input kwargs (passed through unchanged).
+            next_handler (`Callable[..., AsyncGenerator]`):
+                Callable that executes the next middleware or ``_reply``.
+
+        Yields:
+            Events from the reply process.
+        """
+
+        middleware_key = await self.get_middleware_key()
+
+        async for event in next_handler(**input_kwargs):
+            if isinstance(event, ReplyStartEvent):
+                # Initialize the token counting number
+                if middleware_key not in agent.state.middle_context:
+                    agent.state.middle_context[middleware_key] = {}
+                agent.state.middle_context[middleware_key][event.reply_id] = 0
+
+            elif isinstance(event, ReplyEndEvent):
+                # Clean up the token counting number
+                agent.state.middle_context[middleware_key].pop(
+                    event.reply_id,
+                    None,
+                )
+
+            elif isinstance(event, ModelCallEndEvent):
+                # Update the used tokens
+                if middleware_key not in agent.state.middle_context:
+                    agent.state.middle_context[middleware_key] = {}
+                agent.state.middle_context[middleware_key][event.reply_id] += (
+                    self.input_token_weight * event.input_tokens
+                    + self.output_token_weight * event.output_tokens
+                )
+
+            yield event
+
+    async def on_reasoning(
+        self,
+        agent: "Agent",
+        input_kwargs: dict,
+        next_handler: Callable[..., AsyncGenerator],
+    ) -> AsyncGenerator:
+        """Intercept each reasoning step to enforce the token budget.
+
+        Before forwarding to the next handler, reads the accumulated weighted
+        cost for the current reply from ``agent.state.middle_context``. If the
+        budget is exhausted, appends a
+        :class:`~agentscope.message.HintBlock` to the last assistant message
+        in context (or creates a new
+        :class:`~agentscope.message.AssistantMsg`) and overrides
+        ``tool_choice`` to ``ToolChoice(mode="none")``.
+
+        Args:
+            agent (`Agent`):
+                The agent instance executing this middleware.
+            input_kwargs (`dict`):
+                Dictionary containing ``tool_choice`` and other reasoning
+                kwargs forwarded to the next handler.
+            next_handler (`Callable[..., AsyncGenerator]`):
+                Callable that executes the next middleware or
+                ``_reasoning_impl``.
+
+        Yields:
+            Events from the reasoning process.
+        """
+        reply_id = agent.state.reply_id
+        middleware_key = await self.get_middleware_key()
+        used = agent.state.middle_context.get(
+            middleware_key,
+            {},
+        ).get(reply_id, 0)
+
+        # Insert hint block if exceeded budget
+        if used >= self.token_budget:
+            hint_block = HintBlock(hint=self.hint_message)
+            if (
+                len(agent.state.context) > 0
+                and agent.state.context[-1].role == "assistant"
+                and agent.state.context[-1].name == agent.name
+            ):
+                agent.state.context[-1].content.append(hint_block)
+
+            else:
+                agent.state.context.append(
+                    AssistantMsg(
+                        id=agent.state.reply_id,
+                        name=agent.name,
+                        content=[hint_block],
+                    ),
+                )
+            input_kwargs["tool_choice"] = ToolChoice(mode="none")
+
+        async for event in next_handler(**input_kwargs):
+            yield event
diff --git a/src/agentscope/middleware/_longterm_memory/__init__.py b/src/agentscope/middleware/_longterm_memory/__init__.py
new file mode 100644
index 0000000..ca2fd3d
--- /dev/null
+++ b/src/agentscope/middleware/_longterm_memory/__init__.py
@@ -0,0 +1,12 @@
+# -*- coding: utf-8 -*-
+"""Long-term memory middlewares for AgentScope agents."""
+
+from ._agentic_memory import AgenticMemoryMiddleware
+from ._mem0 import Mem0Middleware
+from ._reme import ReMeMiddleware
+
+__all__ = [
+    "AgenticMemoryMiddleware",
+    "Mem0Middleware",
+    "ReMeMiddleware",
+]
diff --git a/src/agentscope/middleware/_longterm_memory/_agentic_memory/__init__.py b/src/agentscope/middleware/_longterm_memory/_agentic_memory/__init__.py
new file mode 100644
index 0000000..6c0a8cf
--- /dev/null
+++ b/src/agentscope/middleware/_longterm_memory/_agentic_memory/__init__.py
@@ -0,0 +1,6 @@
+# -*- coding: utf-8 -*-
+"""File-backed long-term memory middleware."""
+
+from ._middleware import AgenticMemoryMiddleware
+
+__all__ = ["AgenticMemoryMiddleware"]
diff --git a/src/agentscope/middleware/_longterm_memory/_agentic_memory/_middleware.py b/src/agentscope/middleware/_longterm_memory/_agentic_memory/_middleware.py
new file mode 100644
index 0000000..255b22b
--- /dev/null
+++ b/src/agentscope/middleware/_longterm_memory/_agentic_memory/_middleware.py
@@ -0,0 +1,802 @@
+# -*- coding: utf-8 -*-
+"""Filesystem-backed long-term memory middleware.
+
+The middleware keeps a workspace-local Markdown memory store, injects a
+bounded ``MEMORY.md`` index into the system prompt, and can asynchronously
+surface relevant topic files as hint blocks during the reasoning loop.
+"""
+from __future__ import annotations
+
+import asyncio
+import re
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, AsyncGenerator, Callable
+
+from pydantic import BaseModel, Field
+
+from ..._base import MiddlewareBase
+from ...._logging import logger
+from ...._utils._common import _estimate_tokens, _estimate_bytes
+from ....message import Msg, SystemMsg, UserMsg, HintBlock
+from ....model import ChatModelBase
+from ....tool import BackendBase, LocalBackend
+
+if TYPE_CHECKING:
+    from ....agent import Agent
+
+
+@dataclass(slots=True)
+class _MemoryFileHeader:
+    """Lightweight header for one memory file, read from frontmatter only."""
+
+    filename: str
+    """Relative path under the memory directory (e.g. ``user_role.md``)."""
+    path: str
+    """Absolute path inside the backend."""
+    description: str | None
+    """One-line description from frontmatter; ``None`` when absent."""
+    type: str | None
+    """Memory type tag from frontmatter (user/feedback/project/reference)."""
+    mtime: float | None
+    """Modification time as a Unix timestamp; ``None`` when unavailable."""
+
+
+DEFAULT_MEMORY_INSTRUCTIONS = """# Auto Memory
+
+You have a persistent, file-based memory system at `{memory_dir}`. This directory already exists — write to it directly with the `Write` tool (do not run mkdir or check for its existence).
+
+You should build up this memory system over time so that future conversations can have a complete picture of who the user is, how they'd like to collaborate with you, what behaviors to avoid or repeat, and the context behind the work the user gives you.
+
+If the user explicitly asks you to remember something, save it immediately as whichever type fits best. If they ask you to forget something, find and remove the relevant entry.
+
+## Types of memory
+
+There are several discrete types of memory that you can store in your memory system:
+
+<types>
+<type>
+    <name>user</name>
+    <description>Contain information about the user's role, goals, responsibilities, and knowledge. Great user memories help you tailor your future behavior to the user's preferences and perspective. Your goal in reading and writing these memories is to build up an understanding of who the user is and how you can be most helpful to them specifically. For example, you should collaborate with a senior software engineer differently than a student who is coding for the very first time. Keep in mind, that the aim here is to be helpful to the user. Avoid writing memories about the user that could be viewed as a negative judgement or that are not relevant to the work you're trying to accomplish together.</description>
+    <when_to_save>When you learn any details about the user's role, preferences, responsibilities, or knowledge</when_to_save>
+    <how_to_use>When your work should be informed by the user's profile or perspective. For example, if the user is asking you to explain a part of the code, you should answer that question in a way that is tailored to the specific details that they will find most valuable or that helps them build their mental model in relation to domain knowledge they already have.</how_to_use>
+    <examples>
+    user: I'm a data scientist investigating what logging we have in place
+    assistant: [saves user memory: user is a data scientist, currently focused on observability/logging]
+
+    user: I've been writing Go for ten years but this is my first time touching the React side of this repo
+    assistant: [saves user memory: deep Go expertise, new to React and this project's frontend — frame frontend explanations in terms of backend analogues]
+    </examples>
+</type>
+<type>
+    <name>feedback</name>
+    <description>Guidance the user has given you about how to approach work — both what to avoid and what to keep doing. These are a very important type of memory to read and write as they allow you to remain coherent and responsive to the way you should approach work in the project. Record from failure AND success: if you only save corrections, you will avoid past mistakes but drift away from approaches the user has already validated, and may grow overly cautious.</description>
+    <when_to_save>Any time the user corrects your approach ("no not that", "don't", "stop doing X") OR confirms a non-obvious approach worked ("yes exactly", "perfect, keep doing that", accepting an unusual choice without pushback). Corrections are easy to notice; confirmations are quieter — watch for them. In both cases, save what is applicable to future conversations, especially if surprising or not obvious from the code. Include *why* so you can judge edge cases later.</when_to_save>
+    <how_to_use>Let these memories guide your behavior so that the user does not need to offer the same guidance twice.</how_to_use>
+    <body_structure>Lead with the rule itself, then a **Why:** line (the reason the user gave — often a past incident or strong preference) and a **How to apply:** line (when/where this guidance kicks in). Knowing *why* lets you judge edge cases instead of blindly following the rule.</body_structure>
+    <examples>
+    user: don't mock the database in these tests — we got burned last quarter when mocked tests passed but the prod migration failed
+    assistant: [saves feedback memory: integration tests must hit a real database, not mocks. Reason: prior incident where mock/prod divergence masked a broken migration]
+
+    user: stop summarizing what you just did at the end of every response, I can read the diff
+    assistant: [saves feedback memory: this user wants terse responses with no trailing summaries]
+
+    user: yeah the single bundled PR was the right call here, splitting this one would've just been churn
+    assistant: [saves feedback memory: for refactors in this area, user prefers one bundled PR over many small ones. Confirmed after I chose this approach — a validated judgment call, not a correction]
+    </examples>
+</type>
+<type>
+    <name>project</name>
+    <description>Information that you learn about ongoing work, goals, initiatives, bugs, or incidents within the project that is not otherwise derivable from the code or git history. Project memories help you understand the broader context and motivation behind the work the user is doing within this working directory.</description>
+    <when_to_save>When you learn who is doing what, why, or by when. These states change relatively quickly so try to keep your understanding of this up to date. Always convert relative dates in user messages to absolute dates when saving (e.g., "Thursday" → "2026-03-05"), so the memory remains interpretable after time passes.</when_to_save>
+    <how_to_use>Use these memories to more fully understand the details and nuance behind the user's request and make better informed suggestions.</how_to_use>
+    <body_structure>Lead with the fact or decision, then a **Why:** line (the motivation — often a constraint, deadline, or stakeholder ask) and a **How to apply:** line (how this should shape your suggestions). Project memories decay fast, so the why helps future-you judge whether the memory is still load-bearing.</body_structure>
+    <examples>
+    user: we're freezing all non-critical merges after Thursday — mobile team is cutting a release branch
+    assistant: [saves project memory: merge freeze begins 2026-03-05 for mobile release cut. Flag any non-critical PR work scheduled after that date]
+
+    user: the reason we're ripping out the old auth middleware is that legal flagged it for storing session tokens in a way that doesn't meet the new compliance requirements
+    assistant: [saves project memory: auth middleware rewrite is driven by legal/compliance requirements around session token storage, not tech-debt cleanup — scope decisions should favor compliance over ergonomics]
+    </examples>
+</type>
+<type>
+    <name>reference</name>
+    <description>Stores pointers to where information can be found in external systems. These memories allow you to remember where to look to find up-to-date information outside of the project directory.</description>
+    <when_to_save>When you learn about resources in external systems and their purpose. For example, that bugs are tracked in a specific project in Linear or that feedback can be found in a specific Slack channel.</when_to_save>
+    <how_to_use>When the user references an external system or information that may be in an external system.</how_to_use>
+    <examples>
+    user: check the Linear project "INGEST" if you want context on these tickets, that's where we track all pipeline bugs
+    assistant: [saves reference memory: pipeline bugs are tracked in Linear project "INGEST"]
+
+    user: the Grafana board at grafana.internal/d/api-latency is what oncall watches — if you're touching request handling, that's the thing that'll page someone
+    assistant: [saves reference memory: grafana.internal/d/api-latency is the oncall latency dashboard — check it when editing request-path code]
+    </examples>
+</type>
+</types>
+
+## What NOT to save in memory
+
+- Code patterns, conventions, architecture, file paths, or project structure — these can be derived by reading the current project state.
+- Git history, recent changes, or who-changed-what — `git log` / `git blame` are authoritative.
+- Debugging solutions or fix recipes — the fix is in the code; the commit message has the context.
+- Anything already documented in CLAUDE.md files.
+- Ephemeral task details: in-progress work, temporary state, current conversation context.
+
+These exclusions apply even when the user explicitly asks you to save. If they ask you to save a PR list or activity summary, ask what was *surprising* or *non-obvious* about it — that is the part worth keeping.
+
+## How to save memories
+
+Saving a memory is a two-step process:
+
+**Step 1** — write the memory to its own file (e.g., `user_role.md`, `feedback_testing.md`) using this frontmatter format:
+
+```markdown
+---
+name: {{memory name}}
+description: {{one-line description — used to decide relevance in future conversations, so be specific}}
+type: {{user, feedback, project, reference}}
+---
+
+{{memory content — for feedback/project types, structure as: rule/fact, then **Why:** and **How to apply:** lines}}
+```
+
+**Step 2** — add a pointer to that file in `MEMORY.md`. `MEMORY.md` is an index, not a memory — each entry should be one line, under ~150 characters: - [Title](file.md) — one-line hook. It has no frontmatter. Never write memory content directly into MEMORY.md.
+
+- MEMORY.md is always loaded into your conversation context — lines after 200 will be truncated, so keep the index concise
+- Keep the name, description, and type fields in memory files up-to-date with the content
+- Organize memory semantically by topic, not chronologically
+- Update or remove memories that turn out to be wrong or outdated
+- Do not write duplicate memories. First check if there is an existing memory you can update before writing a new one.
+
+## When to access memories
+- When memories seem relevant, or the user references prior-conversation work.
+- You MUST access memory when the user explicitly asks you to check, recall, or remember.
+- If the user says to ignore or not use memory: proceed as if MEMORY.md were empty. Do not apply remembered facts, cite, compare against, or mention memory content.
+- Memory records can become stale over time. Use memory as context for what was true at a given point in time. Before answering the user or building assumptions based solely on information in memory records, verify that the memory is still correct and up-to-date by reading the current state of the files or resources. If a recalled memory conflicts with current information, trust what you observe now — and update or remove the stale memory rather than acting on it.
+
+## Before recommending from memory
+
+A memory that names a specific function, file, or flag is a claim that it existed *when the memory was written*. It may have been renamed, removed, or never merged. Before recommending it:
+- If the memory names a file path: check the file exists.
+- If the memory names a function or flag: grep for it.
+- If the user is about to act on your recommendation (not just asking about history), verify first.
+
+"The memory says X exists" is not the same as "X exists now."
+
+A memory that summarizes repo state (activity logs, architecture snapshots) is frozen in time. If the user asks about *recent* or *current* state, prefer `git log` or reading the code over recalling the snapshot.
+
+## Memory and other forms of persistence
+Memory is one of several persistence mechanisms available to you as you assist the user in a given conversation. The distinction is often that memory can be recalled in future conversations and should not be used for persisting information that is only useful within the scope of the current conversation.
+- When to use or update a plan instead of memory: If you are about to start a non-trivial implementation task and would like to reach alignment with the user on your approach you should use a Plan rather than saving this information to memory. Similarly, if you already have a plan within the conversation and you have changed your approach persist that change by updating the plan rather than saving a memory.
+- When to use or update tasks instead of memory: When you need to break your work in current conversation into discrete steps or keep track of your progress use tasks instead of saving to memory. Tasks are great for persisting information about the work that needs to be done in the current conversation, but memory should be reserved for information that will be useful in future conversations.
+
+## Searching past context
+
+When looking for past context:
+1. Search topic files in your memory directory:
+```
+Grep with pattern="<search>" path="{memory_dir}" glob="*.md"</search>
+# or Bash command:
+grep -rn "<search term>" {memory_dir} --include="*.md"
+```
+Use narrow search terms (error messages, file paths, function names) rather than broad keywords.
+"""  # noqa:
+
+DEFAULT_RETRIEVAL_INSTRUCTIONS = (
+    "You are selecting memory files that will be useful as context for "
+    "processing a user's query. You will be given the user's query and a "
+    "list of available memory files with their filenames and descriptions.\n\n"
+    "Return a list of filenames for the memories that will clearly be "
+    "useful (up to 5). Only include memories that you are certain will be "
+    "helpful based on their name and description.\n"
+    "- If you are unsure whether a memory will be useful, do not include "
+    "it. Be selective and discerning.\n"
+    "- If no memories would clearly be useful, return an empty list."
+)
+
+
+class _MemorySelection(BaseModel):
+    """Structured output schema for the memory relevance selector."""
+
+    selected_files: list[str] = Field(
+        description=(
+            "Filenames of the memory files to surface, relative to the "
+            "memory directory (e.g. 'user_role.md'). Up to 5 entries."
+        ),
+    )
+
+
+class AgenticMemoryMiddleware(MiddlewareBase):
+    """The agentic memory, where the LLM decides when and what to save,
+    together with an asyncio retrieval task in each reply. The memory is
+    stored and retrieval based on the Markdown files.
+
+    The `AgenticMemoryMiddleware` supports different backends via the
+    `backend` argument in its constructor.
+    """
+
+    FILENAME_MEMORY_MD: str = "MEMORY.md"
+
+    class Parameters(BaseModel):
+        """The user-tunable filesystem parameters."""
+
+        model_config = {"arbitrary_types_allowed": True}
+
+        memory_max_tokens: int = Field(
+            default=4_000,
+            title="MEMORY.md Max Length",
+            description=(
+                "The maximum tokens of the MEMORY.md inserted into the system "
+                "prompt."
+            ),
+        )
+
+        memory_instructions: str = Field(
+            default=DEFAULT_MEMORY_INSTRUCTIONS,
+            title="Memory Instructions",
+            description=(
+                "The default instructions appended to the system prompt "
+                "before the MEMORY.md snapshots."
+            ),
+        )
+
+        retrieval_async: bool = Field(
+            default=True,
+            title="Async Retrieval",
+            description=(
+                "Whether to retrieve relevant memory files asynchronously "
+                "during the agent reply. If `True`, an async retrieval task "
+                "will be started."
+            ),
+        )
+
+        retrieval_model: ChatModelBase | None = Field(
+            default=None,
+            title="Retrieval Model",
+            description=(
+                "The LLM used to retrieve relevant memory files "
+                "asynchronously during the agent reply. If `None`, the "
+                "agent's model will be used."
+            ),
+        )
+
+        retrieval_max_tokens_per_md: int = Field(
+            default=2_000,
+            title="Retrieval Max Tokens Per File",
+            description=(
+                "Maximum tokens read from each memory file that is surfaced "
+                "by the relevance retrieval step. Keeps individual files from "
+                "flooding the context window."
+            ),
+        )
+
+        retrieval_max_files: int = Field(
+            default=200,
+            title="Retrieval Max Files",
+            description=(
+                "The maximum number of Markdown memory files to consider "
+                "during relevance selection."
+            ),
+        )
+
+        retrieval_max_tokens_per_frontmatter: int = Field(
+            default=256,
+            title="Retrieval Max Tokens per Frontmatter",
+            description=(
+                "The maximum number of tokens to read from the beginning of "
+                "each Markdown file when parsing frontmatter."
+            ),
+        )
+
+        retrieval_instructions: str = Field(
+            default=DEFAULT_RETRIEVAL_INSTRUCTIONS,
+            title="Retrieval Instructions",
+            description=(
+                "The instructions used to select relevant memory files for a "
+                "given user query in the asynchronous retrieval task."
+            ),
+        )
+
+    def __init__(
+        self,
+        *,
+        workdir: str,
+        memory_dir: str = "Memory",
+        parameters: Parameters | None = None,
+        backend: BackendBase | None = None,
+    ) -> None:
+        """Initialize filesystem-backed long-term memory behavior.
+
+        Args:
+            workdir (`str`):
+                The working directory of this agent, used to store the agentic
+                searchable memory files.
+            memory_dir (`str`, defaults to ``"Memory"``):
+                The directory to store the long-term memory files, including
+                ``MEMORY.md``.
+            parameters (`AgenticMemoryMiddleware.Parameters | None`, \
+            defaults to ``None``):
+                User-tunable parameters.  When ``None``, defaults are used.
+            backend (`BackendBase | None`, optional):
+                The backend to switch between local and remote storage.
+                When ``None``, a local filesystem is used.
+        """
+        self._workdir = workdir
+        self._memory_dir = memory_dir
+        self._parameters = parameters or self.Parameters()
+        self._backend = backend or LocalBackend()
+
+        self._cached_input: str | None = None
+        # The in-flight asynchronous retrieval task started in ``on_reply``
+        # and consumed in ``on_reasoning``. Kept on the instance so the
+        # reasoning hook can poll for completion across iterations.
+        self._retrieval_task: asyncio.Task | None = None
+
+    @staticmethod
+    def _truncate_if_needed(content: str, max_length: int) -> str:
+        """Return ``content`` truncated to at most ``max_length`` tokens.
+
+        Args:
+            content (`str`):
+                The content to truncate.
+            max_length (`int`):
+                The maximum estimated token count to keep.
+
+        Returns:
+            `str`:
+                The original content when it already fits; otherwise a prefix
+                that fits within the requested token budget.
+        """
+        if max_length <= 0:
+            return ""
+
+        n_tokens = _estimate_tokens(content)
+        if n_tokens <= max_length:
+            return content
+
+        index = int((max_length / n_tokens) * len(content))
+        while index > 0 and _estimate_tokens(content[:index]) > max_length:
+            index = max(0, index - 10)
+
+        return content[:index]
+
+    async def on_system_prompt(
+        self,
+        agent: "Agent",
+        current_prompt: str,
+    ) -> str:
+        """Append memory instructions and a bounded ``MEMORY.md`` snapshot.
+
+        Args:
+            agent (`Agent`):
+                The executing agent. Unused, but part of the middleware
+                contract.
+            current_prompt (`str`):
+                The system prompt produced by previous middleware.
+
+        Returns:
+            `str`:
+                The prompt with filesystem memory instructions appended.
+        """
+        await self._ensure_layout()
+        memory_md_content = await self._get_memory_md_content() or ""
+
+        # Truncated by config
+        memory_md_truncated = self._truncate_if_needed(
+            memory_md_content,
+            self._parameters.memory_max_tokens,
+        )
+
+        if len(memory_md_truncated) != len(memory_md_content):
+            memory_md_path = self._get_memory_md_path()
+            remain_lines = len(memory_md_truncated.split("\n"))
+            omitted_lines = len(memory_md_content.split("\n")) - remain_lines
+            memory_md_truncated += (
+                "\n<<<TRUNCATED>>>\n<system-reminder>The remaining "
+                f"{omitted_lines} lines have been omitted due to context "
+                "length limits. Use the `Read` tool with offset "
+                f"`{remain_lines}` to access the rest of '{memory_md_path}'."
+                f"</system-reminder>"
+            )
+
+        if not memory_md_truncated:
+            memory_md_truncated = (
+                "Your MEMORY.md is currently empty. When you save new "
+                "memories, they will appear here."
+            )
+
+        memory_instructions = self._parameters.memory_instructions.replace(
+            "{memory_dir}",
+            self._get_memory_dir(),
+        )
+        content = (
+            f"{memory_instructions}\n" f"## MEMORY.md\n{memory_md_truncated}"
+        )
+
+        return f"{current_prompt}\n\n{content}"
+
+    async def on_reply(
+        self,
+        agent: "Agent",
+        input_kwargs: dict,
+        next_handler: Callable[..., AsyncGenerator],
+    ) -> AsyncGenerator:
+        """Cache the user input and kick off an asynchronous retrieval task
+        that runs concurrently with the agent reply.
+
+        Args:
+            agent (`Agent`):
+                The executing agent whose model may be used for retrieval.
+            input_kwargs (`dict`):
+                Reply input kwargs forwarded unchanged.
+            next_handler (`Callable[..., AsyncGenerator]`):
+                The downstream middleware or core reply logic.
+
+        Yields:
+            `Any`:
+                Items yielded by ``next_handler``.
+        """
+
+        if self._parameters.retrieval_async:
+            inputs = input_kwargs.get("inputs")
+
+            msgs = None
+            if isinstance(inputs, list) and all(
+                isinstance(_, Msg) for _ in inputs
+            ):
+                msgs = inputs
+            elif isinstance(inputs, Msg):
+                msgs = [inputs]
+
+            if msgs is not None:
+                self._cached_input = "\n".join(
+                    [
+                        f"{_.name}: " + _.get_text_content()
+                        for _ in msgs
+                        if _.get_text_content() is not None
+                    ],
+                )
+
+            # Start an asynchronous retrieval task that uses an LLM to decide
+            # which memory files are relevant to the current user input. The
+            # result is consumed by ``on_reasoning``.
+            if self._cached_input:
+                self._retrieval_task = asyncio.create_task(
+                    self._retrieve_relevant_files(agent, self._cached_input),
+                )
+
+        try:
+            async for _ in next_handler(**input_kwargs):
+                yield _
+        finally:
+            # Ensure the retrieval task does not outlive the reply.
+            if (
+                self._retrieval_task is not None
+                and not self._retrieval_task.done()
+            ):
+                self._retrieval_task.cancel()
+                try:
+                    await self._retrieval_task
+                except (asyncio.CancelledError, Exception):  # noqa: BLE001
+                    pass
+            self._retrieval_task = None
+            self._cached_input = None
+
+    async def on_reasoning(
+        self,
+        agent: "Agent",
+        input_kwargs: dict,
+        next_handler: Callable[..., AsyncGenerator],
+    ) -> AsyncGenerator:
+        """Check if the retrieval finished and if yes, insert a hint block to
+        the content.
+
+        Args:
+            agent (`Agent`):
+                The executing agent whose context may receive a hint block.
+            input_kwargs (`dict`):
+                Reasoning input kwargs forwarded unchanged.
+            next_handler (`Callable[..., AsyncGenerator]`):
+                The downstream middleware or core reasoning logic.
+
+        Yields:
+            `Any`:
+                Items yielded by ``next_handler``.
+        """
+        # Poll the in-flight retrieval task; if it has finished, consume its
+        # result and inject it into the agent context exactly once.
+        if self._retrieval_task is not None and self._retrieval_task.done():
+            task = self._retrieval_task
+            self._retrieval_task = None
+            try:
+                retrieval_result = task.result()
+            except (asyncio.CancelledError, Exception):
+                retrieval_result = None
+
+            if retrieval_result:
+                agent.state.append_context(
+                    agent.name,
+                    [
+                        HintBlock(
+                            hint=retrieval_result,
+                        ),
+                    ],
+                )
+
+        async for event in next_handler(**input_kwargs):
+            yield event
+
+    # ========================================================================
+    # Helper functions
+    # ========================================================================
+
+    @staticmethod
+    def _format_manifest(headers: list[_MemoryFileHeader]) -> str:
+        """Format a list of memory file headers into a one-line-per-file
+        manifest string suitable for the selector prompt.
+
+        Args:
+            headers (`list[_MemoryFileHeader]`):
+                The memory file headers to format.
+
+        Returns:
+            `str`:
+                The formatted manifest.
+        """
+        lines = []
+        for h in headers:
+            tag = f"[{h.type}] " if h.type else ""
+            if h.mtime is not None:
+                from datetime import datetime
+
+                ts = datetime.fromtimestamp(h.mtime).strftime("%Y-%m-%d")
+            else:
+                ts = "unknown"
+            desc = f": {h.description}" if h.description else ""
+            lines.append(f"- {tag}{h.filename} ({ts}){desc}")
+        return "\n".join(lines)
+
+    async def _retrieve_relevant_files(
+        self,
+        agent: "Agent",
+        query: str,
+    ) -> str | None:
+        """Use an LLM to identify memory files relevant to ``query`` and
+        return their content as an injectable string.
+
+        Args:
+            agent (`Agent`):
+                The agent whose model / memory store should be consulted.
+            query (`str`):
+                The cached user input used as the retrieval query.
+
+        Returns:
+            `str | None`:
+                The formatted retrieval result ready to be injected into the
+                context, or ``None`` when nothing relevant was found.
+        """
+        await self._ensure_layout()
+
+        # 1. Scan available memory files (frontmatter only, cheap).
+        headers = await self._list_md_files()
+        if not headers:
+            return None
+
+        valid_filenames = {h.filename for h in headers}
+        manifest = self._format_manifest(headers)
+
+        # 2. Ask the model to select relevant files.
+        model = self._parameters.retrieval_model or agent.model
+        res = await model.generate_structured_output(
+            [
+                SystemMsg(
+                    name="system",
+                    content=self._parameters.retrieval_instructions,
+                ),
+                UserMsg(
+                    name="user",
+                    content=(
+                        f"Query: {query}\n\n"
+                        f"Available memories:\n{manifest}"
+                    ),
+                ),
+            ],
+            structured_model=_MemorySelection,
+        )
+
+        # 3. Validate: discard hallucinated filenames.
+        raw_selected: list[str] = res.content.get("selected_files", [])
+        selected = [f for f in raw_selected if f in valid_filenames][:5]
+        if not selected:
+            return None
+
+        # 4. Read each selected file and format as an injectable string.
+        # Cap each file to avoid flooding the context window.
+        header_by_filename = {h.filename: h for h in headers}
+        parts: list[str] = []
+        for filename in selected:
+            h = header_by_filename[filename]
+            try:
+                content = (await self._backend.read_file(h.path)).decode(
+                    "utf-8",
+                    errors="replace",
+                )
+            except Exception:
+                continue
+
+            # Truncate large files to avoid flooding the context window.
+            content = self._truncate_if_needed(
+                content,
+                self._parameters.retrieval_max_tokens_per_md,
+            )
+            if h.mtime is not None:
+                import time
+
+                days = max(0, int((time.time() - h.mtime) / 86_400))
+                if days == 0:
+                    age = "today"
+                elif days == 1:
+                    age = "yesterday"
+                else:
+                    age = f"{days} days ago"
+                header = f"Memory (saved {age}): {h.path}:"
+            else:
+                header = f"Memory: {h.path}:"
+
+            parts.append(f"{header}\n\n{content}")
+
+        if not parts:
+            return None
+
+        return "\n\n---\n\n".join(parts)
+
+    async def _ensure_layout(self) -> None:
+        """Create the memory directory and initial files idempotently.
+
+        Existing human-edited documents are never replaced. The index file is
+        created only when absent so manual edits survive restarts. The memory
+        directory itself is materialized as a side effect of writing
+        ``MEMORY.md`` — :meth:`BackendBase.write_file` creates parent
+        directories — which avoids a platform-specific ``mkdir -p`` shell
+        invocation that is not portable on Windows.
+        """
+        if not await self._backend.file_exists(self._get_memory_md_path()):
+            logger.info(
+                "Creating 'MEMORY.md' file in '%s'",
+                self._workdir,
+            )
+            await self._backend.write_file(
+                self._get_memory_md_path(),
+                b"",
+            )
+
+    def _get_memory_dir(self) -> str:
+        """Get the memory directory.
+
+        Returns:
+            `str`:
+                The backend path of the memory directory.
+        """
+        return self._backend.join_path(self._workdir, self._memory_dir)
+
+    def _get_memory_md_path(self) -> str:
+        """Get the ``MEMORY.md`` path.
+
+        Returns:
+            `str`:
+                The backend path of the ``MEMORY.md`` index file.
+        """
+        return self._backend.join_path(
+            self._get_memory_dir(),
+            self.FILENAME_MEMORY_MD,
+        )
+
+    async def _get_memory_md_content(self) -> str | None:
+        """Get the content of the ``MEMORY.md`` file.
+
+        Returns:
+            `str | None`:
+                The decoded index file content, or ``None`` when the file does
+                not exist.
+        """
+        if not await self._backend.file_exists(self._get_memory_md_path()):
+            return None
+
+        return (
+            await self._backend.read_file(self._get_memory_md_path())
+        ).decode(
+            "utf-8",
+            errors="replace",
+        )
+
+    _FRONTMATTER_RE = re.compile(
+        r"^\s*---\s*\n(?P<body>.*?)\n---\s*\n",
+        re.DOTALL,
+    )
+    _FIELD_RE = re.compile(r"^(?P<key>\w+)\s*:\s*(?P<value>.+)$", re.MULTILINE)
+
+    @classmethod
+    def _parse_frontmatter_fields(cls, content: str) -> dict[str, str]:
+        """Return a dict of YAML-like key/value pairs from the first
+        frontmatter block.  Only scalar ``key: value`` lines are parsed;
+        nested structures are intentionally ignored.
+
+        Args:
+            content (`str`):
+                The Markdown content prefix to inspect.
+
+        Returns:
+            `dict[str, str]`:
+                Parsed frontmatter fields, or an empty dict when no leading
+                frontmatter block is present.
+        """
+        m = cls._FRONTMATTER_RE.match(content)
+        if not m:
+            return {}
+        return {
+            fm.group("key"): fm.group("value").strip()
+            for fm in cls._FIELD_RE.finditer(m.group("body"))
+        }
+
+    async def _list_md_files(self) -> list[_MemoryFileHeader]:
+        """Scan the memory directory for individual memory files.
+
+        Returns:
+            `list[_MemoryFileHeader]`:
+                Memory file headers sorted newest-first and capped by
+                ``retrieval_max_files``. The system index file
+                (``MEMORY.md``) is excluded so only topic files are returned.
+        """
+        memory_dir = self._get_memory_dir()
+        system_files = {self.FILENAME_MEMORY_MD}
+
+        try:
+            all_entries = await self._backend.list_dir(
+                memory_dir,
+                recursive=True,
+            )
+        except Exception:
+            return []
+
+        headers: list[_MemoryFileHeader] = []
+        memory_dir_norm = self._backend.normpath(memory_dir)
+        memory_dir_prefix = self._backend.join_path(memory_dir_norm, "")
+        for entry in all_entries:
+            entry_path = self._backend.normpath(entry)
+            if self._backend.isabs(entry_path):
+                if not entry_path.startswith(memory_dir_prefix):
+                    continue
+                filename = entry_path[len(memory_dir_prefix) :]
+                full_path = entry_path
+            else:
+                filename = entry_path
+                full_path = self._backend.join_path(memory_dir, filename)
+
+            if not filename.endswith(".md") or filename in system_files:
+                continue
+
+            try:
+                raw = await self._backend.read_file(full_path)
+                # Only parse the leading bytes to keep this cheap.
+                max_frontmatter_bytes = _estimate_bytes(
+                    self._parameters.retrieval_max_tokens_per_frontmatter,
+                )
+                snippet = raw[:max_frontmatter_bytes].decode(
+                    "utf-8",
+                    errors="replace",
+                )
+                fields = self._parse_frontmatter_fields(snippet)
+                mtime = await self._backend.stat_mtime(full_path)
+                headers.append(
+                    _MemoryFileHeader(
+                        filename=filename,
+                        path=full_path,
+                        description=fields.get("description") or None,
+                        type=fields.get("type") or None,
+                        mtime=mtime,
+                    ),
+                )
+            except Exception:
+                continue
+
+        headers.sort(key=lambda h: h.mtime or 0.0, reverse=True)
+        return headers[: self._parameters.retrieval_max_files]
diff --git a/src/agentscope/middleware/_longterm_memory/_mem0/__init__.py b/src/agentscope/middleware/_longterm_memory/_mem0/__init__.py
new file mode 100644
index 0000000..645e7e6
--- /dev/null
+++ b/src/agentscope/middleware/_longterm_memory/_mem0/__init__.py
@@ -0,0 +1,6 @@
+# -*- coding: utf-8 -*-
+"""mem0-backed long-term memory middleware."""
+
+from ._middleware import Mem0Middleware
+
+__all__ = ["Mem0Middleware"]
diff --git a/src/agentscope/middleware/_longterm_memory/_mem0/_agentscope_adapter.py b/src/agentscope/middleware/_longterm_memory/_mem0/_agentscope_adapter.py
new file mode 100644
index 0000000..8fedd41
--- /dev/null
+++ b/src/agentscope/middleware/_longterm_memory/_mem0/_agentscope_adapter.py
@@ -0,0 +1,439 @@
+# -*- coding: utf-8 -*-
+"""Adapters that let mem0 drive its memory extraction with the user's
+existing AgentScope chat / embedding model — instead of building yet
+another OpenAI / Anthropic / Ollama client just for mem0.
+
+Two pieces:
+
+- :class:`AgentScopeLLM` — implements ``mem0.llms.base.LLMBase`` by
+  delegating to an ``agentscope.model.ChatModelBase`` instance.
+- :class:`AgentScopeEmbedding` — implements
+  ``mem0.embeddings.base.EmbeddingBase`` by delegating to an
+  ``agentscope.embedding.EmbeddingModelBase`` instance.
+
+mem0 calls these synchronously; AgentScope models are async. We bridge
+the two with ``asyncio.get_event_loop().run_until_complete()`` which
+executes the coroutine on the caller's event loop.
+
+Use :func:`build_mem0_config` to produce a ``MemoryConfig`` wired to
+AgentScope models:
+
+    from mem0 import AsyncMemory
+    from agentscope.middleware._longterm_memory._mem0._agentscope_adapter \\
+        import build_mem0_config
+
+    mem0_client = AsyncMemory(
+        config=build_mem0_config(
+            chat_model=my_chat_model,
+            embedding_model=my_embedding_model,
+        ),
+    )
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import threading
+from collections.abc import AsyncGenerator
+from typing import Any, TYPE_CHECKING
+
+from mem0.configs.embeddings.base import BaseEmbedderConfig
+from mem0.configs.llms.base import BaseLlmConfig
+from mem0.embeddings.base import EmbeddingBase
+from mem0.llms.base import LLMBase
+
+from ....embedding import EmbeddingModelBase
+from ....message import (
+    AssistantMsg,
+    Msg,
+    SystemMsg,
+    UserMsg,
+)
+from ....model import ChatModelBase
+
+if TYPE_CHECKING:
+    from ....model import ChatResponse
+
+
+# ----------------------------------------------------------------------
+# Sync → async bridge
+# ----------------------------------------------------------------------
+
+
+class _AsyncBridge:
+    """Run async coroutines synchronously on a dedicated, long-lived
+    event loop.
+
+    mem0's ``LLMBase.generate_response`` / ``EmbeddingBase.embed`` are
+    sync, but AgentScope models are async. The bridge owns one event
+    loop running on its own daemon thread and submits coroutines to it
+    via ``run_coroutine_threadsafe``, blocking for the result. The loop
+    stays alive for the bridge's lifetime, so async clients created
+    inside the model are reused and cleaned up against a live loop.
+    """
+
+    def __init__(self) -> None:
+        self._loop = asyncio.new_event_loop()
+        self._thread = threading.Thread(
+            target=self._loop.run_forever,
+            name="mem0-agentscope-bridge",
+            daemon=True,
+        )
+        self._thread.start()
+
+    def run(self, coro: Any) -> Any:
+        """Submit ``coro`` to the bridge loop and block for its result."""
+        return asyncio.run_coroutine_threadsafe(coro, self._loop).result()
+
+
+# ----------------------------------------------------------------------
+# LLM adapter
+# ----------------------------------------------------------------------
+
+
+class AgentScopeLLM(LLMBase):
+    """mem0 ``LLMBase`` backed by an AgentScope ``ChatModelBase``.
+
+    Pass your AgentScope model into ``config["model"]``; mem0's memory
+    extraction calls then route through it. Both streaming and
+    non-streaming AgentScope models are accepted (streaming responses are
+    drained and the final chunk is used).
+    """
+
+    def __init__(
+        self,
+        config: BaseLlmConfig | dict | None = None,
+    ) -> None:
+        """Initialize the AgentScope LLM for mem0."""
+        super().__init__(config)
+        if self.config.model is None:
+            raise ValueError(
+                "AgentScopeLLM requires `model` in the config to be an "
+                "AgentScope ChatModelBase instance.",
+            )
+        if not isinstance(self.config.model, ChatModelBase):
+            raise TypeError(
+                f"AgentScopeLLM `model` must be a ChatModelBase, got "
+                f"{type(self.config.model).__name__}.",
+            )
+        self._agentscope_model: ChatModelBase = self.config.model
+        self._bridge = _AsyncBridge()
+
+    # ----- LLMBase interface -----
+    # pylint: disable=unused-argument
+    def generate_response(
+        self,
+        messages: list[dict[str, str]],
+        response_format: Any | None = None,  # mem0 contract — unused
+        tools: list[dict] | None = None,
+        tool_choice: str = "auto",  # mem0 contract — unused
+    ) -> str | dict:
+        """mem0 ``LLMBase`` entry — runs the AgentScope chat model
+        synchronously and returns str (or dict with tool_calls when
+        ``tools`` is given)."""
+        as_messages = _convert_messages_to_agentscope(messages)
+        if not as_messages:
+            raise ValueError(
+                "AgentScopeLLM received no usable messages "
+                "(empty list or all roles unrecognized).",
+            )
+
+        response = self._bridge.run(
+            _await_chat(self._agentscope_model, as_messages, tools),
+        )
+        return _parse_chat_response(response, has_tool=bool(tools))
+
+
+async def _await_chat(
+    model: ChatModelBase,
+    messages: list[Msg],
+    tools: list[dict] | None,
+) -> "ChatResponse":
+    """Call the AgentScope chat model, handling both streaming and
+    non-streaming returns."""
+    result = await model(messages, tools=tools)
+    # Streaming model — drain the generator and keep the final chunk,
+    # which carries the complete content per AgentScope's streaming
+    # contract. ``isinstance`` (not ``hasattr``) — Pydantic BaseModel
+    # raises KeyError instead of AttributeError on missing dunder
+    # attrs, which ``hasattr`` does not catch.
+    if isinstance(result, AsyncGenerator):
+        last = None
+        async for chunk in result:
+            last = chunk
+        if last is None:
+            raise RuntimeError(
+                "AgentScope streaming model yielded no chunks.",
+            )
+        return last
+    return result
+
+
+def _convert_messages_to_agentscope(
+    messages: list[dict[str, str]],
+) -> list[Msg]:
+    """mem0 hands us OpenAI-style ``[{"role", "content"}, ...]`` dicts;
+    AgentScope wants ``Msg`` objects."""
+    out: list[Msg] = []
+    for m in messages:
+        role = m.get("role")
+        content = m.get("content", "")
+        if role == "system":
+            out.append(SystemMsg(name="system", content=content))
+        elif role == "user":
+            out.append(UserMsg(name="user", content=content))
+        elif role == "assistant":
+            out.append(AssistantMsg(name="assistant", content=content))
+        # unknown roles silently dropped — matches v1 behavior
+    return out
+
+
+def _parse_chat_response(
+    response: "ChatResponse",
+    has_tool: bool,
+) -> str | dict:
+    """Flatten an AgentScope ``ChatResponse`` into the str/dict shape
+    mem0 expects from ``LLMBase.generate_response``."""
+    text_parts: list[str] = []
+    thinking_parts: list[str] = []
+    tool_parts: list[dict] = []
+
+    for block in response.content or []:
+        block_type = getattr(block, "type", None)
+        if block_type == "text":
+            text_parts.append(block.text or "")
+        elif block_type == "thinking":
+            thinking_parts.append(f"[Thinking: {block.thinking or ''}]")
+        elif block_type == "tool_call":
+            # AgentScope 2.0 stores tool args as a JSON string; mem0
+            # expects an arguments' dict.
+            raw_input = block.input or "{}"
+            try:
+                arguments = json.loads(raw_input)
+            except json.JSONDecodeError:
+                arguments = raw_input
+            tool_parts.append(
+                {"name": block.name, "arguments": arguments},
+            )
+        # DataBlock and other types are not part of mem0's contract.
+
+    text_out = "\n".join(thinking_parts + text_parts)
+    if has_tool:
+        return {"content": text_out, "tool_calls": tool_parts}
+    return text_out
+
+
+# ----------------------------------------------------------------------
+# Embedding adapter
+# ----------------------------------------------------------------------
+
+
+class AgentScopeEmbedding(EmbeddingBase):
+    """mem0 ``EmbeddingBase`` backed by an AgentScope
+    ``EmbeddingModelBase``."""
+
+    def __init__(
+        self,
+        config: BaseEmbedderConfig | dict | None = None,
+    ) -> None:
+        # mem0's EmbeddingBase (unlike LLMBase) does NOT auto-convert
+        # dict configs — it stores whatever is passed. Normalize here
+        # so callers can use the same dict-config style as the LLM.
+        if isinstance(config, dict):
+            config = BaseEmbedderConfig(**config)
+        super().__init__(config)
+        if self.config.model is None:
+            raise ValueError(
+                "AgentScopeEmbedding requires `model` in the config "
+                "to be an AgentScope EmbeddingModelBase instance.",
+            )
+        if not isinstance(self.config.model, EmbeddingModelBase):
+            raise TypeError(
+                f"AgentScopeEmbedding `model` must be an "
+                f"EmbeddingModelBase, got "
+                f"{type(self.config.model).__name__}.",
+            )
+        self._agentscope_model: EmbeddingModelBase = self.config.model
+        self._bridge = _AsyncBridge()
+
+    # ----- EmbeddingBase interface -----
+    # pylint: disable=unused-argument
+    def embed(
+        self,
+        text: str | list[str],
+        memory_action: str | None = None,  # mem0 contract — unused
+    ) -> list[float]:
+        """mem0 ``EmbeddingBase`` entry — runs the AgentScope embedding
+        model synchronously and returns the first vector."""
+        text_list = [text] if isinstance(text, str) else list(text)
+        response = self._bridge.run(self._agentscope_model(text_list))
+        if not response.embeddings:
+            raise RuntimeError(
+                "AgentScope embedding model returned no embeddings.",
+            )
+        # AgentScope EmbeddingResponse.embeddings is List[List[float]];
+        # mem0 expects a single vector for a single-text call.
+        return response.embeddings[0]
+
+
+# ----------------------------------------------------------------------
+# Build a mem0 MemoryConfig wired to AgentScope models
+# ----------------------------------------------------------------------
+
+# The provider name we register under in mem0's factory + config layer.
+_AGENTSCOPE_PROVIDER = "agentscope"
+
+
+def build_mem0_config(
+    *,
+    chat_model: ChatModelBase | None = None,
+    embedding_model: EmbeddingModelBase | None = None,
+    mem0_config: Any | None = None,
+) -> Any:
+    """Build a ``mem0.configs.base.MemoryConfig`` wired to AgentScope
+    chat / embedding models.
+
+    Three calling shapes:
+
+    1. ``build_mem0_config(chat_model=..., embedding_model=...)``
+       — build a fresh config (mem0 defaults for vector_store /
+       history_db / reranker etc.) with both LLM and embedder routed
+       through AgentScope.
+    2. ``build_mem0_config(mem0_config=cfg, chat_model=...,
+       embedding_model=...)`` — start from your customized
+       ``MemoryConfig`` and override only ``.llm`` / ``.embedder`` with
+       the AgentScope adapters. Use this when you want a non-default
+       vector store / history DB / reranker but still want AgentScope
+       to drive memory extraction. Either or both of ``chat_model``
+       and ``embedding_model`` may be passed — fields you omit keep
+       whatever the input config had.
+    3. ``build_mem0_config(mem0_config=cfg)`` — pass-through; the
+       AgentScope adapters are registered (cheap) but no fields are
+       overridden.
+
+    Why a helper? Two private layers inside mem0 reject anything
+    outside its built-in provider list, so plugging in AgentScope
+    requires both:
+
+    1. Adding ``"agentscope"`` to ``LlmFactory.provider_to_class`` /
+       ``EmbedderFactory.provider_to_class`` so the factory can
+       construct our adapter classes.
+    2. Bypassing the hardcoded provider whitelist in
+       ``LlmConfig.validate_config`` / ``EmbedderConfig.validate_config``.
+       Done by substituting subclasses whose validator only allows
+       ``"agentscope"``. Other provider names are rejected by these
+       subclasses, matching the fact that this helper is only for wiring
+       the AgentScope adapters.
+
+    Args:
+        chat_model:
+            The AgentScope ``ChatModelBase`` mem0 should use for memory
+            extraction. Required when ``mem0_config`` is not given.
+        embedding_model:
+            The AgentScope ``EmbeddingModelBase`` mem0 should use to
+            embed memories. Its ``dimensions`` must match the vector
+            store's expected dim (mem0's default Qdrant expects 1536).
+            Required when ``mem0_config`` is not given.
+        mem0_config:
+            Optional pre-built ``MemoryConfig`` to use as the base.
+            When given, only the LLM / embedder slots are overridden
+            from ``chat_model`` / ``embedding_model`` — every other
+            field (``vector_store``, ``history_db_path``, ``reranker``,
+            ``custom_instructions``, ``version``) is preserved.
+
+    Returns:
+        A ``MemoryConfig`` ready to pass to ``AsyncMemory(config=...)``
+        or ``Memory(config=...)``.
+    """
+    from mem0.configs.base import MemoryConfig
+
+    _register_agentscope_provider()
+    llm_cfg_cls, emb_cfg_cls = _agentscope_config_classes()
+
+    if mem0_config is None:
+        if chat_model is None or embedding_model is None:
+            raise ValueError(
+                "build_mem0_config requires `chat_model` and "
+                "`embedding_model` when `mem0_config` is not given.",
+            )
+        return MemoryConfig(
+            llm=llm_cfg_cls(
+                provider=_AGENTSCOPE_PROVIDER,
+                config={"model": chat_model},
+            ),
+            embedder=emb_cfg_cls(
+                provider=_AGENTSCOPE_PROVIDER,
+                config={"model": embedding_model},
+            ),
+        )
+
+    # Use the user's config as base; partial-override .llm / .embedder
+    # only for fields they actually passed. Pydantic v2 doesn't
+    # re-validate on attribute assignment, so this sticks.
+    if chat_model is not None:
+        mem0_config.llm = llm_cfg_cls(
+            provider=_AGENTSCOPE_PROVIDER,
+            config={"model": chat_model},
+        )
+    if embedding_model is not None:
+        mem0_config.embedder = emb_cfg_cls(
+            provider=_AGENTSCOPE_PROVIDER,
+            config={"model": embedding_model},
+        )
+    return mem0_config
+
+
+def _register_agentscope_provider() -> None:
+    """Plug the AgentScope adapter classes into mem0's factory dicts
+    under provider name ``"agentscope"``. Idempotent."""
+    from mem0.utils.factory import EmbedderFactory, LlmFactory
+
+    LlmFactory.provider_to_class[_AGENTSCOPE_PROVIDER] = (
+        f"{__name__}.AgentScopeLLM",
+        BaseLlmConfig,
+    )
+    EmbedderFactory.provider_to_class[
+        _AGENTSCOPE_PROVIDER
+    ] = f"{__name__}.AgentScopeEmbedding"
+
+
+def _agentscope_config_classes() -> tuple[type, type]:
+    """Return ``LlmConfig`` / ``EmbedderConfig`` subclasses whose
+    validator allows ``provider="agentscope"`` (and only that — every
+    other provider continues to be rejected with the same error mem0
+    would have raised)."""
+    from pydantic import field_validator
+
+    from mem0.embeddings.configs import EmbedderConfig
+    from mem0.llms.configs import LlmConfig
+
+    class _AgentScopeLlmConfig(LlmConfig):
+        """``LlmConfig`` subclass that accepts the AgentScope provider."""
+
+        @field_validator("config")
+        @classmethod
+        def validate_config(cls, v: Any, values: Any) -> Any:
+            """Allow ``provider == "agentscope"``; reject everything
+            else with mem0's original error."""
+            provider = values.data.get("provider")
+            if provider == _AGENTSCOPE_PROVIDER:
+                return v
+            raise ValueError(f"Unsupported LLM provider: {provider}")
+
+    class _AgentScopeEmbedderConfig(EmbedderConfig):
+        """``EmbedderConfig`` subclass that accepts the AgentScope
+        provider."""
+
+        @field_validator("config")
+        @classmethod
+        def validate_config(cls, v: Any, values: Any) -> Any:
+            """Allow ``provider == "agentscope"``; reject everything
+            else with mem0's original error."""
+            provider = values.data.get("provider")
+            if provider == _AGENTSCOPE_PROVIDER:
+                return v
+            raise ValueError(
+                f"Unsupported embedding provider: {provider}",
+            )
+
+    return _AgentScopeLlmConfig, _AgentScopeEmbedderConfig
diff --git a/src/agentscope/middleware/_longterm_memory/_mem0/_middleware.py b/src/agentscope/middleware/_longterm_memory/_mem0/_middleware.py
new file mode 100644
index 0000000..5c65f95
--- /dev/null
+++ b/src/agentscope/middleware/_longterm_memory/_mem0/_middleware.py
@@ -0,0 +1,741 @@
+# -*- coding: utf-8 -*-
+"""mem0-backed long-term memory middleware for AgentScope agents.
+
+Works with either ``mem0.AsyncMemory`` (open-source) or
+``mem0.AsyncMemoryClient`` (hosted Platform). Both clients converge on
+the same call shape:
+
+- ``search(query, filters={"user_id": ..., "agent_id": ...}, top_k=...)``
+- ``add(messages, user_id=..., agent_id=...)``
+
+so one middleware class handles both.
+"""
+from __future__ import annotations
+
+import asyncio
+import inspect
+from typing import (
+    Any,
+    AsyncGenerator,
+    Callable,
+    Literal,
+    TYPE_CHECKING,
+)
+from ..._base import MiddlewareBase
+from ...._logging import logger
+from ....event import ReplyStartEvent
+from ....message import AssistantMsg, HintBlock, Msg
+from ._tools import _build_memory_tools
+from ._utils import (
+    _extract_memory_texts,
+    _extract_query_text,
+    _mem0_extracted_anything,
+)
+
+if TYPE_CHECKING:
+    from typing import TypeAlias
+
+    from mem0 import AsyncMemory, AsyncMemoryClient
+
+    from ....agent import Agent
+    from ....embedding import EmbeddingModelBase
+    from ....model import ChatModelBase
+    from ....tool import ToolBase
+
+    # Explicit ``TypeAlias`` annotation tells mypy this is a type
+    # alias rather than a plain variable assignment — without it
+    # mypy 1.7+ refuses to use ``Mem0AsyncClient`` in annotation
+    # positions ("Variable is not valid as a type").
+    Mem0AsyncClient: TypeAlias = AsyncMemory | AsyncMemoryClient
+
+
+def _looks_async(method: Any) -> bool:
+    """Detect "async-callable" methods, including ones wrapped by a
+    sync ``@functools.wraps`` decorator that returns the underlying
+    coroutine.
+
+    Plain ``inspect.iscoroutinefunction`` is too strict for mem0's
+    Platform client: ``AsyncMemoryClient.search`` is ``async def`` but
+    decorated by mem0's ``@api_error_handler``, which is a sync wrapper
+    that returns the coroutine produced by calling the underlying async
+    function. The wrapper itself isn't a coroutine function, so the
+    naive check rejects an otherwise-valid client. ``inspect.unwrap``
+    walks ``__wrapped__`` (set by ``functools.wraps``) until it finds
+    the original async ``func``, which the strict check then accepts.
+    """
+    if method is None:
+        return False
+    return inspect.iscoroutinefunction(inspect.unwrap(method))
+
+
+DEFAULT_MEMORY_SECTION_HEADER = "## Relevant memories from past conversations"
+DEFAULT_MEMORY_SECTION_INTRO = (
+    "The following memories about the user may be relevant. "
+    "Use them only if they are pertinent to the current request."
+)
+
+DEFAULT_TOOL_INSTRUCTIONS = (
+    "## Long-term memory\n\n"
+    "You have `search_memory` and `add_memory` tools available. Use "
+    "them whenever the conversation depends on (search) or contributes "
+    "(add) a durable fact about the user — see each tool's own "
+    "description for the exact input shape and usage guidance."
+)
+
+
+class Mem0Middleware(MiddlewareBase):
+    """AgentScope middleware that adds long-term memory backed by
+    `mem0 <https://github.com/mem0ai/mem0>`_.
+
+    Two construction paths:
+
+    1. **Models** — pass an AgentScope ``chat_model`` and
+       ``embedding_model`` (optionally with a custom ``mem0_config``
+       as base for vector store / history DB / etc.). The middleware
+       builds an OSS ``AsyncMemory`` internally, wired so mem0's
+       memory extraction and embedding both go through your AgentScope
+       models.
+    2. **Client** — pass a pre-built ``mem0.AsyncMemory`` /
+       ``mem0.AsyncMemoryClient`` when you want full control (e.g.
+       hosted Platform, sharing one mem0 across agents). When
+       ``client`` is given it takes precedence and the other backend
+       kwargs are ignored.
+
+    Three control patterns are available via the ``mode`` parameter
+    (``"static_control"`` / ``"agent_control"`` / ``"both"``); see
+    the constructor's ``mode`` arg for what each does.
+
+    Example (build OSS internally)::
+
+        from agentscope.middleware import Mem0Middleware
+        from agentscope.tool import Toolkit
+
+        mw = Mem0Middleware(
+            user_id="alice",
+            chat_model=my_chat_model,
+            embedding_model=my_embedding_model,
+            mode="both",
+        )
+        agent = Agent(
+            ...,
+            toolkit=Toolkit(tools=await mw.list_tools()),
+            middlewares=[mw],
+        )
+
+    Example (hosted Platform with pre-built client)::
+
+        from agentscope.middleware import Mem0Middleware
+        from agentscope.tool import Toolkit
+        from mem0 import AsyncMemoryClient
+
+        mw = Mem0Middleware(
+            user_id="alice",
+            client=AsyncMemoryClient(api_key="m0-..."),
+            mode="both",
+        )
+        agent = Agent(
+            ...,
+            toolkit=Toolkit(tools=await mw.list_tools()),
+            middlewares=[mw],
+        )
+    """
+
+    def __init__(
+        self,
+        *,
+        user_id: str,
+        client: Mem0AsyncClient | None = None,
+        chat_model: "ChatModelBase | None" = None,
+        embedding_model: "EmbeddingModelBase | None" = None,
+        mem0_config: Any | None = None,
+        mode: Literal["static_control", "agent_control", "both"] = "both",
+        agent_id: str | None = None,
+        top_k: int = 5,
+        threshold: float | None = None,
+        scope_search_by_agent: bool = True,
+        await_write: bool = True,
+        memory_section_header: str = DEFAULT_MEMORY_SECTION_HEADER,
+        memory_section_intro: str = DEFAULT_MEMORY_SECTION_INTRO,
+        tool_instructions: str = DEFAULT_TOOL_INSTRUCTIONS,
+    ) -> None:
+        """Initialize the mem0 middleware.
+
+        Three ways to wire up the mem0 backend:
+
+        - **Models only** — pass ``chat_model`` + ``embedding_model``
+          and the middleware builds a local OSS ``AsyncMemory`` wired
+          to them (mem0's default Qdrant for storage).
+        - **Models + ``mem0_config``** — same but starts from your
+          customized ``MemoryConfig``; only ``.llm`` / ``.embedder``
+          slots are overridden with the AgentScope adapters, every
+          other field (vector store, history DB, reranker, ...) is
+          preserved.
+        - **Client** — pass a pre-built mem0 client (OSS / Platform /
+          custom). When ``client`` is given it takes absolute
+          precedence; ``chat_model`` / ``embedding_model`` /
+          ``mem0_config`` are ignored, with a warning listing any
+          ignored kwargs.
+
+        Args:
+            user_id:
+                The mem0 ``user_id`` for memory namespacing. Required.
+            client:
+                A pre-built mem0 async client —
+                ``mem0.AsyncMemory`` (OSS) or
+                ``mem0.AsyncMemoryClient`` (Platform). Use this when
+                you want full control over the mem0 setup.
+            chat_model:
+                The AgentScope chat model mem0 should use for memory
+                extraction. Required if ``client`` is not given and
+                ``mem0_config`` does not already supply an LLM.
+            embedding_model:
+                The AgentScope embedding model mem0 should use to
+                embed memories. Required if ``client`` is not given
+                and ``mem0_config`` does not already supply an embedder.
+                Its ``dimensions`` must match mem0's vector store
+                (the default Qdrant expects 1536).
+            mem0_config:
+                Optional ``mem0.configs.base.MemoryConfig`` to use as
+                the base — lets you customize vector store / history
+                DB / reranker / etc. while still routing LLM and
+                embedding through AgentScope. Mutually exclusive with
+                ``client``.
+            mode:
+                How the agent interacts with mem0:
+
+                - ``"static_control"``: middleware searches mem0
+                  before each reply, appends the retrieved memories
+                  to ``agent.state.context`` as an
+                  ``AssistantMsg(name="memory")``, and writes the new
+                  exchange back after the reply. The agent never sees
+                  mem0 as a tool.
+                - ``"agent_control"``: middleware exposes
+                  ``search_memory`` / ``add_memory`` tools for the
+                  agent to invoke on demand, plus a short nudge in
+                  the system prompt. No automatic retrieval or
+                  write-back.
+                - ``"both"``: both patterns at once — auto retrieval
+                  AND on-demand tools.
+
+                Defaults to ``"both"`` (matching AgentScope 1.x's
+                ``ReActAgent.long_term_memory_mode`` default).
+            agent_id:
+                Optional mem0 ``agent_id`` for finer-grained
+                namespacing. When ``None`` (default) mem0 receives no
+                ``agent_id`` filter and memories are scoped by
+                ``user_id`` only.
+            top_k:
+                Max number of memories retrieved per static-control
+                search. Also serves as the default ``top_k`` for the
+                ``search_memory`` tool (the agent can override).
+            threshold:
+                Minimum similarity score. ``None`` lets mem0 decide.
+            scope_search_by_agent:
+                When ``True`` (default) search filters include both
+                ``user_id`` and ``agent_id`` — memories are scoped to
+                the agent that created them. When ``False`` search uses
+                ``user_id`` only, so a user's memories are shared across
+                agents.
+            await_write:
+                When ``True`` (default) the post-turn ``add`` call is
+                awaited inline. When ``False`` it's fire-and-forget —
+                faster response but exceptions only surface in logs.
+            memory_section_header, memory_section_intro:
+                Strings used when injecting retrieved memories into
+                the model's messages list (``static_control`` /
+                ``both`` modes).
+            tool_instructions:
+                Markdown block appended to the agent's system prompt
+                in ``agent_control`` / ``both`` modes, advertising the
+                ``search_memory`` / ``add_memory`` tools to the LLM.
+        """
+        is_empty_user_id = isinstance(user_id, str) and not user_id.strip()
+        if user_id is None or is_empty_user_id:
+            raise ValueError(
+                "Mem0Middleware requires a non-empty `user_id`.",
+            )
+        if mode not in ("static_control", "agent_control", "both"):
+            raise ValueError(
+                f"Unknown mode {mode!r}; expected one of "
+                f"'static_control', 'agent_control', 'both'.",
+            )
+
+        client = self._resolve_client(
+            client=client,
+            chat_model=chat_model,
+            embedding_model=embedding_model,
+            mem0_config=mem0_config,
+        )
+        self._client = client
+
+        self._user_id = user_id
+        self._agent_id = agent_id
+        self._mode = mode
+        self._top_k = top_k
+        self._threshold = threshold
+        self._scope_search_by_agent = scope_search_by_agent
+        self._await_write = await_write
+        self._memory_section_header = memory_section_header
+        self._memory_section_intro = memory_section_intro
+        self._tool_instructions = tool_instructions
+
+    # ------------------------------------------------------------------
+    # Hook: on_reply
+    # ------------------------------------------------------------------
+    async def on_reply(
+        self,
+        agent: "Agent",
+        input_kwargs: dict,
+        next_handler: Callable[..., AsyncGenerator],
+    ) -> AsyncGenerator:
+        user_id = self._user_id
+        agent_id = self._agent_id
+
+        # In pure agent_control mode the middleware is a no-op on the
+        # reply path — the agent decides when to invoke the memory
+        # tools — so just pass through.
+        if self._mode == "agent_control":
+            async for item in next_handler(**input_kwargs):
+                yield item
+            return
+
+        # static_control / both, mirroring AgentScope 1.x's ReActAgent:
+        # 1. Pre-fetch memories from mem0 using the user's new query.
+        # 2. Once the agent has actually ingested the new user input
+        #    into state.context (signaled by ReplyStartEvent — fires
+        #    right after _handle_incoming_messages and before the
+        #    reasoning loop), append the memory note. This places the
+        #    note IMMEDIATELY AFTER the user message in context, same
+        #    slot as v1's `_retrieve_from_long_term_memory` (which ran
+        #    right after `self.memory.add(msg)`).
+        # 3. After the reply finishes, write the new exchange back.
+        #
+        # The memory note persists in state.context across turns. Long
+        # sessions will accumulate one per turn that retrieved
+        # anything; rely on ``compress_context`` or pop them yourself
+        # if that becomes a token concern.
+        # user_id / agent_id already resolved + cached above.
+
+        inputs = input_kwargs.get("inputs")
+        query_text = _extract_query_text(inputs)
+
+        memories: list[str] = []
+        if query_text:
+            search_agent_id = agent_id if self._scope_search_by_agent else None
+            logger.info(
+                "mem0 search started: user_id=%s agent_id=%s chars=%d",
+                user_id,
+                search_agent_id,
+                len(query_text),
+            )
+            try:
+                memories = await self._async_search(
+                    query_text,
+                    user_id=user_id,
+                    agent_id=search_agent_id,
+                )
+                logger.info(
+                    "mem0 search finished: user_id=%s agent_id=%s memories=%d",
+                    user_id,
+                    search_agent_id,
+                    len(memories),
+                )
+            except Exception as e:  # noqa: BLE001
+                logger.warning(
+                    "mem0 search failed for user_id=%s: %s",
+                    user_id,
+                    e,
+                )
+
+        final_msg: Msg | None = None
+        injected = False
+        try:
+            async for item in next_handler(**input_kwargs):
+                is_reply_start = isinstance(item, ReplyStartEvent)
+                if not injected and memories and is_reply_start:
+                    agent.state.context.append(
+                        self._build_memory_message(memories),
+                    )
+                    injected = True
+                if isinstance(item, Msg) and item.role == "assistant":
+                    final_msg = item
+                yield item
+        finally:
+            if query_text and final_msg is not None:
+                assistant_text = final_msg.get_text_content()
+                if assistant_text:
+                    await self._dispatch_write(
+                        [
+                            {"role": "user", "content": query_text},
+                            {"role": "assistant", "content": assistant_text},
+                        ],
+                        user_id=user_id,
+                        agent_id=agent_id,
+                    )
+
+    # ------------------------------------------------------------------
+    # Hook: on_system_prompt (advertise memory tools to the LLM)
+    # ------------------------------------------------------------------
+    async def on_system_prompt(
+        self,
+        agent: "Agent",
+        current_prompt: str,
+    ) -> str:
+        """Append memory-tool instructions to the system prompt.
+
+        Args:
+            agent (`Agent`):
+                The agent whose system prompt is being transformed.
+            current_prompt (`str`):
+                The system prompt produced by previous middleware.
+
+        Returns:
+            `str`:
+                The unchanged prompt in static-control mode, otherwise the
+                prompt with memory-tool instructions appended.
+        """
+        if self._mode == "static_control":
+            return current_prompt
+        return f"{current_prompt}\n\n{self._tool_instructions}"
+
+    async def list_tools(self) -> list["ToolBase"]:
+        """List memory tools provided by this middleware.
+
+        Returns:
+            `list[ToolBase]`:
+                The ``search_memory`` and ``add_memory`` tools in
+                agent-control modes, otherwise an empty list.
+        """
+        if self._mode == "static_control":
+            return []
+        return _build_memory_tools(self)
+
+    # ==================================================================
+    # mem0 client construction
+    # ==================================================================
+    @staticmethod
+    def _resolve_client(
+        *,
+        client: "Mem0AsyncClient | None",
+        chat_model: "ChatModelBase | None",
+        embedding_model: "EmbeddingModelBase | None",
+        mem0_config: Any | None,
+    ) -> "Mem0AsyncClient":
+        """Resolve the constructor's mem0-backend kwargs into a single
+        async client.
+
+        ``client=`` takes absolute precedence — if given, the other
+        three (``chat_model`` / ``embedding_model`` / ``mem0_config``)
+        are ignored (a warning is logged so the mismatch is not
+        invisible). Otherwise, the rest are combined by
+        :func:`build_mem0_config` into an ``AsyncMemory``.
+        """
+        if client is not None:
+            ignored = [
+                name
+                for name, value in (
+                    ("chat_model", chat_model),
+                    ("embedding_model", embedding_model),
+                    ("mem0_config", mem0_config),
+                )
+                if value is not None
+            ]
+            if ignored:
+                logger.warning(
+                    "Mem0Middleware: `client` was provided, so %s "
+                    "%s ignored. Pass them via the mem0 client itself "
+                    "(or omit `client` to let the middleware build one "
+                    "for you).",
+                    ", ".join(ignored),
+                    "is" if len(ignored) == 1 else "are",
+                )
+        if client is None:
+            no_models = chat_model is None and embedding_model is None
+            if mem0_config is None and no_models:
+                raise ValueError(
+                    "Mem0Middleware needs one of: a pre-built `client`, "
+                    "a `mem0_config`, or both `chat_model` and "
+                    "`embedding_model`.",
+                )
+            # When no mem0_config is given, models must come as a pair.
+            if mem0_config is None and (
+                (chat_model is None) ^ (embedding_model is None)
+            ):
+                raise ValueError(
+                    "Mem0Middleware: `chat_model` and "
+                    "`embedding_model` must be passed together when "
+                    "`mem0_config` is not given.",
+                )
+
+            from mem0 import AsyncMemory
+
+            from ._agentscope_adapter import build_mem0_config
+
+            client = AsyncMemory(
+                config=build_mem0_config(
+                    chat_model=chat_model,
+                    embedding_model=embedding_model,
+                    mem0_config=mem0_config,
+                ),
+            )
+
+        if not _looks_async(
+            getattr(client, "search", None),
+        ) or not _looks_async(getattr(client, "add", None)):
+            raise TypeError(
+                "Mem0Middleware requires an async mem0 client "
+                "(`mem0.AsyncMemory` or `mem0.AsyncMemoryClient`). "
+                "The synchronous `Memory` / `MemoryClient` are not "
+                "supported.",
+            )
+        return client
+
+    # ==================================================================
+    # mem0 client adapters (OSS + Platform share this call shape)
+    # ==================================================================
+    async def _async_search(
+        self,
+        query: str,
+        *,
+        user_id: str,
+        agent_id: str | None,
+        top_k: int | None = None,
+    ) -> list[str]:
+        """Search mem0 and normalize the result into memory strings.
+
+        Args:
+            query (`str`):
+                Search query text.
+            user_id (`str`):
+                mem0 ``user_id`` namespace.
+            agent_id (`str | None`):
+                Optional mem0 ``agent_id`` namespace. ``None`` searches by
+                user only.
+            top_k (`int | None`, optional):
+                Optional per-call result limit. Defaults to the middleware's
+                configured ``top_k``.
+
+        Returns:
+            `list[str]`:
+                Retrieved memory texts extracted from mem0's response.
+        """
+        filters: dict[str, Any] = {"user_id": user_id}
+        if agent_id:
+            filters["agent_id"] = agent_id
+
+        kwargs: dict[str, Any] = {
+            "filters": filters,
+            "top_k": self._top_k if top_k is None else top_k,
+        }
+        if self._threshold is not None:
+            kwargs["threshold"] = self._threshold
+
+        raw = await self._client.search(query, **kwargs)
+        return _extract_memory_texts(raw)
+
+    async def _async_add(
+        self,
+        messages: list[dict[str, str]],
+        *,
+        user_id: str,
+        agent_id: str | None,
+        infer: bool = True,
+    ) -> dict | None:
+        """Add messages to mem0 using the shared async client call shape.
+
+        Args:
+            messages (`list[dict[str, str]]`):
+                mem0-compatible message dictionaries.
+            user_id (`str`):
+                mem0 ``user_id`` namespace.
+            agent_id (`str | None`):
+                Optional mem0 ``agent_id`` namespace.
+            infer (`bool`, optional):
+                Whether mem0 should run memory extraction. ``False`` asks
+                mem0 to store the text directly.
+
+        Returns:
+            `dict | None`:
+                The raw result returned by mem0.
+        """
+        kwargs: dict[str, Any] = {"user_id": user_id}
+        if agent_id:
+            kwargs["agent_id"] = agent_id
+        if not infer:
+            # mem0 docstring: ``infer=False`` skips the LLM extraction
+            # step and stores the message text directly.
+            kwargs["infer"] = False
+
+        return await self._client.add(messages, **kwargs)
+
+    async def _async_add_with_fallback(
+        self,
+        text: str,
+        *,
+        user_id: str,
+        agent_id: str | None,
+    ) -> dict | None:
+        """Two-tier add strategy: try extraction first; if mem0's
+        extraction LLM returns no memories, fall back to ``infer=False``
+        and save the raw text. Guarantees that ``add_memory`` always
+        persists *something* — matching AgentScope 1.x's
+        ``record_to_memory`` "always save" contract.
+
+        Historical note — why this is 2 tiers, not 3
+        ---------------------------------------------
+        AgentScope 1.x's ``record_to_memory`` had a 3-tier fallback:
+        (a) user role → (b) assistant role → (c) assistant + infer=False.
+        Tier (b) was meaningful against **old** mem0, which routed
+        user-role messages through ``USER_MEMORY_EXTRACTION_PROMPT``
+        and assistant-role messages through
+        ``AGENT_MEMORY_EXTRACTION_PROMPT`` — two genuinely different
+        prompts, so switching role had a real chance of rescuing an
+        empty extraction.
+
+        Current mem0 (v2.x) restructured this in
+        ``_add_to_vector_store``:
+
+            parsed_messages = parse_messages(messages)
+            ...
+            is_agent_scoped = bool(filters.get("agent_id")) \\
+                              and not filters.get("user_id")
+            system_prompt = ADDITIVE_EXTRACTION_PROMPT
+            if is_agent_scoped:
+                system_prompt += AGENT_CONTEXT_SUFFIX
+
+        Prompt selection now depends on the **filters dict**, not on
+        the message role. ``ADDITIVE_EXTRACTION_PROMPT`` itself says
+        explicitly "You extract from BOTH user and assistant messages"
+        (it just changes attribution framing). Since this middleware
+        always passes both ``user_id`` and ``agent_id`` (when scoping
+        is on), ``is_agent_scoped`` is always False and the same
+        ``ADDITIVE_EXTRACTION_PROMPT`` runs regardless of message role.
+        Retrying with role="assistant" is a no-op LLM call.
+
+        So tier (b) is dropped. Tier (c) ``infer=False`` is still
+        valuable — it bypasses extraction entirely and saves raw
+        text, useful when mem0 decides nothing in the input is
+        memory-worthy but the caller wants the bytes persisted anyway.
+        """
+        # 1. Normal path: let mem0's extraction LLM do its job.
+        result = await self._async_add(
+            [{"role": "user", "content": text, "name": "user"}],
+            user_id=user_id,
+            agent_id=agent_id,
+        )
+        if _mem0_extracted_anything(result):
+            return result
+
+        # 2. Raw save: extraction returned empty, persist the raw text
+        # so the caller's ``add_memory`` invocation isn't silently
+        # discarded.
+        return await self._async_add(
+            [{"role": "user", "content": text, "name": "user"}],
+            user_id=user_id,
+            agent_id=agent_id,
+            infer=False,
+        )
+
+    # ==================================================================
+    # Helpers
+    # ==================================================================
+    def _build_memory_message(self, memories: list[str]) -> Msg:
+        """Format retrieved ``memories`` as a synthetic hint message.
+
+        The context entry uses an assistant-role ``Msg`` container because
+        user messages cannot carry ``HintBlock`` content. Formatters convert
+        the ``HintBlock`` itself into a user message before the model call.
+
+        Args:
+            memories (`list[str]`):
+                Retrieved memory texts to expose to the model.
+
+        Returns:
+            `Msg`:
+                An assistant-role message containing one ``HintBlock``.
+        """
+        bullets = "\n".join(f"- {m}" for m in memories)
+        content = (
+            f"{self._memory_section_header}\n"
+            f"{self._memory_section_intro}\n"
+            f"{bullets}"
+        )
+        return AssistantMsg(
+            name="memory",
+            content=[HintBlock(hint=content)],
+        )
+
+    async def _dispatch_write(
+        self,
+        messages: list[dict[str, str]],
+        *,
+        user_id: str,
+        agent_id: str | None,
+    ) -> None:
+        """Persist a completed user/assistant exchange to mem0.
+
+        When ``await_write`` is enabled, the add call is awaited inline so
+        errors can be logged before reply cleanup completes. Otherwise, to
+        write is scheduled as a background task and failures are logged there.
+
+        Args:
+            messages (`list[dict[str, str]]`):
+                User/assistant message pair to persist.
+            user_id (`str`):
+                mem0 ``user_id`` namespace.
+            agent_id (`str | None`):
+                Optional mem0 ``agent_id`` namespace.
+        """
+        if self._await_write:
+            try:
+                logger.info(
+                    "mem0 write started: user_id=%s agent_id=%s messages=%d",
+                    user_id,
+                    agent_id,
+                    len(messages),
+                )
+                await self._async_add(
+                    messages,
+                    user_id=user_id,
+                    agent_id=agent_id,
+                )
+                logger.info(
+                    "mem0 write finished for user_id=%s agent_id=%s",
+                    user_id,
+                    agent_id,
+                )
+            except Exception as e:  # noqa: BLE001
+                logger.warning(
+                    "mem0 add failed for user_id=%s: %s",
+                    user_id,
+                    e,
+                )
+        else:
+
+            async def _bg() -> None:
+                try:
+                    logger.info(
+                        "mem0 background write started for user_id=%s "
+                        "agent_id=%s messages=%d",
+                        user_id,
+                        agent_id,
+                        len(messages),
+                    )
+                    await self._async_add(
+                        messages,
+                        user_id=user_id,
+                        agent_id=agent_id,
+                    )
+                    logger.info(
+                        "mem0 bg write finished: user_id=%s agent_id=%s",
+                        user_id,
+                        agent_id,
+                    )
+                except Exception as e:  # noqa: BLE001
+                    logger.warning(
+                        "mem0 background add failed for user_id=%s: %s",
+                        user_id,
+                        e,
+                    )
+
+            asyncio.create_task(_bg())
diff --git a/src/agentscope/middleware/_longterm_memory/_mem0/_tools.py b/src/agentscope/middleware/_longterm_memory/_mem0/_tools.py
new file mode 100644
index 0000000..633ed89
--- /dev/null
+++ b/src/agentscope/middleware/_longterm_memory/_mem0/_tools.py
@@ -0,0 +1,270 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Agent-control tools exposed by the mem0 middleware.
+
+These ``search_memory`` / ``add_memory`` tools are listed by
+:class:`Mem0Middleware` when ``mode`` is ``"agent_control"`` or
+``"both"``. Callers pass them into the agent's toolkit explicitly.
+Each tool reads ``user_id`` / ``agent_id`` directly from the
+middleware instance — both are plain strings set at construction
+time, so no Agent instance is stored or referenced at call time.
+
+Shape and behavior mirror AgentScope 1.x's
+``Mem0LongTermMemory.retrieve_from_memory`` / ``record_to_memory``
+(multi-keyword parallel search, fallback write, verbose result
+text) — adapted to AgentScope 2.x's tool conventions
+(custom ``ToolBase`` implementations; failures return a ``ToolChunk``
+with ``state=ERROR`` so the toolkit aggregates it properly).
+"""
+from __future__ import annotations
+
+import asyncio
+from typing import Any, TYPE_CHECKING
+
+from ....message import TextBlock, ToolResultState
+from ....permission import PermissionBehavior, PermissionDecision
+from ....tool import ToolBase, ToolChunk
+
+if TYPE_CHECKING:
+    from ._middleware import Mem0Middleware
+
+
+class _Mem0MemoryToolBase(ToolBase):
+    """Base class for mem0 tools that auto-allow themselves.
+
+    Middleware-provided memory tools are part of the agent's standard
+    capabilities — prompting on every call would defeat the point.
+    """
+
+    is_external_tool: bool = False
+    is_state_injected: bool = False
+    is_mcp: bool = False
+    mcp_name: str | None = None
+
+    def __init__(
+        self,
+        mw: "Mem0Middleware",
+    ) -> None:
+        self._mw = mw
+
+    async def check_permissions(
+        self,
+        *_args: Any,
+        **_kwargs: Any,
+    ) -> PermissionDecision:
+        return PermissionDecision(
+            behavior=PermissionBehavior.ALLOW,
+            message="auto-allowed: mem0 long-term memory tool",
+        )
+
+
+class _SearchMemoryTool(_Mem0MemoryToolBase):
+    """Agent-callable mem0 search tool."""
+
+    name: str = "search_memory"
+    description: str = (
+        "Retrieve memories based on short, targeted search keywords. "
+        "Each keyword is issued as an independent query; results are merged "
+        "and deduplicated."
+    )
+    input_schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {
+            "keywords": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": (
+                    "Short, targeted search phrases such as a person's name, "
+                    "a specific date, a location, or a phrase describing what "
+                    "to retrieve from memory."
+                ),
+            },
+            "limit": {
+                "type": "integer",
+                "description": (
+                    "Maximum number of memories to retrieve per keyword."
+                ),
+                "default": 5,
+            },
+        },
+        "required": ["keywords"],
+    }
+    is_concurrency_safe: bool = True
+    is_read_only: bool = True
+
+    async def __call__(
+        self,
+        keywords: list[str],
+        limit: int = 5,
+    ) -> ToolChunk:
+        """Retrieve the memory based on the given keywords.
+
+        Args:
+            keywords (list[str]):
+                Short, targeted search phrases (for example, a person's
+                name, a specific date, a location, or a phrase
+                describing something you want to retrieve from the
+                memory). Each keyword is issued as an independent query
+                against the memory store; results are merged and
+                deduplicated.
+            limit (int):
+                The maximum number of memories to retrieve per keyword.
+                Defaults to 5.
+        """
+        if not keywords:
+            return _text_chunk("(no keywords supplied — nothing to search)")
+
+        user_id = self._mw._user_id
+        agent_id = self._mw._agent_id
+        search_agent_id = agent_id if self._mw._scope_search_by_agent else None
+
+        # Match v1: each keyword is an independent search, run them in
+        # parallel and merge.
+        try:
+            per_keyword = await asyncio.gather(
+                *[
+                    self._mw._async_search(
+                        kw,
+                        user_id=user_id,
+                        agent_id=search_agent_id,
+                        top_k=limit,
+                    )
+                    for kw in keywords
+                ],
+            )
+        except Exception as e:  # noqa: BLE001
+            return _error_chunk(f"Error retrieving memory: {e}")
+
+        seen: set[str] = set()
+        merged: list[str] = []
+        for results in per_keyword:
+            for r in results:
+                if r not in seen:
+                    seen.add(r)
+                    merged.append(r)
+
+        if not merged:
+            return _text_chunk("(no relevant memories found)")
+        return _text_chunk("\n".join(f"- {m}" for m in merged))
+
+
+class _AddMemoryTool(_Mem0MemoryToolBase):
+    """Agent-callable mem0 write tool."""
+
+    name: str = "add_memory"
+    description: str = (
+        "Record important, durable information that may be useful later. "
+        "Only the provided content is persisted; thinking is retained in the "
+        "tool result for auditability."
+    )
+    input_schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {
+            "thinking": {
+                "type": "string",
+                "description": (
+                    "Reasoning about why this information is worth "
+                    "remembering. This is not persisted to mem0."
+                ),
+            },
+            "content": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": (
+                    "Specific facts to remember. Each item should be a "
+                    "complete, standalone sentence."
+                ),
+            },
+        },
+        "required": ["thinking", "content"],
+    }
+    is_concurrency_safe: bool = False
+    is_read_only: bool = False
+
+    async def __call__(
+        self,
+        thinking: str,
+        content: list[str],
+    ) -> ToolChunk:
+        """Use this function to record important information that you
+        may need later. The target content should be specific and
+        concise, e.g. who, when, where, do what, why, how, etc.
+
+        Do NOT pass back content that appears earlier in the
+        conversation history as a previous ``search_memory`` tool
+        result — those facts are already in the store, re-adding them
+        wastes an extraction call.
+
+        Args:
+            thinking (str):
+                Your reasoning about why this is worth remembering.
+                Stays in the agent transcript but is NOT persisted to
+                the memory store — only ``content`` is. Use it to
+                force yourself to think before writing.
+            content (list[str]):
+                The content to remember, as a list of strings (one
+                item per fact). Each item should be a complete,
+                standalone sentence — only this is sent to mem0 for
+                extraction.
+        """
+        if not content:
+            return _error_chunk("`content` is empty — nothing to record.")
+
+        user_id = self._mw._user_id
+        agent_id = self._mw._agent_id
+
+        # Only the user-facing content goes into mem0. ``thinking`` is
+        # the agent's internal rationale — meta about the agent's
+        # decision, not a fact about the user — so feeding it to
+        # mem0's extraction LLM would muddy the stored memories with
+        # agent self-narration. We keep it in the tool response so the
+        # decision is auditable in the transcript.
+        text = "\n".join(content)
+
+        try:
+            result = await self._mw._async_add_with_fallback(
+                text,
+                user_id=user_id,
+                agent_id=agent_id,
+            )
+        except Exception as e:  # noqa: BLE001
+            return _error_chunk(f"Error recording memory: {e}")
+
+        rationale = f" (rationale: {thinking})" if thinking else ""
+        return _text_chunk(
+            f"Successfully recorded to memory{rationale} → {result}",
+        )
+
+
+def _build_memory_tools(
+    mw: "Mem0Middleware",
+) -> list[ToolBase]:
+    """Return the ``search_memory`` / ``add_memory`` tools bound to
+    ``mw``.
+
+    The tool classes intentionally reach into ``mw``'s private state
+    (``_resolve_user_id`` / ``_async_search`` / ...) —
+    we live in the same package and ``mw`` is the natural place for
+    that state.
+    """
+    return [
+        _SearchMemoryTool(mw),
+        _AddMemoryTool(mw),
+    ]
+
+
+def _text_chunk(message: str) -> ToolChunk:
+    """Wrap a text message as a normal tool chunk."""
+    return ToolChunk(
+        content=[TextBlock(type="text", text=message)],
+    )
+
+
+def _error_chunk(message: str) -> ToolChunk:
+    """Wrap an error message as a ``ToolChunk(state=ERROR)`` so the
+    toolkit aggregates it as a failed tool call — the agent sees the
+    message and can decide whether to retry or move on."""
+    return ToolChunk(
+        content=[TextBlock(type="text", text=message)],
+        state=ToolResultState.ERROR,
+    )
diff --git a/src/agentscope/middleware/_longterm_memory/_mem0/_utils.py b/src/agentscope/middleware/_longterm_memory/_mem0/_utils.py
new file mode 100644
index 0000000..2291f34
--- /dev/null
+++ b/src/agentscope/middleware/_longterm_memory/_mem0/_utils.py
@@ -0,0 +1,76 @@
+# -*- coding: utf-8 -*-
+"""Pure helper functions for the mem0 middleware.
+
+These are stateless adapters that translate between AgentScope and
+mem0 data shapes. Keeping them out of the middleware class makes them
+trivial to unit-test in isolation.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from ....event import ExternalExecutionResultEvent, UserConfirmResultEvent
+from ....message import Msg
+
+
+def _extract_query_text(inputs: Any) -> str | None:
+    """Pull a single text query out of the agent inputs.
+
+    Returns ``None`` for resumption events or empty/non-user inputs,
+    in which case the middleware skips both retrieval and write-back.
+    """
+    if inputs is None:
+        return None
+    if isinstance(
+        inputs,
+        (ExternalExecutionResultEvent, UserConfirmResultEvent),
+    ):
+        return None
+
+    msgs = inputs if isinstance(inputs, list) else [inputs]
+    texts: list[str] = []
+    for m in msgs:
+        if not isinstance(m, Msg) or m.role != "user":
+            continue
+        text = m.get_text_content()
+        if text:
+            texts.append(text)
+    return "\n".join(texts) if texts else None
+
+
+def _mem0_extracted_anything(raw: Any) -> bool:
+    """Did mem0's add() actually extract any memories from the input?
+
+    mem0 returns ``{"results": [...]}``; an empty list means its LLM
+    extractor decided nothing was worth storing. The
+    ``_async_add_with_fallback`` strategy uses this to decide whether
+    to try another role / disable inference.
+    """
+    if not isinstance(raw, dict):
+        return False
+    results = raw.get("results")
+    return isinstance(results, list) and len(results) > 0
+
+
+def _extract_memory_texts(raw: Any) -> list[str]:
+    """Flatten a mem0 search response into a list of memory strings.
+
+    Tolerates the common shapes:
+      - ``{"results": [{"memory": str, ...}, ...]}`` (current OSS / Platform)
+      - ``[{"memory": str, ...}, ...]`` (legacy / variations)
+      - ``{"results": [str, ...]}`` (defensive fallback)
+    """
+    if raw is None:
+        return []
+    results = raw.get("results", raw) if isinstance(raw, dict) else raw
+    if not isinstance(results, list):
+        return []
+    out: list[str] = []
+    for item in results:
+        if isinstance(item, str):
+            out.append(item)
+        elif isinstance(item, dict):
+            text = item.get("memory") or item.get("text")
+            if text:
+                out.append(str(text))
+    return out
diff --git a/src/agentscope/middleware/_longterm_memory/_reme/__init__.py b/src/agentscope/middleware/_longterm_memory/_reme/__init__.py
new file mode 100644
index 0000000..ece1942
--- /dev/null
+++ b/src/agentscope/middleware/_longterm_memory/_reme/__init__.py
@@ -0,0 +1,16 @@
+# -*- coding: utf-8 -*-
+"""ReMe-backed long-term memory middleware for AgentScope.
+
+`ReMe <https://github.com/agentscope-ai/ReMe>`_ (``reme-ai``) is a
+file-based memory toolkit built on AgentScope. This package embeds the
+ReMe application in-process and exposes:
+
+- :class:`ReMeMiddleware` — AgentScope middleware wiring an agent to an
+  embedded ``reme.ReMe`` app (holds the app directly, mirroring how
+  :class:`Mem0Middleware` holds a native ``mem0`` client).
+"""
+from ._middleware import ReMeMiddleware
+
+__all__ = [
+    "ReMeMiddleware",
+]
diff --git a/src/agentscope/middleware/_longterm_memory/_reme/_middleware.py b/src/agentscope/middleware/_longterm_memory/_reme/_middleware.py
new file mode 100644
index 0000000..e59ead4
--- /dev/null
+++ b/src/agentscope/middleware/_longterm_memory/_reme/_middleware.py
@@ -0,0 +1,564 @@
+# -*- coding: utf-8 -*-
+"""ReMe-backed long-term memory middleware for AgentScope agents.
+
+`ReMe <https://github.com/agentscope-ai/ReMe>`_ is a file-based memory
+toolkit built on AgentScope. This middleware **embeds the ReMe
+application in-process** (no separate service to run); a chat model for
+ReMe's LLM-backed jobs is configured once at construction.
+
+ReMe records memory by **listening to the conversation through the
+``on_reply`` hook** — after every reply the new exchange is written back
+via ReMe's ``auto_memory`` job, in *all* modes. The agent never writes
+memory itself; there is no manual add tool. The ``mode`` parameter only
+controls **retrieval**:
+
+- ``"static_control"`` — search ReMe when a reply starts and inject the
+  retrieved memories into context before a later reasoning step (plus the
+  automatic write-back). Retrieval runs concurrently with the reply, so
+  injection is best-effort: a single-shot reply may finish first.
+- ``"agent_control"`` — expose a ``memory_search`` tool the agent calls
+  on demand (plus the automatic write-back); no auto-retrieval.
+- ``"both"`` — auto-retrieve/inject *and* expose ``memory_search``.
+
+ReMe scopes writes by ``session_id``, which is read from
+``agent.state.session_id`` at hook time (not configured on the
+middleware), so it always matches the agent's own session; search runs
+over the whole workspace.
+"""
+from __future__ import annotations
+
+import asyncio
+from typing import (
+    Any,
+    AsyncGenerator,
+    Callable,
+    Literal,
+    TYPE_CHECKING,
+)
+
+from pydantic import BaseModel, Field
+
+from ..._base import MiddlewareBase
+from ...._logging import logger
+from ....embedding import EmbeddingModelBase
+from ....message import AssistantMsg, HintBlock, Msg
+from ....model import ChatModelBase
+from ._tools import _build_memory_tools
+from ._utils import _extract_memory_texts, _extract_query_text
+
+if TYPE_CHECKING:
+    from ....agent import Agent
+    from ....tool import ToolBase
+
+
+# Jobs exposed by the ReMe application that this middleware drives.
+_SEARCH_JOB = "search"
+_AUTO_MEMORY_JOB = "auto_memory"
+
+# ReMe component coordinates for the default chat-model / embedding
+# backends. ReMe starts both eagerly at ``start()`` (the embedding
+# component is wired in even when the default file store searches
+# keyword-only), so an injected model bypasses ReMe building its own
+# from credentials — the same escape hatch for both components.
+_AS_LLM_COMPONENT = "as_llm"
+_AS_EMBEDDING_COMPONENT = "as_embedding"
+_AS_DEFAULT = "default"
+
+# Header rendered above retrieved memories injected into context.
+_MEMORY_MSG_NAME = "memory"
+_MEMORY_SECTION_HEADER = "## Relevant memories from past conversations"
+_MEMORY_SECTION_INTRO = (
+    "The following memories about the user may be relevant. "
+    "Use them only if they are pertinent to the current request."
+)
+
+# Appended to the system prompt to advertise the search tool to the LLM.
+_TOOL_INSTRUCTIONS = (
+    "## Long-term memory\n\n"
+    "You have a `memory_search` tool available. Use it whenever the "
+    "current conversation may depend on a durable fact from a past "
+    "session (a preference, a name, a prior decision). Recording memory "
+    "is handled automatically; there is no add tool."
+)
+
+
+class ReMeMiddleware(MiddlewareBase):
+    """AgentScope middleware that adds long-term memory backed by
+    `ReMe <https://github.com/agentscope-ai/ReMe>`_.
+
+    ReMe is embedded **in-process** (no separate service): the middleware
+    instantiates a :class:`reme.ReMe` application whose LLM-backed jobs use
+    the ``chat_model`` configured at construction. The app is built and
+    owned by the middleware — pass ``workspace_dir`` / ``config`` (and
+    optionally a ``Parameters`` with ``chat_model`` / ``embedding_model``)
+    and it is created lazily on first use. When ``chat_model`` is omitted,
+    ReMe uses the LLM from its own config/credentials. Providing an
+    ``embedding_model`` enables ReMe's vector store; otherwise search stays
+    keyword-only.
+
+    The model is fixed at construction (never taken from an agent), so the
+    embedded app's single LLM is well-defined even when one middleware
+    instance is shared across several agents. Per-conversation state — the
+    ReMe ``session_id`` — is instead read live from each agent at hook
+    time and never stored, keeping shared use isolated. Background
+    retrieval tasks are likewise tracked per ``session_id`` so concurrent
+    replies in different sessions never clobber each other's in-flight
+    search.
+
+    AgentScope middleware has no framework-managed lifecycle, so the app
+    is built once and started lazily on first use (idempotent). Call
+    :meth:`close` for explicit teardown of the embedded app.
+
+    Example::
+
+        from agentscope.middleware import ReMeMiddleware
+        from agentscope.tool import Toolkit
+
+        mw = ReMeMiddleware(
+            workspace_dir=".reme",
+            parameters=ReMeMiddleware.Parameters(mode="both"),
+        )
+        agent = Agent(
+            ...,
+            toolkit=Toolkit(tools=await mw.list_tools()),
+            middlewares=[mw],
+        )
+    """
+
+    class Parameters(BaseModel):
+        """User-tunable ReMe memory parameters.
+
+        The agent service parses this schema to render a configuration
+        form. Structural wiring (``workspace_dir`` / ``config``) stays on
+        the constructor.
+        """
+
+        model_config = {"arbitrary_types_allowed": True}
+
+        chat_model: ChatModelBase | None = Field(
+            default=None,
+            title="Chat Model",
+            description=(
+                "AgentScope chat model injected into ReMe's default LLM "
+                "component, fixed for the lifetime of the embedded app. "
+                "When `None`, ReMe uses the LLM from its own "
+                "config/credentials. Needed for `auto_memory` write-back."
+            ),
+        )
+
+        embedding_model: EmbeddingModelBase | None = Field(
+            default=None,
+            title="Embedding Model",
+            description=(
+                "AgentScope embedding model injected into ReMe's default "
+                "embedding component, fixed for the lifetime of the embedded "
+                "app. ReMe starts this component eagerly (it is wired into "
+                "the file store even when search is keyword-only), so "
+                "injecting a model bypasses ReMe building its own from "
+                "credentials. When `None`, ReMe uses the embedding backend "
+                "from its own config/credentials."
+            ),
+        )
+
+        mode: Literal["static_control", "agent_control", "both"] = Field(
+            default="both",
+            title="Retrieval Mode",
+            description=(
+                "How the agent retrieves from ReMe (write-back runs "
+                "automatically in every mode). `static_control`: search and "
+                "inject before each reply, no tool. `agent_control`: expose "
+                "the `memory_search` tool, no auto-retrieval. `both`: "
+                "auto-retrieve/inject and expose the tool."
+            ),
+        )
+
+        top_k: int = Field(
+            default=5,
+            title="Top K",
+            description=(
+                "Max number of memories retrieved per search, and the "
+                "default `limit` advertised by the `memory_search` tool."
+            ),
+        )
+
+    def __init__(
+        self,
+        *,
+        workspace_dir: str = ".reme",
+        config: str = "default",
+        parameters: Parameters | None = None,
+    ) -> None:
+        """Initialize the ReMe middleware.
+
+        The ReMe ``session_id`` (which scopes write-back memory cards) is
+        **not** taken here — it is read from ``agent.state.session_id`` at
+        hook time (every agent has one; ``AgentState`` generates it),
+        mirroring :class:`TracingMiddleware`. To pin a resumable session,
+        set the id on the agent (``Agent(state=AgentState(session_id=...))``).
+
+        Args:
+            workspace_dir (`str`, optional):
+                ReMe workspace (vault) directory for memory cards and
+                indexes. Defaults to ``".reme"``.
+            config (`str`, optional):
+                ReMe config name or path. Defaults to ``"default"``
+                (ReMe's bundled ``default.yaml``).
+            parameters (`ReMeMiddleware.Parameters | None`, optional):
+                User-tunable parameters (``chat_model`` / ``embedding_model``
+                / ``mode`` / ``top_k``) whose schema the agent service
+                renders as a configuration form. When ``None``, defaults are
+                used. Providing an ``embedding_model`` also enables ReMe's
+                vector store (otherwise search is keyword-only).
+        """
+        # Embedded ReMe application state. The app is built lazily and
+        # started once (idempotent guards), since middleware has no
+        # framework-managed lifecycle. The middleware always owns the app
+        # it builds, so :meth:`close` tears it down.
+        self._app: Any | None = None
+        self._started = False
+        self._workspace_dir = workspace_dir
+        self._config = config
+        self._parameters = parameters or self.Parameters()
+        # In-flight background retrieval per session (started in ``on_reply``,
+        # consumed/injected in ``on_reasoning``, cleaned up in ``on_reply``'s
+        # finally). Keyed by ``session_id`` so one middleware shared across
+        # agents keeps each session's retrieval isolated — a concurrent reply
+        # in another session never clobbers this one's task.
+        self._retrieval_tasks: dict[Any, asyncio.Task] = {}
+
+    # ==================================================================
+    # Embedded ReMe application lifecycle
+    # ==================================================================
+    def _build_app(self) -> Any:
+        """Lazily build the embedded :class:`reme.ReMe` application.
+
+        Raises:
+            ImportError:
+                If ``reme-ai`` is not installed.
+        """
+        try:
+            from reme import ReMe
+            from reme.config import resolve_app_config
+        except ImportError as e:  # pragma: no cover - import guard
+            raise ImportError(
+                "ReMeMiddleware requires the `reme-ai` package. Install "
+                'it with `pip install "agentscope[reme]"` (or '
+                "`pip install reme-ai`).",
+            ) from e
+
+        app_kwargs: dict[str, Any] = {
+            "config": self._config,
+            "workspace_dir": self._workspace_dir,
+            "enable_logo": False,
+            "log_to_console": False,
+        }
+        # An embedding model turns on ReMe's vector store: the bundled
+        # ``default`` config ships it off (BM25 keyword search only), so we
+        # wire the file store to the default embedding store when — and
+        # only when — a model is available to build the vectors.
+        if self._parameters.embedding_model is not None:
+            app_kwargs["components"] = {
+                "file_store": {"default": {"embedding_store": "default"}},
+            }
+        app_config = resolve_app_config(**app_kwargs)
+        return ReMe(**app_config)
+
+    async def _ensure_started(self) -> None:
+        """Build (if needed) and start the embedded app (idempotent).
+
+        The configured ``chat_model`` / ``embedding_model`` are injected
+        into ReMe's default LLM and embedding components **before** the
+        one-time ``start()`` (ReMe's ``BaseAsLLM._start`` /
+        ``BaseAsEmbedding._start`` skip building a model from credentials
+        when ``model`` is already set). Both are fixed at construction —
+        never taken from an agent — so the embedded app (which has a
+        single LLM and a single embedding component) has one well-defined
+        model each regardless of how many agents share this middleware.
+        When either is ``None``, ReMe falls back to the backend configured
+        in its own config/credentials.
+        """
+        if self._app is None:
+            self._app = self._build_app()
+        if not self._started:
+            if self._parameters.chat_model is not None:
+                await self._app.update_component(
+                    _AS_LLM_COMPONENT,
+                    _AS_DEFAULT,
+                    model=self._parameters.chat_model,
+                )
+            if self._parameters.embedding_model is not None:
+                await self._app.update_component(
+                    _AS_EMBEDDING_COMPONENT,
+                    _AS_DEFAULT,
+                    model=self._parameters.embedding_model,
+                )
+            await self._app.start()
+            self._started = True
+
+    async def close(self) -> None:
+        """Close the embedded ReMe app.
+
+        AgentScope does not manage middleware lifecycle, so call this
+        explicitly for clean teardown (e.g. on application shutdown).
+        """
+        if self._app is not None and self._started:
+            await self._app.close()
+        self._started = False
+
+    @staticmethod
+    def _session_id_of(agent: "Agent") -> str | None:
+        """Read the ReMe ``session_id`` live from the agent.
+
+        ReMe scopes write-back memory cards by ``session_id``. It is read
+        from ``agent.state.session_id`` at hook time and threaded through
+        per call — **never** stored on the middleware — so a single
+        instance shared across agents keeps each conversation's writes
+        isolated. Mirrors how :class:`TracingMiddleware` sources the
+        session from the agent rather than from middleware config.
+        """
+        return getattr(getattr(agent, "state", None), "session_id", None)
+
+    # ------------------------------------------------------------------
+    # Hook: on_reply
+    # ------------------------------------------------------------------
+    async def on_reply(
+        self,
+        agent: "Agent",
+        input_kwargs: dict,
+        next_handler: Callable[..., AsyncGenerator],
+    ) -> AsyncGenerator:
+        session_id = self._session_id_of(agent)
+
+        # Kick off retrieval (static_control / both only) concurrently with
+        # the reply. It runs in the background while the agent ingests input
+        # and starts reasoning; ``on_reasoning`` injects the result once the
+        # task finishes. Write the new exchange back afterwards in every mode.
+        inputs = input_kwargs.get("inputs")
+        query_text = _extract_query_text(inputs)
+
+        # Discard any stale task left for this session (a previous turn that
+        # never reached its finally is unexpected, but never leak one).
+        stale = self._retrieval_tasks.pop(session_id, None)
+        if stale is not None and not stale.done():
+            stale.cancel()
+        if self._parameters.mode != "agent_control" and query_text:
+            self._retrieval_tasks[session_id] = asyncio.create_task(
+                self._search(query_text),
+            )
+
+        # Snapshot the context BEFORE the turn so the write-back persists
+        # only this turn's *increment*. ReMe's ``auto_memory`` consumes the
+        # incremental exchange, whereas ``agent.state.context`` is the full
+        # accumulated history — so we diff by message id (below) rather than
+        # sending the whole context, which would re-feed every prior turn.
+        # Taking the increment (not just the final message) still captures
+        # every step of the turn — user input, each assistant step, and
+        # every tool call / tool result — which the agent records on
+        # ``state.context`` via ``_save_to_context`` but does not all yield
+        # on the stream (only the final answer is yielded).
+        pre_ids = {m.id for m in agent.state.context if isinstance(m, Msg)}
+
+        try:
+            async for item in next_handler(**input_kwargs):
+                yield item
+        finally:
+            # Retrieval may still be running (or its hint may never have been
+            # injected — e.g. a single-shot reply that finished before the
+            # task did). Consume this session's task so none is orphaned.
+            task = self._retrieval_tasks.pop(session_id, None)
+            if task is not None and not task.done():
+                task.cancel()
+            if task is not None:
+                try:
+                    await task
+                except (asyncio.CancelledError, Exception):  # noqa: BLE001
+                    pass
+            # This turn's new messages only: everything now present that
+            # was not before, minus any memory hint we injected (matched by
+            # its reserved name, since injection happens in ``on_reasoning``).
+            increment = [
+                m
+                for m in agent.state.context
+                if isinstance(m, Msg)
+                and m.id not in pre_ids
+                and getattr(m, "name", None) != _MEMORY_MSG_NAME
+            ]
+            # Only persist a real exchange: a genuine user turn plus at
+            # least one non-empty assistant message produced this turn.
+            if query_text and any(
+                m.role == "assistant" and m.get_text_content()
+                for m in increment
+            ):
+                await self._write_back(increment, session_id)
+
+    # ------------------------------------------------------------------
+    # Hook: on_reasoning (inject retrieved memories once ready)
+    # ------------------------------------------------------------------
+    async def on_reasoning(
+        self,
+        agent: "Agent",
+        input_kwargs: dict,
+        next_handler: Callable[..., AsyncGenerator],
+    ) -> AsyncGenerator:
+        """Inject background-retrieved memories before a reasoning step.
+
+        The search started in :meth:`on_reply` runs concurrently; this hook
+        polls it before each reasoning step and, once it is finished, appends
+        the retrieved memories to the agent's context so the *next* model
+        call sees them. This is best-effort: a single-shot reply (one model
+        call) may finish before retrieval does, in which case the hint is
+        skipped for that turn — the same trade-off as
+        :class:`AgenticMemoryMiddleware`.
+        """
+        session_id = self._session_id_of(agent)
+        task = self._retrieval_tasks.get(session_id)
+        if task is not None and task.done():
+            self._retrieval_tasks.pop(session_id, None)
+            try:
+                memories = task.result()
+            except (asyncio.CancelledError, Exception) as e:  # noqa: BLE001
+                memories = []
+                logger.warning("ReMe search failed: %s", e)
+            if memories:
+                agent.state.context.append(
+                    self._build_memory_message(memories),
+                )
+
+        async for event in next_handler(**input_kwargs):
+            yield event
+
+    # ------------------------------------------------------------------
+    # Hook: on_system_prompt (advertise the search tool to the LLM)
+    # ------------------------------------------------------------------
+    async def on_system_prompt(
+        self,
+        agent: "Agent",
+        current_prompt: str,
+    ) -> str:
+        """Append search-tool instructions to the system prompt.
+
+        Args:
+            agent (`Agent`):
+                The agent whose system prompt is being transformed.
+            current_prompt (`str`):
+                The system prompt produced by previous middleware.
+
+        Returns:
+            `str`:
+                The unchanged prompt in static-control mode, otherwise the
+                prompt with the ``memory_search`` nudge appended.
+        """
+        if self._parameters.mode == "static_control":
+            return current_prompt
+        return f"{current_prompt}\n\n{_TOOL_INSTRUCTIONS}"
+
+    async def list_tools(self) -> list["ToolBase"]:
+        """List memory tools provided by this middleware.
+
+        Returns:
+            `list[ToolBase]`:
+                The ``memory_search`` tool in agent-control modes
+                (``"agent_control"`` / ``"both"``), otherwise an empty
+                list. There is no add tool — writing is automatic.
+        """
+        if self._parameters.mode == "static_control":
+            return []
+        return _build_memory_tools(self)
+
+    # ==================================================================
+    # ReMe job helpers (shared by hooks and tools)
+    # ==================================================================
+    async def _run_job(self, name: str, **kwargs: Any) -> Any:
+        """Start the embedded app (if needed) and run a ReMe job.
+
+        Raises:
+            RuntimeError:
+                If ReMe reports ``success=False``.
+        """
+        await self._ensure_started()
+        assert self._app is not None
+        response = await self._app.run_job(name, **kwargs)
+        if getattr(response, "success", True) is False:
+            raise RuntimeError(
+                f"ReMe {name!r} failed: {getattr(response, 'answer', '')}",
+            )
+        return response
+
+    async def _search(
+        self,
+        query: str,
+        *,
+        limit: int | None = None,
+    ) -> list[str]:
+        """Search ReMe and return the retrieved memory texts."""
+        response = await self._run_job(
+            _SEARCH_JOB,
+            query=query,
+            limit=self._parameters.top_k if limit is None else limit,
+        )
+        return _extract_memory_texts(getattr(response, "metadata", {}))
+
+    async def _write_back(
+        self,
+        messages: list[Msg],
+        session_id: str | None,
+    ) -> None:
+        """Persist a completed conversation increment to ReMe.
+
+        ``messages`` is the full slice this turn appended to the agent's
+        context — the user input, every assistant step, and every tool
+        call / tool result — so ReMe's ``auto_memory`` extraction sees the
+        whole exchange, not just the final answer.
+
+        ``session_id`` is passed in per call (read live from the agent),
+        never stored, so a shared middleware keeps conversations isolated.
+        Skipped (with a warning) when no ``session_id`` is available;
+        failures are logged rather than propagated so a write never blocks
+        the reply.
+        """
+        if not session_id:
+            logger.warning(
+                "ReMe write skipped: no session_id captured from the agent.",
+            )
+            return
+        try:
+            await self._run_job(
+                _AUTO_MEMORY_JOB,
+                messages=[m.model_dump(mode="json") for m in messages],
+                session_id=session_id,
+            )
+        except Exception as e:  # noqa: BLE001
+            logger.warning(
+                "ReMe auto_memory failed for session_id=%s: %s",
+                session_id,
+                e,
+            )
+
+    # ==================================================================
+    # Helpers
+    # ==================================================================
+    @staticmethod
+    def _build_memory_message(memories: list[str]) -> Msg:
+        """Format retrieved ``memories`` as a synthetic hint message.
+
+        The context entry uses an assistant-role ``Msg`` container because
+        user messages cannot carry ``HintBlock`` content. Formatters convert
+        the ``HintBlock`` itself into a user message before the model call.
+
+        Args:
+            memories (`list[str]`):
+                Retrieved memory texts to expose to the model.
+        Returns:
+            `Msg`:
+                An assistant-role message containing one ``HintBlock``.
+        """
+        bullets = "\n".join(f"- {m}" for m in memories)
+        content = (
+            f"{_MEMORY_SECTION_HEADER}\n"
+            f"{_MEMORY_SECTION_INTRO}\n"
+            f"{bullets}"
+        )
+        return AssistantMsg(
+            name=_MEMORY_MSG_NAME,
+            content=[HintBlock(hint=content)],
+        )
diff --git a/src/agentscope/middleware/_longterm_memory/_reme/_tools.py b/src/agentscope/middleware/_longterm_memory/_reme/_tools.py
new file mode 100644
index 0000000..465af8b
--- /dev/null
+++ b/src/agentscope/middleware/_longterm_memory/_reme/_tools.py
@@ -0,0 +1,182 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Agent-control tool exposed by the ReMe middleware.
+
+The single ``memory_search`` tool is listed by :class:`ReMeMiddleware`
+when ``mode`` is ``"agent_control"`` or ``"both"``. The tool drives
+ReMe's ``search`` action through the embedded ReMe app held on the
+middleware.
+
+Unlike the mem0 middleware (which also exposes an ``add_memory`` tool),
+ReMe has **no manual add tool**: it records memory through its
+``auto_memory`` job — an LLM extraction over the *conversation* — which
+the middleware runs automatically on the reply path (write-back). So the
+agent-facing surface is search-only.
+"""
+from __future__ import annotations
+
+from typing import Any, TYPE_CHECKING
+
+from ....message import TextBlock, ToolResultState
+from ....permission import PermissionBehavior, PermissionDecision
+from ....tool import ToolBase, ToolChunk
+
+if TYPE_CHECKING:
+    from ._middleware import ReMeMiddleware
+
+
+class _ReMeMemoryToolBase(ToolBase):
+    """Base class for ReMe tools that auto-allow themselves.
+
+    Middleware-provided memory tools are part of the agent's standard
+    capabilities — prompting on every call would defeat the point.
+    """
+
+    is_external_tool: bool = False
+    is_state_injected: bool = False
+    is_mcp: bool = False
+    mcp_name: str | None = None
+
+    def __init__(
+        self,
+        mw: "ReMeMiddleware",
+    ) -> None:
+        """Bind the tool to its owning middleware.
+
+        Args:
+            mw (`ReMeMiddleware`):
+                The middleware whose embedded ReMe app and parameters this
+                tool drives.
+        """
+        self._mw = mw
+
+    async def check_permissions(
+        self,
+        *_args: Any,
+        **_kwargs: Any,
+    ) -> PermissionDecision:
+        """Auto-allow the call without prompting.
+
+        Middleware-provided memory tools are part of the agent's standard
+        capabilities, so they never require user confirmation.
+
+        Returns:
+            `PermissionDecision`:
+                An ``ALLOW`` decision.
+        """
+        return PermissionDecision(
+            behavior=PermissionBehavior.ALLOW,
+            message="auto-allowed: ReMe long-term memory tool",
+        )
+
+
+class _MemorySearchTool(_ReMeMemoryToolBase):
+    """Agent-callable ReMe search tool.
+
+    The advertised ``limit`` default is the middleware's ``top_k`` (set
+    per instance in :meth:`__init__`), so configuring ``top_k`` on the
+    middleware also governs how many memories this tool retrieves when the
+    agent omits ``limit``.
+    """
+
+    name: str = "memory_search"
+    description: str = (
+        "Retrieve memories from past conversations relevant to a query."
+    )
+    is_concurrency_safe: bool = True
+    is_read_only: bool = True
+
+    def __init__(
+        self,
+        mw: "ReMeMiddleware",
+    ) -> None:
+        """Bind the tool to ``mw`` and build its per-instance schema.
+
+        The advertised ``limit`` default is read from the middleware's
+        ``top_k`` here (rather than a hardcoded constant), so configuring
+        ``top_k`` on the middleware also governs the tool's default.
+
+        Args:
+            mw (`ReMeMiddleware`):
+                The middleware whose embedded ReMe app and ``top_k`` this
+                search tool uses.
+        """
+        super().__init__(mw)
+        # Per-instance schema so the default ``limit`` reflects this
+        # middleware's ``top_k`` rather than a hardcoded constant.
+        self.input_schema: dict[str, Any] = {
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "description": (
+                        "What to retrieve from memory — for example a "
+                        "person's name, a preference, or a past decision."
+                    ),
+                },
+                "limit": {
+                    "type": "integer",
+                    "description": "Maximum number of memories to retrieve.",
+                    "default": mw._parameters.top_k,
+                },
+            },
+            "required": ["query"],
+        }
+
+    async def __call__(
+        self,
+        query: str,
+        limit: int | None = None,
+    ) -> ToolChunk:
+        """Retrieve memory relevant to ``query``.
+
+        Args:
+            query (str):
+                What to retrieve from the ReMe workspace (for example a
+                person's name, a preference, or a past decision).
+            limit (int | None):
+                The maximum number of memories to retrieve. When omitted,
+                falls back to the middleware's ``top_k``.
+        """
+        if not query:
+            return _text_chunk("(no query supplied — nothing to search)")
+
+        try:
+            memories = await self._mw._search(query, limit=limit)
+        except Exception as e:  # noqa: BLE001
+            return _error_chunk(f"Error retrieving memory: {e}")
+
+        if not memories:
+            return _text_chunk("(no relevant memories found)")
+        return _text_chunk("\n".join(f"- {m}" for m in memories))
+
+
+def _build_memory_tools(
+    mw: "ReMeMiddleware",
+) -> list[ToolBase]:
+    """Return the ``memory_search`` tool bound to ``mw``.
+
+    ReMe's agent-facing surface is search-only — writing is handled
+    automatically by the middleware's ``auto_memory`` write-back, not a
+    manual tool.
+    """
+    return [
+        _MemorySearchTool(mw),
+    ]
+
+
+def _text_chunk(message: str) -> ToolChunk:
+    """Wrap a text message as a normal tool chunk."""
+    return ToolChunk(
+        content=[TextBlock(type="text", text=message)],
+    )
+
+
+def _error_chunk(message: str) -> ToolChunk:
+    """Wrap an error message as a ``ToolChunk(state=ERROR)`` so the
+    toolkit aggregates it as a failed tool call — the agent sees the
+    message and can decide whether to retry or move on."""
+    return ToolChunk(
+        content=[TextBlock(type="text", text=message)],
+        state=ToolResultState.ERROR,
+    )
diff --git a/src/agentscope/middleware/_longterm_memory/_reme/_utils.py b/src/agentscope/middleware/_longterm_memory/_reme/_utils.py
new file mode 100644
index 0000000..65f0c82
--- /dev/null
+++ b/src/agentscope/middleware/_longterm_memory/_reme/_utils.py
@@ -0,0 +1,104 @@
+# -*- coding: utf-8 -*-
+"""Pure helper functions for the ReMe middleware.
+
+These are stateless adapters that translate between AgentScope and ReMe
+data shapes. Keeping them out of the middleware class makes them trivial
+to unit-test in isolation.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from ....event import ExternalExecutionResultEvent, UserConfirmResultEvent
+from ....message import Msg
+
+
+def _extract_query_text(inputs: Any) -> str | None:
+    """Pull a single text query out of the agent inputs.
+
+    Returns ``None`` for resumption events or empty/non-user inputs,
+    in which case the middleware skips both retrieval and write-back.
+
+    Args:
+        inputs (`Any`):
+            The unified ``on_reply`` inputs — a ``Msg``, a list of
+            ``Msg``, a HITL resumption event, or ``None``.
+
+    Returns:
+        `str | None`:
+            The joined text of all user messages, or ``None`` when there
+            is nothing to search/write.
+    """
+    if inputs is None:
+        return None
+    if isinstance(
+        inputs,
+        (ExternalExecutionResultEvent, UserConfirmResultEvent),
+    ):
+        return None
+
+    msgs = inputs if isinstance(inputs, list) else [inputs]
+    texts: list[str] = []
+    for m in msgs:
+        if not isinstance(m, Msg) or m.role != "user":
+            continue
+        text = m.get_text_content()
+        if text:
+            texts.append(text)
+    return "\n".join(texts) if texts else None
+
+
+def _extract_memory_texts(raw: Any) -> list[str]:
+    """Flatten a ReMe ``search`` response into a list of memory strings.
+
+    ReMe's ``search`` returns a ``Response`` envelope whose
+    ``metadata["results"]`` is a list of file chunks. This helper
+    tolerates the common shapes:
+
+    - ``{"metadata": {"results": [{"text": str, "path": str, ...}, ...]}}``
+      (the standard ``search`` response)
+    - ``{"results": [{"text": str, ...}, ...]}`` (already-unwrapped)
+    - ``[{"text": str, ...}, ...]`` (plain list of chunks)
+    - ``[str, ...]`` / ``{"results": [str, ...]}`` (defensive fallback)
+
+    Each chunk's text is taken from ``text`` (ReMe's ``FileChunk.text``),
+    falling back to ``memory`` / ``content`` for forward compatibility.
+
+    Args:
+        raw (`Any`):
+            The raw object returned by ReMe's ``search`` job (e.g.
+            ``ReMe.run_job("search", ...)``) or the decoded ReMe response
+            envelope.
+
+    Returns:
+        `list[str]`:
+            Retrieved memory texts, in response order.
+    """
+    if raw is None:
+        return []
+
+    results: Any = raw
+    if isinstance(raw, dict):
+        # Unwrap one level of ``metadata`` if present, then ``results``.
+        if (
+            isinstance(raw.get("metadata"), dict)
+            and "results" in raw["metadata"]
+        ):
+            results = raw["metadata"]["results"]
+        else:
+            results = raw.get("results", raw)
+
+    if not isinstance(results, list):
+        return []
+
+    out: list[str] = []
+    for item in results:
+        if isinstance(item, str):
+            out.append(item)
+        elif isinstance(item, dict):
+            text = (
+                item.get("text") or item.get("memory") or item.get("content")
+            )
+            if text:
+                out.append(str(text))
+    return out
diff --git a/src/agentscope/middleware/_rag.py b/src/agentscope/middleware/_rag.py
new file mode 100644
index 0000000..735c481
--- /dev/null
+++ b/src/agentscope/middleware/_rag.py
@@ -0,0 +1,765 @@
+# -*- coding: utf-8 -*-
+"""RAG middleware that brings knowledge-base search into the agent loop.
+
+The :class:`RAGMiddleware` wraps one or more
+:class:`~agentscope.rag.KnowledgeBase` runtime handles — each carrying
+its own embedding model, vector store, and (optional) metadata filter —
+so a single agent can search across knowledge bases that were created
+with *different* embedding models.
+
+Two modes are supported, selected via :class:`SearchConfig.mode`:
+
+- ``"agentic"`` — exposes a single ``search_knowledge`` tool via
+  :meth:`RAGMiddleware.list_tools`.  The agent decides when (and which
+  knowledge bases) to query.  Nothing is injected automatically.
+- ``"static"`` — on the first reasoning step of each reply
+  (``agent.state.cur_iter == 0``) the middleware searches with the
+  fresh user turn as the query and injects the merged results into
+  ``agent.state.context`` as a :class:`~agentscope.message.HintBlock`.
+  Optionally surfaces a
+  :class:`~agentscope.event.HintBlockEvent` so the front-end can
+  display the matched snippets.
+
+User-tunable parameters are declared on :class:`SearchConfig`; the
+JSON Schema served to the front-end is derived from it via
+``model_json_schema()``.
+
+Document indexing (parsing, chunking, embedding, insertion) is *not*
+this middleware's job — it belongs to the caller (or, in the hosted
+service, to the knowledge-base manager) that constructs the
+:class:`KnowledgeBase` instances passed in.
+"""
+import asyncio
+import json
+from copy import deepcopy
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    AsyncGenerator,
+    Callable,
+    Literal,
+    Sequence,
+)
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+from pydantic.json_schema import SkipJsonSchema
+
+from ._base import MiddlewareBase
+from .._logging import logger
+from ..event import HintBlockEvent
+from ..message import (
+    DataBlock,
+    HintBlock,
+    Msg,
+    TextBlock,
+    ToolResultState,
+)
+from ..permission import PermissionBehavior, PermissionDecision
+from ..tool import ParamsBase, ToolBase, ToolChunk
+
+if TYPE_CHECKING:
+    from ..agent import Agent
+    from ..rag import KnowledgeBase, VectorSearchResult
+
+
+_DEFAULT_HINT_TEMPLATE = (
+    "<system-reminder>The following content is retrieved from the "
+    "knowledge base(s) and may be helpful for the current "
+    "request:\n<content>{context}</content></system-reminder>"
+)
+# Wrapper around the formatted search results.  Must contain a single
+# ``{context}`` placeholder — :func:`_wrap_hint` splits on it.
+
+_HINT_SOURCE = json.dumps({"label": "KnowledgeBase", "sublabel": ""})
+# The ``source`` value stamped on injected hint blocks.  Encoded as a
+# JSON string so the front-end can parse a structured label out of it
+# while the field stays a plain ``str`` everywhere else.
+
+
+class _SearchParams(ParamsBase):
+    """The parameters accepted by ``_SearchKnowledgeTool``."""
+
+    query: str = Field(
+        description=(
+            "The query string to search the knowledge base(s) with. "
+            "Must be concise, explicit, and self-contained: AVOID "
+            "ambiguous references like `he`/`she`/`it`, "
+            "`today`/`yesterday`/`tomorrow`, `here`/`there`, etc. — "
+            "the search is purely semantic and has no conversational "
+            "context. Phrase the query as a complete statement of "
+            "what you want to find."
+        ),
+    )
+
+    knowledge_bases: list[str] | None = Field(
+        default=None,
+        description=(
+            "Optional subset of knowledge bases to query, by name. "
+            "When omitted (or `null`) every equipped knowledge base "
+            "is searched. Names must exactly match those listed in "
+            "the tool description."
+        ),
+    )
+
+
+class _SearchKnowledgeTool(ToolBase):
+    """The agentic-mode search tool exposed by :class:`RAGMiddleware`.
+
+    A single tool fans out across every bound knowledge base; the
+    agent may also pass ``knowledge_bases`` to restrict the search to
+    a subset by name.
+    """
+
+    name: str = "search_knowledge"
+    """The tool name presented to the agent."""
+
+    is_read_only: bool = True
+    is_concurrency_safe: bool = True
+    is_external_tool: bool = False
+    is_state_injected: bool = False
+    is_mcp: bool = False
+
+    def __init__(
+        self,
+        knowledge_bases: list["KnowledgeBase"],
+        top_k: int,
+        score_threshold: float | None,
+    ) -> None:
+        """Initialize the search tool.
+
+        Args:
+            knowledge_bases (`list[KnowledgeBase]`):
+                The knowledge bases the agent may query.
+            top_k (`int`):
+                Maximum number of chunks returned per call, after
+                merging across knowledge bases.
+            score_threshold (`float | None`):
+                Minimum similarity score; forwarded unchanged to each
+                :meth:`KnowledgeBase.search` call.
+        """
+        # ``ToolBase`` expects a list of *tool* middlewares; this tool
+        # has none of its own (the owning ``RAGMiddleware`` is an
+        # *agent* middleware, not a tool one).
+        super().__init__()
+        self._knowledge_bases = knowledge_bases
+        self._top_k = top_k
+        self._score_threshold = score_threshold
+        self.description = self._build_description()
+        self.input_schema = self._build_input_schema()
+
+    def _build_description(self) -> str:
+        """Build the tool description from the currently equipped
+        knowledge bases so the agent has enough context to decide which
+        ones to query."""
+        lines = [
+            "Search the agent's equipped knowledge bases by semantic "
+            "similarity and return the most relevant chunks.",
+            "",
+            "## When to Use",
+            "- The user's question may be answered by content stored "
+            "in one of the listed knowledge bases (see *Equipped "
+            "Knowledge Bases* below).",
+            "- You need supporting facts, definitions, or documents "
+            "that are unlikely to be in your parametric knowledge.",
+            "",
+            "## Guidance",
+            "- Knowledge base names and descriptions are "
+            "user-supplied and may be terse, vague, or unrelated to "
+            "the actual contents. When in doubt, try the search — a "
+            "single call is cheap and an empty result is informative.",
+            "- Phrase `query` as a self-contained statement of what "
+            "you want to find. Avoid pronouns or relative time "
+            "references — the search is purely semantic and has no "
+            "conversational context.",
+            "- Set `knowledge_bases` only when the question clearly "
+            "matches one or two specific bases; otherwise leave it "
+            "unset to search them all.",
+            "",
+            "## Equipped Knowledge Bases",
+        ]
+        if self._knowledge_bases:
+            lines.append(
+                f"The agent is currently equipped with "
+                f"{len(self._knowledge_bases)} knowledge base(s):",
+            )
+            lines.extend(
+                f"- **{kb.name}**: {kb.description}"
+                for kb in self._knowledge_bases
+            )
+        else:
+            lines.append(
+                "No knowledge bases are currently equipped. **Do "
+                "not call this tool** — it will return nothing.",
+            )
+        return "\n".join(lines)
+
+    def _build_input_schema(self) -> dict:
+        """Build the JSON Schema, with ``knowledge_bases.items.enum``
+        narrowed to the currently equipped knowledge-base names so
+        the LLM cannot invent unknown names."""
+        schema: dict[str, Any] = _SearchParams.model_json_schema()
+        if self._knowledge_bases:
+            names = [kb.name for kb in self._knowledge_bases]
+            kb_schema = schema["properties"]["knowledge_bases"]
+            # Pydantic emits ``Optional[list[str]]`` as
+            # ``anyOf: [{type: array, items: ...}, {type: null}]``; we
+            # narrow the array branch's items.  Fall back to a direct
+            # ``items`` field for the non-optional shape.
+            if "items" in kb_schema:
+                kb_schema["items"]["enum"] = names
+            else:
+                for variant in kb_schema.get("anyOf", []):
+                    if variant.get("type") == "array" and "items" in variant:
+                        variant["items"]["enum"] = names
+                        break
+        return schema
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: Any,
+    ) -> Any:
+        """Allow the engine to handle this read-only search.
+
+        Args:
+            tool_input (`dict[str, Any]`):
+                The tool input data.
+            context (`PermissionContext`):
+                The permission context.
+
+        Returns:
+            `PermissionDecision`:
+                An allow decision — knowledge-base search is read-only.
+        """
+        del tool_input, context
+        return PermissionDecision(
+            behavior=PermissionBehavior.ALLOW,
+            message="Knowledge-base search is read-only.",
+        )
+
+    async def call(  # type: ignore[override]
+        self,
+        query: str,
+        knowledge_bases: list[str] | None = None,
+    ) -> ToolChunk:
+        """Search the selected knowledge bases and return the results
+        as content blocks.
+
+        Args:
+            query (`str`):
+                The natural-language search query.
+            knowledge_bases (`list[str] | None`, optional):
+                Optional subset of knowledge bases to query, by name.
+                ``None`` searches every equipped knowledge base.
+
+        Returns:
+            `ToolChunk`:
+                The formatted search results, or a notice when
+                nothing relevant is found.
+        """
+        if knowledge_bases is None:
+            targets = list(self._knowledge_bases)
+        else:
+            wanted = set(knowledge_bases)
+            targets = [kb for kb in self._knowledge_bases if kb.name in wanted]
+
+        if not targets:
+            return ToolChunk(
+                content=[TextBlock(text="No relevant content found.")],
+                state=ToolResultState.SUCCESS,
+                is_last=True,
+            )
+
+        try:
+            results = await _search_across(
+                targets,
+                [query],
+                top_k=self._top_k,
+                score_threshold=self._score_threshold,
+            )
+        except Exception as e:  # pylint: disable=broad-except
+            logger.exception("search_knowledge failed.")
+            return ToolChunk(
+                content=[TextBlock(text=f"Search failed: {e}")],
+                state=ToolResultState.ERROR,
+                is_last=True,
+            )
+
+        blocks = _format_results(results)
+        if not blocks:
+            return ToolChunk(
+                content=[TextBlock(text="No relevant content found.")],
+                state=ToolResultState.SUCCESS,
+                is_last=True,
+            )
+        return ToolChunk(
+            content=blocks,
+            state=ToolResultState.SUCCESS,
+            is_last=True,
+        )
+
+
+# ---------------------------------------------------------------------
+# Shared helpers — used by both the tool (agentic mode) and the
+# middleware's static-mode injection path.
+# ---------------------------------------------------------------------
+
+
+async def _search_across(
+    knowledge_bases: Sequence["KnowledgeBase"],
+    queries: Sequence[str | TextBlock | DataBlock],
+    top_k: int,
+    score_threshold: float | None,
+) -> list["VectorSearchResult"]:
+    """Search every knowledge base concurrently and merge the results.
+
+    Each knowledge base handles its own filtering — it silently drops
+    :class:`DataBlock` inputs when its embedding model is not
+    multimodal — so callers can pass the same query list to every
+    knowledge base without per-KB pre-filtering.  Per-KB hits are
+    flattened, sorted by descending score, and truncated to ``top_k``.
+
+    .. note::
+        Scores from knowledge bases with different embedding models
+        are not strictly comparable; this merge sorts by raw score.
+        For mixed-embedding deployments where that matters, switch to
+        a rank-based fusion (e.g. RRF) — each per-KB
+        :meth:`KnowledgeBase.search` already returns ordered results.
+
+    Args:
+        knowledge_bases (`list[KnowledgeBase]`):
+            The knowledge bases to query.
+        queries (`list[str | TextBlock | DataBlock]`):
+            The query inputs.
+        top_k (`int`):
+            Maximum number of results after merging.
+        score_threshold (`float | None`):
+            Forwarded to each :meth:`KnowledgeBase.search` call.
+
+    Returns:
+        `list[VectorSearchResult]`:
+            At most ``top_k`` hits across all knowledge bases.
+    """
+    if not queries or not knowledge_bases:
+        return []
+
+    queries_list = list(queries)
+    per_kb = await asyncio.gather(
+        *(
+            kb.search(
+                queries=queries_list,
+                top_k=top_k,
+                score_threshold=score_threshold,
+            )
+            for kb in knowledge_bases
+        ),
+    )
+
+    merged = [r for sub in per_kb for r in sub]
+    merged.sort(key=lambda r: r.score, reverse=True)
+    return merged[:top_k]
+
+
+def _format_results(
+    results: list["VectorSearchResult"],
+) -> list[TextBlock | DataBlock]:
+    """Render search results as a numbered, cited list of blocks.
+
+    Every result becomes ``[N] (source: ...)`` followed by its chunk
+    content (text inlined, multimodal blocks kept as standalone
+    :class:`DataBlock` entries).  Adjacent text fragments are merged
+    into a single :class:`TextBlock` so downstream consumers see one
+    contiguous text block instead of many small ones.
+
+    Args:
+        results (`list[VectorSearchResult]`):
+            The search results to format.
+
+    Returns:
+        `list[TextBlock | DataBlock]`:
+            The formatted blocks; empty list when ``results`` is
+            empty.
+    """
+    entries: list[TextBlock | DataBlock] = []
+    last = len(results)
+    for index, result in enumerate(results, start=1):
+        prefix = f"[{index}] (source: {result.chunk.source})\n"
+        block = deepcopy(result.chunk.content)
+        if isinstance(block, TextBlock):
+            block.text = prefix + block.text
+            entries.append(block)
+        else:
+            entries.append(TextBlock(text=prefix))
+            entries.append(block)
+        if index != last:
+            entries.append(TextBlock(text="\n\n"))
+
+    # Coalesce adjacent TextBlocks into one to keep the consumer-facing
+    # block list tight.  We build fresh TextBlocks rather than mutating
+    # the deep copied ones to avoid aliasing the originals.
+    merged: list[TextBlock | DataBlock] = []
+    for entry in entries:
+        if (
+            isinstance(entry, TextBlock)
+            and merged
+            and isinstance(merged[-1], TextBlock)
+        ):
+            merged[-1] = TextBlock(text=merged[-1].text + entry.text)
+        else:
+            merged.append(entry)
+    return merged
+
+
+def _wrap_hint(
+    template: str,
+    blocks: list[TextBlock | DataBlock],
+) -> str | list[TextBlock | DataBlock]:
+    """Substitute ``{context}`` in ``template`` with the rendered blocks.
+
+    When every block is a :class:`TextBlock` the result is a single
+    ``str`` (cheap, no block overhead).  When the blocks include
+    multimodal :class:`DataBlock` content the template is split on
+    ``{context}`` and the surrounding text is prepended / appended as
+    :class:`TextBlock` items, producing a ``list[TextBlock |
+    DataBlock]`` that preserves the binary payloads end-to-end.
+
+    Args:
+        template (`str`):
+            Wrapper template with a single ``{context}`` placeholder.
+        blocks (`list[TextBlock | DataBlock]`):
+            The formatted search blocks to wrap.
+
+    Returns:
+        `str | list[TextBlock | DataBlock]`:
+            A plain string for text-only payloads, or a list of blocks
+            when binary payloads are involved.
+    """
+    if all(isinstance(b, TextBlock) for b in blocks):
+        joined = "\n".join(b.text for b in blocks)  # type: ignore[union-attr]
+        return template.format(context=joined)
+
+    prefix, _, end = template.partition("{context}")
+    wrapped: list[TextBlock | DataBlock] = list(blocks)
+    if prefix:
+        if isinstance(wrapped[0], TextBlock):
+            wrapped[0] = TextBlock(text=prefix + wrapped[0].text)
+        else:
+            wrapped.insert(0, TextBlock(text=prefix))
+    if end:
+        if isinstance(wrapped[-1], TextBlock):
+            wrapped[-1] = TextBlock(text=wrapped[-1].text + end)
+        else:
+            wrapped.append(TextBlock(text=end))
+    return wrapped
+
+
+class RAGMiddleware(MiddlewareBase):
+    """Middleware that integrates knowledge-base search into the agent.
+
+    Constructed from a list of :class:`~agentscope.rag.KnowledgeBase`
+    handles — each carrying its own embedding model, vector store, and
+    metadata filter.  The middleware does not own these resources; it
+    only orchestrates search against them.
+
+    .. code-block:: python
+
+        # Automatic injection (static mode)
+        middleware = RAGMiddleware(
+            knowledge_bases=[kb1, kb2],
+            search_config=SearchConfig(mode="static"),
+        )
+
+        # Agent-driven search (agentic mode, the default)
+        middleware = RAGMiddleware(knowledge_bases=[kb1, kb2])
+
+        agent = Agent(..., middlewares=[middleware], ...)
+    """
+
+    class Parameters(BaseModel):
+        """User-tunable knowledge-base search parameters of
+        :class:`RAGMiddleware`.
+
+        The fields here are exactly the keys the hosted service persists
+        into ``SessionKnowledgeConfig.parameters`` and the keys
+        :class:`RAGMiddleware` accepts as ``search_config``.  Every field
+        is annotated with a ``title`` and ``description`` so the front-end
+        can render them as labels and tooltips via
+        ``model_json_schema()``.
+        """
+
+        model_config = ConfigDict(frozen=True)
+
+        mode: Literal["static", "agentic"] = Field(
+            default="agentic",
+            title="Mode",
+            description=(
+                "Retrieval is either agentic, letting the Agent decide when "
+                "to retrieve, or static, triggering on every user input."
+            ),
+        )
+
+        top_k: int = Field(
+            default=5,
+            ge=1,
+            le=50,
+            title="Top K",
+            description=(
+                "Maximum number of chunks returned per search, across all "
+                "configured knowledge bases."
+            ),
+        )
+
+        score_threshold: float | None = Field(
+            default=None,
+            title="Score Threshold",
+            description=(
+                "Minimum similarity score for a hit to be kept. Leave "
+                "empty to disable filtering."
+            ),
+        )
+
+        emit_hint_event: bool = Field(
+            default=True,
+            title="Show matched chunks in chat",
+            description=(
+                "Emit a `HintBlockEvent` in static mode so the front-end "
+                "can display the matched snippets to the user."
+            ),
+        )
+
+        persist_hint: bool = Field(
+            default=False,
+            title="Persist Hint",
+            description=(
+                "In `static` mode, keep the injected hint block in the "
+                "agent context instead of removing it right after the "
+                "model call."
+            ),
+        )
+
+        hint_template: SkipJsonSchema[str] = Field(
+            default=_DEFAULT_HINT_TEMPLATE,
+            title="Hint template",
+            description=(
+                "Template wrapping the formatted search results in static "
+                "mode, with a `{context}` placeholder."
+            ),
+        )
+
+        # ``hint_template`` is intentionally hidden from the JSON Schema
+        # exposed to the dock UI: the wrapper text is part of the
+        # middleware's prompt contract and exposing it through the dock
+        # invites session-by-session prompt drift.  It is still accepted
+        # for programmatic use.
+
+        @field_validator("hint_template")
+        @classmethod
+        def _validate_hint_template(cls, value: str) -> str:
+            """Reject templates with anything other than exactly one
+            ``{context}`` placeholder — :func:`_wrap_hint` substitutes on
+            the first occurrence, so zero placeholders silently drop the
+            matched content and multiple placeholders duplicate it."""
+            count = value.count("{context}")
+            if count != 1:
+                raise ValueError(
+                    "hint_template must contain exactly one '{context}' "
+                    f"placeholder; found {count}.",
+                )
+            return value
+
+    def __init__(
+        self,
+        knowledge_bases: list["KnowledgeBase"],
+        parameters: "RAGMiddleware.Parameters | None" = None,
+    ) -> None:
+        """Initialize the RAG middleware.
+
+        Args:
+            knowledge_bases (`list[KnowledgeBase]`):
+                The knowledge bases this agent searches.
+            parameters (`RAGMiddleware.Parameters | None`, optional):
+                Search-time knobs (mode, top_k, score threshold, hint
+                behaviour).  ``None`` uses the defaults of
+                :class:`SearchConfig`.
+        """
+        self._knowledge_bases = knowledge_bases
+        self._parameters = parameters or RAGMiddleware.Parameters()
+        # Static-mode reply scratchpad: populated by ``on_reply`` and
+        # consumed by ``on_reasoning`` so the auto-search can use the
+        # original reply inputs (which are no longer in
+        # ``agent.state.context`` by the time ``on_reasoning`` runs in
+        # a tool-call loop).  Cleared in ``on_reply``'s finally.
+        self._cached_inputs: list[TextBlock | DataBlock] | None = None
+
+    # ------------------------------------------------------------------
+    # Agentic mode — expose the search tool
+    # ------------------------------------------------------------------
+
+    async def list_tools(self) -> list[ToolBase]:
+        """Expose the search tool in ``"agentic"`` mode.
+
+        Returns:
+            `list[ToolBase]`:
+                A single ``search_knowledge`` tool in ``"agentic"``
+                mode; an empty list in ``"static"`` mode.
+        """
+        if self._parameters.mode == "agentic":
+            return [
+                _SearchKnowledgeTool(
+                    self._knowledge_bases,
+                    top_k=self._parameters.top_k,
+                    score_threshold=self._parameters.score_threshold,
+                ),
+            ]
+        return []
+
+    # ------------------------------------------------------------------
+    # Static mode — capture inputs in on_reply, search in on_reasoning
+    # ------------------------------------------------------------------
+
+    async def on_reply(
+        self,
+        agent: "Agent",
+        input_kwargs: dict,
+        next_handler: Callable[..., AsyncGenerator],
+    ) -> AsyncGenerator:
+        """Cache reply inputs for the static-mode search.
+
+        ``on_reasoning`` runs *after* the agent has potentially
+        consumed the inputs and started its own reply, so it cannot
+        recover them from ``agent.state.context`` reliably.  This
+        method captures them on entry and clears the cache when the
+        reply finishes.
+
+        Args:
+            agent (`Agent`):
+                The executing agent.  Unused, but part of the
+                middleware contract.
+            input_kwargs (`dict`):
+                Reply input kwargs (``inputs``, plus any extras);
+                forwarded unchanged.
+            next_handler (`Callable[..., AsyncGenerator]`):
+                The downstream middleware or core reply logic.
+
+        Yields:
+            `Any`:
+                Whatever ``next_handler`` yields.
+        """
+        inputs = input_kwargs.get("inputs")
+
+        msgs: list[Msg] | None = None
+        if isinstance(inputs, Msg):
+            msgs = [inputs]
+        elif isinstance(inputs, list) and all(
+            isinstance(m, Msg) for m in inputs
+        ):
+            msgs = inputs
+
+        if msgs:
+            # Deepcopy because we are about to mutate the first text block of
+            # each message to prepend the speaker name — never touch the
+            # caller's message objects.
+            msgs = deepcopy(msgs)
+            blocks: list[TextBlock | DataBlock] = []
+            for msg in msgs:
+                if not msg.content:
+                    continue
+                speaker = f"{msg.name}: "
+                if isinstance(msg.content[0], TextBlock):
+                    msg.content[0].text = speaker + msg.content[0].text
+                else:
+                    blocks.append(TextBlock(text=speaker))
+                blocks.extend(msg.content)
+
+            self._cached_inputs = blocks
+
+        try:
+            async for evt in next_handler(**input_kwargs):
+                yield evt
+        finally:
+            self._cached_inputs = None
+
+    async def on_reasoning(
+        self,
+        agent: "Agent",
+        input_kwargs: dict,
+        next_handler: Callable[..., AsyncGenerator],
+    ) -> AsyncGenerator:
+        """Inject a one-shot RAG hint on the first reasoning step.
+
+        Only active in ``"static"`` mode and only when
+        ``agent.state.cur_iter == 0`` — i.e. the first reasoning cycle
+        of a reply.  Subsequent reasoning iterations (tool-call
+        rounds) skip the search so the agent does not re-embed and
+        re-inject for every iteration.
+
+        When ``persist_hint`` is ``False`` (the default) the injected
+        block is removed from the context right after the reasoning
+        step it participated in — keyed on the block's id so other
+        middlewares can append their own blocks to the same carrier
+        message without interfering.
+
+        Args:
+            agent (`Agent`):
+                The executing agent whose ``state.context`` receives
+                the hint.
+            input_kwargs (`dict`):
+                Reasoning input kwargs; forwarded unchanged.
+            next_handler (`Callable[..., AsyncGenerator]`):
+                The downstream middleware or core reasoning logic.
+
+        Yields:
+            `Any`:
+                An optional :class:`HintBlockEvent` followed by events
+                from downstream.
+        """
+        hint: HintBlock | None = None
+
+        if (
+            self._parameters.mode == "static"
+            and agent.state.cur_iter == 0
+            and self._cached_inputs
+        ):
+            try:
+                results = await _search_across(
+                    self._knowledge_bases,
+                    self._cached_inputs,
+                    top_k=self._parameters.top_k,
+                    score_threshold=self._parameters.score_threshold,
+                )
+            except Exception:  # pylint: disable=broad-except
+                logger.exception(
+                    "Knowledge-base search failed; proceeding without "
+                    "matched context.",
+                )
+                results = []
+
+            blocks = _format_results(results)
+            if blocks:
+                hint = HintBlock(
+                    hint=_wrap_hint(self._parameters.hint_template, blocks),
+                    source=_HINT_SOURCE,
+                )
+                agent.state.append_context(agent.name, [hint])
+                if self._parameters.emit_hint_event:
+                    yield HintBlockEvent(
+                        reply_id=agent.state.reply_id,
+                        block_id=hint.id,
+                        source=hint.source,
+                        hint=hint.hint,
+                    )
+
+        try:
+            async for evt in next_handler(**input_kwargs):
+                yield evt
+        finally:
+            if hint is not None and not self._parameters.persist_hint:
+                # Remove the injected block from whichever message
+                # ``append_context`` placed it on.  Reverse-scan
+                # because that carrier is always the latest message
+                # with our ``reply_id``.
+                for msg in reversed(agent.state.context):
+                    if msg.id != agent.state.reply_id:
+                        continue
+                    msg.content = [b for b in msg.content if b.id != hint.id]
+                    break
diff --git a/src/agentscope/middleware/_tracing/__init__.py b/src/agentscope/middleware/_tracing/__init__.py
new file mode 100644
index 0000000..9fad1de
--- /dev/null
+++ b/src/agentscope/middleware/_tracing/__init__.py
@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+"""The tracing interface class in agentscope."""
+
+from ._trace import TracingMiddleware
+
+__all__ = [
+    "TracingMiddleware",
+]
diff --git a/src/agentscope/middleware/_tracing/_attributes.py b/src/agentscope/middleware/_tracing/_attributes.py
new file mode 100644
index 0000000..ed3d336
--- /dev/null
+++ b/src/agentscope/middleware/_tracing/_attributes.py
@@ -0,0 +1,201 @@
+# -*- coding: utf-8 -*-
+"""The tracing types class in agentscope."""
+from opentelemetry.semconv._incubating.attributes import (
+    gen_ai_attributes as GenAIAttributes,
+)
+
+
+class SpanAttributes:
+    """The span attributes."""
+
+    # GenAI Common Attributes
+    GEN_AI_CONVERSATION_ID = GenAIAttributes.GEN_AI_CONVERSATION_ID
+    """The gen ai conversation ID."""
+
+    GEN_AI_OPERATION_NAME = GenAIAttributes.GEN_AI_OPERATION_NAME
+    """The gen ai operation name."""
+
+    GEN_AI_PROVIDER_NAME = GenAIAttributes.GEN_AI_PROVIDER_NAME
+    """The gen ai provider name."""
+
+    # GenAI Request Attributes
+    GEN_AI_REQUEST_MODEL = GenAIAttributes.GEN_AI_REQUEST_MODEL
+    """The gen ai request model."""
+
+    GEN_AI_REQUEST_TEMPERATURE = GenAIAttributes.GEN_AI_REQUEST_TEMPERATURE
+    """The gen ai request temperature."""
+
+    GEN_AI_REQUEST_TOP_P = GenAIAttributes.GEN_AI_REQUEST_TOP_P
+    """The gen ai request top_p."""
+
+    GEN_AI_REQUEST_TOP_K = GenAIAttributes.GEN_AI_REQUEST_TOP_K
+    """The gen ai request top_k."""
+
+    GEN_AI_REQUEST_MAX_TOKENS = GenAIAttributes.GEN_AI_REQUEST_MAX_TOKENS
+    """The gen ai request max_tokens."""
+
+    GEN_AI_REQUEST_PRESENCE_PENALTY = (
+        GenAIAttributes.GEN_AI_REQUEST_PRESENCE_PENALTY
+    )
+    """The gen ai request presence_penalty."""
+
+    GEN_AI_REQUEST_FREQUENCY_PENALTY = (
+        GenAIAttributes.GEN_AI_REQUEST_FREQUENCY_PENALTY
+    )
+    """The gen ai request frequency_penalty."""
+
+    GEN_AI_REQUEST_STOP_SEQUENCES = (
+        GenAIAttributes.GEN_AI_REQUEST_STOP_SEQUENCES
+    )
+    """The gen ai request stop_sequences."""
+
+    GEN_AI_REQUEST_SEED = GenAIAttributes.GEN_AI_REQUEST_SEED
+    """The gen ai request seed."""
+
+    # GenAI Response Attributes
+    GEN_AI_RESPONSE_ID = GenAIAttributes.GEN_AI_RESPONSE_ID
+    """The gen ai response ID."""
+
+    GEN_AI_RESPONSE_FINISH_REASONS = (
+        GenAIAttributes.GEN_AI_RESPONSE_FINISH_REASONS
+    )
+    """The gen ai response finish reasons."""
+
+    # GenAI Usage Attributes
+    GEN_AI_USAGE_INPUT_TOKENS = GenAIAttributes.GEN_AI_USAGE_INPUT_TOKENS
+    """The gen ai usage input tokens."""
+
+    GEN_AI_USAGE_OUTPUT_TOKENS = GenAIAttributes.GEN_AI_USAGE_OUTPUT_TOKENS
+    """The gen ai usage output tokens."""
+
+    # GenAI Message Attributes
+    GEN_AI_INPUT_MESSAGES = GenAIAttributes.GEN_AI_INPUT_MESSAGES
+    """The gen ai input messages."""
+
+    GEN_AI_OUTPUT_MESSAGES = GenAIAttributes.GEN_AI_OUTPUT_MESSAGES
+    """The gen ai output messages."""
+
+    # GenAI Agent Attributes
+    GEN_AI_AGENT_ID = GenAIAttributes.GEN_AI_AGENT_ID
+    """The gen ai agent ID."""
+
+    GEN_AI_AGENT_NAME = GenAIAttributes.GEN_AI_AGENT_NAME
+    """The gen ai agent name."""
+
+    GEN_AI_AGENT_DESCRIPTION = GenAIAttributes.GEN_AI_AGENT_DESCRIPTION
+    """The gen ai agent description."""
+
+    # GenAI Tool Attributes
+    GEN_AI_TOOL_CALL_ID = GenAIAttributes.GEN_AI_TOOL_CALL_ID
+    """The gen ai tool call ID."""
+
+    GEN_AI_TOOL_NAME = GenAIAttributes.GEN_AI_TOOL_NAME
+    """The gen ai tool name."""
+
+    GEN_AI_TOOL_DESCRIPTION = GenAIAttributes.GEN_AI_TOOL_DESCRIPTION
+    """The gen ai tool description."""
+
+    GEN_AI_TOOL_CALL_ARGUMENTS = GenAIAttributes.GEN_AI_TOOL_CALL_ARGUMENTS
+    """The gen ai tool call arguments."""
+
+    GEN_AI_TOOL_CALL_RESULT = GenAIAttributes.GEN_AI_TOOL_CALL_RESULT
+    """The gen ai tool call result."""
+
+    GEN_AI_TOOL_DEFINITIONS = GenAIAttributes.GEN_AI_TOOL_DEFINITIONS
+    """The gen ai tool definitions."""
+
+    AGENTSCOPE_CACHE_INPUT_TOKENS = "agentscope.usage.cache_input_tokens"
+    """The number of input tokens read from prompt cache."""
+
+    AGENTSCOPE_CACHE_CREATION_INPUT_TOKENS = (
+        "agentscope.usage.cache_creation_input_tokens"
+    )
+    """The number of input tokens used to create prompt cache."""
+
+    AGENTSCOPE_REPLY_ID = "agentscope.agent.reply_id"
+    """The reply ID of the current agent reply.
+
+    Shared by both calls in a HITL or external-execution chain, allowing
+    observers to group the two ``invoke_agent`` spans that belong to the
+    same logical reply.
+    """
+
+    AGENTSCOPE_HITL_PENDING_TOOLS = "agentscope.agent.hitl_pending_tools"
+    """JSON list of tool names that are waiting for human confirmation.
+
+    Set on the first ``invoke_agent`` span when the agent pauses due to a
+    ``RequireUserConfirmEvent``.
+    """
+
+    AGENTSCOPE_EXTERNAL_EXECUTION_PENDING_TOOLS = (
+        "agentscope.agent.external_execution_pending_tools"
+    )
+    """JSON list of tool names submitted for external execution.
+
+    Set on the first ``invoke_agent`` span when the agent pauses due to a
+    ``RequireExternalExecutionEvent``.
+    """
+
+    AGENTSCOPE_INCOMING_EVENT_TYPE = "agentscope.agent.incoming_event_type"
+    """Type of the continuation event passed to the second reply call.
+
+    Possible values: ``"user_confirm_result"``,
+    ``"external_execution_result"``.
+    """
+
+    AGENTSCOPE_IS_EXTERNAL_EXECUTION = "agentscope.agent.is_external_execution"
+    """Marks a synthetic ``execute_tool`` span that represents a tool executed
+    externally (i.e. via ``ExternalExecutionResultEvent``).
+
+    The timestamp reflects when the result was received, not when the tool
+    actually ran on the external system.
+    """
+
+
+class OperationNameValues:
+    """The operation name values."""
+
+    CHAT = GenAIAttributes.GenAiOperationNameValues.CHAT.value
+    """The chat operation name."""
+
+    INVOKE_AGENT = GenAIAttributes.GenAiOperationNameValues.INVOKE_AGENT.value
+    """The invoke agent operation name."""
+
+    EXECUTE_TOOL = GenAIAttributes.GenAiOperationNameValues.EXECUTE_TOOL.value
+    """The execute tool operation name."""
+
+
+class ProviderNameValues:
+    """The provider name values."""
+
+    DASHSCOPE = "dashscope"
+    """The dashscope provider name."""
+
+    OLLAMA = "ollama"
+    """The ollama provider name."""
+
+    DEEPSEEK = GenAIAttributes.GenAiProviderNameValues.DEEPSEEK.value
+    """The deepseek provider name."""
+
+    OPENAI = GenAIAttributes.GenAiProviderNameValues.OPENAI.value
+    """The openai provider name."""
+
+    ANTHROPIC = GenAIAttributes.GenAiProviderNameValues.ANTHROPIC.value
+    """The anthropic provider name."""
+
+    GCP_GEMINI = GenAIAttributes.GenAiProviderNameValues.GCP_GEMINI.value
+    """The gcp gemini provider name."""
+
+    MOONSHOT = "moonshot"
+    """The moonshot provider name."""
+
+    AZURE_AI_OPENAI = (
+        GenAIAttributes.GenAiProviderNameValues.AZURE_AI_OPENAI.value
+    )
+    """The azure openai provider name."""
+
+    AWS_BEDROCK = GenAIAttributes.GenAiProviderNameValues.AWS_BEDROCK.value
+    """The aws bedrock provider name."""
+
+    XAI = GenAIAttributes.GenAiProviderNameValues.X_AI.value
+    """The xAI (Grok) provider name."""
diff --git a/src/agentscope/middleware/_tracing/_converter.py b/src/agentscope/middleware/_tracing/_converter.py
new file mode 100644
index 0000000..f69cf7e
--- /dev/null
+++ b/src/agentscope/middleware/_tracing/_converter.py
@@ -0,0 +1,121 @@
+# -*- coding: utf-8 -*-
+"""Convert ContentBlock to OpenTelemetry GenAI part format."""
+
+import json
+from typing import Any, Dict
+
+from ...message import (
+    ContentBlock,
+    TextBlock,
+    ThinkingBlock,
+    ToolCallBlock,
+    ToolResultBlock,
+    DataBlock,
+    Base64Source,
+    URLSource,
+)
+
+from ._utils import _serialize_to_str
+
+# Valid OTel GenAI modality values for multimodal content parts.
+_VALID_MODALITIES = frozenset({"image", "audio", "video"})
+
+
+def _get_modality(media_type: str) -> str:
+    """Derive OTel modality from a MIME type string (e.g. 'image/png')."""
+    prefix = media_type.split("/")[0] if media_type else ""
+    return prefix if prefix in _VALID_MODALITIES else "unknown"
+
+
+def _convert_media_block(
+    source: Base64Source | URLSource,
+) -> Dict[str, Any] | None:
+    """Convert a DataBlock source to OpenTelemetry GenAI part format.
+
+    Args:
+        source (`Base64Source | URLSource`):
+            The data source of the DataBlock.
+
+    Returns:
+        `Dict[str, Any] | None`:
+            Converted part Dictionary or None if the source type is invalid.
+    """
+    modality = _get_modality(source.media_type)
+
+    if isinstance(source, URLSource):
+        return {
+            "type": "uri",
+            "uri": str(source.url),
+            "modality": modality,
+        }
+
+    if isinstance(source, Base64Source):
+        return {
+            "type": "blob",
+            "content": source.data,
+            "media_type": source.media_type,
+            "modality": modality,
+        }
+
+    return None
+
+
+def _convert_block_to_part(block: ContentBlock) -> Dict[str, Any] | None:
+    """Convert content block to OpenTelemetry GenAI part format.
+
+    Converts text, thinking, tool_call, tool_result and data (media) blocks
+    to standardized parts.
+
+    Args:
+        block (`ContentBlock`):
+            The content block object to convert. Supported block types:
+            - text: Text content block
+            - thinking: Reasoning/thinking content block
+            - tool_call: Tool call block with id, name, and input
+            - tool_result: Tool result block with id and output
+            - data: Binary data block (image, audio, video, etc.)
+
+    Returns:
+        `Dict[str, Any] | None`:
+            Standardized part Dictionary in OpenTelemetry GenAI format,
+            or None if the block type is unsupported or cannot be converted.
+    """
+    part: Dict[str, Any] | None = None
+
+    if isinstance(block, TextBlock):
+        part = {
+            "type": "text",
+            "content": block.text,
+        }
+    elif isinstance(block, ThinkingBlock):
+        part = {
+            "type": "reasoning",
+            "content": block.thinking,
+        }
+    elif isinstance(block, ToolCallBlock):
+        try:
+            arguments = json.loads(block.input)
+        except (json.JSONDecodeError, TypeError):
+            arguments = block.input
+        part = {
+            "type": "tool_call",
+            "id": block.id,
+            "name": block.name,
+            "arguments": arguments,
+        }
+    elif isinstance(block, ToolResultBlock):
+        output = block.output
+        if isinstance(output, (list, dict)):
+            result = _serialize_to_str(output)
+        else:
+            result = str(output)
+
+        part = {
+            "type": "tool_call_response",
+            "id": block.id,
+            "response": result,
+        }
+    elif isinstance(block, DataBlock):
+        part = _convert_media_block(block.source)
+
+    return part
diff --git a/src/agentscope/middleware/_tracing/_extractor.py b/src/agentscope/middleware/_tracing/_extractor.py
new file mode 100644
index 0000000..788253c
--- /dev/null
+++ b/src/agentscope/middleware/_tracing/_extractor.py
@@ -0,0 +1,608 @@
+# -*- coding: utf-8 -*-
+"""Extract attributes from AgentScope components for OpenTelemetry tracing."""
+import inspect
+from typing import Any, Dict, TYPE_CHECKING
+
+from ...message import Msg, ToolCallBlock
+
+from ._attributes import (
+    SpanAttributes,
+    OperationNameValues,
+    ProviderNameValues,
+)
+from ._converter import _convert_block_to_part
+from ._utils import _serialize_to_str
+from ...model import ChatResponse, ChatModelBase
+from ...event import (
+    ExternalExecutionResultEvent,
+    UserConfirmResultEvent,
+)
+
+if TYPE_CHECKING:
+    from ...agent import Agent
+    from ...tool import Toolkit, ToolChoice
+
+_CLASS_NAME_MAP = {
+    "dashscope": ProviderNameValues.DASHSCOPE,
+    "openai": ProviderNameValues.OPENAI,
+    "anthropic": ProviderNameValues.ANTHROPIC,
+    "gemini": ProviderNameValues.GCP_GEMINI,
+    "ollama": ProviderNameValues.OLLAMA,
+    "deepseek": ProviderNameValues.DEEPSEEK,
+    "xai": ProviderNameValues.XAI,
+    "moonshot": ProviderNameValues.MOONSHOT,
+}
+
+# Map base URL fragments to provider names for OpenAI-compatible APIs
+_BASE_URL_PROVIDER_MAP = [
+    ("api.openai.com", ProviderNameValues.OPENAI),
+    ("dashscope", ProviderNameValues.DASHSCOPE),
+    ("deepseek", ProviderNameValues.DEEPSEEK),
+    ("moonshot", ProviderNameValues.MOONSHOT),
+    ("generativelanguage.googleapis.com", ProviderNameValues.GCP_GEMINI),
+    ("openai.azure.com", ProviderNameValues.AZURE_AI_OPENAI),
+    ("amazonaws.com", ProviderNameValues.AWS_BEDROCK),
+    ("api.x.ai", ProviderNameValues.XAI),
+]
+
+
+def _get_common_attributes(session_id: str = "") -> Dict[str, str]:
+    """Get common attributes for all spans.
+
+    Args:
+        session_id (`str`):
+            The session ID to set as conversation ID.
+
+    Returns:
+        `Dict[str, str]`:
+            Common span attributes including conversation ID.
+    """
+    return {
+        SpanAttributes.GEN_AI_CONVERSATION_ID: (
+            session_id if session_id else "[no_session_id]"
+        ),
+    }
+
+
+def _get_provider_name(instance: "ChatModelBase") -> str:
+    """Get provider name from ChatModelBase instance.
+
+    Maps ChatModelBase class names to provider names, with special handling
+    for OpenAI-compatible APIs that may use different base URLs.
+    This follows the implementation pattern from agentscope-java PR #73.
+
+    Args:
+        instance (`ChatModelBase`):
+            The chat model instance to get the provider name for.
+
+    Returns:
+        `str`:
+            Provider name (e.g., "openai", "dashscope", "anthropic")
+    """
+    classname = instance.__class__.__name__
+
+    # For other model types, use direct mapping
+    prefix_key = (
+        classname.removesuffix("ChatModel")
+        .removesuffix("MultiAgentModel")
+        .removesuffix("ResponseModel")
+        .lower()
+    )
+
+    # Special handling for OpenAI-compatible models — inspect base_url
+    # from credential to distinguish the actual provider.
+    if prefix_key == "openai":
+        base_url = getattr(instance.credential, "base_url", None)
+        if base_url:
+            base_url = str(base_url)
+            for url_fragment, provider_name in _BASE_URL_PROVIDER_MAP:
+                if url_fragment in base_url:
+                    return provider_name
+        return ProviderNameValues.OPENAI
+
+    return _CLASS_NAME_MAP.get(prefix_key, "unknown")
+
+
+def _get_tool_definitions(
+    tools: list[dict[str, Any]] | None,
+    tool_choice: "ToolChoice | None",
+) -> str | None:
+    """Extract and serialize tool definitions for tracing.
+
+    Converts AgentScope/OpenAI nested tool format to OpenTelemetry GenAI
+    flat format for tracing.
+
+    Args:
+        tools (`list[dict[str, Any]] | None`, optional):
+            List of tool definitions in OpenAI format with nested
+            structure: ``[{"type": "function", "function": {...}}]``
+        tool_choice (`ToolChoice | None`, optional):
+            Tool choice configuration with ``mode`` and optional ``tools``
+            fields. If mode is ``"none"``, returns None to indicate tools
+            should not be traced.
+
+    Returns:
+        `str | None`:
+            Serialized tool definitions in flat format:
+            ``[{"type": "function", "name": ..., "parameters": ...}]``
+            or None if tools should not be traced (e.g., tools is None/empty
+            or tool_choice is "none").
+    """
+    # No tools provided
+    if tools is None or not isinstance(tools, list) or len(tools) == 0:
+        return None
+
+    # Tool choice is explicitly "none" (model should not use tools)
+    if tool_choice is not None and tool_choice.mode == "none":
+        return None
+
+    try:
+        # Convert nested format to flat format for OpenTelemetry GenAI
+        # TODO: Currently only supports "function" type tools. If other tool
+        # types are added in the future (e.g., "retrieval", "code_interpreter",
+        # "browser"), this conversion logic needs to be updated to handle them.
+        flat_tools = []
+        for tool in tools:
+            if not isinstance(tool, dict) or "function" not in tool:
+                continue
+
+            func_def = tool["function"]
+            flat_tool = {
+                "type": tool.get("type", "function"),
+                "name": func_def.get("name"),
+                "description": func_def.get("description"),
+                "parameters": func_def.get("parameters"),
+            }
+            # Remove None values
+            flat_tool = {k: v for k, v in flat_tool.items() if v is not None}
+            flat_tools.append(flat_tool)
+
+        if flat_tools:
+            return _serialize_to_str(flat_tools)
+        return None
+
+    except Exception:
+        return None
+
+
+def _get_llm_request_attributes(
+    instance: "ChatModelBase",
+    kwargs: Dict[str, Any],
+) -> Dict[str, Any]:
+    """Get LLM request attributes for OpenTelemetry tracing.
+
+    Extracts request parameters from LLM model calls into GenAI attributes.
+
+    Args:
+        instance (`ChatModelBase`):
+            The chat model instance making the request.
+        kwargs (`Dict[str, Any]`):
+            Keyword arguments including generation parameters such as
+            temperature, top_p, top_k, max_tokens, presence_penalty,
+            frequency_penalty, stop_sequences, seed, tools, and tool_choice.
+
+    Returns:
+        `Dict[str, Any]`:
+            OpenTelemetry GenAI attributes with mixed-type values (``str``,
+            ``int``, ``float``, or ``list``), including operation name,
+            provider name, model name, generation parameters (e.g.
+            temperature, max_tokens, stop_sequences), and tool definitions.
+    """
+
+    attributes = {
+        # required attributes
+        SpanAttributes.GEN_AI_OPERATION_NAME: OperationNameValues.CHAT,
+        SpanAttributes.GEN_AI_PROVIDER_NAME: _get_provider_name(instance),
+        # conditionally required attributes
+        SpanAttributes.GEN_AI_REQUEST_MODEL: instance.model,
+        # recommended attributes
+        SpanAttributes.GEN_AI_REQUEST_TEMPERATURE: kwargs.get("temperature"),
+        SpanAttributes.GEN_AI_REQUEST_TOP_P: kwargs.get("p")
+        or kwargs.get("top_p"),
+        SpanAttributes.GEN_AI_REQUEST_TOP_K: kwargs.get("top_k"),
+        SpanAttributes.GEN_AI_REQUEST_MAX_TOKENS: kwargs.get("max_tokens"),
+        SpanAttributes.GEN_AI_REQUEST_PRESENCE_PENALTY: kwargs.get(
+            "presence_penalty",
+        ),
+        SpanAttributes.GEN_AI_REQUEST_FREQUENCY_PENALTY: kwargs.get(
+            "frequency_penalty",
+        ),
+        SpanAttributes.GEN_AI_REQUEST_STOP_SEQUENCES: kwargs.get(
+            "stop_sequences",
+        ),
+        SpanAttributes.GEN_AI_REQUEST_SEED: kwargs.get("seed"),
+    }
+
+    # Extract tool definitions if provided
+    tool_definitions = _get_tool_definitions(
+        tools=kwargs.get("tools"),
+        tool_choice=kwargs.get("tool_choice"),
+    )
+    if tool_definitions:
+        attributes[SpanAttributes.GEN_AI_TOOL_DEFINITIONS] = tool_definitions
+
+    return {k: v for k, v in attributes.items() if v is not None}
+
+
+def _get_llm_span_name(attributes: Dict[str, str]) -> str:
+    """Generate span name for LLM operations.
+
+    Args:
+        attributes (`Dict[str, str]`):
+            LLM request attributes dictionary containing operation name and
+            model name.
+
+    Returns:
+        `str`:
+            Formatted span name in the format "{operation} {model}",
+            e.g., "chat gpt-4" or "chat qwen-plus".
+    """
+    return (
+        f"{attributes[SpanAttributes.GEN_AI_OPERATION_NAME]} "
+        f"{attributes[SpanAttributes.GEN_AI_REQUEST_MODEL]}"
+    )
+
+
+def _get_llm_output_messages(
+    chat_response: ChatResponse | None,
+) -> list[dict[str, Any]]:
+    """Extract and format LLM output messages for tracing.
+
+    Converts ChatResponse objects to standardized message format compatible
+    with OpenTelemetry GenAI specification.
+
+    Args:
+        chat_response (` ChatResponse | None`):
+            Chat response object with content blocks. Should be a ChatResponse
+            instance containing content blocks (text, tool_use, etc.).
+
+    Returns:
+        `list[dict[str, Any]]`:
+            List containing a single formatted message dictionary with role,
+            parts, and finish_reason. Returns the original response if it's
+            not a ChatResponse instance, or an error message format if
+            conversion fails.
+    """
+    try:
+        if not isinstance(chat_response, ChatResponse):
+            return [
+                {
+                    "role": "assistant",
+                    "parts": [
+                        {
+                            "type": "text",
+                            "content": str(chat_response),
+                        },
+                    ],
+                    "finish_reason": "unknown",
+                },
+            ]
+
+        parts = []
+        finish_reason = "stop"  # Default finish reason
+
+        for block in chat_response.content:
+            part = _convert_block_to_part(block)
+            if part:
+                parts.append(part)
+
+        output_message = {
+            "role": "assistant",
+            "parts": parts,
+            "finish_reason": finish_reason,
+        }
+
+        return [output_message]
+
+    except Exception:
+        return [
+            {
+                "role": "assistant",
+                "parts": [
+                    {
+                        "type": "text",
+                        "content": "<error processing response>",
+                    },
+                ],
+                "finish_reason": "error",
+            },
+        ]
+
+
+def _get_llm_response_attributes(
+    chat_response: ChatResponse | None,
+) -> Dict[str, Any]:
+    """Get LLM response attributes for OpenTelemetry tracing.
+
+    Extracts response metadata and formats into GenAI attributes.
+
+    Args:
+        chat_response (`ChatResponse | None`):
+            Chat response object with data and usage info. Should have
+            attributes like id, usage (with input_tokens and output_tokens),
+            and content blocks.
+
+    Returns:
+        `Dict[str, Any]`:
+            OpenTelemetry GenAI response attributes including response ID,
+            finish reasons, token usage (input/output tokens), and output
+            messages.
+    """
+    attributes = {
+        SpanAttributes.GEN_AI_RESPONSE_ID: getattr(
+            chat_response,
+            "id",
+            "unknown_id",
+        ),
+        # FIXME: finish reason should be capture in chat response
+        SpanAttributes.GEN_AI_RESPONSE_FINISH_REASONS: '["stop"]',
+    }
+    if hasattr(chat_response, "usage") and chat_response.usage:
+        usage = chat_response.usage
+        attributes[
+            SpanAttributes.GEN_AI_USAGE_INPUT_TOKENS
+        ] = usage.input_tokens
+        attributes[
+            SpanAttributes.GEN_AI_USAGE_OUTPUT_TOKENS
+        ] = usage.output_tokens
+
+        cache_input = usage.cache_input_tokens
+        if cache_input:
+            attributes[
+                SpanAttributes.AGENTSCOPE_CACHE_INPUT_TOKENS
+            ] = cache_input
+
+        cache_creation = usage.cache_creation_input_tokens
+        if cache_creation:
+            attributes[
+                SpanAttributes.AGENTSCOPE_CACHE_CREATION_INPUT_TOKENS
+            ] = cache_creation
+
+    output_messages = _get_llm_output_messages(chat_response)
+    if output_messages:
+        attributes[SpanAttributes.GEN_AI_OUTPUT_MESSAGES] = _serialize_to_str(
+            output_messages,
+        )
+
+    return attributes
+
+
+def _get_agent_messages(
+    msg: Msg | list[Msg],
+) -> list[dict[str, Any]]:
+    """Convert AgentScope message(s) to standardized parts format.
+
+    Transforms Msg objects into OpenTelemetry GenAI format.
+
+    Args:
+        msg (`Msg | list[Msg]`):
+            AgentScope message object or list of message objects with
+            content blocks.
+
+    Returns:
+        `list[dict[str, Any]]`:
+            List of formatted message dictionaries with role, parts, name,
+            and finish_reason.
+    """
+    try:
+        if isinstance(msg, Msg):
+            msg = [msg]
+
+        formatted_msgs = []
+        for m in msg:
+            parts = []
+            for block in m.get_content_blocks():
+                part = _convert_block_to_part(block)
+                if part:
+                    parts.append(part)
+            formatted_msg = {
+                "role": m.role,
+                "parts": parts,
+                "name": m.name,
+                "finish_reason": "stop",
+            }
+            formatted_msgs.append(formatted_msg)
+
+        return formatted_msgs
+    except Exception:
+        # Fallback: try simple attribute access on the original object.
+        # If msg was already converted to a list or lacks role/name, return
+        # an empty list rather than raising a secondary exception.
+        try:
+            single = msg[0] if isinstance(msg, list) else msg
+            return [
+                {
+                    "role": single.role,
+                    "parts": [
+                        {
+                            "type": "text",
+                            "content": (
+                                str(single.content) if single.content else ""
+                            ),
+                        },
+                    ],
+                    "name": single.name,
+                    "finish_reason": "stop",
+                },
+            ]
+        except Exception:
+            return []
+
+
+def _get_agent_request_attributes(
+    instance: "Agent",
+    kwargs: Dict[str, Any],
+) -> Dict[str, str]:
+    """Get agent request attributes for OpenTelemetry tracing.
+
+    Extracts agent metadata and input data into GenAI attributes.
+
+    Args:
+        instance (`Agent`):
+            The agent instance making the request.
+        kwargs (`Dict[str, Any]`):
+            Keyword arguments passed to the agent's reply method.
+
+    Returns:
+        `Dict[str, str]`:
+            OpenTelemetry GenAI attributes including operation name, agent ID,
+            agent name, agent description, and input messages (if provided).
+    """
+    attributes = {
+        SpanAttributes.GEN_AI_OPERATION_NAME: (
+            OperationNameValues.INVOKE_AGENT
+        ),
+        SpanAttributes.GEN_AI_AGENT_NAME: instance.name,
+        SpanAttributes.GEN_AI_AGENT_DESCRIPTION: inspect.getdoc(
+            instance.__class__,
+        )
+        or "No description available",
+    }
+
+    inputs = kwargs.get("inputs")
+    if inputs is not None:
+        if isinstance(inputs, (Msg, list)):
+            input_messages = _get_agent_messages(inputs)
+            attributes[
+                SpanAttributes.GEN_AI_INPUT_MESSAGES
+            ] = _serialize_to_str(input_messages)
+        elif isinstance(inputs, UserConfirmResultEvent):
+            attributes[
+                SpanAttributes.AGENTSCOPE_INCOMING_EVENT_TYPE
+            ] = "user_confirm_result"
+        elif isinstance(inputs, ExternalExecutionResultEvent):
+            attributes[
+                SpanAttributes.AGENTSCOPE_INCOMING_EVENT_TYPE
+            ] = "external_execution_result"
+
+    return attributes
+
+
+def _get_agent_span_name(attributes: Dict[str, str]) -> str:
+    """Generate span name for agent operations.
+
+    Args:
+        attributes (`Dict[str, str]`):
+            Agent request attributes dictionary containing operation name and
+            agent name.
+
+    Returns:
+        `str`:
+            Formatted span name in the format "{operation} {agent_name}",
+            e.g., "invoke_agent MyAgent".
+    """
+    return (
+        f"{attributes[SpanAttributes.GEN_AI_OPERATION_NAME]} "
+        f"{attributes[SpanAttributes.GEN_AI_AGENT_NAME]}"
+    )
+
+
+def _get_agent_response_attributes(
+    agent_response: Msg,
+) -> Dict[str, str]:
+    """Get agent response attributes for OpenTelemetry tracing.
+
+    Args:
+        agent_response (`Msg`):
+            Response message returned by agent, containing content blocks.
+
+    Returns:
+        `Dict[str, str]`:
+            OpenTelemetry GenAI response attributes including output messages.
+    """
+    attributes = {
+        SpanAttributes.GEN_AI_OUTPUT_MESSAGES: _serialize_to_str(
+            _get_agent_messages(agent_response),
+        ),
+    }
+    return attributes
+
+
+def _get_tool_request_attributes(
+    instance: "Toolkit",
+    tool_call: ToolCallBlock,
+) -> Dict[str, str]:
+    """Get tool request attributes for OpenTelemetry tracing.
+
+    Extracts tool execution metadata into GenAI attributes.
+
+    Args:
+        instance (`Toolkit`):
+            Toolkit instance with tool definitions. Used to extract tool
+            description from the tool's JSON schema.
+        tool_call (`ToolCallBlock`):
+            Tool use block with call information including id, name, and input
+            arguments.
+
+    Returns:
+        `Dict[str, str]`:
+            OpenTelemetry GenAI tool attributes including operation name, tool
+            call ID, tool name, tool description (if available), and tool call
+            arguments.
+    """
+    attributes = {
+        SpanAttributes.GEN_AI_OPERATION_NAME: (
+            OperationNameValues.EXECUTE_TOOL
+        ),
+    }
+
+    if tool_call:
+        tool_name = tool_call.name
+        attributes[SpanAttributes.GEN_AI_TOOL_CALL_ID] = tool_call.id
+        attributes[SpanAttributes.GEN_AI_TOOL_NAME] = tool_name
+        # tool_call.input is already a JSON string; pass it directly to avoid
+        # double-encoding (e.g. '{"city": "Beijing"}' → '"{\\"city\\"...}"')
+        attributes[SpanAttributes.GEN_AI_TOOL_CALL_ARGUMENTS] = tool_call.input
+
+        if tool_name:
+            registered = getattr(instance, "tools", {}).get(tool_name)
+            if registered is not None:
+                tool_obj = getattr(registered, "tool", None)
+                description = getattr(tool_obj, "description", None)
+                if description:
+                    attributes[
+                        SpanAttributes.GEN_AI_TOOL_DESCRIPTION
+                    ] = description
+
+    return attributes
+
+
+def _get_tool_span_name(attributes: Dict[str, str]) -> str:
+    """Generate span name for tool operations.
+
+    Args:
+        attributes (`Dict[str, str]`):
+            Tool request attributes dictionary containing operation name and
+            tool name.
+
+    Returns:
+        `str`:
+            Formatted span name in the format "{operation} {tool_name}",
+            e.g., "execute_tool search".
+    """
+    return (
+        f"{attributes[SpanAttributes.GEN_AI_OPERATION_NAME]} "
+        f"{attributes[SpanAttributes.GEN_AI_TOOL_NAME]}"
+    )
+
+
+def _get_tool_response_attributes(
+    tool_response: Any,
+) -> Dict[str, str]:
+    """Get tool response attributes for OpenTelemetry tracing.
+
+    Args:
+        tool_response (`Any`):
+            Response object from tool execution. Can be any serializable object
+            returned by the tool function.
+
+    Returns:
+        `Dict[str, str]`:
+            OpenTelemetry GenAI response attributes including tool call result.
+    """
+    attributes = {
+        SpanAttributes.GEN_AI_TOOL_CALL_RESULT: _serialize_to_str(
+            tool_response,
+        ),
+    }
+    return attributes
diff --git a/src/agentscope/middleware/_tracing/_setup.py b/src/agentscope/middleware/_tracing/_setup.py
new file mode 100644
index 0000000..5aaedd5
--- /dev/null
+++ b/src/agentscope/middleware/_tracing/_setup.py
@@ -0,0 +1,19 @@
+# -*- coding: utf-8 -*-
+"""The tracing interface class in agentscope."""
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from opentelemetry.trace import Tracer
+else:
+    Tracer = "Tracer"
+
+
+def _get_tracer() -> Tracer:
+    """Get the tracer
+    Returns:
+        `Tracer`: The tracer with the name "agentscope" and version.
+    """
+    from opentelemetry import trace
+    from ..._version import __version__
+
+    return trace.get_tracer("agentscope", __version__)
diff --git a/src/agentscope/middleware/_tracing/_trace.py b/src/agentscope/middleware/_tracing/_trace.py
new file mode 100644
index 0000000..d8c3fb3
--- /dev/null
+++ b/src/agentscope/middleware/_tracing/_trace.py
@@ -0,0 +1,348 @@
+# -*- coding: utf-8 -*-
+"""TracingMiddleware and supporting utilities for OpenTelemetry tracing."""
+import json
+from typing import (
+    Any,
+    AsyncGenerator,
+    Callable,
+    Awaitable,
+    Union,
+    TypeVar,
+    TYPE_CHECKING,
+)
+
+import aioitertools
+
+from opentelemetry import trace as otel_trace
+from opentelemetry.trace import StatusCode
+
+from .._base import MiddlewareBase
+from ...event import (
+    ExternalExecutionResultEvent,
+    RequireExternalExecutionEvent,
+    RequireUserConfirmEvent,
+    ReplyStartEvent,
+)
+from ...message import Msg, ToolCallBlock
+from ...model import ChatModelBase
+
+from ._attributes import SpanAttributes, OperationNameValues
+from ._extractor import (
+    _get_common_attributes,
+    _get_agent_request_attributes,
+    _get_agent_span_name,
+    _get_agent_response_attributes,
+    _get_llm_request_attributes,
+    _get_llm_span_name,
+    _get_llm_response_attributes,
+    _get_tool_request_attributes,
+    _get_tool_span_name,
+    _get_tool_response_attributes,
+)
+from ._setup import _get_tracer
+from ._utils import _serialize_to_str
+
+if TYPE_CHECKING:
+    from opentelemetry.trace import Span
+    from ...agent import Agent
+    from ...model import ChatResponse
+
+T = TypeVar("T")
+
+
+# ---------------------------------------------------------------------------
+# Utility helpers
+# ---------------------------------------------------------------------------
+
+
+def _check_tracing_enabled() -> bool:
+    """Check if the OpenTelemetry tracer is initialised with a real SDK
+    TracerProvider (i.e. ``setup_tracing`` was called).  Returns ``False``
+    when only the default no-op proxy provider is active or when the SDK
+    package is not installed.
+    """
+    try:
+        from opentelemetry.sdk.trace import TracerProvider
+    except ImportError:
+        return False
+
+    return isinstance(otel_trace.get_tracer_provider(), TracerProvider)
+
+
+def _set_span_success_status(span: "Span") -> None:
+    """Set the span status to OK and end it."""
+    span.set_status(StatusCode.OK)
+    span.end()
+
+
+def _set_span_error_status(span: "Span", e: BaseException) -> None:
+    """Set the span status to ERROR, record the exception and end it."""
+    span.set_status(StatusCode.ERROR, str(e))
+    span.record_exception(e)
+    span.end()
+
+
+async def _trace_async_generator_wrapper(
+    res: AsyncGenerator[T, None],
+    span: "Span",
+) -> AsyncGenerator[T, None]:
+    """Wrap an async generator so that response attributes are captured from
+    the last yielded chunk before the span is closed."""
+    has_error = False
+
+    try:
+        last_chunk = None
+        async for chunk in aioitertools.iter(res):
+            last_chunk = chunk
+            yield chunk
+
+    except BaseException as e:
+        has_error = True
+        _set_span_error_status(span, e)
+        raise
+
+    finally:
+        if not has_error:
+            response_attributes = _get_llm_response_attributes(last_chunk)
+            span.set_attributes(response_attributes)
+            _set_span_success_status(span)
+
+
+# ---------------------------------------------------------------------------
+# TracingMiddleware
+# ---------------------------------------------------------------------------
+
+
+class TracingMiddleware(MiddlewareBase):
+    """Agent middleware that adds OpenTelemetry tracing to the reply,
+    model-call and tool-execution lifecycles.
+
+    When tracing has not been configured (``setup_tracing`` was not called),
+    every hook short-circuits to ``next_handler`` with near-zero overhead.
+
+    Example::
+
+        from agentscope.middleware import TracingMiddleware
+
+        agent = Agent(
+            ...,
+            middlewares=[TracingMiddleware()],
+        )
+    """
+
+    # ------------------------------------------------------------------
+    # on_reply
+    # ------------------------------------------------------------------
+    async def on_reply(
+        self,
+        agent: "Agent",
+        input_kwargs: dict,
+        next_handler: Callable[..., AsyncGenerator],
+    ) -> AsyncGenerator:
+        if not _check_tracing_enabled():
+            async for item in next_handler(**input_kwargs):
+                yield item
+            return
+
+        session_id = agent.state.session_id
+        common_attrs = _get_common_attributes(session_id)
+
+        tracer = _get_tracer()
+        request_attributes = _get_agent_request_attributes(
+            agent,
+            input_kwargs,
+        )
+        span_name = _get_agent_span_name(request_attributes)
+
+        with tracer.start_as_current_span(
+            name=span_name,
+            attributes={
+                **request_attributes,
+                **common_attrs,
+            },
+            end_on_exit=False,
+        ) as span:
+            # Synthetic execute_tool spans for externally executed tools
+            event_arg = input_kwargs.get("inputs")
+            if isinstance(event_arg, ExternalExecutionResultEvent):
+                for result in event_arg.execution_results:
+                    tool_attrs: dict[str, Any] = {
+                        SpanAttributes.GEN_AI_OPERATION_NAME: (
+                            OperationNameValues.EXECUTE_TOOL
+                        ),
+                        SpanAttributes.GEN_AI_TOOL_CALL_ID: result.id,
+                        SpanAttributes.GEN_AI_TOOL_NAME: result.name,
+                        SpanAttributes.AGENTSCOPE_IS_EXTERNAL_EXECUTION: (
+                            True
+                        ),
+                        **common_attrs,
+                    }
+                    if result.output is not None:
+                        tool_attrs[
+                            SpanAttributes.GEN_AI_TOOL_CALL_RESULT
+                        ] = _serialize_to_str(result.output)
+                    with tracer.start_as_current_span(
+                        name=(
+                            f"{OperationNameValues.EXECUTE_TOOL}"
+                            f" {result.name}"
+                        ),
+                        attributes=tool_attrs,
+                    ):
+                        pass
+
+            has_error = False
+            error_exc: BaseException | None = None
+            last_msg: Msg | None = None
+            hitl_pending: list[str] = []
+            external_pending: list[str] = []
+            observed_reply_id: str | None = None
+
+            try:
+                async for item in next_handler(**input_kwargs):
+                    if isinstance(item, ReplyStartEvent):
+                        observed_reply_id = item.reply_id
+                    elif isinstance(item, RequireUserConfirmEvent):
+                        hitl_pending.extend(t.name for t in item.tool_calls)
+                    elif isinstance(item, RequireExternalExecutionEvent):
+                        external_pending.extend(
+                            t.name for t in item.tool_calls
+                        )
+                    if isinstance(item, Msg):
+                        last_msg = item
+                    yield item
+            except BaseException as e:
+                has_error = True
+                error_exc = e
+                raise
+            finally:
+                reply_id = observed_reply_id or agent.state.reply_id
+                if reply_id:
+                    span.set_attribute(
+                        SpanAttributes.AGENTSCOPE_REPLY_ID,
+                        reply_id,
+                    )
+                if hitl_pending:
+                    span.set_attribute(
+                        SpanAttributes.AGENTSCOPE_HITL_PENDING_TOOLS,
+                        json.dumps(hitl_pending, ensure_ascii=False),
+                    )
+                if external_pending:
+                    span.set_attribute(
+                        SpanAttributes.AGENTSCOPE_EXTERNAL_EXECUTION_PENDING_TOOLS,  # noqa
+                        json.dumps(external_pending, ensure_ascii=False),
+                    )
+                if has_error and error_exc is not None:
+                    _set_span_error_status(span, error_exc)
+                else:
+                    if last_msg is not None:
+                        span.set_attributes(
+                            _get_agent_response_attributes(last_msg),
+                        )
+                    _set_span_success_status(span)
+
+    # ------------------------------------------------------------------
+    # on_model_call
+    # ------------------------------------------------------------------
+    async def on_model_call(
+        self,
+        agent: "Agent",
+        input_kwargs: dict,
+        next_handler: Callable[
+            ...,
+            Awaitable["ChatResponse" | AsyncGenerator["ChatResponse", None]],
+        ],
+    ) -> Union["ChatResponse", AsyncGenerator["ChatResponse", None]]:
+        if not _check_tracing_enabled():
+            return await next_handler(**input_kwargs)
+
+        model = input_kwargs.get("current_model")
+        if not isinstance(model, ChatModelBase):
+            return await next_handler(**input_kwargs)
+
+        tracer = _get_tracer()
+
+        combined_kwargs = {
+            **getattr(model, "generate_kwargs", {}),
+            **input_kwargs,
+        }
+        request_attributes = _get_llm_request_attributes(
+            model,
+            combined_kwargs,
+        )
+        span_name = _get_llm_span_name(request_attributes)
+
+        with tracer.start_as_current_span(
+            name=span_name,
+            attributes={
+                **request_attributes,
+                **_get_common_attributes(agent.state.session_id),
+            },
+            end_on_exit=False,
+        ) as span:
+            try:
+                result = await next_handler(**input_kwargs)
+
+                if isinstance(result, AsyncGenerator):
+                    return _trace_async_generator_wrapper(result, span)
+
+                span.set_attributes(_get_llm_response_attributes(result))
+                _set_span_success_status(span)
+                return result
+
+            except BaseException as e:
+                _set_span_error_status(span, e)
+                raise
+
+    # ------------------------------------------------------------------
+    # on_acting
+    # ------------------------------------------------------------------
+    async def on_acting(
+        self,
+        agent: "Agent",
+        input_kwargs: dict,
+        next_handler: Callable[..., AsyncGenerator],
+    ) -> AsyncGenerator:
+        if not _check_tracing_enabled():
+            async for item in next_handler(**input_kwargs):
+                yield item
+            return
+
+        tool_call = input_kwargs.get("tool_call")
+        if not isinstance(tool_call, ToolCallBlock):
+            async for item in next_handler(**input_kwargs):
+                yield item
+            return
+
+        tracer = _get_tracer()
+
+        request_attributes = _get_tool_request_attributes(
+            agent.toolkit,
+            tool_call,
+        )
+        span_name = _get_tool_span_name(request_attributes)
+
+        with tracer.start_as_current_span(
+            name=span_name,
+            attributes={
+                **request_attributes,
+                **_get_common_attributes(agent.state.session_id),
+            },
+            end_on_exit=False,
+        ) as span:
+            has_error = False
+            last_item = None
+            try:
+                async for item in next_handler(**input_kwargs):
+                    last_item = item
+                    yield item
+            except BaseException as e:
+                has_error = True
+                _set_span_error_status(span, e)
+                raise
+            finally:
+                if not has_error:
+                    if last_item is not None:
+                        span.set_attributes(
+                            _get_tool_response_attributes(last_item),
+                        )
+                    _set_span_success_status(span)
diff --git a/src/agentscope/middleware/_tracing/_utils.py b/src/agentscope/middleware/_tracing/_utils.py
new file mode 100644
index 0000000..b06bbbc
--- /dev/null
+++ b/src/agentscope/middleware/_tracing/_utils.py
@@ -0,0 +1,78 @@
+# -*- coding: utf-8 -*-
+"""Serialize objects to JSON string."""
+import datetime
+import enum
+import inspect
+import json
+from dataclasses import is_dataclass
+from typing import Any
+
+from pydantic import BaseModel
+
+from ...message import Msg
+
+
+def _to_serializable(
+    obj: Any,
+) -> Any:
+    """Convert an object to a JSON serializable type.
+
+    Args:
+        obj (`Any`):
+            The object to be converted to JSON serializable.
+
+    Returns:
+        `Any`:
+            The converted JSON serializable object
+    """
+
+    # Handle primitive types first
+    if isinstance(obj, (str, int, bool, float, type(None))):
+        res = obj
+
+    elif isinstance(obj, (list, tuple, set, frozenset)):
+        res = [_to_serializable(x) for x in obj]
+
+    elif isinstance(obj, dict):
+        res = {str(key): _to_serializable(val) for (key, val) in obj.items()}
+
+    elif isinstance(obj, (Msg, BaseModel)) or is_dataclass(obj):
+        res = repr(obj)
+
+    elif inspect.isclass(obj) and issubclass(obj, BaseModel):
+        res = repr(obj)
+
+    elif isinstance(obj, (datetime.date, datetime.datetime, datetime.time)):
+        res = obj.isoformat()
+
+    elif isinstance(obj, datetime.timedelta):
+        res = obj.total_seconds()
+
+    elif isinstance(obj, enum.Enum):
+        res = _to_serializable(obj.value)
+
+    else:
+        res = str(obj)
+
+    return res
+
+
+def _serialize_to_str(value: Any) -> str:
+    """Serialize input value to JSON string.
+
+    Args:
+        value (`Any`):
+            The input value
+
+    Returns:
+        `str`:
+            JSON serialized string of the input value
+    """
+    try:
+        return json.dumps(value, ensure_ascii=False)
+
+    except TypeError:
+        return json.dumps(
+            _to_serializable(value),
+            ensure_ascii=False,
+        )
diff --git a/src/agentscope/middleware/_tts_middleware.py b/src/agentscope/middleware/_tts_middleware.py
new file mode 100644
index 0000000..32c1d95
--- /dev/null
+++ b/src/agentscope/middleware/_tts_middleware.py
@@ -0,0 +1,179 @@
+# -*- coding: utf-8 -*-
+"""Middleware that turns reasoning text into speech and injects it as
+``DATA_BLOCK_*`` events into the agent's event stream."""
+from typing import TYPE_CHECKING, AsyncGenerator, Callable
+
+from ._base import MiddlewareBase
+from .._utils._common import _generate_id
+from ..event import (
+    DataBlockDeltaEvent,
+    DataBlockEndEvent,
+    DataBlockStartEvent,
+    TextBlockDeltaEvent,
+    TextBlockEndEvent,
+)
+from ..tts import TTSModelBase, TTSResponse
+
+if TYPE_CHECKING:
+    from ..agent import Agent
+
+
+class TTSMiddleware(MiddlewareBase):
+    """Synthesize speech for every text block produced during reasoning and
+    inject the audio as ``DATA_BLOCK_*`` events into the stream.
+
+    - Non-realtime TTS (``realtime=False``): on each
+      ``TextBlockEndEvent`` the accumulated text is sent to
+      :meth:`TTSModelBase.synthesize`; the resulting audio chunks are
+      emitted as one ``DATA_BLOCK_START`` + N ``DATA_BLOCK_DELTA`` +
+      ``DATA_BLOCK_END``.
+    - Realtime TTS (``realtime=True``): each
+      ``TextBlockDeltaEvent`` is pushed into the model via
+      :meth:`TTSModelBase.push`; any audio produced is emitted immediately.
+      On ``TextBlockEndEvent`` :meth:`TTSModelBase.synthesize` is called
+      to drain remaining audio, and the data block is closed.
+
+    Each ``DataBlockDeltaEvent.data`` carries an **incremental** base64 PCM
+    chunk; the full audio is the concatenation of every delta's decoded
+    bytes (the data block is keyed by ``block_id``).
+    """
+
+    def __init__(self, tts_model: TTSModelBase) -> None:
+        """Initialize the TTS middleware.
+
+        Args:
+            tts_model (`TTSModelBase`):
+                The TTS model used to synthesize speech for assistant text
+                blocks produced during reasoning.
+        """
+        self.tts = tts_model
+
+    async def on_reply(
+        self,
+        agent: "Agent",
+        input_kwargs: dict,
+        next_handler: Callable[..., AsyncGenerator],
+    ) -> AsyncGenerator:
+        """Intercept the reply stream, synthesize speech for text blocks,
+        and inject ``DATA_BLOCK_*`` audio events into the output."""
+        text_buffer: str = ""
+        audio_block_id: str | None = None
+        audio_media_type: str | None = None
+
+        async with self.tts:
+            async for evt in next_handler(**input_kwargs):
+                yield evt
+
+                if isinstance(evt, TextBlockDeltaEvent):
+                    text_buffer += evt.delta
+                    if self.tts.realtime and evt.delta:
+                        tts_res = await self.tts.push(evt.delta)
+                        async for audio_evt in self._emit_chunk(
+                            agent,
+                            tts_res,
+                            audio_block_id,
+                            audio_media_type,
+                        ):
+                            if isinstance(audio_evt, DataBlockStartEvent):
+                                audio_block_id = audio_evt.block_id
+                                audio_media_type = audio_evt.media_type
+                            yield audio_evt
+
+                elif isinstance(evt, TextBlockEndEvent):
+                    text = text_buffer
+                    text_buffer = ""
+
+                    if self.tts.realtime:
+                        res = await self.tts.synthesize()
+                        async for audio_evt in self._emit_synth_result(
+                            agent,
+                            res,
+                            audio_block_id,
+                            audio_media_type,
+                        ):
+                            if isinstance(audio_evt, DataBlockStartEvent):
+                                audio_block_id = audio_evt.block_id
+                                audio_media_type = audio_evt.media_type
+                            yield audio_evt
+                    elif text.strip():
+                        res = await self.tts.synthesize(text)
+                        async for audio_evt in self._emit_synth_result(
+                            agent,
+                            res,
+                            audio_block_id,
+                            audio_media_type,
+                        ):
+                            if isinstance(audio_evt, DataBlockStartEvent):
+                                audio_block_id = audio_evt.block_id
+                                audio_media_type = audio_evt.media_type
+                            yield audio_evt
+
+                    if audio_block_id is not None:
+                        yield DataBlockEndEvent(
+                            reply_id=agent.state.reply_id,
+                            block_id=audio_block_id,
+                        )
+                    audio_block_id = None
+                    audio_media_type = None
+
+    async def _emit_synth_result(
+        self,
+        agent: "Agent",
+        res: TTSResponse | AsyncGenerator[TTSResponse, None],
+        audio_block_id: str | None,
+        audio_media_type: str | None,
+    ) -> AsyncGenerator:
+        """Normalize ``synthesize()`` returns (single response or async
+        generator) into a stream of ``DATA_BLOCK_*`` events."""
+        if isinstance(res, AsyncGenerator):
+            async for chunk in res:
+                async for ae in self._emit_chunk(
+                    agent,
+                    chunk,
+                    audio_block_id,
+                    audio_media_type,
+                ):
+                    if isinstance(ae, DataBlockStartEvent):
+                        audio_block_id = ae.block_id
+                        audio_media_type = ae.media_type
+                    yield ae
+        else:
+            async for ae in self._emit_chunk(
+                agent,
+                res,
+                audio_block_id,
+                audio_media_type,
+            ):
+                yield ae
+
+    @staticmethod
+    async def _emit_chunk(
+        agent: "Agent",
+        tts_res: TTSResponse | None,
+        audio_block_id: str | None,
+        audio_media_type: str | None,
+    ) -> AsyncGenerator:
+        """Emit one TTSResponse chunk as ``DATA_BLOCK_START`` (if needed)
+        followed by ``DATA_BLOCK_DELTA``."""
+        if tts_res is None or tts_res.content is None:
+            return
+        media_type = tts_res.content.source.media_type
+        data = tts_res.content.source.data
+        if not data:
+            return
+
+        if audio_block_id is None:
+            audio_block_id = _generate_id()
+            audio_media_type = media_type
+            yield DataBlockStartEvent(
+                reply_id=agent.state.reply_id,
+                block_id=audio_block_id,
+                media_type=media_type,
+            )
+
+        yield DataBlockDeltaEvent(
+            reply_id=agent.state.reply_id,
+            block_id=audio_block_id,
+            data=data,
+            media_type=audio_media_type,
+        )
diff --git a/src/agentscope/model/__init__.py b/src/agentscope/model/__init__.py
new file mode 100644
index 0000000..e7bf1b8
--- /dev/null
+++ b/src/agentscope/model/__init__.py
@@ -0,0 +1,34 @@
+# -*- coding: utf-8 -*-
+"""The model module."""
+
+from ._base import ChatModelBase
+from ._model_card import ModelCard
+from ._model_response import ChatResponse, StructuredResponse, FinishedReason
+from ._model_usage import ChatUsage
+from ._anthropic import AnthropicChatModel
+from ._dashscope import DashScopeChatModel
+from ._deepseek import DeepSeekChatModel
+from ._gemini import GeminiChatModel
+from ._ollama import OllamaChatModel
+from ._openai_chat import OpenAIChatModel
+from ._xai import XAIChatModel
+from ._moonshot import MoonshotChatModel
+from ._openai_response import OpenAIResponseModel
+
+__all__ = [
+    "ChatUsage",
+    "ChatModelBase",
+    "ChatResponse",
+    "FinishedReason",
+    "ModelCard",
+    "StructuredResponse",
+    "AnthropicChatModel",
+    "DashScopeChatModel",
+    "DeepSeekChatModel",
+    "GeminiChatModel",
+    "OllamaChatModel",
+    "OpenAIChatModel",
+    "XAIChatModel",
+    "MoonshotChatModel",
+    "OpenAIResponseModel",
+]
diff --git a/src/agentscope/model/_anthropic/__init__.py b/src/agentscope/model/_anthropic/__init__.py
new file mode 100644
index 0000000..fd62e62
--- /dev/null
+++ b/src/agentscope/model/_anthropic/__init__.py
@@ -0,0 +1,9 @@
+# -*- coding: utf-8 -*-
+"""The Anthropic LLM API modules."""
+
+from ._model import AnthropicCredential, AnthropicChatModel
+
+__all__ = [
+    "AnthropicCredential",
+    "AnthropicChatModel",
+]
diff --git a/src/agentscope/model/_anthropic/_model.py b/src/agentscope/model/_anthropic/_model.py
new file mode 100644
index 0000000..f3b5e6d
--- /dev/null
+++ b/src/agentscope/model/_anthropic/_model.py
@@ -0,0 +1,545 @@
+# -*- coding: utf-8 -*-
+"""The Anthropic chat model implementation."""
+import json
+from collections import OrderedDict
+from datetime import datetime
+from typing import Literal, Any, AsyncGenerator, TYPE_CHECKING, List, Type
+
+from pydantic import BaseModel, Field
+
+from .._base import ChatModelBase, _TOOL_CHOICE_LITERAL_MODES
+from .._model_response import ChatResponse, StructuredResponse
+from .._model_usage import ChatUsage
+from ..._utils._common import _generate_id
+from ...credential import AnthropicCredential
+from ...formatter import FormatterBase, AnthropicChatFormatter
+from ...message import Msg, ThinkingBlock, ToolCallBlock, TextBlock
+from ...tool import ToolChoice
+
+if TYPE_CHECKING:
+    from anthropic.types.message import Message
+    from anthropic import AsyncStream
+else:
+    Message = Any
+    AsyncStream = Any
+
+
+class AnthropicChatModel(ChatModelBase):
+    """The Anthropic chat model."""
+
+    type: Literal["anthropic_chat"] = "anthropic_chat"
+    """The type of the chat model."""
+
+    class Parameters(BaseModel):
+        """The parameters for the Anthropic chat model."""
+
+        max_tokens: int | None = Field(
+            default=None,
+            title="Max Tokens",
+            description=(
+                "The maximum number of tokens to generate in the chat "
+                "completion."
+            ),
+            gt=0,
+        )
+
+        thinking_enable: bool = Field(
+            default=False,
+            title="Thinking",
+            description="The thinking enable for the LLM output.",
+        )
+
+        thinking_budget: int | None = Field(
+            default=None,
+            title="Thinking Budget",
+            description="The thinking budget for the LLM output.",
+            gt=0,
+        )
+
+    def __init__(
+        self,
+        credential: AnthropicCredential,
+        model: str,
+        parameters: "AnthropicChatModel.Parameters | None" = None,
+        stream: bool = True,
+        max_retries: int = 3,
+        retry_delay: float = 1.0,
+        context_size: int = 200000,
+        formatter: FormatterBase | None = None,
+        client_kwargs: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize the Anthropic chat model.
+
+        Args:
+            credential (`AnthropicCredential`):
+                The Anthropic credential used to authenticate API calls.
+            model (`str`):
+                The Anthropic model name, e.g. ``claude-opus-4-7``.
+            parameters (`AnthropicChatModel.Parameters | None`, defaults to \
+            `None`):
+                The Anthropic API parameters. When ``None``, the default
+                parameters will be used.
+            stream (`bool`, defaults to `True`):
+                Whether to enable streaming output.
+            max_retries (`int`, defaults to `3`):
+                The maximum number of retries for the Anthropic API.
+            retry_delay (`float`, defaults to `1.0`):
+                Seconds to sleep between retry attempts.
+            context_size (`int`, defaults to `200000`):
+                The model context size used for context compression.
+            formatter (`FormatterBase | None`, defaults to `None`):
+                The formatter that converts ``Msg`` objects to the format
+                required by the Anthropic API. When ``None``, an
+                ``AnthropicChatFormatter`` instance will be used.
+            client_kwargs (`dict[str, Any] | None`, defaults to `None`):
+                Extra keyword arguments forwarded to
+                ``anthropic.AsyncAnthropic`` (e.g. ``timeout``,
+                ``default_headers``, ``http_client``, ``auth_token``).
+        """
+        super().__init__(
+            credential=credential,
+            model=model,
+            parameters=parameters or self.Parameters(),
+            stream=stream,
+            max_retries=max_retries,
+            retry_delay=retry_delay,
+            context_size=context_size,
+        )
+        self.formatter = formatter or AnthropicChatFormatter()
+        self.client_kwargs = client_kwargs or {}
+
+    @classmethod
+    def _get_retryable_exceptions(cls) -> tuple[Type[Exception], ...]:
+        import anthropic
+
+        return (
+            anthropic.APIConnectionError,
+            anthropic.APITimeoutError,
+            anthropic.RateLimitError,
+            anthropic.InternalServerError,
+        )
+
+    async def _call_api(
+        self,
+        model_name: str,
+        messages: list[Msg],
+        tools: list[dict] | None = None,
+        tool_choice: ToolChoice | None = None,
+        **generate_kwargs: Any,
+    ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:
+        """Get the response from Anthropic chat completions API by the given
+        arguments.
+
+        Args:
+            model_name (`str`):
+                The model name to use for this call.
+            messages (`list[dict]`):
+                A list of dictionaries, where `role` and `content` fields are
+                required, and `name` field is optional.
+            tools (`list[dict]`, default `None`):
+                The tools JSON schemas.
+            tool_choice (`ToolChoice | None`, optional):
+                Controls which (if any) tool is called by the model.
+            **generate_kwargs (`Any`):
+                The keyword arguments for Anthropic chat completions API.
+
+        Returns:
+            `ChatResponse | AsyncGenerator[ChatResponse, None]`:
+                A ``ChatResponse`` when streaming is disabled, or an async
+                generator of ``ChatResponse`` objects when streaming is
+                enabled.
+        """
+
+        import anthropic
+
+        client = anthropic.AsyncAnthropic(
+            **{
+                "api_key": self.credential.api_key.get_secret_value(),
+                "base_url": self.credential.base_url,
+                **self.client_kwargs,
+            },
+        )
+
+        # Anthropic requires max_tokens; fall back to a safe default when
+        # the user hasn't configured one explicitly.
+        max_tokens = self.parameters.max_tokens or 8192
+
+        kwargs: dict[str, Any] = {
+            "model": model_name,
+            "max_tokens": max_tokens,
+            "stream": self.stream,
+            **generate_kwargs,
+        }
+
+        # Anthropic extended thinking — only set when explicitly enabled.
+        # Anthropic requires max_tokens > budget_tokens strictly.
+        if self.parameters.thinking_enable and "thinking" not in kwargs:
+            budget = self.parameters.thinking_budget or (max_tokens // 2)
+            if budget >= max_tokens:
+                # Auto-expand max_tokens to satisfy the strict inequality.
+                max_tokens = budget + 1024
+                kwargs["max_tokens"] = max_tokens
+            kwargs["thinking"] = {
+                "type": "enabled",
+                "budget_tokens": budget,
+            }
+
+        fmt_tools, fmt_tool_choice = self._format_tools(tools, tool_choice)
+        if fmt_tools:
+            kwargs["tools"] = fmt_tools
+        if fmt_tool_choice is not None:
+            kwargs["tool_choice"] = fmt_tool_choice
+
+        formatted_messages = await self.formatter.format(messages)
+
+        # Extract the system message
+        if formatted_messages and formatted_messages[0]["role"] == "system":
+            kwargs["system"] = formatted_messages[0]["content"]
+            formatted_messages = formatted_messages[1:]
+
+        kwargs["messages"] = formatted_messages
+
+        start_datetime = datetime.now()
+
+        response = await client.messages.create(**kwargs)
+
+        if self.stream:
+            return self._parse_anthropic_stream_completion_response(
+                start_datetime,
+                response,
+            )
+
+        # Non-streaming response
+        parsed_response = await self._parse_anthropic_completion_response(
+            start_datetime,
+            response,
+        )
+
+        return parsed_response
+
+    async def _parse_anthropic_completion_response(
+        self,
+        start_datetime: datetime,
+        response: Message,
+    ) -> ChatResponse:
+        """Given an Anthropic Message object, extract the content blocks and
+        usages from it.
+
+        Args:
+            start_datetime (`datetime`):
+                The start datetime of the response generation.
+            response (`Message`):
+                Anthropic Message object to parse.
+
+        Returns:
+            `ChatResponse`:
+                A single ``ChatResponse`` with ``is_last=True`` containing
+                the extracted content blocks and usage.
+        """
+        content_blocks: List[ThinkingBlock | TextBlock | ToolCallBlock] = []
+
+        if hasattr(response, "content") and response.content:
+            for content_block in response.content:
+                if (
+                    hasattr(content_block, "type")
+                    and content_block.type == "thinking"
+                ):
+                    thinking_block = ThinkingBlock(
+                        thinking=content_block.thinking,
+                        signature=getattr(content_block, "signature", "")
+                        or "",
+                    )
+                    content_blocks.append(thinking_block)
+
+                elif (
+                    hasattr(content_block, "type")
+                    and content_block.type == "text"
+                ):
+                    content_blocks.append(
+                        TextBlock(text=content_block.text),
+                    )
+
+                elif (
+                    hasattr(content_block, "type")
+                    and content_block.type == "tool_use"
+                ):
+                    content_blocks.append(
+                        ToolCallBlock(
+                            id=content_block.id,
+                            name=content_block.name,
+                            input=json.dumps(
+                                content_block.input,
+                                ensure_ascii=False,
+                            ),
+                        ),
+                    )
+
+        usage = None
+        if response.usage:
+            u = response.usage
+            usage = ChatUsage(
+                input_tokens=u.input_tokens,
+                output_tokens=u.output_tokens,
+                time=(datetime.now() - start_datetime).total_seconds(),
+                cache_creation_input_tokens=getattr(
+                    u,
+                    "cache_creation_input_tokens",
+                    0,
+                )
+                or 0,
+                cache_input_tokens=getattr(
+                    u,
+                    "cache_read_input_tokens",
+                    0,
+                )
+                or 0,
+            )
+
+        resp_kwargs: dict[str, Any] = {
+            "content": content_blocks,
+            "is_last": True,
+            "usage": usage,
+        }
+        response_id = getattr(response, "id", None)
+        if response_id:
+            resp_kwargs["id"] = response_id
+
+        return ChatResponse(**resp_kwargs)
+
+    async def _parse_anthropic_stream_completion_response(
+        self,
+        start_datetime: datetime,
+        response: AsyncStream,
+    ) -> AsyncGenerator[ChatResponse, None]:
+        """Given an Anthropic streaming response, extract the content blocks
+        and usages from it and yield ChatResponse objects.
+
+        Args:
+            start_datetime (`datetime`):
+                The start datetime of the response generation.
+            response (`AsyncStream`):
+                Anthropic AsyncStream object to parse.
+
+        Yields:
+            `ChatResponse`:
+                Incremental ``ChatResponse`` objects with ``is_last=False``
+                followed by a final one with ``is_last=True`` containing the
+                fully accumulated content blocks and usage.
+        """
+
+        usage = None
+        response_id: str = _generate_id()
+        text_id: str = _generate_id()
+        thinking_id: str = _generate_id()
+        # The mapping from index to tool call id
+        tool_call_mapping: dict = OrderedDict()
+
+        async for event in response:
+            delta_res = ChatResponse(content=[], is_last=False, id=response_id)
+
+            if event.type == "message_start":
+                message = event.message
+
+                # Update the response ID if exists
+                response_id = getattr(message, "id", None) or response_id
+                delta_res.id = response_id
+
+                if message.usage:
+                    u = message.usage
+                    usage = ChatUsage(
+                        input_tokens=u.input_tokens,
+                        output_tokens=getattr(u, "output_tokens", 0),
+                        time=(datetime.now() - start_datetime).total_seconds(),
+                        cache_creation_input_tokens=getattr(
+                            u,
+                            "cache_creation_input_tokens",
+                            0,
+                        ),
+                        cache_input_tokens=getattr(
+                            u,
+                            "cache_read_input_tokens",
+                            0,
+                        ),
+                    )
+
+            elif event.type == "content_block_start":
+                if event.content_block.type == "tool_use":
+                    tool_block = event.content_block
+                    # Record the id and name
+                    tool_call_mapping[event.index] = (
+                        tool_block.id,
+                        tool_block.name,
+                    )
+                    # New tool call block with empty input
+                    delta_res.append_tool_call(
+                        block_id=tool_block.id,
+                        name=tool_block.name,
+                        input="",
+                    )
+
+            elif event.type == "content_block_delta":
+                block_index = event.index
+                delta = event.delta
+
+                # Text block
+                if delta.type == "text_delta":
+                    delta_res.append_text(delta.text, block_id=text_id)
+
+                # Thinking block
+                elif delta.type == "thinking_delta":
+                    delta_res.append_thinking(
+                        delta.thinking,
+                        block_id=thinking_id,
+                    )
+
+                # Special handling for Anthropic API that requires signature
+                elif delta.type == "signature_delta":
+                    delta_res.append_thinking(
+                        "",
+                        block_id=thinking_id,
+                        signature=delta.signature,
+                    )
+
+                # Tool call block
+                elif (
+                    delta.type == "input_json_delta"
+                    and block_index in tool_call_mapping
+                ):
+                    block_id, name = tool_call_mapping[block_index]
+                    delta_res.append_tool_call(
+                        block_id=block_id,
+                        name=name,
+                        input=delta.partial_json or "",
+                    )
+
+            elif event.type == "message_delta":
+                if event.usage and usage:
+                    usage.output_tokens = event.usage.output_tokens
+
+            if delta_res.content:
+                delta_res.usage = usage
+                yield delta_res
+
+    def _format_tools(
+        self,
+        tools: list[dict] | None,
+        tool_choice: ToolChoice | None,
+    ) -> tuple[list[dict] | None, dict | None]:
+        """Validate and format tools and tool_choice for Anthropic.
+
+        Converts tool schemas to Anthropic's flat format and maps
+        tool_choice modes to Anthropic's type-based format. When
+        ``tool_choice.tools`` is specified the schemas list is filtered
+        to only those tools. When ``tool_choice.mode`` is a specific tool
+        name (str) the model is forced to call exactly that tool without
+        needing to filter the list, preserving prompt-cache efficiency.
+
+        Args:
+            tools (`list[dict] | None`, optional):
+                The raw tool schemas.
+            tool_choice (`ToolChoice | None`, optional):
+                The tool choice configuration.
+
+        Returns:
+            `tuple[list[dict] | None, dict | None]`:
+                A tuple of (formatted_tools, formatted_tool_choice).
+        """
+        if tool_choice and tools:
+            self._validate_tool_choice(tool_choice, tools)
+            if tool_choice.tools:
+                allowed = set(tool_choice.tools)
+                tools = [t for t in tools if t["function"]["name"] in allowed]
+
+        fmt_tools = None
+        if tools:
+            fmt_tools = []
+            for schema in tools:
+                assert (
+                    "function" in schema
+                ), f"Invalid schema: {schema}, expect key 'function'."
+                assert "name" in schema["function"], (
+                    f"Invalid schema: {schema}, "
+                    "expect key 'name' in 'function' field."
+                )
+                fmt_tools.append(
+                    {
+                        "name": schema["function"]["name"],
+                        "description": schema["function"].get(
+                            "description",
+                            "",
+                        ),
+                        "input_schema": schema["function"].get(
+                            "parameters",
+                            {},
+                        ),
+                    },
+                )
+
+        if not tool_choice:
+            return fmt_tools, None
+
+        mode = tool_choice.mode
+
+        if mode not in _TOOL_CHOICE_LITERAL_MODES:
+            # mode is a specific tool name — force call it
+            return fmt_tools, {"type": "tool", "name": mode}
+
+        type_mapping = {
+            "auto": {"type": "auto"},
+            "none": {"type": "none"},
+            "required": {"type": "any"},
+        }
+        return fmt_tools, type_mapping[mode]
+
+    async def _call_api_with_structured_output(
+        self,
+        model_name: str,
+        messages: list[Msg],
+        structured_model: Type[BaseModel] | dict,
+        tool_choice: ToolChoice | None = None,
+        **kwargs: Any,
+    ) -> StructuredResponse:
+        """Anthropic-specific override for structured output.
+
+        Anthropic's extended thinking mode only supports
+        ``tool_choice={"type": "auto"}`` or ``{"type": "none"}``; any
+        forcing form (``"any"`` or a specific tool) raises an API error.
+        When ``thinking_enable`` is on we default ``tool_choice`` to
+        ``"auto"`` and rely on the base class's injected system-reminder
+        prompt to guide the model. When thinking is disabled, this falls
+        through to the base implementation (force the structured-output
+        tool).
+
+        See:
+         https://platform.claude.com/docs/en/build-with-claude/extended-thinking#extended-thinking-with-tool-use
+
+        Args:
+            model_name (`str`):
+                The model name to use for this call.
+            messages (`list[Msg]`):
+                The context for the LLM to generate the structured output.
+            structured_model (`Type[BaseModel] | dict`):
+                A Pydantic model class or a JSON schema dict describing the
+                required output structure.
+            tool_choice (`ToolChoice | None`, defaults to `None`):
+                The tool_choice forwarded to ``_call_api``. When ``None``
+                and thinking mode is enabled, it is downgraded to
+                ``ToolChoice(mode="auto")``; otherwise the base default
+                (force the structured-output tool) is used.
+            **kwargs (`Any`):
+                Additional keyword arguments forwarded to ``_call_api``.
+
+        Returns:
+            `StructuredResponse`:
+                The structured response whose ``content`` is the validated
+                output dict matching ``structured_model``.
+        """
+        if tool_choice is None and self.parameters.thinking_enable:
+            tool_choice = ToolChoice(mode="auto")
+        return await super()._call_api_with_structured_output(
+            model_name=model_name,
+            messages=messages,
+            structured_model=structured_model,
+            tool_choice=tool_choice,
+            **kwargs,
+        )
diff --git a/src/agentscope/model/_anthropic/_models/claude-haiku-4-5.yaml b/src/agentscope/model/_anthropic/_models/claude-haiku-4-5.yaml
new file mode 100644
index 0000000..feae8f1
--- /dev/null
+++ b/src/agentscope/model/_anthropic/_models/claude-haiku-4-5.yaml
@@ -0,0 +1,21 @@
+name: claude-haiku-4-5
+label: Claude Haiku 4.5
+status: active
+
+input_types:
+  - text/plain
+  - application/x-thinking
+  - image/jpeg
+  - image/png
+  - image/gif
+  - image/webp
+
+output_types:
+  - text/plain
+  - application/x-thinking
+
+context_size: 200000
+output_size: 65536
+
+parameter_overrides:
+  max_tokens: {"maximum": 65536}
diff --git a/src/agentscope/model/_anthropic/_models/claude-opus-4-5.yaml b/src/agentscope/model/_anthropic/_models/claude-opus-4-5.yaml
new file mode 100644
index 0000000..69f6b4f
--- /dev/null
+++ b/src/agentscope/model/_anthropic/_models/claude-opus-4-5.yaml
@@ -0,0 +1,21 @@
+name: claude-opus-4-5
+label: Claude Opus 4.5
+status: active
+
+input_types:
+  - text/plain
+  - application/x-thinking
+  - image/jpeg
+  - image/png
+  - image/gif
+  - image/webp
+
+output_types:
+  - text/plain
+  - application/x-thinking
+
+context_size: 200000
+output_size: 65536
+
+parameter_overrides:
+  max_tokens: {"maximum": 65536}
diff --git a/src/agentscope/model/_anthropic/_models/claude-opus-4-6.yaml b/src/agentscope/model/_anthropic/_models/claude-opus-4-6.yaml
new file mode 100644
index 0000000..0e5e2f3
--- /dev/null
+++ b/src/agentscope/model/_anthropic/_models/claude-opus-4-6.yaml
@@ -0,0 +1,21 @@
+name: claude-opus-4-6
+label: Claude Opus 4.6
+status: active
+
+input_types:
+  - text/plain
+  - application/x-thinking
+  - image/jpeg
+  - image/png
+  - image/gif
+  - image/webp
+
+output_types:
+  - text/plain
+  - application/x-thinking
+
+context_size: 1000000
+output_size: 131072
+
+parameter_overrides:
+  max_tokens: {"maximum": 131072}
diff --git a/src/agentscope/model/_anthropic/_models/claude-opus-4-7.yaml b/src/agentscope/model/_anthropic/_models/claude-opus-4-7.yaml
new file mode 100644
index 0000000..a3a9bee
--- /dev/null
+++ b/src/agentscope/model/_anthropic/_models/claude-opus-4-7.yaml
@@ -0,0 +1,21 @@
+name: claude-opus-4-7
+label: Claude Opus 4.7
+status: active
+
+input_types:
+  - text/plain
+  - application/x-thinking
+  - image/jpeg
+  - image/png
+  - image/gif
+  - image/webp
+
+output_types:
+    - text/plain
+    - application/x-thinking
+
+context_size: 1000000
+output_size: 128000
+
+parameter_overrides:
+  max_tokens: {"maximum": 128000}
diff --git a/src/agentscope/model/_anthropic/_models/claude-opus-4-8.yaml b/src/agentscope/model/_anthropic/_models/claude-opus-4-8.yaml
new file mode 100644
index 0000000..28df6a8
--- /dev/null
+++ b/src/agentscope/model/_anthropic/_models/claude-opus-4-8.yaml
@@ -0,0 +1,21 @@
+name: claude-opus-4-8
+label: Claude Opus 4.8
+status: active
+
+input_types:
+  - text/plain
+  - application/x-thinking
+  - image/jpeg
+  - image/png
+  - image/gif
+  - image/webp
+
+output_types:
+  - text/plain
+  - application/x-thinking
+
+context_size: 1000000
+output_size: 128000
+
+parameter_overrides:
+  max_tokens: {"maximum": 128000}
diff --git a/src/agentscope/model/_anthropic/_models/claude-sonnet-4-5.yaml b/src/agentscope/model/_anthropic/_models/claude-sonnet-4-5.yaml
new file mode 100644
index 0000000..fedbea5
--- /dev/null
+++ b/src/agentscope/model/_anthropic/_models/claude-sonnet-4-5.yaml
@@ -0,0 +1,21 @@
+name: claude-sonnet-4-5
+label: Claude Sonnet 4.5
+status: active
+
+input_types:
+  - text/plain
+  - application/x-thinking
+  - image/jpeg
+  - image/png
+  - image/gif
+  - image/webp
+
+output_types:
+  - text/plain
+  - application/x-thinking
+
+context_size: 200000
+output_size: 65536
+
+parameter_overrides:
+  max_tokens: {"maximum": 65536}
diff --git a/src/agentscope/model/_anthropic/_models/claude-sonnet-4-6.yaml b/src/agentscope/model/_anthropic/_models/claude-sonnet-4-6.yaml
new file mode 100644
index 0000000..61d22d0
--- /dev/null
+++ b/src/agentscope/model/_anthropic/_models/claude-sonnet-4-6.yaml
@@ -0,0 +1,21 @@
+name: claude-sonnet-4-6
+label: Claude Sonnet 4.6
+status: active
+
+input_types:
+  - text/plain
+  - application/x-thinking
+  - image/jpeg
+  - image/png
+  - image/gif
+  - image/webp
+
+output_types:
+  - text/plain
+  - application/x-thinking
+
+context_size: 1000000
+output_size: 65536
+
+parameter_overrides:
+  max_tokens: {"maximum": 65536}
diff --git a/src/agentscope/model/_base.py b/src/agentscope/model/_base.py
new file mode 100644
index 0000000..54b65db
--- /dev/null
+++ b/src/agentscope/model/_base.py
@@ -0,0 +1,653 @@
+# -*- coding: utf-8 -*-
+"""The base class for the chat models."""
+import asyncio
+import inspect
+import json
+from abc import abstractmethod
+from copy import deepcopy
+from pathlib import Path
+from typing import Type, Any, AsyncGenerator
+
+import jsonschema
+from pydantic import BaseModel
+
+from ._model_response import StructuredResponse, ChatResponse, FinishedReason
+from ._model_card import ModelCard
+from .._logging import logger
+from .._utils._common import _json_loads_with_repair
+from ..credential import CredentialBase
+from ..message import (
+    Msg,
+    TextBlock,
+    UserMsg,
+    ToolCallBlock,
+    ThinkingBlock,
+    ToolResultBlock,
+    DataBlock,
+    HintBlock,
+)
+from ..tool import ToolChoice
+
+_TOOL_CHOICE_LITERAL_MODES = {"auto", "none", "required"}
+_MULTIMODAL_DATA_BLOCK_TOKEN_ESTIMATE = 2000
+
+
+class ChatModelBase:
+    """The base class for chat models."""
+
+    class Parameters(BaseModel):
+        """Each subclass should implement this inner class to define its
+        parameters."""
+
+    credential: CredentialBase
+    """The API credential."""
+
+    model: str
+    """The model name."""
+
+    stream: bool
+    """The enable stream output for the LLM output."""
+
+    max_retries: int
+    """The maximum number of retries for the underlying API."""
+
+    retry_delay: float
+    """Seconds to sleep between retry attempts."""
+
+    context_size: int
+    """The model context size that will be used in the context compression."""
+
+    def __init__(
+        self,
+        credential: CredentialBase,
+        model: str,
+        parameters: BaseModel,
+        stream: bool = True,
+        max_retries: int = 3,
+        retry_delay: float = 1.0,
+        context_size: int = 32768,
+    ) -> None:
+        """Initialize the chat model base.
+
+        Args:
+            credential (CredentialBase):
+                The API credential.
+            model (`str`):
+                The model name.
+            parameters (`BaseModel`):
+                The model parameters.
+            stream (`bool`, defaults to `True`):
+                Whether to enable streaming output for the LLM.
+            max_retries (`int`, defaults to `3`):
+                The maximum number of retries for API calls. Only exceptions
+                listed in ``_get_retryable_exceptions()`` count against this
+                budget; other exceptions are raised immediately.
+            retry_delay (`float`, defaults to `1.0`):
+                Seconds to sleep between retry attempts.
+            context_size (`int`, defaults to `32768`):
+                The model context size used for context compression.
+        """
+        self.credential = credential
+        self.model = model
+        self.parameters = parameters
+        self.stream = stream
+        self.max_retries = max_retries
+        self.retry_delay = retry_delay
+        self.context_size = context_size
+
+    @classmethod
+    def _get_retryable_exceptions(cls) -> tuple[Type[Exception], ...]:
+        """Return the exception types that should trigger a retry.
+
+        Defaults to an empty tuple (no retries). Subclasses can override to
+        declare provider-specific retryable exceptions. SDK exception types
+        should be imported lazily inside the override so the SDK stays an
+        optional dependency.
+        """
+        return ()
+
+    @classmethod
+    def list_models(
+        cls,
+        custom_yaml_dir: str | None = None,
+    ) -> list[ModelCard]:
+        """List candidate models of the API.
+
+        Args:
+            custom_yaml_dir (`str | None`):
+                The custom YAML directory.
+
+        Returns:
+            `list[ModelCard]`:
+                A list of candidate models.
+        """
+
+        # Determine YAML directory
+        if custom_yaml_dir is None:
+            # Use the ``_models`` directory that sits next to the concrete
+            # subclass's source file (not this base file).
+            subclass_file = Path(inspect.getfile(cls))
+            yaml_dir = subclass_file.parent / "_models"
+        else:
+            yaml_dir = Path(custom_yaml_dir)
+
+        # Find all .yaml files
+        yaml_files = list(yaml_dir.glob("*.yaml"))
+
+        # Load each YAML file and create ModelCard
+        model_cards = []
+        for yaml_file in yaml_files:
+            try:
+                card = ModelCard.from_yaml(
+                    yaml_path=str(yaml_file),
+                    parameter_class=cls.Parameters,
+                )
+                model_cards.append(card)
+            except Exception as e:
+                # Log error but continue with other files
+                logger.warning(
+                    "Warning: Failed to load %s: %s",
+                    yaml_file,
+                    str(e),
+                )
+                continue
+
+        return model_cards
+
+    async def __call__(
+        self,
+        messages: list[Msg],
+        tools: list[dict] | None = None,
+        tool_choice: ToolChoice | None = None,
+        **kwargs: Any,
+    ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:
+        """Call the model with retry logic.
+
+        Attempts to call the model up to ``max_retries + 1`` times. Only
+        exceptions listed in ``_get_retryable_exceptions()`` count against
+        this budget; other exceptions are raised immediately.
+
+        Args:
+            messages (`list[Msg]`):
+                The messages to send to the model.
+            tools (`list[dict] | None`, optional):
+                The tools available to the model.
+            tool_choice (`ToolChoice | None`, optional):
+                The tool choice mode or function name.
+            **kwargs:
+                Additional keyword arguments passed to the underlying API.
+        """
+
+        retryable = self._get_retryable_exceptions()
+        last_error: Exception | None = None
+        for attempt in range(self.max_retries + 1):
+            # The accumulated chat response
+            try:
+                res = await self._call_api(
+                    self.model,
+                    messages=messages,
+                    tools=tools,
+                    tool_choice=tool_choice,
+                    **kwargs,
+                )
+                break
+            except asyncio.CancelledError:
+                return ChatResponse(
+                    content=[],
+                    is_last=True,
+                    finished_reason=FinishedReason.INTERRUPTED,
+                )
+
+            except Exception as e:
+                if not isinstance(e, retryable):
+                    raise
+                last_error = e
+                if attempt < self.max_retries:
+                    logger.warning(
+                        "Attempt %d failed for model %s: %s. "
+                        "Retrying in %.1fs...",
+                        attempt + 1,
+                        self.model,
+                        str(e),
+                        self.retry_delay,
+                    )
+                    await asyncio.sleep(self.retry_delay)
+                else:
+                    logger.warning(
+                        "All %d attempt(s) failed for model %s.",
+                        self.max_retries + 1,
+                        self.model,
+                    )
+        else:
+            if last_error is not None:
+                raise last_error
+            raise RuntimeError(
+                f"Failed to call model {self.model} after "
+                f"{self.max_retries + 1} retries.",
+            )
+
+        # =====================================================================
+        # Consume the model calling result
+        # =====================================================================
+        if isinstance(res, ChatResponse):
+            return res
+
+        # The accumulated chat response
+        acc_res = ChatResponse(
+            content=[],
+            is_last=True,
+            finished_reason=FinishedReason.COMPLETED,
+        )
+
+        async def _stream() -> AsyncGenerator[ChatResponse, None]:
+            """The wrapper around model calling."""
+            # For backward compatibility
+            yield_acc_res = True
+            try:
+                async for chunk in res:
+                    if not chunk.is_last:
+                        acc_res.append_chat_response(chunk)
+                        acc_res.id = chunk.id
+                        # Empty-content deltas are "carrier" chunks used
+                        # by subclasses to propagate usage / id metadata
+                        # (e.g. OpenAI-compatible APIs emit a trailing
+                        # usage-only chunk with no choices). We absorb
+                        # their metadata into ``acc_res`` above but do
+                        # not surface them to the consumer, which keeps
+                        # the visible stream free of spurious empty
+                        # deltas.
+                        if not chunk.content:
+                            continue
+                    else:
+                        yield_acc_res = False
+                    yield chunk
+            except asyncio.CancelledError:
+                acc_res.finished_reason = FinishedReason.INTERRUPTED
+                yield_acc_res = True
+
+            if yield_acc_res:
+                yield acc_res
+
+        return _stream()
+
+    @abstractmethod
+    async def _call_api(
+        self,
+        model_name: str,
+        messages: list[Msg],
+        tools: list[dict] | None = None,
+        tool_choice: ToolChoice | None = None,
+        **kwargs: Any,
+    ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:
+        """Call the underlying API. Subclasses must implement this method.
+
+        Args:
+            model_name (`str`):
+                The model name to use for this call.
+            messages (`list[Msg]`):
+                The messages to send to the model.
+            tools (`list[dict] | None`, optional):
+                The tools available to the model.
+            tool_choice (`ToolChoice | None`, optional):
+                The tool choice mode or function name.
+            **kwargs:
+                Additional keyword arguments for the underlying API.
+        """
+
+    def _validate_tool_choice(
+        self,
+        tool_choice: ToolChoice | None,
+        tools: list[dict] | None,
+    ) -> None:
+        """Validate tool_choice parameter.
+
+        Args:
+            tool_choice (`ToolChoice | None`):
+                Tool choice with ``mode`` and optional ``tools`` fields.
+            tools (`list[dict] | None`):
+                Available tools list.
+
+        Raises:
+            `ValueError`:
+                If mode or tool names are invalid.
+        """
+        if tool_choice is None:
+            return
+
+        mode = tool_choice.mode
+        available_functions = [
+            tool["function"]["name"] for tool in (tools or [])
+        ]
+
+        tool_names = tool_choice.tools
+        if tool_names is not None:
+            for name in tool_names:
+                if name not in available_functions:
+                    raise ValueError(
+                        f"Invalid tool name '{name}' in tool_choice.tools. "
+                        f"Available tools: "
+                        f"{', '.join(sorted(available_functions))}",
+                    )
+
+        if mode not in _TOOL_CHOICE_LITERAL_MODES:
+            # mode is a specific tool name — validate it exists
+            # Fall back to all available tools when tool_names is empty or None
+            validation_scope = (
+                tool_names if tool_names else available_functions
+            )
+            if mode not in validation_scope:
+                raise ValueError(
+                    f"Invalid tool name '{mode}' in tool_choice.mode. "
+                    + (
+                        f"Available tools in tool_choice.tools: "
+                        f"{', '.join(sorted(tool_names))}"
+                        if tool_names is not None
+                        else f"Available tools: "
+                        f"{', '.join(sorted(available_functions))}"
+                    ),
+                )
+
+    async def count_tokens(
+        self,
+        messages: list[Msg],
+        tools: list[dict] | None,
+    ) -> int:
+        """A quick and unified method to estimate the token count of the
+        model input by dividing the total input size in bytes by 4.
+
+        Note a standard way to count the tokens is first formatting the input
+        messages into the API required format, then use the tokenizer of the
+        underlying API to count the tokens.
+
+        Subclasses may override this method to provide a more accurate
+        implementation tailored to their specific tokenizer.
+
+        Args:
+            messages (`list[Msg]`):
+                The messages to send to the model.
+            tools (`list[dict] | None`):
+                The tools available to the model.
+
+        Returns:
+            `int`:
+                The number of tokens in the model.
+        """
+        cnt = 0
+
+        acc_texts = []
+        data_blocks = []
+        for msg in messages:
+            for block in msg.get_content_blocks():
+                if isinstance(block, TextBlock):
+                    acc_texts.append(block.text)
+
+                elif isinstance(block, ThinkingBlock):
+                    acc_texts.append(block.thinking)
+
+                elif isinstance(block, HintBlock):
+                    # ``hint`` may be a plain string or a list of
+                    # ``TextBlock`` / ``DataBlock`` for multimodal
+                    # content; mirror the ``ToolResultBlock.output``
+                    # branching above.
+                    if isinstance(block.hint, str):
+                        acc_texts.append(block.hint)
+                    else:
+                        for item in block.hint:
+                            if isinstance(item, TextBlock):
+                                acc_texts.append(item.text)
+                            elif isinstance(item, DataBlock):
+                                data_blocks.append(item)
+
+                elif isinstance(block, ToolCallBlock):
+                    acc_texts.append(block.input)
+
+                elif isinstance(block, ToolResultBlock):
+                    if isinstance(block.output, str):
+                        acc_texts.append(block.output)
+                    elif isinstance(block.output, list):
+                        for item in block.output:
+                            if isinstance(item, TextBlock):
+                                acc_texts.append(item.text)
+                            elif isinstance(item, DataBlock):
+                                data_blocks.append(item)
+
+                elif isinstance(block, DataBlock):
+                    data_blocks.append(block)
+
+                else:
+                    logger.warning(
+                        "Unknown block type %s in token counting, skipping.",
+                        type(block),
+                    )
+
+        # Count the tokens of the tool JSON schemas
+        if tools:
+            acc_texts.append(json.dumps(tools, ensure_ascii=False))
+
+        # Add the multimodal tokens. Binary payloads are not consumed by
+        # multimodal models as base64 text, and file URLs should not count as
+        # only a path string. Use a stable flat estimate for all DataBlocks.
+        cnt += len(data_blocks) * _MULTIMODAL_DATA_BLOCK_TOKEN_ESTIMATE
+
+        # Count the text tokens
+        acc_text = "".join(acc_texts)
+        cnt += int(len(acc_text.encode("utf-8")) / 4 + 0.5)
+
+        return cnt
+
+    async def generate_structured_output(
+        self,
+        messages: list[Msg],
+        structured_model: Type[BaseModel] | dict,
+        **kwargs: Any,
+    ) -> StructuredResponse:
+        """Generate required structured output by the given model.
+
+        Shares the same retry settings (``max_retries``, ``retry_delay``, and
+        ``_get_retryable_exceptions()``) as the ``__call__`` method.
+
+        Args:
+            messages (`list[Msg]`):
+                The context for LLM to generate the structured output.
+            structured_model (`Type[BaseModel] | dict`):
+                A Pydantic model or a dict of JSON schemas.
+
+        Returns:
+            `StructuredResponse`:
+                The structured response generated by the model.
+        """
+
+        if len(messages) == 0:
+            raise ValueError(
+                "The input messages cannot be empty for the "
+                "`generate_structured_output` method.",
+            )
+
+        retryable = tuple(self._get_retryable_exceptions())
+        last_error: Exception | None = None
+        for attempt in range(self.max_retries + 1):
+            try:
+                return await self._call_api_with_structured_output(
+                    self.model,
+                    messages=messages,
+                    structured_model=structured_model,
+                    **kwargs,
+                )
+            except Exception as e:
+                if not isinstance(e, retryable):
+                    raise
+                last_error = e
+                if attempt < self.max_retries:
+                    logger.warning(
+                        "Attempt %d failed for model %s: %s. "
+                        "Retrying in %.1fs...",
+                        attempt + 1,
+                        self.model,
+                        str(e),
+                        self.retry_delay,
+                    )
+                    await asyncio.sleep(self.retry_delay)
+                else:
+                    logger.warning(
+                        "All %d attempt(s) failed for model %s.",
+                        self.max_retries + 1,
+                        self.model,
+                    )
+        if last_error is not None:
+            raise last_error
+        raise RuntimeError(
+            f"Failed to generate structured output after "
+            f"{self.max_retries + 1} retries.",
+        )
+
+    async def _call_api_with_structured_output(
+        self,
+        model_name: str,
+        messages: list[Msg],
+        structured_model: Type[BaseModel] | dict,
+        tool_choice: ToolChoice | None = None,
+        **kwargs: Any,
+    ) -> StructuredResponse:
+        """This function constructs a 'generate_structured_output' tool to
+        help LLM generate structured output as a compromise for LLM APIs that
+        don't support structured output.
+
+        If your subclasses inherit from `ChatModelBase` and the underlying
+        API supports structured output, you can override this method to
+        provide a more accurate implementation.
+
+        Note by default this method forces LLM to call the
+        'generate_structured_output' tool via tool_choice, and adds
+        instructions into the input messages. Subclasses whose underlying
+        API rejects forced tool_choice in certain modes (e.g. DashScope in
+        thinking mode) can pass ``tool_choice=ToolChoice(mode="auto")`` and
+        rely solely on the injected system-reminder prompt. LLM APIs that
+        don't support "required" tool choice may still fail (e.g. generate
+        text output and ignore the tool call, or fail in validation).
+
+        Args:
+            model_name (`str`):
+                The model name to use for this call.
+            messages (`list[Msg]`):
+                The context for the LLM to generate the structured output.
+            structured_model (`Type[BaseModel] | dict`):
+                A Pydantic model class or a JSON schema dict describing the
+                required output structure.
+            tool_choice (`ToolChoice | None`, defaults to `None`):
+                The tool_choice forwarded to ``_call_api``. When ``None``,
+                defaults to forcing the ``generate_structured_output`` tool.
+            **kwargs (`Any`):
+                Additional keyword arguments forwarded to ``_call_api``.
+        """
+
+        if isinstance(structured_model, dict):
+            input_schema = structured_model
+        else:
+            input_schema = structured_model.model_json_schema()
+
+        func_name = "generate_structured_output"
+        if tool_choice is None:
+            tool_choice = ToolChoice(mode=func_name)
+        instruction = (
+            "<system-reminder>Now you **MUST** call the tool named "
+            f"'{func_name}' to generate the structured output required "
+            "by the user. DON'T do anything else.</system-reminder>"
+        )
+
+        copied_messages = deepcopy(messages)
+        # Insert instruction to ensure llm is correctly guided
+        if copied_messages[-1].role == "user":
+            # Insert a user message to the last
+            copied_messages[-1].content = copied_messages[
+                -1
+            ].get_content_blocks() + [TextBlock(text=instruction)]
+        else:
+            copied_messages.append(
+                UserMsg(name="user", content=[TextBlock(text=instruction)]),
+            )
+
+        res = await self._call_api(
+            model_name=model_name,
+            messages=copied_messages,
+            tools=[
+                {
+                    "type": "function",
+                    "function": {
+                        "name": func_name,
+                        "description": "Call this function to generate "
+                        "structured output required by "
+                        "the user.",
+                        "parameters": input_schema,
+                    },
+                },
+            ],
+            tool_choice=tool_choice,
+            **kwargs,
+        )
+
+        completed_response: ChatResponse | None = None
+        if self.stream:
+            # ``_call_api`` yields raw incremental chunks whose ``is_last``
+            # is always ``False``; subclasses rely on the ``__call__``
+            # wrapper to accumulate them and emit a final ``is_last=True``
+            # chunk. Since this method calls ``_call_api`` directly (to
+            # avoid duplicating the retry logic in ``__call__``), we must
+            # replicate that accumulation here, otherwise the stream may
+            # end without ever producing an ``is_last=True`` chunk.
+            acc_res = ChatResponse(
+                content=[],
+                is_last=True,
+                finished_reason=FinishedReason.COMPLETED,
+            )
+            async for chunk in res:
+                if chunk.is_last:
+                    completed_response = chunk
+                    break
+                acc_res.append_chat_response(chunk)
+                acc_res.id = chunk.id
+            if completed_response is None:
+                completed_response = acc_res
+        else:
+            completed_response = res
+
+        if completed_response is None or not completed_response.content:
+            raise RuntimeError(
+                f"Failed to get the completed response from model "
+                f"{model_name}.",
+            )
+
+        structured_output: dict[str, Any] | None = None
+        for _ in completed_response.content:
+            if isinstance(_, ToolCallBlock) and _.name == func_name:
+                structured_output = _json_loads_with_repair(
+                    _.input,
+                    input_schema,
+                )
+                break
+
+        if structured_output is None:
+            raise RuntimeError(
+                "Failed to generate structured output for model.",
+            )
+
+        # Validate the output
+        if isinstance(structured_model, dict):
+            jsonschema.validate(structured_output, structured_model)
+
+        elif issubclass(structured_model, BaseModel):
+            structured_model.model_validate(structured_output)
+
+        else:
+            raise ValueError(
+                "The structured_model is expected to be a subclass of "
+                "Pydantic.BaseModel or a dict, "
+                f"but got {type(structured_model)}.",
+            )
+
+        return StructuredResponse(
+            id=completed_response.id,
+            created_at=completed_response.created_at,
+            content=structured_output,
+            usage=completed_response.usage,
+            finished_reason=completed_response.finished_reason,
+        )
diff --git a/src/agentscope/model/_dashscope/__init__.py b/src/agentscope/model/_dashscope/__init__.py
new file mode 100644
index 0000000..e22af4f
--- /dev/null
+++ b/src/agentscope/model/_dashscope/__init__.py
@@ -0,0 +1,9 @@
+# -*- coding: utf-8 -*-
+"""The DashScope API modules."""
+
+from ._model import DashScopeChatModel, DashScopeCredential
+
+__all__ = [
+    "DashScopeChatModel",
+    "DashScopeCredential",
+]
diff --git a/src/agentscope/model/_dashscope/_model.py b/src/agentscope/model/_dashscope/_model.py
new file mode 100644
index 0000000..a7cf784
--- /dev/null
+++ b/src/agentscope/model/_dashscope/_model.py
@@ -0,0 +1,581 @@
+# -*- coding: utf-8 -*-
+"""The DashScope chat model class (OpenAI-compatible implementation)."""
+import base64
+import warnings
+from collections import OrderedDict
+from datetime import datetime
+from typing import Any, AsyncGenerator, List, Literal, Type, TYPE_CHECKING
+
+from pydantic import BaseModel, Field
+
+from ..._utils._audio import _build_streaming_wav_header
+from ..._utils._common import _generate_id
+from .._base import ChatModelBase, _TOOL_CHOICE_LITERAL_MODES
+from .._model_response import ChatResponse, StructuredResponse
+from .._model_usage import ChatUsage
+from ...credential import DashScopeCredential
+from ...formatter import FormatterBase, DashScopeChatFormatter
+from ...message import (
+    Msg,
+    TextBlock,
+    ThinkingBlock,
+    ToolCallBlock,
+)
+from ...tool import ToolChoice
+
+if TYPE_CHECKING:
+    from openai.types.chat import ChatCompletion
+    from openai import AsyncStream
+else:
+    ChatCompletion = Any
+    AsyncStream = Any
+
+
+class DashScopeChatModel(ChatModelBase):
+    """The DashScope chat model (OpenAI-compatible implementation).
+
+    This implementation uses the OpenAI Python SDK to call DashScope's
+    OpenAI-compatible endpoint (``compatible-mode/v1``), which supports
+    both text-only and multimodal (image/video) inputs through the same
+    unified API.
+    """
+
+    class Parameters(BaseModel):
+        """The parameters for DashScope LLM API."""
+
+        max_tokens: int | None = Field(
+            default=None,
+            title="Max Tokens",
+            description="The maximum number of tokens for the LLM output.",
+            gt=0,
+        )
+
+        thinking_enable: bool = Field(
+            default=False,
+            title="Thinking",
+            description="The thinking enable for the LLM output.",
+        )
+
+        thinking_budget: int | None = Field(
+            default=None,
+            title="Thinking Budget",
+            description="The thinking budget for the LLM output.",
+            gt=0,
+        )
+
+        temperature: float | None = Field(
+            default=None,
+            title="Temperature",
+            description="The temperature for the LLM output.",
+            ge=0,
+            lt=2,
+        )
+
+        top_p: float | None = Field(
+            default=None,
+            title="Top P",
+            description="The top P value for the LLM output.",
+            gt=0,
+            le=1,
+        )
+
+        top_k: int | None = Field(
+            default=None,
+            title="Top K",
+            description="The top K value for the LLM output.",
+            gt=0,
+            le=100,
+        )
+
+        parallel_tool_calls: bool = Field(
+            default=True,
+            title="Parallel Tool Calls",
+            description="If enable parallel tool calls for the LLM output.",
+        )
+
+        voice: str | None = Field(
+            default=None,
+            title="Voice",
+            description=(
+                "Voice for audio output on omni-style models (e.g. "
+                "``qwen3.5-omni-plus``). Setting this implicitly asks the "
+                "model to speak its response — ``modalities`` is filled in "
+                "automatically. Supported voices vary by model — see the "
+                "model card's ``voice.suggestions``. Any value the API "
+                "accepts works — the suggestions are convenience-only. "
+                "Leave unset for text-only "
+                "responses."
+            ),
+        )
+
+    type: Literal["dashscope_chat"] = "dashscope_chat"
+    """The type of the chat model."""
+
+    def __init__(
+        self,
+        credential: DashScopeCredential,
+        model: str,
+        parameters: "DashScopeChatModel.Parameters | None" = None,
+        stream: bool = True,
+        max_retries: int = 3,
+        retry_delay: float = 1.0,
+        context_size: int = 131072,
+        formatter: FormatterBase | None = None,
+        client_kwargs: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize the DashScope chat model.
+
+        Args:
+            credential (`DashScopeCredential`):
+                The DashScope credential used to authenticate API calls.
+            model (`str`):
+                The DashScope model name, e.g. ``qwen-plus``.
+            parameters (`DashScopeChatModel.Parameters | None`, defaults to \
+            `None`):
+                The DashScope API parameters. When ``None``, the default
+                parameters will be used.
+            stream (`bool`, defaults to `True`):
+                Whether to enable streaming output.
+            max_retries (`int`, defaults to `3`):
+                The maximum number of retries for the DashScope API.
+            retry_delay (`float`, defaults to `1.0`):
+                Seconds to sleep between retry attempts.
+            context_size (`int`, defaults to `131072`):
+                The model context size used for context compression.
+            formatter (`FormatterBase | None`, defaults to `None`):
+                The formatter that converts ``Msg`` objects to the format
+                required by the DashScope API. When ``None``, a
+                ``DashScopeChatFormatter`` instance will be used.
+            client_kwargs (`dict[str, Any] | None`, defaults to `None`):
+                Extra keyword arguments forwarded to ``openai.AsyncClient``
+                (e.g. ``timeout``, ``default_headers``, ``http_client``).
+        """
+        super().__init__(
+            credential=credential,
+            model=model,
+            parameters=parameters or self.Parameters(),
+            stream=stream,
+            max_retries=max_retries,
+            retry_delay=retry_delay,
+            context_size=context_size,
+        )
+        self.formatter = formatter or DashScopeChatFormatter()
+        self.client_kwargs = client_kwargs or {}
+
+    @classmethod
+    def _get_retryable_exceptions(cls) -> tuple[Type[Exception], ...]:
+        import openai
+
+        return (
+            openai.APIConnectionError,
+            openai.APITimeoutError,
+            openai.RateLimitError,
+            openai.InternalServerError,
+        )
+
+    async def _call_api(
+        self,
+        model_name: str,
+        messages: list[Msg],
+        tools: list[dict] | None = None,
+        tool_choice: ToolChoice | None = None,
+        **kwargs: Any,
+    ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:
+        """Call the DashScope chat completions API via OpenAI-compatible
+        endpoint.
+
+        Args:
+            model_name (`str`):
+                The model name to use for this call.
+            messages (`list`):
+                The Msg objects that will be formatted and sent to the API.
+            tools (`list[dict] | None`, default `None`):
+                The tools JSON schemas that the model can use.
+            tool_choice (`ToolChoice | None`, default `None`):
+                Controls which (if any) tool is called by the model.
+            **kwargs (`Any`):
+                The keyword arguments for DashScope chat completions API,
+                e.g. ``temperature``, ``max_tokens``, ``top_p``, etc.
+        """
+        import openai
+
+        client = openai.AsyncClient(
+            **{
+                "api_key": self.credential.api_key.get_secret_value(),
+                "base_url": self.credential.base_url,
+                **self.client_kwargs,
+            },
+        )
+
+        formatted_messages = await self.formatter.format(messages)
+
+        request_kwargs: dict[str, Any] = {
+            "model": model_name,
+            "messages": formatted_messages,
+            "stream": self.stream,
+        }
+
+        if self.parameters.max_tokens is not None:
+            request_kwargs["max_tokens"] = self.parameters.max_tokens
+
+        if self.parameters.temperature is not None:
+            request_kwargs["temperature"] = self.parameters.temperature
+
+        if self.parameters.top_p is not None:
+            request_kwargs["top_p"] = self.parameters.top_p
+
+        if self.parameters.voice is not None:
+            # Requesting audio output implies ``modalities`` must include
+            # ``"audio"``; set it automatically so callers don't have to.
+            # ``format`` is forced to ``pcm16``: omni streaming delivers raw
+            # PCM upstream regardless of the requested format, and we wrap
+            # it as WAV in ``_parse_stream_response`` before yielding.
+            request_kwargs["audio"] = {
+                "voice": self.parameters.voice,
+                "format": "pcm16",
+            }
+            request_kwargs["modalities"] = ["text", "audio"]
+
+        request_kwargs.update(kwargs)
+
+        fmt_tools, fmt_tool_choice = self._format_tools(tools, tool_choice)
+        if fmt_tools is not None:
+            request_kwargs["tools"] = fmt_tools
+            if not self.parameters.parallel_tool_calls:
+                request_kwargs["parallel_tool_calls"] = False
+        if fmt_tool_choice is not None:
+            request_kwargs["tool_choice"] = fmt_tool_choice
+
+        extra_body: dict[str, Any] = {}
+        if self.parameters.thinking_enable is not None:
+            extra_body["enable_thinking"] = self.parameters.thinking_enable
+        if self.parameters.thinking_budget is not None:
+            extra_body["thinking_budget"] = self.parameters.thinking_budget
+        if self.parameters.top_k is not None:
+            extra_body["top_k"] = self.parameters.top_k
+
+        if extra_body:
+            request_kwargs.setdefault("extra_body", {})
+            request_kwargs["extra_body"].update(extra_body)
+
+        if self.stream:
+            request_kwargs["stream_options"] = {"include_usage": True}
+
+        start_datetime = datetime.now()
+        response = await client.chat.completions.create(**request_kwargs)
+
+        if self.stream:
+            return self._parse_stream_response(start_datetime, response)
+
+        return self._parse_completion_response(start_datetime, response)
+
+    async def _parse_stream_response(
+        self,
+        start_datetime: datetime,
+        response: AsyncStream,
+    ) -> AsyncGenerator[ChatResponse, None]:
+        """Parse the DashScope streaming response (OpenAI-compatible format).
+
+        Args:
+            start_datetime (`datetime`):
+                The start datetime of the response generation.
+            response (`AsyncStream`):
+                The OpenAI-compatible async stream object.
+
+        Yields:
+            `ChatResponse`:
+                Incremental ``ChatResponse`` objects with ``is_last=False``
+                followed by a final one with ``is_last=True``.
+        """
+        # ``True`` once the first audio chunk has been prefixed with a
+        # streaming WAV header and yielded.
+        audio_header_sent: bool = False
+
+        usage = None
+        response_id: str = _generate_id()
+        text_id: str = _generate_id()
+        thinking_id: str = _generate_id()
+        audio_id = _generate_id()
+        # The mapping from index to tool call id
+        tool_call_mapping: dict = OrderedDict()
+
+        async with response as stream:
+            async for chunk in stream:
+                delta_res = ChatResponse(
+                    content=[],
+                    is_last=False,
+                    id=response_id,
+                )
+
+                # Update the response ID if exists
+                response_id = getattr(chunk, "id", None) or response_id
+                delta_res.id = response_id
+
+                if chunk.usage:
+                    u = chunk.usage
+                    ptd = getattr(u, "prompt_tokens_details", None)
+                    if ptd and hasattr(ptd, "cached_tokens"):
+                        cache_read = ptd.cached_tokens or 0
+                    else:
+                        cache_read = 0
+                    usage = ChatUsage(
+                        input_tokens=u.prompt_tokens or 0,
+                        output_tokens=u.completion_tokens or 0,
+                        time=(datetime.now() - start_datetime).total_seconds(),
+                        cache_input_tokens=cache_read,
+                    )
+
+                if not chunk.choices:
+                    if usage is not None:
+                        delta_res.usage = usage
+                        yield delta_res
+                    continue
+
+                choice = chunk.choices[0]
+                delta = choice.delta
+
+                # Thinking
+                if getattr(delta, "reasoning_content", None):
+                    delta_res.append_thinking(
+                        block_id=thinking_id,
+                        thinking=delta.reasoning_content,
+                    )
+
+                # Text
+                if getattr(delta, "content", None):
+                    delta_res.append_text(
+                        block_id=text_id,
+                        text=delta.content,
+                    )
+
+                # Tool call
+                for tool_call in getattr(delta, "tool_calls", None) or []:
+                    index = tool_call.index
+                    fn = getattr(tool_call, "function", None)
+                    delta_name = getattr(fn, "name", None) if fn else None
+                    delta_args = getattr(fn, "arguments", None) if fn else None
+
+                    # Record the id and name in case following deltas
+                    # don't provide them
+                    if index not in tool_call_mapping:
+                        tool_call_mapping[index] = (
+                            tool_call.id,
+                            delta_name or "unknown",
+                        )
+
+                    stored_id, stored_name = tool_call_mapping[index]
+
+                    delta_res.append_tool_call(
+                        block_id=tool_call.id or stored_id,
+                        name=delta_name or stored_name,
+                        input=delta_args or "",
+                    )
+
+                # Data block
+                if getattr(delta, "audio", None):
+                    delta_audio = getattr(delta, "audio", None)
+                    if isinstance(delta_audio, dict):
+                        audio_chunk = delta_audio.get("data", "")
+                    else:
+                        audio_chunk = getattr(delta_audio, "data", "")
+
+                    if audio_chunk:
+                        pcm_bytes = base64.b64decode(audio_chunk)
+                        if not audio_header_sent:
+                            payload = _build_streaming_wav_header() + pcm_bytes
+                            audio_header_sent = True
+                        else:
+                            payload = pcm_bytes
+                        # ``append_data_block`` expects the raw incremental
+                        # media bytes and handles base64 encoding internally
+                        # (see ``ChatResponse.append_data_block``); passing an
+                        # already base64-encoded string here would result in
+                        # double-encoding.
+                        delta_res.append_data_block(
+                            block_id=audio_id,
+                            data=payload,
+                            media_type="audio/wav",
+                        )
+
+                if delta_res.content or usage:
+                    delta_res.usage = usage
+                    yield delta_res
+
+    def _parse_completion_response(
+        self,
+        start_datetime: datetime,
+        response: ChatCompletion,
+    ) -> ChatResponse:
+        """Parse the DashScope non-streaming response (OpenAI-compatible
+        format).
+
+        Args:
+            start_datetime (`datetime`):
+                The start datetime of the response generation.
+            response (`ChatCompletion`):
+                The OpenAI-compatible chat completion object.
+
+        Returns:
+            `ChatResponse`:
+                A single ``ChatResponse`` with ``is_last=True``.
+        """
+        content_blocks: List[TextBlock | ToolCallBlock | ThinkingBlock] = []
+
+        if response.choices:
+            choice = response.choices[0]
+            reasoning = getattr(choice.message, "reasoning_content", None)
+            if isinstance(reasoning, str) and reasoning:
+                content_blocks.append(ThinkingBlock(thinking=reasoning))
+
+            if choice.message.content:
+                content_blocks.append(TextBlock(text=choice.message.content))
+
+            for tool_call in choice.message.tool_calls or []:
+                content_blocks.append(
+                    ToolCallBlock(
+                        id=tool_call.id,
+                        name=tool_call.function.name,
+                        input=tool_call.function.arguments,
+                    ),
+                )
+
+        usage = None
+        if response.usage:
+            u = response.usage
+            ptd = getattr(u, "prompt_tokens_details", None)
+            if ptd and hasattr(ptd, "cached_tokens"):
+                cache_read = ptd.cached_tokens or 0
+            else:
+                cache_read = 0
+            usage = ChatUsage(
+                input_tokens=u.prompt_tokens,
+                output_tokens=u.completion_tokens,
+                time=(datetime.now() - start_datetime).total_seconds(),
+                cache_input_tokens=cache_read,
+            )
+
+        resp_kwargs: dict[str, Any] = {
+            "content": content_blocks,
+            "is_last": True,
+            "usage": usage,
+        }
+        response_id = getattr(response, "id", None)
+        if response_id:
+            resp_kwargs["id"] = response_id
+
+        return ChatResponse(**resp_kwargs)
+
+    def _format_tools(
+        self,
+        tools: list[dict] | None,
+        tool_choice: ToolChoice | None,
+    ) -> tuple[list[dict] | None, str | dict | None]:
+        """Validate and format tools and tool_choice for DashScope.
+
+        DashScope supports "auto", "none", and "required" modes in
+        OpenAI-compatible format. When ``tool_choice.tools`` is specified
+        the schemas list is filtered to only those tools. When
+        ``tool_choice.mode`` is a specific tool name (str) the model is
+        forced to call exactly that tool.
+
+        Args:
+            tools (`list[dict] | None`, optional):
+                The raw tool schemas.
+            tool_choice (`ToolChoice | None`, optional):
+                The tool choice configuration.
+
+        Returns:
+            `tuple[list[dict] | None, str | dict | None]`:
+                A tuple of (formatted_tools, formatted_tool_choice).
+        """
+        if tool_choice and tools:
+            self._validate_tool_choice(tool_choice, tools)
+            if tool_choice.tools:
+                allowed = set(tool_choice.tools)
+                tools = [t for t in tools if t["function"]["name"] in allowed]
+
+        fmt_tools = None
+        if tools:
+            for value in tools:
+                if (
+                    not isinstance(value, dict)
+                    or "type" not in value
+                    or value["type"] != "function"
+                    or "function" not in value
+                ):
+                    raise ValueError(
+                        f"Each schema must be a dict with 'type' as "
+                        f"'function' and 'function' key, got {value}",
+                    )
+            fmt_tools = tools
+
+        if not tool_choice:
+            return fmt_tools, None
+
+        mode = tool_choice.mode
+
+        if mode not in _TOOL_CHOICE_LITERAL_MODES:
+            return fmt_tools, {
+                "type": "function",
+                "function": {"name": mode},
+            }
+
+        if mode == "required":
+            warnings.warn(
+                f"'{mode}' is not fully supported by DashScope API. "
+                "It will be converted to 'auto'.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            return fmt_tools, "auto"
+
+        return fmt_tools, mode
+
+    async def _call_api_with_structured_output(
+        self,
+        model_name: str,
+        messages: list[Msg],
+        structured_model: Type[BaseModel] | dict,
+        tool_choice: ToolChoice | None = None,
+        **kwargs: Any,
+    ) -> StructuredResponse:
+        """DashScope-specific override for structured output.
+
+        DashScope rejects ``tool_choice="required"`` or an object-form
+        ``tool_choice`` when thinking mode is enabled. In that case we
+        default ``tool_choice`` to ``"auto"`` and rely on the base class's
+        injected system-reminder prompt to guide the model. When thinking
+        is disabled, this falls through to the base implementation.
+
+        See: https://help.aliyun.com/en/model-studio/qwen-function-calling
+
+        Args:
+            model_name (`str`):
+                The model name to use for this call.
+            messages (`list[Msg]`):
+                The context for the LLM to generate the structured output.
+            structured_model (`Type[BaseModel] | dict`):
+                A Pydantic model class or a JSON schema dict describing the
+                required output structure.
+            tool_choice (`ToolChoice | None`, defaults to `None`):
+                The tool_choice forwarded to ``_call_api``. When ``None``
+                and thinking mode is enabled, it is downgraded to
+                ``ToolChoice(mode="auto")``; otherwise the base default
+                (force the structured-output tool) is used.
+            **kwargs (`Any`):
+                Additional keyword arguments forwarded to ``_call_api``.
+
+        Returns:
+            `StructuredResponse`:
+                The structured response whose ``content`` is the validated
+                output dict matching ``structured_model``.
+        """
+        if tool_choice is None and self.parameters.thinking_enable:
+            tool_choice = ToolChoice(mode="auto")
+        return await super()._call_api_with_structured_output(
+            model_name=model_name,
+            messages=messages,
+            structured_model=structured_model,
+            tool_choice=tool_choice,
+            **kwargs,
+        )
diff --git a/src/agentscope/model/_dashscope/_models/qwen-long.yaml b/src/agentscope/model/_dashscope/_models/qwen-long.yaml
new file mode 100644
index 0000000..56b7f34
--- /dev/null
+++ b/src/agentscope/model/_dashscope/_models/qwen-long.yaml
@@ -0,0 +1,21 @@
+name: qwen-long
+label: Qwen Long
+status: active
+
+input_types:
+  - text/plain
+
+output_types:
+  - text/plain
+
+context_size: 10000000
+output_size: 8192
+
+parameter_overrides:
+  max_tokens: {"maximum": 8192}
+  thinking_enable:
+    hidden: true
+  # Voice only applies to omni-style models; hide the field for this
+  # non-omni model so the frontend popover doesn't render it.
+  voice:
+    hidden: true
diff --git a/src/agentscope/model/_dashscope/_models/qwen-plus.yaml b/src/agentscope/model/_dashscope/_models/qwen-plus.yaml
new file mode 100644
index 0000000..ba5e41e
--- /dev/null
+++ b/src/agentscope/model/_dashscope/_models/qwen-plus.yaml
@@ -0,0 +1,20 @@
+name: qwen-plus
+label: Qwen Plus
+status: active
+
+input_types:
+  - text/plain
+
+output_types:
+  - text/plain
+  - application/x-thinking
+
+context_size: 1000000
+output_size: 16384
+
+parameter_overrides:
+  max_tokens: {"maximum": 16384}
+  # Voice only applies to omni-style models; hide the field for this
+  # non-omni model so the frontend popover doesn't render it.
+  voice:
+    hidden: true
diff --git a/src/agentscope/model/_dashscope/_models/qwen3.5-omni-plus.yaml b/src/agentscope/model/_dashscope/_models/qwen3.5-omni-plus.yaml
new file mode 100644
index 0000000..dcf3c8d
--- /dev/null
+++ b/src/agentscope/model/_dashscope/_models/qwen3.5-omni-plus.yaml
@@ -0,0 +1,38 @@
+name: qwen3.5-omni-plus
+label: Qwen3.5-Omni-Plus
+status: active
+
+input_types:
+  - text/plain
+  - image/bmp
+  - image/jpeg
+  - image/png
+  - image/tiff
+  - image/webp
+  - image/heic
+  - audio/mp3
+  - audio/wav
+  - audio/flac
+  - video/mp4
+
+output_types:
+  - text/plain
+  - application/x-thinking
+  - audio/wav
+
+context_size: 262144
+output_size: 65536
+
+parameter_overrides:
+  max_tokens:
+    maximum: 65536
+  # Source: https://help.aliyun.com/zh/model-studio/omni-voice-list
+  voice:
+    default: Tina
+    enum:
+      - Tina
+      - Cherry
+      - Ethan
+      - Serena
+      - Chelsie
+      - Cindy
diff --git a/src/agentscope/model/_dashscope/_models/qwen3.5-plus.yaml b/src/agentscope/model/_dashscope/_models/qwen3.5-plus.yaml
new file mode 100644
index 0000000..4682425
--- /dev/null
+++ b/src/agentscope/model/_dashscope/_models/qwen3.5-plus.yaml
@@ -0,0 +1,28 @@
+name: qwen3.5-plus
+label: Qwen3.5-Plus
+status: active
+
+input_types:
+  - text/plain
+  - application/x-thinking
+  - image/bmp
+  - image/jpeg
+  - image/png
+  - image/tiff
+  - image/webp
+  - image/heic
+  - video/mp4
+
+output_types:
+  - text/plain
+  - application/x-thinking
+
+context_size: 1000000
+output_size: 65536
+
+parameter_overrides:
+  max_tokens: {"maximum": 65536}
+  # Voice only applies to omni-style models; hide the field for this
+  # non-omni model so the frontend popover doesn't render it.
+  voice:
+    hidden: true
diff --git a/src/agentscope/model/_dashscope/_models/qwen3.6-max-preview.yaml b/src/agentscope/model/_dashscope/_models/qwen3.6-max-preview.yaml
new file mode 100644
index 0000000..501f5a3
--- /dev/null
+++ b/src/agentscope/model/_dashscope/_models/qwen3.6-max-preview.yaml
@@ -0,0 +1,20 @@
+name: qwen3.6-max-preview
+label: Qwen3.6-Max-Preview
+status: active
+
+input_types:
+  - text/plain
+
+output_types:
+  - text/plain
+  - application/x-thinking
+
+context_size: 240000
+output_size: 64000
+
+parameter_overrides:
+  max_tokens: {"maximum": 64000}
+  # Voice only applies to omni-style models; hide the field for this
+  # non-omni model so the frontend popover doesn't render it.
+  voice:
+    hidden: true
diff --git a/src/agentscope/model/_dashscope/_models/qwen3.6-plus.yaml b/src/agentscope/model/_dashscope/_models/qwen3.6-plus.yaml
new file mode 100644
index 0000000..3dbc919
--- /dev/null
+++ b/src/agentscope/model/_dashscope/_models/qwen3.6-plus.yaml
@@ -0,0 +1,28 @@
+name: qwen3.6-plus
+label: Qwen3.6-Plus
+status: active
+
+input_types:
+  - text/plain
+  - application/x-thinking
+  - image/bmp
+  - image/jpeg
+  - image/png
+  - image/tiff
+  - image/webp
+  - image/heic
+  - video/mp4
+
+output_types:
+  - text/plain
+  - application/x-thinking
+
+context_size: 1000000
+output_size: 65536
+
+parameter_overrides:
+  max_tokens: {"maximum": 65536}
+  # Voice only applies to omni-style models; hide the field for this
+  # non-omni model so the frontend popover doesn't render it.
+  voice:
+    hidden: true
diff --git a/src/agentscope/model/_dashscope/_models/qwen3.7-max.yaml b/src/agentscope/model/_dashscope/_models/qwen3.7-max.yaml
new file mode 100644
index 0000000..7b19aaa
--- /dev/null
+++ b/src/agentscope/model/_dashscope/_models/qwen3.7-max.yaml
@@ -0,0 +1,20 @@
+name: qwen3.7-max
+label: Qwen Max 3.7
+status: active
+
+input_types:
+  - text/plain
+
+output_types:
+  - text/plain
+  - application/x-thinking
+
+context_size: 1000000
+output_size: 65536
+
+parameter_overrides:
+  max_tokens: {"maximum": 65536}
+  # Voice only applies to omni-style models; hide the field for this
+  # non-omni model so the frontend popover doesn't render it.
+  voice:
+    hidden: true
diff --git a/src/agentscope/model/_deepseek/__init__.py b/src/agentscope/model/_deepseek/__init__.py
new file mode 100644
index 0000000..580146f
--- /dev/null
+++ b/src/agentscope/model/_deepseek/__init__.py
@@ -0,0 +1,9 @@
+# -*- coding: utf-8 -*-
+"""The DeepSeek LLM API modules."""
+
+from ._model import DeepSeekCredential, DeepSeekChatModel
+
+__all__ = [
+    "DeepSeekCredential",
+    "DeepSeekChatModel",
+]
diff --git a/src/agentscope/model/_deepseek/_model.py b/src/agentscope/model/_deepseek/_model.py
new file mode 100644
index 0000000..b04cd31
--- /dev/null
+++ b/src/agentscope/model/_deepseek/_model.py
@@ -0,0 +1,478 @@
+# -*- coding: utf-8 -*-
+"""The DeepSeek chat model implementation."""
+from collections import OrderedDict
+from datetime import datetime
+from typing import Literal, Any, AsyncGenerator, TYPE_CHECKING, List, Type
+
+from pydantic import BaseModel, Field
+
+from .._base import ChatModelBase, _TOOL_CHOICE_LITERAL_MODES
+from .._model_response import ChatResponse, StructuredResponse
+from .._model_usage import ChatUsage
+from ..._utils._common import _generate_id
+from ...credential import DeepSeekCredential
+from ...formatter import FormatterBase, DeepSeekChatFormatter
+from ...message import Msg, ThinkingBlock, ToolCallBlock, TextBlock
+from ...tool import ToolChoice
+
+if TYPE_CHECKING:
+    from openai.types.chat import ChatCompletion
+    from openai import AsyncStream
+else:
+    ChatCompletion = Any
+    AsyncStream = Any
+
+
+class DeepSeekChatModel(ChatModelBase):
+    """The DeepSeek chat model."""
+
+    class Parameters(BaseModel):
+        """The parameters for the DeepSeek chat model."""
+
+        max_tokens: int | None = Field(
+            default=None,
+            title="Max Tokens",
+            description="The maximum number of tokens for the LLM output.",
+            gt=0,
+        )
+
+        thinking_enable: bool = Field(
+            default=False,
+            title="Thinking",
+            description=(
+                "Whether to enable thinking mode. When enabled, the model "
+                "outputs a chain-of-thought reasoning before the final "
+                "answer via the reasoning_content field."
+            ),
+        )
+
+        reasoning_effort: Literal["high", "max"] | None = Field(
+            default=None,
+            title="Reasoning Effort",
+            description=(
+                "Controls the depth of reasoning in thinking mode. "
+                "Supported values: high (default), max. "
+                "For compatibility, low/medium map to high, "
+                "xhigh maps to max."
+            ),
+        )
+
+        temperature: float | None = Field(
+            default=None,
+            title="Temperature",
+            description="The temperature for the LLM output.",
+            ge=0,
+            le=2,
+        )
+
+        top_p: float | None = Field(
+            default=None,
+            title="Top P",
+            description="The top P value for the LLM output.",
+            gt=0,
+            le=1,
+        )
+
+    type: Literal["deepseek_chat"] = "deepseek_chat"
+    """The type of the chat model."""
+
+    def __init__(
+        self,
+        credential: DeepSeekCredential,
+        model: str,
+        parameters: "DeepSeekChatModel.Parameters | None" = None,
+        stream: bool = True,
+        max_retries: int = 3,
+        retry_delay: float = 1.0,
+        context_size: int = 65536,
+        formatter: FormatterBase | None = None,
+        client_kwargs: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize the DeepSeek chat model.
+
+        Args:
+            credential (`DeepSeekCredential`):
+                The DeepSeek credential used to authenticate API calls.
+            model (`str`):
+                The DeepSeek model name, e.g. ``deepseek-chat``.
+            parameters (`DeepSeekChatModel.Parameters | None`, defaults to \
+            `None`):
+                The DeepSeek API parameters. When ``None``, the default
+                parameters will be used.
+            stream (`bool`, defaults to `True`):
+                Whether to enable streaming output.
+            max_retries (`int`, defaults to `3`):
+                The maximum number of retries for the DeepSeek API.
+            retry_delay (`float`, defaults to `1.0`):
+                Seconds to sleep between retry attempts.
+            context_size (`int`, defaults to `65536`):
+                The model context size used for context compression.
+            formatter (`FormatterBase | None`, defaults to `None`):
+                The formatter that converts ``Msg`` objects to the format
+                required by the DeepSeek API. When ``None``, a
+                ``DeepSeekChatFormatter`` instance will be used.
+            client_kwargs (`dict[str, Any] | None`, defaults to `None`):
+                Extra keyword arguments forwarded to ``openai.AsyncClient``
+                (e.g. ``timeout``, ``default_headers``, ``http_client``).
+        """
+        super().__init__(
+            credential=credential,
+            model=model,
+            parameters=parameters or self.Parameters(),
+            stream=stream,
+            max_retries=max_retries,
+            retry_delay=retry_delay,
+            context_size=context_size,
+        )
+        self.formatter = formatter or DeepSeekChatFormatter()
+        self.client_kwargs = client_kwargs or {}
+
+    @classmethod
+    def _get_retryable_exceptions(cls) -> tuple[Type[Exception], ...]:
+        import openai
+
+        return (
+            openai.APIConnectionError,
+            openai.APITimeoutError,
+            openai.RateLimitError,
+            openai.InternalServerError,
+        )
+
+    async def _call_api(
+        self,
+        model_name: str,
+        messages: list[Msg],
+        tools: list[dict] | None = None,
+        tool_choice: ToolChoice | None = None,
+        **generate_kwargs: Any,
+    ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:
+        """Call the DeepSeek chat completions API.
+
+        Args:
+            model_name (`str`):
+                The model name to use for this call.
+            messages (`list`):
+                A list of message dicts with ``role`` and ``content`` keys.
+            tools (`list[dict]`, default `None`):
+                The tools JSON schemas.
+            tool_choice (`ToolChoice | None`, optional):
+                Controls which (if any) tool is called by the model.
+            **generate_kwargs (`Any`):
+                Extra keyword arguments forwarded to the API.
+
+        Returns:
+            `ChatResponse | AsyncGenerator[ChatResponse, None]`:
+                A ``ChatResponse`` when streaming is disabled, or an async
+                generator of ``ChatResponse`` objects when streaming is
+                enabled.
+        """
+        import openai
+
+        client = openai.AsyncClient(
+            **{
+                "api_key": self.credential.api_key.get_secret_value(),
+                "base_url": self.credential.base_url,
+                **self.client_kwargs,
+            },
+        )
+
+        formatted_messages = await self.formatter.format(messages)
+
+        kwargs: dict[str, Any] = {
+            "model": model_name,
+            "messages": formatted_messages,
+            "stream": self.stream,
+        }
+
+        if self.parameters.max_tokens is not None:
+            kwargs["max_tokens"] = self.parameters.max_tokens
+
+        if self.parameters.temperature is not None:
+            kwargs["temperature"] = self.parameters.temperature
+
+        if self.parameters.top_p is not None:
+            kwargs["top_p"] = self.parameters.top_p
+
+        if self.parameters.reasoning_effort is not None:
+            kwargs["reasoning_effort"] = self.parameters.reasoning_effort
+
+        kwargs.update(generate_kwargs)
+
+        thinking_type = (
+            "enabled" if self.parameters.thinking_enable else "disabled"
+        )
+        kwargs.setdefault("extra_body", {})
+        kwargs["extra_body"].setdefault("thinking", {})
+        kwargs["extra_body"]["thinking"].setdefault("type", thinking_type)
+
+        fmt_tools, fmt_tool_choice = self._format_tools(tools, tool_choice)
+
+        if fmt_tools:
+            kwargs["tools"] = fmt_tools
+
+        if fmt_tool_choice is not None:
+            kwargs["tool_choice"] = fmt_tool_choice
+
+        if self.stream:
+            kwargs["stream_options"] = {"include_usage": True}
+
+        start_datetime = datetime.now()
+        response = await client.chat.completions.create(**kwargs)
+
+        if self.stream:
+            return self._parse_stream_response(start_datetime, response)
+
+        return self._parse_completion_response(start_datetime, response)
+
+    async def _parse_stream_response(
+        self,
+        start_datetime: datetime,
+        response: AsyncStream,
+    ) -> AsyncGenerator[ChatResponse, None]:
+        """Parse the DeepSeek streaming response.
+
+        Args:
+            start_datetime (`datetime`):
+                The start datetime of the response generation.
+            response (`AsyncStream`):
+                The OpenAI-compatible async stream object.
+
+        Yields:
+            `ChatResponse`:
+                Incremental ``ChatResponse`` objects with ``is_last=False``
+                followed by a final one with ``is_last=True``.
+        """
+        usage = None
+        response_id: str = _generate_id()
+        text_id: str = _generate_id()
+        thinking_id: str = _generate_id()
+        # The mapping from index to tool call id
+        tool_call_mapping: dict = OrderedDict()
+
+        async with response as stream:
+            async for chunk in stream:
+                delta_res = ChatResponse(
+                    content=[],
+                    is_last=False,
+                    id=response_id,
+                )
+
+                # Update the response ID if exists
+                response_id = getattr(chunk, "id", None) or response_id
+                delta_res.id = response_id
+
+                if chunk.usage:
+                    u = chunk.usage
+                    usage = ChatUsage(
+                        input_tokens=u.prompt_tokens,
+                        output_tokens=u.completion_tokens,
+                        time=(datetime.now() - start_datetime).total_seconds(),
+                        cache_input_tokens=getattr(
+                            u,
+                            "prompt_cache_hit_tokens",
+                            0,
+                        ),
+                    )
+
+                if not chunk.choices:
+                    # DeepSeek emits a trailing usage-only chunk with no
+                    # choices; forward it as an empty-content delta so the
+                    # base class ``__call__`` can absorb ``usage`` into
+                    # ``acc_res``. The empty delta itself is filtered out
+                    # of the surfaced stream by ``_stream``.
+                    if usage is not None:
+                        delta_res.usage = usage
+                        yield delta_res
+                    continue
+
+                choice = chunk.choices[0]
+                delta = choice.delta
+
+                # Thinking block
+                if getattr(delta, "reasoning_content", None):
+                    delta_res.append_thinking(
+                        block_id=thinking_id,
+                        thinking=delta.reasoning_content,
+                    )
+
+                # Text
+                if getattr(delta, "content", None):
+                    delta_res.append_text(
+                        block_id=text_id,
+                        text=delta.content,
+                    )
+
+                # Tool call
+                for tool_call in getattr(delta, "tool_calls", None) or []:
+                    index = tool_call.index
+                    fn = getattr(tool_call, "function", None)
+                    delta_name = getattr(fn, "name", None) if fn else None
+                    delta_args = getattr(fn, "arguments", None) if fn else None
+
+                    # Record the id and name in case following deltas
+                    # don't provide them
+                    if index not in tool_call_mapping:
+                        tool_call_mapping[index] = (
+                            tool_call.id,
+                            delta_name or "unknown",
+                        )
+
+                    stored_id, stored_name = tool_call_mapping[index]
+
+                    delta_res.append_tool_call(
+                        block_id=tool_call.id or stored_id,
+                        name=delta_name or stored_name,
+                        input=delta_args or "",
+                    )
+
+                if delta_res.content or usage:
+                    delta_res.usage = usage
+                    yield delta_res
+
+    def _parse_completion_response(
+        self,
+        start_datetime: datetime,
+        response: ChatCompletion,
+    ) -> ChatResponse:
+        """Parse the DeepSeek non-streaming response.
+
+        Args:
+            start_datetime (`datetime`):
+                The start datetime of the response generation.
+            response (`ChatCompletion`):
+                The OpenAI-compatible chat completion object.
+
+        Returns:
+            `ChatResponse`:
+                A single ``ChatResponse`` with ``is_last=True``.
+        """
+        content_blocks: List[TextBlock | ToolCallBlock | ThinkingBlock] = []
+
+        if response.choices:
+            choice = response.choices[0]
+            reasoning = getattr(choice.message, "reasoning_content", None)
+            if isinstance(reasoning, str) and reasoning:
+                content_blocks.append(ThinkingBlock(thinking=reasoning))
+
+            if choice.message.content:
+                content_blocks.append(TextBlock(text=choice.message.content))
+
+            for tool_call in choice.message.tool_calls or []:
+                content_blocks.append(
+                    ToolCallBlock(
+                        id=tool_call.id,
+                        name=tool_call.function.name,
+                        input=tool_call.function.arguments,
+                    ),
+                )
+
+        usage = None
+        if response.usage:
+            u = response.usage
+            usage = ChatUsage(
+                input_tokens=u.prompt_tokens,
+                output_tokens=u.completion_tokens,
+                time=(datetime.now() - start_datetime).total_seconds(),
+                cache_input_tokens=getattr(
+                    u,
+                    "prompt_cache_hit_tokens",
+                    0,
+                ),
+            )
+
+        resp_kwargs: dict[str, Any] = {
+            "content": content_blocks,
+            "is_last": True,
+            "usage": usage,
+        }
+        response_id = getattr(response, "id", None)
+        if response_id:
+            resp_kwargs["id"] = response_id
+
+        return ChatResponse(**resp_kwargs)
+
+    def _format_tools(
+        self,
+        tools: list[dict] | None,
+        tool_choice: ToolChoice | None,
+    ) -> tuple[list[dict] | None, str | dict | None]:
+        """Validate, filter, and format tools and tool_choice for the DeepSeek
+        API.
+
+        When ``tool_choice.tools`` is specified the schemas list is filtered
+        to only those tools. When ``tool_choice.mode`` is a specific tool name
+        (str) the model is forced to call exactly that tool without needing to
+        filter the list, preserving prompt-cache efficiency.
+
+        Args:
+            tools (`list[dict] | None`, optional):
+                The raw tool schemas.
+            tool_choice (`ToolChoice | None`, optional):
+                The tool choice configuration.
+
+        Returns:
+            `tuple[list[dict] | None, str | dict | None]`:
+                A tuple of (formatted_tools, formatted_tool_choice).
+        """
+        if tool_choice and tools:
+            self._validate_tool_choice(tool_choice, tools)
+            if tool_choice.tools:
+                allowed = set(tool_choice.tools)
+                tools = [t for t in tools if t["function"]["name"] in allowed]
+
+        if not tool_choice:
+            return tools, None
+
+        mode = tool_choice.mode
+
+        if mode not in _TOOL_CHOICE_LITERAL_MODES:
+            return tools, {"type": "function", "function": {"name": mode}}
+
+        return tools, mode
+
+    async def _call_api_with_structured_output(
+        self,
+        model_name: str,
+        messages: list[Msg],
+        structured_model: Type[BaseModel] | dict,
+        tool_choice: ToolChoice | None = None,
+        **kwargs: Any,
+    ) -> StructuredResponse:
+        """DeepSeek-specific override for structured output.
+
+        DeepSeek rejects ``tool_choice="required"`` or an object-form
+        ``tool_choice`` when thinking mode is enabled. In that case we
+        default ``tool_choice`` to ``"auto"`` and rely on the base class's
+        injected system-reminder prompt to guide the model. When thinking
+        is disabled, this falls through to the base implementation.
+
+        Args:
+            model_name (`str`):
+                The model name to use for this call.
+            messages (`list[Msg]`):
+                The context for the LLM to generate the structured output.
+            structured_model (`Type[BaseModel] | dict`):
+                A Pydantic model class or a JSON schema dict describing the
+                required output structure.
+            tool_choice (`ToolChoice | None`, defaults to `None`):
+                The tool_choice forwarded to ``_call_api``. When ``None``
+                and thinking mode is enabled, it is downgraded to
+                ``ToolChoice(mode="auto")``; otherwise the base default
+                (force the structured-output tool) is used.
+            **kwargs (`Any`):
+                Additional keyword arguments forwarded to ``_call_api``.
+
+        Returns:
+            `StructuredResponse`:
+                The structured response whose ``content`` is the validated
+                output dict matching ``structured_model``.
+        """
+        if tool_choice is None and self.parameters.thinking_enable:
+            tool_choice = ToolChoice(mode="auto")
+        return await super()._call_api_with_structured_output(
+            model_name=model_name,
+            messages=messages,
+            structured_model=structured_model,
+            tool_choice=tool_choice,
+            **kwargs,
+        )
diff --git a/src/agentscope/model/_deepseek/_models/deepseek-chat.yaml b/src/agentscope/model/_deepseek/_models/deepseek-chat.yaml
new file mode 100644
index 0000000..36adf5c
--- /dev/null
+++ b/src/agentscope/model/_deepseek/_models/deepseek-chat.yaml
@@ -0,0 +1,17 @@
+name: deepseek-chat
+label: DeepSeek Chat
+status: sunset
+deprecated_at: "2026-07-24T00:00:00"
+
+input_types:
+  - text/plain
+
+output_types:
+  - text/plain
+
+context_size: 1000000
+output_size: 384000
+
+parameter_overrides:
+  max_tokens:
+    maximum: 384000
diff --git a/src/agentscope/model/_deepseek/_models/deepseek-reasoner.yaml b/src/agentscope/model/_deepseek/_models/deepseek-reasoner.yaml
new file mode 100644
index 0000000..8c0b010
--- /dev/null
+++ b/src/agentscope/model/_deepseek/_models/deepseek-reasoner.yaml
@@ -0,0 +1,18 @@
+name: deepseek-reasoner
+label: DeepSeek Reasoner
+status: sunset
+deprecated_at: "2026-07-24T00:00:00"
+
+input_types:
+  - text/plain
+
+output_types:
+  - text/plain
+  - application/x-thinking
+
+context_size: 1000000
+output_size: 384000
+
+parameter_overrides:
+  max_tokens:
+    maximum: 384000
diff --git a/src/agentscope/model/_deepseek/_models/deepseek-v4-flash.yaml b/src/agentscope/model/_deepseek/_models/deepseek-v4-flash.yaml
new file mode 100644
index 0000000..fed1a83
--- /dev/null
+++ b/src/agentscope/model/_deepseek/_models/deepseek-v4-flash.yaml
@@ -0,0 +1,18 @@
+name: deepseek-v4-flash
+label: DeepSeek V4 Flash
+status: active
+
+input_types:
+  - text/plain
+  - application/x-thinking
+
+output_types:
+  - text/plain
+  - application/x-thinking
+
+context_size: 1000000
+output_size: 384000
+
+parameter_overrides:
+  max_tokens:
+    maximum: 384000
diff --git a/src/agentscope/model/_deepseek/_models/deepseek-v4-pro.yaml b/src/agentscope/model/_deepseek/_models/deepseek-v4-pro.yaml
new file mode 100644
index 0000000..ffb1a2e
--- /dev/null
+++ b/src/agentscope/model/_deepseek/_models/deepseek-v4-pro.yaml
@@ -0,0 +1,18 @@
+name: deepseek-v4-pro
+label: DeepSeek V4 Pro
+status: active
+
+input_types:
+  - text/plain
+  - application/x-thinking
+
+output_types:
+  - text/plain
+  - application/x-thinking
+
+context_size: 1000000
+output_size: 384000
+
+parameter_overrides:
+  max_tokens:
+    maximum: 384000
diff --git a/src/agentscope/model/_gemini/__init__.py b/src/agentscope/model/_gemini/__init__.py
new file mode 100644
index 0000000..66afd74
--- /dev/null
+++ b/src/agentscope/model/_gemini/__init__.py
@@ -0,0 +1,9 @@
+# -*- coding: utf-8 -*-
+"""The Google Gemini LLM API modules."""
+
+from ._model import GeminiCredential, GeminiChatModel
+
+__all__ = [
+    "GeminiCredential",
+    "GeminiChatModel",
+]
diff --git a/src/agentscope/model/_gemini/_model.py b/src/agentscope/model/_gemini/_model.py
new file mode 100644
index 0000000..2df8718
--- /dev/null
+++ b/src/agentscope/model/_gemini/_model.py
@@ -0,0 +1,560 @@
+# -*- coding: utf-8 -*-
+"""The Google Gemini chat model implementation."""
+import base64
+import json
+from datetime import datetime
+from typing import Literal, Any, AsyncGenerator, TYPE_CHECKING, List, Type
+
+from pydantic import BaseModel, Field
+
+from ..._utils._common import _generate_id, _flatten_json_schema
+from .._base import ChatModelBase, _TOOL_CHOICE_LITERAL_MODES
+from .._model_response import ChatResponse
+from .._model_usage import ChatUsage
+from ...credential import GeminiCredential
+from ...formatter import FormatterBase, GeminiChatFormatter
+from ...message import Msg, ThinkingBlock, ToolCallBlock, TextBlock
+from ...tool import ToolChoice
+
+if TYPE_CHECKING:
+    from google.genai.types import GenerateContentResponse
+else:
+    GenerateContentResponse = Any
+
+
+def _sanitize_schema_for_gemini(schema: Any) -> Any:
+    """Sanitize a JSON schema to be compatible with the Gemini API.
+
+    Gemini API does not support certain JSON Schema constructs. This
+    function removes or rewrites the following:
+
+    - ``additionalProperties``: removed entirely.
+    - ``const``: converted to an equivalent single-value ``enum``,
+      since Gemini's ``Schema`` model does not support ``const``.
+    - ``anyOf`` containing a ``{"type": "null"}`` entry: simplified to
+      the single non-null type. If there is exactly one non-null
+      alternative it is inlined directly; otherwise the ``anyOf`` is
+      kept but the null entry is dropped.
+    - All nested sub-schemas (``properties``, ``items``, ``$defs``,
+      etc.) are processed recursively.
+
+    Args:
+        schema (`Any`):
+            The JSON schema to sanitize. Non-dict values are returned
+            unchanged; lists are recursively sanitized element-wise.
+
+    Returns:
+        `Any`:
+            A sanitized copy of the schema, or the original value if it
+            is not a dict or list.
+    """
+    if not isinstance(schema, dict):
+        if isinstance(schema, list):
+            return [_sanitize_schema_for_gemini(v) for v in schema]
+        return schema
+
+    schema = dict(schema)
+
+    # Gemini (and many third-party proxies) reject `null` as a standalone
+    # functionDeclaration property type. Some MCP servers emit
+    # {"type": "null"} directly (not wrapped in anyOf) for parameters that
+    # accept None — rewrite it to "object" so it round-trips through the API.
+    if schema.get("type") == "null":
+        schema["type"] = "object"
+
+    # Remove additionalProperties — not supported by Gemini
+    schema.pop("additionalProperties", None)
+
+    # Convert `const` into an equivalent single-value `enum` — Gemini's
+    # Schema model does not support the `const` keyword.
+    if "const" in schema:
+        const_value = schema.pop("const")
+        schema.setdefault("enum", [const_value])
+
+    # Simplify anyOf that only differs by a null type, e.g. Optional[X]
+    if "anyOf" in schema and isinstance(schema["anyOf"], list):
+        any_of = schema["anyOf"]
+        non_null = [v for v in any_of if v != {"type": "null"}]
+        if len(non_null) < len(any_of):  # at least one null entry removed
+            if len(non_null) == 1:
+                # Inline the single non-null type, preserving outer keys
+                merged = dict(_sanitize_schema_for_gemini(non_null[0]))
+                for k, v in schema.items():
+                    if k != "anyOf":
+                        merged.setdefault(k, v)
+                return merged
+            elif non_null:
+                schema["anyOf"] = [
+                    _sanitize_schema_for_gemini(v) for v in non_null
+                ]
+            else:
+                del schema["anyOf"]
+
+    # Recursively process nested object schemas
+    for key in ["properties", "patternProperties", "$defs"]:
+        if key in schema and isinstance(schema[key], dict):
+            schema[key] = {
+                k: _sanitize_schema_for_gemini(v)
+                for k, v in schema[key].items()
+            }
+
+    for key in ["items", "not", "if", "then", "else"]:
+        if key in schema:
+            schema[key] = _sanitize_schema_for_gemini(schema[key])
+
+    for key in ["allOf", "oneOf", "anyOf"]:
+        if key in schema and isinstance(schema[key], list):
+            schema[key] = [_sanitize_schema_for_gemini(v) for v in schema[key]]
+
+    return schema
+
+
+class GeminiChatModel(ChatModelBase):
+    """The Google Gemini chat model."""
+
+    class Parameters(BaseModel):
+        """The parameters for the Gemini chat model."""
+
+        max_tokens: int | None = Field(
+            default=None,
+            title="Max Tokens",
+            description="The maximum number of tokens for the LLM output.",
+            gt=0,
+        )
+
+        thinking_enable: bool = Field(
+            default=False,
+            title="Thinking",
+            description="Whether to enable thinking output.",
+        )
+
+        thinking_budget: int | None = Field(
+            default=None,
+            title="Thinking Budget",
+            description="The thinking budget in tokens.",
+            gt=0,
+        )
+
+        temperature: float | None = Field(
+            default=None,
+            title="Temperature",
+            description="The temperature for the LLM output.",
+            ge=0,
+            le=2,
+        )
+
+        top_p: float | None = Field(
+            default=None,
+            title="Top P",
+            description="The top P value for the LLM output.",
+            gt=0,
+            le=1,
+        )
+
+    type: Literal["gemini_chat"] = "gemini_chat"
+    """The type of the chat model."""
+
+    def __init__(
+        self,
+        credential: GeminiCredential,
+        model: str,
+        parameters: "GeminiChatModel.Parameters | None" = None,
+        stream: bool = True,
+        max_retries: int = 3,
+        retry_delay: float = 1.0,
+        context_size: int = 1048576,
+        formatter: FormatterBase | None = None,
+        client_kwargs: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize the Gemini chat model.
+
+        Args:
+            credential (`GeminiCredential`):
+                The Google Gemini credential used to authenticate API calls.
+            model (`str`):
+                The Gemini model name, e.g. ``gemini-2.0-flash-exp``.
+            parameters (`GeminiChatModel.Parameters | None`, defaults to \
+            `None`):
+                The Gemini API parameters. When ``None``, the default
+                parameters will be used.
+            stream (`bool`, defaults to `True`):
+                Whether to enable streaming output.
+            max_retries (`int`, defaults to `3`):
+                The maximum number of retries for the Gemini API.
+            retry_delay (`float`, defaults to `1.0`):
+                Seconds to sleep between retry attempts.
+            context_size (`int`, defaults to `1048576`):
+                The model context size used for context compression.
+            formatter (`FormatterBase | None`, defaults to `None`):
+                The formatter that converts ``Msg`` objects to the format
+                required by the Gemini API. When ``None``, a
+                ``GeminiChatFormatter`` instance will be used.
+            client_kwargs (`dict[str, Any] | None`, defaults to `None`):
+                Extra keyword arguments forwarded to ``google.genai.Client``
+                (e.g. ``vertexai``, ``project``, ``location``,
+                ``credentials``, ``http_options``).
+        """
+        super().__init__(
+            credential=credential,
+            model=model,
+            parameters=parameters or self.Parameters(),
+            stream=stream,
+            max_retries=max_retries,
+            retry_delay=retry_delay,
+            context_size=context_size,
+        )
+        self.formatter = formatter or GeminiChatFormatter()
+        self.client_kwargs = client_kwargs or {}
+
+    @classmethod
+    def _get_retryable_exceptions(cls) -> tuple[Type[Exception], ...]:
+        from google.genai import errors
+
+        # APIError is the common parent of ClientError (4xx) and ServerError
+        # (5xx). The google-genai SDK does not expose a dedicated rate-limit
+        # subclass, and 429 surfaces as ClientError — so we accept the wider
+        # set to make sure 429s are retried, at the cost of also retrying
+        # rare 4xx like auth/bad-request a few times.
+        return (errors.APIError,)
+
+    async def _call_api(
+        self,
+        model_name: str,
+        messages: list[Msg],
+        tools: list[dict] | None = None,
+        tool_choice: ToolChoice | None = None,
+        **config_kwargs: Any,
+    ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:
+        """Call the Gemini chat API.
+
+        Args:
+            model_name (`str`):
+                The model name to use for this call.
+            messages (`list`):
+                A list of message objects for Gemini API.
+            tools (`list[dict]`, default `None`):
+                The tools JSON schemas.
+            tool_choice (`ToolChoice | None`, optional):
+                Controls which (if any) tool is called by the model.
+            **config_kwargs (`Any`):
+                Extra keyword arguments for the Gemini config.
+
+        Returns:
+            `ChatResponse | AsyncGenerator[ChatResponse, None]`:
+                A ``ChatResponse`` when streaming is disabled, or an async
+                generator of ``ChatResponse`` objects when streaming is
+                enabled.
+        """
+        from google import genai
+
+        client = genai.Client(
+            **{
+                "api_key": self.credential.api_key.get_secret_value(),
+                **self.client_kwargs,
+            },
+        )
+
+        formatted_messages = await self.formatter.format(messages)
+
+        config: dict[str, Any] = {**config_kwargs}
+
+        if self.parameters.max_tokens is not None:
+            config["max_output_tokens"] = self.parameters.max_tokens
+
+        if self.parameters.temperature is not None:
+            config["temperature"] = self.parameters.temperature
+
+        if self.parameters.top_p is not None:
+            config["top_p"] = self.parameters.top_p
+
+        if self.parameters.thinking_enable:
+            config["thinking_config"] = {
+                "include_thoughts": True,
+                "thinking_budget": self.parameters.thinking_budget or 1024,
+            }
+        else:
+            config["thinking_config"] = {
+                "include_thoughts": False,
+                "thinking_budget": 0,
+            }
+
+        fmt_tools, fmt_tool_choice = self._format_tools(tools, tool_choice)
+
+        if fmt_tools is not None:
+            config["tools"] = fmt_tools
+
+        if fmt_tool_choice is not None:
+            config["tool_config"] = fmt_tool_choice
+
+        kwargs: dict[str, Any] = {
+            "model": model_name,
+            "contents": formatted_messages,
+            "config": config,
+        }
+
+        start_datetime = datetime.now()
+
+        if self.stream:
+            response = await client.aio.models.generate_content_stream(
+                **kwargs,
+            )
+            # Pass client to the generator so the aiohttp session it owns
+            # stays alive until the stream is fully consumed.
+            return self._parse_stream_response(
+                start_datetime,
+                response,
+                client,
+            )
+
+        response = await client.aio.models.generate_content(**kwargs)
+        return self._parse_completion_response(start_datetime, response)
+
+    async def _parse_stream_response(
+        self,
+        start_datetime: datetime,
+        response: Any,
+        _client: Any = None,
+    ) -> AsyncGenerator[ChatResponse, None]:
+        """Parse the Gemini streaming response.
+
+        Args:
+            start_datetime (`datetime`):
+                The start datetime of the response generation.
+            response (`Any`):
+                The Gemini async stream object from
+                ``client.aio.models.generate_content_stream``.
+            _client (`Any`, optional):
+                The ``genai.Client`` that produced the stream. Held here so
+                its aiohttp session is not garbage-collected before the
+                stream is fully consumed.
+
+        Yields:
+            `ChatResponse`:
+                Incremental ``ChatResponse`` objects with ``is_last=False``
+                followed by a final one with ``is_last=True``.
+        """
+
+        response_id: str = _generate_id()
+        text_id: str = _generate_id()
+        thinking_id: str = _generate_id()
+
+        async for chunk in response:
+            # Capture response_id from the first chunk that carries it
+            delta_res = ChatResponse(
+                content=[],
+                is_last=False,
+                id=response_id,
+            )
+
+            # Update the response ID if exists
+            response_id = getattr(chunk, "response_id", None) or response_id
+            delta_res.id = response_id
+
+            if (
+                chunk.candidates
+                and chunk.candidates[0].content
+                and chunk.candidates[0].content.parts
+            ):
+                for part in chunk.candidates[0].content.parts:
+                    if part.text:
+                        # Thinking
+                        if part.thought:
+                            delta_res.append_thinking(
+                                block_id=thinking_id,
+                                thinking=part.text,
+                            )
+
+                        # Text
+                        else:
+                            delta_res.append_text(
+                                block_id=text_id,
+                                text=part.text,
+                            )
+
+                    # Tool call
+                    if part.function_call:
+                        if part.thought_signature:
+                            call_id = base64.b64encode(
+                                part.thought_signature,
+                            ).decode("utf-8")
+                        else:
+                            call_id = part.function_call.id or _generate_id()
+
+                        delta_res.append_tool_call(
+                            block_id=call_id,
+                            name=part.function_call.name,
+                            input=json.dumps(
+                                part.function_call.args or {},
+                                ensure_ascii=False,
+                            ),
+                        )
+
+            usage = self._extract_usage(chunk.usage_metadata, start_datetime)
+
+            if delta_res.content or usage:
+                delta_res.usage = usage
+                yield delta_res
+
+    def _parse_completion_response(
+        self,
+        start_datetime: datetime,
+        response: GenerateContentResponse,
+    ) -> ChatResponse:
+        """Parse the Gemini non-streaming response.
+
+        Args:
+            start_datetime (`datetime`):
+                The start datetime of the response generation.
+            response (`GenerateContentResponse`):
+                The Gemini generate content response object.
+
+        Returns:
+            `ChatResponse`:
+                A single ``ChatResponse`` with ``is_last=True``.
+        """
+        content_blocks: List[TextBlock | ToolCallBlock | ThinkingBlock] = []
+
+        if (
+            response.candidates
+            and response.candidates[0].content
+            and response.candidates[0].content.parts
+        ):
+            for part in response.candidates[0].content.parts:
+                if part.text:
+                    if part.thought:
+                        content_blocks.append(
+                            ThinkingBlock(thinking=part.text),
+                        )
+                    else:
+                        content_blocks.append(TextBlock(text=part.text))
+
+                if part.function_call:
+                    keyword_args = part.function_call.args or {}
+                    if part.thought_signature:
+                        call_id = base64.b64encode(
+                            part.thought_signature,
+                        ).decode("utf-8")
+                    else:
+                        call_id = part.function_call.id or _generate_id()
+                    content_blocks.append(
+                        ToolCallBlock(
+                            id=call_id,
+                            name=part.function_call.name,
+                            input=json.dumps(keyword_args, ensure_ascii=False),
+                        ),
+                    )
+
+        usage = self._extract_usage(response.usage_metadata, start_datetime)
+
+        return ChatResponse(
+            id=getattr(response, "response_id", None) or _generate_id(),
+            content=content_blocks,
+            is_last=True,
+            usage=usage,
+        )
+
+    def _extract_usage(
+        self,
+        usage_metadata: Any,
+        start_datetime: datetime,
+    ) -> ChatUsage | None:
+        """Extract ChatUsage from usage_metadata.
+
+        Args:
+            usage_metadata (`Any`):
+                The usage metadata object from a Gemini response.
+            start_datetime (`datetime`):
+                The start datetime of the response generation.
+
+        Returns:
+            `ChatUsage | None`:
+                A ``ChatUsage`` object if usage data is available, otherwise
+                ``None``.
+        """
+        if not usage_metadata:
+            return None
+        prompt_tokens = usage_metadata.prompt_token_count
+        total_tokens = usage_metadata.total_token_count
+        if prompt_tokens is not None and total_tokens is not None:
+            return ChatUsage(
+                input_tokens=prompt_tokens,
+                output_tokens=total_tokens - prompt_tokens,
+                time=(datetime.now() - start_datetime).total_seconds(),
+                cache_input_tokens=getattr(
+                    usage_metadata,
+                    "cached_content_token_count",
+                    0,
+                ),
+            )
+        return None
+
+    def _format_tools(
+        self,
+        tools: list[dict] | None,
+        tool_choice: ToolChoice | None,
+    ) -> tuple[list[dict] | None, dict | None]:
+        """Validate and format tools and tool_choice for Gemini.
+
+        Converts tool schemas to Gemini's ``function_declarations``
+        format (resolving ``$ref`` references) and maps tool_choice
+        modes to Gemini's ``function_calling_config``. When
+        ``tool_choice.tools`` is specified the schemas list is filtered
+        to only those tools. When ``tool_choice.mode`` is a specific
+        tool name (str) the model is restricted via
+        ``allowed_function_names`` without needing to filter the list,
+        preserving prompt-cache efficiency.
+
+        Args:
+            tools (`list[dict] | None`, optional):
+                The raw tool schemas.
+            tool_choice (`ToolChoice | None`, optional):
+                The tool choice configuration.
+
+        Returns:
+            `tuple[list[dict] | None, dict | None]`:
+                A tuple of (formatted_tools, formatted_tool_config).
+        """
+        if tool_choice and tools:
+            self._validate_tool_choice(tool_choice, tools)
+            if tool_choice.tools:
+                allowed = set(tool_choice.tools)
+                tools = [t for t in tools if t["function"]["name"] in allowed]
+
+        fmt_tools = None
+        if tools:
+            function_declarations = []
+            for schema in tools:
+                if "function" not in schema:
+                    continue
+                func = schema["function"].copy()
+                if "parameters" in func:
+                    func["parameters"] = _sanitize_schema_for_gemini(
+                        _flatten_json_schema(func["parameters"]),
+                    )
+                function_declarations.append(func)
+            fmt_tools = [{"function_declarations": function_declarations}]
+
+        if not tool_choice:
+            return fmt_tools, None
+
+        mode = tool_choice.mode
+
+        if mode not in _TOOL_CHOICE_LITERAL_MODES:
+            # mode is a specific tool name — restrict to that single tool
+            fmt_choice: dict = {
+                "function_calling_config": {
+                    "mode": "ANY",
+                    "allowed_function_names": [mode],
+                },
+            }
+            return fmt_tools, fmt_choice
+
+        mode_mapping = {
+            "auto": "AUTO",
+            "none": "NONE",
+            "required": "ANY",
+        }
+        fmt_choice = {
+            "function_calling_config": {"mode": mode_mapping[mode]},
+        }
+        return fmt_tools, fmt_choice
diff --git a/src/agentscope/model/_gemini/_models/gemini-2.5-flash.yaml b/src/agentscope/model/_gemini/_models/gemini-2.5-flash.yaml
new file mode 100644
index 0000000..9e1b902
--- /dev/null
+++ b/src/agentscope/model/_gemini/_models/gemini-2.5-flash.yaml
@@ -0,0 +1,25 @@
+name: gemini-2.5-flash
+label: Gemini 2.5 Flash
+status: active
+
+input_types:
+  - text/plain
+  - application/x-thinking
+  - image/jpeg
+  - image/png
+  - image/gif
+  - image/webp
+  - audio/mp3
+  - audio/wav
+  - video/mp4
+
+output_types:
+  - text/plain
+  - application/x-thinking
+
+context_size: 1048576
+output_size: 65536
+
+parameter_overrides:
+  max_tokens:
+    maximum: 65536
diff --git a/src/agentscope/model/_gemini/_models/gemini-2.5-pro.yaml b/src/agentscope/model/_gemini/_models/gemini-2.5-pro.yaml
new file mode 100644
index 0000000..6b975fe
--- /dev/null
+++ b/src/agentscope/model/_gemini/_models/gemini-2.5-pro.yaml
@@ -0,0 +1,25 @@
+name: gemini-2.5-pro
+label: Gemini 2.5 Pro
+status: active
+
+input_types:
+  - text/plain
+  - application/x-thinking
+  - image/jpeg
+  - image/png
+  - image/gif
+  - image/webp
+  - audio/mp3
+  - audio/wav
+  - video/mp4
+
+output_types:
+  - text/plain
+  - application/x-thinking
+
+context_size: 1048576
+output_size: 65536
+
+parameter_overrides:
+  max_tokens:
+    maximum: 65536
diff --git a/src/agentscope/model/_gemini/_models/gemini-3-flash-preview.yaml b/src/agentscope/model/_gemini/_models/gemini-3-flash-preview.yaml
new file mode 100644
index 0000000..954f462
--- /dev/null
+++ b/src/agentscope/model/_gemini/_models/gemini-3-flash-preview.yaml
@@ -0,0 +1,25 @@
+name: gemini-3-flash-preview
+label: Gemini 3 Flash Preview
+status: active
+
+input_types:
+  - text/plain
+  - image/jpeg
+  - image/png
+  - image/gif
+  - image/webp
+  - audio/mp3
+  - audio/wav
+  - video/mp4
+  - application/pdf
+
+output_types:
+  - text/plain
+  - application/x-thinking
+
+context_size: 1048576
+output_size: 65536
+
+parameter_overrides:
+  max_tokens:
+    maximum: 65536
diff --git a/src/agentscope/model/_gemini/_models/gemini-3.1-pro-preview.yaml b/src/agentscope/model/_gemini/_models/gemini-3.1-pro-preview.yaml
new file mode 100644
index 0000000..4040646
--- /dev/null
+++ b/src/agentscope/model/_gemini/_models/gemini-3.1-pro-preview.yaml
@@ -0,0 +1,25 @@
+name: gemini-3.1-pro-preview
+label: Gemini 3.1 Pro Preview
+status: active
+
+input_types:
+  - text/plain
+  - image/jpeg
+  - image/png
+  - image/gif
+  - image/webp
+  - audio/mp3
+  - audio/wav
+  - video/mp4
+  - application/pdf
+
+output_types:
+  - text/plain
+  - application/x-thinking
+
+context_size: 1048576
+output_size: 65536
+
+parameter_overrides:
+  max_tokens:
+    maximum: 65536
diff --git a/src/agentscope/model/_model_card.py b/src/agentscope/model/_model_card.py
new file mode 100644
index 0000000..c5795ec
--- /dev/null
+++ b/src/agentscope/model/_model_card.py
@@ -0,0 +1,159 @@
+# -*- coding: utf-8 -*-
+"""The model card class."""
+import copy
+from datetime import datetime
+from typing import Literal, Self, Type
+
+import yaml
+from pydantic import BaseModel, Field
+
+
+class ModelCard(BaseModel):
+    """The model card class."""
+
+    type: Literal["chat_model"] = "chat_model"
+    """The model card type."""
+
+    name: str = Field(description="The name of the model")
+    """The model name."""
+
+    label: str = Field(description="The model label.")
+    """The model label used for frontend rendering."""
+
+    status: Literal["active", "deprecated", "sunset"] = Field(
+        title="Status",
+        description="The model status",
+    )
+    """The model status."""
+
+    deprecated_at: datetime | None = Field(
+        default=None,
+        description="The model deprecation date and time.",
+        title="Deprecation date",
+    )
+    """The model deprecated at."""
+
+    input_types: list[str] = Field(
+        description="The supported model input types.",
+        title="Input types",
+        default=["text/plain"],
+    )
+    """The model supported input types."""
+
+    output_types: list[str] = Field(
+        description="The supported model output types.",
+        title="Output types",
+        default=["text/plain"],
+    )
+    """The model supported output types."""
+
+    context_size: int = Field(
+        title="Context size",
+        description="The context size.",
+        gt=0,
+    )
+    """The model context size."""
+
+    output_size: int = Field(
+        title="Max output tokens",
+        description="The maximum number of tokens.",
+        gt=0,
+    )
+    """The model max output tokens."""
+
+    parameter_schema: dict
+    """The parameters schema, which will be combined with the schema from the
+    DashScopeChatParameter class."""
+
+    parameters_overrides: dict[str, dict]
+    """The parameter overrides, which will be merged into the parameter schema.
+    """
+
+    @classmethod
+    def from_yaml(
+        cls,
+        yaml_path: str,
+        parameter_class: Type[BaseModel],
+    ) -> Self:
+        """Read a model card from a YAML file, and merge the parameter schema
+        with the override parameter schema in the yaml file.
+
+        Args:
+            yaml_path (`str`):
+                Path to the YAML file
+            parameter_class (`Type[BaseModel]`):
+                The parameter class (e.g., DashScopeChatParameters)
+
+        Returns:
+            `list[ModelCard]`:
+                ModelCard instance with merged parameter schema
+        """
+
+        # Load YAML config
+        with open(yaml_path, "r", encoding="utf-8") as file:
+            config = yaml.safe_load(file)
+
+        # Get base schema from parameter class
+        base_schema = parameter_class.model_json_schema()
+        properties = copy.deepcopy(base_schema.get("properties", {}))
+
+        # Auto-filter: remove thinking parameters if not supported
+        output_types = config.get("output_types", [])
+        if "application/x-thinking" not in output_types:
+            properties.pop("thinking_enable", None)
+            properties.pop("thinking_budget", None)
+
+        # Auto-filter: only omni-style models that declare an ``audio/*``
+        # output type expose the ``voice`` parameter to the frontend
+        # popover. Defense in depth — a model yaml can also drop ``voice``
+        # explicitly via ``parameter_overrides: { voice: { hidden: true } }``.
+        if not any(
+            isinstance(t, str) and t.startswith("audio/") for t in output_types
+        ):
+            properties.pop("voice", None)
+
+        # Auto-inject: set max_tokens maximum from output_size
+        if "max_tokens" in properties and "output_size" in config:
+            properties["max_tokens"]["maximum"] = config["output_size"]
+
+        # Apply parameter_overrides with simple dict merge
+        overrides = config.get("parameter_overrides", {})
+        for param_name, override in overrides.items():
+            if override is None:
+                # null means remove
+                properties.pop(param_name, None)
+                continue
+
+            if isinstance(override, dict):
+                # Check for hidden flag
+                if override.get("hidden"):
+                    properties.pop(param_name, None)
+                    continue
+
+                # Simple dict merge: {**base, **override}
+                if param_name in properties:
+                    properties[param_name] = {
+                        **properties[param_name],
+                        **override,
+                    }
+
+        # Build final parameter schema
+        final_schema = {
+            "type": "object",
+            "properties": properties,
+            "required": base_schema.get("required", []),
+        }
+
+        # Create ModelCard instance
+        return cls(
+            name=config["name"],
+            label=config["label"],
+            status=config.get("status", "active"),
+            deprecated_at=config.get("deprecated_at"),
+            input_types=config.get("input_types", ["text/plain"]),
+            output_types=config.get("output_types", ["text/plain"]),
+            context_size=config["context_size"],
+            output_size=config["output_size"],
+            parameter_schema=final_schema,
+            parameters_overrides=config.get("parameter_overrides", {}),
+        )
diff --git a/src/agentscope/model/_model_response.py b/src/agentscope/model/_model_response.py
new file mode 100644
index 0000000..aa29902
--- /dev/null
+++ b/src/agentscope/model/_model_response.py
@@ -0,0 +1,350 @@
+# -*- coding: utf-8 -*-
+"""The model response module."""
+import base64
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import StrEnum
+from typing import Any, Literal, Self, List
+
+from ._model_usage import ChatUsage
+from .._utils._common import _generate_id
+from .._utils._mixin import DictMixin
+from ..message import (
+    TextBlock,
+    ToolCallBlock,
+    ThinkingBlock,
+    DataBlock,
+    Base64Source,
+)
+from ..types import JSONSerializableObject
+
+
+class FinishedReason(StrEnum):
+    """The finished reason of the model response."""
+
+    INTERRUPTED = "interrupted"
+    """The model response is interrupted by the asyncio.CancelledError."""
+
+    COMPLETED = "completed"
+    """The model response is completed."""
+
+
+@dataclass
+class ChatResponse(DictMixin):
+    """The response of chat models."""
+
+    content: List[TextBlock | ToolCallBlock | ThinkingBlock | DataBlock]
+    """The content of the chat response, which can include text blocks,
+    tool use blocks, or thinking blocks."""
+
+    is_last: bool
+    """Whether this response is the last response, if `Ture`, the content will
+    be the complete response, otherwise the content is a partial response"""
+
+    id: str = field(default_factory=_generate_id)
+    """The unique identifier."""
+
+    created_at: str = field(default_factory=lambda: datetime.now().isoformat())
+    """When the response was created"""
+
+    type: Literal["chat_response"] = field(
+        default_factory=lambda: "chat_response",
+    )
+    """The type of the response, which is always 'chat_response'."""
+
+    usage: ChatUsage | None = field(default_factory=lambda: None)
+    """The usage information of the chat response, if available."""
+
+    finished_reason: FinishedReason = field(
+        default=FinishedReason.COMPLETED,
+    )
+    """The finished reason of the chat response, available when `is_last`
+    is `True`."""
+
+    metadata: dict[str, JSONSerializableObject] = field(
+        default_factory=lambda: {},
+    )
+    """The metadata of the chat response"""
+
+    def append_text(self, text: str, block_id: str | None = None) -> Self:
+        """Append text to the current response."""
+        for block in self.content:
+            if isinstance(block, TextBlock) and (
+                block_id is None or block_id == block.id
+            ):
+                block.text += text
+                return self
+
+        # Append a new block
+        assert isinstance(self.content, list)
+        self.content.append(
+            TextBlock(text=text, id=block_id or _generate_id()),
+        )
+        return self
+
+    def append_thinking(
+        self,
+        thinking: str,
+        block_id: str | None = None,
+        **extra_fields: Any,
+    ) -> Self:
+        """Append thinking to the current response.
+
+        Args:
+            thinking (`str`):
+                The thinking content to append.
+            block_id (`str | None`, defaults to `None`):
+                The id of the ``ThinkingBlock`` to accumulate into. If no
+                matching block exists in ``content``, a new one is
+                appended.
+            **extra_fields (`Any`):
+                Additional provider-specific fields to attach to the
+                ``ThinkingBlock`` (e.g. Anthropic's ``signature``, OpenAI
+                Responses API's ``reasoning_item_id``). Only non-``None``
+                values are applied.
+        """
+        for block in self.content:
+            if isinstance(block, ThinkingBlock) and (
+                block_id is None or block_id == block.id
+            ):
+                block.thinking += thinking
+                for key, value in extra_fields.items():
+                    if value is not None:
+                        setattr(block, key, value)
+                return self
+
+        assert isinstance(self.content, list)
+        block = ThinkingBlock(thinking=thinking, id=block_id or _generate_id())
+        for key, value in extra_fields.items():
+            if value is not None:
+                setattr(block, key, value)
+        self.content.append(block)
+        return self
+
+    def append_tool_call(
+        self,
+        block_id: str,
+        name: str,
+        input: str,  # pylint: disable=redefined-builtin
+        **extra_fields: Any,
+    ) -> Self:
+        """Append tool call to the current response by tool call block ID.
+
+        Args:
+            block_id (`str`):
+                The id of the ``ToolCallBlock`` to accumulate into. If no
+                matching block exists in ``content``, a new one is
+                appended.
+            name (`str`):
+                The name of the tool being called.
+            input (`str`):
+                The incremental JSON string arguments to append.
+            **extra_fields (`Any`):
+                Additional provider-specific fields to attach to the
+                ``ToolCallBlock`` (e.g. OpenAI Responses API's
+                ``call_id``). Only non-``None`` values are applied.
+        """
+        for block in self.content:
+            if isinstance(block, ToolCallBlock) and block.id == block_id:
+                block.input += input
+                for key, value in extra_fields.items():
+                    if value is not None:
+                        setattr(block, key, value)
+                return self
+
+        block = ToolCallBlock(
+            id=block_id,
+            name=name,
+            input=input,
+        )
+        for key, value in extra_fields.items():
+            if value is not None:
+                setattr(block, key, value)
+        assert isinstance(self.content, list)
+        self.content.append(block)
+        return self
+
+    def append_data_block(
+        self,
+        block_id: str,
+        data: bytes,
+        media_type: str,
+        name: str | None = None,
+    ) -> Self:
+        """Append raw media bytes to the ``DataBlock`` with the given id.
+
+        The accumulated bytes are stored base64-encoded in
+        ``DataBlock.source.data`` (via a :class:`Base64Source`). Callers must
+        pass the *incremental* raw media bytes only — the method takes care
+        of base64 (de)coding internally, so consumers never have to worry
+        about base64 padding (``=``) corrupting concatenation.
+
+        .. note::
+
+            Byte-level delta accumulation only has a well-defined semantics
+            for streaming media where chunks can be safely concatenated
+            (currently ``audio/*``). For non-streamable media types
+            (e.g. ``image/*``, ``video/*``) each ``DataBlock`` should be
+            treated as a complete file and passed atomically rather than
+            accumulated through this method.
+
+        Args:
+            block_id (`str`):
+                The id of the ``DataBlock`` to accumulate into. If no
+                matching block exists in ``content``, a new one is
+                appended.
+            data (`bytes`):
+                The incremental raw media bytes to append.
+            media_type (`str`):
+                The IANA media type of the raw bytes (e.g. ``audio/pcm``,
+                ``audio/wav``). Used both to tag a newly-created block and
+                to guard against accidentally mixing bytes from different
+                media types under the same id.
+            name (`str | None`, defaults to `None`):
+                The optional ``name`` field used when a new ``DataBlock``
+                needs to be created. Ignored when an existing block with
+                ``block_id`` is found.
+
+        Returns:
+            `Self`:
+                The current ``ChatResponse`` instance for chaining.
+        """
+        for block in self.content:
+            if (
+                isinstance(block, DataBlock)
+                and block.id == block_id
+                and isinstance(block.source, Base64Source)
+                and block.source.media_type == media_type
+            ):
+                old_bytes = (
+                    base64.b64decode(block.source.data)
+                    if block.source.data
+                    else b""
+                )
+                block.source.data = base64.b64encode(
+                    old_bytes + data,
+                ).decode("ascii")
+                return self
+
+        self.content.append(
+            DataBlock(
+                id=block_id,
+                source=Base64Source(
+                    data=base64.b64encode(data).decode("ascii"),
+                    media_type=media_type,
+                ),
+                name=name,
+            ),
+        )
+        return self
+
+    def append_chat_response(self, chat_response: Self) -> Self:
+        """Append chat response to the current response."""
+        # Append content
+        new_block_dict = {_.id: _ for _ in chat_response.content}
+        for block in self.content:
+            if block.id in new_block_dict:
+                delta_block = new_block_dict.pop(block.id)
+                # Append data according to the block type
+                if isinstance(block, ThinkingBlock):
+                    block.thinking += delta_block.thinking
+                    # Provider-specific extra fields (e.g. Anthropic's
+                    # ``signature``, OpenAI Responses API's
+                    # ``reasoning_item_id``) are carried on the delta
+                    # ``ThinkingBlock`` via pydantic's ``extra="allow"``.
+                    # Copy any non-``None`` extras onto the accumulator.
+                    for key, value in (delta_block.model_extra or {}).items():
+                        if value is not None:
+                            setattr(block, key, value)
+
+                elif isinstance(block, TextBlock):
+                    block.text += delta_block.text
+
+                elif isinstance(block, ToolCallBlock):
+                    block.input += delta_block.input
+                    # Provider-specific extras (e.g. OpenAI Responses
+                    # API's ``call_id``) may be attached on the delta
+                    # block via pydantic's ``extra="allow"``.
+                    for key, value in (delta_block.model_extra or {}).items():
+                        if value is not None:
+                            setattr(block, key, value)
+
+                elif isinstance(block, DataBlock):
+                    # Only ``audio/*`` is treated as a streamable delta:
+                    # callers accumulate raw media bytes across chunks and
+                    # the concatenated result is a well-defined stream.
+                    # For non-audio media types (``image/*``, ``video/*``,
+                    # ...) each ``DataBlock`` is a complete standalone
+                    # asset — byte concatenation is meaningless — so we
+                    # overwrite in place with the latest delta instead.
+                    if not (
+                        isinstance(block.source, Base64Source)
+                        and isinstance(delta_block.source, Base64Source)
+                        and block.source.media_type
+                        == delta_block.source.media_type
+                    ):
+                        # Source shape / media type mismatch: replace the
+                        # whole block to avoid mixing incompatible data.
+                        block.source = delta_block.source
+                    elif block.source.media_type.startswith("audio/"):
+                        old_bytes = (
+                            base64.b64decode(block.source.data)
+                            if block.source.data
+                            else b""
+                        )
+                        delta_bytes = (
+                            base64.b64decode(delta_block.source.data)
+                            if delta_block.source.data
+                            else b""
+                        )
+                        block.source.data = base64.b64encode(
+                            old_bytes + delta_bytes,
+                        ).decode("ascii")
+                    else:
+                        # Non-streamable media: latest delta wins.
+                        block.source.data = delta_block.source.data
+
+        if new_block_dict:
+            # Attach new blocks to the content.
+            self.content.extend(
+                block.model_copy(deep=True)
+                for block in new_block_dict.values()
+            )
+
+        # Override the chat usage
+        if chat_response.usage:
+            self.usage = chat_response.usage
+
+        return self
+
+
+@dataclass
+class StructuredResponse:
+    """The structured response of chat models."""
+
+    content: dict
+    """The structured output of the model."""
+
+    id: str = field(default_factory=_generate_id)
+    """The unique identifier."""
+
+    created_at: str = field(default_factory=lambda: datetime.now().isoformat())
+    """When the response was created"""
+
+    type: Literal["structured_response"] = field(
+        default_factory=lambda: "structured_response",
+    )
+    """The type of the response, which is always 'structured_response'."""
+
+    usage: ChatUsage | None = field(default_factory=lambda: None)
+    """The usage information of the chat response, if available."""
+
+    metadata: dict[str, JSONSerializableObject] = field(
+        default_factory=lambda: {},
+    )
+    """The metadata of the chat response"""
+
+    finished_reason: FinishedReason = field(
+        default=FinishedReason.COMPLETED,
+    )
+    """The finished reason of the structured response."""
diff --git a/src/agentscope/model/_model_usage.py b/src/agentscope/model/_model_usage.py
new file mode 100644
index 0000000..952cc6d
--- /dev/null
+++ b/src/agentscope/model/_model_usage.py
@@ -0,0 +1,32 @@
+# -*- coding: utf-8 -*-
+"""The model usage class in agentscope."""
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from .._utils._mixin import DictMixin
+
+
+@dataclass
+class ChatUsage(DictMixin):
+    """The usage of a chat model API invocation."""
+
+    input_tokens: int
+    """The number of input tokens."""
+
+    output_tokens: int
+    """The number of output tokens."""
+
+    time: float
+    """The time used in seconds."""
+
+    cache_creation_input_tokens: int = field(default_factory=lambda: 0)
+    """The number of input tokens used to create the prompt cache."""
+
+    cache_input_tokens: int = field(default_factory=lambda: 0)
+    """The number of input tokens read from the prompt cache."""
+
+    type: Literal["chat"] = field(default_factory=lambda: "chat")
+    """The type of the usage, must be `chat`."""
+
+    metadata: dict[str, Any] | None = field(default_factory=lambda: None)
+    """Optional metadata associated with the usage."""
diff --git a/src/agentscope/model/_moonshot/__init__.py b/src/agentscope/model/_moonshot/__init__.py
new file mode 100644
index 0000000..5480a58
--- /dev/null
+++ b/src/agentscope/model/_moonshot/__init__.py
@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+"""The Moonshot AI LLM API modules."""
+
+from ._model import MoonshotChatModel
+
+__all__ = [
+    "MoonshotChatModel",
+]
diff --git a/src/agentscope/model/_moonshot/_model.py b/src/agentscope/model/_moonshot/_model.py
new file mode 100644
index 0000000..0ab3dca
--- /dev/null
+++ b/src/agentscope/model/_moonshot/_model.py
@@ -0,0 +1,452 @@
+# -*- coding: utf-8 -*-
+"""The Moonshot AI chat model implementation."""
+from collections import OrderedDict
+from datetime import datetime
+from typing import Literal, Any, AsyncGenerator, TYPE_CHECKING, List, Type
+
+from pydantic import BaseModel, Field
+
+from .._base import ChatModelBase, _TOOL_CHOICE_LITERAL_MODES
+from .._model_response import ChatResponse, StructuredResponse
+from .._model_usage import ChatUsage
+from ..._utils._common import _generate_id
+from ...credential import MoonshotCredential
+from ...formatter import FormatterBase, MoonshotChatFormatter
+from ...message import Msg, ThinkingBlock, ToolCallBlock, TextBlock
+from ...tool import ToolChoice
+
+if TYPE_CHECKING:
+    from openai.types.chat import ChatCompletion
+    from openai import AsyncStream
+else:
+    ChatCompletion = Any
+    AsyncStream = Any
+
+
+class MoonshotChatModel(ChatModelBase):
+    """The Moonshot AI chat model."""
+
+    class Parameters(BaseModel):
+        """The parameters for the Moonshot AI chat model."""
+
+        max_tokens: int | None = Field(
+            default=None,
+            title="Max Tokens",
+            description="The maximum number of tokens for the LLM output.",
+            gt=0,
+        )
+
+        thinking_enable: bool = Field(
+            default=False,
+            title="Thinking",
+            description=(
+                "Whether to enable thinking mode. For kimi-k2-thinking, "
+                "thinking is always enabled. For kimi-k2.6, thinking is "
+                "enabled by default but can be disabled."
+            ),
+        )
+
+        temperature: float | None = Field(
+            default=None,
+            title="Temperature",
+            description="The temperature for the LLM output.",
+            ge=0,
+            le=1,
+        )
+
+        top_p: float | None = Field(
+            default=None,
+            title="Top P",
+            description="The top P value for the LLM output.",
+            gt=0,
+            le=1,
+        )
+
+    type: Literal["moonshot_chat"] = "moonshot_chat"
+    """The type of the chat model."""
+
+    def __init__(
+        self,
+        credential: MoonshotCredential,
+        model: str,
+        parameters: "MoonshotChatModel.Parameters | None" = None,
+        stream: bool = True,
+        max_retries: int = 3,
+        retry_delay: float = 1.0,
+        context_size: int = 131072,
+        formatter: FormatterBase | None = None,
+        client_kwargs: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize the Moonshot AI chat model.
+
+        Args:
+            credential (`MoonshotCredential`):
+                The Moonshot AI credential used to authenticate API calls.
+            model (`str`):
+                The model name, e.g. ``moonshot-v1-8k``, ``kimi-k2.6``.
+            parameters (`MoonshotChatModel.Parameters | None`, defaults to \
+            `None`):
+                The API parameters. When ``None``, the default parameters
+                will be used.
+            stream (`bool`, defaults to `True`):
+                Whether to enable streaming output.
+            max_retries (`int`, defaults to `3`):
+                The maximum number of retries for the API.
+            retry_delay (`float`, defaults to `1.0`):
+                Seconds to sleep between retry attempts.
+            context_size (`int`, defaults to `131072`):
+                The model context size used for context compression.
+            formatter (`FormatterBase | None`, defaults to `None`):
+                The formatter that converts ``Msg`` objects to the format
+                required by the API. When ``None``, a
+                ``MoonshotChatFormatter`` instance will be used.
+            client_kwargs (`dict[str, Any] | None`, defaults to `None`):
+                Extra keyword arguments forwarded to ``openai.AsyncClient``
+                (e.g. ``timeout``, ``default_headers``, ``http_client``).
+        """
+        super().__init__(
+            credential=credential,
+            model=model,
+            parameters=parameters or self.Parameters(),
+            stream=stream,
+            max_retries=max_retries,
+            retry_delay=retry_delay,
+            context_size=context_size,
+        )
+        self.formatter = formatter or MoonshotChatFormatter()
+        self.client_kwargs = client_kwargs or {}
+
+    @classmethod
+    def _get_retryable_exceptions(cls) -> tuple[Type[Exception], ...]:
+        import openai
+
+        return (
+            openai.APIConnectionError,
+            openai.APITimeoutError,
+            openai.RateLimitError,
+            openai.InternalServerError,
+        )
+
+    async def _call_api(
+        self,
+        model_name: str,
+        messages: list[Msg],
+        tools: list[dict] | None = None,
+        tool_choice: ToolChoice | None = None,
+        **generate_kwargs: Any,
+    ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:
+        """Call the Moonshot AI chat API (OpenAI-compatible).
+
+        Args:
+            model_name (`str`):
+                The model name to use for this call.
+            messages (`list`):
+                A list of message dicts with ``role`` and ``content`` keys.
+            tools (`list[dict]`, default `None`):
+                The tools JSON schemas.
+            tool_choice (`ToolChoice | None`, optional):
+                Controls which (if any) tool is called by the model.
+            **generate_kwargs (`Any`):
+                Extra keyword arguments forwarded to the API.
+
+        Returns:
+            `ChatResponse | AsyncGenerator[ChatResponse, None]`:
+                A ``ChatResponse`` when streaming is disabled, or an async
+                generator of ``ChatResponse`` objects when streaming is
+                enabled.
+        """
+        import openai
+
+        client = openai.AsyncClient(
+            **{
+                "api_key": self.credential.api_key.get_secret_value(),
+                "base_url": self.credential.base_url,
+                **self.client_kwargs,
+            },
+        )
+
+        formatted_messages = await self.formatter.format(messages)
+
+        kwargs: dict[str, Any] = {
+            "model": model_name,
+            "messages": formatted_messages,
+            "stream": self.stream,
+        }
+
+        if self.parameters.max_tokens is not None:
+            kwargs["max_tokens"] = self.parameters.max_tokens
+
+        if self.parameters.temperature is not None:
+            kwargs["temperature"] = self.parameters.temperature
+
+        if self.parameters.top_p is not None:
+            kwargs["top_p"] = self.parameters.top_p
+
+        kwargs.update(generate_kwargs)
+
+        thinking_type = (
+            "enabled" if self.parameters.thinking_enable else "disabled"
+        )
+        kwargs.setdefault("extra_body", {})
+        kwargs["extra_body"].setdefault("thinking", {})
+        kwargs["extra_body"]["thinking"].setdefault("type", thinking_type)
+
+        fmt_tools, fmt_tool_choice = self._format_tools(tools, tool_choice)
+
+        if fmt_tools:
+            kwargs["tools"] = fmt_tools
+
+        if fmt_tool_choice is not None:
+            kwargs["tool_choice"] = fmt_tool_choice
+
+        if self.stream:
+            kwargs["stream_options"] = {"include_usage": True}
+
+        start_datetime = datetime.now()
+        response = await client.chat.completions.create(**kwargs)
+
+        if self.stream:
+            return self._parse_stream_response(start_datetime, response)
+
+        return self._parse_completion_response(start_datetime, response)
+
+    async def _parse_stream_response(
+        self,
+        start_datetime: datetime,
+        response: AsyncStream,
+    ) -> AsyncGenerator[ChatResponse, None]:
+        """Parse the Moonshot AI streaming response.
+
+        Args:
+            start_datetime (`datetime`):
+                The start datetime of the response generation.
+            response (`AsyncStream`):
+                The OpenAI-compatible async stream object.
+
+        Yields:
+            `ChatResponse`:
+                Incremental ``ChatResponse`` objects with ``is_last=False``
+                followed by a final one with ``is_last=True``.
+        """
+        usage = None
+        response_id: str = _generate_id()
+        text_id: str = _generate_id()
+        thinking_id: str = _generate_id()
+        # The mapping from index to tool call id
+        tool_call_mapping: dict = OrderedDict()
+
+        async with response as stream:
+            async for chunk in stream:
+                delta_res = ChatResponse(
+                    content=[],
+                    is_last=False,
+                    id=response_id,
+                )
+
+                # Update the response ID if exists
+                response_id = getattr(chunk, "id", None) or response_id
+                delta_res.id = response_id
+
+                if chunk.usage:
+                    u = chunk.usage
+                    usage = ChatUsage(
+                        input_tokens=u.prompt_tokens,
+                        output_tokens=u.completion_tokens,
+                        time=(datetime.now() - start_datetime).total_seconds(),
+                        cache_input_tokens=getattr(
+                            u,
+                            "cached_tokens",
+                            0,
+                        ),
+                    )
+
+                if not chunk.choices:
+                    continue
+
+                choice = chunk.choices[0]
+                delta = choice.delta
+
+                # Thinking
+                if getattr(delta, "reasoning_content", None):
+                    delta_res.append_thinking(
+                        block_id=thinking_id,
+                        thinking=delta.reasoning_content,
+                    )
+
+                # Text
+                if getattr(delta, "content", None):
+                    delta_res.append_text(
+                        block_id=text_id,
+                        text=delta.content,
+                    )
+
+                # Tool call
+                for tool_call in getattr(delta, "tool_calls", None) or []:
+                    index = tool_call.index
+                    fn = getattr(tool_call, "function", None)
+                    delta_name = getattr(fn, "name", None) if fn else None
+                    delta_args = getattr(fn, "arguments", None) if fn else None
+
+                    # Record the id and name in case following deltas
+                    # don't provide them
+                    if index not in tool_call_mapping:
+                        tool_call_mapping[index] = (
+                            tool_call.id,
+                            delta_name or "unknown",
+                        )
+
+                    stored_id, stored_name = tool_call_mapping[index]
+
+                    delta_res.append_tool_call(
+                        block_id=tool_call.id or stored_id,
+                        name=delta_name or stored_name,
+                        input=delta_args or "",
+                    )
+
+                if delta_res.content or usage:
+                    delta_res.usage = usage
+                    yield delta_res
+
+    def _parse_completion_response(
+        self,
+        start_datetime: datetime,
+        response: ChatCompletion,
+    ) -> ChatResponse:
+        """Parse the Moonshot AI non-streaming response.
+
+        Args:
+            start_datetime (`datetime`):
+                The start datetime of the response generation.
+            response (`ChatCompletion`):
+                The OpenAI-compatible chat completion object.
+
+        Returns:
+            `ChatResponse`:
+                A single ``ChatResponse`` with ``is_last=True``.
+        """
+        content_blocks: List[ThinkingBlock | TextBlock | ToolCallBlock] = []
+
+        if response.choices:
+            choice = response.choices[0]
+            reasoning = getattr(choice.message, "reasoning_content", None)
+            if reasoning:
+                content_blocks.append(ThinkingBlock(thinking=reasoning))
+
+            if choice.message.content:
+                content_blocks.append(TextBlock(text=choice.message.content))
+
+            for tool_call in choice.message.tool_calls or []:
+                content_blocks.append(
+                    ToolCallBlock(
+                        id=tool_call.id,
+                        name=tool_call.function.name,
+                        input=tool_call.function.arguments,
+                    ),
+                )
+
+        usage = None
+        if response.usage:
+            u = response.usage
+            usage = ChatUsage(
+                input_tokens=u.prompt_tokens,
+                output_tokens=u.completion_tokens,
+                time=(datetime.now() - start_datetime).total_seconds(),
+                cache_input_tokens=getattr(u, "cached_tokens", 0),
+            )
+
+        resp_kwargs: dict[str, Any] = {
+            "content": content_blocks,
+            "is_last": True,
+            "usage": usage,
+        }
+        response_id = getattr(response, "id", None)
+        if response_id:
+            resp_kwargs["id"] = response_id
+
+        return ChatResponse(**resp_kwargs)
+
+    def _format_tools(
+        self,
+        tools: list[dict] | None,
+        tool_choice: ToolChoice | None,
+    ) -> tuple[list[dict] | None, str | dict | None]:
+        """Validate, filter, and format tools and tool_choice for the
+        Moonshot AI API.
+
+        When ``tool_choice.tools`` is specified the schemas list is filtered
+        to only those tools. When ``tool_choice.mode`` is a specific tool name
+        (str) the model is forced to call exactly that tool without needing to
+        filter the list, preserving prompt-cache efficiency.
+
+        Args:
+            tools (`list[dict] | None`, optional):
+                The raw tool schemas.
+            tool_choice (`ToolChoice | None`, optional):
+                The tool choice configuration.
+
+        Returns:
+            `tuple[list[dict] | None, str | dict | None]`:
+                A tuple of (formatted_tools, formatted_tool_choice).
+        """
+        if tool_choice and tools:
+            self._validate_tool_choice(tool_choice, tools)
+            if tool_choice.tools:
+                allowed = set(tool_choice.tools)
+                tools = [t for t in tools if t["function"]["name"] in allowed]
+
+        if not tool_choice:
+            return tools, None
+
+        mode = tool_choice.mode
+
+        if mode not in _TOOL_CHOICE_LITERAL_MODES:
+            return tools, {"type": "function", "function": {"name": mode}}
+
+        return tools, mode
+
+    async def _call_api_with_structured_output(
+        self,
+        model_name: str,
+        messages: list[Msg],
+        structured_model: Type[BaseModel] | dict,
+        tool_choice: ToolChoice | None = None,
+        **kwargs: Any,
+    ) -> StructuredResponse:
+        """Moonshot-specific override for structured output.
+
+        Moonshot rejects ``tool_choice="required"`` or an object-form
+        ``tool_choice`` when thinking mode is enabled. In that case we
+        default ``tool_choice`` to ``"auto"`` and rely on the base class's
+        injected system-reminder prompt to guide the model. When thinking
+        is disabled, this falls through to the base implementation.
+
+        Args:
+            model_name (`str`):
+                The model name to use for this call.
+            messages (`list[Msg]`):
+                The context for the LLM to generate the structured output.
+            structured_model (`Type[BaseModel] | dict`):
+                A Pydantic model class or a JSON schema dict describing the
+                required output structure.
+            tool_choice (`ToolChoice | None`, defaults to `None`):
+                The tool_choice forwarded to ``_call_api``. When ``None``
+                and thinking mode is enabled, it is downgraded to
+                ``ToolChoice(mode="auto")``; otherwise the base default
+                (force the structured-output tool) is used.
+            **kwargs (`Any`):
+                Additional keyword arguments forwarded to ``_call_api``.
+
+        Returns:
+            `StructuredResponse`:
+                The structured response whose ``content`` is the validated
+                output dict matching ``structured_model``.
+        """
+        if tool_choice is None and self.parameters.thinking_enable:
+            tool_choice = ToolChoice(mode="auto")
+        return await super()._call_api_with_structured_output(
+            model_name=model_name,
+            messages=messages,
+            structured_model=structured_model,
+            tool_choice=tool_choice,
+            **kwargs,
+        )
diff --git a/src/agentscope/model/_moonshot/_models/kimi-k2.5.yaml b/src/agentscope/model/_moonshot/_models/kimi-k2.5.yaml
new file mode 100644
index 0000000..bc2e273
--- /dev/null
+++ b/src/agentscope/model/_moonshot/_models/kimi-k2.5.yaml
@@ -0,0 +1,22 @@
+name: kimi-k2.5
+label: Kimi K2.5
+status: active
+
+input_types:
+  - text/plain
+  - application/x-thinking
+  - image/jpeg
+  - image/png
+  - image/gif
+  - image/webp
+
+output_types:
+  - text/plain
+  - application/x-thinking
+
+context_size: 262144
+output_size: 65536
+
+parameter_overrides:
+  max_tokens:
+    maximum: 65536
diff --git a/src/agentscope/model/_moonshot/_models/kimi-k2.6.yaml b/src/agentscope/model/_moonshot/_models/kimi-k2.6.yaml
new file mode 100644
index 0000000..53c58bd
--- /dev/null
+++ b/src/agentscope/model/_moonshot/_models/kimi-k2.6.yaml
@@ -0,0 +1,27 @@
+name: kimi-k2.6
+label: Kimi K2.6
+status: active
+
+input_types:
+  - text/plain
+  - application/x-thinking
+  - image/jpeg
+  - image/png
+  - image/gif
+  - image/webp
+  - video/mp4
+  - video/mpeg
+  - video/quicktime
+  - video/avi
+  - video/webm
+
+output_types:
+  - text/plain
+  - application/x-thinking
+
+context_size: 262144
+output_size: 32768
+
+parameter_overrides:
+  max_tokens:
+    maximum: 32768
diff --git a/src/agentscope/model/_moonshot/_models/moonshot-v1-128k.yaml b/src/agentscope/model/_moonshot/_models/moonshot-v1-128k.yaml
new file mode 100644
index 0000000..7bfa9a9
--- /dev/null
+++ b/src/agentscope/model/_moonshot/_models/moonshot-v1-128k.yaml
@@ -0,0 +1,16 @@
+name: moonshot-v1-128k
+label: Kimi Moonshot v1 128K
+status: active
+
+input_types:
+  - text/plain
+
+output_types:
+  - text/plain
+
+context_size: 131072
+output_size: 131072
+
+parameter_overrides:
+  max_tokens:
+    maximum: 131072
diff --git a/src/agentscope/model/_moonshot/_models/moonshot-v1-32k.yaml b/src/agentscope/model/_moonshot/_models/moonshot-v1-32k.yaml
new file mode 100644
index 0000000..b6ffdd2
--- /dev/null
+++ b/src/agentscope/model/_moonshot/_models/moonshot-v1-32k.yaml
@@ -0,0 +1,16 @@
+name: moonshot-v1-32k
+label: Kimi Moonshot v1 32K
+status: active
+
+input_types:
+  - text/plain
+
+output_types:
+  - text/plain
+
+context_size: 32768
+output_size: 32768
+
+parameter_overrides:
+  max_tokens:
+    maximum: 32768
diff --git a/src/agentscope/model/_moonshot/_models/moonshot-v1-8k.yaml b/src/agentscope/model/_moonshot/_models/moonshot-v1-8k.yaml
new file mode 100644
index 0000000..488cd8d
--- /dev/null
+++ b/src/agentscope/model/_moonshot/_models/moonshot-v1-8k.yaml
@@ -0,0 +1,16 @@
+name: moonshot-v1-8k
+label: Kimi Moonshot v1 8K
+status: active
+
+input_types:
+  - text/plain
+
+output_types:
+  - text/plain
+
+context_size: 8192
+output_size: 8192
+
+parameter_overrides:
+  max_tokens:
+    maximum: 8192
diff --git a/src/agentscope/model/_ollama/__init__.py b/src/agentscope/model/_ollama/__init__.py
new file mode 100644
index 0000000..0e152fc
--- /dev/null
+++ b/src/agentscope/model/_ollama/__init__.py
@@ -0,0 +1,9 @@
+# -*- coding: utf-8 -*-
+"""The Ollama LLM API modules."""
+
+from ._model import OllamaCredential, OllamaChatModel
+
+__all__ = [
+    "OllamaCredential",
+    "OllamaChatModel",
+]
diff --git a/src/agentscope/model/_ollama/_model.py b/src/agentscope/model/_ollama/_model.py
new file mode 100644
index 0000000..a85e003
--- /dev/null
+++ b/src/agentscope/model/_ollama/_model.py
@@ -0,0 +1,350 @@
+# -*- coding: utf-8 -*-
+"""The Ollama chat model implementation."""
+import json
+from datetime import datetime
+from typing import Literal, Any, AsyncGenerator, TYPE_CHECKING, List, Type
+
+from pydantic import BaseModel, Field
+
+from ..._utils._common import _generate_id
+from .._base import ChatModelBase
+from .._model_response import ChatResponse
+from .._model_usage import ChatUsage
+from ...credential import OllamaCredential
+from ...formatter import FormatterBase, OllamaChatFormatter
+from ...message import Msg, ThinkingBlock, ToolCallBlock, TextBlock
+from ...tool import ToolChoice
+from ..._logging import logger
+
+if TYPE_CHECKING:
+    from ollama._types import ChatResponse as OllamaChatResponse
+else:
+    OllamaChatResponse = Any
+
+
+class OllamaChatModel(ChatModelBase):
+    """The Ollama chat model."""
+
+    class Parameters(BaseModel):
+        """The parameters for the Ollama chat model."""
+
+        max_tokens: int | None = Field(
+            default=None,
+            title="Max Tokens",
+            description="The maximum number of tokens for the LLM output.",
+            gt=0,
+        )
+
+        thinking_enable: bool = Field(
+            default=False,
+            title="Thinking",
+            description="Whether to enable thinking"
+            " (for models like qwen3, deepseek-r1).",
+        )
+
+        temperature: float | None = Field(
+            default=None,
+            title="Temperature",
+            description="The temperature for the LLM output.",
+            ge=0,
+            le=2,
+        )
+
+    type: Literal["ollama_chat"] = "ollama_chat"
+    """The type of the chat model."""
+
+    def __init__(
+        self,
+        credential: OllamaCredential | None = None,
+        model: str = "",
+        parameters: "OllamaChatModel.Parameters | None" = None,
+        stream: bool = True,
+        max_retries: int = 3,
+        retry_delay: float = 1.0,
+        context_size: int = 32768,
+        formatter: FormatterBase | None = None,
+        client_kwargs: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize the Ollama chat model.
+
+        Args:
+            credential (`OllamaCredential | None`, defaults to `None`):
+                The Ollama connection settings. When ``None``, a default
+                ``OllamaCredential`` (localhost) will be used.
+            model (`str`):
+                The Ollama model name, e.g. ``llama3.3`` or ``qwen3:14b``.
+            parameters (`OllamaChatModel.Parameters | None`, defaults to \
+            `None`):
+                The Ollama API parameters. When ``None``, the default
+                parameters will be used.
+            stream (`bool`, defaults to `True`):
+                Whether to enable streaming output.
+            max_retries (`int`, defaults to `3`):
+                The maximum number of retries for the Ollama API.
+            retry_delay (`float`, defaults to `1.0`):
+                Seconds to sleep between retry attempts.
+            context_size (`int`, defaults to `32768`):
+                The model context size used for context compression.
+            formatter (`FormatterBase | None`, defaults to `None`):
+                The formatter that converts ``Msg`` objects to the format
+                required by the Ollama API. When ``None``, an
+                ``OllamaChatFormatter`` instance will be used.
+            client_kwargs (`dict[str, Any] | None`, defaults to `None`):
+                Extra keyword arguments forwarded to ``ollama.AsyncClient``
+                and onward to the underlying ``httpx.AsyncClient``
+                (e.g. ``timeout``, ``headers``, ``verify``).
+        """
+        resolved_credential = credential or OllamaCredential()
+
+        super().__init__(
+            credential=resolved_credential,
+            model=model,
+            parameters=parameters or self.Parameters(),
+            stream=stream,
+            max_retries=max_retries,
+            retry_delay=retry_delay,
+            context_size=context_size,
+        )
+
+        self.formatter = formatter or OllamaChatFormatter()
+        self.client_kwargs = client_kwargs or {}
+
+    @classmethod
+    def _get_retryable_exceptions(cls) -> tuple[Type[Exception], ...]:
+        import httpx
+
+        # Local service: retry transient transport-layer failures only.
+        # ollama.ResponseError wraps server-side errors regardless of cause
+        # (incl. 4xx like "model not found"), so we don't retry on it.
+        return (
+            httpx.ConnectError,
+            httpx.ReadTimeout,
+            httpx.RemoteProtocolError,
+        )
+
+    async def _call_api(
+        self,
+        model_name: str,
+        messages: list[Msg],
+        tools: list[dict] | None = None,
+        tool_choice: ToolChoice | None = None,
+        **generate_kwargs: Any,
+    ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:
+        """Call the Ollama chat API.
+
+        Args:
+            model_name (`str`):
+                The model name to use for this call.
+            messages (`list`):
+                A list of message dicts with ``role`` and ``content`` keys.
+            tools (`list[dict]`, default `None`):
+                The tools JSON schemas.
+            tool_choice (`ToolChoice | None`, optional):
+                Not supported by Ollama yet (ignored with warning).
+            **generate_kwargs (`Any`):
+                Extra keyword arguments forwarded to the Ollama API.
+
+        Returns:
+            `ChatResponse | AsyncGenerator[ChatResponse, None]`:
+                A ``ChatResponse`` when streaming is disabled, or an async
+                generator of ``ChatResponse`` objects when streaming is
+                enabled.
+        """
+        import ollama
+
+        client = ollama.AsyncClient(
+            **{
+                "host": self.credential.host,
+                **self.client_kwargs,
+            },
+        )
+
+        formatted_messages = await self.formatter.format(messages)
+
+        kwargs: dict[str, Any] = {
+            "model": model_name,
+            "messages": formatted_messages,
+            "stream": self.stream,
+        }
+
+        options: dict[str, Any] = {}
+        if self.parameters.max_tokens is not None:
+            options["num_predict"] = self.parameters.max_tokens
+        if self.parameters.temperature is not None:
+            options["temperature"] = self.parameters.temperature
+        if options:
+            kwargs["options"] = options
+
+        kwargs["think"] = self.parameters.thinking_enable
+
+        kwargs.update(generate_kwargs)
+
+        fmt_tools, _ = self._format_tools(tools, tool_choice)
+
+        if fmt_tools:
+            kwargs["tools"] = fmt_tools
+
+        start_datetime = datetime.now()
+        response = await client.chat(**kwargs)
+
+        if self.stream:
+            return self._parse_stream_response(start_datetime, response)
+
+        return await self._parse_completion_response(start_datetime, response)
+
+    def _format_tools(
+        self,
+        tools: list[dict] | None,
+        tool_choice: ToolChoice | None,
+    ) -> tuple[list[dict] | None, None]:
+        """Validate, filter tools, and warn if tool_choice is set.
+
+        Ollama does not support ``tool_choice`` natively. When
+        ``tool_choice.tools`` is specified the schemas list is filtered to
+        only those tools. Any ``tool_choice.mode`` value is ignored with a
+        warning.
+
+        Args:
+            tools (`list[dict] | None`, optional):
+                The raw tool schemas.
+            tool_choice (`ToolChoice | None`, optional):
+                The tool choice configuration.
+
+        Returns:
+            `tuple[list[dict] | None, None]`:
+                A tuple of (filtered_tools, None) — tool_choice is always
+                ``None`` since Ollama does not support it.
+        """
+        if tool_choice and tools:
+            self._validate_tool_choice(tool_choice, tools)
+            if tool_choice.tools:
+                allowed = set(tool_choice.tools)
+                tools = [t for t in tools if t["function"]["name"] in allowed]
+
+        if tool_choice:
+            logger.warning(
+                "Ollama ignores tool_choice.mode; "
+                "tool_choice.tools is still applied to filter tool schemas.",
+            )
+
+        return tools, None
+
+    async def _parse_stream_response(
+        self,
+        start_datetime: datetime,
+        response: Any,
+    ) -> AsyncGenerator[ChatResponse, None]:
+        """Parse the Ollama streaming response.
+
+        Args:
+            start_datetime (`datetime`):
+                The start datetime of the response generation.
+            response (`Any`):
+                The Ollama async stream object.
+
+        Yields:
+            `ChatResponse`:
+                Incremental ``ChatResponse`` objects with ``is_last=False``
+                followed by a final one with ``is_last=True``.
+        """
+        response_id: str = _generate_id()
+        text_id: str = _generate_id()
+        thinking_id: str = _generate_id()
+
+        async for chunk in response:
+            delta_res = ChatResponse(
+                content=[],
+                is_last=False,
+                id=response_id,
+            )
+
+            msg = chunk.message
+
+            # Thinking
+            if getattr(msg, "thinking", None):
+                delta_res.append_thinking(
+                    block_id=thinking_id,
+                    thinking=msg.thinking,
+                )
+
+            # Text
+            if msg.content:
+                delta_res.append_text(
+                    block_id=text_id,
+                    text=msg.content,
+                )
+
+            # Tool call
+            for idx, tool_call in enumerate(msg.tool_calls or []):
+                delta_res.append_tool_call(
+                    block_id=f"{idx}_{tool_call.function.name}",
+                    name=tool_call.function.name,
+                    input=json.dumps(
+                        tool_call.function.arguments,
+                        ensure_ascii=False,
+                    ),
+                )
+
+            current_time = (datetime.now() - start_datetime).total_seconds()
+            delta_res.usage = ChatUsage(
+                input_tokens=getattr(chunk, "prompt_eval_count", 0) or 0,
+                output_tokens=getattr(chunk, "eval_count", 0) or 0,
+                time=current_time,
+            )
+
+            yield delta_res
+
+    async def _parse_completion_response(
+        self,
+        start_datetime: datetime,
+        response: OllamaChatResponse,
+    ) -> ChatResponse:
+        """Parse the Ollama non-streaming response.
+
+        Args:
+            start_datetime (`datetime`):
+                The start datetime of the response generation.
+            response (`OllamaChatResponse`):
+                The Ollama chat response object.
+
+        Returns:
+            `ChatResponse`:
+                A single ``ChatResponse`` with ``is_last=True``.
+        """
+        content_blocks: List[TextBlock | ToolCallBlock | ThinkingBlock] = []
+
+        message_thinking = getattr(response.message, "thinking", None)
+        if message_thinking:
+            content_blocks.append(ThinkingBlock(thinking=message_thinking))
+
+        if response.message.content:
+            content_blocks.append(TextBlock(text=response.message.content))
+
+        for idx, tool_call in enumerate(response.message.tool_calls or []):
+            content_blocks.append(
+                ToolCallBlock(
+                    id=f"{idx}_{tool_call.function.name}",
+                    name=tool_call.function.name,
+                    input=json.dumps(
+                        tool_call.function.arguments,
+                        ensure_ascii=False,
+                    ),
+                ),
+            )
+
+        usage = None
+        prompt_eval = getattr(response, "prompt_eval_count", None)
+        eval_count = getattr(response, "eval_count", None)
+        if prompt_eval is not None and eval_count is not None:
+            usage = ChatUsage(
+                input_tokens=prompt_eval,
+                output_tokens=eval_count,
+                time=(datetime.now() - start_datetime).total_seconds(),
+            )
+
+        return ChatResponse(
+            id=getattr(response, "id", None) or _generate_id(),
+            content=content_blocks,
+            is_last=True,
+            usage=usage,
+        )
diff --git a/src/agentscope/model/_ollama/_models/deepseek-r1-14b.yaml b/src/agentscope/model/_ollama/_models/deepseek-r1-14b.yaml
new file mode 100644
index 0000000..4e968ad
--- /dev/null
+++ b/src/agentscope/model/_ollama/_models/deepseek-r1-14b.yaml
@@ -0,0 +1,17 @@
+name: deepseek-r1:14b
+label: DeepSeek R1 14B
+status: active
+
+input_types:
+  - text/plain
+
+output_types:
+  - text/plain
+  - application/x-thinking
+
+context_size: 131072
+output_size: 8192
+
+parameter_overrides:
+  max_tokens:
+    maximum: 8192
diff --git a/src/agentscope/model/_ollama/_models/llama4.yaml b/src/agentscope/model/_ollama/_models/llama4.yaml
new file mode 100644
index 0000000..502df92
--- /dev/null
+++ b/src/agentscope/model/_ollama/_models/llama4.yaml
@@ -0,0 +1,22 @@
+name: llama4
+label: Llama 4 Scout
+status: active
+
+input_types:
+  - text/plain
+  - image/jpeg
+  - image/png
+  - image/gif
+  - image/webp
+
+output_types:
+  - text/plain
+
+context_size: 10485760
+output_size: 8192
+
+parameter_overrides:
+  max_tokens:
+    maximum: 8192
+  thinking_enable:
+    hidden: true
diff --git a/src/agentscope/model/_ollama/_models/qwen3-14b.yaml b/src/agentscope/model/_ollama/_models/qwen3-14b.yaml
new file mode 100644
index 0000000..e7fa983
--- /dev/null
+++ b/src/agentscope/model/_ollama/_models/qwen3-14b.yaml
@@ -0,0 +1,17 @@
+name: qwen3:14b
+label: Qwen3 14B
+status: active
+
+input_types:
+  - text/plain
+
+output_types:
+  - text/plain
+  - application/x-thinking
+
+context_size: 40960
+output_size: 8192
+
+parameter_overrides:
+  max_tokens:
+    maximum: 8192
diff --git a/src/agentscope/model/_ollama/_models/qwen3.5-9b.yaml b/src/agentscope/model/_ollama/_models/qwen3.5-9b.yaml
new file mode 100644
index 0000000..d517d33
--- /dev/null
+++ b/src/agentscope/model/_ollama/_models/qwen3.5-9b.yaml
@@ -0,0 +1,17 @@
+name: qwen3.5
+label: Qwen3.5 9B
+status: active
+
+input_types:
+  - text/plain
+
+output_types:
+  - text/plain
+  - application/x-thinking
+
+context_size: 262144
+output_size: 8192
+
+parameter_overrides:
+  max_tokens:
+    maximum: 8192
diff --git a/src/agentscope/model/_openai_chat/__init__.py b/src/agentscope/model/_openai_chat/__init__.py
new file mode 100644
index 0000000..c3e39e0
--- /dev/null
+++ b/src/agentscope/model/_openai_chat/__init__.py
@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+"""The OpenAI Chat Completions API modules."""
+
+from ._model import OpenAIChatModel
+
+__all__ = [
+    "OpenAIChatModel",
+]
diff --git a/src/agentscope/model/_openai_chat/_model.py b/src/agentscope/model/_openai_chat/_model.py
new file mode 100644
index 0000000..76a1bdd
--- /dev/null
+++ b/src/agentscope/model/_openai_chat/_model.py
@@ -0,0 +1,670 @@
+# -*- coding: utf-8 -*-
+"""The OpenAI Chat Completions model implementation."""
+import warnings
+import base64
+from collections import OrderedDict
+from datetime import datetime
+from typing import Literal, Any, AsyncGenerator, TYPE_CHECKING, List, Type
+
+from pydantic import BaseModel, Field
+
+from ..._utils._audio import _build_streaming_wav_header
+from ..._utils._common import _generate_id, _flatten_json_schema
+from .._base import ChatModelBase, _TOOL_CHOICE_LITERAL_MODES
+from .._model_response import ChatResponse, StructuredResponse
+from .._model_usage import ChatUsage
+from ...credential import OpenAICredential
+from ...formatter import FormatterBase, OpenAIChatFormatter
+from ...message import (
+    Msg,
+    ThinkingBlock,
+    ToolCallBlock,
+    TextBlock,
+    DataBlock,
+    Base64Source,
+)
+from ...tool import ToolChoice
+
+if TYPE_CHECKING:
+    from openai.types.chat import ChatCompletion
+    from openai import AsyncStream
+else:
+    ChatCompletion = Any
+    AsyncStream = Any
+
+
+class OpenAIChatModel(ChatModelBase):
+    """The OpenAI Chat Completions model."""
+
+    class Parameters(BaseModel):
+        """The parameters for the OpenAI Chat model."""
+
+        max_tokens: int | None = Field(
+            default=None,
+            title="Max Tokens",
+            description="The maximum number of tokens for the LLM output.",
+            gt=0,
+        )
+
+        thinking_enable: bool = Field(
+            default=False,
+            title="Thinking",
+            description=(
+                "Whether to enable reasoning for reasoning models "
+                "(e.g. o3, o4-mini, gpt-5.5). Use reasoning_effort to "
+                "control the depth of reasoning."
+            ),
+        )
+
+        reasoning_effort: (
+            Literal["none", "minimal", "low", "medium", "high", "xhigh"] | None
+        ) = Field(
+            default=None,
+            title="Reasoning Effort",
+            description=(
+                "Controls the depth of reasoning for reasoning models "
+                "(e.g. o3, o4-mini, gpt-5.5). Supported values are "
+                "model-dependent and may include: none, minimal, low, "
+                "medium, high, xhigh."
+            ),
+        )
+
+        temperature: float | None = Field(
+            default=None,
+            title="Temperature",
+            description="The temperature for the LLM output.",
+            ge=0,
+            le=2,
+        )
+
+        top_p: float | None = Field(
+            default=None,
+            title="Top P",
+            description="The top P value for the LLM output.",
+            gt=0,
+            le=1,
+        )
+
+        parallel_tool_calls: bool = Field(
+            default=True,
+            title="Parallel Tool Calls",
+            description="Whether to enable parallel tool calls.",
+        )
+
+        voice: str | None = Field(
+            default=None,
+            title="Voice",
+            description=(
+                "Voice for audio output on omni-style models (e.g. "
+                "``gpt-audio-mini``). Setting this implicitly asks the "
+                "model to speak its response — ``modalities`` is filled in "
+                "automatically. Supported voices vary by model — see the "
+                "model card's ``voice.suggestions``. Any value the API "
+                "accepts works — the suggestions are convenience-only. "
+                "Leave unset for text-only "
+                "responses."
+            ),
+        )
+
+    type: Literal["openai_chat"] = "openai_chat"
+    """The type of the chat model."""
+
+    def __init__(
+        self,
+        credential: OpenAICredential,
+        model: str,
+        parameters: "OpenAIChatModel.Parameters | None" = None,
+        stream: bool = True,
+        max_retries: int = 3,
+        retry_delay: float = 1.0,
+        context_size: int = 128000,
+        formatter: FormatterBase | None = None,
+        client_kwargs: dict[str, Any] | None = None,
+        extra_body: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize the OpenAI chat model.
+
+        Args:
+            credential (`OpenAICredential`):
+                The OpenAI credential used to authenticate API calls.
+            model (`str`):
+                The OpenAI model name, e.g. ``gpt-4.1``.
+            parameters (`OpenAIChatModel.Parameters | None`, defaults to \
+            `None`):
+                The OpenAI Chat API parameters. When ``None``, the default
+                parameters will be used.
+            stream (`bool`, defaults to `True`):
+                Whether to enable streaming output.
+            max_retries (`int`, defaults to `3`):
+                The maximum number of retries for the OpenAI API.
+            retry_delay (`float`, defaults to `1.0`):
+                Seconds to sleep between retry attempts.
+            context_size (`int`, defaults to `128000`):
+                The model context size used for context compression.
+            formatter (`FormatterBase | None`, defaults to `None`):
+                The formatter that converts ``Msg`` objects to the format
+                required by the OpenAI API. When ``None``, an
+                ``OpenAIChatFormatter`` instance will be used.
+            client_kwargs (`dict[str, Any] | None`, defaults to `None`):
+                Extra keyword arguments forwarded to ``openai.AsyncClient``
+                (e.g. ``timeout``, ``default_headers``, ``http_client``).
+            extra_body (`dict[str, Any] | None`, defaults to `None`):
+                Additional request body fields forwarded to
+                OpenAI-compatible APIs.
+        """
+        super().__init__(
+            credential=credential,
+            model=model,
+            parameters=parameters or self.Parameters(),
+            stream=stream,
+            max_retries=max_retries,
+            retry_delay=retry_delay,
+            context_size=context_size,
+        )
+        self.formatter = formatter or OpenAIChatFormatter()
+        self.client_kwargs = client_kwargs or {}
+        self.extra_body = dict(extra_body) if extra_body is not None else None
+
+    @classmethod
+    def _get_retryable_exceptions(cls) -> tuple[Type[Exception], ...]:
+        import openai
+
+        return (
+            openai.APIConnectionError,
+            openai.APITimeoutError,
+            openai.RateLimitError,
+            openai.InternalServerError,
+        )
+
+    async def _call_api(
+        self,
+        model_name: str,
+        messages: list[Msg],
+        tools: list[dict] | None = None,
+        tool_choice: ToolChoice | None = None,
+        **generate_kwargs: Any,
+    ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:
+        """Call the OpenAI Chat Completions API.
+
+        Args:
+            model_name (`str`):
+                The model name to use for this call.
+            messages (`list`):
+                A list of message dicts with ``role`` and ``content`` keys.
+            tools (`list[dict]`, default `None`):
+                The tools JSON schemas.
+            tool_choice (`ToolChoice | None`, optional):
+                Controls which (if any) tool is called by the model.
+            **generate_kwargs (`Any`):
+                Extra keyword arguments forwarded to the API.
+
+        Returns:
+            `ChatResponse | AsyncGenerator[ChatResponse, None]`:
+                A ``ChatResponse`` when streaming is disabled, or an async
+                generator of ``ChatResponse`` objects when streaming is
+                enabled.
+        """
+        import openai
+
+        client = openai.AsyncClient(
+            **{
+                "api_key": self.credential.api_key.get_secret_value(),
+                "organization": self.credential.organization,
+                "base_url": self.credential.base_url,
+                **self.client_kwargs,
+            },
+        )
+
+        formatted_messages = await self.formatter.format(messages)
+
+        kwargs: dict[str, Any] = {
+            "model": model_name,
+            "messages": formatted_messages,
+            "stream": self.stream,
+        }
+
+        if self.parameters.max_tokens is not None:
+            kwargs["max_tokens"] = self.parameters.max_tokens
+
+        if self.parameters.temperature is not None:
+            kwargs["temperature"] = self.parameters.temperature
+
+        if self.parameters.top_p is not None:
+            kwargs["top_p"] = self.parameters.top_p
+
+        if (
+            self.parameters.thinking_enable
+            and self.parameters.reasoning_effort
+        ):
+            kwargs["reasoning_effort"] = self.parameters.reasoning_effort
+
+        if self.parameters.voice is not None:
+            # Requesting audio output implies ``modalities`` must include
+            # ``"audio"``; set it automatically so callers don't have to.
+            # ``format`` is forced to ``pcm16``: OpenAI streaming only
+            # supports ``pcm16`` (other formats raise 400), and we re-wrap
+            # as WAV downstream so the frontend receives a playable block.
+            kwargs["audio"] = {
+                "voice": self.parameters.voice,
+                "format": "pcm16",
+            }
+            kwargs["modalities"] = ["text", "audio"]
+
+        if self.extra_body is not None:
+            kwargs["extra_body"] = dict(self.extra_body)
+
+        kwargs.update(generate_kwargs)
+
+        fmt_tools, fmt_tool_choice = self._format_tools(tools, tool_choice)
+
+        if fmt_tools:
+            kwargs["tools"] = fmt_tools
+            if not self.parameters.parallel_tool_calls:
+                kwargs["parallel_tool_calls"] = False
+
+        if fmt_tool_choice is not None:
+            kwargs["tool_choice"] = fmt_tool_choice
+
+        if self.stream:
+            kwargs["stream_options"] = {"include_usage": True}
+
+        start_datetime = datetime.now()
+        response = await client.chat.completions.create(**kwargs)
+
+        audio_cfg = kwargs.get("audio")
+        audio_fmt = (
+            audio_cfg.get("format", "wav")
+            if isinstance(audio_cfg, dict)
+            else "wav"
+        )
+
+        if self.stream:
+            # Streaming wire format is always ``pcm16`` (forced above) and we
+            # re-wrap it as WAV before yielding, so downstream sees ``wav``.
+            return self._parse_stream_response(
+                start_datetime,
+                response,
+            )
+
+        return self._parse_completion_response(
+            start_datetime,
+            response,
+            audio_fmt,
+        )
+
+    async def _parse_stream_response(
+        self,
+        start_datetime: datetime,
+        response: AsyncStream,
+    ) -> AsyncGenerator[ChatResponse, None]:
+        """Parse the OpenAI Chat streaming response.
+
+        Upstream sends raw PCM16 (24kHz, 16-bit mono — OpenAI's only
+        streaming-supported audio format). We prefix the first audio
+        chunk with a streaming WAV header so the frontend can start
+        playback immediately; downstream accumulation is handled by
+        ``ChatResponse.append_data_block``.
+
+        Args:
+            start_datetime (`datetime`):
+                The start datetime of the response generation.
+            response (`AsyncStream`):
+                The OpenAI async stream object.
+
+        Yields:
+            `ChatResponse`:
+                Incremental ``ChatResponse`` objects with ``is_last=False``.
+                The base class ``__call__`` accumulates them and emits the
+                final ``is_last=True`` chunk.
+        """
+        # ``True`` once the first audio chunk has been prefixed with a
+        # streaming WAV header and yielded.
+        audio_header_sent: bool = False
+
+        usage = None
+        response_id: str = _generate_id()
+        text_id: str = _generate_id()
+        thinking_id: str = _generate_id()
+        audio_id: str = _generate_id()
+        # The mapping from index to (tool call id, tool call name)
+        tool_call_mapping: dict = OrderedDict()
+
+        async with response as stream:
+            async for chunk in stream:
+                delta_res = ChatResponse(
+                    content=[],
+                    is_last=False,
+                    id=response_id,
+                )
+
+                # Update the response ID if exists
+                response_id = getattr(chunk, "id", None) or response_id
+                delta_res.id = response_id
+
+                if chunk.usage:
+                    u = chunk.usage
+                    details = getattr(u, "prompt_tokens_details", None)
+                    usage = ChatUsage(
+                        input_tokens=u.prompt_tokens,
+                        output_tokens=u.completion_tokens,
+                        time=(datetime.now() - start_datetime).total_seconds(),
+                        cache_input_tokens=getattr(
+                            details,
+                            "cached_tokens",
+                            0,
+                        )
+                        if details
+                        else 0,
+                    )
+
+                if not chunk.choices:
+                    if delta_res.content or usage:
+                        delta_res.usage = usage
+                        yield delta_res
+                    continue
+
+                choice = chunk.choices[0]
+                delta = choice.delta
+
+                # Thinking
+                delta_thinking = getattr(delta, "reasoning_content", None)
+                if not isinstance(delta_thinking, str):
+                    delta_thinking = getattr(delta, "reasoning", None)
+                if isinstance(delta_thinking, str) and delta_thinking:
+                    delta_res.append_thinking(
+                        block_id=thinking_id,
+                        thinking=delta_thinking,
+                    )
+
+                # Text
+                delta_text = getattr(delta, "content", None) or ""
+
+                # Audio (delta.audio.data / delta.audio.transcript). Omni
+                # models deliver text via ``delta.audio.transcript`` rather
+                # than ``delta.content``; fold it into ``delta_text`` so the
+                # agent's streaming pipeline emits ``TextBlockDelta`` events
+                # alongside the audio chunks.
+                delta_audio = getattr(delta, "audio", None)
+                if delta_audio is not None:
+                    if isinstance(delta_audio, dict):
+                        audio_chunk = delta_audio.get("data", "") or ""
+                        transcript_chunk = (
+                            delta_audio.get("transcript", "") or ""
+                        )
+                    else:
+                        audio_chunk = getattr(delta_audio, "data", "") or ""
+                        transcript_chunk = (
+                            getattr(delta_audio, "transcript", "") or ""
+                        )
+                    if transcript_chunk:
+                        delta_text += transcript_chunk
+                    if audio_chunk:
+                        pcm_bytes = base64.b64decode(audio_chunk)
+                        if not audio_header_sent:
+                            payload = _build_streaming_wav_header() + pcm_bytes
+                            audio_header_sent = True
+                        else:
+                            payload = pcm_bytes
+                        # ``append_data_block`` expects the raw incremental
+                        # media bytes and handles base64 encoding internally
+                        # (see ``ChatResponse.append_data_block``); passing an
+                        # already base64-encoded string here would result in
+                        # double-encoding.
+                        delta_res.append_data_block(
+                            block_id=audio_id,
+                            data=payload,
+                            media_type="audio/wav",
+                        )
+
+                if delta_text:
+                    delta_res.append_text(
+                        block_id=text_id,
+                        text=delta_text,
+                    )
+
+                # Tool call
+                for tool_call in getattr(delta, "tool_calls", None) or []:
+                    index = tool_call.index
+                    fn = getattr(tool_call, "function", None)
+                    delta_name = getattr(fn, "name", None) if fn else None
+                    delta_args = getattr(fn, "arguments", None) if fn else None
+
+                    # Record the id and name in case following deltas
+                    # don't provide them
+                    if index not in tool_call_mapping:
+                        tool_call_mapping[index] = (
+                            tool_call.id,
+                            delta_name or "unknown",
+                        )
+
+                    stored_id, stored_name = tool_call_mapping[index]
+
+                    delta_res.append_tool_call(
+                        block_id=tool_call.id or stored_id,
+                        name=delta_name or stored_name,
+                        input=delta_args or "",
+                    )
+
+                if delta_res.content or usage:
+                    delta_res.usage = usage
+                    yield delta_res
+
+    def _parse_completion_response(
+        self,
+        start_datetime: datetime,
+        response: ChatCompletion,
+        audio_format: str = "wav",
+    ) -> ChatResponse:
+        """Parse the OpenAI Chat non-streaming response.
+
+        Args:
+            start_datetime (`datetime`):
+                The start datetime of the response generation.
+            response (`ChatCompletion`):
+                The OpenAI chat completion object.
+            audio_format (`str`, defaults to ``"wav"``):
+                The audio format requested (used to set the media type on
+                the output ``DataBlock``).
+
+        Returns:
+            `ChatResponse`:
+                A single ``ChatResponse`` with ``is_last=True``.
+        """
+        content_blocks: List[
+            TextBlock | ToolCallBlock | ThinkingBlock | DataBlock
+        ] = []
+
+        if response.choices:
+            choice = response.choices[0]
+            reasoning = getattr(choice.message, "reasoning_content", None)
+            if not isinstance(reasoning, str):
+                reasoning = getattr(choice.message, "reasoning", None)
+            if isinstance(reasoning, str) and reasoning:
+                content_blocks.append(ThinkingBlock(thinking=reasoning))
+
+            if choice.message.content:
+                content_blocks.append(TextBlock(text=choice.message.content))
+
+            # Extract audio output (message.audio.data /
+            # message.audio.transcript)
+            audio_obj = getattr(choice.message, "audio", None)
+            if audio_obj is not None:
+                if isinstance(audio_obj, dict):
+                    audio_data = audio_obj.get("data", "")
+                    audio_transcript = audio_obj.get("transcript", "")
+                else:
+                    audio_data = getattr(audio_obj, "data", "") or ""
+                    audio_transcript = (
+                        getattr(audio_obj, "transcript", "") or ""
+                    )
+                if not choice.message.content and audio_transcript:
+                    content_blocks.append(TextBlock(text=audio_transcript))
+                if audio_data:
+                    content_blocks.append(
+                        DataBlock(
+                            source=Base64Source(
+                                data=audio_data,
+                                media_type=f"audio/{audio_format}",
+                            ),
+                        ),
+                    )
+
+            for tool_call in choice.message.tool_calls or []:
+                content_blocks.append(
+                    ToolCallBlock(
+                        id=tool_call.id,
+                        name=tool_call.function.name,
+                        input=tool_call.function.arguments,
+                    ),
+                )
+
+        usage = None
+        if response.usage:
+            u = response.usage
+            details = getattr(u, "prompt_tokens_details", None)
+            usage = ChatUsage(
+                input_tokens=u.prompt_tokens,
+                output_tokens=u.completion_tokens,
+                time=(datetime.now() - start_datetime).total_seconds(),
+                cache_input_tokens=getattr(
+                    details,
+                    "cached_tokens",
+                    0,
+                )
+                if details
+                else 0,
+            )
+
+        resp_kwargs: dict[str, Any] = {
+            "content": content_blocks,
+            "is_last": True,
+            "usage": usage,
+        }
+        response_id = getattr(response, "id", None)
+        if response_id:
+            resp_kwargs["id"] = response_id
+
+        return ChatResponse(**resp_kwargs)
+
+    async def _call_api_with_structured_output(
+        self,
+        model_name: str,
+        messages: list[Msg],
+        structured_model: Type[BaseModel] | dict,
+        tool_choice: ToolChoice | None = None,
+        **kwargs: Any,
+    ) -> StructuredResponse:
+        """OpenAI-compatible override for structured output.
+
+        Some third-party providers that expose an OpenAI-compatible API (e.g.
+        DeepSeek via DashScope) reject forced ``tool_choice`` when thinking
+        mode is active.  When such a ``BadRequestError`` is encountered, this
+        method automatically retries with ``tool_choice="auto"``.
+        """
+        import openai
+
+        try:
+            return await super()._call_api_with_structured_output(
+                model_name=model_name,
+                messages=messages,
+                structured_model=structured_model,
+                tool_choice=tool_choice,
+                **kwargs,
+            )
+        except openai.BadRequestError as e:
+            if "tool_choice" not in str(e):
+                raise
+            # Thinking mode rejects forced tool_choice; fall back to auto
+            warnings.warn(
+                f"Forced tool_choice rejected by provider ({e}), "
+                "retrying with tool_choice='auto'.",
+                stacklevel=2,
+            )
+            return await super()._call_api_with_structured_output(
+                model_name=model_name,
+                messages=messages,
+                structured_model=structured_model,
+                tool_choice=ToolChoice(mode="auto"),
+                **kwargs,
+            )
+
+    def _format_tools(
+        self,
+        tools: list[dict] | None,
+        tool_choice: ToolChoice | None,
+    ) -> tuple[list[dict] | None, str | dict | None]:
+        """Validate, filter, and format tools and tool_choice for the OpenAI
+        Chat Completions API.
+
+        When ``tool_choice.tools`` is specified the schemas list is filtered
+        to only those tools. When ``tool_choice.mode`` is a specific tool name
+        (str) the model is forced to call exactly that tool without needing to
+        filter the list, preserving prompt-cache efficiency.
+
+        Tool parameter schemas are flattened (``$ref`` / ``$defs`` resolved
+        inline) so that providers which do not support JSON Schema references
+        (e.g. GLM-5.x via OpenCode Go) receive a self-contained schema.
+
+        Args:
+            tools (`list[dict] | None`, optional):
+                The raw tool schemas.
+            tool_choice (`ToolChoice | None`, optional):
+                The tool choice configuration.
+
+        Returns:
+            `tuple[list[dict] | None, str | dict | None]`:
+                A tuple of (formatted_tools, formatted_tool_choice).
+        """
+        if tool_choice and tools:
+            self._validate_tool_choice(tool_choice, tools)
+            if tool_choice.tools:
+                allowed = set(tool_choice.tools)
+                tools = [t for t in tools if t["function"]["name"] in allowed]
+
+        if tools:
+            tools = self._flatten_tool_schemas(tools)
+
+        if not tool_choice:
+            return tools, None
+
+        mode = tool_choice.mode
+
+        if mode not in _TOOL_CHOICE_LITERAL_MODES:
+            return tools, {"type": "function", "function": {"name": mode}}
+
+        return tools, mode
+
+    @staticmethod
+    def _flatten_tool_schemas(
+        tools: list[dict],
+    ) -> list[dict]:
+        """Inline ``$ref`` / ``$defs`` in each tool's parameter schema.
+
+        Args:
+            tools (`list[dict]`):
+                The list of tool dicts, each with a ``"function"`` key
+                containing the tool name, description and ``"parameters"``
+                JSON schema.
+
+        Returns:
+            `list[dict]`:
+                A new list where each tool's ``parameters`` schema has all
+                local ``$ref`` / ``$defs`` resolved inline.  Tools whose
+                schema contained no references are returned unchanged (same
+                object identity).
+        """
+        result = []
+        for tool in tools:
+            func = tool.get("function")
+            if not isinstance(func, dict):
+                result.append(tool)
+                continue
+            params = func.get("parameters")
+            if not isinstance(params, dict):
+                result.append(tool)
+                continue
+            flat = _flatten_json_schema(params)
+            if flat is not params:
+                tool = {**tool, "function": {**func, "parameters": flat}}
+            result.append(tool)
+        return result
diff --git a/src/agentscope/model/_openai_chat/_models/gpt-4.1-mini.yaml b/src/agentscope/model/_openai_chat/_models/gpt-4.1-mini.yaml
new file mode 100644
index 0000000..cc66dca
--- /dev/null
+++ b/src/agentscope/model/_openai_chat/_models/gpt-4.1-mini.yaml
@@ -0,0 +1,28 @@
+name: gpt-4.1-mini
+label: GPT-4.1 Mini
+status: active
+
+input_types:
+  - text/plain
+  - image/jpeg
+  - image/png
+  - image/gif
+  - image/webp
+
+output_types:
+  - text/plain
+
+context_size: 1047576
+output_size: 32768
+
+parameter_overrides:
+  max_tokens:
+    maximum: 32768
+  thinking_enable:
+    hidden: true
+  reasoning_effort:
+    hidden: true
+  # Voice only applies to omni-style models; hide the field for this
+  # non-omni model so the frontend popover doesn't render it.
+  voice:
+    hidden: true
diff --git a/src/agentscope/model/_openai_chat/_models/gpt-4.1-nano.yaml b/src/agentscope/model/_openai_chat/_models/gpt-4.1-nano.yaml
new file mode 100644
index 0000000..bf26d9d
--- /dev/null
+++ b/src/agentscope/model/_openai_chat/_models/gpt-4.1-nano.yaml
@@ -0,0 +1,28 @@
+name: gpt-4.1-nano
+label: GPT-4.1 Nano
+status: active
+
+input_types:
+  - text/plain
+  - image/jpeg
+  - image/png
+  - image/gif
+  - image/webp
+
+output_types:
+  - text/plain
+
+context_size: 1047576
+output_size: 32768
+
+parameter_overrides:
+  max_tokens:
+    maximum: 32768
+  thinking_enable:
+    hidden: true
+  reasoning_effort:
+    hidden: true
+  # Voice only applies to omni-style models; hide the field for this
+  # non-omni model so the frontend popover doesn't render it.
+  voice:
+    hidden: true
diff --git a/src/agentscope/model/_openai_chat/_models/gpt-4.1.yaml b/src/agentscope/model/_openai_chat/_models/gpt-4.1.yaml
new file mode 100644
index 0000000..f26b143
--- /dev/null
+++ b/src/agentscope/model/_openai_chat/_models/gpt-4.1.yaml
@@ -0,0 +1,26 @@
+name: gpt-4.1
+label: GPT-4.1
+status: active
+
+input_types:
+  - text/plain
+  - image/jpeg
+  - image/png
+  - image/gif
+  - image/webp
+
+output_types:
+  - text/plain
+
+context_size: 1047576
+output_size: 32768
+
+parameter_overrides:
+  max_tokens:
+    maximum: 32768
+  thinking_enable:
+    hidden: true
+  # Voice only applies to omni-style models; hide the field for this
+  # non-omni model so the frontend popover doesn't render it.
+  voice:
+    hidden: true
diff --git a/src/agentscope/model/_openai_chat/_models/gpt-4o-mini.yaml b/src/agentscope/model/_openai_chat/_models/gpt-4o-mini.yaml
new file mode 100644
index 0000000..b41ac17
--- /dev/null
+++ b/src/agentscope/model/_openai_chat/_models/gpt-4o-mini.yaml
@@ -0,0 +1,28 @@
+name: gpt-4o-mini
+label: GPT-4o Mini
+status: active
+
+input_types:
+  - text/plain
+  - image/jpeg
+  - image/png
+  - image/gif
+  - image/webp
+
+output_types:
+  - text/plain
+
+context_size: 128000
+output_size: 16384
+
+parameter_overrides:
+  max_tokens:
+    maximum: 16384
+  thinking_enable:
+    hidden: true
+  reasoning_effort:
+    hidden: true
+  # Voice only applies to omni-style models; hide the field for this
+  # non-omni model so the frontend popover doesn't render it.
+  voice:
+    hidden: true
diff --git a/src/agentscope/model/_openai_chat/_models/gpt-4o.yaml b/src/agentscope/model/_openai_chat/_models/gpt-4o.yaml
new file mode 100644
index 0000000..5b19e68
--- /dev/null
+++ b/src/agentscope/model/_openai_chat/_models/gpt-4o.yaml
@@ -0,0 +1,28 @@
+name: gpt-4o
+label: GPT-4o
+status: active
+
+input_types:
+  - text/plain
+  - image/jpeg
+  - image/png
+  - image/gif
+  - image/webp
+
+output_types:
+  - text/plain
+
+context_size: 128000
+output_size: 16384
+
+parameter_overrides:
+  max_tokens:
+    maximum: 16384
+  thinking_enable:
+    hidden: true
+  reasoning_effort:
+    hidden: true
+  # Voice only applies to omni-style models; hide the field for this
+  # non-omni model so the frontend popover doesn't render it.
+  voice:
+    hidden: true
diff --git a/src/agentscope/model/_openai_chat/_models/gpt-5.4.yaml b/src/agentscope/model/_openai_chat/_models/gpt-5.4.yaml
new file mode 100644
index 0000000..dec7e31
--- /dev/null
+++ b/src/agentscope/model/_openai_chat/_models/gpt-5.4.yaml
@@ -0,0 +1,26 @@
+name: gpt-5.4
+label: GPT-5.4
+status: active
+
+input_types:
+  - text/plain
+  - image/jpeg
+  - image/png
+  - image/gif
+  - image/webp
+
+output_types:
+  - text/plain
+
+context_size: 1050000
+output_size: 128000
+
+parameter_overrides:
+  max_tokens:
+    maximum: 128000
+  thinking_enable:
+    hidden: true
+  # Voice only applies to omni-style models; hide the field for this
+  # non-omni model so the frontend popover doesn't render it.
+  voice:
+    hidden: true
diff --git a/src/agentscope/model/_openai_chat/_models/gpt-5.5.yaml b/src/agentscope/model/_openai_chat/_models/gpt-5.5.yaml
new file mode 100644
index 0000000..1e009e3
--- /dev/null
+++ b/src/agentscope/model/_openai_chat/_models/gpt-5.5.yaml
@@ -0,0 +1,30 @@
+name: gpt-5.5
+label: GPT-5.5
+status: active
+
+input_types:
+  - text/plain
+  - image/jpeg
+  - image/png
+  - image/gif
+  - image/webp
+  - audio/mp3
+  - audio/wav
+
+output_types:
+  - text/plain
+
+context_size: 1050000
+output_size: 128000
+
+parameter_overrides:
+  max_tokens:
+    maximum: 128000
+  thinking_enable:
+    hidden: true
+  reasoning_effort:
+    hidden: true
+  # Voice only applies to omni-style models; hide the field for this
+  # non-omni model so the frontend popover doesn't render it.
+  voice:
+    hidden: true
diff --git a/src/agentscope/model/_openai_chat/_models/gpt-audio-mini.yaml b/src/agentscope/model/_openai_chat/_models/gpt-audio-mini.yaml
new file mode 100644
index 0000000..5877d68
--- /dev/null
+++ b/src/agentscope/model/_openai_chat/_models/gpt-audio-mini.yaml
@@ -0,0 +1,31 @@
+name: gpt-audio-mini
+label: GPT Audio Mini
+status: active
+
+input_types:
+  - text/plain
+  - audio/wav
+  - audio/mp3
+
+output_types:
+  - text/plain
+  - audio/wav
+
+context_size: 128000
+output_size: 16384
+
+parameter_overrides:
+  max_tokens:
+    maximum: 16384
+  thinking_enable:
+    hidden: true
+  # Source: https://platform.openai.com/docs/guides/text-to-speech
+  voice:
+    default: alloy
+    enum:
+      - alloy
+      - echo
+      - nova
+      - shimmer
+      - sage
+      - verse
diff --git a/src/agentscope/model/_openai_chat/_models/o3.yaml b/src/agentscope/model/_openai_chat/_models/o3.yaml
new file mode 100644
index 0000000..13e7762
--- /dev/null
+++ b/src/agentscope/model/_openai_chat/_models/o3.yaml
@@ -0,0 +1,25 @@
+name: o3
+label: o3
+status: active
+
+input_types:
+  - text/plain
+  - image/jpeg
+  - image/png
+  - image/gif
+  - image/webp
+
+output_types:
+  - text/plain
+  - application/x-thinking
+
+context_size: 200000
+output_size: 100000
+
+parameter_overrides:
+  max_tokens:
+    maximum: 100000
+  # Voice only applies to omni-style models; hide the field for this
+  # non-omni model so the frontend popover doesn't render it.
+  voice:
+    hidden: true
diff --git a/src/agentscope/model/_openai_chat/_models/o4-mini.yaml b/src/agentscope/model/_openai_chat/_models/o4-mini.yaml
new file mode 100644
index 0000000..ab2e911
--- /dev/null
+++ b/src/agentscope/model/_openai_chat/_models/o4-mini.yaml
@@ -0,0 +1,25 @@
+name: o4-mini
+label: o4-mini
+status: active
+
+input_types:
+  - text/plain
+  - image/jpeg
+  - image/png
+  - image/gif
+  - image/webp
+
+output_types:
+  - text/plain
+  - application/x-thinking
+
+context_size: 200000
+output_size: 100000
+
+parameter_overrides:
+  max_tokens:
+    maximum: 100000
+  # Voice only applies to omni-style models; hide the field for this
+  # non-omni model so the frontend popover doesn't render it.
+  voice:
+    hidden: true
diff --git a/src/agentscope/model/_openai_response/__init__.py b/src/agentscope/model/_openai_response/__init__.py
new file mode 100644
index 0000000..d6cbb08
--- /dev/null
+++ b/src/agentscope/model/_openai_response/__init__.py
@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+"""The OpenAI Responses API modules."""
+
+from ._model import OpenAIResponseModel
+
+__all__ = [
+    "OpenAIResponseModel",
+]
diff --git a/src/agentscope/model/_openai_response/_model.py b/src/agentscope/model/_openai_response/_model.py
new file mode 100644
index 0000000..9155f64
--- /dev/null
+++ b/src/agentscope/model/_openai_response/_model.py
@@ -0,0 +1,485 @@
+# -*- coding: utf-8 -*-
+"""The OpenAI Responses API chat model implementation."""
+from collections import OrderedDict
+from datetime import datetime
+from typing import Literal, Any, AsyncGenerator, List, TYPE_CHECKING, Type
+
+from pydantic import BaseModel, Field
+
+from ..._utils._common import _generate_id
+from .._base import ChatModelBase, _TOOL_CHOICE_LITERAL_MODES
+from .._model_response import ChatResponse
+from .._model_usage import ChatUsage
+from ...credential import OpenAICredential
+from ...formatter import FormatterBase, OpenAIResponseFormatter
+from ...message import Msg, ThinkingBlock, ToolCallBlock, TextBlock
+from ...tool import ToolChoice
+
+if TYPE_CHECKING:
+    from openai.types.responses import Response
+    from openai.types.responses import ResponseStreamEvent
+    from openai import AsyncStream
+else:
+    Response = Any
+    ResponseStreamEvent = Any
+    AsyncStream = Any
+
+# kwargs accepted by Chat Completions but NOT by the Responses API.
+_RESPONSES_UNSUPPORTED_KWARGS = frozenset({"modalities", "audio"})
+
+
+class OpenAIResponseModel(ChatModelBase):
+    """The OpenAI Responses API chat model.
+
+    Compared with the Chat Completions API, the Responses API provides
+    first-class streaming events for reasoning / thinking, text output
+    and function-call arguments, which makes it a natural fit for models
+    that expose chain-of-thought reasoning (e.g. ``o3``, ``o4-mini``).
+    """
+
+    class Parameters(BaseModel):
+        """The parameters for the OpenAI Response API model."""
+
+        max_tokens: int | None = Field(
+            default=None,
+            title="Max Tokens",
+            description="The maximum number of output tokens.",
+            gt=0,
+        )
+
+        thinking_enable: bool = Field(
+            default=False,
+            title="Thinking",
+            description=(
+                "Whether to enable reasoning for reasoning models "
+                "(e.g. o3, o4-mini, gpt-5.5). Use reasoning_effort to "
+                "control the depth of reasoning."
+            ),
+        )
+
+        reasoning_effort: (
+            Literal["none", "minimal", "low", "medium", "high", "xhigh"] | None
+        ) = Field(
+            default=None,
+            title="Reasoning Effort",
+            description=(
+                "Controls the depth of reasoning for reasoning models "
+                "(e.g. o3, o4-mini, gpt-5.5). Supported values are "
+                "model-dependent and may include: none, minimal, low, "
+                "medium, high, xhigh."
+            ),
+        )
+
+        temperature: float | None = Field(
+            default=None,
+            title="Temperature",
+            description="The temperature for the LLM output.",
+            ge=0,
+            le=2,
+        )
+
+    type: Literal["openai_response"] = "openai_response"
+    """The type of the chat model."""
+
+    def __init__(
+        self,
+        credential: OpenAICredential,
+        model: str,
+        parameters: "OpenAIResponseModel.Parameters | None" = None,
+        stream: bool = True,
+        max_retries: int = 3,
+        retry_delay: float = 1.0,
+        context_size: int = 200000,
+        formatter: FormatterBase | None = None,
+        client_kwargs: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize the OpenAI Responses API chat model.
+
+        Args:
+            credential (`OpenAICredential`):
+                The OpenAI credential used to authenticate API calls.
+            model (`str`):
+                The OpenAI model name, e.g. ``o3`` or ``o4-mini``.
+            parameters (`OpenAIResponseModel.Parameters | None`, defaults \
+            to `None`):
+                The OpenAI Responses API parameters. When ``None``, the
+                default parameters will be used.
+            stream (`bool`, defaults to `True`):
+                Whether to enable streaming output.
+            max_retries (`int`, defaults to `3`):
+                The maximum number of retries for the OpenAI Responses API.
+            retry_delay (`float`, defaults to `1.0`):
+                Seconds to sleep between retry attempts.
+            context_size (`int`, defaults to `200000`):
+                The model context size used for context compression.
+            formatter (`FormatterBase | None`, defaults to `None`):
+                The formatter that converts ``Msg`` objects to the format
+                required by the OpenAI Responses API. When ``None``, an
+                ``OpenAIResponseFormatter`` instance will be used.
+            client_kwargs (`dict[str, Any] | None`, defaults to `None`):
+                Extra keyword arguments forwarded to ``openai.AsyncClient``
+                (e.g. ``timeout``, ``default_headers``, ``http_client``).
+        """
+        super().__init__(
+            credential=credential,
+            model=model,
+            parameters=parameters or self.Parameters(),
+            stream=stream,
+            max_retries=max_retries,
+            retry_delay=retry_delay,
+            context_size=context_size,
+        )
+        self.formatter = formatter or OpenAIResponseFormatter()
+        self.client_kwargs = client_kwargs or {}
+
+    @classmethod
+    def _get_retryable_exceptions(cls) -> tuple[Type[Exception], ...]:
+        import openai
+
+        return (
+            openai.APIConnectionError,
+            openai.APITimeoutError,
+            openai.RateLimitError,
+            openai.InternalServerError,
+        )
+
+    async def _call_api(
+        self,
+        model_name: str,
+        messages: list[Msg],
+        tools: list[dict] | None = None,
+        tool_choice: ToolChoice | None = None,
+        **generate_kwargs: Any,
+    ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:
+        """Call the OpenAI Responses API.
+
+        Args:
+            model_name (`str`):
+                The model name to use for this call.
+            messages (`list`):
+                A list of input items for the Responses API.
+            tools (`list[dict]`, default `None`):
+                The tools JSON schemas.
+            tool_choice (`ToolChoice | None`, optional):
+                Controls which (if any) tool is called by the model.
+            **generate_kwargs (`Any`):
+                Extra keyword arguments forwarded to the API.
+
+        Returns:
+            `ChatResponse | AsyncGenerator[ChatResponse, None]`:
+                A ``ChatResponse`` when streaming is disabled, or an async
+                generator of ``ChatResponse`` objects when streaming is
+                enabled.
+        """
+        import openai
+
+        client = openai.AsyncClient(
+            **{
+                "api_key": self.credential.api_key.get_secret_value(),
+                "organization": self.credential.organization,
+                "base_url": self.credential.base_url,
+                **self.client_kwargs,
+            },
+        )
+
+        formatted_messages = await self.formatter.format(messages)
+
+        api_kwargs: dict[str, Any] = {
+            "model": model_name,
+            "input": formatted_messages,
+            "stream": self.stream,
+        }
+
+        if self.parameters.max_tokens is not None:
+            api_kwargs["max_output_tokens"] = self.parameters.max_tokens
+
+        if self.parameters.temperature is not None:
+            api_kwargs["temperature"] = self.parameters.temperature
+
+        if (
+            self.parameters.thinking_enable
+            and self.parameters.reasoning_effort
+        ):
+            api_kwargs["reasoning"] = {
+                "effort": self.parameters.reasoning_effort,
+            }
+
+        # The Responses API does not yet support audio output
+        # (modalities / audio params).  Strip them so callers that
+        # mistakenly pass Chat-Completions-style audio kwargs don't
+        # trigger a TypeError.
+        # https://developers.openai.com/api/docs/guides/migrate-to-responses
+        api_kwargs.update(
+            {
+                k: v
+                for k, v in generate_kwargs.items()
+                if k not in _RESPONSES_UNSUPPORTED_KWARGS
+            },
+        )
+
+        fmt_tools, fmt_tool_choice = self._format_tools(tools, tool_choice)
+        if fmt_tools is not None:
+            api_kwargs["tools"] = fmt_tools
+        if fmt_tool_choice is not None:
+            api_kwargs["tool_choice"] = fmt_tool_choice
+
+        start_datetime = datetime.now()
+        response = await client.responses.create(**api_kwargs)
+
+        if self.stream:
+            return self._parse_stream_response(start_datetime, response)
+
+        return self._parse_completion_response(start_datetime, response)
+
+    async def _parse_stream_response(
+        self,
+        start_datetime: datetime,
+        response: "AsyncStream[ResponseStreamEvent]",
+    ) -> AsyncGenerator[ChatResponse, None]:
+        """Parse the OpenAI Responses API streaming response.
+
+        Each event yields only the *delta* content produced by that event so
+        that the base ``ChatModelBase.__call__`` can accumulate the full
+        response. Because the Responses API only returns the upstream
+        response id on the final ``response.completed`` event, we assign a
+        locally-generated ``response_id`` up-front so every delta chunk
+        carries a stable id.
+
+        Args:
+            start_datetime (`datetime`):
+                The start datetime of the response generation.
+            response (`AsyncStream[ResponseStreamEvent]`):
+                The OpenAI Responses API async stream object.
+
+        Yields:
+            `ChatResponse`:
+                Incremental ``ChatResponse`` objects with ``is_last=False``.
+                The base class ``__call__`` accumulates them and emits the
+                final ``is_last=True`` chunk.
+        """
+        usage: ChatUsage | None = None
+        response_id: str = _generate_id()
+        text_id: str = _generate_id()
+        thinking_id: str = _generate_id()
+        # Mapping from Responses API item id (fc_xxx) to (call_id, name)
+        # so subsequent argument deltas can be routed to the right tool
+        # call block.
+        tool_call_mapping: dict = OrderedDict()
+
+        async for event in response:
+            event_type = event.type
+            delta_res = ChatResponse(
+                content=[],
+                is_last=False,
+                id=response_id,
+            )
+
+            if event_type == "response.reasoning_summary_text.delta":
+                # Reasoning summary text is NOT emitted by all models.
+                # As of 2026-05, o1 and o4-mini do not stream reasoning
+                # summary deltas. This handler exists for forward
+                # compatibility with models that do expose it.
+                delta_res.append_thinking(
+                    event.delta,
+                    block_id=thinking_id,
+                )
+
+            elif event_type == "response.output_text.delta":
+                delta_res.append_text(event.delta, block_id=text_id)
+
+            elif event_type == "response.output_item.added":
+                item = event.item
+                if getattr(item, "type", None) == "function_call":
+                    # item.call_id (call_xxx) is used as ToolCallBlock.id
+                    # so the formatter can echo it back as
+                    # function_call.call_id / function_call_output.call_id.
+                    # Only record the mapping here — do NOT emit an
+                    # empty-input delta so downstream consumers don't see
+                    # a leading no-op chunk. The block is created on the
+                    # first argument delta below.
+                    tool_call_mapping[item.id] = (
+                        item.call_id,
+                        getattr(item, "name", "") or "unknown",
+                    )
+
+            elif event_type == "response.function_call_arguments.delta":
+                item_id = event.item_id
+                if item_id in tool_call_mapping:
+                    call_id, name = tool_call_mapping[item_id]
+                    delta_res.append_tool_call(
+                        block_id=call_id,
+                        name=name,
+                        input=event.delta or "",
+                    )
+
+            elif event_type == "response.completed":
+                resp = event.response
+                if resp.usage:
+                    u = resp.usage
+                    details = getattr(u, "input_tokens_details", None)
+                    usage = ChatUsage(
+                        input_tokens=u.input_tokens,
+                        output_tokens=u.output_tokens,
+                        time=(datetime.now() - start_datetime).total_seconds(),
+                        cache_input_tokens=getattr(
+                            details,
+                            "cached_tokens",
+                            0,
+                        )
+                        if details
+                        else 0,
+                    )
+                # Attach reasoning item id metadata from the completed
+                # response so the formatter can echo it back in
+                # multi-turn history. The Responses API requires every
+                # function_call item to be accompanied by its preceding
+                # reasoning item (see the function-calling guide); the
+                # reasoning item may have an empty summary when the model
+                # does not expose it (e.g. o1/o4-mini as of 2026-05).
+                for output_item in getattr(resp, "output", []):
+                    if getattr(output_item, "type", None) == "reasoning":
+                        reasoning_item_id = getattr(output_item, "id", None)
+                        if reasoning_item_id:
+                            delta_res.append_thinking(
+                                thinking="",
+                                block_id=thinking_id,
+                                reasoning_item_id=reasoning_item_id,
+                            )
+
+            if delta_res.content or usage:
+                delta_res.usage = usage
+                yield delta_res
+
+    def _parse_completion_response(
+        self,
+        start_datetime: datetime,
+        response: "Response",
+    ) -> ChatResponse:
+        """Parse the OpenAI Responses API non-streaming response.
+
+        Args:
+            start_datetime (`datetime`):
+                The start datetime of the response generation.
+            response (`Response`):
+                The OpenAI Responses API response object.
+
+        Returns:
+            `ChatResponse`:
+                A single ``ChatResponse`` with ``is_last=True``.
+        """
+        content_blocks: List[TextBlock | ToolCallBlock | ThinkingBlock] = []
+
+        for item in response.output:
+            item_type = getattr(item, "type", None)
+
+            if item_type == "reasoning":
+                reasoning_item_id = getattr(item, "id", None)
+                combined_summary = " ".join(
+                    getattr(s, "text", "")
+                    for s in getattr(item, "summary", [])
+                    if getattr(s, "text", "")
+                )
+                if combined_summary:
+                    content_blocks.append(
+                        ThinkingBlock(
+                            type="thinking",
+                            thinking=combined_summary,
+                            reasoning_item_id=reasoning_item_id,
+                        ),
+                    )
+
+            elif item_type == "message":
+                for part in getattr(item, "content", []):
+                    if getattr(part, "type", None) == "output_text":
+                        content_blocks.append(
+                            TextBlock(type="text", text=part.text),
+                        )
+
+            elif item_type == "function_call":
+                content_blocks.append(
+                    ToolCallBlock(
+                        id=item.call_id,
+                        name=item.name,
+                        input=getattr(item, "arguments", "") or "{}",
+                    ),
+                )
+
+        usage = None
+        if response.usage:
+            u = response.usage
+            details = getattr(u, "input_tokens_details", None)
+            usage = ChatUsage(
+                input_tokens=u.input_tokens,
+                output_tokens=u.output_tokens,
+                time=(datetime.now() - start_datetime).total_seconds(),
+                cache_input_tokens=getattr(
+                    details,
+                    "cached_tokens",
+                    0,
+                )
+                if details
+                else 0,
+            )
+
+        resp_kwargs: dict[str, Any] = {
+            "content": content_blocks,
+            "is_last": True,
+            "usage": usage,
+        }
+        response_id = getattr(response, "id", None)
+        if response_id:
+            resp_kwargs["id"] = response_id
+
+        return ChatResponse(**resp_kwargs)
+
+    def _format_tools(
+        self,
+        tools: list[dict] | None,
+        tool_choice: ToolChoice | None,
+    ) -> tuple[list[dict] | None, str | dict | None]:
+        """Validate and format tools and tool_choice for the Responses API.
+
+        The full ``tools`` list is always sent unchanged to maximise prompt
+        cache hits.  When ``tool_choice.tools`` restricts the callable
+        subset, the ``allowed_tools`` tool_choice format is used instead of
+        filtering the schemas list.
+
+        Args:
+            tools (`list[dict] | None`, optional):
+                The raw tool schemas.
+            tool_choice (`ToolChoice | None`, optional):
+                The tool choice configuration.
+
+        Returns:
+            `tuple[list[dict] | None, str | dict | None]`:
+                A tuple of ``(formatted_tools, formatted_tool_choice)``
+                ready for the Responses API.
+        """
+        if tool_choice and tools:
+            self._validate_tool_choice(tool_choice, tools)
+
+        fmt_tools = None
+        if tools:
+            fmt_tools = [
+                {"type": "function", **tool["function"]} for tool in tools
+            ]
+
+        if not tool_choice:
+            return fmt_tools, None
+
+        mode = tool_choice.mode
+
+        if mode not in _TOOL_CHOICE_LITERAL_MODES:
+            return fmt_tools, {"type": "function", "name": mode}
+
+        if tool_choice.tools:
+            return fmt_tools, {
+                "type": "allowed_tools",
+                "mode": mode,
+                "tools": [
+                    {"type": "function", "name": name}
+                    for name in tool_choice.tools
+                ],
+            }
+
+        return fmt_tools, mode
diff --git a/src/agentscope/model/_openai_response/_models/gpt-4.1-mini.yaml b/src/agentscope/model/_openai_response/_models/gpt-4.1-mini.yaml
new file mode 100644
index 0000000..a6bdad3
--- /dev/null
+++ b/src/agentscope/model/_openai_response/_models/gpt-4.1-mini.yaml
@@ -0,0 +1,24 @@
+name: gpt-4.1-mini
+label: GPT-4.1 Mini
+status: active
+
+input_types:
+  - text/plain
+  - image/jpeg
+  - image/png
+  - image/gif
+  - image/webp
+
+output_types:
+  - text/plain
+
+context_size: 1047576
+output_size: 32768
+
+parameter_overrides:
+  max_tokens:
+    maximum: 32768
+  thinking_enable:
+    hidden: true
+  reasoning_effort:
+    hidden: true
diff --git a/src/agentscope/model/_openai_response/_models/gpt-4.1-nano.yaml b/src/agentscope/model/_openai_response/_models/gpt-4.1-nano.yaml
new file mode 100644
index 0000000..5a067a0
--- /dev/null
+++ b/src/agentscope/model/_openai_response/_models/gpt-4.1-nano.yaml
@@ -0,0 +1,24 @@
+name: gpt-4.1-nano
+label: GPT-4.1 Nano
+status: active
+
+input_types:
+  - text/plain
+  - image/jpeg
+  - image/png
+  - image/gif
+  - image/webp
+
+output_types:
+  - text/plain
+
+context_size: 1047576
+output_size: 32768
+
+parameter_overrides:
+  max_tokens:
+    maximum: 32768
+  thinking_enable:
+    hidden: true
+  reasoning_effort:
+    hidden: true
diff --git a/src/agentscope/model/_openai_response/_models/gpt-4.1.yaml b/src/agentscope/model/_openai_response/_models/gpt-4.1.yaml
new file mode 100644
index 0000000..8a828eb
--- /dev/null
+++ b/src/agentscope/model/_openai_response/_models/gpt-4.1.yaml
@@ -0,0 +1,24 @@
+name: gpt-4.1
+label: GPT-4.1
+status: active
+
+input_types:
+  - text/plain
+  - image/jpeg
+  - image/png
+  - image/gif
+  - image/webp
+
+output_types:
+  - text/plain
+
+context_size: 1047576
+output_size: 32768
+
+parameter_overrides:
+  max_tokens:
+    maximum: 32768
+  thinking_enable:
+    hidden: true
+  reasoning_effort:
+    hidden: true
diff --git a/src/agentscope/model/_openai_response/_models/gpt-4o-mini.yaml b/src/agentscope/model/_openai_response/_models/gpt-4o-mini.yaml
new file mode 100644
index 0000000..da2ec39
--- /dev/null
+++ b/src/agentscope/model/_openai_response/_models/gpt-4o-mini.yaml
@@ -0,0 +1,24 @@
+name: gpt-4o-mini
+label: GPT-4o Mini
+status: active
+
+input_types:
+  - text/plain
+  - image/jpeg
+  - image/png
+  - image/gif
+  - image/webp
+
+output_types:
+  - text/plain
+
+context_size: 128000
+output_size: 16384
+
+parameter_overrides:
+  max_tokens:
+    maximum: 16384
+  thinking_enable:
+    hidden: true
+  reasoning_effort:
+    hidden: true
diff --git a/src/agentscope/model/_openai_response/_models/gpt-4o.yaml b/src/agentscope/model/_openai_response/_models/gpt-4o.yaml
new file mode 100644
index 0000000..e19c9be
--- /dev/null
+++ b/src/agentscope/model/_openai_response/_models/gpt-4o.yaml
@@ -0,0 +1,24 @@
+name: gpt-4o
+label: GPT-4o
+status: active
+
+input_types:
+  - text/plain
+  - image/jpeg
+  - image/png
+  - image/gif
+  - image/webp
+
+output_types:
+  - text/plain
+
+context_size: 128000
+output_size: 16384
+
+parameter_overrides:
+  max_tokens:
+    maximum: 16384
+  thinking_enable:
+    hidden: true
+  reasoning_effort:
+    hidden: true
diff --git a/src/agentscope/model/_openai_response/_models/gpt-5.4.yaml b/src/agentscope/model/_openai_response/_models/gpt-5.4.yaml
new file mode 100644
index 0000000..6d99663
--- /dev/null
+++ b/src/agentscope/model/_openai_response/_models/gpt-5.4.yaml
@@ -0,0 +1,22 @@
+name: gpt-5.4
+label: GPT-5.4 (Responses API)
+status: active
+
+input_types:
+  - text/plain
+  - image/jpeg
+  - image/png
+  - image/gif
+  - image/webp
+
+output_types:
+  - text/plain
+
+context_size: 1050000
+output_size: 128000
+
+parameter_overrides:
+  max_tokens:
+    maximum: 128000
+  reasoning_effort:
+    hidden: true
diff --git a/src/agentscope/model/_openai_response/_models/gpt-5.5.yaml b/src/agentscope/model/_openai_response/_models/gpt-5.5.yaml
new file mode 100644
index 0000000..746c4f5
--- /dev/null
+++ b/src/agentscope/model/_openai_response/_models/gpt-5.5.yaml
@@ -0,0 +1,26 @@
+name: gpt-5.5
+label: GPT-5.5
+status: active
+
+input_types:
+  - text/plain
+  - image/jpeg
+  - image/png
+  - image/gif
+  - image/webp
+  - audio/mp3
+  - audio/wav
+
+output_types:
+  - text/plain
+
+context_size: 1050000
+output_size: 128000
+
+parameter_overrides:
+  max_tokens:
+    maximum: 128000
+  thinking_enable:
+    hidden: true
+  reasoning_effort:
+    hidden: true
diff --git a/src/agentscope/model/_openai_response/_models/o3.yaml b/src/agentscope/model/_openai_response/_models/o3.yaml
new file mode 100644
index 0000000..a891bd1
--- /dev/null
+++ b/src/agentscope/model/_openai_response/_models/o3.yaml
@@ -0,0 +1,24 @@
+name: o3
+label: o3 (Responses API)
+status: active
+
+input_types:
+  - text/plain
+  - application/x-thinking
+  - image/jpeg
+  - image/png
+  - image/gif
+  - image/webp
+
+output_types:
+  - text/plain
+  - application/x-thinking
+
+context_size: 200000
+output_size: 100000
+
+parameter_overrides:
+  max_tokens:
+    maximum: 100000
+  temperature:
+    hidden: true
diff --git a/src/agentscope/model/_openai_response/_models/o4-mini.yaml b/src/agentscope/model/_openai_response/_models/o4-mini.yaml
new file mode 100644
index 0000000..587223a
--- /dev/null
+++ b/src/agentscope/model/_openai_response/_models/o4-mini.yaml
@@ -0,0 +1,24 @@
+name: o4-mini
+label: o4-mini (Responses API)
+status: active
+
+input_types:
+  - text/plain
+  - application/x-thinking
+  - image/jpeg
+  - image/png
+  - image/gif
+  - image/webp
+
+output_types:
+  - text/plain
+  - application/x-thinking
+
+context_size: 200000
+output_size: 100000
+
+parameter_overrides:
+  max_tokens:
+    maximum: 100000
+  temperature:
+    hidden: true
diff --git a/src/agentscope/model/_xai/__init__.py b/src/agentscope/model/_xai/__init__.py
new file mode 100644
index 0000000..a41fe21
--- /dev/null
+++ b/src/agentscope/model/_xai/__init__.py
@@ -0,0 +1,9 @@
+# -*- coding: utf-8 -*-
+"""The xAI LLM API modules."""
+
+from ._model import XAICredential, XAIChatModel
+
+__all__ = [
+    "XAICredential",
+    "XAIChatModel",
+]
diff --git a/src/agentscope/model/_xai/_model.py b/src/agentscope/model/_xai/_model.py
new file mode 100644
index 0000000..d6f14df
--- /dev/null
+++ b/src/agentscope/model/_xai/_model.py
@@ -0,0 +1,454 @@
+# -*- coding: utf-8 -*-
+"""The xAI chat model implementation using the official xai_sdk."""
+from datetime import datetime
+from typing import Any, AsyncGenerator, List, Literal, TYPE_CHECKING, Type
+
+from pydantic import BaseModel, Field
+
+from ..._utils._common import _generate_id
+from .._base import ChatModelBase, _TOOL_CHOICE_LITERAL_MODES
+from .._model_response import ChatResponse
+from .._model_usage import ChatUsage
+from ...credential import XAICredential
+from ...formatter import XAIChatFormatter
+from ...message import (
+    Msg,
+    TextBlock,
+    ThinkingBlock,
+    ToolCallBlock,
+)
+from ...tool import ToolChoice
+
+if TYPE_CHECKING:
+    from xai_sdk import AsyncClient
+    from xai_sdk.chat import Response
+else:
+    AsyncClient = Any
+    Response = Any
+
+
+class XAIChatModel(ChatModelBase):
+    """The xAI chat model using the official ``xai_sdk`` gRPC client.
+
+    This model provides native access to xAI-specific features such as
+    server-side agentic tools (web search, X search, code execution) and
+    reasoning effort control, which are not available through the
+    OpenAI-compatible REST endpoint.
+    """
+
+    class Parameters(BaseModel):
+        """The parameters for the xAI chat model."""
+
+        max_tokens: int | None = Field(
+            default=None,
+            title="Max Tokens",
+            description="The maximum number of tokens for the LLM output.",
+            gt=0,
+        )
+        """The maximum number of tokens to generate."""
+
+        thinking_enable: bool = Field(
+            default=False,
+            title="Thinking",
+            description=(
+                "Whether to enable reasoning for models that support "
+                "extended thinking (e.g. ``grok-3-mini``). Use "
+                "reasoning_effort to control the depth of reasoning."
+            ),
+        )
+
+        reasoning_effort: Literal["low", "medium", "high"] | None = Field(
+            default=None,
+            title="Reasoning Effort",
+            description=(
+                "Controls the depth of reasoning for models that support "
+                "extended thinking (e.g. ``grok-3-mini``). Set to "
+                "``'low'``, ``'medium'``, or ``'high'`` to enable reasoning "
+                "with the corresponding effort level. ``None`` disables "
+                "reasoning."
+            ),
+        )
+
+        temperature: float | None = Field(
+            default=None,
+            title="Temperature",
+            description="The temperature for the LLM output.",
+            ge=0,
+            le=2,
+        )
+        """The sampling temperature."""
+
+        top_p: float | None = Field(
+            default=None,
+            title="Top P",
+            description="The top-p nucleus sampling value.",
+            gt=0,
+            le=1,
+        )
+        """The top-p sampling parameter."""
+
+    type: Literal["xai_chat"] = "xai_chat"
+    """The type of the chat model."""
+
+    def __init__(
+        self,
+        credential: XAICredential,
+        model: str,
+        parameters: "XAIChatModel.Parameters | None" = None,
+        stream: bool = True,
+        max_retries: int = 3,
+        retry_delay: float = 1.0,
+        context_size: int = 131072,
+        formatter: XAIChatFormatter | None = None,
+        client_kwargs: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize the xAI chat model.
+
+        Args:
+            credential (`XAICredential`):
+                The xAI credential used to authenticate API calls.
+            model (`str`):
+                The xAI model name, e.g. ``grok-3`` or ``grok-3-mini``.
+            parameters (`XAIChatModel.Parameters | None`, defaults to \
+            `None`):
+                The xAI API parameters. When ``None``, the default
+                parameters will be used.
+            stream (`bool`, defaults to `True`):
+                Whether to enable streaming output.
+            max_retries (`int`, defaults to `3`):
+                The maximum number of retries for the xAI API.
+            retry_delay (`float`, defaults to `1.0`):
+                Seconds to sleep between retry attempts.
+            context_size (`int`, defaults to `131072`):
+                The model context size used for context compression.
+            formatter (`XAIChatFormatter | None`, defaults to `None`):
+                The formatter that converts ``Msg`` objects to xai_sdk
+                proto messages. When ``None``, an ``XAIChatFormatter``
+                instance will be used.
+            client_kwargs (`dict[str, Any] | None`, defaults to `None`):
+                Extra keyword arguments forwarded to ``xai_sdk.AsyncClient``
+                (e.g. ``timeout``, ``metadata``, ``channel_options``). Keys
+                that overlap with credential-derived arguments (such as
+                ``api_key`` or ``api_host``) take precedence over the
+                credential values.
+        """
+        super().__init__(
+            credential=credential,
+            model=model,
+            parameters=parameters or self.Parameters(),
+            stream=stream,
+            max_retries=max_retries,
+            retry_delay=retry_delay,
+            context_size=context_size,
+        )
+        self.formatter = formatter or XAIChatFormatter()
+        self.client_kwargs = client_kwargs or {}
+
+    @classmethod
+    def _get_retryable_exceptions(cls) -> tuple[Type[Exception], ...]:
+        import grpc
+
+        # xai_sdk uses grpc.aio under the hood; transport/API failures surface
+        # as grpc.aio.AioRpcError (subclass of grpc.RpcError). We retry the
+        # whole class because the retry mechanism here only filters by type,
+        # not by status code — so 4xx-equivalents (UNAUTHENTICATED, INVALID
+        # _ARGUMENT) will also be retried a few times before failing, which
+        # we accept. Note xai_sdk additionally retries UNAVAILABLE 5 times at
+        # the gRPC layer with exponential backoff before raising to us.
+        return (grpc.RpcError,)
+
+    async def _call_api(
+        self,
+        model_name: str,
+        messages: list[Msg],
+        tools: list[dict] | None = None,
+        tool_choice: ToolChoice | None = None,
+        **generate_kwargs: Any,
+    ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:
+        """Call the xAI API using the official ``xai_sdk`` gRPC client.
+
+        Args:
+            model_name (`str`):
+                The model name to use for this call.
+            messages (`list`):
+                A list of ``Msg`` objects representing the conversation.
+            tools (`list[dict]`, default `None`):
+                The tools JSON schemas.
+            tool_choice (`ToolChoice | None`, optional):
+                Controls which (if any) tool is called by the model.
+            **generate_kwargs (`Any`):
+                Extra keyword arguments forwarded to the API.
+
+        Returns:
+            `ChatResponse | AsyncGenerator[ChatResponse, None]`:
+                A ``ChatResponse`` when streaming is disabled, or an async
+                generator of ``ChatResponse`` objects when streaming is
+                enabled.
+        """
+        from xai_sdk import AsyncClient
+
+        client = AsyncClient(
+            **{
+                "api_key": self.credential.api_key.get_secret_value(),
+                "api_host": self.credential.api_host,
+                **self.client_kwargs,
+            },
+        )
+
+        xai_messages = await self.formatter.format(messages)
+
+        xai_tools, xai_tool_choice = self._format_tools(tools, tool_choice)
+
+        create_kwargs: dict[str, Any] = {"model": model_name}
+        if self.parameters.max_tokens is not None:
+            create_kwargs["max_tokens"] = self.parameters.max_tokens
+        if self.parameters.temperature is not None:
+            create_kwargs["temperature"] = self.parameters.temperature
+        if self.parameters.top_p is not None:
+            create_kwargs["top_p"] = self.parameters.top_p
+        if (
+            self.parameters.thinking_enable
+            and self.parameters.reasoning_effort
+        ):
+            create_kwargs[
+                "reasoning_effort"
+            ] = self.parameters.reasoning_effort
+        if xai_tools:
+            create_kwargs["tools"] = xai_tools
+        if xai_tool_choice is not None:
+            create_kwargs["tool_choice"] = xai_tool_choice
+
+        create_kwargs.update(generate_kwargs)
+
+        chat = client.chat.create(**create_kwargs)
+        for xai_msg in xai_messages:
+            chat.append(xai_msg)
+
+        start_datetime = datetime.now()
+
+        if self.stream:
+            return self._parse_stream_response(start_datetime, chat, client)
+
+        try:
+            response = await chat.sample()
+        finally:
+            await client.close()
+
+        return self._parse_completion_response(start_datetime, response)
+
+    def _format_tools(
+        self,
+        tools: list[dict] | None,
+        tool_choice: ToolChoice | None,
+    ) -> tuple[list | None, Any]:
+        """Validate, filter, and format tools and tool_choice for the xAI API.
+
+        When ``tool_choice.tools`` is specified the schemas list is filtered
+        to only those tools. When ``tool_choice.mode`` is a specific tool name
+        (str) the model is forced to call exactly that tool without needing to
+        filter the list, preserving prompt-cache efficiency.
+
+        Args:
+            tools (`list[dict] | None`, optional):
+                The raw tool schemas.
+            tool_choice (`ToolChoice | None`, optional):
+                The tool choice configuration.
+
+        Returns:
+            `tuple[list | None, Any]`:
+                A tuple of (xai_tools, xai_tool_choice) ready for the
+                ``xai_sdk`` client.
+        """
+        from xai_sdk.chat import required_tool, tool
+
+        if tool_choice and tools:
+            self._validate_tool_choice(tool_choice, tools)
+            if tool_choice.tools:
+                allowed = set(tool_choice.tools)
+                tools = [t for t in tools if t["function"]["name"] in allowed]
+
+        xai_tools = None
+        if tools:
+            xai_tools = []
+            for t in tools:
+                if t.get("type") == "function" and "function" in t:
+                    fn = t["function"]
+                    xai_tools.append(
+                        tool(
+                            name=fn["name"],
+                            description=fn.get("description", ""),
+                            parameters=fn.get("parameters", {}),
+                        ),
+                    )
+
+        if not tool_choice:
+            return xai_tools, None
+
+        mode = tool_choice.mode
+
+        if mode in _TOOL_CHOICE_LITERAL_MODES:
+            return xai_tools, mode
+
+        return xai_tools, required_tool(mode)
+
+    async def _parse_stream_response(
+        self,
+        start_datetime: datetime,
+        chat: Any,
+        client: AsyncClient,
+    ) -> AsyncGenerator[ChatResponse, None]:
+        """Parse the xAI streaming response from ``xai_sdk``.
+
+        Each iteration yields only the incremental *delta* content; the
+        base ``ChatModelBase.__call__`` accumulates them and emits the
+        final ``is_last=True`` chunk. ``xai_sdk`` does not stream tool
+        calls or usage — both are only available on the final response
+        object — so after the delta loop exits we emit one last carrier
+        delta containing the full ``ToolCallBlock`` list and ``usage``
+        for the accumulator to merge.
+
+        Args:
+            start_datetime (`datetime`):
+                The start datetime of the response generation.
+            chat (`Any`):
+                The ``xai_sdk`` chat session object.
+            client (`AsyncClient`):
+                The ``xai_sdk.AsyncClient`` instance; closed when the
+                generator is exhausted or abandoned.
+
+        Yields:
+            `ChatResponse`:
+                Incremental ``ChatResponse`` objects with ``is_last=False``.
+        """
+        # xAI exposes the upstream response id from the very first
+        # streamed ``response`` object; fall back to a locally-generated
+        # id so every delta carries a stable identifier before then.
+        response_id: str = _generate_id()
+        text_id: str = _generate_id()
+        thinking_id: str = _generate_id()
+        last_response = None
+
+        try:
+            async for response, chunk in chat.stream():
+                upstream_id = getattr(response, "id", None)
+                if upstream_id:
+                    response_id = upstream_id
+
+                delta_res = ChatResponse(
+                    content=[],
+                    is_last=False,
+                    id=response_id,
+                )
+
+                delta_thinking: str = chunk.reasoning_content or ""
+                if delta_thinking:
+                    delta_res.append_thinking(
+                        delta_thinking,
+                        block_id=thinking_id,
+                    )
+
+                delta_text: str = chunk.content or ""
+                if delta_text:
+                    delta_res.append_text(delta_text, block_id=text_id)
+
+                if delta_res.content:
+                    yield delta_res
+
+                last_response = response
+
+        finally:
+            await client.close()
+
+        # ``xai_sdk`` does not stream tool calls or usage — both are only
+        # populated on the final accumulated ``response`` object. Emit a
+        # single trailing carrier delta so the base accumulator picks up
+        # the ``ToolCallBlock``s and ``ChatUsage``.
+        trailing = ChatResponse(
+            content=[],
+            is_last=False,
+            id=response_id,
+        )
+
+        if last_response is not None:
+            for tc in last_response.tool_calls or []:
+                trailing.append_tool_call(
+                    block_id=tc.id,
+                    name=tc.function.name,
+                    input=tc.function.arguments,
+                )
+
+        if last_response is not None and last_response.usage is not None:
+            u = last_response.usage
+            trailing.usage = ChatUsage(
+                input_tokens=u.prompt_tokens,
+                output_tokens=u.completion_tokens,
+                time=(datetime.now() - start_datetime).total_seconds(),
+                cache_input_tokens=getattr(
+                    u,
+                    "cached_prompt_text_tokens",
+                    0,
+                ),
+            )
+
+        if trailing.content or trailing.usage:
+            yield trailing
+
+    def _parse_completion_response(
+        self,
+        start_datetime: datetime,
+        response: Response,
+    ) -> ChatResponse:
+        """Parse the xAI non-streaming response from ``xai_sdk``.
+
+        Args:
+            start_datetime (`datetime`):
+                The start datetime of the response generation.
+            response (`Any`):
+                The ``xai_sdk`` ``Response`` object.
+
+        Returns:
+            `ChatResponse`:
+                A single ``ChatResponse`` with ``is_last=True``.
+        """
+        content_blocks: List[TextBlock | ToolCallBlock | ThinkingBlock] = []
+
+        if response.reasoning_content:
+            content_blocks.append(
+                ThinkingBlock(thinking=response.reasoning_content),
+            )
+        if response.content:
+            content_blocks.append(TextBlock(text=response.content))
+
+        for tc in response.tool_calls or []:
+            content_blocks.append(
+                ToolCallBlock(
+                    id=tc.id,
+                    name=tc.function.name,
+                    input=tc.function.arguments,
+                ),
+            )
+
+        usage = None
+        if response.usage is not None:
+            u = response.usage
+            usage = ChatUsage(
+                input_tokens=u.prompt_tokens,
+                output_tokens=u.completion_tokens,
+                time=(datetime.now() - start_datetime).total_seconds(),
+                cache_input_tokens=getattr(
+                    u,
+                    "cached_prompt_text_tokens",
+                    0,
+                ),
+            )
+
+        resp_kwargs: dict[str, Any] = {
+            "content": content_blocks,
+            "is_last": True,
+            "usage": usage,
+        }
+        response_id = getattr(response, "id", None)
+        if response_id:
+            resp_kwargs["id"] = response_id
+
+        return ChatResponse(**resp_kwargs)
diff --git a/src/agentscope/model/_xai/_models/grok-3-fast.yaml b/src/agentscope/model/_xai/_models/grok-3-fast.yaml
new file mode 100644
index 0000000..66be7de
--- /dev/null
+++ b/src/agentscope/model/_xai/_models/grok-3-fast.yaml
@@ -0,0 +1,19 @@
+name: grok-3-fast
+label: Grok 3 Fast
+status: active
+
+input_types:
+  - text/plain
+  - image/jpeg
+  - image/png
+
+output_types:
+  - text/plain
+  - application/x-thinking
+
+context_size: 131072
+output_size: 16000
+
+parameter_overrides:
+  max_tokens:
+    maximum: 16000
diff --git a/src/agentscope/model/_xai/_models/grok-3-mini.yaml b/src/agentscope/model/_xai/_models/grok-3-mini.yaml
new file mode 100644
index 0000000..04f100a
--- /dev/null
+++ b/src/agentscope/model/_xai/_models/grok-3-mini.yaml
@@ -0,0 +1,17 @@
+name: grok-3-mini
+label: Grok 3 Mini
+status: active
+
+input_types:
+  - text/plain
+
+output_types:
+  - text/plain
+  - application/x-thinking
+
+context_size: 131072
+output_size: 16000
+
+parameter_overrides:
+  max_tokens:
+    maximum: 16000
diff --git a/src/agentscope/model/_xai/_models/grok-3.yaml b/src/agentscope/model/_xai/_models/grok-3.yaml
new file mode 100644
index 0000000..6a04c98
--- /dev/null
+++ b/src/agentscope/model/_xai/_models/grok-3.yaml
@@ -0,0 +1,19 @@
+name: grok-3
+label: Grok 3
+status: active
+
+input_types:
+  - text/plain
+  - image/jpeg
+  - image/png
+
+output_types:
+  - text/plain
+  - application/x-thinking
+
+context_size: 131072
+output_size: 16000
+
+parameter_overrides:
+  max_tokens:
+    maximum: 16000
diff --git a/src/agentscope/model/_xai/_models/grok-4.3.yaml b/src/agentscope/model/_xai/_models/grok-4.3.yaml
new file mode 100644
index 0000000..4b712ef
--- /dev/null
+++ b/src/agentscope/model/_xai/_models/grok-4.3.yaml
@@ -0,0 +1,19 @@
+name: grok-4.3
+label: Grok 4.3
+status: active
+
+input_types:
+  - text/plain
+  - image/jpeg
+  - image/png
+
+output_types:
+  - text/plain
+  - application/x-thinking
+
+context_size: 1000000
+output_size: 30000
+
+parameter_overrides:
+  max_tokens:
+    maximum: 30000
diff --git a/src/agentscope/permission/__init__.py b/src/agentscope/permission/__init__.py
new file mode 100644
index 0000000..7271445
--- /dev/null
+++ b/src/agentscope/permission/__init__.py
@@ -0,0 +1,18 @@
+# -*- coding: utf-8 -*-
+"""The tool permission related types and functions."""
+
+from ._context import PermissionContext, AdditionalWorkingDirectory
+from ._decision import PermissionDecision
+from ._engine import PermissionEngine
+from ._rule import PermissionRule
+from ._types import PermissionMode, PermissionBehavior
+
+__all__ = [
+    "PermissionContext",
+    "AdditionalWorkingDirectory",
+    "PermissionDecision",
+    "PermissionEngine",
+    "PermissionRule",
+    "PermissionMode",
+    "PermissionBehavior",
+]
diff --git a/src/agentscope/permission/_context.py b/src/agentscope/permission/_context.py
new file mode 100644
index 0000000..dd46e57
--- /dev/null
+++ b/src/agentscope/permission/_context.py
@@ -0,0 +1,46 @@
+# -*- coding: utf-8 -*-
+"""The permission context module."""
+from pydantic import BaseModel, Field
+
+from ._rule import PermissionRule
+from ._types import PermissionMode
+
+
+class AdditionalWorkingDirectory(BaseModel):
+    """An additional directory included in permission scope.
+
+    Working directories are used to determine which file paths should be
+    automatically allowed in ACCEPT_EDITS mode.
+    """
+
+    path: str
+    """Absolute path to the directory."""
+
+    source: str
+    """Where this directory permission originated from
+    (e.g., 'userSettings', 'session')."""
+
+
+class PermissionContext(BaseModel):
+    """Context for permission checking.
+
+    Contains the permission mode, working directories, and all configured
+    permission rules organized by behavior type (allow, deny, ask).
+    """
+
+    mode: PermissionMode = PermissionMode.DEFAULT
+    """The current permission mode."""
+
+    working_directories: dict[str, AdditionalWorkingDirectory] = Field(
+        default_factory=dict,
+    )
+    """Additional directories allowed for file operations, keyed by path."""
+
+    allow_rules: dict[str, list[PermissionRule]] = Field(default_factory=dict)
+    """Rules that allow tool execution, keyed by tool name."""
+
+    deny_rules: dict[str, list[PermissionRule]] = Field(default_factory=dict)
+    """Rules that deny tool execution, keyed by tool name."""
+
+    ask_rules: dict[str, list[PermissionRule]] = Field(default_factory=dict)
+    """Rules that require user confirmation, keyed by tool name."""
diff --git a/src/agentscope/permission/_decision.py b/src/agentscope/permission/_decision.py
new file mode 100644
index 0000000..c85b9f8
--- /dev/null
+++ b/src/agentscope/permission/_decision.py
@@ -0,0 +1,68 @@
+# -*- coding: utf-8 -*-
+"""The permission decision result."""
+from dataclasses import dataclass
+from typing import Any
+
+from ._rule import PermissionRule
+from ._types import PermissionBehavior
+
+
+@dataclass
+class PermissionDecision:
+    """Decision result from permission checking.
+
+    Represents the outcome of a permission check, including whether
+    the action should be allowed, denied, or require user confirmation.
+    """
+
+    behavior: PermissionBehavior
+    """The permission behavior decision."""
+
+    message: str
+    """Human-readable message describing the decision."""
+
+    decision_reason: str | None = None
+    """Optional explanation for why this decision was made."""
+
+    updated_input: dict[str, Any] | None = None
+    """Optional modified input data (e.g., sanitized paths)."""
+
+    suggested_rules: list[PermissionRule] | None = None
+    """Optional list of suggested permission rules for user to apply."""
+
+    bypass_immune: bool = False
+    """Whether this decision is immune to being silenced by allow rules
+    ("bypass-immune").
+
+    Only meaningful when :attr:`behavior` is :attr:`PermissionBehavior.ASK`.
+    A tool sets this to ``True`` to signal that the operation is
+    dangerous enough that **no allow rule** may convert the ASK into an
+    ALLOW — the user must explicitly confirm in-the-moment. In
+    :attr:`PermissionMode.DONT_ASK` where no user is available, a
+    bypass-immune ASK is converted to DENY rather than silently allowed.
+
+    Per-mode handling of a ``bypass_immune=True`` ASK:
+
+    - ``DEFAULT`` / ``ACCEPT_EDITS``: honored — allow rules cannot
+      override.
+    - ``EXPLORE``: not applicable (the engine resolves EXPLORE via
+      :meth:`ToolBase.check_read_only` and does not invoke
+      :meth:`ToolBase.check_permissions`).
+    - ``BYPASS``: **intentionally ignored** — BYPASS's contract is
+      "the user has opted out of safety prompts; only deny / ask
+      rules remain as guardrails." Use deny rules in BYPASS to
+      enforce specific protections.
+    - ``DONT_ASK``: converted to DENY (no user available).
+
+    Default is ``False``: a regular ASK that may be overridden by an
+    allow rule in DEFAULT / ACCEPT_EDITS, and is silently allowed by
+    BYPASS's fallback. Tools should set this only for genuine safety
+    checks (e.g. writes to dangerous paths, ``rm -rf /``, command
+    injection patterns) — not for "I'd prefer user input" cases.
+
+    Note: this field is internal metadata for the permission engine.
+    Callers handling the decision (agent loop, HITL backend, UI) treat
+    a bypass-immune ASK the same as a regular ASK — both prompt the
+    user. The distinction only governs whether engine-level rules /
+    modes may override it before reaching the caller.
+    """
diff --git a/src/agentscope/permission/_engine.py b/src/agentscope/permission/_engine.py
new file mode 100644
index 0000000..8487ae6
--- /dev/null
+++ b/src/agentscope/permission/_engine.py
@@ -0,0 +1,729 @@
+# -*- coding: utf-8 -*-
+"""The permission engine for checking and enforcing permission rules."""
+from typing import Any, List, TYPE_CHECKING
+
+from ._context import PermissionContext
+from ._rule import PermissionRule
+from ._decision import PermissionDecision, PermissionBehavior
+from ._types import PermissionMode
+from .._utils._common import _execute_async_or_sync_func
+
+if TYPE_CHECKING:
+    from ..tool import ToolBase
+else:
+    ToolBase = "ToolBase"
+
+
+class PermissionEngine:
+    """Engine for checking and enforcing permission rules.
+
+    Evaluates tool execution requests against configured permission rules.
+    Matching strategy is delegated to each tool's :meth:`ToolBase.match_rule`:
+
+    - Bash tools: substring / prefix wildcard matching against the command
+    - Write/Read/Edit tools: glob matching against file paths
+    - Other tools: generic pattern matching (or tool-name-level only)
+
+    Each :class:`PermissionMode` has its own ``_check_<mode>`` method so
+    that mode policies are self-contained and readable in isolation. See
+    :meth:`check_permission` for the dispatcher and the individual methods
+    for per-mode evaluation order.
+    """
+
+    def __init__(
+        self,
+        context: PermissionContext,
+    ) -> None:
+        """Initialize the permission engine.
+
+        Args:
+            context (`PermissionContext`):
+                The permission context containing rules and mode
+
+        Example:
+            >>> context = PermissionContext(mode=PermissionMode.ACCEPT_EDITS)
+            >>> engine = PermissionEngine(context)
+        """
+        self.context = context
+
+    def add_rule(self, rule: PermissionRule) -> None:
+        """Add a permission rule to the context.
+
+        Args:
+            rule (`PermissionRule`):
+                The permission rule to add
+
+        Example:
+            >>> engine.add_rule(PermissionRule(
+            ...     tool_name="Bash",
+            ...     rule_content="git:*",
+            ...     behavior=PermissionBehavior.ALLOW,
+            ... ))
+        """
+
+        if rule.behavior == PermissionBehavior.ALLOW:
+            if rule.tool_name not in self.context.allow_rules:
+                self.context.allow_rules[rule.tool_name] = []
+            self.context.allow_rules[rule.tool_name].append(rule)
+        elif rule.behavior == PermissionBehavior.DENY:
+            if rule.tool_name not in self.context.deny_rules:
+                self.context.deny_rules[rule.tool_name] = []
+            self.context.deny_rules[rule.tool_name].append(rule)
+        elif rule.behavior == PermissionBehavior.ASK:
+            if rule.tool_name not in self.context.ask_rules:
+                self.context.ask_rules[rule.tool_name] = []
+            self.context.ask_rules[rule.tool_name].append(rule)
+
+    async def check_permission(
+        self,
+        tool: ToolBase,
+        tool_input: dict[str, Any],
+    ) -> PermissionDecision:
+        """Check permission for a tool execution request.
+
+        Dispatches to a per-mode private method so each mode's policy
+        is self-contained and readable in isolation:
+
+        - DEFAULT      → :meth:`_check_default`
+        - EXPLORE      → :meth:`_check_explore`
+        - ACCEPT_EDITS → :meth:`_check_accept_edits`
+        - BYPASS       → :meth:`_check_bypass`
+        - DONT_ASK     → :meth:`_check_dont_ask`
+
+        Args:
+            tool (`ToolBase`):
+                The tool instance being called.
+            tool_input (`dict[str, Any]`):
+                The tool input data, used for rule matching and
+                tool-specific checks.
+
+        Returns:
+            `PermissionDecision`:
+                Decision indicating whether to allow, deny, or ask.
+        """
+        mode = self.context.mode
+        if mode == PermissionMode.DEFAULT:
+            return await self._check_default(tool, tool_input)
+        if mode == PermissionMode.EXPLORE:
+            return await self._check_explore(tool, tool_input)
+        if mode == PermissionMode.ACCEPT_EDITS:
+            return await self._check_accept_edits(tool, tool_input)
+        if mode == PermissionMode.BYPASS:
+            return await self._check_bypass(tool, tool_input)
+        if mode == PermissionMode.DONT_ASK:
+            return await self._check_dont_ask(tool, tool_input)
+        raise ValueError(f"Unknown permission mode: {mode}")
+
+    async def _check_default(
+        self,
+        tool: ToolBase,
+        tool_input: dict[str, Any],
+    ) -> PermissionDecision:
+        """Permission check for :attr:`PermissionMode.DEFAULT`.
+
+        Every operation requires explicit permission unless either an
+        allow rule matches or the tool's own ``check_permissions``
+        explicitly returns ALLOW (e.g. ``Bash`` auto-allows recognized
+        read-only commands like ``ls``/``git status``). Evaluation order:
+
+        1. Deny rules → DENY
+        2. Ask rules → ASK (with suggestions)
+        3. ``tool.check_permissions``:
+            - ALLOW / DENY → returned as-is
+            - Safety ASK (bypass-immune) → returned with suggestions; cannot
+              be overridden by allow rules
+            - Non-safety ASK / PASSTHROUGH → continue
+        4. Allow rules → ALLOW
+        5. Default → ASK (with suggestions)
+
+        Args:
+            tool (`ToolBase`):
+                The tool instance being called.
+            tool_input (`dict[str, Any]`):
+                The tool input data.
+
+        Returns:
+            `PermissionDecision`:
+                The final decision.
+        """
+        # step 1: deny rules — highest priority
+        deny = await self._check_deny_rules(tool, tool_input)
+        if deny:
+            return deny
+
+        # step 2: ask rules
+        ask = await self._check_ask_rules(tool, tool_input)
+        if ask:
+            ask.suggested_rules = await self._generate_suggestions(
+                tool,
+                tool_input,
+            )
+            return ask
+
+        # step 3: tool's own check_permissions
+        tool_decision = await tool.check_permissions(tool_input, self.context)
+        # step 3a: tool ALLOW / DENY returned as-is
+        if tool_decision.behavior in (
+            PermissionBehavior.ALLOW,
+            PermissionBehavior.DENY,
+        ):
+            return tool_decision
+        # step 3b: safety ASK is bypass-immune — allow rules can't override
+        if self._is_safety_ask(tool_decision):
+            tool_decision.suggested_rules = await self._generate_suggestions(
+                tool,
+                tool_input,
+            )
+            return tool_decision
+
+        # step 4: allow rules
+        allow = await self._check_allow_rules(tool, tool_input)
+        if allow:
+            return allow
+
+        # step 5: default — ASK the user
+        default = PermissionDecision(
+            behavior=PermissionBehavior.ASK,
+            message=f"Permission required for {tool.name}",
+            decision_reason=f"Mode: {self.context.mode.value}",
+        )
+        default.suggested_rules = await self._generate_suggestions(
+            tool,
+            tool_input,
+        )
+        return default
+
+    async def _check_explore(
+        self,
+        tool: ToolBase,
+        tool_input: dict[str, Any],
+    ) -> PermissionDecision:
+        """Permission check for :attr:`PermissionMode.EXPLORE`.
+
+        Read-only mode — modifications are categorically denied. Evaluation
+        order:
+
+        1. Deny rules → DENY
+        2. Ask rules → ASK (with suggestions)
+        3. :meth:`ToolBase.check_read_only` (input-aware):
+            - True  → ALLOW
+            - False → DENY
+
+        ``tool.check_permissions`` is not invoked: EXPLORE is fully
+        resolved by the read-only verdict, so safety ASK paths (e.g.
+        ``rm -rf /``) are subsumed into the broader DENY. Allow rules are
+        intentionally not consulted — EXPLORE's read-only guarantee
+        cannot be granted away by a user-configured rule.
+
+        Args:
+            tool (`ToolBase`):
+                The tool instance being called.
+            tool_input (`dict[str, Any]`):
+                The tool input data.
+
+        Returns:
+            `PermissionDecision`:
+                ALLOW for read-only invocations, DENY otherwise.
+        """
+        # step 1: deny rules
+        deny = await self._check_deny_rules(tool, tool_input)
+        if deny:
+            return deny
+
+        # step 2: ask rules
+        ask = await self._check_ask_rules(tool, tool_input)
+        if ask:
+            ask.suggested_rules = await self._generate_suggestions(
+                tool,
+                tool_input,
+            )
+            return ask
+
+        # step 3: read-only verdict decides everything (ALLOW or DENY)
+        if await tool.check_read_only(tool_input):
+            return PermissionDecision(
+                behavior=PermissionBehavior.ALLOW,
+                message=(
+                    f"Permission granted for {tool.name} "
+                    f"(explore mode - read-only invocation)"
+                ),
+                decision_reason="Explore mode allows read-only operations",
+            )
+        return PermissionDecision(
+            behavior=PermissionBehavior.DENY,
+            message=(
+                f"Permission denied for {tool.name} "
+                f"(explore mode is read-only)"
+            ),
+            decision_reason="Explore mode does not allow modifications",
+        )
+
+    async def _check_accept_edits(
+        self,
+        tool: ToolBase,
+        tool_input: dict[str, Any],
+    ) -> PermissionDecision:
+        """Permission check for :attr:`PermissionMode.ACCEPT_EDITS`.
+
+        Edits within working directories are auto-allowed by each tool's
+        own ``check_permissions``; other operations follow the normal
+        flow. Evaluation order:
+
+        1. Deny rules → DENY
+        2. Ask rules → ASK (with suggestions)
+        3. :meth:`ToolBase.check_read_only` → True → ALLOW (fast path)
+        4. ``tool.check_permissions``:
+            - ALLOW (e.g. ``Write`` to a file in the working directory) /
+              DENY → returned as-is
+            - Safety ASK (bypass-immune) → returned with suggestions
+            - Non-safety ASK / PASSTHROUGH → continue
+        5. Allow rules → ALLOW
+        6. Default → ASK (with suggestions)
+
+        Args:
+            tool (`ToolBase`):
+                The tool instance being called.
+            tool_input (`dict[str, Any]`):
+                The tool input data.
+
+        Returns:
+            `PermissionDecision`:
+                The final decision.
+        """
+        # step 1: deny rules
+        deny = await self._check_deny_rules(tool, tool_input)
+        if deny:
+            return deny
+
+        # step 2: ask rules
+        ask = await self._check_ask_rules(tool, tool_input)
+        if ask:
+            ask.suggested_rules = await self._generate_suggestions(
+                tool,
+                tool_input,
+            )
+            return ask
+
+        # step 3: read-only fast path — ALLOW without invoking the tool
+        if await tool.check_read_only(tool_input):
+            return PermissionDecision(
+                behavior=PermissionBehavior.ALLOW,
+                message=(
+                    f"Permission granted for {tool.name} "
+                    f"(accept edits mode - read-only invocation)"
+                ),
+                decision_reason="Accept edits mode allows read-only "
+                "operations",
+            )
+
+        # step 4: tool's own check_permissions (working-directory check
+        # for Write/Edit, path-checked auto-allow for Bash, ...)
+        tool_decision = await tool.check_permissions(tool_input, self.context)
+        # step 4a: tool ALLOW / DENY returned as-is
+        if tool_decision.behavior in (
+            PermissionBehavior.ALLOW,
+            PermissionBehavior.DENY,
+        ):
+            return tool_decision
+        # step 4b: safety ASK is bypass-immune
+        if self._is_safety_ask(tool_decision):
+            tool_decision.suggested_rules = await self._generate_suggestions(
+                tool,
+                tool_input,
+            )
+            return tool_decision
+
+        # step 5: allow rules
+        allow = await self._check_allow_rules(tool, tool_input)
+        if allow:
+            return allow
+
+        # step 6: default — ASK the user
+        default = PermissionDecision(
+            behavior=PermissionBehavior.ASK,
+            message=f"Permission required for {tool.name}",
+            decision_reason=f"Mode: {self.context.mode.value}",
+        )
+        default.suggested_rules = await self._generate_suggestions(
+            tool,
+            tool_input,
+        )
+        return default
+
+    async def _check_bypass(
+        self,
+        tool: ToolBase,
+        tool_input: dict[str, Any],
+    ) -> PermissionDecision:
+        """Permission check for :attr:`PermissionMode.BYPASS`.
+
+        BYPASS is the "fully trusted" mode: the user has explicitly
+        opted out of safety prompts. All tool-emitted safety ASKs
+        (``rm -rf /``, write to ``~/.bashrc``, command-injection
+        patterns, dangerous sed, etc.) are **skipped** — only
+        user-configured deny / ask rules and tool-emitted DENY remain
+        as guardrails. The :attr:`PermissionDecision.bypass_immune`
+        field has no effect in BYPASS by design.
+
+        Use BYPASS only for sandboxed / containerized environments or
+        when you fully trust the agent's behavior. For unattended
+        execution where safety still matters, use
+        :attr:`PermissionMode.DONT_ASK` instead — it converts safety
+        ASKs to DENY rather than skipping them.
+
+        Evaluation order:
+
+        1. Deny rules → DENY
+        2. Ask rules → ASK (with suggestions; honors explicit user intent)
+        3. ``tool.check_permissions``:
+            - ALLOW / DENY → returned as-is
+            - ASK (including bypass-immune safety ASKs) → falls through
+            - PASSTHROUGH → falls through
+        4. Allow rules → ALLOW
+        5. Fallback → ALLOW (BYPASS)
+
+        Args:
+            tool (`ToolBase`):
+                The tool instance being called.
+            tool_input (`dict[str, Any]`):
+                The tool input data.
+
+        Returns:
+            `PermissionDecision`:
+                The final decision.
+        """
+        # step 1: deny rules
+        deny = await self._check_deny_rules(tool, tool_input)
+        if deny:
+            return deny
+
+        # step 2: ask rules (honor explicit user intent to be prompted)
+        ask = await self._check_ask_rules(tool, tool_input)
+        if ask:
+            ask.suggested_rules = await self._generate_suggestions(
+                tool,
+                tool_input,
+            )
+            return ask
+
+        # step 3: tool's own check_permissions — ALLOW / DENY returned;
+        # any ASK (including bypass-immune safety ASK) is intentionally
+        # NOT honored here, per BYPASS's "skip safety prompts" contract.
+        tool_decision = await tool.check_permissions(tool_input, self.context)
+        if tool_decision.behavior in (
+            PermissionBehavior.ALLOW,
+            PermissionBehavior.DENY,
+        ):
+            return tool_decision
+
+        # step 4: allow rules
+        allow = await self._check_allow_rules(tool, tool_input)
+        if allow:
+            return allow
+
+        # step 5: bypass fallback — ALLOW everything else
+        return PermissionDecision(
+            behavior=PermissionBehavior.ALLOW,
+            message=f"Permission granted for {tool.name} (bypass mode)",
+            decision_reason="Bypass mode allows all operations",
+        )
+
+    async def _check_dont_ask(
+        self,
+        tool: ToolBase,
+        tool_input: dict[str, Any],
+    ) -> PermissionDecision:
+        """Permission check for :attr:`PermissionMode.DONT_ASK`.
+
+        Used when no user is available to answer prompts (scheduled
+        tasks, background runs). Invariant: this method must never
+        return :attr:`PermissionBehavior.ASK` — every code path that
+        would otherwise ASK is converted to DENY via
+        :meth:`_convert_ask_to_deny`. Evaluation order:
+
+        1. Deny rules → DENY
+        2. Ask rules → DENY (converted, with suggestions preserved)
+        3. ``tool.check_permissions``:
+            - ALLOW / DENY → returned as-is
+            - Safety ASK → DENY (converted, with suggestions preserved)
+            - Non-safety ASK / PASSTHROUGH → continue
+        4. Allow rules → ALLOW
+        5. Default → DENY (user not available to answer)
+
+        Args:
+            tool (`ToolBase`):
+                The tool instance being called.
+            tool_input (`dict[str, Any]`):
+                The tool input data.
+
+        Returns:
+            `PermissionDecision`:
+                The final decision (never ASK).
+        """
+        # step 1: deny rules
+        deny = await self._check_deny_rules(tool, tool_input)
+        if deny:
+            return deny
+
+        # step 2: ask rules — converted to DENY (no user available)
+        ask = await self._check_ask_rules(tool, tool_input)
+        if ask:
+            ask.suggested_rules = await self._generate_suggestions(
+                tool,
+                tool_input,
+            )
+            return self._convert_ask_to_deny(tool, ask)
+
+        # step 3: tool's own check_permissions
+        tool_decision = await tool.check_permissions(tool_input, self.context)
+        # step 3a: tool ALLOW / DENY returned as-is
+        if tool_decision.behavior in (
+            PermissionBehavior.ALLOW,
+            PermissionBehavior.DENY,
+        ):
+            return tool_decision
+        # step 3b: safety ASK converted to DENY (no user available)
+        if self._is_safety_ask(tool_decision):
+            tool_decision.suggested_rules = await self._generate_suggestions(
+                tool,
+                tool_input,
+            )
+            return self._convert_ask_to_deny(tool, tool_decision)
+
+        # step 4: allow rules
+        allow = await self._check_allow_rules(tool, tool_input)
+        if allow:
+            return allow
+
+        # step 5: default — DENY (no user available to confirm)
+        return PermissionDecision(
+            behavior=PermissionBehavior.DENY,
+            message=(
+                f"Permission denied for {tool.name} "
+                f"(dont_ask mode - user not available)"
+            ),
+            decision_reason="User is not available to answer permission "
+            "prompts",
+        )
+
+    @staticmethod
+    def _convert_ask_to_deny(
+        tool: ToolBase,
+        ask_decision: PermissionDecision,
+    ) -> PermissionDecision:
+        """Convert an ASK decision into a DENY for DONT_ASK mode.
+
+        DONT_ASK's invariant is "never return ASK" — the user is not
+        available to answer prompts. This helper turns whatever produced
+        the ASK (an ASK rule, a safety check) into a DENY while
+        preserving traceability by carrying the original reason and
+        ``suggested_rules`` forward; callers (e.g. a UI surfacing the
+        scheduled-task failure) can still show the user what rule they
+        could add to unblock the operation in the future.
+
+        Args:
+            tool (`ToolBase`):
+                The tool whose invocation is being denied.
+            ask_decision (`PermissionDecision`):
+                The original ASK decision to convert.
+
+        Returns:
+            `PermissionDecision`:
+                A DENY decision with the original ASK's reason and
+                suggestions attached.
+        """
+        return PermissionDecision(
+            behavior=PermissionBehavior.DENY,
+            message=(
+                f"Permission denied for {tool.name} "
+                f"(dont_ask mode - ASK converted to DENY, "
+                f"user not available)"
+            ),
+            decision_reason=(
+                f"DONT_ASK mode converted ASK to DENY. "
+                f"Original reason: {ask_decision.decision_reason}"
+            ),
+            suggested_rules=ask_decision.suggested_rules,
+        )
+
+    @staticmethod
+    def _is_safety_ask(decision: PermissionDecision) -> bool:
+        """Whether a decision is a bypass-immune safety ASK.
+
+        A safety ASK is an ASK that a tool has explicitly marked with
+        :attr:`PermissionDecision.bypass_immune` ``= True``. Tools emit
+        these for dangerous operations (e.g. write to ``~/.bashrc``,
+        ``rm -rf /``, command-injection patterns) that must be surfaced
+        to the user regardless of allow rules in
+        ``DEFAULT``/``ACCEPT_EDITS``. ``BYPASS`` mode intentionally
+        skips this check (see :meth:`_check_bypass`); ``DONT_ASK``
+        converts the ASK to DENY (see :meth:`_check_dont_ask`).
+
+        Args:
+            decision (`PermissionDecision`):
+                The decision returned by a tool's ``check_permissions``.
+
+        Returns:
+            `bool`:
+                True iff ``behavior == ASK`` and ``bypass_immune`` is set.
+        """
+        return (
+            decision.behavior == PermissionBehavior.ASK
+            and decision.bypass_immune
+        )
+
+    async def _check_deny_rules(
+        self,
+        tool: ToolBase,
+        input_data: dict[str, Any],
+    ) -> PermissionDecision | None:
+        """Check if any deny rules match the request.
+
+        Args:
+            tool (`ToolBase`):
+                The tool instance being called
+            input_data (`dict[str, Any]`):
+                The tool input data
+
+        Returns:
+            `PermissionDecision | None`:
+                DENY decision if a rule matches, None otherwise
+        """
+        rules = self.context.deny_rules.get(tool.name, [])
+        for rule in rules:
+            if await self._rule_matches(tool, rule, input_data):
+                return PermissionDecision(
+                    behavior=PermissionBehavior.DENY,
+                    message=f"Permission to use {tool.name} has been denied",
+                    decision_reason=f"Rule: {rule.rule_content}",
+                )
+        return None
+
+    async def _check_ask_rules(
+        self,
+        tool: ToolBase,
+        input_data: dict[str, Any],
+    ) -> PermissionDecision | None:
+        """Check if any ask rules match the request.
+
+        Args:
+            tool (`ToolBase`):
+                The tool instance being called (used for tool-specific checks)
+            input_data (`dict[str, Any]`):
+                The tool input data
+
+        Returns:
+            `PermissionDecision | None`:
+                ASK decision if a rule matches, None otherwise
+        """
+        rules = self.context.ask_rules.get(tool.name, [])
+        for rule in rules:
+            if await self._rule_matches(tool, rule, input_data):
+                return PermissionDecision(
+                    behavior=PermissionBehavior.ASK,
+                    message=f"Permission required for {tool.name}",
+                    decision_reason=f"Rule: {rule.rule_content}",
+                )
+        return None
+
+    async def _check_allow_rules(
+        self,
+        tool: ToolBase,
+        input_data: dict[str, Any],
+    ) -> PermissionDecision | None:
+        """Check if any allow rules match the request.
+
+        Args:
+            tool (`ToolBase`):
+                The tool instance being called (used for tool-specific checks)
+            input_data (`dict[str, Any]`):
+                The tool input data
+
+        Returns:
+            `PermissionDecision | None`:
+                ALLOW decision if a rule matches, None otherwise
+        """
+        rules = self.context.allow_rules.get(tool.name, [])
+        for rule in rules:
+            if await self._rule_matches(tool, rule, input_data):
+                return PermissionDecision(
+                    behavior=PermissionBehavior.ALLOW,
+                    message=f"Permission granted for {tool.name}",
+                    updated_input=input_data,
+                )
+        return None
+
+    async def _rule_matches(
+        self,
+        tool: ToolBase,
+        rule: PermissionRule,
+        input_data: dict[str, Any],
+    ) -> bool:
+        """Check if a rule matches the input data.
+
+        The matching strategy depends on the tool type:
+        - Bash: Substring matching against the command
+        - Write/Read: Glob pattern matching against file paths
+        - Other: Generic pattern matching
+
+        Args:
+            rule (`PermissionRule`):
+                The permission rule to check
+            input_data (`dict[str, Any]`):
+                The tool input data
+
+        Returns:
+            `bool`:
+                True if the rule matches, False otherwise
+        """
+        # Empty rule_content matches everything
+        if not rule.rule_content:
+            return True
+
+        # Try to use tool's match_rule method if available.
+        # ``_execute_async_or_sync_func`` keeps backward compatibility
+        # with third-party tools that still override match_rule with a
+        # sync ``def`` (the framework's signature is now ``async def``).
+        return await _execute_async_or_sync_func(
+            tool.match_rule,
+            rule.rule_content,
+            input_data,
+        )
+
+    async def _generate_suggestions(
+        self,
+        tool: ToolBase,
+        tool_input: dict[str, Any],
+    ) -> List[PermissionRule]:
+        """Generate suggested permission rules from a tool call.
+
+        This method analyzes the tool call and generates broader permission
+        suggestions that the user can apply to avoid future confirmations.
+
+        Strategy:
+        - For Bash: Extract command prefix (e.g., "npm run" -> "npm run:*")
+        - For File operations: Extract directory (e.g.,
+         "src/file.py" -> "src/**")
+        - For other tools: Generate exact match rule
+
+        Args:
+            tool (`ToolBase`):
+                The tool instance being called (used for tool-specific
+                suggestions)
+            tool_input (`dict[str, Any]`):
+                The tool input data (used for generating suggestions)
+
+        Returns:
+            `List[PermissionRule]`:
+                List of suggested permission rules (usually 1, max 5 for
+                compound commands)
+        """
+
+        # Try to use tool's generate_suggestions method if available.
+        # ``_execute_async_or_sync_func`` keeps backward compatibility
+        # with third-party tools that still override this method with
+        # a sync ``def`` (the framework's signature is now ``async def``).
+        return await _execute_async_or_sync_func(
+            tool.generate_suggestions,
+            tool_input,
+        )
diff --git a/src/agentscope/permission/_rule.py b/src/agentscope/permission/_rule.py
new file mode 100644
index 0000000..7d4a078
--- /dev/null
+++ b/src/agentscope/permission/_rule.py
@@ -0,0 +1,36 @@
+# -*- coding: utf-8 -*-
+"""Permission rule model for tool usage."""
+from pydantic import BaseModel
+
+from ._types import PermissionBehavior
+
+
+class PermissionRule(BaseModel):
+    """Permission rule for tool usage.
+
+    A permission rule defines whether a specific tool or tool operation
+    should be allowed, denied, or require user confirmation. The
+    rule_content field has different semantics depending on the tool_name:
+
+    - For "Bash": rule_content is a substring pattern matched against the
+      command Example: rule_content="npm install" matches "npm install express"
+
+    - For "Write"/"Read": rule_content is a glob pattern matched against file
+      paths Example: rule_content="src/**" matches "src/main.py"
+
+    - For other tools: rule_content is a tool-specific filter pattern
+    """
+
+    tool_name: str
+    """The name of the tool this rule applies to (e.g., "Bash",
+    "Write", "Read")."""
+
+    rule_content: str | None
+    """Optional filter pattern - semantics depend on tool_name."""
+
+    behavior: PermissionBehavior
+    """The permission behavior ("allow", "deny", or "ask")."""
+
+    source: str
+    """Where this rule originated from (e.g., "userSettings",
+    "projectSettings")."""
diff --git a/src/agentscope/permission/_types.py b/src/agentscope/permission/_types.py
new file mode 100644
index 0000000..fc7b88a
--- /dev/null
+++ b/src/agentscope/permission/_types.py
@@ -0,0 +1,102 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=line-too-long
+"""Permission system types and engine for tool usage control.
+
+This module implements a permission system that controls tool execution based
+on configurable rules. The permission system supports different matching
+strategies depending on the tool type:
+
+- For Bash tools: rule_content is a substring pattern matched against commands
+- For Write/Read tools: rule_content is a glob pattern matched against file
+ paths
+- For other tools: rule_content uses generic matching logic
+"""
+
+from enum import Enum
+
+
+class PermissionMode(Enum):
+    """The mode of permission.
+
+    Permission modes control how the system handles tool execution requests.
+    Different modes are suitable for different scenarios:
+
+    +---------------+--------------------------------------------------+--------------------------------+
+    | Mode          | Behavior                                         | Use Case                       |
+    +===============+==================================================+================================+
+    | DEFAULT       | Every operation asks for permission unless:      | Default mode, most secure      |
+    |               | - an allow rule matches, OR                      |                                |
+    |               | - the tool's ``check_permissions`` explicitly    |                                |
+    |               |   returns ALLOW for the invocation (currently   |                                |
+    |               |   only ``Bash`` auto-allows recognized          |                                |
+    |               |   read-only commands such as ``ls``/``git       |                                |
+    |               |   status``). Read/Glob/Grep return PASSTHROUGH  |                                |
+    |               |   and fall through to the default ASK unless    |                                |
+    |               |   an allow rule matches.                        |                                |
+    +---------------+--------------------------------------------------+--------------------------------+
+    | ACCEPT_EDITS  | - Auto-allow file writes in working directories | User present, rapid iteration  |
+    |               | - Auto-allow file reads in working directories  | development                    |
+    |               | - Auto-allow filesystem commands (mkdir, rm,     |                                |
+    |               |   mv, cp, ...) **only when all target paths**   |                                |
+    |               |   **resolve inside a working directory**         |                                |
+    |               | - Other operations follow normal rules           |                                |
+    +---------------+--------------------------------------------------+--------------------------------+
+    | EXPLORE       | Read-only mode:                                  | Exploring codebase, planning   |
+    |               | - Allow: read-only tools (``Read``/``Grep``/    | implementation                 |
+    |               |   ``Glob``) and read-only bash commands         |                                |
+    |               |   (e.g. ``ls``, ``git status``)                  |                                |
+    |               | - Deny: any modification tool / command         |                                |
+    |               | - User-configured DENY or ASK rules take         |                                |
+    |               |   precedence over the read-only auto-allow      |                                |
+    +---------------+--------------------------------------------------+--------------------------------+
+    | BYPASS        | Skip all permission checks except explicit       | Sandboxed environments         |
+    |               | user-configured deny / ask rules and tool       | (container, VM), unattended    |
+    |               | DENY. **Safety ASKs from tools are NOT**         | runs where you fully trust     |
+    |               | **enforced** — including ``rm -rf /``, writes   | the agent                      |
+    |               | to ``~/.bashrc``, command-injection patterns,    |                                |
+    |               | etc. Use deny rules to protect specific paths.   |                                |
+    |               | For unattended runs that still need safety,      |                                |
+    |               | prefer DONT_ASK.                                 |                                |
+    +---------------+--------------------------------------------------+--------------------------------+
+    | DONT_ASK      | Convert every ASK (including safety ASKs and     | Scheduled tasks, background    |
+    |               | ASK-rule hits) to DENY. Safe-by-default for     | execution when user is away    |
+    |               | unattended execution.                            |                                |
+    +---------------+--------------------------------------------------+--------------------------------+
+
+    Attributes:
+        DEFAULT: Default mode - explicit permission per action. The
+            only auto-allow path is the tool's own ``check_permissions``
+            returning ALLOW (currently just ``Bash`` for recognized
+            read-only commands like ``ls``/``git status``).
+        ACCEPT_EDITS: Accept edits mode - automatically allows file
+            edits within working directories (including filesystem
+            bash commands whose every target is in a working dir).
+        EXPLORE: Explore mode - read-only; modifications are denied.
+        BYPASS: Bypass mode - skips safety checks; relies on user
+            deny / ask rules as the only guardrail.
+        DONT_ASK: Don't ask mode - converts all ASK decisions to DENY
+            (for unattended execution).
+    """  # noqa: E501
+
+    DEFAULT = "default"
+    ACCEPT_EDITS = "accept_edits"
+    EXPLORE = "explore"
+    BYPASS = "bypass"
+    DONT_ASK = "dont_ask"
+
+
+class PermissionBehavior(Enum):
+    """The behavior of permission.
+
+    Attributes:
+        ALLOW: Allow the operation
+        DENY: Deny the operation
+        ASK: Ask the user for permission
+        PASSTHROUGH: Let the permission engine continue with rule matching
+            (used by tools to defer decision to the engine)
+    """
+
+    ALLOW = "allow"
+    DENY = "deny"
+    ASK = "ask"
+    PASSTHROUGH = "passthrough"
diff --git a/src/agentscope/py.typed b/src/agentscope/py.typed
new file mode 100644
index 0000000..e69de29
diff --git a/src/agentscope/rag/__init__.py b/src/agentscope/rag/__init__.py
new file mode 100644
index 0000000..659c073
--- /dev/null
+++ b/src/agentscope/rag/__init__.py
@@ -0,0 +1,49 @@
+# -*- coding: utf-8 -*-
+"""The retrieval-augmented generation (RAG) module in AgentScope."""
+
+from ._chunker import ApproxTokenChunker, ChunkerBase
+from ._document import (
+    Section,
+    Chunk,
+)
+from ._parser import (
+    ImageParser,
+    ParserBase,
+    PDFParser,
+    PPTParser,
+    TextParser,
+    WordParser,
+    ExcelParser,
+)
+from ._vdb import (
+    DocumentSummary,
+    MilvusLiteStore,
+    VectorStoreBase,
+    VectorRecord,
+    VectorSearchResult,
+    QdrantStore,
+    MongoDBStore,
+)
+from ._knowledge import KnowledgeBase
+
+__all__ = [
+    "ApproxTokenChunker",
+    "ChunkerBase",
+    "Chunk",
+    "DocumentSummary",
+    "ImageParser",
+    "MilvusLiteStore",
+    "ParserBase",
+    "PDFParser",
+    "PPTParser",
+    "TextParser",
+    "WordParser",
+    "ExcelParser",
+    "Section",
+    "VectorStoreBase",
+    "VectorRecord",
+    "VectorSearchResult",
+    "QdrantStore",
+    "KnowledgeBase",
+    "MongoDBStore",
+]
diff --git a/src/agentscope/rag/_chunker/__init__.py b/src/agentscope/rag/_chunker/__init__.py
new file mode 100644
index 0000000..e8c2719
--- /dev/null
+++ b/src/agentscope/rag/_chunker/__init__.py
@@ -0,0 +1,10 @@
+# -*- coding: utf-8 -*-
+"""Chunker implementations for the RAG indexing pipeline."""
+
+from ._approx_token_chunker import ApproxTokenChunker
+from ._base import ChunkerBase
+
+__all__ = [
+    "ApproxTokenChunker",
+    "ChunkerBase",
+]
diff --git a/src/agentscope/rag/_chunker/_approx_token_chunker.py b/src/agentscope/rag/_chunker/_approx_token_chunker.py
new file mode 100644
index 0000000..fe26674
--- /dev/null
+++ b/src/agentscope/rag/_chunker/_approx_token_chunker.py
@@ -0,0 +1,172 @@
+# -*- coding: utf-8 -*-
+"""A chunker that splits text by an approximate token count.
+
+The token count is approximated as ``len(text.encode("utf-8")) // 4``,
+which avoids a hard dependency on any tokenizer library while staying
+within the right order of magnitude for most LLM tokenizers.
+"""
+from bisect import bisect_right
+from itertools import accumulate
+
+from ._base import ChunkerBase
+from .._document import Chunk, Section
+from ...message import TextBlock, DataBlock
+
+
+class ApproxTokenChunker(ChunkerBase):
+    """A chunker based on an approximate token counting strategy.
+
+    Text sections are sliced into pieces of at most ``chunk_size``
+    approximate tokens, with ``overlap`` approximate tokens shared
+    between two consecutive pieces.  The token count of a string is
+    approximated as ``len(text.encode("utf-8")) // 4``, so no
+    tokenizer dependency is required.
+
+    Sections carrying a :class:`~agentscope.message.DataBlock`
+    (images, video, etc.) are passed through unchanged as a single
+    chunk.
+
+    .. note:: Chunks never span across two input Sections, as
+        required by :class:`ChunkerBase`.
+    """
+
+    def __init__(self, chunk_size: int = 512, overlap: int = 50) -> None:
+        """Initialize the approx token chunker.
+
+        Args:
+            chunk_size (`int`, defaults to `512`):
+                The maximum number of approximate tokens per chunk.
+                Must be a positive integer.
+            overlap (`int`, defaults to `50`):
+                The number of approximate tokens shared between two
+                consecutive chunks.  Must be non-negative and smaller
+                than ``chunk_size``.
+
+        Raises:
+            `ValueError`:
+                If ``chunk_size`` is not positive, or ``overlap`` is
+                negative or not smaller than ``chunk_size``.
+        """
+        if chunk_size <= 0:
+            raise ValueError(
+                f"chunk_size must be positive, got {chunk_size}.",
+            )
+        if overlap < 0 or overlap >= chunk_size:
+            raise ValueError(
+                "overlap must satisfy 0 <= overlap < chunk_size, "
+                f"got overlap={overlap}, chunk_size={chunk_size}.",
+            )
+
+        self.chunk_size = chunk_size
+        self.overlap = overlap
+
+    async def chunk(self, sections: list[Section]) -> list[Chunk]:
+        """Chunk the input sections into smaller chunks based on an approx
+        token counting strategy.
+
+        Args:
+            sections (`list[Section]`):
+                A list of sections to chunk.
+
+        Returns:
+            `list[Chunk]`:
+                A list of chunks, with ``chunk_index`` numbered
+                ``0..N-1`` and ``total_chunks`` set to ``N`` on every
+                chunk.
+        """
+        chunks: list[Chunk] = []
+        for section in sections:
+            contents: list[TextBlock | DataBlock]
+            if isinstance(section.content, TextBlock):
+                contents = [
+                    TextBlock(text=piece)
+                    for piece in self._split_text(section.content.text)
+                ]
+            else:
+                # DataBlock pass-through: never slice multimodal data
+                contents = [section.content]
+
+            chunks.extend(
+                Chunk(
+                    content=content,
+                    source=section.source,
+                    chunk_index=0,  # renumbered below
+                    total_chunks=0,  # renumbered below
+                    metadata=dict(section.metadata),
+                )
+                for content in contents
+            )
+
+        for index, chunk in enumerate(chunks):
+            chunk.chunk_index = index
+            chunk.total_chunks = len(chunks)
+
+        return chunks
+
+    def _split_text(self, text: str) -> list[str]:
+        """Split text into pieces of at most ``chunk_size`` approx tokens.
+
+        Consecutive pieces share approximately ``overlap`` tokens.
+
+        Args:
+            text (`str`):
+                The text to split.
+
+        Returns:
+            `list[str]`:
+                The text pieces, in document order.
+        """
+        if self._approx_count_tokens(text) <= self.chunk_size:
+            return [text]
+
+        # Cumulative UTF-8 byte length after each character, so that
+        # the byte length of text[i:j] == byte_offsets[j] - byte_offsets[i]
+        byte_offsets = [0, *accumulate(len(c.encode("utf-8")) for c in text)]
+
+        chunk_bytes = self.chunk_size * 4
+        overlap_bytes = self.overlap * 4
+
+        pieces: list[str] = []
+        start = 0
+        while start < len(text):
+            # The largest end such that the slice fits the byte budget
+            end = (
+                bisect_right(
+                    byte_offsets,
+                    byte_offsets[start] + chunk_bytes,
+                )
+                - 1
+            )
+            # Always make progress, even for characters whose UTF-8
+            # encoding exceeds the budget on their own
+            end = max(end, start + 1)
+            pieces.append(text[start:end])
+
+            if end >= len(text):
+                break
+
+            # Step back by the overlap budget, ensuring forward progress
+            next_start = (
+                bisect_right(
+                    byte_offsets,
+                    byte_offsets[end] - overlap_bytes,
+                )
+                - 1
+            )
+            start = max(next_start, start + 1)
+
+        return pieces
+
+    @staticmethod
+    def _approx_count_tokens(text: str) -> int:
+        """The approx count of tokens.
+
+        Args:
+            text (`str`):
+                The text to be counted.
+
+        Returns:
+            `int`:
+                The approx count of tokens.
+        """
+        return len(text.encode("utf-8")) // 4
diff --git a/src/agentscope/rag/_chunker/_base.py b/src/agentscope/rag/_chunker/_base.py
new file mode 100644
index 0000000..a766d20
--- /dev/null
+++ b/src/agentscope/rag/_chunker/_base.py
@@ -0,0 +1,62 @@
+# -*- coding: utf-8 -*-
+"""Abstract base class for chunkers.
+
+A :class:`ChunkerBase` subclass takes the :class:`Section` list
+produced by a :class:`~agentscope.rag.ParserBase` and splits the
+content into final :class:`Chunk` objects suitable for embedding and
+storage in a vector database.
+
+Chunkers are **format-agnostic** — they operate on the unified
+``TextBlock | DataBlock`` content carried in each Section.  Long
+:class:`TextBlock` content is sliced according to a chunking strategy
+(by character count, by tokens, by semantic boundaries, etc.); short
+text and :class:`DataBlock` content are passed through unchanged.
+
+Chunkers **never combine content across Section boundaries**.  This
+guarantee preserves the structural metadata attached by the Parser
+(page numbers, slide indices, embedded-image isolation, etc.).
+"""
+from abc import ABC, abstractmethod
+
+from .._document import Chunk, Section
+
+
+class ChunkerBase(ABC):
+    """Abstract base class for chunkers.
+
+    Subclasses implement a specific chunking strategy (by character
+    count, by token count, by semantic boundary, etc.).  The
+    chunker is configured once at construction time and reused
+    across many ``chunk()`` calls within the same knowledge base.
+
+    Subclasses must guarantee:
+
+    - **No cross-Section merging**: every output :class:`Chunk` is
+      derived from exactly one input :class:`Section`.
+    - **DataBlock pass-through**: a Section whose content is a
+      :class:`~agentscope.message.DataBlock` becomes a single Chunk
+      with the same content; multimodal data is never sliced.
+    - **Continuous indexing**: ``chunk_index`` runs from ``0`` to
+      ``total_chunks - 1`` across the entire output list, even
+      when the input contains many Sections.
+    - **Consistent total_chunks**: every output Chunk carries the
+      same ``total_chunks`` value (the length of the output list).
+    - **Metadata inheritance**: each output Chunk's ``source`` and
+      ``metadata`` are copied from its parent Section.
+    """
+
+    @abstractmethod
+    async def chunk(self, sections: list[Section]) -> list[Chunk]:
+        """Split a list of Sections into Chunks.
+
+        Args:
+            sections (`list[Section]`):
+                The Sections produced by a :class:`ParserBase`, in
+                document order.
+
+        Returns:
+            `list[Chunk]`:
+                The final chunks, in document order, with
+                ``chunk_index`` numbered ``0..N-1`` and
+                ``total_chunks`` set to ``N`` on every chunk.
+        """
diff --git a/src/agentscope/rag/_document.py b/src/agentscope/rag/_document.py
new file mode 100644
index 0000000..b6fce8b
--- /dev/null
+++ b/src/agentscope/rag/_document.py
@@ -0,0 +1,102 @@
+# -*- coding: utf-8 -*-
+"""Data structures used in the RAG indexing pipeline.
+
+The indexing pipeline has two stages, each producing its own
+structured output:
+
+1. :class:`Section` — produced by a :class:`ParserBase` from a raw
+   file.  Each ``Section`` represents one "natural boundary" of the
+   source (a PDF page, a PPTX slide, an embedded image, a Markdown
+   heading section, etc.).  A ``Chunker`` never combines content
+   across two ``Section`` instances, so ``Section`` is also a hard
+   boundary that prevents leakage of format-specific structure into
+   downstream chunks.
+
+2. :class:`Chunk` — produced by a :class:`ChunkerBase` from one or
+   more ``Section`` instances.  Each ``Chunk`` is the final unit
+   that gets embedded and inserted into the vector store.
+
+Neither structure is persisted on its own — they are transient
+in-memory carriers between pipeline stages.  Persistence happens at
+the :class:`~agentscope.rag.VectorRecord` and
+``KnowledgeDocumentRecord`` layers.
+"""
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from ..message import TextBlock, DataBlock
+
+
+class Section(BaseModel):
+    """A single natural section produced by a :class:`ParserBase`.
+
+    A ``Section`` represents one logical region of the source file.
+    The :class:`ChunkerBase` guarantees that no resulting
+    :class:`Chunk` ever spans content from two different sections.
+
+    The granularity of a ``Section`` is format-specific:
+
+    - **PDF**: one section per page (plus separate sections for
+      embedded images).
+    - **PPTX**: one section per slide.
+    - **Markdown**: one section per top-level heading, or the entire
+      file if unstructured.
+    - **TXT / image / video**: one section for the whole file.
+    """
+
+    content: TextBlock | DataBlock
+    """The section content.  Text sections use :class:`TextBlock`;
+    multimodal sections (images, video, etc.) use :class:`DataBlock`."""
+
+    source: str
+    """The source filename (e.g. ``"report.pdf"``).  Carried through
+    to every downstream :class:`Chunk` and into the vector store
+    metadata for citation / display."""
+
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    """Format-specific metadata written by the parser.  Examples:
+
+    - PDFParser: ``{"page": 3}``
+    - PPTXParser: ``{"slide": 2}``
+    - ExcelParser: ``{"sheet": "Q3 Sales"}``
+
+    These keys are not part of any retrieval / pipeline contract —
+    they are passed through verbatim to the vector store metadata for
+    later citation.  Each Chunk inherits this dict from its parent
+    Section.
+    """
+
+
+class Chunk(BaseModel):
+    """A final indexable chunk produced by a :class:`ChunkerBase`.
+
+    Each ``Chunk`` corresponds to one record in the vector store.
+    The required structural fields (``source``, ``chunk_index``,
+    ``total_chunks``) enable downstream features such as "expand
+    context around a hit" during retrieval.
+    """
+
+    content: TextBlock | DataBlock
+    """The chunk content (sliced from a text :class:`Section`, or a
+    multimodal :class:`DataBlock` passed through unchanged)."""
+
+    source: str
+    """The source filename — inherited from the parent
+    :class:`Section`.  Used for display / citation."""
+
+    chunk_index: int
+    """The 0-based index of this chunk **within the document**.
+    Sequential across all sections of the same source file.  Used to
+    locate neighbouring chunks for "context expansion" at query time.
+    """
+
+    total_chunks: int
+    """The total number of chunks produced from the same source file.
+    Together with :attr:`chunk_index` lets callers know whether a hit
+    is near the start / end of the document, and bounds the
+    expansion range."""
+
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    """Format-specific metadata inherited from the parent
+    :class:`Section`.  See :attr:`Section.metadata`."""
diff --git a/src/agentscope/rag/_knowledge.py b/src/agentscope/rag/_knowledge.py
new file mode 100644
index 0000000..cc87c08
--- /dev/null
+++ b/src/agentscope/rag/_knowledge.py
@@ -0,0 +1,384 @@
+# -*- coding: utf-8 -*-
+"""Runtime handle for a single knowledge base.
+
+A :class:`KnowledgeBase` instance is the **single algorithmic source of
+truth** for talking to one knowledge base: it pairs an embedding model
+with a vector-store collection (optionally scoped by a payload
+``metadata_filter``) and exposes the four operations a caller ever
+needs — :meth:`search`, :meth:`insert_document`,
+:meth:`delete_document`, :meth:`list_documents`.
+
+The handle is *narrow on purpose* — it carries the resolved runtime
+state (embedding model + vector store + scope) and delegates every
+operation to the bound :class:`VectorStoreBase`.  Document parsing,
+chunking, credential resolution, dimension policy validation, and
+persistence of knowledge-base records all belong one layer up
+(service-side :class:`KnowledgeBaseManagerBase` for hosted
+deployments; the caller directly otherwise).
+
+The backing collection is created on first use — each operation
+transparently calls :meth:`ensure_collection`, which is itself
+idempotent and memoised after the first success, so the only cost is
+one extra round-trip on the very first call against a fresh
+deployment.
+
+``metadata_filter`` is the defense-in-depth scoping mechanism for
+co-locating multiple logical knowledge bases inside the same physical
+collection — typically multi-tenant deployments where every record
+carries a ``{"tenant_id": "..."}`` payload.  It is set once at
+construction time and **always** applied: search/list never escape
+it, and insert forces it onto every chunk's metadata so a malicious or
+buggy parser cannot rebind a record into another scope.
+"""
+
+import asyncio
+
+from ._document import Chunk
+from ._vdb import VectorRecord, VectorSearchResult, VectorStoreBase
+from .._utils._common import _generate_id
+from ..embedding import EmbeddingModelBase
+from ..message import DataBlock, TextBlock
+from ._vdb import DocumentSummary
+
+
+class KnowledgeBase:
+    """Runtime handle for one knowledge base.
+
+    Binds an embedding model and a vector-store collection together so
+    callers can retrieve / insert / delete / list documents without
+    repeating the wiring.  Cheap to construct (no I/O); the collection
+    itself is created lazily on the first operation, so a fresh
+    deployment "just works" without an explicit setup step.
+
+    .. code-block:: python
+
+        kb = KnowledgeBase(
+            name="company-handbook",
+            description="Internal HR and onboarding documents.",
+            embedding_model=embedding_model,
+            vector_store=vector_store,
+            collection="handbook",
+        )
+        await kb.insert_document(chunks)
+        results = await kb.search(["What is the PTO policy?"])
+    """
+
+    name: str
+    """Agent-oriented knowledge base name — used by tool descriptions
+    and frontend rendering."""
+
+    description: str
+    """Agent-oriented knowledge base description — what this knowledge
+    base contains and when to retrieve from it."""
+
+    def __init__(
+        self,
+        name: str,
+        description: str,
+        embedding_model: EmbeddingModelBase,
+        vector_store: VectorStoreBase,
+        collection: str,
+        metadata_filter: dict | None = None,
+    ) -> None:
+        """Initialize the runtime handle.
+
+        Args:
+            name (`str`):
+                Agent-oriented knowledge base name.  Surfaced to the
+                LLM (via tool descriptions) and to the front-end.
+            description (`str`):
+                Agent-oriented description.  Should answer "what is in
+                this knowledge base and when should I search it?" — the
+                LLM uses it to decide whether to call the search tool
+                in agentic mode.
+            embedding_model (`EmbeddingModelBase`):
+                The embedding model used to embed both queries and
+                inserted chunks.  Must be the same model used at
+                indexing time and at retrieval time, otherwise vectors
+                will not be comparable.
+            vector_store (`VectorStoreBase`):
+                The shared vector-store connection.  The store must
+                already be entered (its own ``__aenter__`` already
+                called) before any operation on this handle runs.
+            collection (`str`):
+                The physical collection backing this knowledge base.
+                Created lazily on the first operation; see
+                :meth:`ensure_collection`.
+            metadata_filter (`dict | None`, optional):
+                Defense-in-depth payload filter.  When set:
+
+                - :meth:`search` and :meth:`list_documents` restrict
+                  results to records whose payload matches every
+                  ``key == value`` pair;
+                - :meth:`insert_document` forces these keys onto every
+                  inserted chunk's metadata, overriding caller-supplied
+                  values, so records cannot leak into another scope.
+
+                ``None`` disables filtering — the default for
+                deployments where every knowledge base owns its
+                collection outright.
+        """
+        self.name = name
+        self.description = description
+        self._embedding_model = embedding_model
+        self._vector_store = vector_store
+        self._collection = collection
+        self._metadata_filter = metadata_filter
+        # Memoise the "collection exists" check after the first
+        # successful ensure_collection so subsequent operations avoid
+        # the extra round-trip.
+        self._collection_ready = False
+
+    # ------------------------------------------------------------------
+    # Read-only accessors
+    # ------------------------------------------------------------------
+
+    @property
+    def embedding_model(self) -> EmbeddingModelBase:
+        """The bound embedding model."""
+        return self._embedding_model
+
+    @property
+    def vector_store(self) -> VectorStoreBase:
+        """The bound vector store."""
+        return self._vector_store
+
+    @property
+    def collection(self) -> str:
+        """The physical collection backing this knowledge base."""
+        return self._collection
+
+    @property
+    def metadata_filter(self) -> dict | None:
+        """The defense-in-depth payload filter, or ``None``."""
+        return self._metadata_filter
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def ensure_collection(self) -> None:
+        """Idempotently create the backing collection if missing.
+
+        Called transparently at the top of every public operation —
+        callers should not need to invoke it themselves.  Memoised on
+        the instance after the first success, so subsequent calls are
+        a single ``if`` check.
+
+        Looks up the collection via
+        :meth:`VectorStoreBase.has_collection` and creates it with the
+        embedding model's :attr:`~EmbeddingModelBase.dimensions` when
+        absent.
+
+        Raises whatever the backend raises if the collection exists at
+        an incompatible dimension (the backend is the authority on
+        that; we do not double-check here).
+        """
+        if self._collection_ready:
+            return
+        if not await self._vector_store.has_collection(self._collection):
+            await self._vector_store.create_collection(
+                self._collection,
+                dimensions=self._embedding_model.dimensions,
+            )
+        self._collection_ready = True
+
+    # ------------------------------------------------------------------
+    # Search
+    # ------------------------------------------------------------------
+
+    async def search(
+        self,
+        queries: list[str | TextBlock | DataBlock],
+        top_k: int = 5,
+        score_threshold: float | None = None,
+    ) -> list[VectorSearchResult]:
+        """Search the knowledge base with one or more queries.
+
+        All queries are embedded in a single batch, then searched
+        concurrently against the bound collection (with
+        :attr:`metadata_filter` applied).  Hits are deduplicated by
+        ``(document_id, chunk_index)`` keeping the best score,
+        optionally filtered by ``score_threshold``, sorted by
+        descending score, and truncated to ``top_k``.
+
+        Args:
+            queries (`list[str | TextBlock | DataBlock]`):
+                Query inputs.  Text may be either bare ``str`` or
+                :class:`TextBlock`; :class:`DataBlock` items are
+                **silently dropped** when the bound embedding model
+                does not declare ``supports_multimodal`` — text-only
+                models would otherwise reject them.  Callers can
+                therefore pass a mixed list without per-KB filtering.
+            top_k (`int`, defaults to ``5``):
+                Maximum number of results returned across all queries
+                (after dedup).
+            score_threshold (`float | None`, optional):
+                Minimum similarity score for a hit to be retained.
+                Only meaningful for similarity metrics where higher is
+                better (cosine / dot-product).  ``None`` disables
+                filtering.
+
+        Returns:
+            `list[VectorSearchResult]`:
+                At most ``top_k`` deduplicated hits ordered by
+                descending similarity score.  Empty when there are no
+                queries the bound embedding model can consume.
+        """
+        if not queries:
+            return []
+
+        if not self._embedding_model.supports_multimodal:
+            queries = [q for q in queries if not isinstance(q, DataBlock)]
+            if not queries:
+                return []
+
+        await self.ensure_collection()
+        response = await self._embedding_model(queries)
+
+        results_per_query = await asyncio.gather(
+            *(
+                self._vector_store.search(
+                    collection=self._collection,
+                    query_vector=vector,
+                    top_k=top_k,
+                    metadata_filter=self._metadata_filter,
+                )
+                for vector in response.embeddings
+            ),
+        )
+
+        best: dict[tuple[str, int], VectorSearchResult] = {}
+        for results in results_per_query:
+            for result in results:
+                if (
+                    score_threshold is not None
+                    and result.score < score_threshold
+                ):
+                    continue
+                # ``(document_id, chunk_index)`` is the stable identity
+                # of a chunk: it survives reindex (block UUIDs do not)
+                # and uniquely names "this slice of that document"
+                # regardless of which query surfaced it.
+                key = (result.document_id, result.chunk.chunk_index)
+                if key not in best or result.score > best[key].score:
+                    best[key] = result
+
+        merged = sorted(
+            best.values(),
+            key=lambda result: result.score,
+            reverse=True,
+        )
+        return merged[:top_k]
+
+    # ------------------------------------------------------------------
+    # Document management
+    # ------------------------------------------------------------------
+
+    async def insert_document(
+        self,
+        chunks: list[Chunk],
+        document_id: str | None = None,
+        document_metadata: dict | None = None,
+    ) -> str:
+        """Embed and insert a list of chunks as a single source document.
+
+        All chunks share the resolved ``document_id``;
+        :meth:`delete_document` later removes them as a unit.  Each
+        chunk's metadata is merged in this precedence (highest wins):
+
+        1. :attr:`metadata_filter` keys — defense-in-depth scoping, so
+           a chunk can never be inserted with a payload that escapes
+           the filter (any escape would silently disappear at retrieve
+           time anyway, but failing closed at insert is clearer).
+        2. The chunk's pre-existing ``metadata`` — parser-supplied.
+        3. ``document_metadata`` — document-level fields propagated
+           down (filename, media type, upload time, ...).
+
+        Args:
+            chunks (`list[Chunk]`):
+                The pre-chunked document content (already produced by
+                a parser + chunker pipeline).  An empty list is a
+                no-op.
+            document_id (`str | None`, optional):
+                The document identifier.  When ``None`` a fresh UUID
+                hex is generated and returned so the caller can record
+                it for future :meth:`delete_document` calls.
+            document_metadata (`dict | None`, optional):
+                Document-level metadata (filename, media type, size,
+                upload time, ...).  Merged into each chunk's
+                ``metadata``.
+
+        Returns:
+            `str`:
+                The (possibly generated) document id.
+
+        Raises:
+            `RuntimeError`:
+                If the embedding model returns a number of vectors
+                that does not match the number of chunks.
+        """
+        if not chunks:
+            return document_id or _generate_id()
+        document_id = document_id or _generate_id()
+
+        await self.ensure_collection()
+
+        # Precedence: metadata_filter wins (security boundary), then
+        # chunk metadata, then document_metadata.  See docstring.
+        for chunk in chunks:
+            chunk.metadata = {
+                **(document_metadata or {}),
+                **chunk.metadata,
+                **(self._metadata_filter or {}),
+            }
+
+        response = await self._embedding_model(
+            [chunk.content for chunk in chunks],
+        )
+
+        if len(response.embeddings) != len(chunks):
+            raise RuntimeError(
+                f"Embedding model returned {len(response.embeddings)} "
+                f"vectors for {len(chunks)} chunks.",
+            )
+
+        records = [
+            VectorRecord(
+                vector=vector,
+                document_id=document_id,
+                chunk=chunk,
+            )
+            for vector, chunk in zip(response.embeddings, chunks)
+        ]
+        await self._vector_store.insert(self._collection, records)
+        return document_id
+
+    async def delete_document(self, document_id: str) -> None:
+        """Remove every record for one source document.
+
+        Args:
+            document_id (`str`):
+                The source document id whose records should be removed.
+        """
+        await self.ensure_collection()
+        await self._vector_store.delete(
+            self._collection,
+            document_id,
+        )
+
+    async def list_documents(self) -> list["DocumentSummary"]:
+        """List all distinct source documents in this knowledge base.
+
+        Filtered by :attr:`metadata_filter` when set, so callers only
+        ever see documents within their own scope.
+
+        Returns:
+            `list[DocumentSummary]`:
+                One summary per indexed document, in unspecified order.
+        """
+        await self.ensure_collection()
+        return await self._vector_store.list_documents(
+            self._collection,
+            metadata_filter=self._metadata_filter,
+        )
diff --git a/src/agentscope/rag/_parser/__init__.py b/src/agentscope/rag/_parser/__init__.py
new file mode 100644
index 0000000..f461b04
--- /dev/null
+++ b/src/agentscope/rag/_parser/__init__.py
@@ -0,0 +1,20 @@
+# -*- coding: utf-8 -*-
+"""File parser implementations for the RAG indexing pipeline."""
+
+from ._base import ParserBase
+from ._image import ImageParser
+from ._pdf import PDFParser
+from ._ppt import PPTParser
+from ._text import TextParser
+from ._word import WordParser
+from ._excel import ExcelParser
+
+__all__ = [
+    "ParserBase",
+    "PDFParser",
+    "PPTParser",
+    "ImageParser",
+    "TextParser",
+    "WordParser",
+    "ExcelParser",
+]
diff --git a/src/agentscope/rag/_parser/_base.py b/src/agentscope/rag/_parser/_base.py
new file mode 100644
index 0000000..b980558
--- /dev/null
+++ b/src/agentscope/rag/_parser/_base.py
@@ -0,0 +1,116 @@
+# -*- coding: utf-8 -*-
+"""Abstract base class for file parsers.
+
+A :class:`ParserBase` subclass handles **one file format**.  Its job
+is to read a file's raw bytes and produce a list of
+:class:`~agentscope.rag.Section` objects, each representing a natural
+boundary of the source (e.g. one PDF page, one PPTX slide, one
+embedded image).
+
+Parsers **do not chunk text**.  Long text is left intact inside the
+Section; splitting happens later in a
+:class:`~agentscope.rag.ChunkerBase`.  Parsers also do not need to
+worry about output size — only about preserving the structural
+boundaries that downstream consumers must not cross.
+"""
+import mimetypes
+from abc import ABC, abstractmethod
+
+from .._document import Section
+
+
+class ParserBase(ABC):
+    """Abstract base class for file-format parsers.
+
+    Each subclass handles a single file format (or a related family,
+    e.g. all plain-text MIME types).  Subclasses are typically
+    instantiated once and reused across many ``parse()`` calls.
+
+    Subclasses should be stateless or thread-safe — a single
+    instance may be invoked concurrently from multiple agent runs.
+
+    Subclasses must declare :attr:`supported_media_types` so that the
+    KnowledgeBaseManager can route uploaded files to the right parser
+    based on standard IANA media types (RFC 6838).
+    """
+
+    supported_media_types: list[str]
+    """Standard IANA media types (RFC 6838) this parser handles,
+    e.g. ``["application/pdf"]`` or
+    ``["text/plain", "text/markdown"]``.  Used by the
+    KnowledgeBaseManager to select a parser for an uploaded file."""
+
+    @classmethod
+    def supported_extensions(cls) -> list[str]:
+        """Filename extensions (including the leading ``.``) this parser
+        can produce uploads for.
+
+        The base implementation derives extensions from
+        :attr:`supported_media_types` via
+        :func:`mimetypes.guess_all_extensions` — good enough for clean
+        IANA types like ``application/pdf``.  Subclasses **should
+        override** this when the default reverse-lookup is noisy
+        (``text/plain`` resolves to ``.bat`` / ``.c`` / ``.pl`` and a
+        dozen other developer extensions no KB user wants in the file
+        picker) or when a media type has no registered extension at all
+        (``application/x-yaml`` returns the empty list).
+
+        The result is consumed by the front-end's ``<input accept>`` and
+        by the client-side filename guard; it is **not** consulted for
+        media-type routing — that always goes through
+        :attr:`supported_media_types`.
+
+        Returns:
+            `list[str]`:
+                Deduplicated, sorted extensions (each starting with
+                ``.``).  May be empty when no media type resolves.
+        """
+        out: set[str] = set()
+        for media_type in cls.supported_media_types:
+            out.update(mimetypes.guess_all_extensions(media_type))
+        return sorted(out)
+
+    @abstractmethod
+    async def parse(
+        self,
+        file: bytes | str,
+        filename: str,
+    ) -> list[Section]:
+        """Parse a file into a list of :class:`Section` objects.
+
+        The ``file`` argument is a union covering the three call sites
+        a parser sees in practice:
+
+        - ``bytes`` — the raw payload, as handed in by HTTP uploads
+          and blob-store reads.
+        - ``str`` for binary parsers (PDF, PPT, image, …) — a
+          **filesystem path** to the file to read.  The parser opens
+          the path itself; callers do not need to read the bytes first.
+        - ``str`` for :class:`TextParser` — disambiguated at runtime:
+          if the string names an existing file on disk it is treated
+          as a path and the file is decoded with the configured
+          encoding; otherwise it is treated as pre-decoded text.
+
+        Args:
+            file (`bytes | str`):
+                The file content or a path to it (see above).
+            filename (`str`):
+                The original filename (e.g. ``"report.pdf"``).  Used
+                for error messages and copied into each Section's
+                :attr:`Section.source` field for downstream display
+                / citation.
+
+        Returns:
+            `list[Section]`:
+                One Section per natural boundary in the source file.
+                For unstructured formats (plain text, image, video),
+                a single Section may cover the whole file.  Sections
+                are returned in document order.
+
+        Raises:
+            `TypeError`: If the subclass does not accept the supplied
+                ``file`` form.
+            `FileNotFoundError`: If a binary parser is handed a
+                ``str`` that does not name an existing file.
+            `ValueError`: If the file cannot be parsed.
+        """
diff --git a/src/agentscope/rag/_parser/_excel.py b/src/agentscope/rag/_parser/_excel.py
new file mode 100644
index 0000000..46909c8
--- /dev/null
+++ b/src/agentscope/rag/_parser/_excel.py
@@ -0,0 +1,462 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Excel (.xlsx / .xls) file parser.
+
+Reads an Excel workbook sheet-by-sheet and emits :class:`Section`
+objects.  Each sheet's tabular content is rendered as a single text
+section (in Markdown or JSON format); embedded images (when enabled)
+are emitted as their own :class:`DataBlock` sections.
+
+Supported options: ``include_sheet_names``, ``include_cell_coordinates``,
+``include_image``, ``separate_sheet``, ``table_format``.  Chunking is
+**not** done here — long text stays intact inside a section and is split
+downstream by a :class:`~agentscope.rag.ChunkerBase`.
+"""
+import base64
+import io
+import json
+from typing import Any, Literal
+
+from ..._logging import logger
+from ...message import Base64Source, DataBlock, TextBlock
+from .._document import Section
+from ._base import ParserBase
+from ._utils import _guess_image_media_type
+
+
+def _get_excel_column_name(col_index: int) -> str:
+    """Convert a 0-based column index to an Excel column name.
+
+    Args:
+        col_index (`int`):
+            Zero-based column index (0 → ``"A"``, 25 → ``"Z"``,
+            26 → ``"AA"``, etc.).
+
+    Returns:
+        `str`:
+            The corresponding Excel column letter(s).
+    """
+    result = ""
+    col_index += 1
+    while col_index > 0:
+        col_index -= 1
+        result = chr(ord("A") + col_index % 26) + result
+        col_index //= 26
+    return result
+
+
+def _extract_table_data(df: Any) -> list[list[str]]:
+    """Extract table data from a pandas DataFrame.
+
+    NaN values are converted to empty strings, and Windows-style line
+    breaks (``\\r\\n``) are normalised to ``\\n``.
+
+    Args:
+        df (`pandas.DataFrame`):
+            The DataFrame to extract data from.
+
+    Returns:
+        `list[list[str]]`:
+            A 2-D list where the first row is the column header and
+            subsequent rows contain the cell values as strings.
+    """
+    import pandas as pd
+
+    header = [str(col).strip() for col in df.columns]
+    rows: list[list[str]] = [header]
+    for _, row in df.iterrows():
+        cells: list[str] = []
+        for val in row:
+            if pd.isna(val):
+                cells.append("")
+            else:
+                text = str(val).strip()
+                text = text.replace("\r\n", "\n").replace("\r", "\n")
+                cells.append(text)
+        rows.append(cells)
+    return rows
+
+
+def _extract_images_from_worksheet(
+    worksheet: Any,
+    filename: str,
+) -> list[tuple[int, DataBlock]]:
+    """Extract images from an openpyxl worksheet with their row positions.
+
+    Args:
+        worksheet (`openpyxl.worksheet.worksheet.Worksheet`):
+            The openpyxl worksheet to scan for embedded images.
+        filename (`str`):
+            Source filename, stored in each :class:`DataBlock`'s
+            ``name`` field.
+
+    Returns:
+        `list[tuple[int, DataBlock]]`:
+            A list of ``(row_index, DataBlock)`` tuples, where
+            ``row_index`` is 0-based.  Images whose anchor cannot
+            be determined default to row 0.
+    """
+    images: list[tuple[int, DataBlock]] = []
+
+    if not (hasattr(worksheet, "_images") and worksheet._images):
+        return images
+
+    for img in worksheet._images:
+        try:
+            row_index = 0
+            if hasattr(img, "anchor") and hasattr(img.anchor, "_from"):
+                row_index = img.anchor._from.row
+
+            img_data = img._data()
+            media_type = _guess_image_media_type(img_data)
+            b64_data = base64.b64encode(img_data).decode("utf-8")
+
+            images.append(
+                (
+                    row_index,
+                    DataBlock(
+                        source=Base64Source(
+                            media_type=media_type,
+                            data=b64_data,
+                        ),
+                        name=filename,
+                    ),
+                ),
+            )
+        except Exception as e:
+            logger.warning("Failed to extract image from worksheet: %s", e)
+
+    return images
+
+
+class ExcelParser(ParserBase):
+    """Parser for Excel ``.xlsx`` / ``.xls`` files.
+
+    Each sheet is scanned for tabular data and (optionally) images.
+    Tables are rendered as Markdown pipe-tables or JSON arrays; images
+    are emitted as standalone :class:`DataBlock` sections.
+
+    When ``separate_sheet=True`` each sheet becomes a batch of
+    sections that never intermix with other sheets, making it possible
+    for a downstream chunker to keep sheets apart.
+
+    .. note:: The table content can be extracted in Markdown or JSON format.
+
+        **Markdown format example** (``include_cell_coordinates=False``):
+
+        .. code-block:: text
+
+            | Name  | Age | City     |
+            |-------|-----|----------|
+            | Alice | 25  | New York |
+
+        **JSON format example** (``include_cell_coordinates=True``):
+
+        .. code-block:: json
+
+            {"A1": "Name", "B1": "Age", "C1": "City"}
+            {"A2": "Alice", "B2": "25", "C2": "New York"}
+    """
+
+    supported_media_types: list[str] = [
+        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        "application/vnd.ms-excel",
+    ]
+
+    @classmethod
+    def supported_extensions(cls) -> list[str]:
+        """Return ``[".xlsx", ".xls"]``."""
+        return [".xls", ".xlsx"]
+
+    def __init__(
+        self,
+        include_sheet_names: bool = True,
+        include_cell_coordinates: bool = False,
+        include_image: bool = False,
+        separate_sheet: bool = False,
+        table_format: Literal["markdown", "json"] = "markdown",
+    ) -> None:
+        """Initialize the Excel parser.
+
+        Args:
+            include_sheet_names (`bool`, defaults to ``True``):
+                Whether to prepend each sheet's name as a header.
+            include_cell_coordinates (`bool`, defaults to ``False``):
+                Whether to include cell coordinates (e.g. ``[A1]``) in
+                the rendered table.
+            include_image (`bool`, defaults to ``False``):
+                Whether to extract and include embedded images.
+                Requires ``openpyxl``.
+            separate_sheet (`bool`, defaults to ``False``):
+                If ``True``, images and table text from different
+                sheets are never combined into the same section.
+            table_format (`Literal["markdown", "json"]``, defaults to
+                ``"markdown"``):
+                How to render tables.
+
+        Raises:
+            `ValueError`: If ``table_format`` is not ``"markdown"``
+                or ``"json"``.
+        """
+        if table_format not in ("markdown", "json"):
+            raise ValueError(
+                "The table_format must be one of 'markdown' or 'json', "
+                f"got {table_format!r}.",
+            )
+        self.include_sheet_names = include_sheet_names
+        self.include_cell_coordinates = include_cell_coordinates
+        self.include_image = include_image
+        self.separate_sheet = separate_sheet
+        self.table_format = table_format
+
+    async def parse(
+        self,
+        file: bytes | str,
+        filename: str,
+    ) -> list[Section]:
+        """Parse an Excel file into a list of :class:`Section` objects.
+
+        Args:
+            file (`bytes | str`):
+                Either the raw Excel bytes, or a filesystem path to
+                the Excel file.
+            filename (`str`):
+                The source filename, copied into each Section's
+                :attr:`Section.source`.
+
+        Returns:
+            `list[Section]`:
+                Sections in sheet order.  When ``separate_sheet=True``,
+                text sections carry ``{"sheet": "<name>"}`` metadata
+                and image sections add
+                ``{"media_type": "image/..."}``.  When
+                ``separate_sheet=False`` (default), all text is merged
+                into a single section with ``metadata={}``.
+
+        Raises:
+            `FileNotFoundError`: If ``file`` is a ``str`` pointing to
+                a path that does not exist.
+            `ImportError`: If :mod:`pandas` is not installed.
+            `ValueError`: If the bytes cannot be parsed.
+        """
+        try:
+            import pandas as pd
+        except ImportError as e:
+            raise ImportError(
+                "Please install pandas to use the Excel parser. "
+                "You can install it by `pip install pandas` (or "
+                "`pip install agentscope[rag]`).",
+            ) from e
+
+        if isinstance(file, str):
+            excel_file = pd.ExcelFile(file)
+        else:
+            excel_file = pd.ExcelFile(io.BytesIO(file))
+
+        workbook = None
+        try:
+            if self.include_image:
+                try:
+                    from openpyxl import load_workbook
+
+                    if isinstance(file, str):
+                        workbook = load_workbook(file)
+                    else:
+                        workbook = load_workbook(io.BytesIO(file))
+                except ImportError:
+                    logger.warning(
+                        "openpyxl not available, image extraction disabled.",
+                    )
+                except Exception as e:
+                    logger.warning("Failed to load workbook for images: %s", e)
+
+            sections: list[Section] = []
+
+            for sheet_name in excel_file.sheet_names:
+                sheet_sections = self._parse_sheet(
+                    excel_file,
+                    sheet_name,
+                    filename,
+                    workbook,
+                )
+                sections.extend(sheet_sections)
+
+            if not self.separate_sheet:
+                sections = self._merge_text_sections(sections, filename)
+
+            return sections
+        finally:
+            if workbook is not None:
+                workbook.close()
+            excel_file.close()
+
+    # ------------------------------------------------------------------
+    # Sheet-level parsing
+    # ------------------------------------------------------------------
+
+    def _parse_sheet(
+        self,
+        excel_file: Any,
+        sheet_name: str,
+        filename: str,
+        workbook: Any = None,
+    ) -> list[Section]:
+        """Parse a single sheet and return its sections."""
+        sheet_sections: list[Section] = []
+
+        try:
+            df = excel_file.parse(sheet_name=sheet_name)
+        except Exception as e:
+            logger.warning("Failed to parse sheet '%s': %s", sheet_name, e)
+            return sheet_sections
+
+        if df.empty:
+            return sheet_sections
+
+        table_data = _extract_table_data(df)
+
+        if self.table_format == "markdown":
+            table_text = self._table_to_markdown(table_data, sheet_name)
+        else:
+            table_text = self._table_to_json(table_data, sheet_name)
+
+        if table_text:
+            sheet_sections.append(
+                Section(
+                    content=TextBlock(text=table_text),
+                    source=filename,
+                    metadata={"sheet": sheet_name},
+                ),
+            )
+
+        if self.include_image and workbook is not None:
+            try:
+                worksheet = workbook[sheet_name]
+                images = _extract_images_from_worksheet(
+                    worksheet,
+                    filename,
+                )
+                images.sort(key=lambda x: x[0])
+
+                for _row, block in images:
+                    sheet_sections.append(
+                        Section(
+                            content=block,
+                            source=filename,
+                            metadata={
+                                "sheet": sheet_name,
+                                "media_type": block.source.media_type,
+                            },
+                        ),
+                    )
+            except Exception as e:
+                logger.warning(
+                    "Failed to extract images from sheet '%s': %s",
+                    sheet_name,
+                    e,
+                )
+
+        return sheet_sections
+
+    # ------------------------------------------------------------------
+    # Cross-sheet merging
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _merge_text_sections(
+        sections: list[Section],
+        filename: str,
+    ) -> list[Section]:
+        """Merge all text sections into a single section.
+
+        When ``separate_sheet=False`` (default), text from all sheets
+        is concatenated into one :class:`Section` so a downstream
+        chunker may create chunks that span sheet boundaries.  Image
+        sections are kept unchanged and appended after the merged text.
+        """
+        text_parts: list[str] = []
+        non_text: list[Section] = []
+        for section in sections:
+            if isinstance(section.content, TextBlock):
+                text_parts.append(section.content.text)
+            else:
+                non_text.append(section)
+
+        result: list[Section] = []
+        if text_parts:
+            result.append(
+                Section(
+                    content=TextBlock(text="\n".join(text_parts)),
+                    source=filename,
+                    metadata={},
+                ),
+            )
+        result.extend(non_text)
+        return result
+
+    # ------------------------------------------------------------------
+    # Table rendering
+    # ------------------------------------------------------------------
+
+    def _table_to_markdown(
+        self,
+        table_data: list[list[str]],
+        sheet_name: str,
+    ) -> str:
+        """Render table data as Markdown with optional sheet header and
+        cell coordinates."""
+        if not table_data or not table_data[0]:
+            return ""
+
+        lines: list[str] = []
+
+        if self.include_sheet_names:
+            lines.append(f"Sheet: {sheet_name}")
+
+        num_cols = len(table_data[0])
+
+        def _fmt(cell: str, row_idx: int, col_idx: int) -> str:
+            escaped = cell.replace("|", "\\|")
+            if self.include_cell_coordinates:
+                coord = f"{_get_excel_column_name(col_idx)}{row_idx + 1}"
+                return f"[{coord}] {escaped}"
+            return escaped
+
+        header = [_fmt(c, 0, ci) for ci, c in enumerate(table_data[0])]
+        lines.append("| " + " | ".join(header) + " |")
+        lines.append("| " + " | ".join(["---"] * num_cols) + " |")
+
+        for ri, row in enumerate(table_data[1:], start=1):
+            padded = list(row) + [""] * max(0, num_cols - len(row))
+            cells = [_fmt(c, ri, ci) for ci, c in enumerate(padded[:num_cols])]
+            lines.append("| " + " | ".join(cells) + " |")
+
+        return "\n".join(lines) + "\n"
+
+    def _table_to_json(
+        self,
+        table_data: list[list[str]],
+        sheet_name: str,
+    ) -> str:
+        """Render table data as JSON with optional sheet header and cell
+        coordinates."""
+        parts: list[str] = []
+
+        if self.include_sheet_names:
+            parts.append(f"Sheet: {sheet_name}")
+
+        parts.append(
+            "<system-info>A table loaded as a JSON array:</system-info>",
+        )
+
+        for ri, row in enumerate(table_data):
+            if self.include_cell_coordinates:
+                row_dict = {
+                    f"{_get_excel_column_name(ci)}{ri + 1}": cell
+                    for ci, cell in enumerate(row)
+                }
+                parts.append(json.dumps(row_dict, ensure_ascii=False))
+            else:
+                parts.append(json.dumps(row, ensure_ascii=False))
+
+        return "\n".join(parts)
diff --git a/src/agentscope/rag/_parser/_image.py b/src/agentscope/rag/_parser/_image.py
new file mode 100644
index 0000000..f64d441
--- /dev/null
+++ b/src/agentscope/rag/_parser/_image.py
@@ -0,0 +1,92 @@
+# -*- coding: utf-8 -*-
+"""Image file parser.
+
+A single :class:`Section` carrying the raw image bytes as a
+base64-encoded :class:`DataBlock`.  No OCR, no captioning — the
+section is the image, ready to flow through to a multimodal
+embedding model unchanged.
+"""
+import base64
+
+from ...message import Base64Source, DataBlock
+from .._document import Section
+from ._base import ParserBase
+from ._utils import _guess_image_media_type
+
+
+class ImageParser(ParserBase):
+    """Parser for image files.
+
+    Wraps the entire file as a single :class:`Section` holding a
+    :class:`DataBlock` with the image's base64-encoded bytes.  This is
+    the input shape a multimodal embedding model expects; the
+    surrounding pipeline (chunker, vector store) treats the section
+    opaquely.
+
+    The IANA media type is sniffed from the bytes' magic number so
+    callers do not need to pass it explicitly.
+    """
+
+    supported_media_types: list[str] = [
+        "image/png",
+        "image/jpeg",
+        "image/gif",
+        "image/bmp",
+        "image/webp",
+    ]
+
+    @classmethod
+    def supported_extensions(cls) -> list[str]:
+        """Return the canonical image extensions."""
+        return [
+            ".bmp",
+            ".gif",
+            ".jpeg",
+            ".jpg",
+            ".png",
+            ".webp",
+        ]
+
+    async def parse(
+        self,
+        file: bytes | str,
+        filename: str,
+    ) -> list[Section]:
+        """Wrap the image bytes in a single :class:`Section`.
+
+        Args:
+            file (`bytes | str`):
+                Either the raw image bytes, or a filesystem path to
+                the image file.
+            filename (`str`):
+                The source filename, copied into
+                :attr:`Section.source`.
+
+        Returns:
+            `list[Section]`:
+                A one-element list whose section's ``content`` is a
+                :class:`DataBlock` with the base64-encoded image data.
+
+        Raises:
+            `FileNotFoundError`: If ``file`` is a ``str`` pointing to
+                a path that does not exist.
+        """
+        if isinstance(file, str):
+            with open(file, "rb") as fp:
+                file = fp.read()
+
+        media_type = _guess_image_media_type(file)
+        data = base64.b64encode(file).decode("utf-8")
+        return [
+            Section(
+                content=DataBlock(
+                    source=Base64Source(
+                        media_type=media_type,
+                        data=data,
+                    ),
+                    name=filename,
+                ),
+                source=filename,
+                metadata={"media_type": media_type},
+            ),
+        ]
diff --git a/src/agentscope/rag/_parser/_pdf.py b/src/agentscope/rag/_parser/_pdf.py
new file mode 100644
index 0000000..0a7d240
--- /dev/null
+++ b/src/agentscope/rag/_parser/_pdf.py
@@ -0,0 +1,92 @@
+# -*- coding: utf-8 -*-
+"""PDF file parser.
+
+One :class:`Section` per page so a downstream
+:class:`~agentscope.rag.ChunkerBase` never combines text across page
+boundaries.  Each section's :attr:`Section.metadata` carries the
+page number (starting at 1) for later citation.
+"""
+import io
+
+from ...message import TextBlock
+from .._document import Section
+from ._base import ParserBase
+
+
+class PDFParser(ParserBase):
+    """Parser for PDF files.
+
+    Returns one :class:`Section` per page.  Empty / image-only pages
+    still produce a Section (with empty text) so the page → section
+    correspondence stays exact — downstream chunkers naturally drop
+    empty content.
+
+    Requires :mod:`pypdf`; install with ``pip install pypdf`` (or via
+    the ``agentscope[rag]`` extra).
+    """
+
+    supported_media_types: list[str] = ["application/pdf"]
+
+    @classmethod
+    def supported_extensions(cls) -> list[str]:
+        """Return the canonical ``.pdf`` extension."""
+        return [".pdf"]
+
+    async def parse(
+        self,
+        file: bytes | str,
+        filename: str,
+    ) -> list[Section]:
+        """Read the PDF bytes and return one Section per page.
+
+        Args:
+            file (`bytes | str`):
+                Either the raw PDF bytes, or a filesystem path to
+                the PDF file.
+            filename (`str`):
+                The source filename, copied verbatim into each
+                Section's :attr:`Section.source` field.
+
+        Returns:
+            `list[Section]`:
+                One Section per page, in document order.  Each
+                section's metadata holds ``{"page": <starting at 1>}``.
+
+        Raises:
+            `FileNotFoundError`: If ``file`` is a ``str`` pointing to
+                a path that does not exist.
+            `ImportError`: If :mod:`pypdf` is not installed.
+            `ValueError`: If the bytes cannot be parsed as PDF.
+        """
+        if isinstance(file, str):
+            with open(file, "rb") as fp:
+                file = fp.read()
+
+        try:
+            from pypdf import PdfReader
+            from pypdf.errors import PdfReadError
+        except ImportError as e:
+            raise ImportError(
+                "Please install pypdf to use the PDF parser. "
+                "You can install it by `pip install pypdf` (or "
+                "`pip install agentscope[rag]`).",
+            ) from e
+
+        try:
+            reader = PdfReader(io.BytesIO(file))
+        except PdfReadError as e:
+            raise ValueError(
+                f"Failed to parse {filename!r} as PDF: {e}",
+            ) from e
+
+        sections: list[Section] = []
+        for page_idx, page in enumerate(reader.pages, start=1):
+            text = page.extract_text() or ""
+            sections.append(
+                Section(
+                    content=TextBlock(text=text),
+                    source=filename,
+                    metadata={"page": page_idx},
+                ),
+            )
+        return sections
diff --git a/src/agentscope/rag/_parser/_ppt.py b/src/agentscope/rag/_parser/_ppt.py
new file mode 100644
index 0000000..52bc2b4
--- /dev/null
+++ b/src/agentscope/rag/_parser/_ppt.py
@@ -0,0 +1,341 @@
+# -*- coding: utf-8 -*-
+"""PowerPoint (.pptx) file parser.
+
+Walks the deck slide-by-slide and emits one :class:`Section` per
+contiguous content block — adjacent text runs (and, by default,
+tables) are merged into a single text section; embedded images are
+emitted as their own :class:`DataBlock` sections.  Each section's
+metadata carries the slide index (starting at 1) for later citation.
+
+Mirrors the knob set of the v1 ``PowerPointReader``:
+``include_image``, ``separate_table``, ``table_format``,
+``slide_prefix``, ``slide_suffix``.  Chunking is **not** done here —
+long text stays intact inside a section and is split downstream by a
+:class:`~agentscope.rag.ChunkerBase`.
+"""
+import base64
+import io
+from typing import Any, Literal
+
+from ..._logging import logger
+from ...message import Base64Source, DataBlock, TextBlock
+from .._document import Section
+from ._base import ParserBase
+from ._utils import (
+    _guess_image_media_type,
+    _table_to_json,
+    _table_to_markdown,
+)
+
+
+def _extract_table_rows(table: Any) -> list[list[str]]:
+    """Read a python-pptx table into a 2-D ``list[list[str]]``.
+
+    Args:
+        table (`Any`):
+            The python-pptx ``Table`` object.
+
+    Returns:
+        `list[list[str]]`:
+            One inner list per row; per-cell line breaks are
+            normalised to ``\\n``.
+    """
+    rows: list[list[str]] = []
+    for row in table.rows:
+        cells: list[str] = []
+        for cell in row.cells:
+            text = cell.text.strip()
+            text = text.replace("\r\n", "\n").replace("\r", "\n")
+            cells.append(text)
+        rows.append(cells)
+    return rows
+
+
+def _extract_image_bytes(shape: Any) -> bytes | None:
+    """Return the embedded image bytes for a picture shape, or ``None``.
+
+    Args:
+        shape (`Any`):
+            A python-pptx shape.  Non-picture shapes return ``None``.
+
+    Returns:
+        `bytes | None`:
+            The raw image bytes, or ``None`` when ``shape`` is not a
+            picture / the bytes are unreadable.
+    """
+    try:
+        from pptx.enum.shapes import MSO_SHAPE_TYPE
+
+        picture_type = MSO_SHAPE_TYPE.PICTURE
+    except ImportError:
+        # MSO_SHAPE_TYPE.PICTURE numeric value used as the fallback
+        # so the parser still works against pptx builds where the
+        # enum import path has moved.
+        picture_type = 13
+
+    if shape.shape_type != picture_type:
+        return None
+    try:
+        return shape.image.blob
+    except Exception as e:  # pylint: disable=broad-except
+        logger.warning("Failed to extract image from PPT shape: %s", e)
+        return None
+
+
+class PPTParser(ParserBase):
+    """Parser for PowerPoint ``.pptx`` files.
+
+    Slide order is preserved.  Within a slide, shapes are visited in
+    document order and grouped into a minimum number of sections:
+
+    - **Text** shapes and **table** shapes contribute to one running
+      text section.  When ``separate_table=True`` a table closes the
+      running section and starts a new one of its own.
+    - **Picture** shapes emit a standalone :class:`Section` whose
+      ``content`` is a :class:`DataBlock` holding the base64-encoded
+      image bytes.
+
+    ``slide_prefix`` / ``slide_suffix`` are wrapped around each
+    slide's text content (the prefix is prepended to the slide's
+    first text section, the suffix is appended to its last text
+    section).  Use ``None`` on either to disable wrapping.
+    """
+
+    supported_media_types: list[str] = [
+        "application/vnd.openxmlformats-officedocument.presentationml"
+        ".presentation",
+    ]
+
+    @classmethod
+    def supported_extensions(cls) -> list[str]:
+        """Return ``[".pptx"]`` — the only format ``python-pptx``
+        reads."""
+        return [".pptx"]
+
+    def __init__(
+        self,
+        include_image: bool = True,
+        separate_table: bool = False,
+        table_format: Literal["markdown", "json"] = "markdown",
+        slide_prefix: str | None = "<slide index={index}>",
+        slide_suffix: str | None = "</slide>",
+    ) -> None:
+        """Initialize the PowerPoint parser.
+
+        Args:
+            include_image (`bool`, defaults to ``True``):
+                When ``True``, picture shapes are emitted as
+                :class:`DataBlock` sections.  Set to ``False`` to keep
+                a text-only index.
+            separate_table (`bool`, defaults to ``False``):
+                When ``True``, each table becomes its own text
+                section, never merged with surrounding text.
+            table_format (`Literal["markdown", "json"]`, defaults to
+                ``"markdown"``):
+                How to render tables.  ``"markdown"`` uses pipe-table
+                syntax; ``"json"`` emits a JSON array prefixed with a
+                ``<system-info>`` marker — choose JSON when cells
+                contain newlines that would corrupt Markdown layout.
+            slide_prefix (`str | None`, defaults to
+                ``"<slide index={index}>"``):
+                Prepended to the first text section of each slide.
+                Supports the ``{index}`` placeholder (starting at 1).  Use
+                ``None`` to disable.
+            slide_suffix (`str | None`, defaults to ``"</slide>"``):
+                Appended to the last text section of each slide.  Use
+                ``None`` to disable.
+
+        Raises:
+            `ValueError`: If ``table_format`` is not one of
+                ``"markdown"`` / ``"json"``.
+        """
+        if table_format not in ("markdown", "json"):
+            raise ValueError(
+                "The table_format must be one of 'markdown' or 'json', "
+                f"got {table_format!r}.",
+            )
+        self.include_image = include_image
+        self.separate_table = separate_table
+        self.table_format = table_format
+        self.slide_prefix = slide_prefix
+        self.slide_suffix = slide_suffix
+
+    async def parse(
+        self,
+        file: bytes | str,
+        filename: str,
+    ) -> list[Section]:
+        """Parse a PPTX file into a list of :class:`Section` objects.
+
+        Args:
+            file (`bytes | str`):
+                Either the raw PPTX bytes, or a filesystem path to
+                the PPTX file.
+            filename (`str`):
+                The source filename, copied into each Section's
+                :attr:`Section.source`.
+
+        Returns:
+            `list[Section]`:
+                Sections in deck order.  Text sections carry
+                ``{"slide": <starting at 1>}``; image sections add
+                ``{"media_type": "image/..."}``.
+
+        Raises:
+            `FileNotFoundError`: If ``file`` is a ``str`` pointing to
+                a path that does not exist.
+            `ImportError`: If :mod:`python-pptx` is not installed.
+            `ValueError`: If the bytes cannot be parsed.
+        """
+        if isinstance(file, str):
+            with open(file, "rb") as fp:
+                file = fp.read()
+
+        try:
+            from pptx import Presentation
+        except ImportError as e:
+            raise ImportError(
+                "Please install python-pptx to use the PowerPoint "
+                "parser. You can install it by "
+                "`pip install python-pptx` (or "
+                "`pip install agentscope[rag]`).",
+            ) from e
+
+        try:
+            prs = Presentation(io.BytesIO(file))
+        except Exception as e:  # pylint: disable=broad-except
+            raise ValueError(
+                f"Failed to parse {filename!r} as PPTX: {e}",
+            ) from e
+
+        sections: list[Section] = []
+        for slide_idx, slide in enumerate(prs.slides):
+            sections.extend(
+                self._parse_slide(slide, slide_idx, filename),
+            )
+        return sections
+
+    # ------------------------------------------------------------------
+    # Slide-level parsing
+    # ------------------------------------------------------------------
+
+    def _parse_slide(
+        self,
+        slide: Any,
+        slide_idx: int,
+        filename: str,
+    ) -> list[Section]:
+        """Walk one slide and return its ordered sections."""
+        slide_no = slide_idx + 1
+        prefix = (
+            self.slide_prefix.format(index=slide_no)
+            if self.slide_prefix is not None
+            else ""
+        )
+
+        slide_sections: list[Section] = []
+        # ``text_buffer`` accumulates the running text section; it is
+        # flushed whenever an image arrives, the slide ends, or
+        # ``separate_table`` forces a break around a table shape.
+        text_buffer: list[str] = []
+
+        def flush_text() -> None:
+            if not text_buffer:
+                return
+            slide_sections.append(
+                Section(
+                    content=TextBlock(text="\n".join(text_buffer)),
+                    source=filename,
+                    metadata={"slide": slide_no},
+                ),
+            )
+            text_buffer.clear()
+
+        # Slide prefix lives at the very top of the first text section.
+        if prefix:
+            text_buffer.append(prefix)
+
+        for shape in slide.shapes:
+            # 1. Pictures — flush running text, emit a DataBlock section.
+            if self.include_image:
+                image_bytes = _extract_image_bytes(shape)
+                if image_bytes is not None:
+                    flush_text()
+                    media_type = _guess_image_media_type(image_bytes)
+                    data = base64.b64encode(image_bytes).decode("utf-8")
+                    slide_sections.append(
+                        Section(
+                            content=DataBlock(
+                                source=Base64Source(
+                                    media_type=media_type,
+                                    data=data,
+                                ),
+                                name=filename,
+                            ),
+                            source=filename,
+                            metadata={
+                                "slide": slide_no,
+                                "media_type": media_type,
+                            },
+                        ),
+                    )
+                    continue
+
+            # 2. Tables — render to text; optionally flush around them.
+            if getattr(shape, "has_table", False):
+                try:
+                    rows = _extract_table_rows(shape.table)
+                except Exception as e:  # pylint: disable=broad-except
+                    logger.warning(
+                        "Failed to extract table from slide %d: %s",
+                        slide_no,
+                        e,
+                    )
+                    continue
+                rendered = (
+                    _table_to_markdown(rows)
+                    if self.table_format == "markdown"
+                    else _table_to_json(rows)
+                )
+                if not rendered:
+                    continue
+                if self.separate_table:
+                    flush_text()
+                    slide_sections.append(
+                        Section(
+                            content=TextBlock(text=rendered),
+                            source=filename,
+                            metadata={"slide": slide_no},
+                        ),
+                    )
+                else:
+                    text_buffer.append(rendered)
+                continue
+
+            # 3. Text frames.
+            if getattr(shape, "has_text_frame", False):
+                try:
+                    parts = [
+                        para.text.strip()
+                        for para in shape.text_frame.paragraphs
+                        if para.text.strip()
+                    ]
+                except Exception as e:  # pylint: disable=broad-except
+                    logger.warning(
+                        "Failed to extract text from shape in slide %d: %s",
+                        slide_no,
+                        e,
+                    )
+                    continue
+                if parts:
+                    text_buffer.append("\n".join(parts))
+
+        # Suffix goes onto the last text section of this slide.  If the
+        # slide ends on an image (text_buffer empty, no prior text
+        # section in this slide), create a small text-only carrier so
+        # the suffix is preserved.
+        if self.slide_suffix is not None:
+            text_buffer.append(self.slide_suffix)
+
+        flush_text()
+        return slide_sections
diff --git a/src/agentscope/rag/_parser/_text.py b/src/agentscope/rag/_parser/_text.py
new file mode 100644
index 0000000..6fd4116
--- /dev/null
+++ b/src/agentscope/rag/_parser/_text.py
@@ -0,0 +1,125 @@
+# -*- coding: utf-8 -*-
+"""Plain-text file parser."""
+import os
+
+from ...message import TextBlock
+from .._document import Section
+from ._base import ParserBase
+
+
+class TextParser(ParserBase):
+    """Parser for plain-text file formats.
+
+    Reads the entire file as UTF-8 text and returns a single
+    :class:`Section`.  No internal boundaries are inferred — the file
+    is treated as one unstructured blob, leaving all splitting to a
+    downstream :class:`~agentscope.rag.ChunkerBase`.
+
+    Supports a fixed set of standard text-based IANA media types
+    (``text/plain``, ``text/markdown``, ``text/csv``, …).  Use
+    ``TextParser.supported_media_types`` to enumerate them.
+    """
+
+    supported_media_types: list[str] = [
+        "text/plain",
+        "text/markdown",
+        "text/csv",
+        "text/html",
+        "text/x-rst",
+        "application/json",
+        "application/xml",
+        "application/x-yaml",
+    ]
+    """Standard IANA media types this parser handles."""
+
+    @classmethod
+    def supported_extensions(cls) -> list[str]:
+        """Return the human-friendly text extensions.
+
+        Override the base reverse-lookup because
+        :func:`mimetypes.guess_all_extensions` returns a long tail of
+        developer-tool extensions for ``text/plain`` (``.bat`` /
+        ``.c`` / ``.pl`` / ``.ksh`` / …) that have no place in a KB
+        file picker, and returns the empty list for
+        ``application/x-yaml``.
+        """
+        return [
+            ".csv",
+            ".htm",
+            ".html",
+            ".json",
+            ".markdown",
+            ".md",
+            ".rst",
+            ".txt",
+            ".xml",
+            ".yaml",
+            ".yml",
+        ]
+
+    def __init__(self, encoding: str = "utf-8") -> None:
+        """Initialize the text parser.
+
+        Args:
+            encoding (`str`, defaults to ``"utf-8"``):
+                The text encoding used to decode the file bytes.
+        """
+        self.encoding = encoding
+
+    async def parse(
+        self,
+        file: bytes | str,
+        filename: str,
+    ) -> list[Section]:
+        """Read the file as text and return a single :class:`Section`.
+
+        Args:
+            file (`bytes | str`):
+                The file content.  ``bytes`` is decoded with the
+                configured encoding.  ``str`` is disambiguated at
+                runtime: if it names an existing file on disk the
+                file is read and decoded; otherwise it is used
+                verbatim as pre-decoded text — letting local-mode
+                callers skip the encode → decode round trip.
+            filename (`str`):
+                The source filename, copied verbatim into
+                :attr:`Section.source`.
+
+        Returns:
+            `list[Section]`:
+                Always a one-element list containing the entire file
+                contents.
+
+        Raises:
+            `ValueError`: If the bytes cannot be decoded with the
+                configured encoding.
+        """
+        if isinstance(file, str):
+            if os.path.isfile(file):
+                with open(file, "rb") as fp:
+                    raw = fp.read()
+                try:
+                    text = raw.decode(self.encoding)
+                except UnicodeDecodeError as e:
+                    raise ValueError(
+                        f"Failed to decode {filename!r} as "
+                        f"{self.encoding!r}: {e}",
+                    ) from e
+            else:
+                text = file
+        else:
+            try:
+                text = file.decode(self.encoding)
+            except UnicodeDecodeError as e:
+                raise ValueError(
+                    f"Failed to decode {filename!r} as "
+                    f"{self.encoding!r}: {e}",
+                ) from e
+
+        return [
+            Section(
+                content=TextBlock(text=text),
+                source=filename,
+                metadata={},
+            ),
+        ]
diff --git a/src/agentscope/rag/_parser/_utils.py b/src/agentscope/rag/_parser/_utils.py
new file mode 100644
index 0000000..bff8f45
--- /dev/null
+++ b/src/agentscope/rag/_parser/_utils.py
@@ -0,0 +1,99 @@
+# -*- coding: utf-8 -*-
+"""Shared helpers for binary parsers.
+
+Three small utilities used by :class:`PDFParser`, :class:`ImageParser`,
+and :class:`PPTParser`:
+
+- :func:`_guess_image_media_type` — sniff the IANA media type from raw
+  image bytes by looking at the magic number.  Used to populate the
+  ``media_type`` field of :class:`Base64Source` for embedded images.
+- :func:`_table_to_markdown` — render a 2-D ``list[list[str]]`` as a
+  Markdown pipe-table; the default rendering for table content.
+- :func:`_table_to_json` — render the same shape as a JSON array
+  prefixed with a one-line ``<system-info>`` marker; used when the
+  caller picks ``table_format="json"`` to avoid Markdown's
+  multi-line-cell ambiguity.
+"""
+import json
+
+
+def _guess_image_media_type(data: bytes) -> str:
+    """Sniff the IANA media type of an image from its magic number.
+
+    Args:
+        data (`bytes`):
+            The raw image bytes.
+
+    Returns:
+        `str`:
+            The IANA media type (e.g. ``"image/png"``).  Falls back to
+            ``"image/jpeg"`` when no signature matches — JPEG is the
+            most permissive default and matches what every consumer can
+            decode.
+    """
+    signatures = {
+        b"\x89PNG\r\n\x1a\n": "image/png",
+        b"\xff\xd8": "image/jpeg",
+        b"GIF87a": "image/gif",
+        b"GIF89a": "image/gif",
+        b"BM": "image/bmp",
+    }
+    for signature, media_type in signatures.items():
+        if data.startswith(signature):
+            return media_type
+    # WebP: ``RIFF`` at offset 0 + ``WEBP`` at offset 8.
+    if len(data) > 12 and data[:4] == b"RIFF" and data[8:12] == b"WEBP":
+        return "image/webp"
+    return "image/jpeg"
+
+
+def _table_to_markdown(table_data: list[list[str]]) -> str:
+    """Render a 2-D table as a Markdown pipe-table.
+
+    Args:
+        table_data (`list[list[str]]`):
+            The table data; ``table_data[0]`` is the header row.
+
+    Returns:
+        `str`:
+            The Markdown rendering, or the empty string when
+            ``table_data`` is empty / column-less.
+    """
+    if not table_data:
+        return ""
+
+    num_cols = len(table_data[0])
+    if num_cols == 0:
+        return ""
+
+    lines = [
+        "| " + " | ".join(table_data[0]) + " |",
+        "| " + " | ".join(["---"] * num_cols) + " |",
+    ]
+    for row in table_data[1:]:
+        # Pad short rows so column counts match the header.
+        padded = list(row) + [""] * max(0, num_cols - len(row))
+        lines.append("| " + " | ".join(padded[:num_cols]) + " |")
+    return "\n".join(lines) + "\n"
+
+
+def _table_to_json(table_data: list[list[str]]) -> str:
+    """Render a 2-D table as JSON prefixed by a one-line marker.
+
+    The ``<system-info>`` marker lets the LLM (and any
+    structure-aware downstream renderer) tell at a glance that this
+    block is tabular data, not free text — which is otherwise
+    indistinguishable from a raw JSON dump in the middle of a chunk.
+
+    Args:
+        table_data (`list[list[str]]`):
+            The table data.
+
+    Returns:
+        `str`:
+            ``"<system-info>...</system-info>\\n<json>"``.
+    """
+    return (
+        "<system-info>A table loaded as a JSON array:</system-info>\n"
+        + json.dumps(table_data, ensure_ascii=False)
+    )
diff --git a/src/agentscope/rag/_parser/_word.py b/src/agentscope/rag/_parser/_word.py
new file mode 100644
index 0000000..c230caf
--- /dev/null
+++ b/src/agentscope/rag/_parser/_word.py
@@ -0,0 +1,341 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Word (.docx) file parser.
+
+Walks the document element-by-element and emits one :class:`Section`
+per contiguous content block — adjacent paragraphs (and, by default,
+tables) are merged into a single text section; embedded images are
+emitted as their own :class:`DataBlock` sections.
+
+Supported options: ``include_image``, ``separate_table``,
+``table_format``.  Chunking is **not** done here — long text stays
+intact inside a section and is split downstream by a
+:class:`~agentscope.rag.ChunkerBase`.
+"""
+from __future__ import annotations
+
+import base64
+import io
+from typing import Literal, TYPE_CHECKING
+
+from ..._logging import logger
+from ...message import Base64Source, DataBlock, TextBlock
+from .._document import Section
+from ._base import ParserBase
+from ._utils import (
+    _guess_image_media_type,
+    _table_to_json,
+    _table_to_markdown,
+)
+
+if TYPE_CHECKING:
+    from docx.table import Table as DocxTable
+    from docx.text.paragraph import Paragraph as DocxParagraph
+
+_VML_NS = "{urn:schemas-microsoft-com:vml}"
+
+
+def _extract_text_from_paragraph(para: DocxParagraph) -> str:
+    """Extract text from a paragraph, including text in text boxes and
+    VML shapes.
+
+    Tries three methods in order:
+    1. All ``w:t`` elements in the paragraph XML (covers revisions,
+       hyperlinks, etc.).
+    2. The standard ``para.text`` property.
+    3. Text inside ``w:txbxContent`` and VML ``v:textbox`` elements.
+    """
+    from docx.oxml.ns import qn
+
+    text = ""
+    for t_elem in para._element.findall(".//" + qn("w:t")):
+        if t_elem.text:
+            text += t_elem.text
+
+    if not text:
+        text = para.text.strip()
+
+    if not text:
+        for txbx in para._element.findall(".//" + qn("w:txbxContent")):
+            for p_elem in txbx.findall(".//" + qn("w:p")):
+                for t_elem in p_elem.findall(".//" + qn("w:t")):
+                    if t_elem.text:
+                        text += t_elem.text
+
+        for vml_tb in para._element.findall(".//" + _VML_NS + "textbox"):
+            for p_elem in vml_tb.findall(".//" + qn("w:p")):
+                for t_elem in p_elem.findall(".//" + qn("w:t")):
+                    if t_elem.text:
+                        text += t_elem.text
+
+    return text.strip()
+
+
+def _extract_table_data(table: DocxTable) -> list[list[str]]:
+    """Extract table data from a python-docx Table, preserving line breaks
+    within cells.
+
+    Horizontal merges (``w:gridSpan``) are expanded with empty strings so
+    that every row has the same number of columns.  Vertically merged
+    continuation cells (``w:vMerge`` without ``val="restart"``) are kept
+    as-is — their XML content is typically empty, which is the desired
+    behaviour for downstream renderers.
+    """
+    from docx.oxml.ns import qn
+
+    table_data: list[list[str]] = []
+    for tr in table._element.findall(qn("w:tr")):
+        row_data: list[str] = []
+        for tc in tr.findall(qn("w:tc")):
+            paragraphs: list[str] = []
+            for p_elem in tc.findall(qn("w:p")):
+                texts: list[str] = []
+                for t_elem in p_elem.findall(".//" + qn("w:t")):
+                    if t_elem.text:
+                        texts.append(t_elem.text)
+                para_text = "".join(texts)
+                if para_text:
+                    paragraphs.append(para_text)
+            row_data.append("\n".join(paragraphs))
+
+            tc_pr = tc.find(qn("w:tcPr"))
+            if tc_pr is not None:
+                gs = tc_pr.find(qn("w:gridSpan"))
+                if gs is not None:
+                    span = int(
+                        gs.get(qn("w:val"), gs.get("val", "1")),
+                    )
+                    row_data.extend([""] * (span - 1))
+
+        table_data.append(row_data)
+    return table_data
+
+
+def _extract_image_blocks(
+    para: DocxParagraph,
+    filename: str,
+) -> list[DataBlock]:
+    """Extract image blocks from a paragraph (both modern ``w:drawing``
+    and legacy ``w:pict`` / VML formats)."""
+    from docx.oxml.ns import qn
+
+    blocks: list[DataBlock] = []
+
+    for drawing in para._element.findall(".//" + qn("w:drawing")):
+        for blip in drawing.findall(".//" + qn("a:blip")):
+            embed = blip.get(qn("r:embed"))
+            if not embed:
+                continue
+            try:
+                part = para.part.related_parts[embed]
+                media_type = part.content_type or _guess_image_media_type(
+                    part.blob,
+                )
+                blocks.append(
+                    DataBlock(
+                        source=Base64Source(
+                            media_type=media_type,
+                            data=base64.b64encode(part.blob).decode("utf-8"),
+                        ),
+                        name=filename,
+                    ),
+                )
+            except Exception as e:
+                logger.warning("Failed to extract image: %s", e)
+
+    for pict in para._element.findall(".//" + qn("w:pict")):
+        for imagedata in pict.findall(".//" + _VML_NS + "imagedata"):
+            rel_id = imagedata.get(qn("r:id"))
+            if not rel_id:
+                continue
+            try:
+                part = para.part.related_parts[rel_id]
+                media_type = part.content_type or _guess_image_media_type(
+                    part.blob,
+                )
+                blocks.append(
+                    DataBlock(
+                        source=Base64Source(
+                            media_type=media_type,
+                            data=base64.b64encode(part.blob).decode("utf-8"),
+                        ),
+                        name=filename,
+                    ),
+                )
+            except Exception as e:
+                logger.warning("Failed to extract VML image: %s", e)
+
+    return blocks
+
+
+class WordParser(ParserBase):
+    """Parser for Word ``.docx`` files.
+
+    Document order is preserved.  Elements are visited sequentially and
+    grouped into a minimum number of sections:
+
+    - **Paragraphs** contribute to one running text section.
+    - **Tables** are rendered as Markdown or JSON and, depending on
+      ``separate_table``, either merged into the running text or emitted
+      as standalone text sections.
+    - **Images** emit standalone :class:`Section` instances holding a
+      :class:`DataBlock` with the base64-encoded image bytes.
+    """
+
+    supported_media_types: list[str] = [
+        "application/vnd.openxmlformats-officedocument.wordprocessingml"
+        ".document",
+    ]
+
+    @classmethod
+    def supported_extensions(cls) -> list[str]:
+        """Return ``[".docx"]`` — the only format ``python-docx`` reads."""
+        return [".docx"]
+
+    def __init__(
+        self,
+        include_image: bool = True,
+        separate_table: bool = False,
+        table_format: Literal["markdown", "json"] = "markdown",
+    ) -> None:
+        """Initialize the Word parser.
+
+        Args:
+            include_image (`bool`, defaults to ``True``):
+                When ``True``, embedded images are emitted as
+                :class:`DataBlock` sections.  Set to ``False`` to keep
+                a text-only index.
+            separate_table (`bool`, defaults to ``False``):
+                When ``True``, each table becomes its own text section,
+                never merged with surrounding paragraphs.
+            table_format (`Literal["markdown", "json"]`, defaults to
+                ``"markdown"``):
+                How to render tables.  ``"markdown"`` uses pipe-table
+                syntax; ``"json"`` emits a JSON array prefixed with a
+                ``<system-info>`` marker.
+
+        Raises:
+            `ValueError`: If ``table_format`` is not one of
+                ``"markdown"`` / ``"json"``.
+        """
+        if table_format not in ("markdown", "json"):
+            raise ValueError(
+                "The table_format must be one of 'markdown' or 'json', "
+                f"got {table_format!r}.",
+            )
+        self.include_image = include_image
+        self.separate_table = separate_table
+        self.table_format = table_format
+
+    async def parse(
+        self,
+        file: bytes | str,
+        filename: str,
+    ) -> list[Section]:
+        """Parse a DOCX file into a list of :class:`Section` objects.
+
+        Args:
+            file (`bytes | str`):
+                Either the raw DOCX bytes, or a filesystem path to the
+                DOCX file.
+            filename (`str`):
+                The source filename, copied into each Section's
+                :attr:`Section.source`.
+
+        Returns:
+            `list[Section]`:
+                Sections in document order.
+
+        Raises:
+            `FileNotFoundError`: If ``file`` is a ``str`` pointing to
+                a path that does not exist.
+            `ImportError`: If :mod:`python-docx` is not installed.
+            `ValueError`: If the bytes cannot be parsed.
+        """
+        try:
+            from docx import Document as DocxDocument
+            from docx.oxml import CT_P, CT_Tbl
+            from docx.text.paragraph import Paragraph
+            from docx.table import Table
+            from docx.oxml.ns import qn
+        except ImportError as e:
+            raise ImportError(
+                "Please install python-docx to use the Word parser. "
+                "You can install it by `pip install python-docx` (or "
+                "`pip install agentscope[rag]`).",
+            ) from e
+
+        if isinstance(file, str):
+            doc = DocxDocument(file)
+        else:
+            doc = DocxDocument(io.BytesIO(file))
+
+        sections: list[Section] = []
+        text_buffer: list[str] = []
+
+        def flush_text() -> None:
+            if not text_buffer:
+                return
+            sections.append(
+                Section(
+                    content=TextBlock(text="\n".join(text_buffer)),
+                    source=filename,
+                    metadata={},
+                ),
+            )
+            text_buffer.clear()
+
+        for element in doc.element.body:
+            if isinstance(element, CT_P):
+                para = Paragraph(element, doc)
+
+                text = _extract_text_from_paragraph(para)
+                if text:
+                    text_buffer.append(text)
+
+                if self.include_image:
+                    has_drawing = bool(
+                        para._element.findall(".//" + qn("w:drawing")),
+                    )
+                    has_pict = bool(
+                        para._element.findall(".//" + qn("w:pict")),
+                    )
+                    if has_drawing or has_pict:
+                        flush_text()
+                        for block in _extract_image_blocks(para, filename):
+                            sections.append(
+                                Section(
+                                    content=block,
+                                    source=filename,
+                                    metadata={
+                                        "media_type": (
+                                            block.source.media_type
+                                        ),
+                                    },
+                                ),
+                            )
+
+            elif isinstance(element, CT_Tbl):
+                table_data = _extract_table_data(Table(element, doc))
+                rendered = (
+                    _table_to_markdown(table_data)
+                    if self.table_format == "markdown"
+                    else _table_to_json(table_data)
+                )
+                if not rendered:
+                    continue
+
+                if self.separate_table:
+                    flush_text()
+                    sections.append(
+                        Section(
+                            content=TextBlock(text=rendered),
+                            source=filename,
+                            metadata={},
+                        ),
+                    )
+                else:
+                    text_buffer.append(rendered)
+
+        flush_text()
+        return sections
diff --git a/src/agentscope/rag/_vdb/__init__.py b/src/agentscope/rag/_vdb/__init__.py
new file mode 100644
index 0000000..68c7120
--- /dev/null
+++ b/src/agentscope/rag/_vdb/__init__.py
@@ -0,0 +1,22 @@
+# -*- coding: utf-8 -*-
+"""The vector store classes in AgentScope."""
+
+from ._vector_store import (
+    DocumentSummary,
+    VectorRecord,
+    VectorSearchResult,
+    VectorStoreBase,
+)
+from ._qdrant import QdrantStore
+from ._mongodb import MongoDBStore
+from ._milvus_lite import MilvusLiteStore
+
+__all__ = [
+    "DocumentSummary",
+    "MilvusLiteStore",
+    "VectorStoreBase",
+    "VectorRecord",
+    "VectorSearchResult",
+    "QdrantStore",
+    "MongoDBStore",
+]
diff --git a/src/agentscope/rag/_vdb/_milvus_lite.py b/src/agentscope/rag/_vdb/_milvus_lite.py
new file mode 100644
index 0000000..de94c9e
--- /dev/null
+++ b/src/agentscope/rag/_vdb/_milvus_lite.py
@@ -0,0 +1,453 @@
+# -*- coding: utf-8 -*-
+"""Milvus Lite implementation of the vector store backend.
+
+Built on the official ``pymilvus`` ``MilvusClient`` API. Milvus Lite is
+started automatically when the URI points to a local ``.db`` file, so it
+is convenient for local development, tests, and small RAG workloads.
+"""
+import asyncio
+import json
+import os
+import uuid
+from typing import TYPE_CHECKING, Any, Literal
+
+from ._vector_store import (
+    DocumentSummary,
+    VectorRecord,
+    VectorSearchResult,
+    VectorStoreBase,
+)
+from .._document import Chunk
+
+if TYPE_CHECKING:
+    from pymilvus import MilvusClient
+
+
+class MilvusLiteStore(VectorStoreBase):
+    """Vector store backend backed by Milvus Lite.
+
+    Each knowledge base maps to one Milvus collection. Every entity
+    stores the owning ``document_id``, the serialized
+    :class:`~agentscope.rag.Chunk`, and the chunk metadata in a JSON
+    field used for flat equality filtering.
+
+    .. note:: Install optional dependencies with
+        ``pip install agentscope[milvuslite]``.
+
+    .. code-block:: python
+
+        store = MilvusLiteStore(uri="./rag_demo.db")
+
+        async with store:
+            await store.create_collection("kb_1", dimensions=768)
+    """
+
+    def __init__(
+        self,
+        uri: str = "./agentscope_milvus_lite.db",
+        metric_type: Literal["COSINE", "IP", "L2"] = "COSINE",
+        index_type: str = "AUTOINDEX",
+        client_kwargs: dict[str, Any] | None = None,
+        batch_size: int = 256,
+    ) -> None:
+        """Initialize the Milvus Lite vector store.
+
+        Args:
+            uri (`str`, defaults to ``"./agentscope_milvus_lite.db"``):
+                Local ``.db`` path for Milvus Lite, or a Milvus-compatible
+                endpoint URI.
+            metric_type (`Literal["COSINE", "IP", "L2"]`, defaults to \
+             ``"COSINE"``):
+                The metric used for the vector index and search.
+            index_type (`str`, defaults to ``"AUTOINDEX"``):
+                The Milvus index type used for newly created collections.
+            client_kwargs (`dict[str, Any] | None`, optional):
+                Extra keyword arguments forwarded to
+                :class:`pymilvus.MilvusClient`.
+            batch_size (`int`, defaults to ``256``):
+                Batch size used by inserts and document listing.
+        """
+        self._uri = uri
+        self._metric_type = metric_type
+        self._index_type = index_type
+        self._client_kwargs = client_kwargs or {}
+        self._batch_size = batch_size
+        self._client: "MilvusClient | None" = None
+        self._is_lite_uri = self._is_local_db_uri(uri)
+
+    def get_client(self) -> "MilvusClient":
+        """Lazily create and cache the Milvus client."""
+        if self._client is None:
+            from pymilvus import MilvusClient
+
+            self._client = MilvusClient(uri=self._uri, **self._client_kwargs)
+        return self._client
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: Any,
+    ) -> None:
+        """Exit the async context and close the underlying client."""
+        if self._client is None:
+            return
+
+        client = self._client
+        self._client = None
+        close = getattr(client, "close", None)
+        if close is not None:
+            await asyncio.to_thread(close)
+        if self._is_lite_uri:
+            await asyncio.to_thread(self._release_lite_server)
+
+    # ------------------------------------------------------------------
+    # Collection management
+    # ------------------------------------------------------------------
+
+    async def create_collection(
+        self,
+        name: str,
+        dimensions: int,
+    ) -> None:
+        """Create a new Milvus collection.
+
+        No-op if the collection already exists.
+
+        Args:
+            name (`str`):
+                The collection name. Typically, the knowledge base ID.
+            dimensions (`int`):
+                The fixed vector dimensionality for this collection.
+                All vectors inserted later must have this many elements.
+        """
+        client = self.get_client()
+
+        def _create() -> None:
+            from pymilvus import DataType
+
+            if client.has_collection(collection_name=name):
+                client.load_collection(collection_name=name)
+                return
+
+            schema = client.create_schema(
+                auto_id=False,
+                enable_dynamic_field=False,
+            )
+            schema.add_field(
+                field_name="id",
+                datatype=DataType.VARCHAR,
+                is_primary=True,
+                max_length=64,
+            )
+            schema.add_field(
+                field_name="vector",
+                datatype=DataType.FLOAT_VECTOR,
+                dim=dimensions,
+            )
+            schema.add_field(
+                field_name="document_id",
+                datatype=DataType.VARCHAR,
+                max_length=512,
+            )
+            schema.add_field(
+                field_name="chunk",
+                datatype=DataType.JSON,
+            )
+            schema.add_field(
+                field_name="metadata",
+                datatype=DataType.JSON,
+            )
+
+            index_params = client.prepare_index_params()
+            index_params.add_index(
+                field_name="vector",
+                index_type=self._index_type,
+                metric_type=self._metric_type,
+            )
+            client.create_collection(
+                collection_name=name,
+                schema=schema,
+                index_params=index_params,
+            )
+            client.load_collection(collection_name=name)
+
+        await asyncio.to_thread(_create)
+
+    async def delete_collection(self, name: str) -> None:
+        """Delete a collection and all its data."""
+        await asyncio.to_thread(
+            self.get_client().drop_collection,
+            collection_name=name,
+        )
+
+    async def has_collection(self, name: str) -> bool:
+        """Check whether a collection exists."""
+        return await asyncio.to_thread(
+            self.get_client().has_collection,
+            collection_name=name,
+        )
+
+    # ------------------------------------------------------------------
+    # Data operations
+    # ------------------------------------------------------------------
+
+    async def insert(
+        self,
+        collection: str,
+        records: list[VectorRecord],
+    ) -> None:
+        """Insert records into a collection.
+
+        Each entity stores the :attr:`VectorRecord.document_id`, the
+        serialized :class:`Chunk`, and a copy of ``chunk.metadata`` in a
+        JSON field used by :meth:`search` and :meth:`list_documents` for
+        flat equality filtering.
+
+        Args:
+            collection (`str`):
+                The target collection name.
+            records (`list[VectorRecord]`):
+                The records to insert, each carrying a
+                :class:`Chunk` and its embedding vector.
+        """
+        if not records:
+            return
+
+        for start in range(0, len(records), self._batch_size):
+            batch = records[start : start + self._batch_size]
+            await asyncio.to_thread(
+                self.get_client().insert,
+                collection_name=collection,
+                data=[
+                    {
+                        "id": str(uuid.uuid4()),
+                        "vector": record.vector,
+                        "document_id": record.document_id,
+                        "chunk": record.chunk.model_dump(mode="json"),
+                        "metadata": record.chunk.metadata,
+                    }
+                    for record in batch
+                ],
+            )
+
+    async def delete(
+        self,
+        collection: str,
+        document_id: str,
+    ) -> None:
+        """Delete all records belonging to one source document."""
+        await asyncio.to_thread(
+            self.get_client().delete,
+            collection_name=collection,
+            filter=self._build_document_filter(document_id),
+        )
+
+    # ------------------------------------------------------------------
+    # Search
+    # ------------------------------------------------------------------
+
+    async def search(
+        self,
+        collection: str,
+        query_vector: list[float],
+        top_k: int = 5,
+        metadata_filter: dict[str, Any] | None = None,
+    ) -> list[VectorSearchResult]:
+        """Find the most similar records to a query vector.
+
+        Args:
+            collection (`str`):
+                The collection to search.
+            query_vector (`list[float]`):
+                The query embedding vector.
+            top_k (`int`, defaults to ``5``):
+                Maximum number of results to return.
+            metadata_filter (`dict[str, Any] | None`, optional):
+                If provided, restrict the search to records whose
+                ``chunk.metadata`` matches every ``key == value`` pair
+                in this dict. Milvus Lite stores this metadata in a JSON
+                field and supports flat scalar equality filters.
+
+        Returns:
+            `list[VectorSearchResult]`:
+                Results ordered by descending similarity score for
+                cosine / inner product metrics, or ascending distance
+                semantics for L2 as exposed by Milvus.
+        """
+        response = await asyncio.to_thread(
+            self.get_client().search,
+            collection_name=collection,
+            data=[query_vector],
+            anns_field="vector",
+            limit=top_k,
+            filter=self._build_metadata_filter(metadata_filter),
+            output_fields=["document_id", "chunk"],
+            search_params={"metric_type": self._metric_type},
+        )
+
+        hits = response[0] if response else []
+        return [
+            VectorSearchResult(
+                score=self._extract_score(hit, self._metric_type),
+                document_id=hit["entity"]["document_id"],
+                chunk=Chunk.model_validate(hit["entity"]["chunk"]),
+            )
+            for hit in hits
+        ]
+
+    # ------------------------------------------------------------------
+    # Document listing
+    # ------------------------------------------------------------------
+
+    async def list_documents(
+        self,
+        collection: str,
+        metadata_filter: dict[str, Any] | None = None,
+    ) -> list[DocumentSummary]:
+        """List all distinct source documents indexed in a collection.
+
+        Scans stored entities and aggregates them by ``document_id``.
+        The first chunk encountered for each document supplies the
+        source filename and document-level metadata.
+
+        Args:
+            collection (`str`):
+                The target collection name.
+            metadata_filter (`dict[str, Any] | None`, optional):
+                If provided, restrict aggregation to records whose
+                ``chunk.metadata`` matches every ``key == value`` pair
+                in this dict.
+
+        Returns:
+            `list[DocumentSummary]`:
+                One summary per distinct ``document_id``.
+        """
+        client = self.get_client()
+        rows = await asyncio.to_thread(
+            self._query_all_rows,
+            client,
+            collection,
+            metadata_filter,
+        )
+        summaries: dict[str, DocumentSummary] = {}
+        seen_ids: set[str] = set()
+
+        for row in rows:
+            record_id = row.get("id")
+            if record_id in seen_ids:
+                continue
+            if record_id is not None:
+                seen_ids.add(record_id)
+
+            doc_id = row["document_id"]
+            summary = summaries.get(doc_id)
+            if summary is None:
+                chunk_payload = row["chunk"]
+                summaries[doc_id] = DocumentSummary(
+                    document_id=doc_id,
+                    source=chunk_payload.get("source", ""),
+                    chunk_count=1,
+                    metadata=dict(chunk_payload.get("metadata", {})),
+                )
+            else:
+                summary.chunk_count += 1
+
+        return list(summaries.values())
+
+    def _query_all_rows(
+        self,
+        client: "MilvusClient",
+        collection: str,
+        metadata_filter: dict[str, Any] | None,
+    ) -> list[dict[str, Any]]:
+        """Query all rows needed by ``list_documents``."""
+        output_fields = ["id", "document_id", "chunk"]
+        expr = self._build_metadata_filter(metadata_filter)
+
+        if hasattr(client, "query_iterator"):
+            iterator = client.query_iterator(
+                collection_name=collection,
+                filter=expr,
+                output_fields=output_fields,
+                batch_size=self._batch_size,
+            )
+            try:
+                rows = []
+                while True:
+                    batch = iterator.next()
+                    if not batch:
+                        break
+                    rows.extend(batch)
+                return rows
+            finally:
+                close = getattr(iterator, "close", None)
+                if close is not None:
+                    close()
+
+        rows = []
+        offset = 0
+        while True:
+            batch = client.query(
+                collection_name=collection,
+                filter=expr,
+                output_fields=output_fields,
+                limit=self._batch_size,
+                offset=offset,
+            )
+            if not batch:
+                break
+            rows.extend(batch)
+            if len(batch) < self._batch_size:
+                break
+            offset += self._batch_size
+        return rows
+
+    @staticmethod
+    def _build_document_filter(document_id: str) -> str:
+        """Build a Milvus scalar filter for a document id."""
+        return f"document_id == {json.dumps(document_id, ensure_ascii=False)}"
+
+    @staticmethod
+    def _build_metadata_filter(
+        metadata_filter: dict[str, Any] | None,
+    ) -> str:
+        """Translate a flat ``{key: value}`` filter into a Milvus expr."""
+        if not metadata_filter:
+            return ""
+
+        return " and ".join(
+            f"metadata[{json.dumps(key, ensure_ascii=False)}] == "
+            f"{json.dumps(value, ensure_ascii=False)}"
+            for key, value in metadata_filter.items()
+        )
+
+    @staticmethod
+    def _extract_score(
+        hit: dict[str, Any],
+        metric_type: Literal["COSINE", "IP", "L2"],
+    ) -> float:
+        """Extract a score from Milvus search result shapes."""
+        if "distance" in hit:
+            distance = float(hit["distance"])
+            if metric_type == "COSINE":
+                return 1.0 - distance
+            return distance
+        if "score" in hit:
+            return float(hit["score"])
+        return 0.0
+
+    @staticmethod
+    def _is_local_db_uri(uri: str) -> bool:
+        """Check whether a URI starts an embedded Milvus Lite server."""
+        return not uri.startswith(("http://", "https://")) and (
+            os.path.splitext(uri)[1] == ".db"
+        )
+
+    def _release_lite_server(self) -> None:
+        """Release the embedded Milvus Lite server for local ``.db`` URIs."""
+        try:
+            from milvus_lite import server_manager_instance
+        except ImportError:
+            return
+        server_manager_instance.release_server(self._uri)
diff --git a/src/agentscope/rag/_vdb/_mongodb.py b/src/agentscope/rag/_vdb/_mongodb.py
new file mode 100644
index 0000000..358c8a8
--- /dev/null
+++ b/src/agentscope/rag/_vdb/_mongodb.py
@@ -0,0 +1,464 @@
+# -*- coding: utf-8 -*-
+"""MongoDB implementation of the vector store backend.
+
+Built on ``pymongo.AsyncMongoClient`` and MongoDB Vector Search
+(``$vectorSearch``), so all operations are non-blocking and safe to
+call from the application's event loop.
+
+The same class supports MongoDB Atlas and self-hosted deployments
+through the constructor arguments:
+
+- ``uri="mongodb+srv://..."`` — MongoDB Atlas cluster
+- ``uri="mongodb://localhost:27017"`` — self-hosted replica set
+  (MongoDB 7.0+ with Vector Search enabled)
+"""
+import asyncio
+import time
+from typing import TYPE_CHECKING, Any, Literal
+
+from ._vector_store import (
+    DocumentSummary,
+    VectorRecord,
+    VectorSearchResult,
+    VectorStoreBase,
+)
+from .._document import Chunk
+
+if TYPE_CHECKING:
+    from pymongo import AsyncMongoClient
+
+
+class MongoDBStore(VectorStoreBase):
+    """Vector store backend backed by `MongoDB Vector Search \
+<https://www.mongodb.com/docs/atlas/atlas-vector-search/vector-search-overview/>`_.
+
+    Each knowledge base maps to one MongoDB collection inside a single
+    database.  Every document stores the owning ``document_id`` plus
+    the serialized :class:`~agentscope.rag.Chunk`, which is
+    reconstructed on retrieval.
+
+    .. note:: Requires ``pymongo`` with ``AsyncMongoClient`` support
+        (``pymongo>=4.7``).  Install with
+        ``pip install agentscope[mongodb]``.
+
+    .. note:: Fields used in :meth:`search` ``metadata_filter`` must be
+        declared in ``filter_fields`` at construction time so they are
+        included in the vector search index definition.
+
+    .. code-block:: python
+
+        # MongoDB Atlas
+        store = MongoDBStore(
+            uri="mongodb+srv://user:pass@cluster.mongodb.net",
+            database="agentscope_rag",
+            filter_fields=[
+                "document_id",
+                "chunk.metadata.tenant_id",
+            ],
+        )
+
+        async with store:
+            await store.create_collection("kb-1", dimensions=768)
+
+    """
+
+    def __init__(
+        self,
+        uri: str,
+        database: str,
+        distance: Literal["cosine", "euclidean", "dotProduct"] = "cosine",
+        index_name: str = "vector_index",
+        filter_fields: list[str] | None = None,
+        client_kwargs: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize the MongoDB vector store.
+
+        Args:
+            uri (`str`):
+                The MongoDB connection URI, e.g.
+                ``"mongodb+srv://..."`` for Atlas or
+                ``"mongodb://localhost:27017"`` for a self-hosted
+                replica set.
+            database (`str`):
+                The database name.  Each knowledge base maps to one
+                collection inside this database.
+            distance (`Literal["cosine", "euclidean", "dotProduct"]`, \
+             defaults to ``"cosine"``):
+                The similarity metric used when creating vector search
+                indexes.
+            index_name (`str`, defaults to ``"vector_index"``):
+                The name of the vector search index created on each
+                collection.  All collections share this index name.
+            filter_fields (`list[str] | None`, optional):
+                Field paths declared as filter fields in the vector
+                search index.  Required for ``metadata_filter`` in
+                :meth:`search`.  Defaults to ``["document_id"]``.
+            client_kwargs (`dict[str, Any] | None`, optional):
+                Extra keyword arguments forwarded to
+                :class:`~pymongo.AsyncMongoClient`.
+        """
+        self._uri = uri
+        self._database_name = database
+        self._distance = distance
+        self._index_name = index_name
+        self._filter_fields = filter_fields or ["document_id"]
+        self._client_kwargs = client_kwargs or {}
+        self._client: "AsyncMongoClient | None" = None
+
+    def get_client(self) -> "AsyncMongoClient":
+        """Lazily create and cache the async MongoDB client.
+
+        Returns:
+            `AsyncMongoClient`:
+                The shared async client instance.
+        """
+        if self._client is None:
+            from pymongo import AsyncMongoClient
+
+            self._client = AsyncMongoClient(
+                self._uri,
+                **self._client_kwargs,
+            )
+        return self._client
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: Any,
+    ) -> None:
+        """Exit the async context — close the underlying client."""
+        if self._client is not None:
+            await self._client.close()
+            self._client = None
+
+    # ------------------------------------------------------------------
+    # Collection management
+    # ------------------------------------------------------------------
+
+    def _db(self) -> Any:
+        """Return the configured database handle."""
+        return self.get_client()[self._database_name]
+
+    def _col(self, collection: str) -> Any:
+        """Return a collection handle inside the configured database."""
+        return self._db()[collection]
+
+    async def create_collection(self, name: str, dimensions: int) -> None:
+        """Create a new MongoDB collection with a vector search index.
+
+        No-op if the collection already exists.
+
+        Args:
+            name (`str`):
+                The collection name. Typically, the knowledge base ID.
+            dimensions (`int`):
+                The fixed vector dimensionality for this collection.
+        """
+        if await self.has_collection(name):
+            return
+
+        from pymongo.operations import SearchIndexModel
+
+        await self._db().create_collection(name)
+        col = self._col(name)
+
+        fields: list[dict[str, Any]] = [
+            {
+                "type": "vector",
+                "path": "vector",
+                "numDimensions": dimensions,
+                "similarity": self._distance,
+            },
+        ]
+        fields.extend(
+            {"type": "filter", "path": field_path}
+            for field_path in self._filter_fields
+        )
+
+        model = SearchIndexModel(
+            definition={"fields": fields},
+            name=self._index_name,
+            type="vectorSearch",
+        )
+        await col.create_search_index(model)
+        await self._wait_for_index_ready(col, name)
+
+    async def delete_collection(self, name: str) -> None:
+        """Delete a collection and all its data.
+
+        Args:
+            name (`str`):
+                The collection name to delete.
+        """
+        await self._col(name).drop()
+
+    async def has_collection(self, name: str) -> bool:
+        """Check whether a collection exists.
+
+        Args:
+            name (`str`):
+                The collection name to check.
+
+        Returns:
+            `bool`: ``True`` if the collection exists.
+        """
+        return name in await self._db().list_collection_names()
+
+    async def _wait_for_index_ready(
+        self,
+        collection: Any,
+        collection_name: str,
+        timeout: float = 30.0,
+    ) -> None:
+        """Poll until the vector search index becomes queryable.
+
+        Args:
+            collection:
+                The MongoDB collection handle.
+            collection_name (`str`):
+                The collection name (used in timeout error messages).
+            timeout (`float`, defaults to ``30.0``):
+                Maximum seconds to wait before raising
+                :class:`TimeoutError`.
+
+        Raises:
+            `TimeoutError`:
+                If the index is not queryable within ``timeout`` seconds.
+        """
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            async for index in await collection.list_search_indexes(
+                self._index_name,
+            ):
+                if index.get("queryable"):
+                    return
+                break
+            await asyncio.sleep(0.5)
+
+        raise TimeoutError(
+            f"Vector search index {self._index_name!r} on collection "
+            f"{collection_name!r} was not queryable within {timeout}s",
+        )
+
+    async def _ensure_index_ready(self, collection: str) -> None:
+        """Ensure the vector search index is queryable before reads."""
+        await self._wait_for_index_ready(self._col(collection), collection)
+
+    # ------------------------------------------------------------------
+    # Data operations
+    # ------------------------------------------------------------------
+
+    async def insert(
+        self,
+        collection: str,
+        records: list[VectorRecord],
+    ) -> None:
+        """Insert records into a collection.
+
+        Each document stores :attr:`VectorRecord.document_id` under the
+        ``document_id`` key and the serialized :class:`Chunk` under the
+        ``chunk`` key, so that :meth:`delete` can remove all records of
+        one document.
+
+        Args:
+            collection (`str`):
+                The target collection name.
+            records (`list[VectorRecord]`):
+                The records to insert (each carrying a
+                :class:`Chunk` and its embedding vector).
+        """
+        if not records:
+            return
+
+        from pymongo import ReplaceOne
+
+        col = self._col(collection)
+        operations = [
+            ReplaceOne(
+                {"_id": f"{record.document_id}_{record.chunk.chunk_index}"},
+                {
+                    "_id": f"{record.document_id}_{record.chunk.chunk_index}",
+                    "document_id": record.document_id,
+                    "vector": record.vector,
+                    "chunk": record.chunk.model_dump(mode="json"),
+                },
+                upsert=True,
+            )
+            for record in records
+        ]
+        await col.bulk_write(operations, ordered=False)
+
+    async def delete(
+        self,
+        collection: str,
+        document_id: str,
+    ) -> None:
+        """Delete all records belonging to one source document.
+
+        Matches the ``document_id`` field written by :meth:`insert` from
+        :attr:`VectorRecord.document_id`.
+
+        Args:
+            collection (`str`):
+                The target collection name.
+            document_id (`str`):
+                The source document ID whose records should be
+                removed.
+        """
+        await self._col(collection).delete_many({"document_id": document_id})
+
+    # ------------------------------------------------------------------
+    # Search
+    # ------------------------------------------------------------------
+
+    async def search(
+        self,
+        collection: str,
+        query_vector: list[float],
+        top_k: int = 5,
+        metadata_filter: dict[str, Any] | None = None,
+    ) -> list[VectorSearchResult]:
+        """Find the most similar records to a query vector.
+
+        Args:
+            collection (`str`):
+                The collection to search.
+            query_vector (`list[float]`):
+                The query embedding vector.
+            top_k (`int`, defaults to ``5``):
+                Maximum number of results to return.
+            metadata_filter (`dict[str, Any] | None`, optional):
+                If provided, restrict the search to records whose
+                ``chunk.metadata`` matches every ``key == value`` pair
+                in this dict (translated into a MongoDB filter against
+                ``chunk.metadata.<key>``).  Each key must correspond to
+                a path declared in ``filter_fields``.
+
+        Returns:
+            `list[VectorSearchResult]`:
+                Results ordered by descending similarity score.
+        """
+        await self._ensure_index_ready(collection)
+        col = self._col(collection)
+
+        vector_search: dict[str, Any] = {
+            "index": self._index_name,
+            "path": "vector",
+            "queryVector": query_vector,
+            "numCandidates": max(100, top_k * 20),
+            "limit": top_k,
+        }
+        filter_expr = self._build_metadata_filter(metadata_filter)
+        if filter_expr is not None:
+            vector_search["filter"] = filter_expr
+
+        pipeline = [
+            {"$vectorSearch": vector_search},
+            {
+                "$project": {
+                    "document_id": 1,
+                    "chunk": 1,
+                    "score": {"$meta": "vectorSearchScore"},
+                },
+            },
+        ]
+
+        results: list[VectorSearchResult] = []
+        async for doc in await col.aggregate(pipeline):
+            results.append(
+                VectorSearchResult(
+                    score=float(doc["score"]),
+                    document_id=doc["document_id"],
+                    chunk=Chunk.model_validate(doc["chunk"]),
+                ),
+            )
+        return results
+
+    @staticmethod
+    def _build_metadata_filter(
+        metadata_filter: dict[str, Any] | None,
+    ) -> dict[str, Any] | None:
+        """Translate a flat ``{key: value}`` filter into a MongoDB filter.
+
+        Each ``key`` is matched against the corresponding nested path
+        ``chunk.metadata.<key>`` written by :meth:`insert`.  Returns
+        ``None`` when ``metadata_filter`` is empty so that callers
+        skip the filter argument entirely.
+
+        Args:
+            metadata_filter (`dict[str, Any] | None`):
+                The flat filter, or ``None`` for no filter.
+
+        Returns:
+            `dict[str, Any] | None`:
+                A MongoDB filter document, or ``None``.
+        """
+        if not metadata_filter:
+            return None
+
+        return {
+            "$and": [
+                {f"chunk.metadata.{key}": {"$eq": value}}
+                for key, value in metadata_filter.items()
+            ],
+        }
+
+    # ------------------------------------------------------------------
+    # Document listing
+    # ------------------------------------------------------------------
+
+    async def list_documents(
+        self,
+        collection: str,
+        metadata_filter: dict[str, Any] | None = None,
+    ) -> list[DocumentSummary]:
+        """List all distinct source documents indexed in a collection.
+
+        Aggregates records by ``document_id``.  The first chunk encountered
+        for each document supplies the ``source`` filename and the
+        document-level ``metadata``.
+
+        Args:
+            collection (`str`):
+                The target collection name.
+            metadata_filter (`dict[str, Any] | None`, optional):
+                If provided, restrict aggregation to records whose
+                ``chunk.metadata`` matches every ``key == value`` pair.
+
+        Returns:
+            `list[DocumentSummary]`:
+                One summary per distinct ``document_id``.
+        """
+        pipeline: list[dict[str, Any]] = []
+        if metadata_filter:
+            pipeline.append(
+                {
+                    "$match": {
+                        f"chunk.metadata.{key}": value
+                        for key, value in metadata_filter.items()
+                    },
+                },
+            )
+        pipeline.append(
+            {
+                "$group": {
+                    "_id": "$document_id",
+                    "source": {"$first": "$chunk.source"},
+                    "metadata": {"$first": "$chunk.metadata"},
+                    "chunk_count": {"$sum": 1},
+                },
+            },
+        )
+
+        summaries: list[DocumentSummary] = []
+        async for row in await self._col(collection).aggregate(pipeline):
+            summaries.append(
+                DocumentSummary(
+                    document_id=row["_id"],
+                    source=row["source"],
+                    chunk_count=row["chunk_count"],
+                    metadata=row["metadata"] or {},
+                ),
+            )
+        return summaries
diff --git a/src/agentscope/rag/_vdb/_qdrant.py b/src/agentscope/rag/_vdb/_qdrant.py
new file mode 100644
index 0000000..3fc44b0
--- /dev/null
+++ b/src/agentscope/rag/_vdb/_qdrant.py
@@ -0,0 +1,392 @@
+# -*- coding: utf-8 -*-
+"""Qdrant implementation of the vector store backend.
+
+Built on the official ``qdrant-client`` SDK using its fully
+asynchronous client (:class:`~qdrant_client.AsyncQdrantClient`), so all
+operations are non-blocking and safe to call from the application's
+event loop.
+
+The same class supports all Qdrant deployment modes through the
+constructor arguments:
+
+- ``location=":memory:"`` — in-process, ephemeral (ideal for tests)
+- ``path="/path/to/db"`` — in-process, persisted to local disk
+- ``url="http://localhost:6333"`` — remote Qdrant server / cloud
+"""
+import uuid
+from typing import TYPE_CHECKING, Any, Literal
+
+from ._vector_store import (
+    DocumentSummary,
+    VectorRecord,
+    VectorSearchResult,
+    VectorStoreBase,
+)
+from .._document import Chunk
+
+if TYPE_CHECKING:
+    from qdrant_client import AsyncQdrantClient
+
+
+class QdrantStore(VectorStoreBase):
+    """Vector store backend backed by `Qdrant <https://qdrant.tech>`_.
+
+    Each knowledge base maps to one Qdrant collection.  Every point
+    payload stores the owning ``document_id`` plus the serialized
+    :class:`~agentscope.rag.Chunk`, which is reconstructed on
+    retrieval.
+
+    .. note:: The ``qdrant-client`` package is required. Install it
+        with ``pip install qdrant-client``.
+
+    .. code-block:: python
+
+        # In-memory (tests / prototyping)
+        store = QdrantStore(location=":memory:")
+
+        # Remote server
+        store = QdrantStore(
+            url="http://localhost:6333",
+            api_key="...",
+        )
+
+        async with store:
+            await store.create_collection("kb-1", dimensions=768)
+
+    """
+
+    def __init__(
+        self,
+        location: str | None = None,
+        url: str | None = None,
+        path: str | None = None,
+        api_key: str | None = None,
+        distance: Literal["Cosine", "Dot", "Euclid", "Manhattan"] = "Cosine",
+        client_kwargs: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize the Qdrant vector store.
+
+        Args:
+            location (`str | None`, optional):
+                Pass ``":memory:"`` for an ephemeral in-process
+                instance. Mutually exclusive with ``url`` and ``path``.
+            url (`str | None`, optional):
+                The URL of a remote Qdrant server, e.g.
+                ``"http://localhost:6333"``.
+            path (`str | None`, optional):
+                A local directory for an in-process, on-disk instance.
+            api_key (`str | None`, optional):
+                The API key for Qdrant Cloud or a secured server.
+            distance (`Literal["Cosine", "Dot", "Euclid", "Manhattan"]`, \
+             defaults to ``"Cosine"``):
+                The distance metric used when creating collections.
+            client_kwargs (`dict[str, Any] | None`, optional):
+                Extra keyword arguments forwarded to
+                :class:`~qdrant_client.AsyncQdrantClient`.
+        """
+        self._location = location
+        self._url = url
+        self._path = path
+        self._api_key = api_key
+        self._distance = distance
+        self._client_kwargs = client_kwargs or {}
+        self._client: "AsyncQdrantClient | None" = None
+
+    def get_client(self) -> "AsyncQdrantClient":
+        """Lazily create and cache the async Qdrant client.
+
+        Returns:
+            `AsyncQdrantClient`:
+                The shared async client instance.
+        """
+        if self._client is None:
+            from qdrant_client import AsyncQdrantClient
+
+            self._client = AsyncQdrantClient(
+                location=self._location,
+                url=self._url,
+                path=self._path,
+                api_key=self._api_key,
+                **self._client_kwargs,
+            )
+        return self._client
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: Any,
+    ) -> None:
+        """Exit the async context — close the underlying client."""
+        if self._client is not None:
+            await self._client.close()
+            self._client = None
+
+    # ------------------------------------------------------------------
+    # Collection management
+    # ------------------------------------------------------------------
+
+    async def create_collection(
+        self,
+        name: str,
+        dimensions: int,
+    ) -> None:
+        """Create a new Qdrant collection.
+
+        No-op if the collection already exists.
+
+        Args:
+            name (`str`):
+                The collection name. Typically, the knowledge base ID.
+            dimensions (`int`):
+                The fixed vector dimensionality for this collection.
+        """
+        from qdrant_client import models
+
+        client = self.get_client()
+        if await client.collection_exists(name):
+            return
+        await client.create_collection(
+            collection_name=name,
+            vectors_config=models.VectorParams(
+                size=dimensions,
+                distance=models.Distance(self._distance),
+            ),
+        )
+
+    async def delete_collection(self, name: str) -> None:
+        """Delete a collection and all its data.
+
+        Args:
+            name (`str`):
+                The collection name to delete.
+        """
+        await self.get_client().delete_collection(name)
+
+    async def has_collection(self, name: str) -> bool:
+        """Check whether a collection exists.
+
+        Args:
+            name (`str`):
+                The collection name to check.
+
+        Returns:
+            `bool`: ``True`` if the collection exists.
+        """
+        return await self.get_client().collection_exists(name)
+
+    # ------------------------------------------------------------------
+    # Data operations
+    # ------------------------------------------------------------------
+
+    async def insert(
+        self,
+        collection: str,
+        records: list[VectorRecord],
+    ) -> None:
+        """Insert records into a collection.
+
+        Each point payload stores the :attr:`VectorRecord.document_id`
+        under the ``document_id`` key and the serialized
+        :class:`Chunk` under the ``chunk`` key, so that :meth:`delete`
+        can remove all records of one document.
+
+        Args:
+            collection (`str`):
+                The target collection name.
+            records (`list[VectorRecord]`):
+                The records to insert (each carrying a
+                :class:`Chunk` and its embedding vector).
+        """
+
+        from qdrant_client import models
+
+        if not records:
+            return
+        await self.get_client().upsert(
+            collection_name=collection,
+            points=[
+                models.PointStruct(
+                    id=str(uuid.uuid4()),
+                    vector=record.vector,
+                    payload={
+                        "document_id": record.document_id,
+                        "chunk": record.chunk.model_dump(mode="json"),
+                    },
+                )
+                for record in records
+            ],
+        )
+
+    async def delete(
+        self,
+        collection: str,
+        document_id: str,
+    ) -> None:
+        """Delete all records belonging to one source document.
+
+        Matches the ``document_id`` payload key written by
+        :meth:`insert` from :attr:`VectorRecord.document_id`.
+
+        Args:
+            collection (`str`):
+                The target collection name.
+            document_id (`str`):
+                The source document ID whose records should be
+                removed.
+        """
+        from qdrant_client import models
+
+        await self.get_client().delete(
+            collection_name=collection,
+            points_selector=models.FilterSelector(
+                filter=models.Filter(
+                    must=[
+                        models.FieldCondition(
+                            key="document_id",
+                            match=models.MatchValue(value=document_id),
+                        ),
+                    ],
+                ),
+            ),
+        )
+
+    # ------------------------------------------------------------------
+    # Search
+    # ------------------------------------------------------------------
+
+    async def search(
+        self,
+        collection: str,
+        query_vector: list[float],
+        top_k: int = 5,
+        metadata_filter: dict[str, Any] | None = None,
+    ) -> list[VectorSearchResult]:
+        """Find the most similar records to a query vector.
+
+        Args:
+            collection (`str`):
+                The collection to search.
+            query_vector (`list[float]`):
+                The query embedding vector.
+            top_k (`int`, defaults to ``5``):
+                Maximum number of results to return.
+            metadata_filter (`dict[str, Any] | None`, optional):
+                If provided, restrict the search to records whose
+                ``chunk.metadata`` matches every ``key == value`` pair
+                in this dict (translated into a Qdrant ``must`` payload
+                filter against ``chunk.metadata.<key>``).
+
+        Returns:
+            `list[VectorSearchResult]`:
+                Results ordered by descending similarity score.
+        """
+        response = await self.get_client().query_points(
+            collection_name=collection,
+            query=query_vector,
+            limit=top_k,
+            with_payload=True,
+            query_filter=self._build_metadata_filter(metadata_filter),
+        )
+        return [
+            VectorSearchResult(
+                score=point.score,
+                document_id=point.payload["document_id"],
+                chunk=Chunk.model_validate(point.payload["chunk"]),
+            )
+            for point in response.points
+        ]
+
+    # ------------------------------------------------------------------
+    # Document listing
+    # ------------------------------------------------------------------
+
+    async def list_documents(
+        self,
+        collection: str,
+        metadata_filter: dict[str, Any] | None = None,
+    ) -> list[DocumentSummary]:
+        """List all distinct source documents indexed in a collection.
+
+        Scrolls the collection in payload-only mode (vectors disabled)
+        and aggregates by ``document_id``.  The first chunk encountered
+        for each document supplies the ``source`` filename and the
+        document-level ``metadata``.
+
+        Args:
+            collection (`str`):
+                The target collection name.
+            metadata_filter (`dict[str, Any] | None`, optional):
+                If provided, restrict aggregation to records whose
+                ``chunk.metadata`` matches every ``key == value`` pair.
+
+        Returns:
+            `list[DocumentSummary]`:
+                One summary per distinct ``document_id``.
+        """
+        client = self.get_client()
+        query_filter = self._build_metadata_filter(metadata_filter)
+        summaries: dict[str, DocumentSummary] = {}
+        offset: Any = None
+
+        while True:
+            points, next_offset = await client.scroll(
+                collection_name=collection,
+                scroll_filter=query_filter,
+                limit=256,
+                offset=offset,
+                with_payload=True,
+                with_vectors=False,
+            )
+            for point in points:
+                doc_id = point.payload["document_id"]
+                summary = summaries.get(doc_id)
+                if summary is None:
+                    chunk_payload = point.payload["chunk"]
+                    summaries[doc_id] = DocumentSummary(
+                        document_id=doc_id,
+                        source=chunk_payload.get("source", ""),
+                        chunk_count=1,
+                        metadata=dict(chunk_payload.get("metadata", {})),
+                    )
+                else:
+                    summary.chunk_count += 1
+            if next_offset is None:
+                break
+            offset = next_offset
+
+        return list(summaries.values())
+
+    @staticmethod
+    def _build_metadata_filter(
+        metadata_filter: dict[str, Any] | None,
+    ) -> Any:
+        """Translate a flat ``{key: value}`` filter into a Qdrant filter.
+
+        Each ``key`` is matched against the corresponding nested path
+        ``chunk.metadata.<key>`` written by :meth:`insert`.  Returns
+        ``None`` when ``metadata_filter`` is empty so that callers
+        skip the filter argument entirely.
+
+        Args:
+            metadata_filter (`dict[str, Any] | None`):
+                The flat filter, or ``None`` for no filter.
+
+        Returns:
+            `qdrant_client.models.Filter | None`:
+                A Qdrant ``Filter`` object, or ``None``.
+        """
+        if not metadata_filter:
+            return None
+
+        from qdrant_client import models
+
+        return models.Filter(
+            must=[
+                models.FieldCondition(
+                    key=f"chunk.metadata.{key}",
+                    match=models.MatchValue(value=value),
+                )
+                for key, value in metadata_filter.items()
+            ],
+        )
diff --git a/src/agentscope/rag/_vdb/_vector_store.py b/src/agentscope/rag/_vdb/_vector_store.py
new file mode 100644
index 0000000..e491c70
--- /dev/null
+++ b/src/agentscope/rag/_vdb/_vector_store.py
@@ -0,0 +1,291 @@
+# -*- coding: utf-8 -*-
+"""Abstract base class for vector store backends.
+
+A :class:`VectorStoreBase` instance is the single connection point to
+one vector database deployment.  It is created once at application
+startup, passed into ``create_app(vector_store=...)``, and shared
+across all requests for the lifetime of the process — similar to
+:class:`~agentscope.app.storage.StorageBase` and
+:class:`~agentscope.app.message_bus.MessageBus`.
+
+Each **knowledge base** maps to one **collection** inside the vector
+store.  Collections are isolated: different knowledge bases never
+share a collection, so retrieval is always scoped to a single
+collection without cross-collection filtering.
+
+Lifecycle is managed via the async context manager protocol
+(``__aenter__`` / ``__aexit__``), which the app lifespan calls
+automatically.
+"""
+from abc import ABC, abstractmethod
+from typing import Any, Self
+
+from pydantic import BaseModel, Field
+
+from .._document import Chunk
+
+
+class VectorRecord(BaseModel):
+    """A single record to insert into a vector store collection.
+
+    Pairs a :class:`Chunk` (the business payload — content, source,
+    structural metadata) with its dense embedding vector.  ``Chunk``
+    is intentionally not extended with an ``embedding`` field so its
+    semantics stay stable across the indexing pipeline; instead the
+    vector lives in this wrapper whose only purpose is "I am about
+    to be inserted into a vector database."
+    """
+
+    vector: list[float]
+    """The dense embedding vector for :attr:`chunk`."""
+
+    document_id: str
+    """The ID of the source document this record belongs to.
+    Assigned by the knowledge base layer when the document is
+    registered.  Backends must persist it at insertion time so that
+    :meth:`VectorStoreBase.delete` can remove all records of one
+    document as a unit."""
+
+    chunk: Chunk
+    """The business payload — content, source, structural metadata."""
+
+
+class VectorSearchResult(BaseModel):
+    """A single result returned by a similarity search.
+
+    Pairs the matched :class:`Chunk` with its similarity score.
+    ``Chunk`` is intentionally not extended with a ``score`` field so
+    its semantics stay stable; instead the score lives in this
+    wrapper whose only purpose is "I am a query hit."
+    """
+
+    score: float
+    """Similarity score.  Higher = more similar for cosine /
+    dot-product; lower = more similar for L2 distance."""
+
+    document_id: str
+    """The ID of the source document the matched chunk belongs to —
+    the same value carried by :attr:`VectorRecord.document_id` at
+    insertion time.  Lets callers cite, group, or delete the source
+    document of a hit."""
+
+    chunk: Chunk
+    """The matched business payload."""
+
+
+class DocumentSummary(BaseModel):
+    """A lightweight description of one source document inside a collection.
+
+    Aggregated by :meth:`VectorStoreBase.list_documents` from the
+    records of each ``document_id`` — the vector store is the single
+    source of truth for "what documents exist in a knowledge base".
+    """
+
+    document_id: str
+    """The source document identifier — the same value carried by
+    :attr:`VectorRecord.document_id` at insertion time."""
+
+    source: str
+    """The original filename, taken from the first chunk encountered.
+    All chunks of the same document share the same filename so any
+    chunk yields the same value."""
+
+    chunk_count: int
+    """The total number of chunks indexed for this document."""
+
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    """Document-level metadata propagated from the parser / uploader
+    (media type, size, upload time, ...).  Taken from the first chunk
+    encountered."""
+
+
+class VectorStoreBase(ABC):
+    """Abstract base class for vector store backends.
+
+    Subclasses implement the concrete connection and query logic for a
+    specific vector database (Chroma, Milvus, Qdrant, FAISS, etc.).
+
+    A single instance is shared across the entire application.  The
+    underlying client SDK is expected to handle connection pooling and
+    thread safety internally.
+    """
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def __aenter__(self) -> Self:
+        """Enter the async context — open connections if needed.
+
+        The default implementation is a no-op.  Subclasses that need
+        explicit connection setup should override this.
+
+        Returns:
+            `VectorStoreBase`: ``self``.
+        """
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: Any,
+    ) -> None:
+        """Exit the async context — close connections if needed.
+
+        The default implementation is a no-op.
+        """
+
+    # ------------------------------------------------------------------
+    # Collection management
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    async def create_collection(
+        self,
+        name: str,
+        dimensions: int,
+    ) -> None:
+        """Create a new collection (vector index).
+
+        If the collection already exists, implementations should raise
+        or silently no-op depending on the backend's semantics.
+
+        Args:
+            name (`str`):
+                The collection name. Typically, the knowledge base ID.
+            dimensions (`int`):
+                The fixed vector dimensionality for this collection.
+                All vectors inserted later must have this many elements.
+        """
+
+    @abstractmethod
+    async def delete_collection(self, name: str) -> None:
+        """Delete a collection and all its data.
+
+        Args:
+            name (`str`):
+                The collection name to delete.
+        """
+
+    @abstractmethod
+    async def has_collection(self, name: str) -> bool:
+        """Check whether a collection exists.
+
+        Args:
+            name (`str`):
+                The collection name to check.
+
+        Returns:
+            `bool`: ``True`` if the collection exists.
+        """
+
+    # ------------------------------------------------------------------
+    # Data operations
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    async def insert(
+        self,
+        collection: str,
+        records: list[VectorRecord],
+    ) -> None:
+        """Insert records into a collection.
+
+        Args:
+            collection (`str`):
+                The target collection name.
+            records (`list[VectorRecord]`):
+                The records to insert (each carrying a
+                :class:`Chunk` and its embedding vector).
+        """
+
+    @abstractmethod
+    async def delete(
+        self,
+        collection: str,
+        document_id: str,
+    ) -> None:
+        """Delete all records belonging to one source document.
+
+        Identifies records by the :attr:`VectorRecord.document_id`
+        field that backends persist at insertion time.  This matches
+        the typical RAG workflow where a user uploads or removes a
+        file as a unit.
+
+        Args:
+            collection (`str`):
+                The target collection name.
+            document_id (`str`):
+                The source document ID whose records should be
+                removed.
+        """
+
+    # ------------------------------------------------------------------
+    # Search
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    async def search(
+        self,
+        collection: str,
+        query_vector: list[float],
+        top_k: int = 5,
+        metadata_filter: dict[str, Any] | None = None,
+    ) -> list[VectorSearchResult]:
+        """Find the most similar records to a query vector.
+
+        Args:
+            collection (`str`):
+                The collection to search.
+            query_vector (`list[float]`):
+                The query embedding vector.
+            top_k (`int`, defaults to ``5``):
+                Maximum number of results to return.
+            metadata_filter (`dict[str, Any] | None`, optional):
+                If provided, restrict the search to records whose
+                ``chunk.metadata`` matches every ``key == value`` pair
+                in this dict.  Backends translate this into a native
+                payload filter.  Used for defense-in-depth
+                cross-tenant scoping when an isolation strategy
+                co-locates multiple knowledge bases inside the same
+                collection.
+
+        Returns:
+            `list[VectorSearchResult]`:
+                Results ordered by descending similarity score.
+        """
+
+    # ------------------------------------------------------------------
+    # Document listing
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    async def list_documents(
+        self,
+        collection: str,
+        metadata_filter: dict[str, Any] | None = None,
+    ) -> list[DocumentSummary]:
+        """List all distinct source documents indexed in a collection.
+
+        Aggregates records by :attr:`VectorRecord.document_id` and
+        returns one :class:`DocumentSummary` per document.  Backends
+        are free to use whatever scrolling / aggregation primitive
+        they expose; this method is expected to be O(documents) not
+        O(chunks) on backends that support payload-only scans.
+
+        Args:
+            collection (`str`):
+                The target collection name.
+            metadata_filter (`dict[str, Any] | None`, optional):
+                If provided, restrict aggregation to records whose
+                ``chunk.metadata`` matches every ``key == value`` pair
+                in this dict.  Used together with the search-time
+                filter when an isolation strategy co-locates multiple
+                knowledge bases inside the same collection.
+
+        Returns:
+            `list[DocumentSummary]`:
+                One summary per distinct ``document_id``, in
+                unspecified order.
+        """
diff --git a/src/agentscope/skill/__init__.py b/src/agentscope/skill/__init__.py
new file mode 100644
index 0000000..98bd09a
--- /dev/null
+++ b/src/agentscope/skill/__init__.py
@@ -0,0 +1,11 @@
+# -*- coding: utf-8 -*-
+"""The skill related classes and functions."""
+
+from ._base import SkillLoaderBase, Skill
+from ._local_loader import LocalSkillLoader
+
+__all__ = [
+    "Skill",
+    "SkillLoaderBase",
+    "LocalSkillLoader",
+]
diff --git a/src/agentscope/skill/_base.py b/src/agentscope/skill/_base.py
new file mode 100644
index 0000000..9069073
--- /dev/null
+++ b/src/agentscope/skill/_base.py
@@ -0,0 +1,29 @@
+# -*- coding: utf-8 -*-
+"""The skill loader base class."""
+from abc import abstractmethod, ABC
+from dataclasses import dataclass
+
+
+@dataclass
+class Skill:
+    """The agent skill class"""
+
+    name: str
+    """The name of the skill."""
+    description: str
+    """The description of the skill."""
+    dir: str
+    """The directory of the agent skill."""
+    markdown: str
+    """The markdown content of the agent skill."""
+    updated_at: float
+    """The last updated time of the skill."""
+
+
+class SkillLoaderBase(ABC):
+    """The base class for skill loader."""
+
+    @abstractmethod
+    async def list_skills(self) -> list[Skill]:
+        """List all the skills that can be loaded by this loader."""
+        raise NotImplementedError
diff --git a/src/agentscope/skill/_local_loader.py b/src/agentscope/skill/_local_loader.py
new file mode 100644
index 0000000..04f3205
--- /dev/null
+++ b/src/agentscope/skill/_local_loader.py
@@ -0,0 +1,171 @@
+# -*- coding: utf-8 -*-
+"""The local skill loader class."""
+import asyncio
+import os
+
+import aiofiles
+import aiofiles.ospath
+import frontmatter
+
+from ._base import SkillLoaderBase
+from .._logging import logger
+from ..skill import Skill
+
+
+class LocalSkillLoader(SkillLoaderBase):
+    """The skill loader that loads skills from a local directory."""
+
+    def __init__(self, directory: str, scan_subdir: bool = False) -> None:
+        """Initialize the loader with the directory.
+
+        Args:
+            directory (`str`):
+                The directory to load skills from.
+            scan_subdir (`bool`, defaults to False):
+                Whether to scan subdirectories. Defaults to False (only
+                scan current directory).
+        """
+        self.directory = os.path.abspath(directory)
+        self.scan_subdir = scan_subdir
+        self._cache: dict[str, Skill] = {}
+
+    async def _load_single_skill(self, skill_root: str) -> Skill | None:
+        """Load a single skill from a skill root directory.
+
+        Args:
+            skill_root (`str`): The skill root directory containing SKILL.md.
+
+        Returns:
+            `Skill | None`: A Skill object or None if loading failed.
+        """
+        skill_md_path = os.path.join(skill_root, "SKILL.md")
+
+        try:
+            # Check if SKILL.md exists
+            if not await aiofiles.ospath.isfile(skill_md_path):
+                return None
+
+            # Get file modification time
+            updated_at = await aiofiles.ospath.getmtime(skill_md_path)
+
+            # Check cache: if cached skill exists and updated_at matches,
+            # return cached
+            if skill_root in self._cache:
+                cached_skill = self._cache[skill_root]
+                if cached_skill.updated_at == updated_at:
+                    return cached_skill
+
+            # Read and parse SKILL.md
+            async with aiofiles.open(
+                skill_md_path,
+                "r",
+                encoding="utf-8",
+            ) as f:
+                content_str = await f.read()
+                content = frontmatter.loads(content_str)
+
+            name = content.get("name")
+            description = content.get("description")
+
+            if not name or not description:
+                logger.warning(
+                    "SKILL.md in %s is missing required fields "
+                    "(name or description). Skipping.",
+                    skill_root,
+                )
+                return None
+
+            skill = Skill(
+                name=str(name),
+                description=str(description),
+                dir=skill_root,
+                markdown=content.content,
+                updated_at=updated_at,
+            )
+
+            # Update cache
+            self._cache[skill_root] = skill
+
+            return skill
+
+        except Exception as e:
+            logger.warning(
+                "Failed to load skill from %s: %s",
+                skill_root,
+                str(e),
+            )
+            return None
+
+    async def list_skills(self) -> list[Skill]:
+        """List all the available skills from the directory.
+
+        This method will:
+        1. Search for SKILL.md in the current directory
+        2. If scan_subdir is True, search for SKILL.md in all subdirectories
+        3. Load all SKILL.md files concurrently
+
+        Returns:
+            `list[Skill]`: A list of Skill objects.
+        """
+        try:
+            # Check if directory exists
+            if not await aiofiles.ospath.isdir(self.directory):
+                logger.warning(
+                    "Skill directory %s does not exist.",
+                    self.directory,
+                )
+                return []
+
+            # Find all directories containing SKILL.md
+            def _find_skill_dirs() -> list[str]:
+                """Find all directories containing SKILL.md file."""
+                dirs = []
+
+                if os.path.isfile(os.path.join(self.directory, "SKILL.md")):
+                    dirs.append(self.directory)
+
+                if self.scan_subdir:
+                    for root, _, filenames in os.walk(self.directory):
+                        if root == self.directory:
+                            continue
+                        if "SKILL.md" in filenames:
+                            dirs.append(root)
+
+                return dirs
+
+            skill_dirs = await asyncio.to_thread(_find_skill_dirs)
+
+            if not skill_dirs:
+                logger.info(
+                    "No SKILL.md files found in %s",
+                    self.directory,
+                )
+                return []
+
+            # Load all skills concurrently
+            tasks = [
+                self._load_single_skill(skill_dir) for skill_dir in skill_dirs
+            ]
+            results = await asyncio.gather(*tasks, return_exceptions=True)
+
+            # Filter out None results and exceptions
+            skills: list = []
+            for i, result in enumerate(results):
+                if isinstance(result, Exception):
+                    logger.warning(
+                        "Failed to load skill from %s: %s",
+                        skill_dirs[i],
+                        str(result),
+                    )
+                elif result is not None:
+                    skills.append(result)
+
+            return skills
+
+        except Exception as e:
+            logger.warning(
+                "Failed to list skills from directory %s: %s",
+                self.directory,
+                str(e),
+            )
+            return []
diff --git a/src/agentscope/state/__init__.py b/src/agentscope/state/__init__.py
new file mode 100644
index 0000000..d9db1c5
--- /dev/null
+++ b/src/agentscope/state/__init__.py
@@ -0,0 +1,11 @@
+# -*- coding: utf-8 -*-
+"""The agent state module in agentscope."""
+
+from ._state import AgentState, TaskContext
+from ._task import Task
+
+__all__ = [
+    "Task",
+    "TaskContext",
+    "AgentState",
+]
diff --git a/src/agentscope/state/_state.py b/src/agentscope/state/_state.py
new file mode 100644
index 0000000..3f3b676
--- /dev/null
+++ b/src/agentscope/state/_state.py
@@ -0,0 +1,251 @@
+# -*- coding: utf-8 -*-
+"""The agent state class."""
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+import aiofiles.os
+
+from .._utils._common import _generate_id
+from ._task import Task
+from ..message import (
+    TextBlock,
+    DataBlock,
+    Msg,
+    ToolCallBlock,
+    ToolCallState,
+    ToolResultBlock,
+    HintBlock,
+)
+from ..permission import PermissionContext
+
+
+class ReadCacheEntry(BaseModel):
+    """The read file cache."""
+
+    lines: list[str]
+    updated_at: float
+    bytes: float
+    file_path: str
+
+
+class ToolContext(BaseModel):
+    """The tool context, e.g. tool cache"""
+
+    max_cache_files: int = Field(default=100, gt=1)
+    """The maximum number of cached files."""
+    max_cache_bytes: float = Field(default=25000, gt=10000)
+    """The maximum size of the accumulated read file cache."""
+    read_file_cache: list[ReadCacheEntry] = Field(default_factory=list)
+    """The cache for Read/Write/Edit file tools."""
+
+    activated_groups: list[str] = Field(default_factory=list)
+    """The names of the activated tool groups, each group contains a set of
+    tools."""
+
+    async def get_cache(self, file_path: str) -> ReadCacheEntry | None:
+        """Get cached file content if still valid.
+
+        Args:
+            file_path: The absolute path of the file.
+
+        Returns:
+            The cached entry if valid, otherwise None.
+        """
+
+        # Find the cache entry
+        for entry in self.read_file_cache:
+            if entry.file_path == file_path:
+                # Check if cache is still valid
+                try:
+                    updated_at = await aiofiles.os.path.getmtime(file_path)
+                    if updated_at == entry.updated_at:
+                        return entry
+                    else:
+                        # Cache is outdated, remove it
+                        self.read_file_cache.remove(entry)
+                        return None
+                except Exception:
+                    # File might not exist anymore
+                    self.read_file_cache.remove(entry)
+                    return None
+        return None
+
+    async def cache_file(self, file_path: str, lines: list[str]) -> None:
+        """Cache file content with LRU eviction.
+
+        Args:
+            file_path: The absolute path of the file.
+            lines: The lines of the file content.
+        """
+        try:
+            updated_at = await aiofiles.os.path.getmtime(file_path)
+        except Exception:
+            # Cannot get mtime, skip caching
+            return
+
+        # Calculate size in KB
+        new_entry_bytes = (
+            sum(len(line.encode("utf-8")) for line in lines) / 1024
+        )
+
+        # Remove existing cache for this file if present
+        self.read_file_cache = [
+            entry
+            for entry in self.read_file_cache
+            if entry.file_path != file_path
+        ]
+
+        # Evict the oldest entries if exceeding max_cache_files
+        while len(self.read_file_cache) >= self.max_cache_files:
+            self.read_file_cache.pop(0)
+
+        # Evict the oldest entries if exceeding max_cache_bytes
+        current_size = sum(entry.bytes for entry in self.read_file_cache)
+        while (
+            self.read_file_cache
+            and current_size + new_entry_bytes > self.max_cache_bytes
+        ):
+            removed = self.read_file_cache.pop(0)
+            current_size -= removed.bytes
+
+        # Add new entry to the end (most recent)
+        self.read_file_cache.append(
+            ReadCacheEntry(
+                lines=lines,
+                updated_at=updated_at,
+                bytes=new_entry_bytes,
+                file_path=file_path,
+            ),
+        )
+
+    async def clean_file_cache(
+        self,
+        reserved_file_paths: set[str] | None = None,
+    ) -> None:
+        """Drop read caches whose paths are not in ``reserved_file_paths``.
+
+        Args:
+            reserved_file_paths: File paths from Read calls that remain in the
+                context. Caches for these files are kept; all others are
+                evicted.
+        """
+        reserved_file_paths = reserved_file_paths or set()
+
+        self.read_file_cache = [
+            entry
+            for entry in self.read_file_cache
+            if entry.file_path in reserved_file_paths
+        ]
+
+
+class TaskContext(BaseModel):
+    """The task context."""
+
+    tasks: list[Task] = Field(default_factory=lambda: [])
+    """The task context."""
+
+
+class AgentState(BaseModel):
+    """The agent state that should be saved and loaded from storage."""
+
+    session_id: str = Field(default_factory=_generate_id)
+    """The session id of the agent. Normally, each session will maintain one
+    independent agent state for each agent."""
+
+    summary: str | list[TextBlock | DataBlock] = ""
+    """The compressed summary of the context, which will be prepended to the
+    context when fed into the LLM."""
+    context: list[Msg] = Field(default_factory=list)
+    """The uncompressed conversation context, which will be fed into the LLM"""
+    reply_id: str = Field(default_factory=_generate_id)
+    """The id of the current reply, which is also used as the id of the
+    final message of the reply."""
+    cur_iter: int = 0
+    """The current iteration of the agent's reasoning-acting loop."""
+
+    # =================================================================
+    # The permission context
+    # =================================================================
+    permission_context: PermissionContext = Field(
+        default_factory=PermissionContext,
+    )
+    """The permission context that will be passed to the toolkit to determine
+    the tool permissions."""
+
+    # =================================================================
+    # The tool context
+    # =================================================================
+    tool_context: ToolContext = Field(default_factory=ToolContext)
+
+    # =================================================================
+    # The tasks context
+    # =================================================================
+    tasks_context: TaskContext = Field(default_factory=TaskContext)
+    """The task context that records the agent tasks."""
+
+    # =================================================================
+    # The middleware context
+    # =================================================================
+    middle_context: dict[str, Any] = Field(default_factory=dict)
+    """The context that allow the middlewares to store/get data across
+    different replies."""
+
+    def append_context(
+        self,
+        name: str,
+        blocks: list[
+            TextBlock | DataBlock | HintBlock | ToolCallBlock | ToolResultBlock
+        ],
+    ) -> None:
+        """Append the given blocks to the agent's own message with the current
+        `reply_id`. If such message doesn't exist, a new assistant message
+        with agent's name and current reply ID will be created.
+        """
+        # If append to the latest message
+        if (
+            self.context
+            and self.context[-1].role == "assistant"
+            and self.context[-1].name == name
+            and self.context[-1].id == self.reply_id
+        ):
+            self.context[-1].content.extend(blocks)
+        else:
+            # Create a new assistant message with the current reply ID
+            self.context.append(
+                Msg(
+                    id=self.reply_id,
+                    role="assistant",
+                    name=name,
+                    content=blocks,
+                ),
+            )
+
+    def has_awaiting_tool_calls(self, name: str) -> bool:
+        """Whether the tail assistant message written by ``name`` has
+        any tool call still awaiting an outside response — an
+        ``ASKING`` user confirmation or a ``SUBMITTED`` external
+        execution with no matching tool result yet.
+
+        Args:
+            name (`str`):
+                Only messages authored by this agent name are inspected;
+                observed messages from other agents are ignored.
+
+        Returns:
+            `bool`:
+                ``True`` when at least one such tool call is pending.
+        """
+        if not self.context:
+            return False
+        last_msg = self.context[-1]
+        if last_msg.role != "assistant" or last_msg.name != name:
+            return False
+        result_ids = {b.id for b in last_msg.get_content_blocks("tool_result")}
+        return any(
+            tc.state == ToolCallState.ASKING
+            or (
+                tc.state == ToolCallState.SUBMITTED and tc.id not in result_ids
+            )
+            for tc in last_msg.get_content_blocks("tool_call")
+        )
diff --git a/src/agentscope/state/_task.py b/src/agentscope/state/_task.py
new file mode 100644
index 0000000..ae594f1
--- /dev/null
+++ b/src/agentscope/state/_task.py
@@ -0,0 +1,39 @@
+# -*- coding: utf-8 -*-
+"""The task class."""
+from datetime import datetime
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+from .._utils._common import _generate_id
+
+
+class Task(BaseModel):
+    """The agent task."""
+
+    subject: str
+    """The subject of the task."""
+
+    description: str
+    """The task description."""
+
+    metadata: dict[str, Any]
+    """The additional metadata of the task."""
+
+    created_at: str = Field(default_factory=lambda: datetime.now().isoformat())
+    """The created timestamp."""
+
+    state: Literal["pending", "in_progress", "completed"] = "pending"
+    """The task state."""
+
+    id: str = Field(default_factory=_generate_id)
+    """The task identifier."""
+
+    owner: str | None = None
+    """The owner of the task."""
+
+    blocks: list[str] = Field(default_factory=lambda: [])
+    """The task ids blocked by this task."""
+
+    blocked_by: list[str] = Field(default_factory=lambda: [])
+    """The task ids blocking this task."""
diff --git a/src/agentscope/tool/__init__.py b/src/agentscope/tool/__init__.py
new file mode 100644
index 0000000..f58f5f3
--- /dev/null
+++ b/src/agentscope/tool/__init__.py
@@ -0,0 +1,58 @@
+# -*- coding: utf-8 -*-
+"""The tool module in agentscope."""
+
+from ._types import ToolChoice, Function, RegisteredTool
+from ._response import ToolResponse, ToolChunk
+from ._toolkit import Toolkit
+from ._base import ToolBase, ParamsBase, ToolMiddlewareBase
+from ._adapters import MCPTool, FunctionTool
+from ._builtin import (
+    ResetTools,
+    Bash,
+    Edit,
+    Glob,
+    Grep,
+    Read,
+    Write,
+    BackendBase,
+    ExecResult,
+    LocalBackend,
+)
+from ._task import (
+    TaskUpdate,
+    TaskGet,
+    TaskList,
+    TaskCreate,
+)
+from ._tool_group import ToolGroup
+
+__all__ = [
+    # Basic tool related types and functions
+    "ToolChoice",
+    "Function",
+    "ToolBase",
+    "ParamsBase",
+    "ToolMiddlewareBase",
+    "MCPTool",
+    "FunctionTool",
+    "ToolGroup",
+    "Toolkit",
+    "ToolChunk",
+    "ToolResponse",
+    "RegisteredTool",
+    # Builtin tools
+    "BackendBase",
+    "LocalBackend",
+    "ExecResult",
+    "ResetTools",
+    "Bash",
+    "Edit",
+    "Glob",
+    "Grep",
+    "Read",
+    "Write",
+    "TaskUpdate",
+    "TaskGet",
+    "TaskList",
+    "TaskCreate",
+]
diff --git a/src/agentscope/tool/_adapters.py b/src/agentscope/tool/_adapters.py
new file mode 100644
index 0000000..b2ba535
--- /dev/null
+++ b/src/agentscope/tool/_adapters.py
@@ -0,0 +1,394 @@
+# -*- coding: utf-8 -*-
+"""Adapters to convert functions and MCP tools to ToolProtocol."""
+import inspect
+import json
+import re
+from contextlib import _AsyncGeneratorContextManager
+from datetime import timedelta
+from typing import Callable, Any, AsyncGenerator, Generator
+
+from mcp import ClientSession
+import mcp
+
+from ._types import Function
+from ._base import ToolBase, ToolMiddlewareBase
+from ..permission import (
+    PermissionBehavior,
+    PermissionDecision,
+)
+from ._response import ToolChunk
+from ._utils import _extract_func_description, _extract_input_schema
+from .._logging import logger
+from ..message import (
+    TextBlock,
+    DataBlock,
+    Base64Source,
+    URLSource,
+    ToolResultState,
+)
+
+
+class FunctionTool(ToolBase):
+    """Adapter to convert a Python function to ToolProtocol.
+
+    This class wraps a regular Python function and makes it compatible with
+    the ToolProtocol interface. It automatically extracts metadata from the
+    function's signature and docstring, and normalizes the return value to
+    ToolChunk or AsyncGenerator[ToolChunk, None].
+    """
+
+    is_external_tool: bool = False
+    """If this tool is an external tool, which doesn't need to implement the
+    __call__ method and the agent will yield the external tool call event."""
+    is_mcp: bool = False
+    """If this tool is an MCP tool, which will be used in the permission"""
+    mcp_name: str | None = None
+    """The name of the MCP server this tool belongs to, which is required if
+    this tool is an MCP tool."""
+
+    def __init__(
+        self,
+        func: Function,
+        name: str | None = None,
+        description: str | None = None,
+        is_concurrency_safe: bool = True,
+        is_read_only: bool = False,
+        is_state_injected: bool = False,
+        middlewares: list[ToolMiddlewareBase] | None = None,
+    ) -> None:
+        """Initialize the FunctionTool.
+
+        Args:
+            func (`Callable`):
+                The Python function to wrap.
+            name (`str | None`, optional):
+                Custom tool name. If None, uses the function name.
+            description (`str | None`, optional):
+                Custom tool description. If None, extracts from docstring.
+            is_concurrency_safe (`bool`, optional):
+                Whether this tool is safe to call concurrently.
+            is_read_only (`bool`, optional):
+                Whether this tool only reads data without side effects.
+            is_state_injected (`bool`, optional):
+                Whether this tool requires agent state injection.
+            middlewares (`list[ToolMiddlewareBase] | None`, optional):
+                Tool middlewares wrapping the tool execution.
+        """
+        super().__init__(middlewares=middlewares)
+        self.name = name or func.__name__
+        self.description = description or _extract_func_description(
+            func.__doc__ or "",
+        )
+        self.input_schema = _extract_input_schema(func)
+        self.is_concurrency_safe = is_concurrency_safe
+        self.is_read_only = is_read_only
+        self.is_state_injected = is_state_injected
+        self.is_external_tool = False
+        self.is_mcp = False
+        self._func = func
+
+    async def check_permissions(
+        self,
+        *_args: Any,
+        **_kwargs: Any,
+    ) -> PermissionDecision:
+        """Check permissions for the tool usage.
+
+        Default implementation allows all operations.
+
+        Returns:
+            `PermissionDecision`:
+                Permission decision (default: allowed).
+        """
+        return PermissionDecision(
+            behavior=PermissionBehavior.ASK,
+            message="Custom function tools must be explicitly allowed "
+            "by the user.",
+        )
+
+    async def call(
+        self,
+        **kwargs: Any,
+    ) -> ToolChunk | AsyncGenerator[ToolChunk, None]:
+        """Invoke the wrapped function in an async style.
+
+        Returns:
+            `ToolChunk` or `AsyncGenerator[ToolChunk, None]`:
+                The normalized result of the function execution.
+        """
+        if inspect.iscoroutinefunction(self._func):
+            result = await self._func(**kwargs)
+        else:
+            result = self._func(**kwargs)
+
+        if isinstance(result, AsyncGenerator):
+
+            async def _stream() -> AsyncGenerator[ToolChunk, None]:
+                async for chunk in result:
+                    if isinstance(chunk, ToolChunk):
+                        yield chunk
+                    else:
+                        yield self._convert_func_result_to_chunk(chunk)
+
+            return _stream()
+
+        if isinstance(result, Generator):
+
+            async def _stream() -> AsyncGenerator[ToolChunk, None]:
+                for chunk in result:
+                    if isinstance(chunk, ToolChunk):
+                        yield chunk
+                    else:
+                        yield self._convert_func_result_to_chunk(chunk)
+
+            return _stream()
+
+        return self._convert_func_result_to_chunk(result)
+
+    @staticmethod
+    def _convert_func_result_to_chunk(
+        result: Any,
+    ) -> ToolChunk:
+        if isinstance(result, ToolChunk):
+            return result
+        if isinstance(result, str):
+            text = result
+        else:
+            try:
+                text = json.dumps(result, ensure_ascii=False)
+            except (TypeError, ValueError):
+                text = str(result)
+        return ToolChunk(
+            content=[TextBlock(text=text)],
+            state=ToolResultState.RUNNING,
+        )
+
+
+class MCPTool(ToolBase):
+    """Adapter to convert an MCP tool to ToolProtocol.
+
+    This class wraps an MCP tool and makes it compatible with the ToolProtocol
+    interface. It handles the conversion between MCP's result format and
+    AgentScope's ToolChunk format.
+    """
+
+    is_mcp: bool = True
+    """Whether this tool is an MCP tool."""
+    is_state_injected: bool = False
+    """The mcp tools is prohibited state injection for safety reason."""
+
+    def __init__(
+        self,
+        mcp_name: str,
+        tool: mcp.types.Tool,
+        client_gen: Callable[..., _AsyncGeneratorContextManager[Any]]
+        | None = None,
+        session: Any | None = None,
+        timeout: float | None = None,
+        middlewares: list[ToolMiddlewareBase] | None = None,
+    ) -> None:
+        """Initialize the MCPTool.
+
+        Args:
+            mcp_name (`str`):
+                The name of the MCP server instance.
+            tool (`mcp.types.Tool`):
+                The MCP tool definition.
+            client_gen (`Callable[..., _AsyncGeneratorContextManager[Any]] \
+            | None`, optional):
+                The MCP client generator function for stateless clients.
+                Either this or ``session`` must be provided.
+            session (`mcp.ClientSession | None`, optional):
+                The MCP client session for stateful clients.
+                Either this or ``client_gen`` must be provided.
+            timeout (`float | None`, optional):
+                The timeout in seconds for tool execution.
+            middlewares (`list[ToolMiddlewareBase] | None`, optional):
+                Tool middlewares wrapping the tool execution.
+        """
+        super().__init__(middlewares=middlewares)
+        self.mcp_name = mcp_name
+
+        # LLM providers enforce ^[a-zA-Z0-9_-]+$ on tool names.
+        # mcp_name is validated in MCPClient.model_post_init;
+        # tool.name comes from the MCP server and may contain dots,
+        # colons, etc. — replace illegal chars with "x" (not "_")
+        # to avoid collisions with the "__" separator.
+        # self._tool.name retains the original for server-side calls.
+        sanitized_tool = re.sub(r"[^a-zA-Z0-9_-]", "x", tool.name)
+        self.name = f"mcp__{mcp_name}__{sanitized_tool}"
+        if sanitized_tool != tool.name:
+            logger.debug(
+                "MCP tool name sanitized: '%s' -> '%s'.",
+                tool.name,
+                self.name,
+            )
+
+        self.description = tool.description or ""
+
+        # Preserve the full inputSchema (including $defs, anyOf, oneOf, etc.)
+        # rather than only copying "properties" and "required", which would
+        # silently drop any nested type definitions that the LLM needs to
+        # resolve $ref pointers.
+        _schema = dict(tool.inputSchema) if tool.inputSchema else {}
+        _schema.setdefault("type", "object")
+        _schema.setdefault("properties", {})
+        _schema.setdefault("required", [])
+        self.input_schema = _schema
+
+        # By default
+        self.is_concurrency_safe = False
+        self.is_external_tool = False
+
+        # Extract is_read_only from MCP tool annotations
+        self.is_read_only = False
+        if tool.annotations and hasattr(tool.annotations, "readOnlyHint"):
+            self.is_read_only = tool.annotations.readOnlyHint or False
+
+        # Store MCP tool and connection info
+        self._tool = tool
+        self._client_gen = client_gen
+        self._session = session
+
+        if timeout:
+            self._timeout = timedelta(seconds=timeout)
+        else:
+            self._timeout = None
+
+        # Validate that either client_gen or session is provided
+        if (client_gen is None and session is None) or (
+            client_gen is not None and session is not None
+        ):
+            raise ValueError(
+                "Either client_gen or session must be provided, but not both.",
+            )
+
+    async def check_permissions(
+        self,
+        *_args: Any,
+        **_kwargs: Any,
+    ) -> PermissionDecision:
+        """Check permissions for the MCP tool usage.
+
+        Default implementation allows all operations.
+
+        Returns:
+            `PermissionDecision`:
+                Permission decision (default: ask for confirmation).
+        """
+        if self.is_read_only:
+            return PermissionDecision(
+                behavior=PermissionBehavior.ALLOW,
+                message="This is a read-only MCP tool. Allowing execution.",
+            )
+        return PermissionDecision(
+            behavior=PermissionBehavior.ASK,
+            message="MCP tools must be explicitly allowed by the user.",
+        )
+
+    async def call(
+        self,
+        **kwargs: Any,
+    ) -> ToolChunk:
+        """Invoke the MCP tool and convert the result to ToolChunk.
+
+        Args:
+            **kwargs: Arguments to pass to the MCP tool.
+
+        Returns:
+            `ToolChunk`: The converted tool execution result.
+        """
+
+        # Call the MCP tool
+        if self._client_gen:
+            # Stateless client: create temporary session
+            async with self._client_gen() as cli:
+                read_stream, write_stream = cli[0], cli[1]
+                async with ClientSession(read_stream, write_stream) as session:
+                    await session.initialize()
+                    result = await session.call_tool(
+                        self._tool.name,
+                        arguments=kwargs,
+                        read_timeout_seconds=self._timeout,
+                    )
+        else:
+            # Stateful client: use existing session
+            result = await self._session.call_tool(
+                self._tool.name,
+                arguments=kwargs,
+                read_timeout_seconds=self._timeout,
+            )
+
+        # Convert MCP result to AgentScope blocks
+        return ToolChunk(
+            content=self._convert_mcp_content_to_blocks(result.content),
+            state=ToolResultState.ERROR
+            if result.isError
+            else ToolResultState.RUNNING,
+        )
+
+    @staticmethod
+    def _convert_mcp_content_to_blocks(
+        mcp_content_blocks: list,
+    ) -> list[TextBlock | DataBlock]:
+        """Convert MCP content to AgentScope blocks.
+
+        Args:
+            mcp_content_blocks (`list`):
+                The MCP content blocks to convert.
+
+        Returns:
+            `list[TextBlock | DataBlock]`: Converted AgentScope blocks.
+        """
+
+        as_content = []
+        for content in mcp_content_blocks:
+            if isinstance(content, mcp.types.TextContent):
+                as_content.append(TextBlock(text=content.text))
+            elif isinstance(
+                content,
+                (mcp.types.ImageContent, mcp.types.AudioContent),
+            ):
+                as_content.append(
+                    DataBlock(
+                        source=Base64Source(
+                            type="base64",
+                            media_type=content.mimeType,
+                            data=content.data,
+                        ),
+                    ),
+                )
+
+            elif isinstance(content, mcp.types.EmbeddedResource):
+                if isinstance(
+                    content.resource,
+                    mcp.types.TextResourceContents,
+                ):
+                    as_content.append(
+                        TextBlock(
+                            text=content.resource.model_dump_json(indent=2),
+                        ),
+                    )
+                else:
+                    logger.error(
+                        "Unsupported EmbeddedResource content type: %s. "
+                        "Skipping this content.",
+                        type(content.resource),
+                    )
+
+            elif isinstance(content, mcp.types.ResourceContents):
+                as_content.append(
+                    DataBlock(
+                        source=URLSource(
+                            media_type=content.mimeType,
+                            url=content.uri,
+                        ),
+                    ),
+                )
+
+            else:
+                logger.warning(
+                    "Unsupported content type: %s. Skipping this content.",
+                    type(content),
+                )
+        return as_content
diff --git a/src/agentscope/tool/_base.py b/src/agentscope/tool/_base.py
new file mode 100644
index 0000000..33cc11b
--- /dev/null
+++ b/src/agentscope/tool/_base.py
@@ -0,0 +1,451 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=unused-argument
+"""The tool protocol in agentscope."""
+import inspect
+import os
+from abc import abstractmethod, ABC
+from pathlib import Path
+from typing import AsyncGenerator, Any, Callable, List
+
+from pydantic import BaseModel
+
+from ._constants import DEFAULT_DANGEROUS_FILES, DEFAULT_DANGEROUS_DIRECTORIES
+from ..permission import (
+    PermissionContext,
+    PermissionDecision,
+    PermissionRule,
+    PermissionBehavior,
+)
+from ._response import ToolChunk
+from ._utils import _remove_title_field
+
+
+class ParamsBase(BaseModel):
+    """A base class for tool parameters that remove the title field from the
+    exported JSON schema.
+    """
+
+    @classmethod
+    def model_json_schema(cls, *args: Any, **kwargs: Any) -> dict:
+        """An override implementation to remove the title field from the
+        exported schema.
+        """
+        return _remove_title_field(super().model_json_schema(*args, **kwargs))
+
+
+class ToolMiddlewareBase(ABC):
+    """Base class for tool middlewares.
+
+    A tool middleware wraps the execution of a tool in an onion fashion: the
+    first registered middleware is the outermost layer and runs its pre-logic
+    before any inner layer, then its post-logic after all inner layers have
+    completed. Subclass this and implement :meth:`on_tool_call` — the signature
+    is already spelled out, so second-party developers only need to fill in the
+    body without reasoning about the wrapping protocol.
+
+    Streaming and non-streaming tools are unified: ``next_handler`` always
+    returns an async generator, so a middleware never needs to know whether the
+    underlying tool yields a stream of chunks or returns a single chunk.
+
+    Example:
+        ```python
+        class LoggingMiddleware(ToolMiddlewareBase):
+            async def on_tool_call(self, tool, input_kwargs, next_handler):
+                print(f"Calling {tool.name} with {input_kwargs}")
+                async for chunk in next_handler(**input_kwargs):
+                    yield chunk
+                print(f"Finished {tool.name}")
+
+        tool = MyTool(middlewares=[LoggingMiddleware()])
+        ```
+    """
+
+    @abstractmethod
+    async def on_tool_call(
+        self,
+        tool: "ToolBase",
+        input_kwargs: dict[str, Any],
+        next_handler: Callable[..., AsyncGenerator[ToolChunk, None]],
+    ) -> AsyncGenerator[ToolChunk, None]:
+        """Intercept a single tool invocation.
+
+        Add pre-/post-logic around ``next_handler``, rewrite the tool inputs by
+        passing modified keyword arguments to ``next_handler``, or transform
+        the yielded chunks.
+
+        Args:
+            tool (`ToolBase`):
+                The tool instance being invoked.
+            input_kwargs (`dict[str, Any]`):
+                The tool's input arguments for this invocation. Pass them on
+                via ``next_handler(**input_kwargs)``; mutate or replace them to
+                change what the inner layers and the tool itself receive.
+            next_handler (`Callable[..., AsyncGenerator[ToolChunk, None]]`):
+                Call it as ``next_handler(**input_kwargs)`` to run the next
+                layer. It always returns an async generator, regardless of
+                whether the underlying tool is streaming or not.
+
+        Yields:
+            `ToolChunk`:
+                The chunks produced by this tool invocation.
+        """
+
+
+class ToolBase(ABC):
+    """The tool protocol."""
+
+    name: str
+    """The name presented to the agent."""
+    description: str
+    """The agent-oriented tool description."""
+    input_schema: dict[str, Any]
+    """The input schema of the tool, following JSON schema format."""
+    is_concurrency_safe: bool
+    """If this tool is concurrency safe."""
+    is_read_only: bool
+    """If this tool is read-only, which will be used in the permission
+    checking."""
+    is_external_tool: bool = False
+    """If this tool is an external tool, which doesn't need to implement the
+    __call__ method and the agent will yield the external tool call event."""
+    is_state_injected: bool = False
+    """If this tool requires agent state to be injected when called. If `True`,
+    the state will be injected by an argument named `_agent_state`. Note your
+    tool should be able to accept such argument.
+    """
+    is_mcp: bool = False
+    """If this tool is an MCP tool, which will be used in the permission"""
+    mcp_name: str | None = None
+    """The name of the MCP server this tool belongs to, which is required if
+    this tool is an MCP tool."""
+
+    # Class attributes for dangerous path checking
+    dangerous_files: list[str] = DEFAULT_DANGEROUS_FILES
+    """List of dangerous files that should be protected from auto-editing."""
+    dangerous_directories: list[str] = DEFAULT_DANGEROUS_DIRECTORIES
+    """List of dangerous directories that should be protected from
+    auto-editing."""
+
+    def __init__(
+        self,
+        middlewares: List["ToolMiddlewareBase"] | None = None,
+    ) -> None:
+        """Initialize the tool with optional middlewares.
+
+        Args:
+            middlewares (`List[ToolMiddlewareBase] | None`, optional):
+                A list of :class:`ToolMiddlewareBase` instances wrapping the
+                tool execution in an onion fashion. Defaults to an empty list.
+        """
+        self._middlewares: List["ToolMiddlewareBase"] = (
+            middlewares if middlewares is not None else []
+        )
+
+    async def call(
+        self,
+        *args: Any,
+        **kwargs: Any,
+    ) -> ToolChunk | AsyncGenerator[ToolChunk, None]:
+        """Execute the tool logic.
+
+        This is the new override point for tool implementations.
+        Subclasses should override this method instead of
+        :meth:`__call__`.  The base implementation raises
+        :exc:`NotImplementedError` for non-external tools and
+        :exc:`RuntimeError` for external tools.
+
+        Args:
+            **kwargs: Tool input arguments.
+
+        Returns:
+            `ToolChunk | AsyncGenerator[ToolChunk, None]`:
+                A single :class:`~agentscope.tool.ToolChunk` or an
+                async generator that yields them.
+        """
+        if not self.is_external_tool:
+            raise NotImplementedError(
+                f"{self.__class__.__name__} does not implement call",
+            )
+
+        raise RuntimeError(
+            f"{self.__class__.__name__} is an external tool and should not "
+            f"be called directly",
+        )
+
+    async def __call__(
+        self,
+        *args: Any,
+        **kwargs: Any,
+    ) -> ToolChunk | AsyncGenerator[ToolChunk, None]:
+        """Invoke the tool, layering any registered middlewares around
+        :meth:`call`.
+
+        Tools are always invoked with keyword arguments only. ``*args`` is
+        accepted in the signature solely to stay Liskov-compatible with
+        subclasses that override ``__call__`` with their own positional
+        parameters; any positional argument actually passed here is rejected
+        (raising :exc:`TypeError`) so it fails loudly instead of being silently
+        dropped.
+
+        Middlewares are applied in an onion fashion: the first registered
+        middleware is the outermost layer and runs its pre-logic before
+        any inner layers, then its post-logic after all inner layers
+        have completed.
+        """
+        if args:
+            raise TypeError(
+                f"{type(self).__name__} must be called with keyword arguments "
+                f"only, but got {len(args)} positional argument(s).",
+            )
+        # ``getattr`` with a default so the no-middleware path keeps working
+        # even if a subclass overrides ``__init__`` without calling
+        # ``super().__init__()``.
+        middlewares = getattr(self, "_middlewares", [])
+        if not middlewares:
+            if inspect.isasyncgenfunction(self.call):
+                return self.call(**kwargs)
+            return await self.call(**kwargs)
+
+        async def execute_chain(
+            index: int = 0,
+            **chain_kwargs: Any,
+        ) -> AsyncGenerator[ToolChunk, None]:
+            """Execute the tool middleware chain."""
+            if index >= len(middlewares):
+                # Innermost layer: run the tool's own ``call``. ``call`` is
+                # always async but comes in two shapes — an async generator
+                # function (e.g. ``Bash``) or a coroutine returning a single
+                # ``ToolChunk`` / an async generator (e.g. ``FunctionTool``).
+                # Normalize both into a single stream so middlewares never have
+                # to distinguish them.
+                if inspect.isasyncgenfunction(self.call):
+                    async for chunk in self.call(**chain_kwargs):
+                        yield chunk
+                else:
+                    result = await self.call(**chain_kwargs)
+                    if isinstance(result, AsyncGenerator):
+                        async for chunk in result:
+                            yield chunk
+                    else:
+                        yield result
+            else:
+                mw = middlewares[index]
+                input_kwargs = dict(chain_kwargs)
+
+                async def next_handler(
+                    **kw: Any,
+                ) -> AsyncGenerator[ToolChunk, None]:
+                    async for chunk in execute_chain(index + 1, **kw):
+                        yield chunk
+
+                async for chunk in mw.on_tool_call(
+                    tool=self,
+                    input_kwargs=input_kwargs,
+                    next_handler=next_handler,
+                ):
+                    yield chunk
+
+        return execute_chain(**kwargs)
+
+    @abstractmethod
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        """Check permissions for the tool usage."""
+
+    async def check_read_only(
+        self,
+        tool_input: dict[str, Any],
+    ) -> bool:
+        """Decide whether this specific invocation is read-only.
+
+        Returns the static :attr:`is_read_only` attribute by default.
+        Subclasses with input-dependent semantics (e.g. ``Bash``) should
+        override this to inspect ``tool_input`` — for example, ``Bash`` is
+        statically marked as not read-only but ``ls -a`` is in fact read-only.
+
+        Should be cheap — the permission engine may call this before the
+        full :meth:`check_permissions` flow.
+
+        Args:
+            tool_input (`dict[str, Any]`):
+                The tool input data for this invocation.
+
+        Returns:
+            `bool`:
+                ``True`` if this invocation is read-only, ``False`` otherwise.
+        """
+        return self.is_read_only
+
+    async def match_rule(
+        self,
+        rule_content: str | None,
+        tool_input: dict[str, Any],
+    ) -> bool:
+        """Check if a permission rule matches the tool input.
+
+        .. note:: This is an optional method. A rule with no content (``None``)
+        is a tool-name-level rule that matches every invocation; a rule
+        with content requires the tool to override this method with its
+        own matching logic, otherwise it returns ``False``.
+
+        This means:
+        - ``_FunctionTool`` and ``MCPTool`` (which do not override this)
+          can still be controlled at the tool-name level via rules like
+          ``{"tool_name": "my_tool", "rule_content": None}``.
+        - Specific tools (Bash, Read, Write, Edit, Glob, Grep) override
+          this method to support fine-grained pattern matching.
+
+        Args:
+            rule_content (`str | None`):
+                The rule pattern to match. ``None`` means "match all
+                invocations of this tool" (tool-name-level rule).
+            tool_input (`dict[str, Any]`):
+                The tool input data
+
+        Returns:
+            `bool`:
+                True if the rule matches, False otherwise
+        """
+        # None rule_content = tool-name-level rule, matches everything
+        return rule_content is None
+
+    async def generate_suggestions(
+        self,
+        tool_input: dict[str, Any],
+    ) -> List[PermissionRule]:
+        """Generate suggested permission rules for the tool input.
+
+        .. note:: Suggest a single tool-name-level rule (``rule_content=None``)
+        that allows all invocations of this tool. Tools can override this to
+        provide finer-grained suggestions.
+
+        For example:
+        - File tools (Read/Write/Edit): suggest a glob pattern covering the
+          parent directory (e.g., "src/main.py" -> "src/**")
+        - Bash: suggest command prefix patterns (e.g., "git commit -m 'xxx'"
+          -> "git commit:*")
+        - Grep/Glob: suggest patterns based on search paths
+
+        Args:
+            tool_input (`dict[str, Any]`):
+                The tool input data
+
+        Returns:
+            `List[PermissionRule]`:
+                List of suggested permission rules (usually 1, max 5 for
+                compound operations)
+        """
+        return [
+            PermissionRule(
+                tool_name=self.name,
+                rule_content=None,
+                behavior=PermissionBehavior.ALLOW,
+                source="suggested",
+            ),
+        ]
+
+    def _path_in_allowed_working_path(
+        self,
+        file_path: str,
+        context: PermissionContext,
+    ) -> bool:
+        """Check if a file path is within any allowed working directory.
+
+        A "working directory" is the process's current directory plus any
+        entries in :attr:`PermissionContext.working_directories`. Paths
+        are compared via :func:`os.path.realpath` so that aliases like
+        macOS's ``/tmp`` → ``/private/tmp`` and symlinked working
+        directories compare equal on both sides.
+
+        Used by tools that conditionally auto-allow file operations in
+        :attr:`PermissionMode.ACCEPT_EDITS` (e.g. Write, Edit, and the
+        filesystem-command branch of Bash).
+
+        Args:
+            file_path (`str`):
+                The file path to check.
+            context (`PermissionContext`):
+                The permission context containing the working directories.
+
+        Returns:
+            `bool`:
+                True if ``file_path`` is within any allowed working
+                directory.
+        """
+        current_dir = os.getcwd()
+        additional_dirs = list(context.working_directories.keys())
+        all_working_dirs = [current_dir] + additional_dirs
+
+        abs_file_path = os.path.realpath(os.path.expanduser(file_path))
+
+        for working_dir in all_working_dirs:
+            abs_working_dir = os.path.realpath(
+                os.path.expanduser(working_dir),
+            )
+            try:
+                os.path.relpath(abs_file_path, abs_working_dir)
+                if (
+                    abs_file_path.startswith(abs_working_dir + os.sep)
+                    or abs_file_path == abs_working_dir
+                ):
+                    return True
+            except ValueError:
+                # On Windows, relpath raises ValueError if paths are on
+                # different drives.
+                continue
+
+        return False
+
+    def _is_dangerous_path(self, file_path: str) -> bool:
+        """Check if a file path is dangerous (sensitive file or directory).
+
+        A path is considered dangerous if:
+        1. The filename matches a dangerous file (e.g., .bashrc, .gitconfig)
+        2. Any path segment matches a dangerous directory (e.g., .git, .ssh)
+
+        Case-insensitive matching is used to prevent bypasses on
+        case-insensitive filesystems (macOS, Windows).
+
+        Args:
+            file_path (`str`):
+                The file path to check
+
+        Returns:
+            `bool`:
+                True if the path is dangerous and should require explicit
+                permission
+
+        Example:
+            >>> self._is_dangerous_path("/home/user/.bashrc")
+            True
+            >>> self._is_dangerous_path("/home/user/.git/config")
+            True
+            >>> self._is_dangerous_path("/home/user/project/main.py")
+            False
+        """
+
+        # Normalize path
+        abs_path = os.path.abspath(os.path.expanduser(file_path))
+
+        # Split path into segments
+        path_parts = Path(abs_path).parts
+        path_parts_lower = [p.lower() for p in path_parts]
+
+        # Check if filename matches dangerous files (case-insensitive)
+        filename = os.path.basename(abs_path)
+        filename_lower = filename.lower()
+        for dangerous_file in self.dangerous_files:
+            if filename_lower == dangerous_file.lower():
+                return True
+
+        # Check if any path segment matches dangerous directories
+        # (case-insensitive)
+        for dangerous_dir in self.dangerous_directories:
+            dangerous_dir_lower = dangerous_dir.lower()
+            if dangerous_dir_lower in path_parts_lower:
+                return True
+
+        return False
diff --git a/src/agentscope/tool/_builtin/__init__.py b/src/agentscope/tool/_builtin/__init__.py
new file mode 100644
index 0000000..5e63a95
--- /dev/null
+++ b/src/agentscope/tool/_builtin/__init__.py
@@ -0,0 +1,26 @@
+# -*- coding: utf-8 -*-
+"""The builtin tools in agentscope."""
+
+from ._backend import BackendBase, ExecResult, LocalBackend
+from ._bash import Bash
+from ._edit import Edit
+from ._glob import Glob
+from ._grep import Grep
+from ._meta import ResetTools
+from ._read import Read
+from ._skill import SkillViewer
+from ._write import Write
+
+__all__ = [
+    "ResetTools",
+    "SkillViewer",
+    "Bash",
+    "Edit",
+    "Glob",
+    "Grep",
+    "Read",
+    "Write",
+    "BackendBase",
+    "LocalBackend",
+    "ExecResult",
+]
diff --git a/src/agentscope/tool/_builtin/_backend.py b/src/agentscope/tool/_builtin/_backend.py
new file mode 100644
index 0000000..a777312
--- /dev/null
+++ b/src/agentscope/tool/_builtin/_backend.py
@@ -0,0 +1,747 @@
+# -*- coding: utf-8 -*-
+"""Backend abstraction for builtin tools.
+
+Provides a :class:`BackendBase` abstract base class that captures the
+core I/O primitives shared across all six builtin tools (Bash, Read,
+Write, Edit, Grep, Glob).
+
+Every backend implements exactly **three** abstract primitives whose
+mechanism genuinely differs per environment:
+
+* :meth:`BackendBase.exec_shell` — run a program from an argv list
+  (no shell; callers needing shell features wrap with ``sh -c``).
+* :meth:`BackendBase.read_file` — read raw bytes.
+* :meth:`BackendBase.write_file` — write raw bytes.
+
+All remaining filesystem operations (``file_exists``, ``is_dir``,
+``list_dir``, ``stat_mtime``, ``delete_path``) are derived on the base
+class from ``exec_shell`` and work out-of-the-box for any remote
+backend.  A backend that has a cheaper native path (e.g.
+:class:`LocalBackend` using ``os.*``) simply overrides them.
+
+Concrete implementations:
+
+* :class:`LocalBackend` — default; uses ``asyncio`` subprocesses,
+  ``aiofiles``, and ``os.*`` for host-local I/O.  Injected automatically
+  when no explicit backend is given.
+* ``DockerBackend`` — uses ``aiodocker`` exec / archive APIs.
+* ``E2BBackend`` — uses the E2B SDK ``commands`` / ``files`` APIs.
+
+By accepting a ``BackendBase`` parameter, each builtin tool can
+operate identically in local, Docker, and E2B workspaces without any
+workspace-specific branching inside the tool code itself.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import posixpath
+import shlex
+import shutil
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from types import ModuleType
+from typing import Any
+
+import aiofiles
+
+# ── data class ─────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True, slots=True)
+class ExecResult:
+    """Result of running a shell command via a backend.
+
+    Attributes:
+        exit_code: Process exit code.  ``-1`` conventionally indicates
+            an internal failure (timeout, connection error, …).
+        stdout: Raw bytes captured from standard output.
+        stderr: Raw bytes captured from standard error.
+    """
+
+    exit_code: int
+    stdout: bytes
+    stderr: bytes
+
+    def ok(self) -> bool:
+        """Whether the command exited successfully.
+
+        Returns:
+            `bool`:
+                ``True`` iff the command exited with code ``0``.
+        """
+        return self.exit_code == 0
+
+
+# ── helpers ────────────────────────────────────────────────────────────
+
+
+def _normalize_newlines(text: str) -> str:
+    """Normalize Windows/old-Mac line endings to ``\\n``.
+
+    Converts ``\\r\\n`` (Windows) and lone ``\\r`` (classic Mac) to a
+    single ``\\n``.  Builtin tools read files as raw bytes (so binary
+    payloads survive intact); when the bytes are decoded as text for
+    line-based caching, editing, or matching, the line endings must be
+    normalized so that content written on Windows behaves identically to
+    content written on POSIX.
+
+    Args:
+        text (`str`):
+            Decoded file contents.
+
+    Returns:
+        `str`:
+            The text with all line endings collapsed to ``\\n``.
+    """
+    return text.replace("\r\n", "\n").replace("\r", "\n")
+
+
+# ── base class ─────────────────────────────────────────────────────────
+
+
+class BackendBase(ABC):
+    """Filesystem + subprocess interface consumed by builtin tools.
+
+    Subclasses must implement three abstract primitives — ``exec_shell``,
+    ``read_file``, and ``write_file`` — which are the only operations
+    whose mechanism genuinely differs per environment.  The remaining
+    filesystem helpers are implemented here on top of ``exec_shell`` and
+    work for any backend whose shell is POSIX-like; a backend with a
+    cheaper native path may override them (see :class:`LocalBackend`).
+    """
+
+    #: Path-manipulation module whose semantics match the backend's
+    #: environment.  Used by :meth:`join_path`, :meth:`dirname`,
+    #: :meth:`isabs`, :meth:`normpath`, and :meth:`abspath` to ensure
+    #: correct behavior when the host OS and the backend OS differ
+    #: (e.g. a Windows host driving a Linux Docker container).
+    #:
+    #: Defaults to :mod:`posixpath`, which is correct for any backend
+    #: whose environment is Linux/macOS (Docker, E2B, …).  Subclasses
+    #: targeting a different environment override this attribute, e.g.
+    #: :class:`LocalBackend` sets it to :mod:`os.path`, and a future
+    #: Windows-container backend would set it to :mod:`ntpath`.
+    #:
+    #: .. important::
+    #:
+    #:     Only **pure string operations** on this module are safe to
+    #:     call (``join``, ``split``, ``dirname``, ``basename``,
+    #:     ``normpath``, ``isabs``, ``splitext``, ``splitdrive``, …).
+    #:
+    #:     Do **not** call functions that touch the filesystem or
+    #:     environment variables — ``exists``, ``isfile``, ``isdir``,
+    #:     ``getmtime``, ``realpath``, ``expanduser``, ``expandvars``,
+    #:     and parameterless ``abspath`` — because those read the
+    #:     **host** process's filesystem / ``$HOME`` / ``cwd``, which
+    #:     is meaningless (and a silent bug) for remote backends.  Use
+    #:     the async I/O methods on the backend instead
+    #:     (:meth:`file_exists`, :meth:`is_dir`, :meth:`stat_mtime`,
+    #:     …) or the :meth:`abspath` wrapper below, which requires an
+    #:     explicit ``cwd`` argument.
+    _path_module: ModuleType = posixpath
+
+    # ── path manipulation helpers (pure string ops) ────────────────
+
+    def join_path(self, path: str, *paths: str) -> str:
+        """Join one or more path components using the backend's separator.
+
+        Args:
+            path (`str`):
+                The first path component.
+            *paths (`str`):
+                Additional components to join onto ``path``.
+
+        Returns:
+            `str`:
+                The joined path, using the backend environment's path
+                separator.
+        """
+        return self._path_module.join(path, *paths)
+
+    def dirname(self, path: str) -> str:
+        """Return the directory component of ``path``.
+
+        Args:
+            path (`str`):
+                A path inside the backend's environment.
+
+        Returns:
+            `str`:
+                Everything up to (but not including) the last path
+                separator. Empty string if ``path`` has no separator.
+        """
+        return self._path_module.dirname(path)
+
+    def basename(self, path: str) -> str:
+        """Return the final component of ``path``.
+
+        Args:
+            path (`str`):
+                A path inside the backend's environment.
+
+        Returns:
+            `str`:
+                Everything after the last path separator. Empty string
+                if ``path`` ends with a separator.
+        """
+        return self._path_module.basename(path)
+
+    def isabs(self, path: str) -> bool:
+        """Return ``True`` if ``path`` is absolute in the backend.
+
+        Args:
+            path (`str`):
+                A path inside the backend's environment.
+
+        Returns:
+            `bool`:
+                ``True`` iff ``path`` is absolute under the backend
+                environment's path semantics.
+        """
+        return self._path_module.isabs(path)
+
+    def normpath(self, path: str) -> str:
+        """Normalize ``path`` (collapse ``..``, ``.``, duplicate seps).
+
+        Pure string operation — does not touch the filesystem.
+
+        Args:
+            path (`str`):
+                A path inside the backend's environment.
+
+        Returns:
+            `str`:
+                The normalized path.
+        """
+        return self._path_module.normpath(path)
+
+    def abspath(self, path: str, *, cwd: str) -> str:
+        """Return an absolute, normalized version of ``path``.
+
+        Unlike :func:`os.path.abspath`, this helper **never** reads
+        the host process's working directory: when ``path`` is
+        relative it is joined with the explicitly supplied ``cwd``,
+        which must itself be a path that is meaningful inside the
+        backend's environment.  This avoids the silent bug where the
+        host's ``os.getcwd()`` leaks into paths that will actually be
+        used on a remote backend.
+
+        Args:
+            path (`str`):
+                A path inside the backend's environment.
+            cwd (`str`):
+                Directory to resolve a relative ``path`` against.
+                Ignored when ``path`` is already absolute.
+
+        Returns:
+            `str`:
+                An absolute, normalized path.
+        """
+        if self._path_module.isabs(path):
+            return self._path_module.normpath(path)
+        return self._path_module.normpath(
+            self._path_module.join(cwd, path),
+        )
+
+    # ── abstract primitives ────────────────────────────────────────
+
+    @abstractmethod
+    async def exec_shell(
+        self,
+        command: list[str],
+        *,
+        cwd: str | None = None,
+        timeout: float | None = None,
+    ) -> ExecResult:
+        """Run a program directly from an argument vector.
+
+        *command* is an executable followed by its arguments — it is
+        **not** passed through a shell, so callers never have to quote
+        or escape arguments and there is no platform-specific quoting
+        bug. This makes the primitive portable to Windows, where POSIX
+        single-quote escaping (``shlex.quote``) is not understood by
+        ``cmd.exe``.
+
+        Callers that genuinely need shell features (pipes, redirects,
+        ``&&``) must wrap their command line explicitly, e.g.
+        ``["/bin/sh", "-c", command_line]``.
+
+        Args:
+            command (`list[str]`):
+                Executable path/name followed by its arguments.
+            cwd (`str | None`, optional):
+                Working directory to run the command in. When ``None``
+                the backend's default working directory is used.
+            timeout (`float | None`, optional):
+                Maximum number of seconds to wait. When ``None`` the
+                call waits indefinitely. On timeout the result carries
+                an ``exit_code`` of ``-1``.
+
+        Returns:
+            `ExecResult`:
+                The captured exit code, stdout, and stderr.
+        """
+
+    @abstractmethod
+    async def read_file(self, path: str) -> bytes:
+        """Read the full contents of ``path`` as raw bytes.
+
+        Args:
+            path (`str`):
+                Path to the file inside the backend's environment.
+
+        Returns:
+            `bytes`:
+                The raw file contents.
+        """
+
+    @abstractmethod
+    async def write_file(self, path: str, data: bytes) -> None:
+        """Write ``data`` to ``path``, creating parent directories.
+
+        Args:
+            path (`str`):
+                Destination path inside the backend's environment.
+            data (`bytes`):
+                The raw bytes to write.
+        """
+
+    # ── derived filesystem ops (shell-based defaults) ──────────────
+
+    async def getcwd(self) -> str:
+        """Return the backend environment's current working directory.
+
+        This is the directory that bare ``exec_shell`` invocations
+        (those with ``cwd=None``) execute in.  Tools should call this
+        — instead of :func:`os.getcwd` — whenever they need a default
+        path that is meaningful inside the backend, because the host
+        process's cwd is meaningless for remote backends
+        (Docker / E2B).
+
+        The default implementation runs ``pwd`` via :meth:`exec_shell`,
+        which works for any POSIX-like backend.  Backends with cheaper
+        native access (e.g. :class:`LocalBackend`, or remote backends
+        that already track their workdir) should override it.
+
+        Returns:
+            `str`:
+                The backend's current working directory.
+        """
+        result = await self.exec_shell(["pwd"])
+        return result.stdout.decode("utf-8", errors="replace").strip()
+
+    async def expanduser(self, path: str) -> str:
+        """Expand a leading ``~`` / ``~/`` to the backend's home directory.
+
+        Tools should call this — instead of :func:`os.path.expanduser`
+        — whenever they need to expand ``~`` in a path that lives
+        inside the backend's environment, because the host process's
+        ``$HOME`` is meaningless for remote backends.
+
+        The default implementation queries ``$HOME`` via
+        :meth:`exec_shell` (POSIX-only).  Only the leading ``~`` /
+        ``~/foo`` form is expanded; ``~user/...`` is not supported by
+        the default and is returned unchanged.  Backends with cheaper
+        native access should override (e.g. :class:`LocalBackend`).
+
+        Args:
+            path (`str`):
+                A path inside the backend's environment, possibly
+                starting with ``~``.
+
+        Returns:
+            `str`:
+                ``path`` with a leading ``~`` / ``~/`` expanded.  If
+                ``path`` does not start with ``~``, or starts with
+                ``~user`` (unsupported), it is returned unchanged.
+        """
+        if not path or path[0] != "~":
+            return path
+        # ``~user/...`` form — not supported by the default impl.
+        if len(path) > 1 and path[1] not in ("/", self._path_module.sep):
+            return path
+        result = await self.exec_shell(["printenv", "HOME"])
+        home = result.stdout.decode("utf-8", errors="replace").strip()
+        if not home:
+            return path
+        return home + path[1:]
+
+    async def file_exists(self, path: str) -> bool:
+        """Return ``True`` if ``path`` exists (file or directory).
+
+        Args:
+            path (`str`):
+                Path to test inside the backend's environment.
+
+        Returns:
+            `bool`:
+                ``True`` if the path exists, ``False`` otherwise.
+        """
+        result = await self.exec_shell(["test", "-e", path])
+        return result.ok()
+
+    async def is_dir(self, path: str) -> bool:
+        """Return ``True`` if ``path`` is an existing directory.
+
+        Args:
+            path (`str`):
+                Path to test inside the backend's environment.
+
+        Returns:
+            `bool`:
+                ``True`` if the path is an existing directory.
+        """
+        result = await self.exec_shell(["test", "-d", path])
+        return result.ok()
+
+    async def list_dir(
+        self,
+        path: str,
+        *,
+        recursive: bool = False,
+    ) -> list[str]:
+        """List entries under ``path``.
+
+        Output is NUL-delimited (``find -print0`` / ``-printf '%f\\0'``)
+        and split on ``\\0`` so that file names containing spaces or
+        newlines are handled correctly.  ``find -printf`` is a GNU
+        extension; backends running on non-GNU userlands should override
+        this method.
+
+        Args:
+            path (`str`):
+                Directory to list inside the backend's environment.
+            recursive (`bool`, optional):
+                When ``True``, return all files underneath ``path`` as
+                paths (like ``find path -type f``). When ``False``
+                (default), return the immediate children's base names
+                (like ``os.listdir``).
+
+        Returns:
+            `list[str]`:
+                The matched entries, or an empty list if ``path`` does
+                not exist or cannot be listed.
+        """
+        if recursive:
+            command = ["find", path, "-type", "f", "-print0"]
+        else:
+            command = [
+                "find",
+                path,
+                "-mindepth",
+                "1",
+                "-maxdepth",
+                "1",
+                "-printf",
+                "%f\\0",
+            ]
+        result = await self.exec_shell(command)
+        if not result.ok():
+            return []
+        return [
+            part.decode("utf-8", errors="surrogateescape")
+            for part in result.stdout.split(b"\0")
+            if part
+        ]
+
+    async def stat_mtime(self, path: str) -> float | None:
+        """Return the modification time of ``path``, or ``None``.
+
+        Tries GNU ``stat -c %Y`` first and falls back to BSD
+        ``stat -f %m`` so the same call works across coreutils and
+        BSD/macOS userlands.  The two attempts are combined with ``||``,
+        so this default wraps a ``sh -c`` script; backends without a
+        POSIX shell (e.g. :class:`LocalBackend`) override it.
+
+        Args:
+            path (`str`):
+                Path to stat inside the backend's environment.
+
+        Returns:
+            `float | None`:
+                The modification time as a POSIX timestamp, or ``None``
+                if the path does not exist or cannot be stat'd.
+        """
+        quoted = shlex.quote(path)
+        script = (
+            f"stat -c %Y {quoted} 2>/dev/null || "
+            f"stat -f %m {quoted} 2>/dev/null"
+        )
+        result = await self.exec_shell(["sh", "-c", script])
+        if not result.ok():
+            return None
+        try:
+            return float(
+                result.stdout.decode("utf-8", errors="replace").strip(),
+            )
+        except ValueError:
+            return None
+
+    async def delete_path(self, path: str) -> None:
+        """Delete ``path`` (file or directory tree).
+
+        If ``path`` does not exist the call is a silent no-op (like
+        ``rm -rf``).  Handles both files and directories (recursively).
+
+        Args:
+            path (`str`):
+                Path to delete inside the backend's environment.
+        """
+        await self.exec_shell(["rm", "-rf", path])
+
+
+# ── local backend ──────────────────────────────────────────────────────
+
+
+def _subprocess_creation_kwargs() -> dict[str, Any]:
+    """Return platform-specific subprocess creation options.
+
+    Returns:
+        `dict[str, Any]`:
+            Extra keyword arguments for ``create_subprocess_shell``.
+            Empty on POSIX; on Windows it sets ``creationflags`` to
+            suppress a console window.
+    """
+    if os.name != "nt":
+        return {}
+
+    import subprocess
+
+    return {
+        "creationflags": getattr(
+            subprocess,
+            "CREATE_NO_WINDOW",
+            0x08000000,
+        ),
+    }
+
+
+class LocalBackend(BackendBase):
+    """Host-local :class:`BackendBase` implementation.
+
+    Uses ``asyncio.create_subprocess_exec``, ``aiofiles``, and the
+    ``os`` module.  This is the default backend injected when no
+    explicit one is given to a builtin tool.  Commands are spawned
+    directly from their argument vector (no shell), which avoids the
+    POSIX-vs-``cmd.exe`` quoting mismatch and makes the backend work on
+    Windows.  The derived filesystem helpers are overridden with native
+    ``os.*`` calls — faster and more robust than shelling out, and
+    portable to Windows where ``test`` / ``find`` / ``stat`` are
+    unavailable.
+    """
+
+    # Use the host OS's path semantics (Windows or POSIX) instead of
+    # the base class default (``posixpath``), so path helpers behave
+    # correctly when running on a Windows host.
+    _path_module = os.path
+
+    async def exec_shell(
+        self,
+        command: list[str],
+        *,
+        cwd: str | None = None,
+        timeout: float | None = None,
+    ) -> ExecResult:
+        """Run a program via ``asyncio.create_subprocess_exec``.
+
+        The program is spawned directly from *command* without an
+        intervening shell, so no argument quoting is required and the
+        same code path works on POSIX and Windows.
+
+        Args:
+            command (`list[str]`):
+                Executable path/name followed by its arguments.
+            cwd (`str | None`, optional):
+                Working directory for the subprocess. When ``None`` the
+                current process working directory is used.
+            timeout (`float | None`, optional):
+                Maximum number of seconds to wait before the process is
+                killed and an ``exit_code`` of ``-1`` is returned.
+
+        Returns:
+            `ExecResult`:
+                The captured exit code, stdout, and stderr. If the
+                executable cannot be found or spawned, ``exit_code`` is
+                ``127`` (matching a shell's "command not found"), with
+                the OS error message on stderr.
+        """
+        kwargs = _subprocess_creation_kwargs()
+        if cwd is not None:
+            kwargs["cwd"] = cwd
+
+        try:
+            process = await asyncio.create_subprocess_exec(
+                *command,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                **kwargs,
+            )
+        except (FileNotFoundError, NotADirectoryError, OSError) as exc:
+            # The executable could not be found or spawned. A shell would
+            # have returned 127 ("command not found"); mirror that so
+            # callers see a normal non-zero ExecResult instead of an
+            # exception.
+            return ExecResult(
+                exit_code=127,
+                stdout=b"",
+                stderr=str(exc).encode("utf-8"),
+            )
+
+        try:
+            stdout, stderr = await asyncio.wait_for(
+                process.communicate(),
+                timeout=timeout,
+            )
+        except asyncio.TimeoutError:
+            process.kill()
+            await process.communicate()
+            return ExecResult(exit_code=-1, stdout=b"", stderr=b"timed out")
+
+        return ExecResult(
+            exit_code=process.returncode or 0,
+            stdout=stdout,
+            stderr=stderr,
+        )
+
+    async def read_file(self, path: str) -> bytes:
+        """Read a local file as raw bytes.
+
+        Args:
+            path (`str`):
+                Path to the local file.
+
+        Returns:
+            `bytes`:
+                The raw file contents.
+        """
+        async with aiofiles.open(path, mode="rb") as f:
+            return await f.read()
+
+    async def write_file(self, path: str, data: bytes) -> None:
+        """Write *data* to a local file, creating parent dirs.
+
+        Args:
+            path (`str`):
+                Destination path on the local filesystem.
+            data (`bytes`):
+                The raw bytes to write.
+        """
+        parent = os.path.dirname(path)
+        if parent:
+            os.makedirs(parent, exist_ok=True)
+        async with aiofiles.open(path, mode="wb") as f:
+            await f.write(data)
+
+    async def getcwd(self) -> str:
+        """Return the host process's current working directory.
+
+        Returns:
+            `str`:
+                ``os.getcwd()`` — avoids spawning a ``pwd`` subprocess.
+        """
+        return os.getcwd()
+
+    async def expanduser(self, path: str) -> str:
+        """Expand ``~`` using the host process's ``$HOME``.
+
+        Args:
+            path (`str`):
+                A local path, possibly starting with ``~``.
+
+        Returns:
+            `str`:
+                ``os.path.expanduser(path)`` — avoids spawning a
+                subprocess.
+        """
+        return os.path.expanduser(path)
+
+    async def file_exists(self, path: str) -> bool:
+        """Check if a local path exists.
+
+        Args:
+            path (`str`):
+                Path to test.
+
+        Returns:
+            `bool`:
+                ``True`` if the path exists.
+        """
+        return os.path.exists(path)
+
+    async def is_dir(self, path: str) -> bool:
+        """Check if a local path is a directory.
+
+        Args:
+            path (`str`):
+                Path to test.
+
+        Returns:
+            `bool`:
+                ``True`` if the path is an existing directory.
+        """
+        return os.path.isdir(path)
+
+    async def list_dir(
+        self,
+        path: str,
+        *,
+        recursive: bool = False,
+    ) -> list[str]:
+        """List local directory entries.
+
+        Mirrors the base contract using native ``os`` calls.
+
+        Args:
+            path (`str`):
+                Directory to list.
+            recursive (`bool`, optional):
+                When ``True``, return file paths underneath ``path``
+                (``os.walk``). When ``False`` (default), return the
+                immediate children's base names (``os.listdir``).
+
+        Returns:
+            `list[str]`:
+                The matched entries.
+        """
+        if recursive:
+            results: list[str] = []
+            for root, _dirs, files in os.walk(path):
+                for f in files:
+                    results.append(os.path.join(root, f))
+            return results
+        return os.listdir(path)
+
+    async def stat_mtime(self, path: str) -> float | None:
+        """Return the modification time of a local file.
+
+        Args:
+            path (`str`):
+                Path to stat.
+
+        Returns:
+            `float | None`:
+                The modification time as a POSIX timestamp, or ``None``
+                if the path does not exist or cannot be stat'd.
+        """
+        try:
+            return os.stat(path).st_mtime
+        except (OSError, FileNotFoundError):
+            return None
+
+    async def delete_path(self, path: str) -> None:
+        """Delete a local file or directory tree.
+
+        No-op if *path* does not exist.
+
+        Args:
+            path (`str`):
+                Path to delete.
+        """
+        if not os.path.exists(path):
+            return
+        if os.path.isdir(path):
+            shutil.rmtree(path)
+        else:
+            os.remove(path)
diff --git a/src/agentscope/tool/_builtin/_bash.py b/src/agentscope/tool/_builtin/_bash.py
new file mode 100644
index 0000000..58952f6
--- /dev/null
+++ b/src/agentscope/tool/_builtin/_bash.py
@@ -0,0 +1,778 @@
+# -*- coding: utf-8 -*-
+"""The bash tool in agentscope."""
+import os
+from typing import AsyncGenerator, Any, List
+import re
+
+from ._bash_parser import BashCommandParser
+from .._base import ToolBase, ToolMiddlewareBase
+from .._constants import (
+    DEFAULT_DANGEROUS_FILES,
+    DEFAULT_DANGEROUS_DIRECTORIES,
+)
+from ...permission import (
+    PermissionContext,
+    PermissionDecision,
+    PermissionBehavior,
+    PermissionMode,
+    PermissionRule,
+)
+from ...message import TextBlock, ToolResultState
+from .._response import ToolChunk
+from ._backend import BackendBase
+
+
+class Bash(ToolBase):
+    """The bash tool."""
+
+    name: str = "Bash"
+    """The tool name presented to the agent."""
+
+    description: str = """Executes a bash command and returns its output.
+
+The working directory persists between commands, but shell state does
+not. The shell environment is initialized from the user's profile
+(bash or zsh).
+
+IMPORTANT: Avoid using this tool to run `find`, `grep`, `cat`, `head`,
+`tail`, `sed`, `awk`, or `echo` commands, unless explicitly instructed
+or after you have verified that a dedicated tool cannot accomplish your
+task. Instead, use the appropriate dedicated tool as this will provide
+a much better experience for the user:
+
+ - File search: Use Glob (NOT find or ls)
+ - Content search: Use Grep (NOT grep or rg)
+ - Read files: Use Read (NOT cat/head/tail)
+ - Edit files: Use Edit (NOT sed/awk)
+ - Write files: Use Write (NOT echo >/cat <<EOF)
+ - Communication: Output text directly (NOT echo/printf)
+
+While the Bash tool can do similar things, it's better to use the
+built-in tools as they provide a better user experience and make it
+easier to review tool calls and give permission.
+
+# Instructions
+ - If your command will create new directories or files, first use
+   this tool to run `ls` to verify the parent directory exists and is
+   the correct location.
+ - Always quote file paths that contain spaces with double quotes in
+   your command (e.g., cd "path with spaces/file.txt")
+ - Try to maintain your current working directory throughout the
+   session by using absolute paths and avoiding usage of `cd`. You may
+   use `cd` if the User explicitly requests it.
+ - You may specify an optional timeout in milliseconds (up to 600000ms
+   / 10 minutes). By default, your command will timeout after 120000ms
+   (2 minutes).
+ - Write a clear, concise description of what your command does. For
+   simple commands, keep it brief (5-10 words). For complex commands
+   (piped commands, obscure flags, or anything hard to understand at a
+   glance), include enough context so that the user can understand what
+   your command will do.
+ - When issuing multiple commands:
+  - If the commands are independent and can run in parallel, make
+    multiple Bash tool calls in a single message. Example: if you need
+    to run "git status" and "git diff", send a single message with two
+    Bash tool calls in parallel.
+  - If the commands depend on each other and must run sequentially,
+    use a single Bash call with '&&' to chain them together.
+  - Use ';' only when you need to run commands sequentially but don't
+    care if earlier commands fail.
+  - DO NOT use newlines to separate commands (newlines are ok in
+    quoted strings).
+ - For git commands:
+  - Prefer to create a new commit rather than amending an existing
+    commit.
+  - Before running destructive operations (e.g., git reset --hard, git
+    push --force, git checkout --), consider whether there is a safer
+    alternative that achieves the same goal. Only use destructive
+    operations when they are truly the best approach.
+  - Never skip hooks (--no-verify) or bypass signing (--no-gpg-sign,
+    -c commit.gpgsign=false) unless the user has explicitly asked for
+    it. If a hook fails, investigate and fix the underlying issue.
+ - Avoid unnecessary `sleep` commands:
+  - Do not sleep between commands that can run immediately — just run
+    them.
+  - Do not retry failing commands in a sleep loop — diagnose the root
+    cause or consider an alternative approach.
+  - If you must sleep, keep the duration short (1-5 seconds) to avoid
+    blocking the user."""
+    """The description presented to the agent."""
+
+    input_schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {
+            "command": {
+                "type": "string",
+                "description": "The bash command to execute.",
+            },
+            "description": {
+                "type": "string",
+                "description": (
+                    "Clear, concise description of what this command "
+                    "does. For simple commands, keep it brief (5-10 "
+                    "words). For complex commands, include enough "
+                    "context."
+                ),
+            },
+            "timeout": {
+                "type": "integer",
+                "description": (
+                    "Optional timeout in milliseconds "
+                    "(default: 120000, max: 600000)"
+                ),
+                "default": 120000,
+                "maximum": 600000,
+                "minimum": 0,
+            },
+        },
+        "required": ["command"],
+    }
+
+    is_mcp: bool = False
+    is_read_only: bool = False
+    is_concurrency_safe: bool = False
+    is_external_tool: bool = False
+    is_state_injected: bool = False
+
+    def __init__(  # pylint: disable=dangerous-default-value
+        self,
+        dangerous_files: list[str] = DEFAULT_DANGEROUS_FILES,
+        dangerous_directories: list[str] = DEFAULT_DANGEROUS_DIRECTORIES,
+        cwd: str | os.PathLike[str] | None = None,
+        middlewares: List[ToolMiddlewareBase] | None = None,
+        backend: BackendBase | None = None,
+    ) -> None:
+        """Initialize the bash tool.
+
+        Args:
+            dangerous_files (`list[str]`, optional):
+                Sensitive files that require explicit user confirmation,
+                even in BYPASS mode. Matched by basename
+                (case-insensitive). Defaults to `DEFAULT_DANGEROUS_FILES`.
+                Pass a custom list to fully replace the defaults, or `[]`
+                to disable the filename check.
+            dangerous_directories (`list[str]`, optional):
+                Sensitive directories that require explicit user
+                confirmation. Matched when any path segment equals an
+                entry (case-insensitive). Defaults to
+                `DEFAULT_DANGEROUS_DIRECTORIES`. Pass a custom list to
+                fully replace the defaults, or `[]` to disable the
+                directory check.
+            cwd (`str | os.PathLike[str] | None`, optional):
+                The working directory used when executing bash commands.
+            middlewares (`List[ToolMiddlewareBase] | None`, optional):
+                Tool middlewares wrapping the tool execution.
+            backend (`BackendBase | None`, optional):
+                The sandbox backend to use for shell execution. When
+                ``None``, a :class:`LocalBackend` is created.
+        """
+        from ._backend import LocalBackend
+
+        super().__init__(middlewares=middlewares)
+        self._bash_parser = BashCommandParser()
+
+        self.dangerous_files = list(dangerous_files)
+        self.dangerous_directories = list(dangerous_directories)
+        self._cwd = os.fspath(cwd) if cwd is not None else None
+        self._backend = backend or LocalBackend()
+
+    async def check_read_only(
+        self,
+        tool_input: dict[str, Any],
+    ) -> bool:
+        """Decide whether this specific bash invocation is read-only.
+
+        Inspects the command and returns ``True`` for known-safe read-only
+        commands (e.g. ``ls``, ``cat``, ``grep``, ``git status``). The
+        static :attr:`is_read_only` class attribute is ``False`` because
+        Bash can execute arbitrary commands; this method overrides that
+        with a per-invocation answer.
+        """
+        command = tool_input.get("command", "")
+        if not command:
+            return self.is_read_only
+        return self._bash_parser.is_read_only_command(command)
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        """Check permissions for bash command execution.
+
+        This method implements Bash-specific permission checks:
+
+        0. Injection risk check (bypass-immune safety ASK if command
+           contains dynamic expansion like ``$(...)`` or ``<(...)``)
+        1. Read-only command check — auto-ALLOW in **every mode**
+           (including DEFAULT) for known-safe read-only commands
+           (``ls``, ``pwd``, ``git status``, ``cat``, etc.). This is
+           the static counterpart to :meth:`check_read_only`.
+        2. Dangerous command pattern check (bypass-immune safety ASK)
+        3. Sed in-place constraint check (bypass-immune safety ASK)
+        4. Dangerous path check for config files (bypass-immune safety
+           ASK)
+        5. Dangerous removal path check for system dirs (bypass-immune
+           safety ASK)
+        6. ACCEPT_EDITS auto-allow for ``mkdir``/``touch``/``rm``/
+           ``rmdir``/``mv``/``cp``/``sed`` — only when **every**
+           target path resolves inside a working directory
+        7. PASSTHROUGH (engine continues with rule matching)
+
+        "Bypass-immune" decisions set
+        :attr:`PermissionDecision.bypass_immune` so they cannot be
+        silenced by allow rules in DEFAULT mode. In BYPASS mode all
+        bypass-immune ASKs are intentionally skipped — see
+        :attr:`PermissionMode.BYPASS`.
+
+        Args:
+            tool_input (`dict[str, Any]`):
+                The tool input containing "command" key
+            context (`PermissionContext`):
+                The permission context with mode and rules
+
+        Returns:
+            `PermissionDecision`:
+                ALLOW for safe operations, ASK for dangerous operations,
+                PASSTHROUGH to let Engine continue with rule matching
+        """
+
+        command = tool_input.get("command", "")
+        if not command:
+            return PermissionDecision(
+                behavior=PermissionBehavior.PASSTHROUGH,
+                message="Empty command",
+            )
+
+        # 0. Injection check: detect dynamic shell structures that cannot be
+        # statically analyzed (command substitution, process substitution,
+        # control flow, etc.). Must run before read-only check so that
+        # `$(rm -rf /)` inside an otherwise-safe command is caught.
+        injection_reason = self._bash_parser.check_injection_risk(command)
+        if injection_reason:
+            return PermissionDecision(
+                behavior=PermissionBehavior.ASK,
+                message=f"Permission required: {injection_reason}",
+                decision_reason="Safety check: command contains dynamic "
+                "expansion that cannot be statically analyzed",
+                bypass_immune=True,
+            )
+
+        # 1. Check if command is read-only (auto-allow)
+        if self._bash_parser.is_read_only_command(command):
+            return PermissionDecision(
+                behavior=PermissionBehavior.ALLOW,
+                message="Permission granted for read-only command",
+                decision_reason="Read-only command is allowed",
+            )
+
+        # 2. Check for dangerous commands (safety check, bypass-immune)
+        dangerous_pattern = self._bash_parser.check_dangerous_command(command)
+        if dangerous_pattern:
+            return PermissionDecision(
+                behavior=PermissionBehavior.ASK,
+                message=f"Permission required: Command contains dangerous "
+                f"pattern: {dangerous_pattern}",
+                decision_reason="Safety check: dangerous command pattern "
+                "detected",
+                bypass_immune=True,
+            )
+
+        # 3. Check for sed constraints (safety check, bypass-immune)
+        sed_error = self._bash_parser.check_sed_constraints(
+            command,
+            self.dangerous_files,
+        )
+        if sed_error:
+            return PermissionDecision(
+                behavior=PermissionBehavior.ASK,
+                message=f"Permission required: {sed_error}",
+                decision_reason="Safety check: sed in-place modification "
+                "of dangerous file",
+                bypass_immune=True,
+            )
+
+        # 4. Check for dangerous paths in sensitive config files/dirs
+        # (safety check, bypass-immune)
+        dangerous_paths = self._extract_dangerous_paths_from_bash(command)
+        if dangerous_paths:
+            paths_str = ", ".join(dangerous_paths)
+            return PermissionDecision(
+                behavior=PermissionBehavior.ASK,
+                message=f"Permission required: Bash command operates on "
+                f"sensitive paths: {paths_str}",
+                decision_reason="Safety check: dangerous file or "
+                "directory in bash command",
+                bypass_immune=True,
+            )
+
+        # 5. Check for dangerous removal paths: rm/rmdir targeting system
+        # critical directories like /, /usr, /etc, ~ (bypass-immune).
+        # Checked separately from step 4 because these paths are not in the
+        # dangerous_files/directories lists — they are system-level paths
+        # that should never be removed regardless of user configuration.
+        removal_path = await self._check_dangerous_removal_path(command)
+        if removal_path:
+            return PermissionDecision(
+                behavior=PermissionBehavior.ASK,
+                message=f"Dangerous removal operation detected: "
+                f"'{removal_path}'\n\nThis command would remove a critical "
+                f"system directory. This requires explicit approval and "
+                f"cannot be auto-allowed by permission rules.",
+                decision_reason="Safety check: dangerous removal of "
+                "critical system path",
+                bypass_immune=True,
+            )
+
+        # 6. ACCEPT_EDITS auto-allow for filesystem commands whose targets
+        # all live inside a working directory. Mirrors Write/Edit's strict
+        # working-directory check — we never auto-allow a bash command that
+        # would touch a path outside the configured working set (e.g.
+        # ``cp /etc/hosts /tmp/x`` must not pass even though ``cp`` is in
+        # the auto-allow list).
+        if context.mode == PermissionMode.ACCEPT_EDITS:
+            filesystem_commands = {
+                "mkdir",
+                "touch",
+                "rm",
+                "rmdir",
+                "mv",
+                "cp",
+                "sed",
+            }
+            base_command = (
+                command.strip().split()[0] if command.strip() else ""
+            )
+
+            if base_command in filesystem_commands:
+                # Collect every target path: file arguments AND output
+                # redirections. ``extract_file_paths`` includes both.
+                target_paths = [
+                    path
+                    for _cmd, path in self._bash_parser.extract_file_paths(
+                        command,
+                    )
+                ]
+                # Conservative: only auto-allow when we extracted at least
+                # one target AND every target resolves inside a working
+                # directory. An empty list means the parser found nothing
+                # actionable (or the command has no args) — in that case
+                # we fall through to PASSTHROUGH rather than blindly
+                # allowing.
+                if target_paths and all(
+                    self._path_in_allowed_working_path(path, context)
+                    for path in target_paths
+                ):
+                    return PermissionDecision(
+                        behavior=PermissionBehavior.ALLOW,
+                        message=f"Permission granted for '{base_command}' "
+                        f"command (accept edits mode - filesystem command, "
+                        f"all targets in working directory)",
+                        decision_reason=(
+                            f"Filesystem command '{base_command}' is "
+                            f"auto-allowed in accept edits mode because "
+                            f"all target paths are within a working "
+                            f"directory"
+                        ),
+                    )
+
+        # 7. Passthrough to let Engine continue with rule matching
+        return PermissionDecision(
+            behavior=PermissionBehavior.PASSTHROUGH,
+            message=f"Execute bash command: {command}",
+        )
+
+    async def match_rule(
+        self,
+        rule_content: str | None,
+        tool_input: dict[str, Any],
+    ) -> bool:
+        r"""Match Bash command using regex-based wildcard matching.
+
+        Implements wildcard matching with escape sequences:
+        - Supports \* for literal asterisk and \\ for literal backslash
+        - Special optimization: "git *" matches both "git" and "git add"
+        - Prefix pattern (e.g., "git:*"): matches commands starting with "git "
+        - Wildcard pattern: converts to regex with proper escape handling
+        - Substring pattern: exact substring matching
+        - If rule_content is None, matches all invocations
+         (tool-name-level rule)
+
+        Args:
+            rule_content: The command pattern to match, or None to match all
+            tool_input: Must contain a "command" key with the command string
+
+        Returns:
+            True if pattern matches the command
+        """
+        # None = tool-name-level rule, matches everything
+        if rule_content is None:
+            return True
+
+        command = tool_input.get("command", "")
+
+        # Check if pattern is a prefix pattern (ends with :*)
+        if rule_content.endswith(":*"):
+            prefix = rule_content[:-2].strip()
+            return command.startswith(prefix + " ") or command == prefix
+
+        # Check if pattern has unescaped wildcards
+        def has_wildcards(pattern: str) -> bool:
+            """Check if pattern contains unescaped * wildcards."""
+            i = 0
+            while i < len(pattern):
+                if pattern[i] == "\\":
+                    i += 2  # Skip escaped character
+                elif pattern[i] == "*":
+                    return True
+                else:
+                    i += 1
+            return False
+
+        if not has_wildcards(rule_content):
+            # No wildcards, but may have escape sequences
+            # Convert escape sequences for matching
+            pattern = rule_content
+            pattern = pattern.replace("\\\\", "\x00BACKSLASH\x00")
+            pattern = pattern.replace("\\*", "*")
+            pattern = pattern.replace("\x00BACKSLASH\x00", "\\")
+            # Use substring matching with converted pattern
+            return pattern in command
+
+        # Convert wildcard pattern to regex with escape handling
+        # Use placeholders for escaped sequences
+        ESCAPED_STAR = "\x00ESCAPED_STAR\x00"
+        ESCAPED_BACKSLASH = "\x00ESCAPED_BACKSLASH\x00"
+
+        pattern = rule_content
+        # Replace \\ with placeholder
+        pattern = pattern.replace("\\\\", ESCAPED_BACKSLASH)
+        # Replace \* with placeholder
+        pattern = pattern.replace("\\*", ESCAPED_STAR)
+
+        # Manually escape regex special characters (except *)
+        # Don't use re.escape() as it escapes spaces too
+        special_chars = r".^$+?{}[]|()"
+        for char in special_chars:
+            pattern = pattern.replace(char, "\\" + char)
+
+        # Convert * to regex .* (match any characters)
+        pattern = pattern.replace("*", ".*")
+
+        # Restore escaped sequences
+        pattern = pattern.replace(ESCAPED_STAR, r"\*")
+        pattern = pattern.replace(ESCAPED_BACKSLASH, r"\\")
+
+        # Special optimization: "git *" should match both "git" and "git add"
+        # Pattern: if ends with .*, make it optional
+        if pattern.endswith(".*"):
+            base_pattern = pattern[:-2]  # Remove .*
+            # Try exact match first (handles trailing space)
+            base_pattern = base_pattern.rstrip()
+            if re.fullmatch(base_pattern, command):
+                return True
+
+        # Full regex match
+        try:
+            return bool(re.fullmatch(pattern, command))
+        except re.error:
+            # Invalid regex, fall back to substring matching
+            return rule_content.replace("*", "") in command
+
+    async def generate_suggestions(
+        self,
+        tool_input: dict[str, Any],
+    ) -> List["PermissionRule"]:
+        """Generate suggested permission rules for Bash commands.
+
+        Generates prefix rules based on command + subcommand (two words).
+        For example, "git commit -m 'xxx'" generates "git commit:*".
+
+        Args:
+            tool_input (`dict[str, Any]`):
+                The tool input data containing "command" key
+
+        Returns:
+            `List[PermissionRule]`:
+                List of suggested permission rules based on command prefixes
+        """
+
+        command = tool_input.get("command", "")
+        if not command:
+            return []
+
+        # Use bash parser to extract command prefixes
+        prefixes = self._bash_parser.extract_command_prefixes(
+            command,
+            max_prefixes=5,
+        )
+
+        if not prefixes:
+            # Cannot extract any prefix, return empty
+            return []
+
+        # Generate rules for each prefix
+        rules = []
+        for prefix in prefixes:
+            rules.append(
+                PermissionRule(
+                    tool_name="Bash",
+                    rule_content=f"{prefix}:*",
+                    behavior=PermissionBehavior.ALLOW,
+                    source="suggested",
+                ),
+            )
+
+        return rules
+
+    def _extract_dangerous_paths_from_bash(
+        self,
+        command: str,
+    ) -> list[str]:
+        """Extract dangerous paths from a bash command using tree-sitter.
+
+        Checks for dangerous paths in:
+        - File-manipulating commands (rm, mv, cp, chmod, chown, sed, touch)
+        - Output redirections (>, >>)
+
+        Args:
+            command (`str`):
+                The bash command string
+
+        Returns:
+            `list[str]`:
+                List of dangerous paths found in the command
+        """
+        dangerous_paths = []
+
+        # Use tree-sitter to extract file paths
+        file_paths = self._bash_parser.extract_file_paths(command)
+
+        for _cmd_name, path in file_paths:
+            if self._is_dangerous_path(path):
+                dangerous_paths.append(path)
+
+        return dangerous_paths
+
+    async def _check_dangerous_removal_path(self, command: str) -> str | None:
+        """Check if a rm/rmdir command targets a critical system path.
+
+        Detects commands like `rm -rf /`, `rm -rf /usr`, `rmdir ~` that
+        would destroy critical system directories. Unlike _is_dangerous_path
+        (which checks against a configurable list of sensitive config files),
+        this checks against a fixed set of system-level paths that must
+        never be removed regardless of user configuration.
+
+        Dangerous paths are:
+        - Root directory (/)
+        - Home directory (~)
+        - Wildcard alone (*) or as dir/* (removes everything)
+        - Direct children of root (/usr, /etc, /tmp, /var, etc.)
+
+        Args:
+            command (`str`):
+                The bash command string
+
+        Returns:
+            `str | None`:
+                The dangerous path if found, None otherwise
+        """
+        tokens = command.strip().split()
+        if not tokens:
+            return None
+
+        # Find rm or rmdir subcommands (handle compound commands)
+        try:
+            tree = self._bash_parser.parser.parse(bytes(command, "utf8"))
+            subcommands = self._bash_parser.split_compound_command(
+                tree.root_node,
+                command,
+            )
+        except Exception:
+            subcommands = [command]
+
+        # Check each subcommand for rm/rmdir
+        for subcmd in subcommands:
+            subcmd_tokens = subcmd.strip().split()
+            if not subcmd_tokens:
+                continue
+            base = subcmd_tokens[0]
+            if base not in ("rm", "rmdir"):
+                continue
+
+            # Collect non-flag arguments as potential paths
+            i = 1
+            while i < len(subcmd_tokens):
+                tok = subcmd_tokens[i]
+                # Skip flags
+                if tok.startswith("-"):
+                    i += 1
+                    continue
+                path = tok.strip("'\"")
+                if await self._is_dangerous_removal_path(path):
+                    return path
+                i += 1
+
+        return None
+
+    async def _is_dangerous_removal_path(self, path: str) -> bool:
+        """Check if a path is a critical system directory that must not be
+        removed.
+
+        All path resolution is performed via the backend so that the
+        check operates on the **backend environment's** ``$HOME`` /
+        ``cwd`` / path semantics, not the host process's.
+
+        Args:
+            path (`str`):
+                The path to check (may be relative, absolute, or contain ~)
+
+        Returns:
+            `bool`:
+                True if removing this path would be catastrophic
+        """
+
+        # Bare wildcard
+        if path in ("*", "./*", "/"):
+            return True
+        # Ends with /* — removes everything in a directory
+        if path.endswith("/*") or path.endswith("\\*"):
+            return True
+
+        # Expand tilde and resolve to an absolute path inside the
+        # backend environment.  Don't resolve symlinks — ``/tmp`` is a
+        # symlink on macOS but is still a root-child and should be
+        # flagged.
+        expanded = await self._backend.expanduser(path)
+        backend_cwd = await self._backend.getcwd()
+        abs_path = self._backend.abspath(expanded, cwd=backend_cwd)
+
+        # Home directory
+        home = await self._backend.expanduser("~")
+        if abs_path == home:
+            return True
+
+        # Root itself: ``dirname(root) == root`` on both POSIX
+        # (``"/"``) and Windows (``"C:\\"``), so this check is
+        # path-flavor agnostic.
+        parent = self._backend.dirname(abs_path)
+        if abs_path == parent:
+            return True
+
+        # Direct children of root (e.g. ``/usr``, ``/etc``, ``/tmp``):
+        # the *parent* of these is the root, where
+        # ``dirname(parent) == parent``.
+        if self._backend.dirname(parent) == parent:
+            return True
+
+        return False
+
+    async def call(  # type: ignore[override] # pylint: disable=unused-argument
+        self,
+        command: str,
+        description: str = "",
+        timeout: int = 120000,
+    ) -> AsyncGenerator[ToolChunk, None]:
+        """Execute the bash and return the output.
+
+        Args:
+            command: The bash command to execute.
+            description: Optional description of what the command does.
+            timeout: Timeout in milliseconds (default: 120000, max: 600000).
+
+        Yields:
+            ToolChunk: The tool execution result with stdout/stderr content.
+        """
+
+        # Clamp timeout to max 600000ms and convert to seconds
+        timeout_ms = min(timeout, 600000)
+        timeout_sec = timeout_ms / 1000.0
+
+        try:
+            # ``command`` is a full shell command line (it may contain
+            # pipes, redirects, ``&&``, …), so wrap it in a shell — the
+            # backend primitive runs the argv directly without one. Pick
+            # the platform's native shell so the Windows experience that
+            # ``main`` had (commands interpreted by ``cmd.exe``) is
+            # preserved; POSIX hosts use ``/bin/sh``.
+            if os.name == "nt":
+                shell_command = ["cmd", "/c", command]
+            else:
+                shell_command = ["/bin/sh", "-c", command]
+            result = await self._backend.exec_shell(
+                shell_command,
+                cwd=self._cwd,
+                timeout=timeout_sec,
+            )
+
+            # Decode and normalize line endings
+            stdout = result.stdout.decode(
+                "utf-8",
+                errors="replace",
+            ).replace("\r\n", "\n")
+            stderr = result.stderr.decode(
+                "utf-8",
+                errors="replace",
+            ).replace("\r\n", "\n")
+
+            # Check for timeout (backend returns exit_code=-1,
+            # stderr=b"timed out")
+            if result.exit_code == -1 and result.stderr == b"timed out":
+                error_msg = (
+                    f"Command timed out after {timeout_ms}ms: {command}"
+                )
+                yield ToolChunk(
+                    content=[TextBlock(text=error_msg)],
+                    state=ToolResultState.ERROR,
+                    is_last=True,
+                )
+                return
+
+            # Combine output
+            output = stdout
+            if stderr:
+                if output:
+                    output += "\n"
+                output += stderr
+
+            # Truncate if exceeds 30000 characters
+            if len(output) > 30000:
+                output = output[:30000] + "\n... (output truncated)"
+
+            # Check exit code
+            if not result.ok():
+                # Command failed
+                error_result = f"Command failed: {command}\n"
+                if stdout:
+                    error_result += f"\nStdout:\n{stdout}"
+                if stderr:
+                    error_result += f"\nStderr:\n{stderr}"
+
+                # Truncate error message if needed
+                if len(error_result) > 30000:
+                    error_result = (
+                        error_result[:30000] + "\n... (output truncated)"
+                    )
+
+                yield ToolChunk(
+                    content=[TextBlock(text=error_result)],
+                    state=ToolResultState.ERROR,
+                    is_last=True,
+                )
+            else:
+                # Command succeeded - note: ToolChunk uses "running" state
+                # which will be converted to "finished" in ToolResponse
+                yield ToolChunk(
+                    content=[TextBlock(text=output)],
+                    state=ToolResultState.RUNNING,
+                    is_last=True,
+                )
+
+        except Exception as e:
+            # Other errors
+            error_msg = f"Command failed: {command}\nError: {str(e)}"
+            yield ToolChunk(
+                content=[TextBlock(text=error_msg)],
+                state=ToolResultState.ERROR,
+                is_last=True,
+            )
diff --git a/src/agentscope/tool/_builtin/_bash_parser.py b/src/agentscope/tool/_builtin/_bash_parser.py
new file mode 100644
index 0000000..62d6f1a
--- /dev/null
+++ b/src/agentscope/tool/_builtin/_bash_parser.py
@@ -0,0 +1,884 @@
+# -*- coding: utf-8 -*-
+"""Bash command parser using tree-sitter for precise syntax analysis.
+
+This module provides utilities to parse Bash commands and extract meaningful
+information for permission rule generation, including:
+- Splitting compound commands (&&, ||, ;, |)
+- Extracting command prefixes (e.g., "npm run" from "npm run build")
+- Extracting file paths from commands for dangerous path detection
+- Extracting output redirections
+- Checking if commands are read-only
+"""
+
+from typing import List, Optional, Set, Tuple
+
+import re
+import shlex
+
+import tree_sitter_bash as tsbash
+from tree_sitter import Language, Parser, Node
+
+from .._constants import DANGEROUS_NODE_TYPES, DANGEROUS_COMMANDS
+
+
+# Commands that are considered safe and don't require permission rules
+SAFE_COMMANDS: Set[str] = {
+    "echo",
+    "cat",
+    "ls",
+    "pwd",
+    "cd",
+    "true",
+    "false",
+    "printf",
+    "grep",
+    "tee",
+}
+
+# Safe environment variables that can be skipped when extracting command prefix
+SAFE_ENV_VARS = {
+    "NODE_ENV",
+    "PYTHONUNBUFFERED",
+    "RUST_LOG",
+    "LANG",
+    "TERM",
+    "NO_COLOR",
+    "FORCE_COLOR",
+    "DEBUG",
+    "VERBOSE",
+    "CI",
+    "PATH",
+    "HOME",
+    "USER",
+    "SHELL",
+    "EDITOR",
+    "PAGER",
+    "TZ",
+    "LC_ALL",
+    "LC_CTYPE",
+    "COLUMNS",
+    "LINES",
+    "CLICOLOR",
+    "CLICOLOR_FORCE",
+}
+
+# Read-only git commands
+GIT_READ_ONLY_COMMANDS = {
+    "git status",
+    "git log",
+    "git diff",
+    "git show",
+    "git branch",
+    "git tag",
+    "git remote",
+    "git ls-files",
+    "git ls-tree",
+    "git cat-file",
+    "git rev-parse",
+    "git rev-list",
+    "git describe",
+    "git shortlog",
+    "git blame",
+    "git grep",
+    "git reflog",
+    "git config --get",
+    "git config --list",
+}
+
+# Read-only commands for various tools
+READ_ONLY_COMMANDS = {
+    # Basic file operations
+    "ls",
+    "cat",
+    "head",
+    "tail",
+    "less",
+    "more",
+    "file",
+    "stat",
+    "wc",
+    "grep",
+    "rg",
+    "ag",
+    "ack",
+    "find",
+    "tree",
+    "pwd",
+    "which",
+    "whereis",
+    "type",
+    # Git commands
+    *GIT_READ_ONLY_COMMANDS,
+    # Docker read-only
+    "docker ps",
+    "docker images",
+    "docker inspect",
+    "docker logs",
+    "docker version",
+    "docker info",
+    # GitHub CLI read-only
+    "gh repo view",
+    "gh issue list",
+    "gh pr list",
+    "gh status",
+    # Python/Node tools
+    "python --version",
+    "python -V",
+    "node --version",
+    "node -v",
+    "npm list",
+    "npm ls",
+    "pip list",
+    "pip show",
+}
+
+
+class BashCommandParser:
+    """Parse Bash commands using tree-sitter for accurate syntax analysis."""
+
+    def __init__(self) -> None:
+        """Initialize the parser with tree-sitter-bash language."""
+        self.parser = Parser(Language(tsbash.language()))
+
+    def is_read_only_command(self, command: str) -> bool:
+        """Check if a command is read-only (safe to auto-allow).
+
+        For compound commands (&&, ||, ;, |), ALL subcommands must be
+        read-only for the entire command to be considered read-only.
+
+        Commands with output redirections (>, >>) are NOT considered read-only.
+
+        Args:
+            command (`str`):
+                The bash command string
+
+        Returns:
+            `bool`:
+                True if the command (and all subcommands) are read-only,
+                False otherwise
+        """
+        # Normalize command (strip leading/trailing whitespace)
+        cmd = command.strip()
+
+        # Check for output redirections - these are NOT read-only
+        if ">" in cmd:
+            return False
+
+        # Check if it's a compound command
+        if any(op in cmd for op in ["&&", "||", ";", "|"]):
+            # Split into subcommands and check each one
+            try:
+                tree = self.parser.parse(bytes(cmd, "utf8"))
+                root = tree.root_node
+                subcommands = self.split_compound_command(root, cmd)
+
+                # All subcommands must be read-only
+                for subcmd in subcommands:
+                    if not self._is_single_command_read_only(subcmd.strip()):
+                        return False
+                return True
+            except Exception:
+                # If parsing fails, be conservative
+                return False
+
+        # Single command - check directly
+        return self._is_single_command_read_only(cmd)
+
+    def _is_single_command_read_only(self, cmd: str) -> bool:
+        """Check if a single (non-compound) command is read-only.
+
+        Args:
+            cmd (`str`):
+                A single command string (no &&, ||, ;, |)
+
+        Returns:
+            `bool`:
+                True if the command is read-only, False otherwise
+        """
+        # Check exact match in read-only commands
+        if cmd in READ_ONLY_COMMANDS:
+            return True
+
+        # Check if it starts with a read-only prefix
+        for readonly_cmd in READ_ONLY_COMMANDS:
+            if cmd == readonly_cmd or cmd.startswith(readonly_cmd + " "):
+                return True
+
+        # Check base command for simple read-only operations
+        tokens = cmd.split()
+        if tokens:
+            base_cmd = tokens[0]
+            # Skip environment variables
+            i = 0
+            while i < len(tokens) and "=" in tokens[i]:
+                i += 1
+            if i < len(tokens):
+                base_cmd = tokens[i]
+
+            # Check if base command is in safe commands
+            if base_cmd in SAFE_COMMANDS:
+                return True
+
+        return False
+
+    def extract_file_paths(
+        self,
+        command: str,
+    ) -> List[Tuple[str, str]]:
+        """Extract file paths from a bash command using tree-sitter.
+
+        Returns paths that are arguments to file-manipulating commands
+        (rm, mv, cp, chmod, chown, etc.) and output redirection targets.
+
+        Args:
+            command (`str`):
+                The bash command string
+
+        Returns:
+            `List[Tuple[str, str]]`:
+                List of tuples (command_name, file_path)
+        """
+        paths = []
+
+        try:
+            # Parse command to AST
+            tree = self.parser.parse(bytes(command, "utf8"))
+            root = tree.root_node
+
+            # Extract paths from commands
+            self._extract_paths_from_node(root, command, paths)
+
+        except Exception:
+            # Fallback to simple token-based extraction
+            paths = self._extract_paths_fallback(command)
+
+        return paths
+
+    def _extract_paths_from_node(
+        self,
+        node: Node,
+        command: str,
+        paths: List[Tuple[str, str]],
+    ) -> None:
+        """Recursively extract file paths from AST nodes.
+
+        Args:
+            node (`Node`):
+                The AST node to process
+            command (`str`):
+                The original command string
+            paths (`List[Tuple[str, str]]`):
+                List to append (command_name, path) tuples to
+        """
+        # Check for redirections
+        if node.type == "file_redirect":
+            # Extract the target file
+            for child in node.children:
+                if child.type == "word":
+                    path = command[child.start_byte : child.end_byte]
+                    paths.append(("redirect", path.strip("'\"")))
+        # Check for commands
+        if node.type == "command":
+            # Extract command name and arguments
+            cmd_name = None
+            args = []
+
+            for child in node.children:
+                if child.type == "command_name":
+                    cmd_name = command[child.start_byte : child.end_byte]
+                elif child.type == "word" and cmd_name:
+                    arg = command[child.start_byte : child.end_byte]
+                    args.append(arg.strip("'\""))
+
+            # Check if this is a file-manipulating command
+            if cmd_name in [
+                "rm",
+                "mv",
+                "cp",
+                "chmod",
+                "chown",
+                "chgrp",
+                "touch",
+                "ln",
+                "sed",
+                "mkdir",
+                "rmdir",
+            ]:
+                # Extract file arguments (skip flags)
+                for arg in args:
+                    if not arg.startswith("-"):
+                        paths.append((cmd_name, arg))
+
+        # Recursively process children
+        for child in node.children:
+            self._extract_paths_from_node(child, command, paths)
+
+    def _extract_paths_fallback(
+        self,
+        command: str,
+    ) -> List[Tuple[str, str]]:
+        """Fallback path extraction using simple token parsing.
+
+        Args:
+            command (`str`):
+                The bash command string
+
+        Returns:
+            `List[Tuple[str, str]]`:
+                List of tuples (command_name, file_path)
+        """
+        paths = []
+        tokens = command.split()
+        i = 0
+
+        while i < len(tokens):
+            token = tokens[i]
+
+            # Check for output redirections
+            if token in [">", ">>", "2>", "&>"]:
+                if i + 1 < len(tokens):
+                    path = tokens[i + 1].strip("'\"")
+                    paths.append(("redirect", path))
+                i += 2
+                continue
+
+            # Check for file-manipulating commands
+            if token in [
+                "rm",
+                "mv",
+                "cp",
+                "chmod",
+                "chown",
+                "sed",
+                "touch",
+                "mkdir",
+                "rmdir",
+            ]:
+                cmd_name = token
+                # Look for file arguments after this command
+                j = i + 1
+                while j < len(tokens):
+                    arg = tokens[j].strip("'\"")
+                    # Skip flags
+                    if arg.startswith("-"):
+                        j += 1
+                        continue
+                    # This is a file argument
+                    paths.append((cmd_name, arg))
+                    j += 1
+                break
+
+            i += 1
+
+        return paths
+
+    def extract_redirections(self, command: str) -> List[str]:
+        """Extract output redirection targets from a bash command.
+
+        Args:
+            command (`str`):
+                The bash command string
+
+        Returns:
+            `List[str]`:
+                List of file paths that are redirection targets
+        """
+        redirections = []
+
+        try:
+            # Parse command to AST
+            tree = self.parser.parse(bytes(command, "utf8"))
+            root = tree.root_node
+
+            # Extract redirections
+            self._extract_redirections_from_node(root, command, redirections)
+
+        except Exception:
+            # Fallback to simple extraction
+            tokens = command.split()
+            for i, token in enumerate(tokens):
+                if token in [">", ">>", "2>", "&>"] and i + 1 < len(tokens):
+                    path = tokens[i + 1].strip("'\"")
+                    redirections.append(path)
+
+        return redirections
+
+    def _extract_redirections_from_node(
+        self,
+        node: Node,
+        command: str,
+        redirections: List[str],
+    ) -> None:
+        """Recursively extract redirections from AST nodes.
+
+        Args:
+            node (`Node`):
+                The AST node to process
+            command (`str`):
+                The original command string
+            redirections (`List[str]`):
+                List to append redirection targets to
+        """
+        if node.type == "file_redirect":
+            # Extract the target file
+            for child in node.children:
+                if child.type == "word":
+                    path = command[child.start_byte : child.end_byte]
+                    redirections.append(path.strip("'\""))
+
+        # Recursively process children
+        for child in node.children:
+            self._extract_redirections_from_node(child, command, redirections)
+
+    def extract_command_prefixes(
+        self,
+        command: str,
+        max_prefixes: int = 5,
+    ) -> List[str]:
+        """Extract command prefixes from a bash command.
+
+        Automatically handles compound commands (&&, ||, ;, |) and extracts
+        prefixes from each subcommand. Returns deduplicated list of prefixes.
+
+        Args:
+            command (`str`):
+                The bash command string (may be compound)
+            max_prefixes (`int`):
+                Maximum number of prefixes to return (default: 5)
+
+        Returns:
+            `List[str]`:
+                List of command prefixes (deduplicated), e.g., ["npm run",
+                "git commit"]
+
+        Examples:
+            >>> parser.extract_command_prefixes("git add . && git commit")
+            ['git add', 'git commit']
+            >>> parser.extract_command_prefixes("npm run build")
+            ['npm run']
+            >>> parser.extract_command_prefixes("ls -la")
+            []
+        """
+        if not command or not command.strip():
+            return []
+
+        # Parse command to AST
+        tree = self.parser.parse(bytes(command, "utf8"))
+        root = tree.root_node
+
+        # Split compound commands
+        subcommands = self.split_compound_command(root, command)
+
+        # Extract prefixes from each subcommand
+        prefixes = []
+        seen = set()
+
+        for subcmd in subcommands[:max_prefixes]:
+            prefix = self._extract_command_prefix(subcmd)
+            if prefix and prefix not in seen:
+                prefixes.append(prefix)
+                seen.add(prefix)
+
+            if len(prefixes) >= max_prefixes:
+                break
+
+        return prefixes
+
+    def split_compound_command(self, root: Node, command: str) -> List[str]:
+        """Split compound commands using tree-sitter for precise parsing.
+
+        Recognizes: &&, ||, ;, |
+
+        Args:
+            root (`Node`):
+                The root AST node
+            command (`str`):
+                The original command string
+
+        Returns:
+            `List[str]`:
+                List of individual subcommands
+        """
+        subcommands = []
+
+        def extract_commands(node: Node) -> None:
+            """Recursively extract commands from AST."""
+            if node.type == "command":
+                # Extract command text
+                cmd_text = command[node.start_byte : node.end_byte]
+                subcommands.append(cmd_text)
+            elif node.type in ["list", "pipeline", "command_list"]:
+                # Recursively process compound structures
+                for child in node.children:
+                    if child.type not in ["&&", "||", ";", "|", "|&"]:
+                        extract_commands(child)
+            else:
+                # Continue traversing
+                for child in node.children:
+                    extract_commands(child)
+
+        extract_commands(root)
+        return subcommands if subcommands else [command]
+
+    def _extract_command_prefix(
+        self,
+        subcmd: str,
+    ) -> Optional[str]:
+        """Extract command prefix (first two words) from a subcommand.
+
+        Logic:
+        1. Skip safe environment variable assignments
+        2. Extract command name and first subcommand
+        3. Verify the second word looks like a subcommand (not a flag)
+
+        Args:
+            subcmd (`str`):
+                The subcommand string to extract prefix from
+
+        Returns:
+            `Optional[str]`:
+                Command prefix (e.g., "npm run") or None if cannot extract
+        """
+        # Parse the subcommand
+        tree = self.parser.parse(bytes(subcmd, "utf8"))
+        root = tree.root_node
+
+        # Find the first simple_command node
+        simple_cmd = self._find_first_simple_command(root)
+        if not simple_cmd:
+            return None
+
+        # Extract command parts
+        parts = []
+        env_vars = []
+
+        for child in simple_cmd.children:
+            if child.type == "variable_assignment":
+                # Environment variable assignment
+                var_name = subcmd[child.start_byte : child.end_byte].split(
+                    "=",
+                )[0]
+                env_vars.append(var_name)
+            elif child.type == "command_name":
+                # Command name
+                parts.append(subcmd[child.start_byte : child.end_byte])
+            elif child.type == "word" and len(parts) >= 1:
+                # Argument (might be a flag or subcommand)
+                word = subcmd[child.start_byte : child.end_byte]
+                parts.append(word)
+                # Stop after we have command + first argument
+                if len(parts) >= 2:
+                    break
+
+        # Check if environment variables are safe
+        if env_vars and not all(v in SAFE_ENV_VARS for v in env_vars):
+            return None
+
+        # Check if the command is a safe command that doesn't need permission
+        if parts and parts[0].lower() in SAFE_COMMANDS:
+            return None
+
+        # Return first two words
+        if len(parts) >= 2:
+            return " ".join(parts[:2])
+
+        return None
+
+    def _find_first_simple_command(self, node: Node) -> Optional[Node]:
+        """Recursively find the first command node in AST.
+
+        Args:
+            node (`Node`):
+                The AST node to search from
+
+        Returns:
+            `Optional[Node]`:
+                The first command node found, or None
+        """
+        if node.type == "command":
+            return node
+
+        for child in node.children:
+            result = self._find_first_simple_command(child)
+            if result:
+                return result
+
+        return None
+
+    def check_dangerous_command(self, command: str) -> Optional[str]:
+        """Check if command contains dangerous patterns.
+
+        Uses word-boundary aware matching to avoid false positives like
+        'git add' matching 'dd' pattern.
+
+        Args:
+            command (`str`):
+                The bash command to check
+
+        Returns:
+            `Optional[str]`:
+                The matched dangerous pattern if found, None otherwise
+        """
+
+        # Normalize command for matching
+        normalized = " ".join(command.split())
+
+        # Check each dangerous pattern
+        for pattern in DANGEROUS_COMMANDS:
+            # For single-word patterns like "dd", use word boundary matching
+            # to avoid false positives (e.g., "git add" shouldn't match "dd")
+            if " " not in pattern and len(pattern) <= 4:
+                # Single word pattern - use word boundaries
+                regex = r"\b" + re.escape(pattern) + r"\b"
+                if re.search(regex, normalized):
+                    return pattern
+            else:
+                # Multi-word pattern or longer pattern - use substring match
+                if pattern in normalized:
+                    return pattern
+
+        return None
+
+    # pylint: disable=too-many-return-statements, too-many-branches
+    def check_sed_constraints(
+        self,
+        command: str,
+        dangerous_files: List[str],
+    ) -> str | None:
+        """Check if sed command violates safety constraints.
+
+        Implements allowlist/denylist system:
+        - Allowlist: Line printing (sed -n 'Np') and substitution (sed 's///')
+        - Denylist: Dangerous operations (w/W/e/E), file writes, command
+         execution
+
+        Args:
+            command: The bash command to check
+            dangerous_files: List of dangerous file patterns
+
+        Returns:
+            Error message if dangerous sed operation found, None otherwise
+        """
+
+        if "sed" not in command:
+            return None
+
+        # Parse command using shlex
+        try:
+            tokens = shlex.split(command)
+        except ValueError:
+            return "sed command has invalid shell syntax"
+
+        # Find sed command position
+        sed_idx = None
+        for i, token in enumerate(tokens):
+            if token == "sed" or token.endswith("/sed"):
+                sed_idx = i
+                break
+
+        if sed_idx is None:
+            return None
+
+        # Extract flags and expressions
+        args = tokens[sed_idx + 1 :]
+        flags = []
+        expressions = []
+        file_args = []
+        i = 0
+        found_first_expr = False
+
+        while i < len(args):
+            arg = args[i]
+
+            # Handle flags
+            if arg.startswith("-") and not arg.startswith("--"):
+                # Combined flags like -nE
+                flag_chars = arg[1:]
+                for char in flag_chars:
+                    flags.append(char)
+                # -i flag may have optional backup extension argument
+                # But only skip if next arg doesn't look like an expression
+                if "i" in flag_chars and i + 1 < len(args):
+                    next_arg = args[i + 1]
+                    # Skip backup extension only if it's not an expression
+                    # or file
+                    if (
+                        not next_arg.startswith("-")
+                        and not next_arg.startswith("s")
+                        and "." not in next_arg
+                    ):
+                        i += 1  # Skip backup extension
+            elif arg == "--in-place":
+                flags.append("i")
+                if i + 1 < len(args):
+                    next_arg = args[i + 1]
+                    if (
+                        not next_arg.startswith("-")
+                        and not next_arg.startswith("s")
+                        and "." not in next_arg
+                    ):
+                        i += 1
+            elif arg in ["-e", "--expression"]:
+                if i + 1 < len(args):
+                    expressions.append(args[i + 1])
+                    i += 1
+            elif not arg.startswith("-"):
+                # First non-flag, non-option arg is expression (if no -e used)
+                if not found_first_expr:
+                    expressions.append(arg)
+                    found_first_expr = True
+                else:
+                    file_args.append(arg)
+
+            i += 1
+
+        # If no expressions found, command is invalid
+        if not expressions:
+            return "sed command missing expression"
+
+        # Validate flags - only allow specific flags
+        allowed_flags = {"n", "E", "e", "i"}
+        for flag in flags:
+            if flag not in allowed_flags:
+                return f"sed flag -{flag} not allowed"
+
+        # Check allowlist patterns
+        has_n_flag = "n" in flags
+        has_i_flag = "i" in flags
+
+        for expr in expressions:
+            # Denylist checks first - dangerous operations
+            # Check for write operations (w, W) - must be at end or followed
+            # by space/filename
+            if (
+                re.search(r"/[wW]\s+\S+", expr)
+                or expr.endswith("/w")
+                or expr.endswith("/W")
+            ):
+                return "sed write operation (w/W) not allowed"
+
+            # Check for execute operations (e, E) - must be at end or
+            # followed by space
+            if (
+                re.search(r"/[eE](?:\s|$)", expr)
+                or expr.endswith("/e")
+                or expr.endswith("/E")
+            ):
+                return "sed execute operation (e/E) not allowed"
+
+            # Check for dangerous patterns
+            if "{" in expr or "}" in expr:
+                return "sed curly braces not allowed"
+            if expr.startswith("!"):
+                return "sed negation (!) not allowed"
+            if "#" in expr and not expr.startswith("s#"):
+                return "sed comments not allowed"
+
+            # Pattern 1: Line printing with -n flag (sed -n 'Np' or 'N,Mp')
+            if has_n_flag:
+                # Match: number followed by 'p', or range 'N,Mp'
+                if re.match(
+                    r"^\d+p$",
+                    expr,
+                ) or re.match(
+                    r"^\d+,\d+p$",
+                    expr,
+                ):
+                    continue
+
+            # Pattern 2: Substitution command
+            # (sed 's/pattern/replacement/flags')
+            if (
+                expr.startswith("s/")
+                or expr.startswith("s|")
+                or expr.startswith("s#")
+            ):
+                delimiter = expr[1]
+                parts = expr[2:].split(delimiter)
+                if len(parts) >= 2:
+                    # Valid substitution
+                    # Check substitution flags (g, p, number, etc.)
+                    if len(parts) > 2:
+                        sub_flags = parts[2]
+                        # Allow common substitution flags
+                        if all(c in "gp0123456789" for c in sub_flags):
+                            continue
+                    else:
+                        continue
+
+            # If we reach here, expression doesn't match allowlist
+            return f"sed expression '{expr}' not in allowlist"
+
+        # Check -i flag with dangerous files
+        if has_i_flag and file_args:
+            for file_path in file_args:
+                for dangerous_file in dangerous_files:
+                    if dangerous_file in file_path or file_path.endswith(
+                        dangerous_file,
+                    ):
+                        return f"sed -i modifying dangerous file: {file_path}"
+
+        return None
+
+    def check_injection_risk(self, command: str) -> Optional[str]:
+        """Check if command contains structures that cannot be statically
+        analyzed.
+
+        This detects command substitution, process substitution, complex
+        expansions, control flow, and other dynamic shell features that
+        make it impossible to determine the command's behavior without
+        execution.
+
+        Args:
+            command (`str`):
+                The bash command to check
+
+        Returns:
+            `Optional[str]`:
+                Reason string if command is too complex, None if it can be
+                statically analyzed
+
+        Examples:
+            >>> parser.check_injection_risk("ls -la")
+            None
+            >>> parser.check_injection_risk("rm $(find . -name '*.tmp')")
+            "Command contains command_substitution which cannot be statically
+            analyzed"
+            >>> parser.check_injection_risk("for f in *.txt; do cat $f; done")
+            "Command contains for_statement which cannot be statically
+            analyzed"
+        """
+
+        try:
+            tree = self.parser.parse(bytes(command, "utf8"))
+            return self._walk_for_dangerous_nodes(tree.root_node)
+        except Exception:
+            # If parsing fails, be conservative and require review
+            return "Command parsing failed, cannot verify safety"
+
+    def _walk_for_dangerous_nodes(self, node: Node) -> Optional[str]:
+        """Recursively walk AST to find dangerous node types.
+
+        Args:
+            node (`Node`):
+                The AST node to check
+
+        Returns:
+            `Optional[str]`:
+                Reason string if dangerous node found, None otherwise
+        """
+
+        # Check if this node is a dangerous type
+        if node.type in DANGEROUS_NODE_TYPES:
+            return (
+                f"Command contains {node.type} which cannot be "
+                f"statically analyzed"
+            )
+
+        # Recursively check children
+        for child in node.children:
+            result = self._walk_for_dangerous_nodes(child)
+            if result:
+                return result
+
+        return None
diff --git a/src/agentscope/tool/_builtin/_edit.py b/src/agentscope/tool/_builtin/_edit.py
new file mode 100644
index 0000000..962b680
--- /dev/null
+++ b/src/agentscope/tool/_builtin/_edit.py
@@ -0,0 +1,416 @@
+# -*- coding: utf-8 -*-
+"""The edit tool in agentscope."""
+import difflib
+import fnmatch
+from typing import Any, List
+
+from .._base import ToolBase, ToolMiddlewareBase
+from .._constants import (
+    DEFAULT_DANGEROUS_FILES,
+    DEFAULT_DANGEROUS_DIRECTORIES,
+)
+from ...permission import (
+    PermissionContext,
+    PermissionDecision,
+    PermissionBehavior,
+    PermissionMode,
+    PermissionRule,
+)
+from .._response import ToolChunk
+from ...message import TextBlock, ToolResultState
+from ...state import AgentState
+from ._backend import BackendBase, _normalize_newlines
+
+
+class Edit(ToolBase):
+    """The edit tool for performing exact string replacements in files."""
+
+    name: str = "Edit"
+    """The tool name presented to the agent."""
+
+    description: str = """Performs exact string replacements in files.
+
+Usage:
+- You must use your `Read` tool at least once in the conversation
+  before editing. This tool will error if you attempt an edit without
+  reading the file.
+- When editing text from Read tool output, ensure you preserve the
+  exact indentation (tabs/spaces) as it appears AFTER the line number
+  prefix. The line number prefix format is: line number + tab.
+  Everything after that is the actual file content to match. Never
+  include any part of the line number prefix in the old_string or
+  new_string.
+- ALWAYS prefer editing existing files in the codebase. NEVER write
+  new files unless explicitly required.
+- Only use emojis if the user explicitly requests it. Avoid adding
+  emojis to files unless asked.
+- The edit will FAIL if `old_string` is not unique in the file."""  # noqa: E501
+    """The description presented to the agent."""
+
+    input_schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {
+            "file_path": {
+                "type": "string",
+                "description": "The absolute path to the file to edit.",
+            },
+            "old_string": {
+                "type": "string",
+                "description": (
+                    "The exact string to replace. Must match exactly "
+                    "including whitespace and indentation."
+                ),
+            },
+            "new_string": {
+                "type": "string",
+                "description": "The string to replace old_string with.",
+            },
+            "replace_all": {
+                "type": "boolean",
+                "description": (
+                    "If true, replace all occurrences. If false "
+                    "(default), only replace if there is exactly one "
+                    "occurrence."
+                ),
+                "default": False,
+            },
+        },
+        "required": ["file_path", "old_string", "new_string"],
+    }
+
+    is_mcp: bool = False
+    is_read_only: bool = False
+    is_concurrency_safe: bool = False
+    is_external_tool: bool = False
+    is_state_injected: bool = True
+
+    def __init__(  # pylint: disable=dangerous-default-value
+        self,
+        dangerous_files: list[str] = DEFAULT_DANGEROUS_FILES,
+        dangerous_directories: list[str] = DEFAULT_DANGEROUS_DIRECTORIES,
+        middlewares: List[ToolMiddlewareBase] | None = None,
+        backend: BackendBase | None = None,
+    ) -> None:
+        """Initialize the edit tool.
+
+        Args:
+            dangerous_files (`list[str]`, optional):
+                Sensitive files that require explicit user confirmation,
+                even in BYPASS mode. Matched by basename
+                (case-insensitive). Defaults to `DEFAULT_DANGEROUS_FILES`.
+                Pass a custom list to fully replace the defaults, or `[]`
+                to disable the filename check.
+            dangerous_directories (`list[str]`, optional):
+                Sensitive directories that require explicit user
+                confirmation. Matched when any path segment equals an
+                entry (case-insensitive). Defaults to
+                `DEFAULT_DANGEROUS_DIRECTORIES`. Pass a custom list to
+                fully replace the defaults, or `[]` to disable the
+                directory check.
+            middlewares (`List[ToolMiddlewareBase] | None`, optional):
+                Tool middlewares wrapping the tool execution.
+            backend (`BackendBase | None`, optional):
+                The sandbox backend to use for file I/O. When ``None``,
+                a :class:`LocalBackend` is created.
+        """
+        from ._backend import LocalBackend
+
+        super().__init__(middlewares=middlewares)
+        self.dangerous_files = list(dangerous_files)
+        self.dangerous_directories = list(dangerous_directories)
+        self._backend = backend or LocalBackend()
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        """Check permissions for file editing.
+
+        This method implements Edit-specific permission checks:
+        1. Dangerous path check (safety check, bypass-immune)
+        2. ACCEPT_EDITS mode check for files in working directories
+
+        Args:
+            tool_input (`dict[str, Any]`):
+                The tool input containing "file_path" key
+            context (`PermissionContext`):
+                The permission context with mode and rules
+
+        Returns:
+            `PermissionDecision`:
+                ASK for dangerous paths, ALLOW for safe operations in
+                ACCEPT_EDITS mode, PASSTHROUGH otherwise
+        """
+
+        file_path = tool_input.get("file_path")
+        if not file_path:
+            return PermissionDecision(
+                behavior=PermissionBehavior.PASSTHROUGH,
+                message="No file path provided",
+            )
+
+        # 1. Check for dangerous paths (safety check, bypass-immune)
+        if self._is_dangerous_path(file_path):
+            return PermissionDecision(
+                behavior=PermissionBehavior.ASK,
+                message=f"Permission required: Edit operation on "
+                f"sensitive file {file_path}",
+                decision_reason="Safety check: dangerous file or directory",
+                bypass_immune=True,
+            )
+
+        # 2. Check ACCEPT_EDITS mode for files in working directories
+        if context.mode == PermissionMode.ACCEPT_EDITS:
+            if self._path_in_allowed_working_path(file_path, context):
+                return PermissionDecision(
+                    behavior=PermissionBehavior.ALLOW,
+                    message=f"Permission granted for editing {file_path} "
+                    f"(accept edits mode - in working directory)",
+                    decision_reason="File is in working directory and not "
+                    "a dangerous path",
+                )
+
+        # 3. Return PASSTHROUGH to let PermissionEngine check allow rules
+        # This ensures allow rules can grant Edit permissions
+        return PermissionDecision(
+            behavior=PermissionBehavior.PASSTHROUGH,
+            message="",
+        )
+
+    async def match_rule(
+        self,
+        rule_content: str | None,
+        tool_input: dict[str, Any],
+    ) -> bool:
+        """Check if a permission rule matches the file path.
+
+        Matches rule_content as a glob pattern against the "file_path"
+        parameter using fnmatch. If rule_content is None, matches all
+        invocations (tool-name-level rule).
+
+        Args:
+            rule_content (`str | None`):
+                Glob pattern to match against the file path (e.g., "src/**"),
+                or None to match all invocations
+            tool_input (`dict[str, Any]`):
+                The tool input data containing "file_path" key
+
+        Returns:
+            `bool`:
+                True if the glob pattern matches the file path, False otherwise
+        """
+        if rule_content is None:
+            return True
+
+        file_path = tool_input.get("file_path", "")
+        if not file_path:
+            return False
+        return fnmatch.fnmatch(file_path, rule_content)
+
+    async def generate_suggestions(
+        self,
+        tool_input: dict[str, Any],
+    ) -> List[PermissionRule]:
+        """Generate suggested permission rules for the file path.
+
+        Suggests a glob pattern covering the parent directory of the file,
+        allowing the user to grant permission for the entire directory at once.
+
+        Args:
+            tool_input (`dict[str, Any]`):
+                The tool input data containing "file_path" key
+
+        Returns:
+            `List[PermissionRule]`:
+                A single suggested rule covering the parent directory
+                (e.g., file "/src/main.py" -> rule "src/**")
+        """
+        file_path = tool_input.get("file_path", "")
+        if not file_path:
+            return []
+
+        parent = self._backend.dirname(file_path)
+        # Glob patterns are POSIX-style strings (matched by fnmatch),
+        # not real filesystem paths — do NOT use backend.join_path here.
+        pattern = (parent.rstrip("/\\") + "/**") if parent else "**"
+
+        return [
+            PermissionRule(
+                tool_name=self.name,
+                rule_content=pattern,
+                behavior=PermissionBehavior.ALLOW,
+                source="suggested",
+            ),
+        ]
+
+    async def call(  # type: ignore[override]
+        self,
+        file_path: str,
+        old_string: str,
+        new_string: str,
+        replace_all: bool = False,
+        _agent_state: AgentState | None = None,
+    ) -> ToolChunk:
+        """Execute the edit and return the result."""
+        # Validate file_path is absolute
+        if not self._backend.isabs(file_path):
+            return ToolChunk(
+                content=[
+                    TextBlock(
+                        text=(
+                            f"Error: file_path must be an absolute "
+                            f"path, got: {file_path}"
+                        ),
+                    ),
+                ],
+                state=ToolResultState.ERROR,
+                is_last=True,
+            )
+
+        # Check file exists
+        if not await self._backend.file_exists(file_path):
+            return ToolChunk(
+                content=[
+                    TextBlock(text=f"Error: File not found: {file_path}"),
+                ],
+                state=ToolResultState.ERROR,
+                is_last=True,
+            )
+
+        # Check old_string != new_string
+        if old_string == new_string:
+            return ToolChunk(
+                content=[
+                    TextBlock(
+                        text=(
+                            "Error: old_string and new_string are "
+                            "identical. No changes to make."
+                        ),
+                    ),
+                ],
+                state=ToolResultState.ERROR,
+                is_last=True,
+            )
+
+        content = None
+        if _agent_state is not None:
+            cache = await _agent_state.tool_context.get_cache(file_path)
+            if cache is None:
+                # Haven't read this file before
+                return ToolChunk(
+                    content=[
+                        TextBlock(
+                            text="Error: To edit a file, you must first read "
+                            "it using the Read tool.",
+                        ),
+                    ],
+                    state=ToolResultState.ERROR,
+                    is_last=True,
+                )
+            content = "".join(cache.lines)
+        else:
+            # No state provided, read from backend
+            try:
+                raw = await self._backend.read_file(file_path)
+                # Normalize CRLF/CR to match the cached-content path and
+                # the LF-based old_string the caller supplies.
+                content = _normalize_newlines(
+                    raw.decode("utf-8", errors="replace"),
+                )
+            except Exception as e:
+                return ToolChunk(
+                    content=[TextBlock(text=f"Error reading file: {str(e)}")],
+                    state=ToolResultState.ERROR,
+                    is_last=True,
+                )
+
+        # Count occurrences
+        occurrences = content.count(old_string)
+
+        # If occurrences == 0, raise error
+        if occurrences == 0:
+            return ToolChunk(
+                content=[
+                    TextBlock(
+                        text=f"Error: old_string not found in {file_path}",
+                    ),
+                ],
+                state=ToolResultState.ERROR,
+                is_last=True,
+            )
+
+        # If occurrences > 1 and not replace_all, raise error
+        if occurrences > 1 and not replace_all:
+            return ToolChunk(
+                content=[
+                    TextBlock(
+                        text=(
+                            f"Error: old_string appears {occurrences} "
+                            f"times in {file_path}. Set replace_all=true "
+                            f"to replace all occurrences, or make "
+                            f"old_string more specific."
+                        ),
+                    ),
+                ],
+                state=ToolResultState.ERROR,
+                is_last=True,
+            )
+
+        # Perform replacement
+        if replace_all:
+            updated_content = content.replace(old_string, new_string)
+        else:
+            updated_content = content.replace(
+                old_string,
+                new_string,
+                1,
+            )
+
+        # Write updated content back to file via backend
+        try:
+            await self._backend.write_file(
+                file_path,
+                updated_content.encode("utf-8"),
+            )
+        except Exception as e:
+            return ToolChunk(
+                content=[TextBlock(text=f"Error writing file: {str(e)}")],
+                state=ToolResultState.ERROR,
+                is_last=True,
+            )
+
+        # Return success message
+        replacement_msg = (
+            f"all {occurrences} occurrences" if replace_all else "1 occurrence"
+        )
+
+        # Build a unified diff of the change with absolute line numbers so the
+        # web UI can render it with real line numbers and proper inter-hunk
+        # gaps. The diff is kept in ``metadata`` only (not in the textual
+        # output) so it does not bloat the LLM context.
+        diff_text = "".join(
+            difflib.unified_diff(
+                content.splitlines(keepends=True),
+                updated_content.splitlines(keepends=True),
+                fromfile=f"a/{file_path}",
+                tofile=f"b/{file_path}",
+                n=3,
+            ),
+        )
+
+        return ToolChunk(
+            content=[
+                TextBlock(
+                    text=f"Successfully replaced {replacement_msg} "
+                    f"in {file_path}",
+                ),
+            ],
+            state=ToolResultState.RUNNING,
+            is_last=True,
+            metadata={
+                "diff": diff_text,
+                "file_path": file_path,
+                "occurrences": occurrences if replace_all else 1,
+            },
+        )
diff --git a/src/agentscope/tool/_builtin/_glob.py b/src/agentscope/tool/_builtin/_glob.py
new file mode 100644
index 0000000..f5261c1
--- /dev/null
+++ b/src/agentscope/tool/_builtin/_glob.py
@@ -0,0 +1,305 @@
+# -*- coding: utf-8 -*-
+"""The glob tool in agentscope."""
+
+from __future__ import annotations
+
+import fnmatch
+import json
+import sys
+from typing import TYPE_CHECKING, Any, List
+
+from ...message import TextBlock, ToolResultState
+from ...permission import (
+    PermissionBehavior,
+    PermissionContext,
+    PermissionDecision,
+    PermissionRule,
+)
+from .._base import ToolBase, ToolMiddlewareBase
+from .._response import ToolChunk
+
+if TYPE_CHECKING:
+    from ._backend import BackendBase
+
+
+def _default_glob_helper_path() -> str:
+    """Resolve the on-disk path of the bundled ``_glob_helper.py`` script.
+
+    Used by :class:`Glob` when no explicit ``glob_helper_path`` is
+    provided (i.e. the local-workspace case). The path is obtained via
+    :mod:`importlib.resources` so it works for both editable and
+    installed packages.
+    """
+    import importlib.resources as _res
+
+    ref = _res.files("agentscope.tool._builtin._scripts").joinpath(
+        "_glob_helper.py",
+    )
+    # as_posix() on a MultiplexedPath / PosixPath gives a str path
+    return str(ref)
+
+
+class Glob(ToolBase):
+    """The glob tool for fast file pattern matching."""
+
+    name: str = "Glob"
+    """The tool name presented to the agent."""
+
+    description: str = """Fast file pattern matching tool that works with
+any codebase size.
+
+Supports glob patterns like "**/*.js" or "src/**/*.ts" and returns
+matching file paths sorted by modification time (newest first).
+
+Use this tool when you need to find files by pattern across the
+codebase."""  # ignore: E501
+    """The description presented to the agent."""
+
+    input_schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {
+            "pattern": {
+                "type": "string",
+                "description": "The glob pattern to match against "
+                "(e.g., '**/*.py', 'src/**/*.ts')",
+            },
+            "path": {
+                "type": "string",
+                "description": "The base directory to search from "
+                "(defaults to current working directory)",
+            },
+        },
+        "required": ["pattern"],
+    }
+
+    is_mcp: bool = False
+    is_read_only: bool = True
+    is_concurrency_safe: bool = True
+    is_external_tool: bool = False
+    is_state_injected: bool = False
+
+    def __init__(
+        self,
+        backend: BackendBase | None = None,
+        glob_helper_path: str | None = None,
+        middlewares: List[ToolMiddlewareBase] | None = None,
+    ) -> None:
+        """Initialize the glob tool.
+
+        Args:
+            middlewares (`List[ToolMiddlewareBase] | None`, optional):
+                Tool middlewares wrapping the tool execution.
+            backend (`BackendBase | None`, optional):
+                The sandbox backend to use. When ``None``, a
+                :class:`LocalBackend` is created automatically.
+            glob_helper_path (`str | None`, optional):
+                Filesystem path (inside the backend's environment) to
+                the ``_glob_helper.py`` script. When ``None``, the
+                path is resolved from the installed package resources
+                (suitable for :class:`LocalBackend`). Remote backends
+                (Docker, E2B) should pass the path where the script
+                was deployed during workspace initialization.
+        """
+        from ._backend import LocalBackend
+
+        super().__init__(middlewares=middlewares)
+        self._backend = backend or LocalBackend()
+        # When running against the host, invoke the helper with the
+        # current interpreter (``sys.executable``) rather than assuming
+        # ``python3`` is on PATH.
+        self._is_local = isinstance(self._backend, LocalBackend)
+        self._glob_helper_path = (
+            glob_helper_path
+            if glob_helper_path is not None
+            else _default_glob_helper_path()
+        )
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        """Check permissions for glob pattern matching.
+
+        Glob is a read-only tool. Return PASSTHROUGH to let the engine
+        handle EXPLORE mode and rule matching.
+        """
+        return PermissionDecision(
+            behavior=PermissionBehavior.PASSTHROUGH,
+            message="Glob pattern matching is read-only.",
+        )
+
+    async def match_rule(
+        self,
+        rule_content: str | None,
+        tool_input: dict[str, Any],
+    ) -> bool:
+        """Check if a permission rule matches the glob pattern or path.
+
+        Matches rule_content as a glob pattern against the "pattern" or "path"
+        parameters. This allows rules to match either the search pattern itself
+        or the directory being searched. If rule_content is None, matches all
+        invocations (tool-name-level rule).
+
+        Args:
+            rule_content (`str | None`):
+                Glob pattern to match (e.g., "src/**" to match searches in
+                src), or None to match all invocations
+            tool_input (`dict[str, Any]`):
+                The tool input data containing "pattern" and optional "path"
+
+        Returns:
+            `bool`:
+                True if the rule matches the pattern or path, False otherwise
+        """
+        # None = tool-name-level rule, matches everything
+        if rule_content is None:
+            return True
+
+        # Try matching against the search path first
+        path = tool_input.get("path", "")
+        if path and fnmatch.fnmatch(path, rule_content):
+            return True
+
+        # Fall back to matching against the pattern itself
+        pattern = tool_input.get("pattern", "")
+        if pattern and fnmatch.fnmatch(pattern, rule_content):
+            return True
+
+        return False
+
+    async def generate_suggestions(
+        self,
+        tool_input: dict[str, Any],
+    ) -> List[PermissionRule]:
+        """Generate suggested permission rules for the glob search.
+
+        Suggests a rule based on the search path. If no path is provided,
+        suggests a rule for the current directory.
+
+        Args:
+            tool_input (`dict[str, Any]`):
+                The tool input data containing optional "path" key
+
+        Returns:
+            `List[PermissionRule]`:
+                A single suggested rule covering the search directory
+        """
+        backend_cwd = await self._backend.getcwd()
+        path = tool_input.get("path") or backend_cwd
+
+        # Normalize path and build a glob pattern. Glob patterns are
+        # POSIX-style strings (matched by fnmatch), not real filesystem
+        # paths — do NOT use backend.join_path here.
+        abs_path = self._backend.abspath(path, cwd=backend_cwd)
+        pattern = abs_path.rstrip("/\\") + "/**"
+
+        return [
+            PermissionRule(
+                tool_name=self.name,
+                rule_content=pattern,
+                behavior=PermissionBehavior.ALLOW,
+                source="suggested",
+            ),
+        ]
+
+    async def call(  # type: ignore[override]
+        self,
+        pattern: str,
+        path: str | None = None,
+    ) -> ToolChunk:
+        """Execute the glob pattern matching and return the results.
+
+        Invokes the standalone ``_glob_helper.py`` script via
+        ``exec_shell``. The script performs high-performance
+        ``os.walk`` + ``os.scandir`` matching and returns results
+        sorted by modification time (newest first) as JSON.
+
+        This unified path works identically across Local, Docker,
+        and E2B backends.
+
+        Args:
+            pattern (`str`):
+                The glob pattern to match against (e.g. ``**/*.py``).
+            path (`str | None`, optional):
+                Base directory to search from. Defaults to the current
+                working directory when ``None``.
+
+        Returns:
+            `ToolChunk`:
+                On success, the matched file paths joined by newlines
+                (or a "no files found" message). If the base directory
+                is missing or the helper fails, an error chunk with
+                ``ToolResultState.ERROR``.
+        """
+        base_dir = path if path else await self._backend.getcwd()
+
+        # The base must be an existing directory; a regular file would
+        # otherwise be accepted here and fail later with a confusing
+        # error from the helper.
+        if not await self._backend.is_dir(base_dir):
+            return ToolChunk(
+                content=[
+                    TextBlock(text=f"Directory not found: {base_dir}"),
+                ],
+                state=ToolResultState.ERROR,
+                is_last=True,
+            )
+
+        # Invoke the glob helper script via exec_shell as an argv list
+        # (run directly, without a shell, so no platform-specific
+        # quoting is needed). Use the current interpreter locally
+        # (``python3`` may be absent, e.g. on Windows or venvs exposing
+        # only ``python``); remote backends run inside Linux images
+        # where ``python3`` is the safe choice.
+        python = sys.executable if self._is_local else "python3"
+        command = [
+            python,
+            self._glob_helper_path,
+            "--pattern",
+            pattern,
+            "--base-dir",
+            base_dir,
+        ]
+        result = await self._backend.exec_shell(command, timeout=30.0)
+
+        # A non-zero exit means the helper itself failed (missing
+        # interpreter/script, permission error, …) — surface it rather
+        # than masking it as an empty match.
+        if not result.ok():
+            stderr = result.stderr.decode("utf-8", errors="replace").strip()
+            return ToolChunk(
+                content=[
+                    TextBlock(
+                        text=f"Glob helper failed: {stderr}"
+                        if stderr
+                        else "Glob helper failed with no error output.",
+                    ),
+                ],
+                state=ToolResultState.ERROR,
+                is_last=True,
+            )
+
+        try:
+            matches = json.loads(
+                result.stdout.decode("utf-8", errors="replace"),
+            )
+        except (json.JSONDecodeError, ValueError):
+            matches = []
+
+        if len(matches) == 0:
+            return ToolChunk(
+                content=[
+                    TextBlock(
+                        text=f"No files found matching pattern: {pattern}",
+                    ),
+                ],
+                state=ToolResultState.RUNNING,
+                is_last=True,
+            )
+
+        return ToolChunk(
+            content=[TextBlock(text="\n".join(matches))],
+            state=ToolResultState.RUNNING,
+            is_last=True,
+        )
diff --git a/src/agentscope/tool/_builtin/_grep.py b/src/agentscope/tool/_builtin/_grep.py
new file mode 100644
index 0000000..e0c7987
--- /dev/null
+++ b/src/agentscope/tool/_builtin/_grep.py
@@ -0,0 +1,488 @@
+# -*- coding: utf-8 -*-
+"""The grep tool in agentscope."""
+import fnmatch
+from typing import Any, List, Literal
+
+from .._base import ToolBase, ToolMiddlewareBase
+from ...permission import (
+    PermissionContext,
+    PermissionDecision,
+    PermissionBehavior,
+    PermissionRule,
+)
+from .._response import ToolChunk
+from ...message import TextBlock, ToolResultState
+from ._backend import BackendBase
+
+# Version control system directories to exclude from searches
+VCS_DIRECTORIES_TO_EXCLUDE = [
+    ".git",
+    ".svn",
+    ".hg",
+    ".bzr",
+    ".jj",
+    ".sl",
+]
+
+# Default cap on grep results when head_limit is unspecified
+DEFAULT_HEAD_LIMIT = 250
+
+
+class RipgrepTimeoutError(Exception):
+    """Custom error class for ripgrep timeouts."""
+
+    def __init__(self, message: str, partial_results: list[str]):
+        super().__init__(message)
+        self.partial_results = partial_results
+
+
+class Grep(ToolBase):
+    """The grep tool for searching file contents using ripgrep."""
+
+    name: str = "Grep"
+    """The tool name presented to the agent."""
+
+    description: str = """A powerful search tool built on ripgrep
+
+  Usage:
+- ALWAYS use Grep for search tasks. NEVER invoke `grep` or `rg` as a Bash command. The Grep tool has been optimized for correct permissions and access.
+- Supports full regex syntax (e.g., "log.*Error", "function\\s+\\w+")
+- Filter files with glob parameter (e.g., "*.js", "**/*.tsx") or type parameter (e.g., "js", "py", "rust")
+- Output modes: "content" shows matching lines, "files_with_matches" shows only file paths (default), "count" shows match counts per file
+- Context lines: use context parameter or -A/-B/-C for lines after/before/around matches
+- Case-insensitive search: set i to true
+- Multiline regex: set multiline to true for patterns spanning multiple lines
+- Limit results: use head_limit to cap the number of results returned"""  # noqa: E501
+    """The description presented to the agent."""
+
+    input_schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {
+            "pattern": {
+                "type": "string",
+                "description": "The regular expression pattern to search "
+                "for in file contents.",
+            },
+            "path": {
+                "type": "string",
+                "description": "File or directory to search in. Defaults "
+                "to current working directory.",
+            },
+            "output_mode": {
+                "type": "string",
+                "enum": ["content", "files_with_matches", "count"],
+                "description": "Output mode: 'content' shows matching lines "
+                "(supports -A/-B/-C context, -n line numbers, "
+                "head_limit), 'files_with_matches' shows file "
+                "paths (supports head_limit), 'count' shows "
+                "match counts (supports head_limit). "
+                "Defaults to 'files_with_matches'.",
+                "default": "files_with_matches",
+            },
+            "glob": {
+                "type": "string",
+                "description": "Glob pattern to filter files (e.g., '*.js', "
+                "'*.{ts,tsx}').",
+            },
+            "type": {
+                "type": "string",
+                "description": "File type to search (rg --type). "
+                "Common types: js, py, rust, go, java, etc.",
+            },
+            "-A": {
+                "type": "integer",
+                "description": "Number of lines to show after each match. "
+                "Requires output_mode: 'content'.",
+            },
+            "-B": {
+                "type": "integer",
+                "description": "Number of lines to show before each match. "
+                "Requires output_mode: 'content'.",
+            },
+            "-C": {
+                "type": "integer",
+                "description": "Alias for context.",
+            },
+            "context": {
+                "type": "integer",
+                "description": "Number of context lines to show before and "
+                "after matches. Requires output_mode: "
+                "'content'.",
+            },
+            "n": {
+                "type": "boolean",
+                "description": "Show line numbers in output. Requires "
+                "output_mode: 'content'. Defaults to true.",
+                "default": True,
+            },
+            "i": {
+                "type": "boolean",
+                "description": "Case insensitive search.",
+                "default": False,
+            },
+            "case_insensitive": {
+                "type": "boolean",
+                "description": "Case insensitive search (alias for i).",
+                "default": False,
+            },
+            "multiline": {
+                "type": "boolean",
+                "description": "Enable multiline mode where . matches "
+                "newlines and patterns can span lines. "
+                "Default: false.",
+                "default": False,
+            },
+            "head_limit": {
+                "type": "integer",
+                "description": "Limit output to first N lines/entries. "
+                "Defaults to 250 when unspecified. "
+                "Pass 0 for unlimited.",
+                "minimum": 0,
+            },
+            "offset": {
+                "type": "integer",
+                "description": "Skip first N lines/entries before applying "
+                "head_limit. Defaults to 0.",
+                "default": 0,
+                "minimum": 0,
+            },
+        },
+        "required": ["pattern"],
+    }
+
+    is_mcp: bool = False
+    is_read_only: bool = True
+    is_concurrency_safe: bool = True
+    is_external_tool: bool = False
+    is_state_injected: bool = False
+
+    def __init__(
+        self,
+        middlewares: List[ToolMiddlewareBase] | None = None,
+        backend: BackendBase | None = None,
+    ) -> None:
+        """Initialize the grep tool.
+
+        Args:
+            middlewares (`List[ToolMiddlewareBase] | None`, optional):
+                Tool middlewares wrapping the tool execution.
+            backend (`BackendBase | None`, optional):
+                The sandbox backend to use for shell execution. When
+                ``None``, a :class:`LocalBackend` is created.
+                Ripgrep is always invoked via ``exec_shell`` so that
+                the same code path works for local, Docker, and E2B
+                backends.
+        """
+        from ._backend import LocalBackend
+
+        super().__init__(middlewares=middlewares)
+        self._backend = backend or LocalBackend()
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        """Check permissions for grep search."""
+        return PermissionDecision(
+            behavior=PermissionBehavior.PASSTHROUGH,
+            message="Grep search is read-only.",
+        )
+
+    async def match_rule(
+        self,
+        rule_content: str | None,
+        tool_input: dict[str, Any],
+    ) -> bool:
+        """Check if a permission rule matches the grep search path.
+
+        Matches rule_content as a glob pattern against the "path" parameter.
+        If no path is given, falls back to the current working directory.
+        If rule_content is None, matches all invocations (tool-name-level
+        rule).
+
+        Args:
+            rule_content (`str | None`):
+                Glob pattern to match against the search path (e.g., "src/**"),
+                or None to match all invocations
+            tool_input (`dict[str, Any]`):
+                The tool input data containing optional "path" key
+
+        Returns:
+            `bool`:
+                True if the glob pattern matches the search path, False
+                otherwise
+        """
+        # None = tool-name-level rule, matches everything
+        if rule_content is None:
+            return True
+
+        path = tool_input.get("path", "")
+        if not path:
+            path = await self._backend.getcwd()
+        return fnmatch.fnmatch(path, rule_content)
+
+    async def generate_suggestions(
+        self,
+        tool_input: dict[str, Any],
+    ) -> List[PermissionRule]:
+        """Generate suggested permission rules for the grep search path.
+
+        Suggests a rule based on the search path. If no path is provided,
+        suggests a rule for the current directory.
+
+        Args:
+            tool_input (`dict[str, Any]`):
+                The tool input data containing optional "path" key
+
+        Returns:
+            `List[PermissionRule]`:
+                A single suggested rule covering the search directory
+        """
+        backend_cwd = await self._backend.getcwd()
+        path = tool_input.get("path") or backend_cwd
+
+        abs_path = self._backend.abspath(path, cwd=backend_cwd)
+        # Glob patterns are POSIX-style strings (matched by fnmatch),
+        # not real filesystem paths — do NOT use backend.join_path here.
+        pattern = abs_path.rstrip("/\\") + "/**"
+
+        return [
+            PermissionRule(
+                tool_name=self.name,
+                rule_content=pattern,
+                behavior=PermissionBehavior.ALLOW,
+                source="suggested",
+            ),
+        ]
+
+    def _apply_head_limit(
+        self,
+        items: list[str],
+        limit: int | None,
+        offset: int = 0,
+    ) -> tuple[list[str], int | None]:
+        """Apply head_limit and offset to a list of items.
+
+        Returns (sliced_items, applied_limit_if_truncated).
+        """
+        if limit == 0:
+            return items[offset:], None
+        effective_limit = limit if limit is not None else DEFAULT_HEAD_LIMIT
+        sliced = items[offset : offset + effective_limit]
+        was_truncated = len(items) - offset > effective_limit
+        return sliced, (effective_limit if was_truncated else None)
+
+    async def _run_ripgrep(
+        self,
+        args: list[str],
+        search_path: str,
+        timeout: int = 30,
+    ) -> list[str]:
+        """Run ripgrep and return output lines.
+
+        Builds an argument vector and dispatches it through
+        ``backend.exec_shell`` (which runs the program directly, without
+        a shell), so the same code path works for local, Docker, and E2B
+        backends and needs no platform-specific argument quoting.
+        """
+        command = ["rg", *args, search_path]
+
+        result = await self._backend.exec_shell(
+            command,
+            timeout=float(timeout),
+        )
+
+        if result.exit_code == -1 and result.stderr == b"timed out":
+            raise RipgrepTimeoutError(
+                f"Ripgrep search timed out after {timeout} seconds. "
+                "Try searching a more specific path or pattern.",
+                [],
+            )
+
+        # returncode 0 = matches found, 1 = no matches
+        if result.exit_code not in (0, 1):
+            error_msg = result.stderr.decode(
+                "utf-8",
+                errors="ignore",
+            ).strip()
+            raise RuntimeError(
+                f"ripgrep error (code {result.exit_code}): {error_msg}",
+            )
+
+        raw = result.stdout.decode("utf-8", errors="ignore")
+
+        lines = [
+            line.rstrip("\r") for line in raw.split("\n") if line.rstrip("\r")
+        ]
+        return lines
+
+    async def call(  # type: ignore[override]
+        self,
+        pattern: str,
+        path: str | None = None,
+        output_mode: Literal[
+            "content",
+            "files_with_matches",
+            "count",
+        ] = "files_with_matches",
+        glob: str | None = None,
+        type: str | None = None,  # pylint: disable=redefined-builtin
+        i: bool = False,
+        case_insensitive: bool = False,
+        context: int | None = None,
+        multiline: bool = False,
+        head_limit: int | None = None,
+        offset: int = 0,
+        n: bool = True,
+        **kwargs: Any,
+    ) -> ToolChunk:
+        """Execute the grep search using ripgrep.
+
+        Args:
+            pattern: The regex pattern to search for
+            path: The directory or file path to search in
+            output_mode: Output mode ('content', 'files_with_matches', 'count')
+            glob: Glob pattern to filter files
+            type: File type to filter by (rg --type)
+            i: Case-insensitive search (rg -i)
+            case_insensitive: Alias for i (backward compatibility)
+            context: Number of context lines around matches
+            multiline: Enable multiline regex matching
+            head_limit: Maximum number of results to return
+            (default 250, 0=unlimited)
+            offset: Skip first N results
+            n: Show line numbers (content mode only, default True)
+            **kwargs: Additional parameters (-A, -B, -C)
+        """
+        search_path = path or await self._backend.getcwd()
+
+        if head_limit is not None and head_limit < 0:
+            return ToolChunk(
+                content=[
+                    TextBlock(text="Error: head_limit must be non-negative."),
+                ],
+                state=ToolResultState.ERROR,
+                is_last=True,
+            )
+
+        if offset < 0:
+            return ToolChunk(
+                content=[
+                    TextBlock(text="Error: offset must be non-negative."),
+                ],
+                state=ToolResultState.ERROR,
+                is_last=True,
+            )
+
+        args: list[str] = ["--hidden"]
+
+        # Exclude VCS directories
+        for vcs_dir in VCS_DIRECTORIES_TO_EXCLUDE:
+            args.extend(["--glob", f"!{vcs_dir}"])
+
+        # Limit line length to prevent base64/minified content
+        args.extend(["--max-columns", "500"])
+
+        # Multiline mode
+        if multiline:
+            args.extend(["-U", "--multiline-dotall"])
+
+        # Case-insensitive (support both i and case_insensitive
+        # for compatibility)
+        if i or case_insensitive:
+            args.append("-i")
+
+        # Output mode flags
+        if output_mode == "files_with_matches":
+            args.append("-l")
+        elif output_mode == "count":
+            args.append("-c")
+
+        # Line numbers (content mode only)
+        if n and output_mode == "content":
+            args.append("-n")
+
+        # Context flags (content mode only)
+        if output_mode == "content":
+            A = kwargs.get("-A")
+            B = kwargs.get("-B")
+            C = kwargs.get("-C")
+
+            if context is not None:
+                args.extend(["-C", str(context)])
+            elif C is not None:
+                args.extend(["-C", str(C)])
+            else:
+                if B is not None:
+                    args.extend(["-B", str(B)])
+                if A is not None:
+                    args.extend(["-A", str(A)])
+
+        # Pattern — use -e if it starts with a dash
+        if pattern.startswith("-"):
+            args.extend(["-e", pattern])
+        else:
+            args.append(pattern)
+
+        # File type filter
+        if type is not None:
+            args.extend(["--type", type])
+
+        # Glob filter
+        if glob is not None:
+            raw_patterns = glob.split()
+            glob_patterns: list[str] = []
+            for raw in raw_patterns:
+                if "{" in raw and "}" in raw:
+                    glob_patterns.append(raw)
+                else:
+                    glob_patterns.extend(p for p in raw.split(",") if p)
+            for gp in glob_patterns:
+                args.extend(["--glob", gp])
+
+        try:
+            results = await self._run_ripgrep(args, search_path)
+        except RipgrepTimeoutError as e:
+            return ToolChunk(
+                content=[TextBlock(text=str(e))],
+                state=ToolResultState.ERROR,
+                is_last=True,
+            )
+        except RuntimeError as e:
+            return ToolChunk(
+                content=[TextBlock(text=str(e))],
+                state=ToolResultState.ERROR,
+                is_last=True,
+            )
+
+        if not results:
+            return ToolChunk(
+                content=[
+                    TextBlock(text=f"No matches found for pattern: {pattern}"),
+                ],
+                state=ToolResultState.SUCCESS,
+                is_last=True,
+            )
+
+        limited, applied_limit = self._apply_head_limit(
+            results,
+            head_limit,
+            offset,
+        )
+
+        suffix = ""
+        if applied_limit is not None:
+            suffix = (
+                f"\n\n[Showing results with pagination = "
+                f"limit: {applied_limit}"
+            )
+            if offset:
+                suffix += f", offset: {offset}"
+            suffix += "]"
+
+        return ToolChunk(
+            content=[TextBlock(text="\n".join(limited) + suffix)],
+            state=ToolResultState.SUCCESS,
+            is_last=True,
+        )
diff --git a/src/agentscope/tool/_builtin/_meta.py b/src/agentscope/tool/_builtin/_meta.py
new file mode 100644
index 0000000..fe0fecf
--- /dev/null
+++ b/src/agentscope/tool/_builtin/_meta.py
@@ -0,0 +1,130 @@
+# -*- coding: utf-8 -*-
+"""The meta tool class."""
+from typing import Any, List
+
+from pydantic import Field, create_model
+from jinja2 import Template
+
+from .._tool_group import ToolGroup
+from ...permission import (
+    PermissionContext,
+    PermissionDecision,
+    PermissionBehavior,
+)
+from .._response import ToolChunk
+from .._base import ToolBase, ToolMiddlewareBase
+from ...exception import DeveloperOrientedException
+from ...message import TextBlock
+from ...state import AgentState
+
+
+class ResetTools(ToolBase):
+    """A meta tool allows agent to self-manage its equipped tools by
+    activating or deactivating tool groups dynamically."""
+
+    name: str = "reset_tools"
+    description: str = (
+        "This tool allows you to reset your equipped tools based on your "
+        "current task requirements. These tools are organized into different "
+        "groups, and you can activate/deactivate them by specifying the "
+        "boolean values for each group in the input.\n\n"
+        "**Important: The input booleans are the final state of their "
+        "corresponding tool groups, not incremental changes.** Any group not "
+        "explicitly set to True will be deactivated, regardless of its "
+        "previous state.\n\n"
+        "**Best practice**: Actively manage your tool groups——activate only "
+        "what you need for the current task, and promptly deactivate groups "
+        "as soon as they are no longer needed to conserve context space.\n\n"
+        "This tool will return the usage instructions for the activated tool "
+        "groups, which you **MUST pay attention to and follow**. You can "
+        "also reuse this tool to re-check the instructions."
+    )
+    is_mcp: bool = False
+    is_read_only: bool = False
+    is_concurrency_safe: bool = True
+    is_external_tool: bool = False
+    is_state_injected: bool = True
+
+    def __init__(
+        self,
+        groups: list[ToolGroup],
+        response_template: str,
+        middlewares: List[ToolMiddlewareBase] | None = None,
+    ) -> None:
+        """Initialize the meta tool with the current tool groups."""
+        super().__init__(middlewares=middlewares)
+        self.groups = groups
+        self.response_template = response_template
+
+    @property
+    def input_schema(self) -> dict[str, Any]:  # type: ignore[override]
+        """Dynamically generate the input schema based on the current
+        available tool groups."""
+        fields = {}
+        for group in self.groups:
+            if group.name == "basic":
+                continue
+            fields[group.name] = (
+                bool,
+                Field(
+                    default=False,
+                    description=group.description,
+                ),
+            )
+
+        model = create_model("_DynamicModel", **fields)
+        schema = model.model_json_schema()
+        return schema
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        """The meta tool is always allowed to be called."""
+        return PermissionDecision(
+            behavior=PermissionBehavior.ALLOW,
+            message="The meta tool is always allowed to be called.",
+        )
+
+    async def call(
+        self,
+        _agent_state: AgentState,
+        **kwargs: Any,
+    ) -> ToolChunk:
+        """Activate or deactivate tool groups based on the input arguments,
+        and return their usage instructions."""
+        if _agent_state is None:
+            raise DeveloperOrientedException(
+                "Error: ResetTools requires state to be provided.",
+            )
+
+        # Deactivate all tool groups first
+        _agent_state.tool_context.activated_groups.clear()
+
+        to_activate = []
+        for key, value in kwargs.items():
+            if not isinstance(value, bool):
+                return ToolChunk(
+                    content=[
+                        TextBlock(
+                            text=f"Invalid arguments: the argument {key} "
+                            f"should be a bool value, but got {type(value)}.",
+                        ),
+                    ],
+                )
+
+            if value:
+                to_activate.append(key)
+
+        _agent_state.tool_context.activated_groups.extend(to_activate)
+
+        template = Template(self.response_template)
+        activated_groups = [_ for _ in self.groups if _.name in to_activate]
+        return ToolChunk(
+            content=[
+                TextBlock(
+                    text=template.render(groups=activated_groups),
+                ),
+            ],
+        )
diff --git a/src/agentscope/tool/_builtin/_read.py b/src/agentscope/tool/_builtin/_read.py
new file mode 100644
index 0000000..9d18006
--- /dev/null
+++ b/src/agentscope/tool/_builtin/_read.py
@@ -0,0 +1,285 @@
+# -*- coding: utf-8 -*-
+"""The read tool in agentscope."""
+import fnmatch
+from typing import Any, List
+
+from .._base import ToolBase, ToolMiddlewareBase
+from ...permission import (
+    PermissionContext,
+    PermissionDecision,
+    PermissionBehavior,
+    PermissionRule,
+)
+from .._response import ToolChunk
+from ...message import TextBlock, ToolResultState
+from ...state import AgentState
+from ._backend import BackendBase, _normalize_newlines
+
+
+class Read(ToolBase):
+    """The read tool."""
+
+    name: str = "Read"
+    """The tool name presented to the agent."""
+
+    # pylint: disable=line-too-long
+    description: str = """Reads a file from the local filesystem. You can access any file directly by using this tool.
+Assume this tool is able to read all files on the machine. If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.
+
+Usage:
+- The file_path parameter must be an absolute path, not a relative path
+- By default, it reads up to 2000 lines starting from the beginning of the file
+- You can optionally specify a line offset and limit (especially handy for long files), but it's recommended to read the whole file by not providing these parameters
+- Results are returned using cat -n format, with line numbers starting at 1
+- This tool allows you to read images (eg PNG, JPG, etc). When reading an image file the contents are presented visually as you're a multimodal LLM.
+- This tool can read PDF files (.pdf). For large PDFs (more than 10 pages), you MUST provide the pages parameter to read specific pages."""  # noqa: E501
+    """The description presented to the agent."""
+
+    input_schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {
+            "file_path": {
+                "type": "string",
+                "description": "The absolute path to the file to read.",
+            },
+            "offset": {
+                "type": "integer",
+                "description": "Optional 1-based line number to start reading "
+                "from (default: 1)",
+                "default": 1,
+                "minimum": 1,
+            },
+            "limit": {
+                "type": "integer",
+                "description": "Optional maximum number of lines to read "
+                "(default: 2000, max: 2000)",
+                "default": 2000,
+                "maximum": 2000,
+                "minimum": 1,
+            },
+        },
+        "required": ["file_path"],
+    }
+
+    is_mcp: bool = False
+    is_read_only: bool = True
+    is_concurrency_safe: bool = True
+    is_external_tool: bool = False
+    is_state_injected: bool = True
+
+    def __init__(
+        self,
+        max_line_characters: int = 2000,
+        middlewares: List[ToolMiddlewareBase] | None = None,
+        backend: BackendBase | None = None,
+    ) -> None:
+        """Initialize the read tool.
+
+        Args:
+            max_line_characters (`int`, defaults to 2000):
+                The maximum number of characters to include for each line when
+                reading files. Lines longer than this will be truncated with
+                a "[truncated]" suffix. This prevents overwhelming the agent
+                with excessively long lines while still providing useful
+                content.
+            middlewares (`List[ToolMiddlewareBase] | None`, optional):
+                Tool middlewares wrapping the tool execution.
+            backend (`BackendBase | None`, optional):
+                The sandbox backend to use for file I/O. When ``None``,
+                a :class:`LocalBackend` is created.
+        """
+        from ._backend import LocalBackend
+
+        super().__init__(middlewares=middlewares)
+        self._max_line_characters = max_line_characters
+        self._backend = backend or LocalBackend()
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        """Check permissions for file reading.
+
+        Read is a read-only tool. In EXPLORE mode the engine already handles
+        the ALLOW via _check_explore_mode, so here we just return PASSTHROUGH
+        to let the engine continue with rule matching.
+        """
+        return PermissionDecision(
+            behavior=PermissionBehavior.PASSTHROUGH,
+            message="File reading is read-only.",
+        )
+
+    async def match_rule(
+        self,
+        rule_content: str | None,
+        tool_input: dict[str, Any],
+    ) -> bool:
+        """Check if a permission rule matches the file path.
+
+        Matches rule_content as a glob pattern against the "file_path"
+        parameter using fnmatch. If rule_content is None, matches all
+        invocations (tool-name-level rule).
+
+        Args:
+            rule_content (`str | None`):
+                Glob pattern to match against the file path (e.g., "src/**"),
+                or None to match all invocations
+            tool_input (`dict[str, Any]`):
+                The tool input data containing "file_path" key
+
+        Returns:
+            `bool`:
+                True if the glob pattern matches the file path, False otherwise
+        """
+        # None = tool-name-level rule, matches everything
+        if rule_content is None:
+            return True
+
+        file_path = tool_input.get("file_path", "")
+        if not file_path:
+            return False
+        return fnmatch.fnmatch(file_path, rule_content)
+
+    async def generate_suggestions(
+        self,
+        tool_input: dict[str, Any],
+    ) -> List[PermissionRule]:
+        """Generate suggested permission rules for the file path.
+
+        Suggests a glob pattern covering the parent directory of the file,
+        allowing the user to grant permission for the entire directory at once.
+
+        Args:
+            tool_input (`dict[str, Any]`):
+                The tool input data containing "file_path" key
+
+        Returns:
+            `List[PermissionRule]`:
+                A single suggested rule covering the parent directory
+                (e.g., file "/src/main.py" -> rule "src/**")
+        """
+        file_path = tool_input.get("file_path", "")
+        if not file_path:
+            return []
+
+        parent = self._backend.dirname(file_path)
+        # Glob patterns are POSIX-style strings (matched by fnmatch),
+        # not real filesystem paths — do NOT use backend.join_path here.
+        pattern = (parent.rstrip("/\\") + "/**") if parent else "**"
+
+        return [
+            PermissionRule(
+                tool_name=self.name,
+                rule_content=pattern,
+                behavior=PermissionBehavior.ALLOW,
+                source="suggested",
+            ),
+        ]
+
+    async def call(  # type: ignore[override]
+        self,
+        file_path: str,
+        offset: int = 1,
+        limit: int = 2000,
+        _agent_state: AgentState | None = None,
+    ) -> ToolChunk:
+        """Read the file and return the content with line numbers."""
+
+        # Validate file_path is absolute
+        if not self._backend.isabs(file_path):
+            return ToolChunk(
+                content=[
+                    TextBlock(
+                        text=f"Error: file_path must be an absolute path, "
+                        f"got: {file_path}",
+                    ),
+                ],
+                state=ToolResultState.ERROR,
+                is_last=True,
+            )
+
+        # Check file exists
+        if not await self._backend.file_exists(file_path):
+            return ToolChunk(
+                content=[
+                    TextBlock(text=f"Error: File does not exist: {file_path}"),
+                ],
+                state=ToolResultState.ERROR,
+                is_last=True,
+            )
+
+        # Check it's not a directory
+        if await self._backend.is_dir(file_path):
+            return ToolChunk(
+                content=[
+                    TextBlock(
+                        text=f"Error: Path is a directory, not a file: "
+                        f"{file_path}",
+                    ),
+                ],
+                state=ToolResultState.ERROR,
+                is_last=True,
+            )
+
+        try:
+            # Read file content via backend
+            lines = None
+            if _agent_state is not None:
+                cache = await _agent_state.tool_context.get_cache(file_path)
+                if cache is not None:
+                    lines = cache.lines
+
+            if lines is None:
+                raw = await self._backend.read_file(file_path)
+                content_str = raw.decode("utf-8", errors="replace")
+                # Normalize CRLF/CR so cached lines end in "\n" regardless
+                # of the platform the file was written on (Windows text
+                # files use "\r\n").
+                content_str = _normalize_newlines(content_str)
+                lines = content_str.splitlines(keepends=True)
+
+                # Cache file if state is provided
+                if _agent_state is not None:
+                    await _agent_state.tool_context.cache_file(
+                        file_path=file_path,
+                        lines=lines,
+                    )
+
+            # Apply offset and limit (offset is 1-based)
+            start_idx = offset - 1
+            end_idx = start_idx + limit
+            selected_lines = lines[start_idx:end_idx]
+
+            # Format with line numbers (6-char padded + tab + content)
+            formatted_lines = []
+            for i, line in enumerate(selected_lines, start=offset):
+                # Remove trailing newline if present
+                line_content = line.rstrip("\n\r")
+
+                # Truncate lines longer than 2000 chars
+                if len(line_content) > self._max_line_characters:
+                    line_content = (
+                        line_content[: self._max_line_characters]
+                        + "[truncated]"
+                    )
+
+                # Format: 6-char padded line number + tab + content
+                formatted_line = f"{i:6d}\t{line_content}"
+                formatted_lines.append(formatted_line)
+
+            # Join all lines
+            result = "\n".join(formatted_lines)
+
+            return ToolChunk(
+                content=[TextBlock(text=result)],
+                state=ToolResultState.RUNNING,
+                is_last=True,
+            )
+
+        except Exception as e:
+            return ToolChunk(
+                content=[TextBlock(text=f"Error reading file: {str(e)}")],
+                state=ToolResultState.ERROR,
+                is_last=True,
+            )
diff --git a/src/agentscope/tool/_builtin/_scripts/__init__.py b/src/agentscope/tool/_builtin/_scripts/__init__.py
new file mode 100644
index 0000000..596df86
--- /dev/null
+++ b/src/agentscope/tool/_builtin/_scripts/__init__.py
@@ -0,0 +1,9 @@
+# -*- coding: utf-8 -*-
+"""Standalone helper scripts shipped as package resources.
+
+Scripts in this package are deployed into remote workspaces (Docker /
+E2B) at initialization time and invoked via ``exec_shell``. They must
+remain importable *without* ``agentscope`` installed — the host reads
+them as raw bytes via :mod:`importlib.resources` and ships them into
+the workspace environment.
+"""
diff --git a/src/agentscope/tool/_builtin/_scripts/_glob_helper.py b/src/agentscope/tool/_builtin/_scripts/_glob_helper.py
new file mode 100644
index 0000000..d6025ec
--- /dev/null
+++ b/src/agentscope/tool/_builtin/_scripts/_glob_helper.py
@@ -0,0 +1,215 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Standalone glob helper script for agentscope builtin tools.
+
+This script is designed to run **without** agentscope installed. It is
+deployed into remote workspaces (Docker / E2B) at initialization time
+and invoked via ``exec_shell`` by the :class:`Glob` tool.
+
+Usage::
+
+    python3 _glob_helper.py --pattern '**/*.py' --base-dir /workspace
+
+Output: a JSON array of matching file paths, sorted by modification
+time (newest first).  Exits with code 0 on success (even when no
+matches are found — the array is simply empty).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+
+# ── glob matching (mirrors the logic from Glob tool) ──────────────
+
+
+def _glob_part_to_regex(part: str) -> re.Pattern[str]:
+    """Convert a single glob pattern segment to a compiled regex.
+
+    Translates glob wildcards (``*`` → ``.*``, ``?`` → ``.``) and
+    escapes regex meta-characters so that a segment like ``*.py``
+    becomes the anchored pattern ``^.*\\.py$``.
+
+    Args:
+        part: One path segment of a glob pattern (e.g. ``*.py``
+            or ``test_*``).
+
+    Returns:
+        A compiled :class:`re.Pattern` anchored with ``^…$``.
+    """
+    regex_str = ""
+    for c in part:
+        if c == "*":
+            regex_str += ".*"
+        elif c == "?":
+            regex_str += "."
+        elif c in ".^$+{}[]|()\\":
+            regex_str += "\\" + c
+        else:
+            regex_str += c
+    return re.compile(f"^{regex_str}$")
+
+
+def _collect_all(current_dir: str, results: list[str]) -> None:
+    """Recursively collect all file paths under *current_dir*.
+
+    Uses :func:`os.walk` to traverse the directory tree.
+    ``PermissionError`` and ``OSError`` are silently ignored so that
+    inaccessible subtrees do not abort the entire glob operation.
+
+    Args:
+        current_dir: Root directory to walk.
+        results: Accumulator list; matched file paths are appended
+            in-place.
+    """
+    try:
+        for root, _dirs, files in os.walk(current_dir):
+            for fname in files:
+                results.append(os.path.join(root, fname))
+    except (PermissionError, OSError):
+        pass
+
+
+def _match_parts(
+    parts: list[str],
+    part_index: int,
+    current_dir: str,
+    results: list[str],
+) -> None:
+    """Recursively match glob pattern *parts* against directory entries.
+
+    Walks the filesystem starting from *current_dir*, consuming one
+    pattern segment per directory level.  The ``**`` segment is handled
+    specially: it matches zero or more intermediate directories by
+    recursing into every subdirectory while keeping the same
+    *part_index*, and also advancing to the next segment in the
+    current directory.
+
+    Args:
+        parts: The glob pattern split into path segments
+            (e.g. ``["src", "**", "*.py"]``).
+        part_index: Index into *parts* indicating which segment is
+            being matched at this recursion level.
+        current_dir: The directory currently being scanned.
+        results: Accumulator list; matched file paths are appended
+            in-place.
+    """
+    if part_index >= len(parts):
+        return
+
+    part = parts[part_index]
+    is_last = part_index == len(parts) - 1
+
+    if part == "**":
+        if is_last:
+            _collect_all(current_dir, results)
+        else:
+            _match_parts(parts, part_index + 1, current_dir, results)
+            try:
+                with os.scandir(current_dir) as entries:
+                    for entry in entries:
+                        if entry.is_dir(follow_symlinks=False):
+                            _match_parts(
+                                parts,
+                                part_index,
+                                entry.path,
+                                results,
+                            )
+            except (PermissionError, OSError):
+                pass
+    else:
+        regex = _glob_part_to_regex(part)
+        try:
+            with os.scandir(current_dir) as entries:
+                for entry in entries:
+                    if regex.match(entry.name):
+                        full_path = entry.path
+                        if is_last:
+                            if entry.is_file(follow_symlinks=False):
+                                results.append(full_path)
+                        elif entry.is_dir(follow_symlinks=False):
+                            _match_parts(
+                                parts,
+                                part_index + 1,
+                                full_path,
+                                results,
+                            )
+        except (PermissionError, OSError):
+            pass
+
+
+def glob_match(pattern: str, base_dir: str) -> list[str]:
+    """Match files against a glob pattern starting from *base_dir*.
+
+    Splits *pattern* on path separators (``/`` or ``\\``) and
+    delegates to :func:`_match_parts` for recursive directory
+    traversal.  Supports ``*`` (any characters within a segment),
+    ``?`` (single character), and ``**`` (zero or more directories).
+
+    Args:
+        pattern: Glob pattern such as ``"**/*.py"`` or
+            ``"src/utils/*.txt"``.
+        base_dir: Absolute path of the directory to search from.
+
+    Returns:
+        A list of absolute file paths that match *pattern*.  The
+        list is unsorted; callers should sort as needed (e.g. by
+        modification time).
+    """
+    results: list[str] = []
+    parts = [p for p in re.split(r"[\\/]+", pattern) if p]
+    _match_parts(parts, 0, base_dir, results)
+    return results
+
+
+# ── entry point ───────────────────────────────────────────────────
+
+
+def main() -> None:
+    """CLI entry point: parse ``--pattern`` and ``--base-dir``, run
+    the glob, and print results as a JSON array to stdout.
+
+    The results are sorted by file modification time (newest first).
+    If *base_dir* does not exist, an empty JSON array ``[]`` is
+    printed and the process exits with code 0.
+    """
+    parser = argparse.ArgumentParser(
+        description="Glob file matching with mtime sorting.",
+    )
+    parser.add_argument(
+        "--pattern",
+        required=True,
+        help="Glob pattern (e.g. '**/*.py')",
+    )
+    parser.add_argument(
+        "--base-dir",
+        required=True,
+        help="Base directory to search from",
+    )
+    args = parser.parse_args()
+
+    if not os.path.isdir(args.base_dir):
+        # Empty result for non-existent directory (caller handles
+        # the "directory not found" error message).
+        json.dump([], sys.stdout)
+        return
+
+    matches = glob_match(args.pattern, args.base_dir)
+
+    # Sort by modification time, newest first.
+    def _mtime(path: str) -> float:
+        try:
+            return os.stat(path).st_mtime
+        except (OSError, FileNotFoundError):
+            return 0.0
+
+    matches.sort(key=_mtime, reverse=True)
+
+    json.dump(matches, sys.stdout)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/src/agentscope/tool/_builtin/_skill.py b/src/agentscope/tool/_builtin/_skill.py
new file mode 100644
index 0000000..44e7055
--- /dev/null
+++ b/src/agentscope/tool/_builtin/_skill.py
@@ -0,0 +1,127 @@
+# -*- coding: utf-8 -*-
+"""The builtin skill viewer tool."""
+from typing import Any, Callable, Awaitable, List
+
+from ...exception import DeveloperOrientedException
+from ...permission import (
+    PermissionContext,
+    PermissionDecision,
+    PermissionBehavior,
+)
+from .._response import ToolChunk
+from .._base import ToolBase, ToolMiddlewareBase
+from ...skill import Skill
+from ...message import TextBlock, ToolResultState
+from ...state import AgentState
+
+
+class SkillViewer(ToolBase):
+    """The builtin skill viewer tool."""
+
+    name: str = "Skill"
+    """The name of the skill viewer tool to the agent."""
+
+    description = (
+        "Retrieve a skill within the conversation. "
+        "When users asks you to perform tasks, check if any of the available "
+        "skills match. "
+        "Skills provide specialized capabilities and domain knowledge."
+    )
+    """The tool description of the skill viewer tool to the agent."""
+
+    input_schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {
+            "skill": {
+                "type": "string",
+                "description": "The exact name of the skill to view. ",
+            },
+        },
+        "required": ["skill"],
+    }
+    """The input schema of the skill viewer tool."""
+
+    is_concurrency_safe: bool = True
+    """The skill viewer is concurrency safe."""
+
+    is_external_tool: bool = False
+    """The skill viewer is not an external tool."""
+
+    is_state_injected: bool = True
+    """The skill viewer require state injection to access the activated tool
+    group."""
+
+    is_read_only: bool = True
+    """The skill viewer is read-only."""
+
+    is_mcp: bool = False
+    """The skill viewer is not an MCP tool."""
+
+    mcp_name: str | None = None
+    """The skill viewer does not belong to any MCP server."""
+
+    def __init__(
+        self,
+        get_skills_method: Callable[..., Awaitable[dict[str, Skill]]],
+        middlewares: List[ToolMiddlewareBase] | None = None,
+    ) -> None:
+        """Initialize the skill viewer with the list of skills.
+
+        Args:
+            get_skills_method (`Callable[..., dict[str, Skill]]`):
+                An async method that returns the current skills of the agent.
+            middlewares (`List[ToolMiddlewareBase] | None`, optional):
+                Tool middlewares wrapping the tool execution.
+        """
+        super().__init__(middlewares=middlewares)
+        self._get_skills_method = get_skills_method
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        """The skill viewer is always allowed to be called."""
+        return PermissionDecision(
+            behavior=PermissionBehavior.ALLOW,
+            message="The skill viewer is always allowed to be called.",
+        )
+
+    async def call(
+        self,
+        skill: str,
+        _agent_state: AgentState,
+    ) -> ToolChunk:
+        """View the details of the skill with the given name.
+
+        Args:
+            skill (`str`):
+                The name of the skill to be viewed.
+
+        Returns:
+            `ToolChunk`:
+                The details of the skill.
+        """
+        if not isinstance(_agent_state, AgentState):
+            raise DeveloperOrientedException(
+                f"Expected AgentState but got {type(_agent_state)} "
+                "instead for the Skill viewer tool.",
+            )
+
+        # View the activated skills
+        skills = await self._get_skills_method(
+            _agent_state.tool_context.activated_groups,
+        )
+        target_skill = skills.get(skill)
+        if not target_skill:
+            return ToolChunk(
+                content=[
+                    TextBlock(
+                        text=f"SkillNotFoundError: Skill '{skill}' "
+                        f"not found.",
+                    ),
+                ],
+                state=ToolResultState.ERROR,
+            )
+
+        return ToolChunk(content=[TextBlock(text=target_skill.markdown)])
diff --git a/src/agentscope/tool/_builtin/_write.py b/src/agentscope/tool/_builtin/_write.py
new file mode 100644
index 0000000..a4fdd11
--- /dev/null
+++ b/src/agentscope/tool/_builtin/_write.py
@@ -0,0 +1,328 @@
+# -*- coding: utf-8 -*-
+"""The write tool in agentscope."""
+import difflib
+import fnmatch
+from pathlib import Path
+from typing import Any, List
+
+from .._base import ToolBase, ToolMiddlewareBase
+from .._constants import (
+    DEFAULT_DANGEROUS_FILES,
+    DEFAULT_DANGEROUS_DIRECTORIES,
+)
+from ...permission import (
+    PermissionContext,
+    PermissionDecision,
+    PermissionBehavior,
+    PermissionMode,
+    PermissionRule,
+)
+from .._response import ToolChunk
+from ...message import TextBlock, ToolResultState
+from ...state import AgentState
+from ._backend import BackendBase
+
+
+class Write(ToolBase):
+    """The write tool."""
+
+    name: str = "Write"
+    """The tool name presented to the agent."""
+
+    # pylint: disable=line-too-long
+    description: str = """Writes a file to the local filesystem.
+
+Usage:
+- This tool will overwrite the existing file if there is one at the provided path.
+- If this is an existing file, you MUST use the Read tool first to read the file's contents. This tool will fail if you did not read the file first.
+- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.
+- NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.
+- Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked."""  # noqa: E501
+    """The description presented to the agent."""
+
+    input_schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {
+            "file_path": {
+                "type": "string",
+                "description": "The absolute path to the file to write "
+                "(must be absolute, not relative)",
+            },
+            "content": {
+                "type": "string",
+                "description": "The content to write to the file",
+            },
+        },
+        "required": ["file_path", "content"],
+    }
+
+    is_mcp: bool = False
+    is_read_only: bool = False
+    is_concurrency_safe: bool = False
+    is_external_tool: bool = False
+    is_state_injected: bool = True
+
+    def __init__(  # pylint: disable=dangerous-default-value
+        self,
+        dangerous_files: list[str] = DEFAULT_DANGEROUS_FILES,
+        dangerous_directories: list[str] = DEFAULT_DANGEROUS_DIRECTORIES,
+        middlewares: List[ToolMiddlewareBase] | None = None,
+        backend: BackendBase | None = None,
+    ) -> None:
+        """Initialize the write tool.
+
+        Args:
+            dangerous_files (`list[str]`, optional):
+                Sensitive files that require explicit user confirmation,
+                even in BYPASS mode. Matched by basename
+                (case-insensitive). Defaults to `DEFAULT_DANGEROUS_FILES`.
+                Pass a custom list to fully replace the defaults, or `[]`
+                to disable the filename check.
+            dangerous_directories (`list[str]`, optional):
+                Sensitive directories that require explicit user
+                confirmation. Matched when any path segment equals an
+                entry (case-insensitive). Defaults to
+                `DEFAULT_DANGEROUS_DIRECTORIES`. Pass a custom list to
+                fully replace the defaults, or `[]` to disable the
+                directory check.
+            middlewares (`List[ToolMiddlewareBase] | None`, optional):
+                Tool middlewares wrapping the tool execution.
+            backend (`BackendBase | None`, optional):
+                The sandbox backend to use for file I/O. When ``None``,
+                a :class:`LocalBackend` is created.
+        """
+        from ._backend import LocalBackend
+
+        super().__init__(middlewares=middlewares)
+        self.dangerous_files = list(dangerous_files)
+        self.dangerous_directories = list(dangerous_directories)
+
+        self._backend = backend or LocalBackend()
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        """Check permissions for file writing.
+
+        This method implements Write-specific permission checks:
+        1. Dangerous path check (safety check, bypass-immune)
+        2. ACCEPT_EDITS mode check for files in working directories
+
+        Args:
+            tool_input (`dict[str, Any]`):
+                The tool input containing "file_path" key
+            context (`PermissionContext`):
+                The permission context with mode and rules
+
+        Returns:
+            `PermissionDecision`:
+                ASK for dangerous paths, ALLOW for safe operations in
+                ACCEPT_EDITS mode, PASSTHROUGH otherwise
+        """
+
+        file_path = tool_input.get("file_path")
+        if not file_path:
+            return PermissionDecision(
+                behavior=PermissionBehavior.PASSTHROUGH,
+                message="No file path provided",
+            )
+
+        # 1. Check for dangerous paths (safety check, bypass-immune)
+        if self._is_dangerous_path(file_path):
+            return PermissionDecision(
+                behavior=PermissionBehavior.ASK,
+                message=f"Permission required: Write operation on "
+                f"sensitive file {file_path}",
+                decision_reason="Safety check: dangerous file or directory",
+                bypass_immune=True,
+            )
+
+        # 2. Check ACCEPT_EDITS mode for files in working directories
+        if context.mode == PermissionMode.ACCEPT_EDITS:
+            if self._path_in_allowed_working_path(file_path, context):
+                return PermissionDecision(
+                    behavior=PermissionBehavior.ALLOW,
+                    message=f"Permission granted for writing {file_path} "
+                    f"(accept edits mode - in working directory)",
+                    decision_reason="File is in working directory and not "
+                    "a dangerous path",
+                )
+
+        # 3. Return PASSTHROUGH to let PermissionEngine check allow rules
+        # This ensures allow rules can grant Write permissions
+        return PermissionDecision(
+            behavior=PermissionBehavior.PASSTHROUGH,
+            message="",
+        )
+
+    async def match_rule(
+        self,
+        rule_content: str | None,
+        tool_input: dict[str, Any],
+    ) -> bool:
+        """Check if a permission rule matches the file path.
+
+        Matches rule_content as a glob pattern against the "file_path"
+        parameter using fnmatch. If rule_content is None, matches all
+        invocations (tool-name-level rule).
+
+        Args:
+            rule_content (`str | None`):
+                Glob pattern to match against the file path (e.g., "src/**"),
+                or None to match all invocations
+            tool_input (`dict[str, Any]`):
+                The tool input data containing "file_path" key
+
+        Returns:
+            `bool`:
+                True if the glob pattern matches the file path, False otherwise
+        """
+        if rule_content is None:
+            return True
+
+        file_path = tool_input.get("file_path", "")
+        if not file_path:
+            return False
+        return fnmatch.fnmatch(file_path, rule_content)
+
+    async def generate_suggestions(
+        self,
+        tool_input: dict[str, Any],
+    ) -> List[PermissionRule]:
+        """Generate suggested permission rules for the file path.
+
+        Suggests a glob pattern covering the parent directory of the file,
+        allowing the user to grant permission for the entire directory at once.
+
+        Args:
+            tool_input (`dict[str, Any]`):
+                The tool input data containing "file_path" key
+
+        Returns:
+            `List[PermissionRule]`:
+                A single suggested rule covering the parent directory
+                (e.g., file "/src/main.py" -> rule "src/**")
+        """
+        file_path = tool_input.get("file_path", "")
+        if not file_path:
+            return []
+
+        parent = self._backend.dirname(file_path)
+        # Glob patterns are POSIX-style strings (matched by fnmatch),
+        # not real filesystem paths — do NOT use backend.join_path here.
+        pattern = (parent.rstrip("/\\") + "/**") if parent else "**"
+
+        return [
+            PermissionRule(
+                tool_name=self.name,
+                rule_content=pattern,
+                behavior=PermissionBehavior.ALLOW,
+                source="suggested",
+            ),
+        ]
+
+    async def call(  # type: ignore[override]
+        self,
+        file_path: str,
+        content: str,
+        _agent_state: AgentState | None = None,
+    ) -> ToolChunk:
+        """Write content to a file and return the result."""
+        # Validate that file_path is absolute
+        if not self._backend.isabs(file_path):
+            return ToolChunk(
+                content=[
+                    TextBlock(
+                        text=f"Error: file_path must be an absolute path, "
+                        f"got: {file_path}",
+                    ),
+                ],
+                state=ToolResultState.ERROR,
+                is_last=True,
+            )
+
+        # Check if file exists, it must be read first if it exists
+        if (
+            await self._backend.file_exists(file_path)
+            and _agent_state is not None
+        ):
+            cache = await _agent_state.tool_context.get_cache(file_path)
+            if cache is None:
+                return ToolChunk(
+                    content=[
+                        TextBlock(
+                            text=f"Error: File {file_path} exists but has not "
+                            f"been read yet. You must read the file first "
+                            f"before writing to it.",
+                        ),
+                    ],
+                    state=ToolResultState.ERROR,
+                    is_last=True,
+                )
+
+        # Capture the pre-write content (if any) so we can compute a unified
+        # diff for the web UI. For brand-new files this stays as an empty
+        # string, which produces a clean "new file" diff (``--- /dev/null``).
+        # Track ``file_existed`` separately from ``previous_content`` because
+        # an *existing* empty file overwrite is not the same as creating a
+        # new file — the diff header must reflect that.
+        file_existed = await self._backend.file_exists(file_path)
+        previous_content = ""
+        if file_existed:
+            try:
+                previous_content = (
+                    await self._backend.read_file(file_path)
+                ).decode("utf-8")
+            except Exception:  # pylint: disable=broad-except
+                # Binary or unreadable file — fall back to empty so we still
+                # render a best-effort "add" diff in the UI.
+                previous_content = ""
+
+        # Create parent directories if they don't exist
+        parent_dir = Path(file_path).parent
+        await self._backend.exec_shell(
+            ["mkdir", "-p", str(parent_dir)],
+        )
+
+        # Write content to file (backend handles parent dir creation)
+        await self._backend.write_file(
+            file_path,
+            content.encode("utf-8"),
+        )
+
+        # Count lines in content
+        line_count = len(content.split("\n"))
+
+        # Build the unified diff between previous and new content. When the
+        # file is brand new, ``unified_diff`` over an empty old side naturally
+        # produces a single "all add" hunk starting at line 1.
+        diff_text = "".join(
+            difflib.unified_diff(
+                previous_content.splitlines(keepends=True),
+                content.splitlines(keepends=True),
+                fromfile=(
+                    "/dev/null" if not file_existed else f"a/{file_path}"
+                ),
+                tofile=f"b/{file_path}",
+                n=3,
+            ),
+        )
+
+        # Return success message
+        return ToolChunk(
+            content=[
+                TextBlock(
+                    text=f"The file {file_path} has been written successfully "
+                    f"({line_count} lines).",
+                ),
+            ],
+            state=ToolResultState.RUNNING,
+            is_last=True,
+            metadata={
+                "diff": diff_text,
+                "file_path": file_path,
+                "occurrences": 1,
+            },
+        )
diff --git a/src/agentscope/tool/_constants.py b/src/agentscope/tool/_constants.py
new file mode 100644
index 0000000..c6c435a
--- /dev/null
+++ b/src/agentscope/tool/_constants.py
@@ -0,0 +1,110 @@
+# -*- coding: utf-8 -*-
+"""Constants for tool permission system."""
+
+DEFAULT_DANGEROUS_FILES = [
+    ".gitconfig",
+    ".gitmodules",
+    ".bashrc",
+    ".bash_profile",
+    ".zshrc",
+    ".zprofile",
+    ".profile",
+    ".ssh/config",
+    ".ssh/authorized_keys",
+    ".netrc",
+    ".npmrc",
+    ".pypirc",
+    ".env",
+    ".envrc",
+    ".env.local",
+    ".env.development",
+    ".env.development.local",
+    ".env.test",
+    ".env.test.local",
+    ".env.staging",
+    ".env.production",
+    ".env.production.local",
+]
+# Built-in list of dangerous files that should be protected from auto-editing.
+#
+# These files can be used for code execution, credential storage, or data
+# exfiltration:
+# - Shell configuration files: .bashrc, .zshrc, .profile, etc.
+# - Git configuration: .gitconfig, .gitmodules
+# - SSH configuration: .ssh/config, .ssh/authorized_keys
+# - Credential files: .netrc, .npmrc, .pypirc
+# - Environment / secret files: .env and common variants (.envrc for direnv,
+#   .env.local / .env.production / etc. for framework-specific overrides)
+
+
+DEFAULT_DANGEROUS_DIRECTORIES = [
+    ".git",
+    ".vscode",
+    ".idea",
+    ".ssh",
+]
+# Built-in list of dangerous directories that should be protected from
+# auto-editing.
+#
+# These directories contain sensitive configuration or executable files:
+# - .git: Git repository metadata
+# - .vscode: VS Code configuration
+# - .idea: JetBrains IDE configuration
+# - .ssh: SSH keys and configuration
+
+
+DANGEROUS_COMMANDS = [
+    "rm -rf",
+    "sudo rm",
+    "dd",
+    "mkfs",
+    "fdisk",
+    "format",
+    "chmod 777",
+    "chmod -R 777",
+    "chown -R",
+    "kill -9",
+    "> /dev/",
+]
+# Built-in list of dangerous command patterns that require explicit
+# user approval.
+#
+# These commands can cause data loss, system damage, or security issues:
+# - rm -rf: Recursive force deletion
+# - sudo rm: Deletion with elevated privileges
+# - dd: Direct disk operations
+# - mkfs: Format filesystem
+# - fdisk: Disk partitioning
+# - format: Format disk
+# - chmod 777: Overly permissive file permissions
+# - chown -R: Recursive ownership changes
+# - kill -9: Force kill processes
+# - > /dev/: Writing to device files
+
+
+DANGEROUS_NODE_TYPES = {
+    "command_substitution",  # $(...)  or `...`
+    "process_substitution",  # <(...)
+    "expansion",  # ${VAR:-default} complex expansion
+    "subshell",  # (...)
+    "for_statement",  # for loops
+    "while_statement",  # while loops
+    "until_statement",  # until loops
+    "if_statement",  # if conditionals
+    "case_statement",  # case statements
+    "function_definition",  # function definitions
+    "test_command",  # [[ ... ]] test commands
+}
+# Node types that indicate commands cannot be statically analyzed.
+# These either execute arbitrary code or expand to values we can't
+# determine statically.
+#
+# When these are detected, the command requires user review because:
+# - Command substitution $(cmd) executes arbitrary commands
+# - Process substitution <(cmd) creates dynamic file descriptors
+# - Complex expansions ${VAR:-default} have runtime-dependent values
+# - Control flow (if/while/for) has conditional execution paths
+# - Subshells (...) create new execution contexts
+#
+# Note: simple_expansion ($VAR) is handled separately with allowlist
+# for known-safe environment variables ($HOME, $PWD, etc.)
diff --git a/src/agentscope/tool/_response.py b/src/agentscope/tool/_response.py
new file mode 100644
index 0000000..db6eed5
--- /dev/null
+++ b/src/agentscope/tool/_response.py
@@ -0,0 +1,164 @@
+# -*- coding: utf-8 -*-
+"""The tool response class."""
+import base64
+import binascii
+from typing import List, Literal, Self
+
+from pydantic import BaseModel, Field
+
+from .._utils._common import _generate_id
+from ..message import DataBlock, TextBlock, Base64Source, ToolResultState
+
+
+def _merge_base64_chunks(existing: str, incoming: str) -> str:
+    """Merge independently encoded base64 chunks without corrupting padding."""
+    try:
+        merged = base64.b64decode(
+            existing,
+            validate=True,
+        ) + base64.b64decode(incoming, validate=True)
+    except (binascii.Error, ValueError):
+        # Keep compatibility with callers/tests that used placeholder strings
+        # instead of valid base64 payloads.
+        return existing + incoming
+
+    return base64.b64encode(merged).decode("ascii")
+
+
+class ToolChunk(BaseModel):
+    """The tool result chunk from a tool execution."""
+
+    content: List[TextBlock | DataBlock]
+    """The chunk data blocks, note for one multimodal data, the DataBlock
+    instance should have the same block id, so that the agent can group them
+    together."""
+
+    state: ToolResultState = ToolResultState.RUNNING
+    """The execution state of the tool chunk."""
+
+    is_last: bool = True
+    """Whether this is the last response in a stream tool execution."""
+
+    metadata: dict = Field(default_factory=dict)
+    """The metadata to be accessed within the agent, so that we don't need to
+    parse the tool result block."""
+
+    id: str = Field(default_factory=_generate_id)
+    """The identity of the tool chunk."""
+
+
+class ToolResponse(BaseModel):
+    """The tool response from a tool execution, which contains the completed
+    tool result (compared to ToolChunk)."""
+
+    content: List[TextBlock | DataBlock] = Field(default_factory=list)
+    """The completed tool result data blocks."""
+
+    state: Literal[
+        ToolResultState.ERROR,
+        ToolResultState.DENIED,
+        ToolResultState.INTERRUPTED,
+        ToolResultState.SUCCESS,
+    ] = ToolResultState.SUCCESS
+    """The execution state of the tool response."""
+
+    metadata: dict = Field(default_factory=dict)
+    """The metadata to be accessed within the agent, so that we don't need to
+    parse the tool result block."""
+
+    id: str = Field(default_factory=_generate_id)
+    """The identity of the tool response."""
+
+    def append_chunk(self, chunk: ToolChunk) -> Self:
+        """Append a tool chunk to the current tool response, accumulate the
+        data blocks and update the state and metadata."""
+
+        # Update content blocks
+        current_ids_to_index = {
+            _.id: index for index, _ in enumerate(self.content)
+        }
+        for chunk_block in chunk.content:
+            if chunk_block.id in current_ids_to_index:
+                # Append to the existing block
+                target_block = self.content[
+                    current_ids_to_index[chunk_block.id]
+                ]
+
+                if isinstance(target_block, TextBlock) and isinstance(
+                    chunk_block,
+                    TextBlock,
+                ):
+                    target_block.text += chunk_block.text
+                elif isinstance(target_block, DataBlock) and isinstance(
+                    chunk_block,
+                    DataBlock,
+                ):
+                    if isinstance(
+                        target_block.source,
+                        Base64Source,
+                    ) and isinstance(chunk_block.source, Base64Source):
+                        # Accumulate independently encoded base64 chunks.
+                        target_block.source.data = _merge_base64_chunks(
+                            target_block.source.data,
+                            chunk_block.source.data,
+                        )
+                        # Update the newest media type and name if provided
+                        target_block.name = (
+                            chunk_block.name or target_block.name
+                        )
+                        target_block.source.media_type = (
+                            chunk_block.source.media_type
+                            or target_block.source.media_type
+                        )
+                    else:
+                        raise ValueError(
+                            "Cannot append DataBlock with URL source or "
+                            f"different source types: {target_block.source} "
+                            f"vs {chunk_block.source}",
+                        )
+                else:
+                    # For different block types with the same ID, we just
+                    # append the new block with a new ID to avoid the conflict
+                    new_chunk_block = chunk_block.model_copy(deep=True)
+                    new_chunk_block.id = _generate_id()
+                    self.content.append(new_chunk_block)
+
+            else:
+                # Append a copy to avoid modifying the original chunk
+                self.content.append(chunk_block.model_copy(deep=True))
+
+                # Update the index mapping for the new block
+                current_ids_to_index[chunk_block.id] = len(self.content) - 1
+
+        # Update id, state and metadata
+        # Only reserve the failure state and keep the previous state if not
+        # worse.
+        if chunk.state == ToolResultState.ERROR:
+            self.state = ToolResultState.ERROR
+        elif chunk.state == "interrupted":
+            self.state = ToolResultState.INTERRUPTED
+        elif chunk.state == ToolResultState.DENIED:
+            self.state = ToolResultState.DENIED
+
+        self.metadata.update(chunk.metadata)
+
+        # Post-processing: merge consecutive TextBlocks
+        # DataBlocks are kept separate and only merged by explicit id matching
+        merged_content: List[TextBlock | DataBlock] = []
+        for block in self.content:
+            if isinstance(block, TextBlock) and merged_content:
+                # Check if the last block is also a TextBlock
+                last_block = merged_content[-1]
+                if isinstance(last_block, TextBlock):
+                    # Merge consecutive TextBlocks
+                    last_block.text += block.text
+                else:
+                    # Last block is DataBlock, append current TextBlock
+                    merged_content.append(block)
+            else:
+                # First block or current block is DataBlock
+                merged_content.append(block)
+
+        self.content = merged_content
+
+        return self
diff --git a/src/agentscope/tool/_task/__init__.py b/src/agentscope/tool/_task/__init__.py
new file mode 100644
index 0000000..023b6a6
--- /dev/null
+++ b/src/agentscope/tool/_task/__init__.py
@@ -0,0 +1,13 @@
+# -*- coding: utf-8 -*-
+"""Task planning tools for agents."""
+from ._create_task import TaskCreate
+from ._get_task import TaskGet
+from ._list_task import TaskList
+from ._update_task import TaskUpdate
+
+__all__ = [
+    "TaskCreate",
+    "TaskGet",
+    "TaskList",
+    "TaskUpdate",
+]
diff --git a/src/agentscope/tool/_task/_create_task.py b/src/agentscope/tool/_task/_create_task.py
new file mode 100644
index 0000000..2dc165e
--- /dev/null
+++ b/src/agentscope/tool/_task/_create_task.py
@@ -0,0 +1,132 @@
+# -*- coding: utf-8 -*-
+"""The creating task tool class."""
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from ._task_tool_base import _TaskToolBase
+from .._response import ToolChunk
+from ...state import AgentState, Task
+from ...exception import DeveloperOrientedException
+from ...message import TextBlock, ToolResultState
+
+
+class _TaskCreateParams(BaseModel):
+    """The params of the creating task tool."""
+
+    subject: str = Field(description="A brief title for the task")
+    description: str = Field(description="What needs to be done")
+    metadata: dict[str, Any] | None = Field(
+        default=None,
+        description="Arbitrary metadata to attach to the task",
+    )
+
+
+class TaskCreate(_TaskToolBase):
+    """Create a task for the agent to perform."""
+
+    name: str = "TaskCreate"
+
+    description: str = """Use this tool to create a structured task list for \
+your current session. This helps you track progress, organize complex tasks, \
+and demonstrate thoroughness to the user.
+It also helps the user understand the progress of the task and overall \
+progress of their requests.
+
+## When to Use This Tool
+Use this tool proactively in these scenarios:
+
+- Complex multi-step tasks - When a task requires 3 or more distinct steps \
+or actions
+- Non-trivial and complex tasks - Tasks that require careful planning or \
+multiple operations
+- Plan mode - When using plan mode, create a task list to track the work
+- User explicitly requests todo list - When the user directly asks you to \
+use the todo list
+- User provides multiple tasks - When users provide a list of things to be \
+done (numbered or comma-separated)
+- After receiving new instructions - Immediately capture user requirements \
+as tasks
+- When you start working on a task - Mark it as in_progress BEFORE \
+beginning work
+- After completing a task - Mark it as completed and add any new follow-up \
+tasks discovered during implementation
+
+## When NOT to Use This Tool
+
+Skip using this tool when:
+- There is only a single, straightforward task
+- The task is trivial and tracking it provides no organizational benefit
+- The task can be completed in less than 3 trivial steps
+- The task is purely conversational or informational
+
+NOTE that you should not use this tool if there is only one trivial task to \
+do. In this case you are better off just doing the task directly.
+
+## Task Fields
+
+- **subject**: A brief, actionable title in imperative form (e.g., \
+"Fix authentication bug in login flow")
+- **description**: What needs to be done
+
+All tasks are created with status `pending`.
+
+## Tips
+
+- Create tasks with clear, specific subjects that describe the outcome
+- After creating tasks, use TaskUpdate to set up dependencies \
+(blocks/blockedBy) if needed
+- Check TaskList first to avoid creating duplicate tasks"""
+
+    input_schema: dict = _TaskCreateParams.model_json_schema()
+
+    async def call(
+        self,
+        _agent_state: AgentState,
+        subject: str,
+        description: str,
+        metadata: dict[str, Any] | None = None,
+    ) -> ToolChunk:
+        """Create the subtask and add it into the agent state."""
+        if not isinstance(_agent_state, AgentState):
+            # Expose error to the developer
+            raise DeveloperOrientedException(
+                f"Error: TaskCreate requires AgentState to be provided, got "
+                f"{_agent_state} instead.",
+            )
+
+        try:
+            # Derive the next sequential id from existing tasks.
+            # Existing ids that look numeric are considered; any
+            # non-numeric ids (e.g. legacy UUIDs) are ignored.
+            max_numeric = 0
+            for t in _agent_state.tasks_context.tasks:
+                try:
+                    max_numeric = max(max_numeric, int(t.id))
+                except (ValueError, TypeError):
+                    pass
+            next_id = str(max_numeric + 1)
+
+            task = Task(
+                id=next_id,
+                subject=subject,
+                description=description,
+                metadata=metadata or {},
+            )
+            _agent_state.tasks_context.tasks.append(task)
+
+            return ToolChunk(
+                content=[
+                    TextBlock(
+                        text=f"Task (id={next_id}) created successfully: "
+                        f"{task.subject}",
+                    ),
+                ],
+            )
+        except Exception as e:
+            return ToolChunk(
+                content=[
+                    TextBlock(text=f"CreateTaskError: {e}"),
+                ],
+                state=ToolResultState.ERROR,
+            )
diff --git a/src/agentscope/tool/_task/_get_task.py b/src/agentscope/tool/_task/_get_task.py
new file mode 100644
index 0000000..82936e2
--- /dev/null
+++ b/src/agentscope/tool/_task/_get_task.py
@@ -0,0 +1,100 @@
+# -*- coding: utf-8 -*-
+"""The get task tool class."""
+from pydantic import BaseModel, Field
+
+from ._task_tool_base import _TaskToolBase
+from .._response import ToolChunk
+from ...state import AgentState
+from ...exception import DeveloperOrientedException
+from ...message import TextBlock, ToolResultState
+
+
+class _TaskGetParams(BaseModel):
+    """The params of the get task."""
+
+    task_id: str = Field(description="The ID of the task to retrieve")
+
+
+class TaskGet(_TaskToolBase):
+    """Retrieve a task by its ID from the task list."""
+
+    name: str = "TaskGet"
+
+    description: str = """Use this tool to retrieve a task by its ID from the task list.
+
+## When to Use This Tool
+
+- When you need the full description and context before starting work on a task
+- To understand task dependencies (what it blocks, what blocks it)
+- After being assigned a task, to get complete requirements
+
+## Output
+
+Returns full task details:
+- **subject**: Task title
+- **description**: Detailed requirements and context
+- **status**: 'pending', 'in_progress', or 'completed'
+- **blocks**: Tasks waiting on this one to complete
+- **blockedBy**: Tasks that must complete before this one can start
+
+## Tips
+
+- After fetching a task, verify its blockedBy list is empty before beginning work.
+- Use TaskList to see all tasks in summary form."""  # noqa: E501
+
+    input_schema: dict = _TaskGetParams.model_json_schema()
+
+    async def call(
+        self,
+        task_id: str,
+        _agent_state: AgentState,
+    ) -> ToolChunk:
+        """Retrieve a task by its ID."""
+        if not isinstance(_agent_state, AgentState):
+            # Expose error to the developer
+            raise DeveloperOrientedException(
+                f"Error: TaskGet requires AgentState to be provided, got "
+                f"{_agent_state} instead.",
+            )
+
+        # Find the task by ID
+        task = None
+        for t in _agent_state.tasks_context.tasks:
+            if t.id == task_id:
+                task = t
+                break
+
+        if task is None:
+            return ToolChunk(
+                content=[
+                    TextBlock(text="Task not found"),
+                ],
+                state=ToolResultState.ERROR,
+            )
+
+        # Build the response
+        lines = [
+            f"Task (id={task.id}): {task.subject}",
+            f"Status: {task.state}",
+            f"Description: {task.description}",
+        ]
+
+        if task.owner:
+            lines.append(f"Owner: {task.owner}")
+
+        if task.blocked_by:
+            blocked_by_str = ", ".join([f"#{bid}" for bid in task.blocked_by])
+            lines.append(f"Blocked by: {blocked_by_str}")
+
+        if task.blocks:
+            blocks_str = ", ".join([f"#{bid}" for bid in task.blocks])
+            lines.append(f"Blocks: {blocks_str}")
+
+        if task.metadata:
+            lines.append(f"Metadata: {task.metadata}")
+
+        return ToolChunk(
+            content=[
+                TextBlock(text="\n".join(lines)),
+            ],
+        )
diff --git a/src/agentscope/tool/_task/_list_task.py b/src/agentscope/tool/_task/_list_task.py
new file mode 100644
index 0000000..38f1565
--- /dev/null
+++ b/src/agentscope/tool/_task/_list_task.py
@@ -0,0 +1,74 @@
+# -*- coding: utf-8 -*-
+"""The task list tool class."""
+
+from ._task_tool_base import _TaskToolBase
+from .._response import ToolChunk
+from .._base import ParamsBase
+from ...state import AgentState
+from ...exception import DeveloperOrientedException
+from ...message import TextBlock
+
+
+class _TaskListParams(ParamsBase):
+    """The params of the list task params."""
+
+
+class TaskList(_TaskToolBase):
+    """List tasks for the agent to perform."""
+
+    name: str = "TaskList"
+
+    # pylint: disable=line-too-long
+    description: str = """Use this tool to list all tasks in the task list.
+
+## When to Use This Tool
+- To see what tasks are available to work on (status: 'pending', no owner, not blocked)
+- To check overall progress on the project
+- To find tasks that are blocked and need dependencies resolved
+- After completing a task, to check for newly unblocked work or claim the next available task
+- **Prefer working on tasks in ID order** (lowest ID first) when multiple tasks are available, as earlier tasks often set up context for later ones
+
+## Output
+
+Returns a summary of each task:
+- **id**: Task identifier (use with TaskGet, TaskUpdate)
+- **subject**: Brief description of the task
+- **status**: 'pending', 'in_progress', or 'completed'
+- **owner**: Agent ID if assigned, empty if available
+- **blockedBy**: List of open task IDs that must be resolved first (tasks with blockedBy cannot be claimed until dependencies resolve)
+
+Use TaskGet with a specific task ID to view full details including description and comments."""  # noqa: E501
+
+    input_schema: dict = _TaskListParams.model_json_schema()
+
+    async def call(self, _agent_state: AgentState) -> ToolChunk:
+        """List tasks for the agent to perform."""
+        if not isinstance(_agent_state, AgentState):
+            # Expose error to the developer
+            raise DeveloperOrientedException(
+                f"Error: TaskList requires AgentState to be provided, got "
+                f"{_agent_state} instead.",
+            )
+
+        if len(_agent_state.tasks_context.tasks) == 0:
+            return ToolChunk(
+                content=[TextBlock(text="No tasks available.")],
+            )
+
+        tasks = []
+        for task in _agent_state.tasks_context.tasks:
+            owner = f"({task.owner})" if task.owner else ""
+            blocked = (
+                f'[blocked by {", ".join(task.blocked_by)}]'
+                if task.blocked_by
+                else ""
+            )
+            tasks.append(
+                f"{task.id} [{task.state}] {task.subject}{owner}{blocked}",
+            )
+
+        return ToolChunk(
+            content=[
+                TextBlock(text="\n".join(tasks)),
+            ],
+        )
diff --git a/src/agentscope/tool/_task/_task_tool_base.py b/src/agentscope/tool/_task/_task_tool_base.py
new file mode 100644
index 0000000..463a04f
--- /dev/null
+++ b/src/agentscope/tool/_task/_task_tool_base.py
@@ -0,0 +1,42 @@
+# -*- coding: utf-8 -*-
+"""The task tool base class, providing unified interface and permission
+check for builtin task related tools."""
+from typing import Any
+
+from .._base import ToolBase
+from ...permission import (
+    PermissionContext,
+    PermissionDecision,
+    PermissionBehavior,
+)
+
+
+class _TaskToolBase(ToolBase):
+    name: str
+
+    description: str
+
+    input_schema: dict
+
+    is_concurrency_safe: bool = True
+
+    is_read_only: bool = False
+
+    is_state_injected: bool = True
+
+    is_external_tool: bool = False
+
+    is_mcp: bool = False
+
+    mcp_name: str | None = None
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        """Check permission for the tool usage."""
+        return PermissionDecision(
+            behavior=PermissionBehavior.ALLOW,
+            message=f"{self.name} is always allowed to be called.",
+        )
diff --git a/src/agentscope/tool/_task/_update_task.py b/src/agentscope/tool/_task/_update_task.py
new file mode 100644
index 0000000..abdf11d
--- /dev/null
+++ b/src/agentscope/tool/_task/_update_task.py
@@ -0,0 +1,293 @@
+# -*- coding: utf-8 -*-
+"""The task updated tool class."""
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from ._task_tool_base import _TaskToolBase
+from .._response import ToolChunk
+from ...state import AgentState
+from ...exception import DeveloperOrientedException
+from ...message import TextBlock, ToolResultState
+
+
+class _TaskUpdateParams(BaseModel):
+    """The params of the update task."""
+
+    task_id: str = Field(description="The task id.")
+    subject: str | None = Field(
+        default=None,
+        description="New subject for the task",
+    )
+    description: str | None = Field(
+        default=None,
+        description="New description for the task",
+    )
+    add_blocks: list[str] | None = Field(
+        default=None,
+        description="Task IDs that this task blocks",
+    )
+    status: Literal[
+        "pending",
+        "in_progress",
+        "completed",
+        "deleted",
+    ] | None = Field(
+        default=None,
+        description="New status for the task",
+    )
+    add_blocked_by: list[str] | None = Field(
+        default=None,
+        description="Task IDs that block this task",
+    )
+    owner: str | None = Field(
+        default=None,
+        description="New owner for the task",
+    )
+    metadata: dict | None = Field(
+        default=None,
+        description="Metadata keys to merge into the task. "
+        "Set a key to null to delete it.",
+    )
+
+
+class TaskUpdate(_TaskToolBase):
+    """The tool to update the agent task."""
+
+    name: str = "TaskUpdate"
+
+    description: str = """Use this tool to update a task in the task list.
+
+## When to Use This Tool
+
+**Mark tasks as resolved:**
+- When you have completed the work described in a task
+- When a task is no longer needed or has been superseded
+- IMPORTANT: Always mark your assigned tasks as resolved when you finish them
+- After resolving, call TaskList to find your next task
+
+- ONLY mark a task as completed when you have FULLY accomplished it
+- If you encounter errors, blockers, or cannot finish, keep the task as in_progress
+- When blocked, create a new task describing what needs to be resolved
+- Never mark a task as completed if:
+  - Tests are failing
+  - Implementation is partial
+  - You encountered unresolved errors
+  - You couldn't find necessary files or dependencies
+
+**Delete tasks:**
+- When a task is no longer relevant or was created in error
+- Setting status to `deleted` permanently removes the task
+
+**Update task details:**
+- When requirements change or become clearer
+- When establishing dependencies between tasks
+
+## Fields You Can Update
+
+- **status**: The task status (see Status Workflow below)
+- **subject**: Change the task title (imperative form, e.g., "Run tests")
+- **description**: Change the task description
+- **owner**: Change the task owner (agent name)
+- **metadata**: Merge metadata keys into the task (set a key to null to delete it)
+- **add_blocks**: Mark tasks that cannot start until this one completes
+- **add_blocked_by**: Mark tasks that must complete before this one can start
+
+## Status Workflow
+
+Status progresses: `pending` → `in_progress` → `completed`
+
+Use `deleted` to permanently remove a task.
+
+## Staleness
+
+Make sure to read a task's latest state using `TaskGet` before updating it.
+
+## Examples
+
+Mark task as in progress when starting work:
+```json
+{"task_id": "1", "status": "in_progress"}
+```
+
+Mark task as completed after finishing work:
+```json
+{"task_id": "1", "status": "completed"}
+```
+
+Delete a task:
+```json
+{"task_id": "1", "status": "deleted"}
+```
+
+Claim a task by setting owner:
+```json
+{"task_id": "1", "owner": "my-name"}
+```
+
+Set up task dependencies:
+```json
+{"task_id": "2", "add_blocked_by": ["1"]}
+```"""  # noqa: E501
+
+    input_schema: dict = _TaskUpdateParams.model_json_schema()
+
+    async def call(
+        self,
+        _agent_state: AgentState,
+        task_id: str,
+        subject: str | None = None,
+        description: str | None = None,
+        add_blocks: list[str] | None = None,
+        status: Literal["pending", "completed", "in_progress", "deleted"]
+        | None = None,
+        add_blocked_by: list[str] | None = None,
+        owner: str | None = None,
+        metadata: dict | None = None,
+    ) -> ToolChunk:
+        """Update the agent task."""
+        if not isinstance(_agent_state, AgentState):
+            # Expose error to the developer
+            raise DeveloperOrientedException(
+                f"Error: {self.name} requires AgentState to be provided, got "
+                f"{_agent_state} instead.",
+            )
+
+        index = None
+        for i, task in enumerate(_agent_state.tasks_context.tasks):
+            if task.id == task_id:
+                index = i
+
+        if index is None:
+            return ToolChunk(
+                content=[
+                    TextBlock(
+                        text=f"TaskNotFoundError: "
+                        f"The task (id={task_id}) does not exist.",
+                    ),
+                ],
+                state=ToolResultState.ERROR,
+            )
+
+        updated_fields = []
+
+        if subject:
+            updated_fields.append("subject")
+            _agent_state.tasks_context.tasks[index].subject = subject
+
+        if description is not None:
+            updated_fields.append("description")
+            _agent_state.tasks_context.tasks[index].description = description
+
+        existed_ids = [_.id for _ in _agent_state.tasks_context.tasks]
+        if add_blocks:
+            current_blocks = _agent_state.tasks_context.tasks[index].blocks
+            new_blocks = [
+                _
+                for _ in add_blocks
+                if _ not in current_blocks and _ in existed_ids
+            ]
+            if new_blocks:
+                updated_fields.append("add_blocks")
+                for block_id in new_blocks:
+                    self._update_block_relation(
+                        task_id,
+                        block_id,
+                        _agent_state,
+                    )
+
+        if add_blocked_by is not None:
+            current_blocked_by = _agent_state.tasks_context.tasks[
+                index
+            ].blocked_by
+            new_blocked_by = [
+                _
+                for _ in add_blocked_by
+                if _ not in current_blocked_by and _ in existed_ids
+            ]
+            if new_blocked_by:
+                updated_fields.append("add_blocked_by")
+                for blocked_by_id in new_blocked_by:
+                    self._update_block_relation(
+                        blocked_by_id,
+                        task_id,
+                        _agent_state,
+                    )
+
+        if status:
+            if status == "deleted":
+                # Permanently remove the task
+                _agent_state.tasks_context.tasks.pop(index)
+                # Remove task id from all the blocks and blocked_by
+                for task in _agent_state.tasks_context.tasks:
+                    if task_id in task.blocks:
+                        task.blocks.remove(task_id)
+
+                    if task_id in task.blocked_by:
+                        task.blocked_by.remove(task_id)
+                return ToolChunk(
+                    content=[
+                        TextBlock(
+                            text=f"Task (id={task_id}) has been deleted.",
+                        ),
+                    ],
+                )
+            # Update the status
+            updated_fields.append("status")
+            _agent_state.tasks_context.tasks[index].state = status
+
+        if owner is not None:
+            updated_fields.append("owner")
+            _agent_state.tasks_context.tasks[index].owner = owner
+
+        if metadata:
+            updated_fields.append("metadata")
+            for k, v in metadata.items():
+                if v is None:
+                    _agent_state.tasks_context.tasks[index].metadata.pop(
+                        k,
+                        None,
+                    )
+                else:
+                    _agent_state.tasks_context.tasks[index].metadata[k] = v
+
+        if updated_fields:
+            res = f'Update task (id={task_id}) {", ".join(updated_fields)}.'
+        else:
+            res = (
+                f"No updates were made to the task (id={task_id}). "
+                f"Make sure you provided at least one field to update and "
+                f"the values are correct."
+            )
+
+        if _agent_state.tasks_context.tasks[index].state == "completed":
+            res += (
+                "\n\nTask completed. Call TaskList now to find your next "
+                "available task or see if your work unblocked others."
+            )
+
+        return ToolChunk(content=[TextBlock(text=res)])
+
+    @staticmethod
+    def _update_block_relation(
+        block_id: str,
+        blocked_by_id: str,
+        _agent_state: AgentState,
+    ) -> None:
+        """Update the block relationship between the tasks.
+
+        Args:
+            block_id (`str`):
+                The id of the task that blocks the other tasks.
+            blocked_by_id (`str`):
+                The id of the task blocked by the task of `block_id`.
+            _agent_state (`AgentState`):
+                The agent state to update.
+        """
+        # Update the blocks
+        for task in _agent_state.tasks_context.tasks:
+            if task.id == block_id and blocked_by_id not in task.blocks:
+                task.blocks.append(blocked_by_id)
+
+            if task.id == blocked_by_id and block_id not in task.blocked_by:
+                task.blocked_by.append(block_id)
diff --git a/src/agentscope/tool/_tool_group.py b/src/agentscope/tool/_tool_group.py
new file mode 100644
index 0000000..87857b0
--- /dev/null
+++ b/src/agentscope/tool/_tool_group.py
@@ -0,0 +1,108 @@
+# -*- coding: utf-8 -*-
+"""The tool group class."""
+from typing import Literal, Sequence
+
+from ..mcp import MCPClient
+from ._base import ToolBase
+from ..skill import SkillLoaderBase, Skill, LocalSkillLoader
+
+
+class ToolGroup:
+    """A group of related tools, mcps, and skills that an agent can activate,
+    deactivate and use together. The tool group is activated by the meta tool
+    `ResetTools`.
+
+    In high-code scenarios, the tools argument accepts any child classes for
+    ToolBase class, and the tool groups supports serialization.
+    """
+
+    name: Literal["basic"] | str
+    """Note the "basic" group is special and represents the default tool group
+    that will be always be activated for the agent."""
+
+    description: str
+    """A description of the tool group from an agent-oriented perspective,
+    outlining its capabilities and the conditions under which it should be
+    activated."""
+
+    instructions: str | None
+    """Instructions included in the meta tool's result upon activation of
+    this tool group, guiding the agent on how to properly use the meta tool."""
+
+    tools: list[ToolBase]
+    """The tools in this group."""
+
+    skills_or_loaders: list[Skill | SkillLoaderBase]
+    """The skills in this group."""
+
+    mcps: list[MCPClient]
+    """The mcps in this group."""
+
+    def __init__(
+        self,
+        name: Literal["basic"] | str,
+        description: str | None = None,
+        instructions: str | None = None,
+        tools: list[ToolBase] | None = None,
+        skills_or_loaders: Sequence[str | Skill | SkillLoaderBase]
+        | None = None,
+        mcps: list[MCPClient] | None = None,
+    ) -> None:
+        """Initialize the tool group.
+
+        Args:
+            name (`Literal["basic"] | str):
+                The name of the tool group.
+            description (`str | None`):
+                The description of the tool group.
+            instructions (`str | None`, optional):
+                Instructions included in the meta tool's result upon
+                activation of this tool group, guiding the agent on how to
+                properly use the meta tool.
+            tools (`list[ToolBase] | None`, optional):
+                The tools in this group.
+            skills_or_loaders (`list[str | Skill | SkillLoaderBase] | None`, \
+            optional):
+                The skill paths, data, and loaders to access skills in this
+                group.
+            mcps (`list[MCPClient] | None`, optional):
+                The mcps in this group.
+        """
+        if name != "basic" and description is None:
+            raise ValueError(
+                f"The tool group description is required for tool group "
+                f"'{name}' (Only the 'basic' tool group can have an optional "
+                f"description).",
+            )
+
+        self.name = name
+        self.description = description or ""
+        self.instructions = instructions
+        self.tools = tools or []
+        self.mcps = mcps or []
+
+        # Skill
+        self.skills_or_loaders = []
+        for _ in skills_or_loaders or []:
+            if isinstance(_, str):
+                self.skills_or_loaders.append(LocalSkillLoader(directory=_))
+
+            elif isinstance(_, (Skill, SkillLoaderBase)):
+                self.skills_or_loaders.append(_)
+
+            else:
+                raise TypeError(
+                    f"Invalid skill or loader: {_}. Must be a skill, "
+                    f"skill loader, or directory path.",
+                )
+
+    async def list_skills(self) -> list[Skill]:
+        """List all the skills in this tool group."""
+        skills = []
+        for skill_or_loader in self.skills_or_loaders:
+            if isinstance(skill_or_loader, Skill):
+                skills.append(skill_or_loader)
+            elif isinstance(skill_or_loader, SkillLoaderBase):
+                skills.extend(await skill_or_loader.list_skills())
+
+        return skills
diff --git a/src/agentscope/tool/_toolkit.py b/src/agentscope/tool/_toolkit.py
new file mode 100644
index 0000000..1964152
--- /dev/null
+++ b/src/agentscope/tool/_toolkit.py
@@ -0,0 +1,614 @@
+# -*- coding: utf-8 -*-
+"""The toolkit class for tool calls in AgentScope."""
+import asyncio
+import inspect
+from collections import OrderedDict
+from typing import (
+    AsyncGenerator,
+    Type,
+    Generator,
+    Sequence,
+)
+
+import mcp
+from jinja2 import Template
+from pydantic import (
+    BaseModel,
+    Field,
+    create_model,
+)
+
+from ._builtin import ResetTools, SkillViewer
+from ._base import ToolBase
+from ._response import ToolResponse, ToolChunk
+from ..skill import SkillLoaderBase, Skill
+from ._types import RegisteredTool
+from .._utils._common import _json_loads_with_repair
+from ..exception import (
+    DeveloperOrientedException,
+    ToolNotFoundError,
+    ToolGroupInactiveError,
+)
+from ..mcp import MCPClient
+from ..message import (
+    ToolCallBlock,
+    TextBlock,
+    ToolResultState,
+)
+from ._tool_group import ToolGroup
+from .._logging import logger
+from ..state import AgentState
+
+
+# pylint: disable=line-too-long
+DEFAULT_META_TOOL_RESPONSE_TEMPLATE = """{% if groups | length == 0 %}All tool groups are currently deactivated.{% else %}The currently activated tool group(s): {{ groups | map(attribute='name') | join(', ') }}.{% if groups | selectattr('instructions', 'ne', None) | list | length > 0 %}
+<tool-instructions>
+The tool instructions are a collection of suggestions, rules and notifications about how to use the tools in the activated groups.
+{% for group in groups %}{% if group.instructions %}<group name="{{ group.name }}">{{ group.instructions }}</group>{% endif %}{% endfor %}
+</tool-instructions>{% endif %}{% endif %}"""  # noqa: E501
+
+
+DEFAULT_SKILL_INSTRUCTION = """<agent-skills>
+Skills are a collection of instructions, scripts, and resources to extend your capabilities.
+
+**IMPORTANT**: Skills are NOT tools, and you cannot call a skill directly. To use a skill, you MUST use the `{{ skill_viewer }}` tool to read the skill's full instructions, and then follow those instructions to use the tools and resources provided by the skill.
+
+# Available Skills:{% for skill in skills %}
+<skill>
+<name>{{ skill.name }}</name>
+<description>{{ skill.description }}</description>
+<dir>{{ skill.dir }}</dir>
+</skill>{% endfor %}
+</agent-skills>
+"""  # noqa: E501
+
+
+class Toolkit:
+    """Toolkit is the core module to register, manage and delete tool
+    functions, MCP clients, Agent skills in AgentScope.
+
+    About tool functions:
+
+    - Register and parse JSON schemas from their docstrings automatically.
+    - Group-wise tools management, and agentic tools activation/deactivation.
+    - Extend the tool function JSON schema dynamically with Pydantic BaseModel.
+    - Tool function execution with unified streaming interface.
+
+    About MCP clients:
+
+    - Register tool functions from MCP clients directly.
+    - Client-level tool functions removal.
+
+    About Agent skills:
+
+    - Register agent skills from the given directory.
+    - Provide prompt for the registered skills to the agent.
+    """
+
+    def __init__(
+        self,
+        tools: list[ToolBase] | None = None,
+        skills_or_loaders: Sequence[str | Skill | SkillLoaderBase]
+        | None = None,
+        mcps: list[MCPClient] | None = None,
+        tool_groups: list[ToolGroup] | None = None,
+        meta_tool_response_template: str = DEFAULT_META_TOOL_RESPONSE_TEMPLATE,
+        skill_instruction_template: str = DEFAULT_SKILL_INSTRUCTION,
+    ) -> None:
+        """Initialize the toolkit.
+
+        Args:
+            tools (`list[ToolBase] | None`, optional):
+                The tool objects that belong to the "basic" tool group.
+            skills_or_loaders (`list[str | Skill | SkillLoaderBase] | None`, \
+            optional):
+                The agent skill directories to be registered in the "basic"
+                tool group.
+            mcps (`list[MCPClient] | None`, optional):
+                The mcp clients to be registered in the "basic" tool group.
+            tool_groups (`list[ToolGroup] | None`, optional):
+                The tool groups to be registered.
+            meta_tool_response_template (`str`, optional):
+                The template for meta tool responses.
+            skill_instruction_template (`str`):
+                A Jinja2 template for generating the agent skill instruction.
+        """
+
+        if tool_groups is not None and any(
+            _.name == "basic" for _ in tool_groups
+        ):
+            raise ValueError(
+                "The 'basic' tool group is reserved for the default tool "
+                "group. Don't include 'basic' in the tool_groups argument "
+                "when you also provide tools, skills or mcps in the "
+                "constructor.",
+            )
+
+        self.tool_groups = [
+            ToolGroup(
+                name="basic",
+                tools=tools or [],
+                skills_or_loaders=skills_or_loaders or [],
+                mcps=mcps or [],
+            ),
+        ] + (tool_groups or [])
+
+        # Check name conflict for tool groups
+        if len(set(_.name for _ in self.tool_groups)) != len(
+            self.tool_groups,
+        ):
+            raise ValueError(
+                "Tool groups must not contain duplicate tool groups.",
+            )
+
+        # The stateful MCP clients should be initialized already
+        for group in self.tool_groups:
+            for client in group.mcps:
+                if client.is_stateful and not client.is_connected:
+                    raise ValueError(
+                        f"The MCP client '{client.name}' is stateful, but "
+                        f"not connected.",
+                    )
+
+        self.meta_tool_response_template = meta_tool_response_template
+        self.skill_instruction_template = skill_instruction_template
+
+        self.builtin_meta_tool = RegisteredTool(
+            tool=ResetTools(
+                # An inference value for groups so that it can generate the
+                # corresponding input schema.
+                groups=self.tool_groups,
+                response_template=meta_tool_response_template,
+            ),
+        )
+
+        self.builtin_skill_viewer = RegisteredTool(
+            tool=SkillViewer(
+                get_skills_method=self._get_available_skills,
+            ),
+        )
+
+    async def get_tool_schemas(
+        self,
+        groups: list[str] | None = None,
+    ) -> list[dict]:
+        """Get the JSON schemas of the currently available tool functions
+        based on the given activated tool groups.
+
+        .. note:: The preset keyword arguments is removed from the JSON
+         schema, and the extended model is applied if it is set.
+
+         Args:
+             groups (`list[str] | None`, optional):
+                A list of group names to filter the tool function. The "basic"
+                group will always be included regardless of the filter. If not
+                provided, only the "basic" group will be included.
+
+        Example:
+            .. code-block:: JSON
+                :caption: Example of tool function JSON schemas
+
+                [
+                    {
+                        "type": "function",
+                        "function": {
+                            "name": "google_search",
+                            "description": "Search on Google.",
+                            "parameters": {
+                                "type": "object",
+                                "properties": {
+                                    "query": {
+                                        "type": "string",
+                                        "description": "The search query."
+                                    }
+                                },
+                                "required": ["query"]
+                            }
+                        }
+                    },
+                    ...
+                ]
+
+        Returns:
+            `list[dict]`:
+                A list of function JSON schemas.
+        """
+        function_schemas = []
+
+        # Get all available tools
+        tools_dict = await self._get_available_tools(groups)
+        for tool in tools_dict.values():
+            function_schemas.append(tool.get_tool_schema())
+
+        return function_schemas
+
+    async def call_tool(
+        self,
+        tool_call: ToolCallBlock,
+        state: AgentState,
+    ) -> AsyncGenerator[ToolChunk | ToolResponse, None]:
+        """Call the tool function, return the incremental tool result in
+        a ToolChunk stream, and finally return the complete tool result in a
+        ToolResponse object. **Note the accumulation process occurs within this
+        function, so the tool functions only need to return/yield the
+        ToolChunk objects in an incremental manner.**
+
+        Args:
+            tool_call (`ToolCallBlock`):
+                A tool call block.
+            state (`AgentState`):
+                The current agent state, used to state injection.
+
+        Yields:
+            `ToolChunk | ToolResponse`:
+                The incremental tool result in a ToolChunk stream, and finally
+                the complete tool result in a ToolResponse object.
+        """
+        tool_response = ToolResponse(id=tool_call.id)
+
+        # Check
+        available_tools = await self._get_available_tools(
+            state.tool_context.activated_groups,
+        )
+
+        if tool_call.name not in available_tools:
+            all_tools = await self._get_available_tools(
+                groups=[_.name for _ in self.tool_groups],
+            )
+            # Not activate
+            if tool_call.name in all_tools:
+                group_name = all_tools[tool_call.name].group
+                chunk = ToolChunk(
+                    content=[
+                        TextBlock(
+                            text=(
+                                "ToolGroupInactiveError: The tool "
+                                f"'{tool_call.name}' in group '{group_name}' "
+                                "is currently inactive. You should first "
+                                "activate the group by calling the "
+                                f"'{self.builtin_meta_tool.tool.name}' tool."
+                            ),
+                        ),
+                    ],
+                    state=ToolResultState.ERROR,
+                )
+                yield chunk
+                yield tool_response.append_chunk(chunk)
+                return
+
+            # Not exist
+            chunk = ToolChunk(
+                content=[
+                    TextBlock(
+                        text=f"ToolNotFoundError: The tool named "
+                        f"'{tool_call.name}' doesn't exist.",
+                    ),
+                ],
+                state=ToolResultState.ERROR,
+            )
+            yield chunk
+            yield tool_response.append_chunk(chunk)
+            return
+
+        # Obtain the tool function
+        tool_func = available_tools[tool_call.name].tool
+
+        # Async function
+        try:
+            # Prepare keyword arguments
+            kwargs = _json_loads_with_repair(tool_call.input)
+
+            # State injection
+            if (
+                tool_func.is_state_injected
+                and not tool_func.is_mcp
+                and not tool_func.is_external_tool
+            ):
+                kwargs["_agent_state"] = state
+
+            if inspect.iscoroutinefunction(tool_func.__call__):
+                res = await tool_func(**kwargs)
+            else:
+                # When `tool_func.original_func` is Async generator function or
+                # Sync function
+                res = tool_func(**kwargs)
+
+            if isinstance(res, ToolChunk):
+                yield res
+                tool_response.append_chunk(res)
+
+            # If return an async generator
+            elif isinstance(res, AsyncGenerator):
+                async for chunk in res:
+                    yield chunk
+                    tool_response.append_chunk(chunk)
+
+            # If return a sync generator
+            elif isinstance(res, Generator):
+                for chunk in res:
+                    yield chunk
+                    tool_response.append_chunk(chunk)
+
+            else:
+                raise DeveloperOrientedException(
+                    "The tool function must return a ToolChunk object, or an "
+                    "AsyncGenerator/Generator of ToolChunk objects, "
+                    f"but got {type(res)}.",
+                )
+
+        except mcp.shared.exceptions.McpError as e:
+            chunk = ToolChunk(
+                content=[
+                    TextBlock(
+                        type="text",
+                        text=f"Error occurred when calling MCP tool: {e}",
+                    ),
+                ],
+                state=ToolResultState.ERROR,
+            )
+            yield chunk
+            tool_response.append_chunk(chunk)
+
+        except Exception as e:
+            # Raise the developer-oriented exception
+            if isinstance(e, DeveloperOrientedException):
+                raise e from None
+
+            # The exceptions should be handled by the agent
+            chunk = ToolChunk(
+                content=[
+                    TextBlock(
+                        type="text",
+                        text=str(e),
+                    ),
+                ],
+                state=ToolResultState.ERROR,
+            )
+            yield chunk
+            tool_response.append_chunk(chunk)
+
+        except asyncio.CancelledError:
+            chunk = ToolChunk(
+                content=[
+                    TextBlock(
+                        type="text",
+                        text="<system-reminder>"
+                        "The tool call has been interrupted "
+                        "by the user."
+                        "</system-reminder>",
+                    ),
+                ],
+                state=ToolResultState.INTERRUPTED,
+            )
+            yield chunk
+            tool_response.append_chunk(chunk)
+
+        finally:
+            # Finally, yield the complete tool response
+            yield tool_response
+
+    async def _get_available_skills(
+        self,
+        groups: list[str] | None = None,
+    ) -> dict[str, Skill]:
+        """A unified method to collect all skills from the registered skill
+        loaders.
+
+        Args:
+            groups (`list[str] | None`, optional):
+                A list of group names to filter the skill loaders. The "basic"
+                group will always be included regardless of the filter. If not
+                provided, only the "basic" group will be included.
+
+        Returns:
+            `dict[str, Skill]`
+                A dictionary of skill name and their corresponding Skill
+                objects.
+        """
+        groups_filter = ["basic"] + (groups or [])
+
+        skills = OrderedDict()
+        for group in self.tool_groups:
+            if group.name not in groups_filter:
+                continue
+
+            for skill in await group.list_skills():
+                if skill.name in skills:
+                    logger.warning(
+                        "Duplicate skill name '%s' found in group '%s', "
+                        "overwriting it.",
+                        skill.name,
+                        group.name,
+                    )
+                skills[skill.name] = skill
+
+        return skills
+
+    async def get_skill_instructions(
+        self,
+        activated_groups: list[str] | None = None,
+    ) -> str | None:
+        """Get the prompt for all registered agent skills, which can be
+        attached to the system prompt for the agent.
+
+        The prompt is consisted of an overall instruction and the detailed
+        descriptions of each skill, including its name, description, and
+        directory.
+
+        .. note:: If no skill is registered, None will be returned.
+
+        Args:
+            activated_groups (`list[str] | None`, optional):
+                The currently activated tool groups. If omitted, all groups
+                will be included for backwards compatibility.
+
+        Returns:
+            `str | None`:
+                The combined prompt for registered agent skills, or None
+                if no skill is registered.
+        """
+        if activated_groups is None:
+            activated_groups = [_.name for _ in self.tool_groups]
+
+        skills = await self._get_available_skills(
+            activated_groups,
+        )
+
+        # If no skills were collected, return None
+        if len(skills) == 0:
+            return None
+
+        # Generate the skill instruction prompt with the template
+        template = Template(self.skill_instruction_template)
+
+        return template.render(
+            skills=skills.values(),
+            skill_viewer=self.builtin_skill_viewer.tool.name,
+        )
+
+    async def _get_available_tools(
+        self,
+        groups: list[str] | None,
+    ) -> dict[str, RegisteredTool]:
+        """Return the currently available tools based on the given
+        activated tool groups. Tools in the ``"basic"`` group are always
+        included. When at least one tool group is registered, the built-in
+        meta tool is also included.
+
+        Args:
+            groups (`list[str]`):
+                The list of currently activated tool group names.
+
+        Returns:
+            `dict[str, RegisteredTool]`:
+                The dictionary of available tool name and their corresponding
+                RegisteredTool objects.
+        """
+        available_tools = {}
+
+        # Built-in skill viewers
+        skills = await self._get_available_skills(groups)
+        if len(skills):
+            available_tools[
+                self.builtin_skill_viewer.tool.name
+            ] = self.builtin_skill_viewer
+
+        # Builtin meta tool is only included when there is at least one tool
+        # group
+        if (
+            len(self.tool_groups) == 1
+            and self.tool_groups[0].name != "basic"
+            or len(self.tool_groups) > 1
+        ):
+            available_tools[
+                self.builtin_meta_tool.tool.name
+            ] = self.builtin_meta_tool
+
+        # The tools in the activated groups and the "basic" group are included
+        groups_filter = ["basic"] + (groups or [])
+        for group in self.tool_groups:
+            if group.name not in groups_filter:
+                continue
+
+            cache_tools = []
+            # Python tools
+            for tool in group.tools:
+                cache_tools.append(tool)
+
+            # MCP tools
+            for client in group.mcps:
+                tools = await client.list_tools()
+                cache_tools.extend(tools)
+
+            # Append cached tools into the available tools and solve the name
+            # conflict
+            for tool in cache_tools:
+                if tool.name in available_tools:
+                    logger.warning(
+                        "Duplicate tool name '%s' found in group '%s', "
+                        "overwriting it.",
+                        tool.name,
+                        group.name,
+                    )
+                available_tools[tool.name] = RegisteredTool(
+                    tool=tool,
+                    group=group.name,
+                )
+
+        return available_tools
+
+    async def check_tool_available(
+        self,
+        tool_name: str,
+        activated_groups: list[str],
+    ) -> ToolBase:
+        """Check if the tool is available now. If not, raise the
+        agent-oriented exception.
+
+        Args:
+            tool_name (`str`):
+                The name of the tool to be checked.
+            activated_groups (`list[str]`):
+                The currently activated tool groups.
+
+        Returns:
+            `ToolBase`:
+                If the tool is available, return the corresponding ToolBase
+                object. Otherwise, raise the agent-oriented exception with the
+                error message.
+        """
+        tools = await self._get_available_tools(activated_groups)
+        if tool_name not in tools:
+            raise ToolNotFoundError(
+                f"ToolNotFoundError: The tool named '{tool_name}' doesn't "
+                f"exist.",
+            )
+
+        group_name = tools[tool_name].group
+        if group_name != "basic" and group_name not in activated_groups:
+            raise ToolGroupInactiveError(
+                f"ToolGroupInactiveError: The tool '{tool_name}' in group "
+                f"'{group_name}' is currently inactive. "
+                f"You should first activate the group by calling the "
+                f"'{self.builtin_meta_tool.tool.name}' tool.",
+            )
+
+        return tools[tool_name].tool
+
+    async def get_tool(self, name: str) -> ToolBase | None:
+        """Get tool instance by its name.
+
+        Args:
+            name (`str`):
+                The name of the tool to be checked.
+
+        Returns:
+            `ToolBase | None`:
+                The tool instance, or `None` if no tool is found.
+        """
+        tools = await self._get_available_tools(
+            [_.name for _ in self.tool_groups],
+        )
+        registered_tool = tools.get(name, None)
+        if registered_tool is None:
+            return None
+        return registered_tool.tool
+
+    def _get_meta_tool_schema(self) -> Type[BaseModel]:
+        """Get the meta tool schema based on the current tool groups."""
+        fields = {}
+        for group in self.tool_groups:
+            if group.name == "basic":
+                continue
+            fields[group.name] = (
+                bool,
+                Field(
+                    default=False,
+                    description=group.description,
+                ),
+            )
+        return create_model("_DynamicModel", **fields)
+
+    def clear(self) -> None:
+        """Clear the registered tools, skills and MCPs."""
+        self.tool_groups.clear()
diff --git a/src/agentscope/tool/_types.py b/src/agentscope/tool/_types.py
new file mode 100644
index 0000000..0823187
--- /dev/null
+++ b/src/agentscope/tool/_types.py
@@ -0,0 +1,203 @@
+# -*- coding: utf-8 -*-
+"""The types for the tool module in AgentScope."""
+from copy import deepcopy
+from dataclasses import dataclass, field
+from typing import (
+    Literal,
+    Type,
+    Any,
+    TypeAlias,
+    Coroutine,
+    AsyncGenerator,
+    Generator,
+    Awaitable,
+    Callable,
+)
+
+from pydantic import BaseModel
+
+from ._response import ToolChunk
+from ._base import ToolBase
+from ._utils import _remove_title_field
+
+
+@dataclass
+class RegisteredTool:
+    """The registered tool function class, used to store the tool function and
+    its registration information."""
+
+    tool: ToolBase
+    """The original tool function."""
+
+    # Execution related fields
+    extended_model: Type[BaseModel] | None = field(init=False, default=None)
+    """The base model used to extend the JSON schema of the original tool
+    function, so that we can dynamically adjust the tool function."""
+
+    # Tools management fields
+    group: str | Literal["basic"] = "basic"
+    """The belonging group of the tool function"""
+    original_name: str | None = field(default=None)
+    """The original name of the tool function when it has been renamed."""
+
+    def __post_init__(self) -> None:
+        """Validate the registered tool function after initialization."""
+        # validate schema
+        if self.tool.input_schema is not None:
+            if not (
+                isinstance(self.tool.input_schema, dict)
+                and self.tool.input_schema.get("type") == "object"
+                and isinstance(self.tool.input_schema.get("properties"), dict)
+            ):
+                raise ValueError(
+                    f"Invalid input_schema: {self.tool.input_schema}. ",
+                )
+
+    def get_tool_schema(
+        self,
+        extended_model: Type[BaseModel] | None = None,
+    ) -> dict:
+        """Get the JSON schema of the tool function via the following steps:
+
+        1. Remove preset_kwargs from the JSON schema, since they are not
+        exposed to the agent.
+        2. If extended_model is provided, merge its schema with the
+        current function schema.
+
+        Args:
+            extended_model (`Type[BaseModel] | None`, optional):
+                The dynamic BaseModel used to extend the original function. If
+                provided, the given BaseModel will be merged into the original
+                function schema instead of the extended_model field.
+
+        Returns:
+            `dict`: The JSON schema of the tool function.
+        """
+        input_schema = deepcopy(self.tool.input_schema)
+        _remove_title_field(input_schema)
+        function_schema: dict = {
+            "type": "function",
+            "function": {
+                "name": self.tool.name,
+                "description": self.tool.description,
+                "parameters": input_schema,
+            },
+        }
+
+        extended_model = extended_model or self.extended_model
+
+        if extended_model is None:
+            return function_schema
+
+        # Merge the extended model with the original JSON schema
+        extended_schema = extended_model.model_json_schema()
+
+        _remove_title_field(extended_schema)
+
+        # Merge properties from extended schema
+        for key, value in extended_schema["properties"].items():
+            if key in function_schema["function"]["parameters"]["properties"]:
+                raise ValueError(
+                    f"The field `{key}` already exists in the original "
+                    f"function schema of `{self.tool.name}`. Try to use a "
+                    "different name.",
+                )
+
+            function_schema["function"]["parameters"]["properties"][
+                key
+            ] = value
+
+            if key in extended_schema.get("required", []):
+                if "required" not in function_schema["function"]["parameters"]:
+                    function_schema["function"]["parameters"]["required"] = []
+                function_schema["function"]["parameters"]["required"].append(
+                    key,
+                )
+
+        # Merge $defs from extended schema to support nested models
+        if "$defs" in extended_schema:
+            merged_params = function_schema["function"]["parameters"]
+            if "$defs" not in merged_params:
+                merged_params["$defs"] = {}
+
+            # Check for conflicts and merge $defs
+            for def_key, def_value in extended_schema["$defs"].items():
+                def_value_copy = deepcopy(def_value)
+                _remove_title_field(
+                    def_value_copy,
+                )  # pylint: disable=protected-access
+
+                if def_key in merged_params["$defs"]:
+                    # Check if the two definitions are from the same BaseModel
+                    # by comparing their content
+                    # Create copies and remove title fields for comparison
+
+                    existing_def_copy = deepcopy(
+                        merged_params["$defs"][def_key],
+                    )
+                    _remove_title_field(existing_def_copy)
+
+                    if existing_def_copy != def_value_copy:
+                        # The definitions are different, raise an error
+                        raise ValueError(
+                            f"The $defs key `{def_key}` conflicts with "
+                            f"existing definition in function schema of "
+                            f"`{self.tool.name}`.",
+                        )
+                    # The definitions are the same (from the same BaseModel),
+                    # skip merging this key
+                    continue
+
+                merged_params["$defs"][def_key] = def_value_copy
+
+        return function_schema
+
+
+# The function types that can be registered as tools in AgentScope.
+Function: TypeAlias = (
+    # Sync function
+    Callable[..., ToolChunk]
+    |
+    # Async function
+    Callable[..., Awaitable[ToolChunk]]
+    |
+    # Sync generator function
+    Callable[..., Generator[ToolChunk, None, None]]
+    |
+    # Async generator function
+    Callable[..., AsyncGenerator[ToolChunk, None]]
+    |
+    # Async function that returns async generator
+    Callable[..., Coroutine[Any, Any, AsyncGenerator[ToolChunk, None]]]
+    |
+    # Async function that returns sync generator
+    Callable[..., Coroutine[Any, Any, Generator[ToolChunk, None, None]]]
+)
+
+
+class ToolChoice(BaseModel):
+    """The tool choice configuration.
+
+    Attributes:
+        mode: The tool choice mode. Supports:
+
+            * ``"auto"`` – the model decides whether to call a tool.
+            * ``"none"`` – the model must not call any tool.
+            * ``"required"`` – the model must call at least one tool.
+            * ``str`` (a tool name) – the model **must** call exactly that
+              tool (forced single-tool call).  The name is validated against
+              ``tools`` (if provided) or against the full tools list passed to
+              the model.
+
+        tools: An optional list of tool names. When specified, the tool
+            schemas forwarded to the model are filtered to only those tools.
+            This also acts as a validation whitelist for ``mode`` when it
+            is a specific tool name (str): the name must appear in this
+            list.  Prefer using ``mode=<tool_name>`` (str) over
+            ``tools=["<tool_name>"]`` when the goal is a forced single-tool
+            call without changing the available tool set, as the former
+            avoids schema-list changes that would invalidate prompt caches.
+    """
+
+    mode: Literal["auto", "none", "required"] | str
+    tools: list[str] | None = None
diff --git a/src/agentscope/tool/_utils.py b/src/agentscope/tool/_utils.py
new file mode 100644
index 0000000..5d6a410
--- /dev/null
+++ b/src/agentscope/tool/_utils.py
@@ -0,0 +1,160 @@
+# -*- coding: utf-8 -*-
+"""The tool module utils."""
+import inspect
+from typing import Any, Dict, Callable
+
+from docstring_parser import parse
+from pydantic import Field, create_model, ConfigDict
+
+
+def _remove_title_field(schema: dict) -> dict:
+    """Remove the title field from the JSON schema to avoid
+    misleading the LLM."""
+    # The top level title field
+    if "title" in schema:
+        schema.pop("title")
+
+    # properties
+    if "properties" in schema:
+        for prop in schema["properties"].values():
+            if isinstance(prop, dict):
+                _remove_title_field(prop)
+
+    # items
+    if "items" in schema and isinstance(schema["items"], dict):
+        _remove_title_field(schema["items"])
+
+    # additionalProperties
+    if "additionalProperties" in schema and isinstance(
+        schema["additionalProperties"],
+        dict,
+    ):
+        _remove_title_field(schema["additionalProperties"])
+
+    # $defs — referenced sub-schemas, e.g. Pydantic models used as parameter
+    # types generate "$defs": {"SubModel": {"title": "SubModel", ...}}.
+    # These titles are auto-generated noise just like property titles, and
+    # should be removed for the same reason.
+    if "$defs" in schema and isinstance(schema["$defs"], dict):
+        for def_schema in schema["$defs"].values():
+            if isinstance(def_schema, dict):
+                _remove_title_field(def_schema)
+
+    return schema
+
+
+def _extract_func_description(docstring: str) -> str:
+    """Extract the function description from the docstring.
+
+    Args:
+        docstring (`str`):
+            The docstring to extract the function description from.
+
+    Returns:
+        `str`:
+            The extracted function description.
+    """
+    parsed_docstring = parse(docstring or "")
+    descriptions = []
+    if parsed_docstring.short_description is not None:
+        descriptions.append(parsed_docstring.short_description)
+
+    if parsed_docstring.long_description is not None:
+        descriptions.append(parsed_docstring.long_description)
+
+    return "\n".join(descriptions)
+
+
+def _extract_input_schema(
+    tool_func: Callable,
+    include_var_positional: bool = False,
+    include_var_keyword: bool = False,
+) -> dict:
+    """Extract input schema from the tool function's docstring
+
+    Args:
+        tool_func (`ToolFunction`):
+            The tool function to extract the JSON schema from.
+        include_var_positional (`bool`):
+            Whether to include variable positional arguments in the JSON
+            schema.
+        include_var_keyword (`bool`):
+            Whether to include variable keyword arguments in the JSON schema.
+
+    Returns:
+        `dict`:
+            The extracted input JSON schema.
+    """
+    docstring = parse(tool_func.__doc__ or "")
+    params_docstring = {_.arg_name: _.description for _ in docstring.params}
+
+    # Create a dynamic model with the function signature
+    fields = {}
+    for name, param in inspect.signature(tool_func).parameters.items():
+        # Skip the `self` and `cls` parameters
+        if name in ["self", "cls"]:
+            continue
+
+        # Handle `**kwargs`
+        if param.kind == inspect.Parameter.VAR_KEYWORD:
+            if not include_var_keyword:
+                continue
+
+            fields[name] = (
+                Dict[str, Any]
+                if param.annotation == inspect.Parameter.empty
+                else Dict[str, param.annotation],  # type: ignore
+                Field(
+                    description=params_docstring.get(
+                        f"**{name}",
+                        params_docstring.get(name, None),
+                    ),
+                    default={}
+                    if param.default is param.empty
+                    else param.default,
+                ),
+            )
+
+        elif param.kind == inspect.Parameter.VAR_POSITIONAL:
+            if not include_var_positional:
+                continue
+
+            fields[name] = (
+                list[Any]
+                if param.annotation == inspect.Parameter.empty
+                else list[param.annotation],  # type: ignore
+                Field(
+                    description=params_docstring.get(
+                        f"*{name}",
+                        params_docstring.get(name, None),
+                    ),
+                    default=[]
+                    if param.default is param.empty
+                    else param.default,
+                ),
+            )
+
+        else:
+            fields[name] = (
+                Any
+                if param.annotation == inspect.Parameter.empty
+                else param.annotation,
+                Field(
+                    description=params_docstring.get(name, None),
+                    default=...
+                    if param.default is param.empty
+                    else param.default,
+                ),
+            )
+
+    base_model = create_model(
+        "_StructuredOutputDynamicClass",
+        __config__=ConfigDict(arbitrary_types_allowed=True),
+        **fields,
+    )
+    params_json_schema = base_model.model_json_schema()
+
+    # Remove the title from the json schema
+    _remove_title_field(params_json_schema)
+
+    return params_json_schema
diff --git a/src/agentscope/tts/__init__.py b/src/agentscope/tts/__init__.py
new file mode 100644
index 0000000..43180fe
--- /dev/null
+++ b/src/agentscope/tts/__init__.py
@@ -0,0 +1,23 @@
+# -*- coding: utf-8 -*-
+"""The TTS (Text-to-Speech) module in AgentScope."""
+
+from ._tts_base import TTSModelBase
+from ._tts_model_card import TTSModelCard
+from ._tts_response import TTSResponse, TTSUsage
+from ._dashscope import (
+    DashScopeCosyVoiceTTSModel,
+    DashScopeTTSModel,
+    DashScopeRealtimeTTSModel,
+)
+from ._openai import OpenAITTSModel
+
+__all__ = [
+    "TTSModelBase",
+    "TTSModelCard",
+    "TTSResponse",
+    "TTSUsage",
+    "DashScopeCosyVoiceTTSModel",
+    "DashScopeTTSModel",
+    "DashScopeRealtimeTTSModel",
+    "OpenAITTSModel",
+]
diff --git a/src/agentscope/tts/_dashscope/__init__.py b/src/agentscope/tts/_dashscope/__init__.py
new file mode 100644
index 0000000..03599ae
--- /dev/null
+++ b/src/agentscope/tts/_dashscope/__init__.py
@@ -0,0 +1,12 @@
+# -*- coding: utf-8 -*-
+"""The DashScope TTS module."""
+
+from ._cosyvoice_model import DashScopeCosyVoiceTTSModel
+from ._model import DashScopeTTSModel
+from ._realtime_model import DashScopeRealtimeTTSModel
+
+__all__ = [
+    "DashScopeCosyVoiceTTSModel",
+    "DashScopeTTSModel",
+    "DashScopeRealtimeTTSModel",
+]
diff --git a/src/agentscope/tts/_dashscope/_cosyvoice_model.py b/src/agentscope/tts/_dashscope/_cosyvoice_model.py
new file mode 100644
index 0000000..2b12071
--- /dev/null
+++ b/src/agentscope/tts/_dashscope/_cosyvoice_model.py
@@ -0,0 +1,397 @@
+# -*- coding: utf-8 -*-
+"""DashScope CosyVoice TTS model implementation."""
+import asyncio
+import base64
+import io
+import os
+from typing import Any, AsyncGenerator, Literal, TYPE_CHECKING
+import wave
+
+from pydantic import BaseModel, Field
+
+from .._tts_base import TTSModelBase
+from .._tts_model_card import TTSModelCard
+from .._tts_response import TTSResponse
+from ._cosyvoice_utils import (
+    _BITS_PER_SAMPLE,
+    _CHANNELS,
+    _make_cosyvoice_callback_class,
+    _MEDIA_TYPE,
+    _SAMPLE_RATE,
+)
+from ..._logging import logger
+from ...credential import DashScopeCredential
+from ...message import DataBlock, Base64Source
+
+if TYPE_CHECKING:
+    from dashscope.audio.tts_v2 import SpeechSynthesizer, ResultCallback
+
+
+class DashScopeCosyVoiceTTSModel(TTSModelBase):
+    """DashScope CosyVoice TTS model using the WebSocket SpeechSynthesizer."""
+
+    class Parameters(BaseModel):
+        """Frontend-exposed parameters for DashScope CosyVoice TTS models."""
+
+        voice: str = Field(
+            default="longanhuan",
+            title="Voice",
+            description="The voice to use for synthesis.",
+        )
+        realtime: bool = Field(
+            default=False,
+            title="Realtime",
+            description="Whether to enable streaming input mode.",
+        )
+
+    type: Literal["dashscope_cosyvoice_tts"] = "dashscope_cosyvoice_tts"
+    """The type of the TTS model."""
+
+    _MODELS_DIR = os.path.join(os.path.dirname(__file__), "_cosyvoice_models")
+
+    def __init__(
+        self,
+        credential: DashScopeCredential,
+        model: str = "cosyvoice-v3-flash",
+        parameters: "DashScopeCosyVoiceTTSModel.Parameters | None" = None,
+        stream: bool = True,
+        cold_start_length: int | None = None,
+        cold_start_words: int | None = None,
+        max_retries: int = 3,
+        retry_delay: float = 5.0,
+    ) -> None:
+        """Initialize the DashScope CosyVoice TTS model.
+
+        Args:
+            credential (`DashScopeCredential`):
+                The DashScope credential used to authenticate the API call.
+            model (`str`, defaults to ``"cosyvoice-v3-flash"``):
+                The CosyVoice model name.
+            parameters (`DashScopeCosyVoiceTTSModel.Parameters | None`, \
+            defaults to `None`):
+                The TTS parameters. When ``None``, the default voice is used.
+            stream (`bool`, defaults to `True`):
+                Whether :meth:`synthesize` returns an async generator yielding
+                ``TTSResponse`` chunks. When ``False``, audio is aggregated.
+            cold_start_length (`int | None`, defaults to `None`):
+                Minimum character count before the first realtime text chunk is
+                sent to the synthesizer.
+            cold_start_words (`int | None`, defaults to `None`):
+                Minimum word count before the first realtime text chunk is
+                sent.
+            max_retries (`int`, defaults to `3`):
+                Max retry attempts on realtime synthesis failure.
+            retry_delay (`float`, defaults to `5.0`):
+                Initial retry delay in seconds (exponential backoff).
+        """
+        super().__init__(
+            credential=credential,
+            model=model,
+            parameters=parameters,
+            stream=stream,
+        )
+        self.realtime = self.parameters.realtime
+        self.cold_start_length = cold_start_length
+        self.cold_start_words = cold_start_words
+        self.max_retries = max_retries
+        self.retry_delay = retry_delay
+
+        self._synthesizer: Any = None
+        self._callback: Any = None
+        self._connected = False
+        self._cold_start_buffer: str = ""
+        self._cold_start_done: bool = False
+        self._accumulated_text: str = ""
+
+    @classmethod
+    def list_models(
+        cls,
+        custom_yaml_dir: str | None = None,
+    ) -> list[TTSModelCard]:
+        """List CosyVoice model cards from the dedicated card directory."""
+        return super().list_models(
+            custom_yaml_dir=custom_yaml_dir or cls._MODELS_DIR,
+        )
+
+    async def synthesize(
+        self,
+        text: str | None = None,
+        **kwargs: Any,
+    ) -> TTSResponse | AsyncGenerator[TTSResponse, None]:
+        """Call the DashScope CosyVoice TTS API to synthesize speech.
+
+        Args:
+            text (`str | None`, optional):
+                The text to be synthesized.
+            **kwargs (`Any`):
+                Reserved for API compatibility. Runtime synthesis options
+                are configured when the model is initialized.
+
+        Returns:
+            `TTSResponse | AsyncGenerator[TTSResponse, None]`:
+                A single aggregated response when ``stream=False``, or an
+                async generator yielding incremental chunks when
+                ``stream=True``.
+        """
+        if self.realtime:
+            return await self._synthesize_realtime(text)
+
+        return self._synthesize_once(text)
+
+    def _synthesize_once(
+        self,
+        text: str | None = None,
+    ) -> TTSResponse | AsyncGenerator[TTSResponse, None]:
+        """Synthesize text with the non-realtime one-shot SDK path."""
+        if not text:
+            return TTSResponse(content=None)
+
+        synthesizer, callback = self._create_synthesizer(
+            callback=self.stream,
+        )
+
+        if self.stream:
+            assert callback is not None
+            synthesizer.call(text=text)
+            return callback.get_audio_chunks()
+
+        audio_data = synthesizer.call(text=text)
+        if not audio_data:
+            return TTSResponse(content=None)
+        return self._build_wav_response(audio_data)
+
+    def _create_synthesizer(
+        self,
+        *,
+        callback: bool,
+    ) -> tuple["SpeechSynthesizer", "ResultCallback | None"]:
+        """Create a fresh SpeechSynthesizer and optional callback."""
+        import dashscope
+        from dashscope.audio.tts_v2 import AudioFormat, SpeechSynthesizer
+
+        dashscope.api_key = self.credential.api_key.get_secret_value()
+
+        callback_instance = None
+        if callback:
+            callback_cls = _make_cosyvoice_callback_class()
+            callback_instance = callback_cls()
+
+        synthesizer = SpeechSynthesizer(
+            model=self.model,
+            voice=self.parameters.voice,
+            format=AudioFormat.PCM_24000HZ_MONO_16BIT,
+            callback=callback_instance,
+        )
+        return synthesizer, callback_instance
+
+    async def connect(self) -> None:
+        """Initialize the SpeechSynthesizer for realtime mode."""
+        if self._connected:
+            return
+        self._synthesizer, self._callback = self._create_synthesizer(
+            callback=True,
+        )
+        self._connected = True
+
+    async def close(self) -> None:
+        """Close the realtime SpeechSynthesizer."""
+        if not self._connected:
+            return
+        self._connected = False
+        try:
+            if self._synthesizer is not None:
+                self._synthesizer.close()
+        except Exception:
+            pass
+
+    async def _reconnect(self) -> None:
+        """Reconnect by recreating the realtime synthesizer."""
+        try:
+            if self._synthesizer is not None:
+                self._synthesizer.close()
+        except Exception:
+            pass
+        self._connected = False
+        self._cold_start_buffer = ""
+        self._cold_start_done = False
+        await self.connect()
+
+    async def push(
+        self,
+        text: str,
+        **kwargs: Any,
+    ) -> TTSResponse:
+        """Push an incremental text delta for realtime synthesis."""
+        del kwargs
+        if not self.realtime:
+            return await super().push(text)
+
+        if not self._connected:
+            raise RuntimeError(
+                "TTS model is not connected. Call `connect()` first.",
+            )
+
+        if not text:
+            return TTSResponse(content=None)
+
+        self._accumulated_text += text
+
+        if self._cold_start_done:
+            text_to_send = text
+        else:
+            self._cold_start_buffer += text
+            if (
+                self.cold_start_length
+                and len(self._cold_start_buffer) < self.cold_start_length
+            ) or (
+                self.cold_start_words
+                and len(self._cold_start_buffer.split())
+                < self.cold_start_words
+            ):
+                return self._callback.get_audio_response(block=False)
+            text_to_send = self._cold_start_buffer
+            self._cold_start_buffer = ""
+            self._cold_start_done = True
+
+        try:
+            self._synthesizer.streaming_call(text_to_send)
+        except Exception:
+            return TTSResponse(content=None)
+
+        return self._callback.get_audio_response(block=False)
+
+    async def _synthesize_realtime(
+        self,
+        text: str | None = None,
+    ) -> TTSResponse | AsyncGenerator[TTSResponse, None]:
+        """Finalize synthesis for the current realtime utterance."""
+        if not self._connected:
+            raise RuntimeError(
+                "TTS model is not connected. Call `connect()` first.",
+            )
+
+        if text is not None:
+            self._accumulated_text += text
+
+        unsent = self._cold_start_buffer
+        if text is not None:
+            unsent += text
+        self._cold_start_buffer = ""
+
+        full_text = self._accumulated_text
+        delay = self.retry_delay
+
+        try:
+            if not full_text and not unsent:
+                if self.stream:
+
+                    async def _empty_gen() -> AsyncGenerator[
+                        TTSResponse,
+                        None,
+                    ]:
+                        yield TTSResponse(content=None)
+
+                    return _empty_gen()
+                return TTSResponse(content=None)
+
+            for attempt in range(self.max_retries):
+                try:
+                    if unsent:
+                        self._synthesizer.streaming_call(unsent)
+
+                    self._synthesizer.streaming_complete()
+
+                    finished = await asyncio.to_thread(
+                        self._callback.finish_event.wait,
+                        30,
+                    )
+
+                    if not finished:
+                        logger.warning(
+                            "CosyVoice TTS: timed out waiting for synthesis "
+                            "completion (30s)",
+                        )
+                        if attempt < self.max_retries - 1:
+                            await asyncio.sleep(delay)
+                            await self._reconnect()
+                            unsent = full_text
+                            delay *= 2
+                            continue
+                        raise RuntimeError(
+                            "CosyVoice TTS synthesis timed out after 30s",
+                        )
+
+                    if full_text and not self._callback.has_audio_data():
+                        if attempt < self.max_retries - 1:
+                            logger.warning(
+                                "CosyVoice TTS: no audio received, retrying "
+                                "(%d/%d) in %.1fs...",
+                                attempt + 1,
+                                self.max_retries,
+                                delay,
+                            )
+                            await asyncio.sleep(delay)
+                            await self._reconnect()
+                            unsent = full_text
+                            delay *= 2
+                            continue
+                        raise RuntimeError(
+                            f"CosyVoice TTS synthesis failed: no audio after "
+                            f"{self.max_retries} attempts",
+                        )
+                    break
+
+                except RuntimeError:
+                    raise
+                except Exception as e:
+                    if attempt < self.max_retries - 1:
+                        logger.warning(
+                            "CosyVoice TTS error, retrying (%d/%d) in "
+                            "%.1fs: %s",
+                            attempt + 1,
+                            self.max_retries,
+                            delay,
+                            e,
+                        )
+                        await asyncio.sleep(delay)
+                        await self._reconnect()
+                        unsent = full_text
+                        delay *= 2
+                    else:
+                        raise
+
+            if self.stream:
+                return self._callback.get_audio_chunks()
+
+            response = self._callback.get_audio_response(block=True)
+            self._callback.reset()
+            return response
+        finally:
+            self._reset_state()
+
+    def _reset_state(self) -> None:
+        """Reset per-utterance realtime tracking state."""
+        self._cold_start_buffer = ""
+        self._cold_start_done = False
+        self._accumulated_text = ""
+
+    @staticmethod
+    def _build_wav_response(
+        audio_data: bytes,
+    ) -> TTSResponse:
+        """Build a self-contained WAV response from PCM audio bytes."""
+        buf = io.BytesIO()
+        with wave.open(buf, "wb") as wav:
+            wav.setnchannels(_CHANNELS)
+            wav.setsampwidth(_BITS_PER_SAMPLE // 8)
+            wav.setframerate(_SAMPLE_RATE)
+            wav.writeframes(audio_data)
+
+        return TTSResponse(
+            content=DataBlock(
+                source=Base64Source(
+                    data=base64.b64encode(buf.getvalue()).decode("ascii"),
+                    media_type=_MEDIA_TYPE,
+                ),
+            ),
+        )
diff --git a/src/agentscope/tts/_dashscope/_cosyvoice_models/cosyvoice-v3-flash.yaml b/src/agentscope/tts/_dashscope/_cosyvoice_models/cosyvoice-v3-flash.yaml
new file mode 100644
index 0000000..5810bfd
--- /dev/null
+++ b/src/agentscope/tts/_dashscope/_cosyvoice_models/cosyvoice-v3-flash.yaml
@@ -0,0 +1,23 @@
+name: cosyvoice-v3-flash
+label: CosyVoice-v3-Flash
+status: active
+
+input_types:
+  - text/plain
+
+output_types:
+  - audio/wav
+
+voices:
+  # Source: https://help.aliyun.com/en/model-studio/cosyvoice-voice-list
+  - longanyang
+  - longanhuan
+  - longhuhu_v3
+  - longyingmu_v3
+  - longxiaochun_v3
+  - longxiaoxia_v3
+  - longlaotie_v3
+  - longshuo_v3
+  - longshu_v3
+
+parameter_overrides: {}
diff --git a/src/agentscope/tts/_dashscope/_cosyvoice_models/cosyvoice-v3-plus.yaml b/src/agentscope/tts/_dashscope/_cosyvoice_models/cosyvoice-v3-plus.yaml
new file mode 100644
index 0000000..fa68a04
--- /dev/null
+++ b/src/agentscope/tts/_dashscope/_cosyvoice_models/cosyvoice-v3-plus.yaml
@@ -0,0 +1,16 @@
+name: cosyvoice-v3-plus
+label: CosyVoice-v3-Plus
+status: active
+
+input_types:
+  - text/plain
+
+output_types:
+  - audio/wav
+
+voices:
+  # Source: https://help.aliyun.com/en/model-studio/cosyvoice-voice-list
+  - longanyang
+  - longanhuan
+
+parameter_overrides: {}
diff --git a/src/agentscope/tts/_dashscope/_cosyvoice_utils.py b/src/agentscope/tts/_dashscope/_cosyvoice_utils.py
new file mode 100644
index 0000000..b1573b5
--- /dev/null
+++ b/src/agentscope/tts/_dashscope/_cosyvoice_utils.py
@@ -0,0 +1,157 @@
+# -*- coding: utf-8 -*-
+"""Shared helpers for DashScope CosyVoice TTS models."""
+import asyncio
+import base64
+import threading
+from typing import Any, AsyncGenerator, TYPE_CHECKING
+
+from .._tts_response import TTSResponse
+from ..._logging import logger
+from ..._utils._audio import _build_streaming_wav_header
+from ...message import DataBlock, Base64Source
+
+if TYPE_CHECKING:
+    from dashscope.audio.tts_v2 import ResultCallback
+
+
+_SAMPLE_RATE = 24000
+_CHANNELS = 1
+_BITS_PER_SAMPLE = 16
+_MEDIA_TYPE = "audio/wav"
+
+
+def _build_audio_response(
+    audio_data: bytes,
+    media_type: str,
+    *,
+    is_last: bool = True,
+) -> TTSResponse:
+    """Build a TTSResponse containing base64-encoded audio data."""
+    return TTSResponse(
+        content=DataBlock(
+            source=Base64Source(
+                data=base64.b64encode(audio_data).decode("ascii"),
+                media_type=media_type,
+            ),
+        ),
+        is_last=is_last,
+    )
+
+
+def _make_cosyvoice_callback_class() -> type["ResultCallback"]:
+    """Create the shared CosyVoice callback class lazily."""
+    from dashscope.audio.tts_v2 import ResultCallback
+
+    class _CosyVoiceCallback(ResultCallback):
+        """Accumulate PCM audio from the WebSocket and expose deltas."""
+
+        def __init__(self) -> None:
+            """Initialize callback with audio buffer and synchronization
+            events."""
+            super().__init__()
+            self.chunk_event = threading.Event()
+            self.finish_event = threading.Event()
+            self._pcm_bytes: bytearray = bytearray()
+            self._consumed: int = 0
+
+        def on_open(self) -> None:
+            """Handle WebSocket open by resetting audio state."""
+            self._pcm_bytes = bytearray()
+            self._consumed = 0
+            self.finish_event.clear()
+            self.chunk_event.clear()
+
+        def on_data(self, data: bytes) -> None:
+            """Handle incoming PCM audio data."""
+            if data:
+                self._pcm_bytes += data
+                if not self.chunk_event.is_set():
+                    self.chunk_event.set()
+
+        def on_complete(self) -> None:
+            """Handle synthesis completion."""
+            self.finish_event.set()
+            self.chunk_event.set()
+
+        def on_close(self) -> None:
+            """Handle WebSocket close."""
+            self.finish_event.set()
+            self.chunk_event.set()
+
+        def on_error(self, message: Any) -> None:
+            """Handle synthesis error."""
+            logger.error("CosyVoice TTS error: %s", message)
+            self.finish_event.set()
+            self.chunk_event.set()
+
+        def _take_delta(self, header: bool = False) -> bytes | None:
+            """Return new PCM bytes since last call, or None if empty."""
+            new_data = self._pcm_bytes[self._consumed :]
+            if not new_data:
+                return None
+            self._consumed = len(self._pcm_bytes)
+            if header:
+                return _build_streaming_wav_header(
+                    sample_rate=_SAMPLE_RATE,
+                    channels=_CHANNELS,
+                    bits_per_sample=_BITS_PER_SAMPLE,
+                ) + bytes(new_data)
+            return bytes(new_data)
+
+        def get_audio_response(self, block: bool) -> TTSResponse:
+            """Return incremental audio delta."""
+            if block:
+                self.finish_event.wait()
+            delta = self._take_delta(header=self._consumed == 0)
+            if delta:
+                return _build_audio_response(delta, _MEDIA_TYPE)
+            return TTSResponse(content=None)
+
+        async def get_audio_chunks(
+            self,
+        ) -> AsyncGenerator[TTSResponse, None]:
+            """Yield incremental audio chunks as they arrive."""
+            header_sent = self._consumed > 0
+            while True:
+                if self.finish_event.is_set():
+                    delta = self._take_delta(header=not header_sent)
+                    if delta:
+                        yield _build_audio_response(
+                            delta,
+                            _MEDIA_TYPE,
+                            is_last=True,
+                        )
+                    else:
+                        yield TTSResponse(content=None, is_last=True)
+                    self.reset()
+                    break
+
+                if self.chunk_event.is_set():
+                    self.chunk_event.clear()
+                else:
+                    await asyncio.to_thread(self.chunk_event.wait, 30)
+
+                if self.finish_event.is_set():
+                    continue
+
+                delta = self._take_delta(header=not header_sent)
+                if delta:
+                    header_sent = True
+                    yield _build_audio_response(
+                        delta,
+                        _MEDIA_TYPE,
+                        is_last=False,
+                    )
+
+        def reset(self) -> None:
+            """Reset internal state for the next utterance."""
+            self.finish_event.clear()
+            self.chunk_event.clear()
+            self._pcm_bytes = bytearray()
+            self._consumed = 0
+
+        def has_audio_data(self) -> bool:
+            """Return whether any audio data has been received."""
+            return bool(self._pcm_bytes)
+
+    return _CosyVoiceCallback
diff --git a/src/agentscope/tts/_dashscope/_model.py b/src/agentscope/tts/_dashscope/_model.py
new file mode 100644
index 0000000..8f63a60
--- /dev/null
+++ b/src/agentscope/tts/_dashscope/_model.py
@@ -0,0 +1,252 @@
+# -*- coding: utf-8 -*-
+"""DashScope TTS model implementation using MultiModalConversation API."""
+import base64
+import io
+import wave
+from datetime import datetime
+from typing import (
+    Any,
+    AsyncGenerator,
+    Generator,
+    Literal,
+    TYPE_CHECKING,
+)
+
+from pydantic import BaseModel, Field
+
+from .._tts_base import TTSModelBase
+from .._tts_response import TTSResponse, TTSUsage
+from ..._utils._audio import _build_streaming_wav_header
+from ...credential import DashScopeCredential
+from ...message import DataBlock, Base64Source
+
+if TYPE_CHECKING:
+    from dashscope.api_entities.dashscope_response import (
+        MultiModalConversationResponse,
+    )
+
+
+# DashScope TTS returns raw PCM (24kHz, mono, 16-bit). We wrap it as WAV
+# on the way out so the frontend can play it: streaming deltas get a
+# streaming WAV header on the first chunk; non-streaming returns a
+# self-contained fixed-size WAV.
+_TTS_SAMPLE_RATE = 24000
+_TTS_CHANNELS = 1
+_TTS_BITS_PER_SAMPLE = 16
+_DEFAULT_MEDIA_TYPE = "audio/wav"
+_SENTINEL = object()
+
+
+def _parse_usage(usage: Any, elapsed: float) -> TTSUsage | None:
+    """Extract a TTSUsage from the DashScope usage object, or None."""
+    if usage is None:
+        return None
+    return TTSUsage(
+        input_tokens=getattr(usage, "input_tokens", 0) or 0,
+        output_tokens=getattr(usage, "output_tokens", 0) or 0,
+        time=elapsed,
+    )
+
+
+class DashScopeTTSModel(TTSModelBase):
+    """DashScope TTS model implementation using the MultiModalConversation
+    API. For more details please see the `official document
+    <https://bailian.console.aliyun.com/?tab=doc#/doc/?type=model&url=2879134>`_.
+    """
+
+    class Parameters(BaseModel):
+        """Frontend-exposed parameters for DashScope TTS models."""
+
+        voice: str = Field(
+            default="Cherry",
+            title="Voice",
+            description="The voice to use for synthesis.",
+        )
+
+    type: Literal["dashscope_tts"] = "dashscope_tts"
+    """The type of the TTS model."""
+
+    realtime: bool = False
+
+    def __init__(
+        self,
+        credential: DashScopeCredential,
+        model: str = "qwen3-tts-flash",
+        parameters: "DashScopeTTSModel.Parameters | None" = None,
+        stream: bool = True,
+    ) -> None:
+        """Initialize the DashScope TTS model.
+
+        .. note:: More details about the parameters, such as ``model``
+         and ``voice``, can be found in the `official document
+         <https://bailian.console.aliyun.com/?tab=doc#/doc/?type=model&url=2879134>`_.
+
+        Args:
+            credential (`DashScopeCredential`):
+                The DashScope credential used to authenticate the API call.
+            model (`str`, defaults to ``"qwen3-tts-flash"``):
+                The TTS model name. Supported models include
+                ``qwen3-tts-flash``, ``qwen-tts``, etc.
+            parameters (`DashScopeTTSModel.Parameters | None`, defaults to \
+            `None`):
+                The TTS parameters (voice, language, etc.). When ``None``,
+                the default parameters will be used.
+            stream (`bool`, defaults to `True`):
+                Whether to use streaming output. When `True`,
+                :meth:`synthesize` returns an async generator yielding
+                ``TTSResponse`` chunks; when `False`, it returns a single
+                aggregated ``TTSResponse``.
+        """
+        super().__init__(
+            credential=credential,
+            model=model,
+            parameters=parameters,
+            stream=stream,
+        )
+
+    async def synthesize(
+        self,
+        text: str | None = None,
+        **kwargs: Any,
+    ) -> TTSResponse | AsyncGenerator[TTSResponse, None]:
+        """Call the DashScope TTS API to synthesize speech from text.
+
+        Args:
+            text (`str | None`, optional):
+                The text to be synthesized.
+            **kwargs (`Any`):
+                Additional keyword arguments to pass to the TTS API call.
+
+        Returns:
+            `TTSResponse | AsyncGenerator[TTSResponse, None]`:
+                A single ``TTSResponse`` when ``stream=False``, or an async
+                generator yielding ``TTSResponse`` chunks when ``stream=True``.
+        """
+        if not text:
+            return TTSResponse(content=None)
+
+        import dashscope
+
+        response = dashscope.MultiModalConversation.call(
+            model=self.model,
+            api_key=self.credential.api_key.get_secret_value(),
+            text=text,
+            voice=self.parameters.voice,
+            stream=True,
+            **kwargs,
+        )
+
+        if self.stream:
+            return self._parse_into_async_generator(response)
+
+        return self._aggregate_sync(response)
+
+    @staticmethod
+    def _aggregate_sync(
+        response: Generator["MultiModalConversationResponse", None, None],
+    ) -> TTSResponse:
+        """Aggregate all streaming chunks into a single self-contained WAV."""
+        start_datetime = datetime.now()
+        audio_bytes = bytearray()
+        usage = None
+        for chunk in response:
+            if chunk.usage is not None:
+                usage = chunk.usage
+            if chunk.output is not None:
+                audio = chunk.output.audio
+                if audio and audio.data:
+                    audio_bytes += base64.b64decode(audio.data)
+        elapsed = (datetime.now() - start_datetime).total_seconds()
+
+        buf = io.BytesIO()
+        with wave.open(buf, "wb") as wav:
+            wav.setnchannels(_TTS_CHANNELS)
+            wav.setsampwidth(_TTS_BITS_PER_SAMPLE // 8)
+            wav.setframerate(_TTS_SAMPLE_RATE)
+            wav.writeframes(bytes(audio_bytes))
+
+        return TTSResponse(
+            content=DataBlock(
+                source=Base64Source(
+                    data=base64.b64encode(buf.getvalue()).decode("ascii"),
+                    media_type=_DEFAULT_MEDIA_TYPE,
+                ),
+            ),
+            usage=_parse_usage(usage, elapsed),
+        )
+
+    @staticmethod
+    async def _parse_into_async_generator(
+        response: Generator["MultiModalConversationResponse", None, None],
+    ) -> AsyncGenerator[TTSResponse, None]:
+        """Parse the streaming TTS response into an async generator.
+
+        Each yielded ``TTSResponse`` carries an **incremental** WAV chunk:
+        the first chunk is prefixed with a streaming WAV/RIFF header so the
+        frontend can start playback immediately (without waiting for
+        end-of-stream); subsequent chunks are raw PCM bytes appended to that
+        open stream. The final response has ``is_last=True``.
+
+        Args:
+            response (`Generator[MultiModalConversationResponse, None, None]`):
+                The streaming response from the DashScope TTS API.
+
+        Yields:
+            `TTSResponse`:
+                A ``TTSResponse`` for each incremental audio chunk; the final
+                response has ``is_last=True``.
+        """
+        pending: TTSResponse | None = None
+        header_sent = False
+        usage = None
+        start_datetime = datetime.now()
+        it = iter(response)
+        while True:
+            chunk = next(it, _SENTINEL)
+            if chunk is _SENTINEL:
+                break
+            if chunk.usage is not None:
+                usage = chunk.usage
+            if chunk.output is None:
+                continue
+            audio = chunk.output.audio
+            if not audio or not audio.data:
+                continue
+            delta_bytes = base64.b64decode(audio.data)
+            if not delta_bytes:
+                continue
+            if not header_sent:
+                payload = (
+                    _build_streaming_wav_header(
+                        sample_rate=_TTS_SAMPLE_RATE,
+                        channels=_TTS_CHANNELS,
+                        bits_per_sample=_TTS_BITS_PER_SAMPLE,
+                    )
+                    + delta_bytes
+                )
+                header_sent = True
+            else:
+                payload = delta_bytes
+            if pending is not None:
+                yield pending
+            pending = TTSResponse(
+                content=DataBlock(
+                    source=Base64Source(
+                        data=base64.b64encode(payload).decode("ascii"),
+                        media_type=_DEFAULT_MEDIA_TYPE,
+                    ),
+                ),
+                is_last=False,
+            )
+        elapsed = (datetime.now() - start_datetime).total_seconds()
+
+        if pending is not None:
+            pending.is_last = True
+            pending.usage = _parse_usage(usage, elapsed)
+            yield pending
+        else:
+            yield TTSResponse(
+                content=None,
+                is_last=True,
+                usage=_parse_usage(usage, elapsed),
+            )
diff --git a/src/agentscope/tts/_dashscope/_models/qwen3-tts-flash-realtime.yaml b/src/agentscope/tts/_dashscope/_models/qwen3-tts-flash-realtime.yaml
new file mode 100644
index 0000000..a0f4f0c
--- /dev/null
+++ b/src/agentscope/tts/_dashscope/_models/qwen3-tts-flash-realtime.yaml
@@ -0,0 +1,19 @@
+name: qwen3-tts-flash-realtime
+label: Qwen3-TTS-Flash-Realtime
+status: active
+realtime: true
+
+input_types:
+  - text/plain
+
+output_types:
+  - audio/wav
+
+voices:
+  # Source: https://help.aliyun.com/zh/model-studio/qwen-tts-voice-list
+  - Cherry
+  - Serena
+  - Ethan
+  - Chelsie
+
+parameter_overrides: {}
diff --git a/src/agentscope/tts/_dashscope/_models/qwen3-tts-flash.yaml b/src/agentscope/tts/_dashscope/_models/qwen3-tts-flash.yaml
new file mode 100644
index 0000000..6750a50
--- /dev/null
+++ b/src/agentscope/tts/_dashscope/_models/qwen3-tts-flash.yaml
@@ -0,0 +1,18 @@
+name: qwen3-tts-flash
+label: Qwen3-TTS-Flash
+status: active
+
+input_types:
+  - text/plain
+
+output_types:
+  - audio/wav
+
+voices:
+  # Source: https://help.aliyun.com/zh/model-studio/qwen-tts-voice-list
+  - Cherry
+  - Serena
+  - Ethan
+  - Chelsie
+
+parameter_overrides: {}
diff --git a/src/agentscope/tts/_dashscope/_realtime_model.py b/src/agentscope/tts/_dashscope/_realtime_model.py
new file mode 100644
index 0000000..49df43c
--- /dev/null
+++ b/src/agentscope/tts/_dashscope/_realtime_model.py
@@ -0,0 +1,468 @@
+# -*- coding: utf-8 -*-
+"""DashScope Realtime TTS model implementation."""
+import asyncio
+import base64
+import threading
+from typing import Any, AsyncGenerator, Literal, TYPE_CHECKING
+
+from pydantic import BaseModel, Field
+
+from .._tts_base import TTSModelBase
+from .._tts_response import TTSResponse
+from ..._logging import logger
+from ..._utils._audio import _build_streaming_wav_header
+from ...credential import DashScopeCredential
+from ...message import DataBlock, Base64Source
+
+if TYPE_CHECKING:
+    from dashscope.audio.qwen_tts_realtime import (
+        QwenTtsRealtime,
+        QwenTtsRealtimeCallback,
+    )
+
+
+_MEDIA_TYPE = "audio/wav"
+_SAMPLE_RATE = 24000
+_CHANNELS = 1
+_BITS_PER_SAMPLE = 16
+
+
+def _make_callback_class() -> type["QwenTtsRealtimeCallback"]:
+    """Create the DashScope realtime TTS callback class lazily to avoid
+    importing dashscope at module level."""
+    from dashscope.audio.qwen_tts_realtime import QwenTtsRealtimeCallback
+
+    class _Callback(QwenTtsRealtimeCallback):
+        """Internal callback that accumulates PCM audio from the WebSocket.
+
+        Audio data is stored as raw bytes (decoded from base64) to allow
+        incremental delta extraction without base64 boundary issues.
+        """
+
+        def __init__(self) -> None:
+            """Initialize callback with audio buffer and synchronization
+            events."""
+            super().__init__()
+            self.chunk_event = threading.Event()
+            self.finish_event = threading.Event()
+            self._pcm_bytes: bytearray = bytearray()
+            self._consumed: int = 0
+
+        def on_event(self, response: dict[str, Any]) -> None:
+            """Handle incoming WebSocket events from the TTS service."""
+            try:
+                event_type = response.get("type")
+
+                if event_type == "session.created":
+                    self._pcm_bytes = bytearray()
+                    self._consumed = 0
+                    self.finish_event.clear()
+                    self.chunk_event.clear()
+
+                elif event_type == "response.audio.delta":
+                    audio_data = response.get("delta")
+                    if audio_data:
+                        if isinstance(audio_data, bytes):
+                            self._pcm_bytes += audio_data
+                        else:
+                            self._pcm_bytes += base64.b64decode(audio_data)
+                        if not self.chunk_event.is_set():
+                            self.chunk_event.set()
+
+                elif event_type == "session.finished":
+                    self.chunk_event.set()
+                    self.finish_event.set()
+
+            except Exception:
+                logger.exception("Error in TTS WebSocket callback")
+                self.finish_event.set()
+
+        def on_close(self, close_status_code: int, close_msg: str) -> None:
+            """Handle WebSocket connection closure."""
+            self.finish_event.set()
+            self.chunk_event.set()
+            if close_status_code:
+                logger.warning(
+                    "TTS WebSocket closed with code %s: %s",
+                    close_status_code,
+                    close_msg,
+                )
+
+        def _take_delta(self, header: bool = False) -> bytes | None:
+            """Return new PCM bytes since last call, or None if empty.
+
+            Args:
+                header: If True, prepend a streaming WAV header to the
+                    first returned chunk.
+            """
+            new_data = self._pcm_bytes[self._consumed :]
+            if not new_data:
+                return None
+            self._consumed = len(self._pcm_bytes)
+            if header:
+                return _build_streaming_wav_header(
+                    sample_rate=_SAMPLE_RATE,
+                    channels=_CHANNELS,
+                    bits_per_sample=_BITS_PER_SAMPLE,
+                ) + bytes(new_data)
+            return bytes(new_data)
+
+        def get_audio_response(self, block: bool) -> TTSResponse:
+            """Return incremental audio delta (non-blocking or blocking)."""
+            if block:
+                self.finish_event.wait()
+            delta = self._take_delta(header=self._consumed == 0)
+            if delta:
+                return TTSResponse(
+                    content=DataBlock(
+                        source=Base64Source(
+                            data=base64.b64encode(delta).decode("ascii"),
+                            media_type=_MEDIA_TYPE,
+                        ),
+                    ),
+                )
+            return TTSResponse(content=None)
+
+        async def get_audio_chunks(self) -> AsyncGenerator[TTSResponse, None]:
+            """Yield incremental WAV audio chunks as they arrive."""
+            header_sent = self._consumed > 0
+            while True:
+                if self.finish_event.is_set():
+                    delta = self._take_delta(header=not header_sent)
+                    if delta:
+                        yield TTSResponse(
+                            content=DataBlock(
+                                source=Base64Source(
+                                    data=base64.b64encode(delta).decode(
+                                        "ascii",
+                                    ),
+                                    media_type=_MEDIA_TYPE,
+                                ),
+                            ),
+                            is_last=True,
+                        )
+                    else:
+                        yield TTSResponse(content=None, is_last=True)
+                    self.reset()
+                    break
+
+                if self.chunk_event.is_set():
+                    self.chunk_event.clear()
+                else:
+                    await asyncio.to_thread(self.chunk_event.wait)
+
+                if self.finish_event.is_set():
+                    continue
+
+                delta = self._take_delta(header=not header_sent)
+                if delta:
+                    header_sent = True
+                    yield TTSResponse(
+                        content=DataBlock(
+                            source=Base64Source(
+                                data=base64.b64encode(delta).decode("ascii"),
+                                media_type=_MEDIA_TYPE,
+                            ),
+                        ),
+                        is_last=False,
+                    )
+
+        def reset(self) -> None:
+            """Reset internal state for the next utterance."""
+            self.finish_event.clear()
+            self.chunk_event.clear()
+            self._pcm_bytes = bytearray()
+            self._consumed = 0
+
+        def has_audio_data(self) -> bool:
+            """Return whether any audio data has been received."""
+            return bool(self._pcm_bytes)
+
+    return _Callback
+
+
+class DashScopeRealtimeTTSModel(TTSModelBase):
+    """DashScope Realtime TTS model using the QwenTtsRealtime WebSocket API.
+
+    This model supports streaming input: text can be pushed incrementally
+    via :meth:`push`, and :meth:`synthesize` finalizes the current utterance.
+
+    For more details see the `official document
+    <https://bailian.console.aliyun.com/?tab=doc#/doc/?type=model&url=2938790>`_.
+
+    .. note:: Only one streaming input request can be active at a time.
+    """
+
+    class Parameters(BaseModel):
+        """Frontend-exposed parameters for DashScope Realtime TTS models."""
+
+        voice: str = Field(
+            default="Cherry",
+            title="Voice",
+            description="The voice to use for synthesis.",
+        )
+
+    type: Literal["dashscope_realtime_tts"] = "dashscope_realtime_tts"
+
+    realtime: bool = True
+
+    def __init__(
+        self,
+        credential: DashScopeCredential,
+        model: str = "qwen3-tts-flash-realtime",
+        parameters: "DashScopeRealtimeTTSModel.Parameters | None" = None,
+        stream: bool = True,
+        cold_start_length: int | None = None,
+        cold_start_words: int | None = None,
+        max_retries: int = 3,
+        retry_delay: float = 5.0,
+    ) -> None:
+        """Initialize the DashScope Realtime TTS model.
+
+        Args:
+            credential (`DashScopeCredential`):
+                The DashScope credential.
+            model (`str`, defaults to ``"qwen3-tts-flash-realtime"``):
+                The realtime TTS model name.
+            parameters (`Parameters | None`, defaults to `None`):
+                The TTS parameters (voice, etc.).
+            stream (`bool`, defaults to `True`):
+                Whether :meth:`synthesize` returns a streaming async generator.
+            cold_start_length (`int | None`, defaults to `None`):
+                Minimum character count before the first text chunk is sent.
+            cold_start_words (`int | None`, defaults to `None`):
+                Minimum word count before the first text chunk is sent.
+            max_retries (`int`, defaults to `3`):
+                Max retry attempts on WebSocket failure.
+            retry_delay (`float`, defaults to `5.0`):
+                Initial retry delay in seconds (exponential backoff).
+        """
+        super().__init__(
+            credential=credential,
+            model=model,
+            parameters=parameters,
+            stream=stream,
+        )
+        self.cold_start_length = cold_start_length
+        self.cold_start_words = cold_start_words
+        self.max_retries = max_retries
+        self.retry_delay = retry_delay
+
+        self._tts_client: QwenTtsRealtime | None = None
+        self._callback: Any = None
+        self._connected = False
+        self._cold_start_buffer: str = ""
+        self._cold_start_done: bool = False
+        self._accumulated_text: str = ""
+
+    def _create_client(self) -> None:
+        """Create a fresh TTS client and callback."""
+        import dashscope
+        from dashscope.audio.qwen_tts_realtime import QwenTtsRealtime
+
+        dashscope.api_key = self.credential.api_key.get_secret_value()
+
+        callback_cls = _make_callback_class()
+        self._callback = callback_cls()
+        self._tts_client = QwenTtsRealtime(
+            model=self.model,
+            callback=self._callback,
+        )
+
+    async def connect(self) -> None:
+        """Establish the WebSocket connection."""
+        if self._connected:
+            return
+
+        self._create_client()
+        self._tts_client.connect()
+        self._tts_client.update_session(
+            voice=self.parameters.voice,
+            mode="server_commit",
+        )
+        self._connected = True
+
+    async def close(self) -> None:
+        """Close the WebSocket connection."""
+        if not self._connected:
+            return
+        self._connected = False
+        try:
+            self._tts_client.close()
+        except Exception:
+            pass
+
+    async def _reconnect(self) -> None:
+        """Reconnect by recreating the client."""
+        try:
+            self._tts_client.close()
+        except Exception:
+            pass
+        self._connected = False
+        self._cold_start_buffer = ""
+        self._cold_start_done = False
+        await self.connect()
+
+    async def push(
+        self,
+        text: str,
+        **kwargs: Any,
+    ) -> TTSResponse:
+        """Push an incremental text delta for realtime synthesis.
+
+        Args:
+            text (`str`):
+                An incremental text chunk (delta) to append.
+            **kwargs (`Any`):
+                Additional keyword arguments (unused).
+
+        Returns:
+            `TTSResponse`:
+                Audio accumulated so far, or empty if not yet available.
+        """
+        from websocket import WebSocketConnectionClosedException
+
+        if not self._connected:
+            raise RuntimeError(
+                "TTS model is not connected. Call `connect()` first.",
+            )
+
+        if not text:
+            return TTSResponse(content=None)
+
+        self._accumulated_text += text
+
+        if not self._cold_start_done:
+            self._cold_start_buffer += text
+            ready = True
+            if (
+                self.cold_start_length
+                and len(self._cold_start_buffer) < self.cold_start_length
+            ):
+                ready = False
+            if (
+                ready
+                and self.cold_start_words
+                and len(self._cold_start_buffer.split())
+                < self.cold_start_words
+            ):
+                ready = False
+            if ready:
+                try:
+                    self._tts_client.append_text(self._cold_start_buffer)
+                except WebSocketConnectionClosedException:
+                    return TTSResponse(content=None)
+                self._cold_start_buffer = ""
+                self._cold_start_done = True
+        else:
+            try:
+                self._tts_client.append_text(text)
+            except WebSocketConnectionClosedException:
+                return TTSResponse(content=None)
+
+        return self._callback.get_audio_response(block=False)
+
+    async def synthesize(
+        self,
+        text: str | None = None,
+        **kwargs: Any,
+    ) -> TTSResponse | AsyncGenerator[TTSResponse, None]:
+        """Finalize synthesis for the current utterance.
+
+        If text was previously pushed via :meth:`push`, this flushes any
+        remaining buffered text, commits, and waits for audio. If ``text``
+        is provided, it is appended before committing.
+
+        Args:
+            text (`str | None`, defaults to `None`):
+                Optional additional text to append before finalizing.
+                If ``None``, finalizes previously pushed text.
+            **kwargs (`Any`):
+                Additional keyword arguments (unused).
+
+        Returns:
+            `TTSResponse | AsyncGenerator[TTSResponse, None]`:
+                A single response when ``stream=False``, or an async generator
+                of incremental chunks when ``stream=True``.
+        """
+        from websocket import WebSocketConnectionClosedException
+
+        if not self._connected:
+            raise RuntimeError(
+                "TTS model is not connected. Call `connect()` first.",
+            )
+
+        if text is not None:
+            self._accumulated_text += text
+
+        unsent = self._cold_start_buffer
+        if text is not None:
+            unsent += text
+        self._cold_start_buffer = ""
+
+        full_text = self._accumulated_text
+        delay = self.retry_delay
+
+        for attempt in range(self.max_retries):
+            try:
+                if unsent:
+                    self._tts_client.append_text(unsent)
+
+                self._tts_client.commit()
+                self._tts_client.finish()
+
+                await asyncio.to_thread(
+                    self._callback.finish_event.wait,
+                )
+
+                if full_text and not self._callback.has_audio_data():
+                    if attempt < self.max_retries - 1:
+                        logger.warning(
+                            "TTS: no audio received, retrying (%d/%d) in "
+                            "%.1fs...",
+                            attempt + 1,
+                            self.max_retries,
+                            delay,
+                        )
+                        await asyncio.sleep(delay)
+                        await self._reconnect()
+                        unsent = full_text
+                        delay *= 2
+                        continue
+                    self._reset_state()
+                    raise RuntimeError(
+                        f"TTS synthesis failed: no audio after "
+                        f"{self.max_retries} attempts",
+                    )
+                break
+
+            except WebSocketConnectionClosedException:
+                if attempt < self.max_retries - 1:
+                    logger.warning(
+                        "TTS WebSocket closed, retrying (%d/%d) in %.1fs...",
+                        attempt + 1,
+                        self.max_retries,
+                        delay,
+                    )
+                    await asyncio.sleep(delay)
+                    await self._reconnect()
+                    unsent = full_text
+                    delay *= 2
+                else:
+                    self._reset_state()
+                    raise
+
+        self._reset_state()
+
+        if self.stream:
+            return self._callback.get_audio_chunks()
+
+        response = self._callback.get_audio_response(block=True)
+        self._callback.reset()
+        return response
+
+    def _reset_state(self) -> None:
+        """Reset per-utterance tracking state."""
+        self._cold_start_buffer = ""
+        self._cold_start_done = False
+        self._accumulated_text = ""
diff --git a/src/agentscope/tts/_openai/__init__.py b/src/agentscope/tts/_openai/__init__.py
new file mode 100644
index 0000000..153f721
--- /dev/null
+++ b/src/agentscope/tts/_openai/__init__.py
@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+"""The OpenAI TTS module."""
+
+from ._model import OpenAITTSModel
+
+__all__ = [
+    "OpenAITTSModel",
+]
diff --git a/src/agentscope/tts/_openai/_model.py b/src/agentscope/tts/_openai/_model.py
new file mode 100644
index 0000000..125333a
--- /dev/null
+++ b/src/agentscope/tts/_openai/_model.py
@@ -0,0 +1,252 @@
+# -*- coding: utf-8 -*-
+"""OpenAI TTS model implementation using the Audio Speech API."""
+import base64
+from datetime import datetime
+from typing import (
+    Any,
+    AsyncGenerator,
+    Literal,
+    TYPE_CHECKING,
+)
+
+from pydantic import BaseModel, Field
+
+from .._tts_base import TTSModelBase
+from .._tts_response import TTSResponse, TTSUsage
+from ...credential import OpenAICredential
+from ...message import DataBlock, Base64Source
+
+if TYPE_CHECKING:
+    from openai import AsyncOpenAI
+
+
+# Map the OpenAI ``response_format`` values to their MIME media types.
+_MEDIA_TYPES = {
+    "mp3": "audio/mpeg",
+    "opus": "audio/opus",
+    "aac": "audio/aac",
+    "flac": "audio/flac",
+    "wav": "audio/wav",
+    "pcm": "audio/pcm",
+}
+_DEFAULT_RESPONSE_FORMAT = "mp3"
+
+
+def _parse_usage(usage: Any, elapsed: float) -> TTSUsage | None:
+    """Extract a TTSUsage from the OpenAI usage object, or None."""
+    if usage is None:
+        return None
+    return TTSUsage(
+        input_tokens=getattr(usage, "input_tokens", 0) or 0,
+        output_tokens=getattr(usage, "output_tokens", 0) or 0,
+        time=elapsed,
+    )
+
+
+class OpenAITTSModel(TTSModelBase):
+    """OpenAI TTS model implementation using the Audio Speech API. For more
+    details please see the `official document
+    <https://platform.openai.com/docs/guides/text-to-speech>`_.
+    """
+
+    class Parameters(BaseModel):
+        """Frontend-exposed parameters for OpenAI TTS models."""
+
+        voice: str = Field(
+            default="alloy",
+            title="Voice",
+            description="The voice to use for synthesis.",
+        )
+
+        response_format: Literal[
+            "mp3",
+            "opus",
+            "aac",
+            "flac",
+            "wav",
+            "pcm",
+        ] = Field(
+            default=_DEFAULT_RESPONSE_FORMAT,
+            title="Response Format",
+            description="The audio format of the synthesized speech.",
+        )
+
+        instructions: str | None = Field(
+            default=None,
+            title="Instructions",
+            description=(
+                "Additional instructions for controlling the voice "
+                "(only supported by some models, e.g. gpt-4o-mini-tts)."
+            ),
+        )
+
+    type: Literal["openai_tts"] = "openai_tts"
+    """The type of the TTS model."""
+
+    realtime: bool = False
+
+    def __init__(
+        self,
+        credential: OpenAICredential,
+        model: str = "tts-1",
+        parameters: "OpenAITTSModel.Parameters | None" = None,
+        stream: bool = True,
+    ) -> None:
+        """Initialize the OpenAI TTS model.
+
+        .. note:: More details about the parameters, such as ``model``
+         and ``voice``, can be found in the `official document
+         <https://platform.openai.com/docs/guides/text-to-speech>`_.
+
+        Args:
+            credential (`OpenAICredential`):
+                The OpenAI credential used to authenticate the API call.
+            model (`str`, defaults to ``"tts-1"``):
+                The TTS model name. Supported models include ``tts-1``,
+                ``tts-1-hd`` and ``gpt-4o-mini-tts``.
+            parameters (`OpenAITTSModel.Parameters | None`, defaults to \
+            `None`):
+                The TTS parameters (voice, response format, etc.). When
+                ``None``, the default parameters will be used.
+            stream (`bool`, defaults to `True`):
+                Whether to use streaming output. When `True`,
+                :meth:`synthesize` returns an async generator yielding
+                ``TTSResponse`` chunks; when `False`, it returns a single
+                aggregated ``TTSResponse``.
+        """
+        super().__init__(
+            credential=credential,
+            model=model,
+            parameters=parameters,
+            stream=stream,
+        )
+
+    async def synthesize(
+        self,
+        text: str | None = None,
+        **kwargs: Any,
+    ) -> TTSResponse | AsyncGenerator[TTSResponse, None]:
+        """Call the OpenAI Audio Speech API to synthesize speech from text.
+
+        Args:
+            text (`str | None`, optional):
+                The text to be synthesized.
+            **kwargs (`Any`):
+                Additional keyword arguments to pass to the TTS API call.
+
+        Returns:
+            `TTSResponse | AsyncGenerator[TTSResponse, None]`:
+                A single ``TTSResponse`` when ``stream=False``, or an async
+                generator yielding ``TTSResponse`` chunks when ``stream=True``.
+        """
+        if not text:
+            return TTSResponse(content=None)
+
+        import openai
+
+        client = openai.AsyncClient(
+            api_key=self.credential.api_key.get_secret_value(),
+            organization=self.credential.organization,
+            base_url=self.credential.base_url,
+        )
+
+        media_type = _MEDIA_TYPES.get(
+            self.parameters.response_format,
+            _MEDIA_TYPES[_DEFAULT_RESPONSE_FORMAT],
+        )
+
+        request_kwargs: dict[str, Any] = {
+            "model": self.model,
+            "voice": self.parameters.voice,
+            "input": text,
+            "response_format": self.parameters.response_format,
+            **kwargs,
+        }
+        if self.parameters.instructions:
+            request_kwargs["instructions"] = self.parameters.instructions
+
+        if self.stream:
+            return self._stream(client, media_type, **request_kwargs)
+
+        return await self._aggregate(client, media_type, **request_kwargs)
+
+    @staticmethod
+    async def _aggregate(
+        client: "AsyncOpenAI",
+        media_type: str,
+        **request_kwargs: Any,
+    ) -> TTSResponse:
+        """Call the API and aggregate the full audio into a single
+        ``TTSResponse``."""
+        start_datetime = datetime.now()
+        response = await client.audio.speech.create(**request_kwargs)
+        audio_bytes = response.content
+        elapsed = (datetime.now() - start_datetime).total_seconds()
+
+        return TTSResponse(
+            content=DataBlock(
+                source=Base64Source(
+                    data=base64.b64encode(audio_bytes).decode("ascii"),
+                    media_type=media_type,
+                ),
+            ),
+            usage=_parse_usage(None, elapsed),
+        )
+
+    @staticmethod
+    async def _stream(
+        client: "AsyncOpenAI",
+        media_type: str,
+        **request_kwargs: Any,
+    ) -> AsyncGenerator[TTSResponse, None]:
+        """Call the API and yield incremental audio chunks as
+        ``TTSResponse`` objects.
+
+        Args:
+            client (`AsyncOpenAI`):
+                The async OpenAI client.
+            media_type (`str`):
+                The media type of the synthesized audio.
+            **request_kwargs (`Any`):
+                Keyword arguments forwarded to the Audio Speech API.
+
+        Yields:
+            `TTSResponse`:
+                A ``TTSResponse`` for each incremental audio chunk; the
+                final response has ``is_last=True``.
+        """
+        start_datetime = datetime.now()
+        pending: TTSResponse | None = None
+
+        async with client.audio.speech.with_streaming_response.create(
+            **request_kwargs,
+        ) as response:
+            async for delta_bytes in response.iter_bytes():
+                if not delta_bytes:
+                    continue
+                if pending is not None:
+                    yield pending
+                pending = TTSResponse(
+                    content=DataBlock(
+                        source=Base64Source(
+                            data=base64.b64encode(delta_bytes).decode(
+                                "ascii",
+                            ),
+                            media_type=media_type,
+                        ),
+                    ),
+                    is_last=False,
+                )
+
+        elapsed = (datetime.now() - start_datetime).total_seconds()
+
+        if pending is not None:
+            pending.is_last = True
+            pending.usage = _parse_usage(None, elapsed)
+            yield pending
+        else:
+            yield TTSResponse(
+                content=None,
+                is_last=True,
+                usage=_parse_usage(None, elapsed),
+            )
diff --git a/src/agentscope/tts/_openai/_models/gpt-4o-mini-tts.yaml b/src/agentscope/tts/_openai/_models/gpt-4o-mini-tts.yaml
new file mode 100644
index 0000000..4917171
--- /dev/null
+++ b/src/agentscope/tts/_openai/_models/gpt-4o-mini-tts.yaml
@@ -0,0 +1,30 @@
+name: gpt-4o-mini-tts
+label: GPT-4o Mini TTS
+status: active
+
+input_types:
+  - text/plain
+
+output_types:
+  - audio/mpeg
+  - audio/opus
+  - audio/aac
+  - audio/flac
+  - audio/wav
+  - audio/pcm
+
+voices:
+  # Source: https://platform.openai.com/docs/guides/text-to-speech
+  - alloy
+  - ash
+  - ballad
+  - coral
+  - echo
+  - fable
+  - onyx
+  - nova
+  - sage
+  - shimmer
+  - verse
+
+parameter_overrides: {}
diff --git a/src/agentscope/tts/_openai/_models/tts-1-hd.yaml b/src/agentscope/tts/_openai/_models/tts-1-hd.yaml
new file mode 100644
index 0000000..744cbba
--- /dev/null
+++ b/src/agentscope/tts/_openai/_models/tts-1-hd.yaml
@@ -0,0 +1,34 @@
+name: tts-1-hd
+label: TTS-1 HD
+status: active
+
+input_types:
+  - text/plain
+
+output_types:
+  - audio/mpeg
+  - audio/opus
+  - audio/aac
+  - audio/flac
+  - audio/wav
+  - audio/pcm
+
+voices:
+  # Source: https://platform.openai.com/docs/guides/text-to-speech
+  - alloy
+  - ash
+  - ballad
+  - coral
+  - echo
+  - fable
+  - onyx
+  - nova
+  - sage
+  - shimmer
+  - verse
+
+parameter_overrides:
+  # The instructions parameter is not supported by tts-1-hd, hide it from
+  # the frontend to avoid confusing users.
+  instructions:
+    hidden: true
diff --git a/src/agentscope/tts/_openai/_models/tts-1.yaml b/src/agentscope/tts/_openai/_models/tts-1.yaml
new file mode 100644
index 0000000..755d212
--- /dev/null
+++ b/src/agentscope/tts/_openai/_models/tts-1.yaml
@@ -0,0 +1,34 @@
+name: tts-1
+label: TTS-1
+status: active
+
+input_types:
+  - text/plain
+
+output_types:
+  - audio/mpeg
+  - audio/opus
+  - audio/aac
+  - audio/flac
+  - audio/wav
+  - audio/pcm
+
+voices:
+  # Source: https://platform.openai.com/docs/guides/text-to-speech
+  - alloy
+  - ash
+  - ballad
+  - coral
+  - echo
+  - fable
+  - onyx
+  - nova
+  - sage
+  - shimmer
+  - verse
+
+parameter_overrides:
+  # The instructions parameter is not supported by tts-1, hide it from
+  # the frontend to avoid confusing users.
+  instructions:
+    hidden: true
diff --git a/src/agentscope/tts/_tts_base.py b/src/agentscope/tts/_tts_base.py
new file mode 100644
index 0000000..14401b9
--- /dev/null
+++ b/src/agentscope/tts/_tts_base.py
@@ -0,0 +1,212 @@
+# -*- coding: utf-8 -*-
+"""The TTS model base class."""
+import inspect
+from abc import abstractmethod
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, AsyncGenerator
+
+from pydantic import BaseModel
+
+from ._tts_response import TTSResponse
+from .._logging import logger
+from ..credential import CredentialBase
+
+if TYPE_CHECKING:
+    from ._tts_model_card import TTSModelCard
+
+
+class TTSModelBase:
+    """Base class for TTS models in AgentScope.
+
+    This base class provides a unified abstraction for both non-realtime and
+    realtime (streaming-input) TTS models, governed by the
+    ``realtime`` flag.
+
+    For non-realtime TTS models, only :meth:`synthesize` needs to be
+    implemented. For realtime TTS models, the lifecycle is managed via the
+    async context manager (``async with model: ...``) or by calling
+    :meth:`connect` / :meth:`close` manually; :meth:`push` appends text
+    chunks and returns whatever audio is currently available, while
+    :meth:`synthesize` blocks until the full speech has been synthesized.
+    """
+
+    class Parameters(BaseModel):
+        """Base parameter schema for TTS models. Subclasses should override
+        this with provider-specific parameters."""
+
+    credential: CredentialBase
+    """The credential used to authenticate against the TTS provider."""
+
+    model: str
+    """The name of the TTS model."""
+
+    parameters: BaseModel
+    """The TTS model parameters."""
+
+    stream: bool
+    """Whether to use streaming output if supported by the model."""
+
+    realtime: bool = False
+    """Whether the TTS model supports realtime (streaming-input) mode."""
+
+    def __init__(
+        self,
+        credential: CredentialBase,
+        model: str,
+        parameters: BaseModel | None = None,
+        stream: bool = True,
+    ) -> None:
+        """Initialize the TTS model base class.
+
+        Args:
+            credential (`CredentialBase`):
+                The credential used to authenticate against the TTS provider.
+            model (`str`):
+                The name of the TTS model.
+            parameters (`BaseModel | None`, defaults to `None`):
+                The TTS model parameters.
+            stream (`bool`, defaults to `True`):
+                Whether to use streaming output if supported by the model.
+        """
+        self.credential = credential
+        self.model = model
+        self.parameters = parameters or self.Parameters()
+        self.stream = stream
+
+    async def __aenter__(self) -> "TTSModelBase":
+        """Enter the async context manager and initialize resources if
+        needed."""
+        if self.realtime:
+            await self.connect()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: Any,
+        exc_value: Any,
+        traceback: Any,
+    ) -> None:
+        """Exit the async context manager and clean up resources if needed."""
+        if self.realtime:
+            await self.close()
+
+    async def connect(self) -> None:
+        """Connect to the TTS model and initialize resources.
+
+        .. note:: Only relevant for realtime TTS models — realtime subclasses
+              must override this. The default is a no-op so that non-realtime
+              models can ignore the lifecycle hooks; :meth:`__aenter__` only
+              calls it when ``realtime`` is True.
+        """
+        return
+
+    async def close(self) -> None:
+        """Close the connection to the TTS model and clean up resources.
+
+        .. note:: Only relevant for realtime TTS models — realtime subclasses
+              must override this. See :meth:`connect` for the rationale behind
+              the no-op default.
+        """
+        return
+
+    async def push(  # pylint: disable=unused-argument
+        self,
+        text: str,
+        **kwargs: Any,
+    ) -> TTSResponse:
+        """Append text to be synthesized and return the received TTS response.
+        This method is non-blocking and may return an empty response if no
+        audio is available yet.
+
+        To receive all the synthesized speech, call :meth:`synthesize` after
+        pushing all the text chunks.
+
+        .. note:: Only relevant for realtime TTS models — realtime subclasses
+              must override this. Non-realtime models should call
+              :meth:`synthesize` directly and never reach this method.
+
+        Args:
+            text (`str`):
+                The text chunk to be synthesized.
+            **kwargs (`Any`):
+                Additional keyword arguments to pass to the TTS API call.
+
+        Returns:
+            `TTSResponse`:
+                The TTSResponse containing the audio block.
+        """
+        return TTSResponse(content=None)
+
+    @classmethod
+    def list_models(
+        cls,
+        custom_yaml_dir: str | None = None,
+    ) -> list["TTSModelCard"]:
+        """List candidate TTS models by scanning YAML model cards.
+
+        Args:
+            custom_yaml_dir (`str | None`):
+                The custom YAML directory. If ``None``, uses the ``_models``
+                directory next to the concrete subclass's source file.
+
+        Returns:
+            `list[TTSModelCard]`:
+                A list of TTS model cards.
+        """
+        from ._tts_model_card import TTSModelCard
+
+        if custom_yaml_dir is None:
+            subclass_file = Path(inspect.getfile(cls))
+            yaml_dir = subclass_file.parent / "_models"
+        else:
+            yaml_dir = Path(custom_yaml_dir)
+
+        yaml_files = list(yaml_dir.glob("*.yaml"))
+
+        model_cards = []
+        for yaml_file in yaml_files:
+            try:
+                card = TTSModelCard.from_yaml(
+                    yaml_path=str(yaml_file),
+                    parameter_class=cls.Parameters,
+                )
+                if card.realtime != cls.realtime:
+                    continue
+                model_cards.append(card)
+            except Exception as e:
+                logger.warning(
+                    "Warning: Failed to load %s: %s",
+                    yaml_file,
+                    str(e),
+                )
+                continue
+
+        return model_cards
+
+    @abstractmethod
+    async def synthesize(
+        self,
+        text: str | None = None,
+        **kwargs: Any,
+    ) -> TTSResponse | AsyncGenerator[TTSResponse, None]:
+        """Synthesize speech from the appended text. Different from
+        :meth:`push`, this method blocks until the full speech has been
+        synthesized.
+
+        Args:
+            text (`str | None`, defaults to `None`):
+                The text to be synthesized. If `None`, this method will
+                wait for all previously pushed text to be synthesized and
+                return the last synthesized TTSResponse.
+            **kwargs (`Any`):
+                Additional keyword arguments to pass to the TTS API call.
+
+        Returns:
+            `TTSResponse | AsyncGenerator[TTSResponse, None]`:
+                A single TTSResponse containing the full audio when
+                ``stream=False``. When ``stream=True``, an async generator
+                yielding TTSResponse chunks where each chunk carries an
+                **incremental** audio delta (not a cumulative buffer); the
+                full audio is the concatenation of every chunk's decoded
+                bytes. The final yielded chunk has ``is_last=True``.
+        """
diff --git a/src/agentscope/tts/_tts_model_card.py b/src/agentscope/tts/_tts_model_card.py
new file mode 100644
index 0000000..55ad4f2
--- /dev/null
+++ b/src/agentscope/tts/_tts_model_card.py
@@ -0,0 +1,134 @@
+# -*- coding: utf-8 -*-
+"""The TTS model card class."""
+import copy
+from datetime import datetime
+from typing import Literal, Self, Type
+
+import yaml
+from pydantic import BaseModel, Field
+
+
+class TTSModelCard(BaseModel):
+    """The model card class for TTS models."""
+
+    type: Literal["tts_model"] = "tts_model"
+    """The model card type discriminator."""
+
+    name: str = Field(description="The name of the TTS model")
+    """The model name."""
+
+    label: str = Field(description="The model label.")
+    """The model label used for frontend rendering."""
+
+    status: Literal["active", "deprecated", "sunset"] = Field(
+        default="active",
+        title="Status",
+        description="The model status",
+    )
+    """The model status."""
+
+    deprecated_at: datetime | None = Field(
+        default=None,
+        description="The model deprecation date and time.",
+        title="Deprecation date",
+    )
+    """The model deprecated at."""
+
+    input_types: list[str] = Field(
+        description="The supported model input types.",
+        title="Input types",
+        default=["text/plain"],
+    )
+    """The model supported input types."""
+
+    output_types: list[str] = Field(
+        description="The supported model output types.",
+        title="Output types",
+        default=["audio/wav"],
+    )
+    """The model supported output types."""
+
+    realtime: bool = Field(
+        default=False,
+        description="Whether the model supports streaming input (realtime).",
+        title="Realtime",
+    )
+    """Whether the model supports streaming input."""
+
+    parameter_schema: dict
+    """The parameters schema."""
+
+    parameters_overrides: dict[str, dict]
+    """The parameter overrides."""
+
+    @classmethod
+    def from_yaml(
+        cls,
+        yaml_path: str,
+        parameter_class: Type[BaseModel],
+    ) -> Self:
+        """Read a TTS model card from a YAML file.
+
+        Args:
+            yaml_path (`str`):
+                Path to the YAML file
+            parameter_class (`Type[BaseModel]`):
+                The parameter class (e.g., DashScopeTTSModel.Parameters)
+
+        Returns:
+            `TTSModelCard`:
+                TTSModelCard instance with merged parameter schema
+        """
+        with open(yaml_path, "r", encoding="utf-8") as file:
+            config = yaml.safe_load(file)
+
+        base_schema = parameter_class.model_json_schema()
+        properties = copy.deepcopy(base_schema.get("properties", {}))
+
+        # Auto-inject: populate voice enum from YAML voices list
+        voices = config.get("voices", [])
+        if voices and "voice" in properties:
+            properties["voice"] = {
+                **properties["voice"],
+                "default": voices[0],
+                "enum": voices,
+            }
+
+        # Apply parameter_overrides
+        overrides = config.get("parameter_overrides", {})
+        for param_name, override in overrides.items():
+            if override is None:
+                properties.pop(param_name, None)
+                continue
+
+            if isinstance(override, dict):
+                if override.get("hidden"):
+                    properties.pop(param_name, None)
+                    continue
+
+                if param_name in properties:
+                    properties[param_name] = {
+                        **properties[param_name],
+                        **override,
+                    }
+
+        required = [
+            r for r in base_schema.get("required", []) if r in properties
+        ]
+        final_schema = {
+            "type": "object",
+            "properties": properties,
+            "required": required,
+        }
+
+        return cls(
+            name=config["name"],
+            label=config["label"],
+            status=config.get("status", "active"),
+            deprecated_at=config.get("deprecated_at"),
+            input_types=config.get("input_types", ["text/plain"]),
+            output_types=config.get("output_types", ["audio/wav"]),
+            realtime=config.get("realtime", False),
+            parameter_schema=final_schema,
+            parameters_overrides=config.get("parameter_overrides", {}),
+        )
diff --git a/src/agentscope/tts/_tts_response.py b/src/agentscope/tts/_tts_response.py
new file mode 100644
index 0000000..0fe6605
--- /dev/null
+++ b/src/agentscope/tts/_tts_response.py
@@ -0,0 +1,56 @@
+# -*- coding: utf-8 -*-
+"""The TTS response module."""
+from dataclasses import dataclass, field
+from typing import Literal
+
+from .._utils._common import _get_timestamp
+from .._utils._mixin import DictMixin
+from ..message import DataBlock
+from ..types import JSONSerializableObject
+
+
+@dataclass
+class TTSUsage(DictMixin):
+    """The usage of a TTS model API invocation."""
+
+    input_tokens: int
+    """The number of input tokens."""
+
+    output_tokens: int
+    """The number of output tokens."""
+
+    time: float
+    """The time used in seconds."""
+
+    type: Literal["tts"] = field(default_factory=lambda: "tts")
+    """The type of the usage, must be `tts`."""
+
+
+@dataclass
+class TTSResponse(DictMixin):
+    """The response of TTS models."""
+
+    content: DataBlock | None
+    """The audio chunk produced by the TTS model. The audio format is
+    indicated by ``content.source.media_type`` (e.g.
+    ``"audio/pcm;rate=24000"``, ``"audio/mpeg"``)."""
+
+    id: str = field(default_factory=lambda: _get_timestamp(True))
+    """The unique identifier of the response."""
+
+    created_at: str = field(default_factory=_get_timestamp)
+    """When the response was created."""
+
+    type: Literal["tts"] = field(default_factory=lambda: "tts")
+    """The type of the response, which is always 'tts'."""
+
+    usage: TTSUsage | None = field(default_factory=lambda: None)
+    """The usage information of the TTS response, if available."""
+
+    metadata: dict[str, JSONSerializableObject] | None = field(
+        default_factory=lambda: None,
+    )
+    """The metadata of the TTS response."""
+
+    is_last: bool = field(default_factory=lambda: True)
+    """Whether this is the last response in a stream of TTS responses."""
diff --git a/src/agentscope/types/__init__.py b/src/agentscope/types/__init__.py
new file mode 100644
index 0000000..03ff21f
--- /dev/null
+++ b/src/agentscope/types/__init__.py
@@ -0,0 +1,20 @@
+# -*- coding: utf-8 -*-
+"""The types in agentscope"""
+
+from ._hook import (
+    AgentHookTypes,
+    ReActAgentHookTypes,
+)
+from ._object import Embedding
+from ._json import (
+    JSONPrimitive,
+    JSONSerializableObject,
+)
+
+__all__ = [
+    "AgentHookTypes",
+    "ReActAgentHookTypes",
+    "Embedding",
+    "JSONPrimitive",
+    "JSONSerializableObject",
+]
diff --git a/src/agentscope/types/_hook.py b/src/agentscope/types/_hook.py
new file mode 100644
index 0000000..638dcb6
--- /dev/null
+++ b/src/agentscope/types/_hook.py
@@ -0,0 +1,25 @@
+# -*- coding: utf-8 -*-
+"""The agent hooks types."""
+from typing import Literal
+
+AgentHookTypes = (
+    str
+    | Literal[
+        "pre_reply",
+        "post_reply",
+        "pre_print",
+        "post_print",
+        "pre_observe",
+        "post_observe",
+    ]
+)
+
+ReActAgentHookTypes = (
+    AgentHookTypes
+    | Literal[
+        "pre_reasoning",
+        "post_reasoning",
+        "pre_acting",
+        "post_acting",
+    ]
+)
diff --git a/src/agentscope/types/_json.py b/src/agentscope/types/_json.py
new file mode 100644
index 0000000..3a506a0
--- /dev/null
+++ b/src/agentscope/types/_json.py
@@ -0,0 +1,14 @@
+# -*- coding: utf-8 -*-
+"""The JSON related types"""
+from typing import TypeAlias
+
+JSONPrimitive: TypeAlias = str | int | float | bool | None
+
+JSONSerializableObject: TypeAlias = (
+    JSONPrimitive
+    | list["JSONSerializableObject"]
+    | dict[
+        str,
+        "JSONSerializableObject",
+    ]
+)
diff --git a/src/agentscope/types/_object.py b/src/agentscope/types/_object.py
new file mode 100644
index 0000000..58041c7
--- /dev/null
+++ b/src/agentscope/types/_object.py
@@ -0,0 +1,5 @@
+# -*- coding: utf-8 -*-
+"""The object types in agentscope."""
+from typing import List
+
+Embedding = List[float]
diff --git a/src/agentscope/workspace/__init__.py b/src/agentscope/workspace/__init__.py
new file mode 100644
index 0000000..2aa043c
--- /dev/null
+++ b/src/agentscope/workspace/__init__.py
@@ -0,0 +1,26 @@
+# -*- coding: utf-8 -*-
+"""The workspace module in agentscope."""
+
+
+from ._base import WorkspaceBase
+from ._local_workspace import LocalWorkspace
+from ._offload_protocol import Offloader
+from ._docker import DockerBackend, DockerWorkspace
+from ._e2b import E2BWorkspace, E2BBackend
+from ._k8s import K8sBackend, K8sWorkspace
+from ._opensandbox import OpenSandboxBackend, OpenSandboxWorkspace
+
+
+__all__ = [
+    "WorkspaceBase",
+    "LocalWorkspace",
+    "DockerBackend",
+    "DockerWorkspace",
+    "E2BBackend",
+    "E2BWorkspace",
+    "K8sBackend",
+    "K8sWorkspace",
+    "Offloader",
+    "OpenSandboxBackend",
+    "OpenSandboxWorkspace",
+]
diff --git a/src/agentscope/workspace/_base.py b/src/agentscope/workspace/_base.py
new file mode 100644
index 0000000..cb90f55
--- /dev/null
+++ b/src/agentscope/workspace/_base.py
@@ -0,0 +1,735 @@
+# -*- coding: utf-8 -*-
+"""WorkspaceBase — abstract interface and shared backend-driven impl.
+
+A workspace provides:
+
+- **Resources** — skills available to the agent.
+- **Tools** — MCPs and built-in tools for operating on resources.
+- **Offload** — persistence of compressed context and tool results
+  for agentic retrieval.
+
+Three concrete implementations:
+
+- :class:`agentscope.workspace.LocalWorkspace` — local filesystem.
+- :class:`agentscope.workspace.DockerWorkspace` — Docker container.
+- :class:`agentscope.workspace.E2BWorkspace` — E2B cloud sandbox.
+- :class:`agentscope.workspace.OpenSandboxWorkspace` — OpenSandbox
+  remote sandbox.
+
+Consumers:
+
+- **Agent** — calls ``list_mcps``, ``list_skills``, ``list_tools``,
+  ``offload_context``, ``offload_tool_result``.
+- **User** — dynamically adds/removes MCPs and skills via
+  ``add_mcp`` / ``remove_mcp`` / ``add_skill`` / ``remove_skill``.
+- **Developer** — manages lifecycle via ``initialize`` / ``close``.
+- **Backend consumers** access the active backend via :meth:`get_backend`.
+
+Shared implementation
+---------------------
+
+The base class implements every operation that can be expressed against
+the workspace's :class:`BackendBase` plus a fixed layout derived from
+``workdir``:
+
+.. code-block:: text
+
+    {workdir}/
+    ├── .mcp          # persisted MCP client configs (JSON array)
+    ├── data/         # offloaded multimodal payloads
+    ├── skills/       # skill subdirectories
+    └── sessions/     # per-session context and tool-result files
+
+Subclasses only set ``self.workdir`` (the agent-visible root); all
+other directory paths are derived via :meth:`BackendBase.join_path`,
+keeping path semantics consistent with whichever backend is bound.
+"""
+
+import asyncio
+import base64
+import hashlib
+import io
+import json
+import mimetypes
+import os
+import tarfile
+from abc import abstractmethod
+from copy import deepcopy
+from pathlib import Path
+from typing import Self
+
+from pydantic import AnyUrl
+
+from .._logging import logger
+from .._utils._common import _generate_id
+from ..mcp import MCPClient
+from ..message import (
+    Base64Source,
+    DataBlock,
+    Msg,
+    TextBlock,
+    ToolResultBlock,
+    URLSource,
+)
+from ..skill import Skill
+from ..tool import BackendBase, ToolBase
+from ._utils import (
+    DEFAULT_DATA_DIR,
+    DEFAULT_MCP_FILE,
+    DEFAULT_SESSIONS_DIR,
+    DEFAULT_SKILLS_DIR,
+)
+
+_EXTRACT_TAR_SHIM = (
+    "import tarfile, sys, os\n"
+    "src, dst = sys.argv[1], sys.argv[2]\n"
+    "os.makedirs(dst, exist_ok=True)\n"
+    "dst_real = os.path.realpath(dst)\n"
+    "tf = tarfile.open(src)\n"
+    "try:\n"
+    "    members = tf.getmembers()\n"
+    "    for m in members:\n"
+    "        target = os.path.realpath(os.path.join(dst, m.name))\n"
+    "        if not (target == dst_real"
+    " or target.startswith(dst_real + os.sep)):\n"
+    "            raise Exception('unsafe tar member: ' + m.name)\n"
+    "    tf.extractall(dst, members=members)\n"
+    "finally:\n"
+    "    tf.close()\n"
+    "os.unlink(src)\n"
+)
+
+
+class WorkspaceBase:
+    """Abstract base class for all workspace implementations.
+
+    Subclasses provide concrete behaviour for one execution backend
+    (local filesystem, Docker container, E2B sandbox). The base class
+    owns:
+
+    - lifecycle scaffolding (``async with`` protocol, ``is_alive``);
+    - the canonical workspace layout derived from ``workdir`` (data/,
+      skills/, sessions/, .mcp);
+    - shared backend-driven implementations of offload, MCP
+      persistence and a basic skill manager that subclasses can
+      override (LocalWorkspace does, with a hash-indexed variant).
+    """
+
+    workspace_id: str
+    """Unique identifier for this workspace instance."""
+
+    workdir: str
+    """Agent-visible root directory for workspace file operations."""
+
+    is_alive: bool
+    """If the workspace is still operational."""
+
+    _backend: BackendBase | None
+    """Current execution backend, available through :meth:`get_backend`."""
+
+    default_mcps: list[MCPClient]
+    """MCP clients to seed on first :meth:`initialize` when the
+    persisted ``.mcp`` file is absent."""
+
+    skill_paths: list[str]
+    """Local skill directories to seed on first :meth:`initialize`."""
+
+    _mcps: list[MCPClient]
+    """Currently registered MCP clients (in-memory authoritative copy).
+
+    :class:`LocalWorkspace` stores the local live handles directly;
+    :class:`SandboxedWorkspaceBase` stores gateway-side
+    :class:`GatewayMCPClient` wrappers (also ``MCPClient`` instances)
+    so ``list_mcps`` / persistence work uniformly across both.
+    """
+
+    _mcp_lock: asyncio.Lock
+    """Guards mutation of :attr:`_mcps` and the ``.mcp`` file."""
+
+    _skill_lock: asyncio.Lock
+    """Guards mutation of the ``skills/`` directory."""
+
+    def __init__(
+        self,
+        *,
+        workspace_id: str | None = None,
+        default_mcps: list[MCPClient] | None = None,
+        skill_paths: list[str] | None = None,
+    ) -> None:
+        """Initialise the shared workspace state.
+
+        Subclasses must call ``super().__init__`` and then set
+        :attr:`workdir` themselves before any base-class method is
+        invoked. Backend binding (``self._backend``) is left to the
+        subclass (Local sets it eagerly; Docker/E2B set it during
+        :meth:`initialize`).
+
+        Args:
+            workspace_id (`str | None`, optional):
+                Existing identifier to adopt; ``None`` mints a fresh
+                UUID.
+            default_mcps (`list[MCPClient] | None`, optional):
+                MCP clients to register when the workspace boots
+                without a persisted ``.mcp`` file.
+            skill_paths (`list[str] | None`, optional):
+                Local skill directories to copy into ``skills/`` on
+                first start.
+        """
+        self.workspace_id = workspace_id or _generate_id()
+        self.is_alive = False
+        self._backend = None
+
+        self.default_mcps = list(default_mcps or [])
+        self.skill_paths = list(skill_paths or [])
+
+        self._mcps = []
+        self._mcp_lock = asyncio.Lock()
+        self._skill_lock = asyncio.Lock()
+
+    # ── derived paths ──────────────────────────────────────────────
+
+    @property
+    def _data_dir(self) -> str:
+        """``${workdir}/data`` — offloaded multimodal payloads."""
+        return self.get_backend().join_path(self.workdir, DEFAULT_DATA_DIR)
+
+    @property
+    def _skills_dir(self) -> str:
+        """``${workdir}/skills`` — skill subdirectories."""
+        return self.get_backend().join_path(
+            self.workdir,
+            DEFAULT_SKILLS_DIR,
+        )
+
+    @property
+    def _sessions_dir(self) -> str:
+        """``${workdir}/sessions`` — per-session offload files."""
+        return self.get_backend().join_path(
+            self.workdir,
+            DEFAULT_SESSIONS_DIR,
+        )
+
+    @property
+    def _mcp_file(self) -> str:
+        """``${workdir}/.mcp`` — persisted MCP registrations."""
+        return self.get_backend().join_path(self.workdir, DEFAULT_MCP_FILE)
+
+    @property
+    def is_persistent(self) -> bool:
+        """Whether the workspace storage survives :meth:`close`.
+
+        Defaults to ``True``. Subclasses with conditional persistence
+        (e.g. :class:`DockerWorkspace` without a host bind-mount)
+        override this to gate the cost of writing ``.mcp`` and other
+        files that would not survive the next session.
+        """
+        return True
+
+    @staticmethod
+    def _path_to_file_uri(path: str) -> str:
+        """Convert an absolute backend-side path to a ``file://`` URI.
+
+        Absolute POSIX paths (every remote backend, plus
+        :class:`LocalBackend` on Linux/macOS) start with ``/`` and use
+        the plain ``file://{path}`` form. Windows absolute paths
+        (e.g. ``C:\\Users\\...``) round-trip through
+        :meth:`pathlib.Path.as_uri` to produce ``file:///C:/...`` form.
+        """
+        if path.startswith("/"):
+            return f"file://{path}"
+        return Path(path).as_uri()
+
+    # ── lifecycle (developer) ──────────────────────────────────────
+
+    @abstractmethod
+    async def initialize(self) -> None:
+        """Provision resources, connect MCP servers, copy skills."""
+
+    @abstractmethod
+    async def close(self) -> None:
+        """Release all resources and connections."""
+
+    async def reset(self) -> None:
+        """Reset the workspace to a clean state.
+
+        Closes and removes all registered MCPs, deletes all skills,
+        and wipes per-session state (offloaded context / tool results
+        and any data files). Constructor-time ``default_mcps`` and
+        ``skill_paths`` are **not** re-seeded — reset returns the
+        workspace to an empty state, not its initial state.
+
+        The default implementation is a no-op. Subclasses with user
+        state must override this.
+        """
+
+    def get_backend(self) -> BackendBase:
+        """Return the workspace's active filesystem/execution backend.
+
+        Docker and E2B workspaces may replace their backend when reconnecting,
+        so callers should resolve it from the workspace when beginning an
+        operation rather than retaining a stale private ``_backend`` value.
+
+        Raises:
+            RuntimeError:
+                If the workspace has not been initialized or has no active
+                backend.
+        """
+        if self._backend is None:
+            raise RuntimeError(
+                f"{type(self).__name__} has no active backend. "
+                "Initialize the workspace before requesting its backend.",
+            )
+        return self._backend
+
+    async def __aenter__(self) -> Self:
+        """Context manager support for ``async with``. Calls ``initialize()``
+        and returns the workspace instance.
+        """
+        await self.initialize()
+        self.is_alive = True
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        """Context manager support for ``async with``. Calls ``close()``
+        and returns the workspace instance.
+        """
+        await self.close()
+        self.is_alive = False
+
+    # ── instructions ───────────────────────────────────────────────
+
+    @abstractmethod
+    async def get_instructions(self) -> str:
+        """Workspace-specific system prompt fragment."""
+
+    # ── for Agent: tool & MCP discovery ────────────────────────────
+
+    async def list_tools(self) -> list[ToolBase]:
+        """Built-in tools scoped to this workspace.
+
+        Returns the six builtin tools (:class:`Bash`, :class:`Edit`,
+        :class:`Glob`, :class:`Grep`, :class:`Read`, :class:`Write`),
+        each bound to the workspace's active backend so that all
+        filesystem and process I/O happens inside the workspace's
+        execution environment. :class:`Bash` is rooted at
+        :attr:`workdir`; :class:`Glob` receives the optional
+        :attr:`_glob_helper_path` when the backend ships one.
+
+        Raises:
+            RuntimeError:
+                If the workspace has not been initialised yet.
+        """
+        from ..tool import Bash, Edit, Glob, Grep, Read, Write
+
+        backend = self.get_backend()
+        glob_kwargs: dict = {"backend": backend}
+        if self._glob_helper_path is not None:
+            glob_kwargs["glob_helper_path"] = self._glob_helper_path
+        return [
+            Bash(cwd=self.workdir, backend=backend),
+            Edit(backend=backend),
+            Glob(**glob_kwargs),
+            Grep(backend=backend),
+            Read(backend=backend),
+            Write(backend=backend),
+        ]
+
+    async def list_mcps(self) -> list[MCPClient]:
+        """Return the currently registered MCP clients."""
+        return list(self._mcps)
+
+    # ── for User: dynamic MCP management ───────────────────────────
+
+    @abstractmethod
+    async def add_mcp(self, mcp_client: MCPClient) -> None:
+        """Register a new MCP server.
+
+        Args:
+            mcp_client (`MCPClient`):
+                The MCP to register.
+
+        Raises:
+            `ValueError`:
+                If an MCP with the same name already exists.
+        """
+
+    @abstractmethod
+    async def remove_mcp(self, name: str) -> None:
+        """Deregister an MCP server by name.
+
+        Args:
+            name (`str`):
+                MCP name to remove. Unknown names log a warning and
+                return silently.
+        """
+
+    # ── MCP persistence (shared) ───────────────────────────────────
+
+    async def _save_mcp_file(self) -> None:
+        """Persist ``self._mcps`` to ``${workdir}/.mcp`` via backend.
+
+        No-op when :attr:`is_persistent` is ``False`` (e.g. ephemeral
+        Docker container without a host bind-mount). Failures are
+        logged but not raised — the in-memory MCP list remains the
+        authoritative copy regardless of whether disk persistence
+        succeeded.
+
+        Callers are expected to hold :attr:`_mcp_lock` already.
+        """
+        if not self.is_persistent:
+            return
+        backend = self._backend
+        if backend is None:
+            return
+        payload = json.dumps(
+            [m.model_dump(mode="json") for m in self._mcps],
+            indent=2,
+            ensure_ascii=False,
+        ).encode("utf-8")
+        try:
+            await backend.write_file(self._mcp_file, payload)
+        except Exception as e:
+            logger.warning(
+                "Failed to save MCP file at %s: %s",
+                self._mcp_file,
+                e,
+            )
+
+    # ── for Agent: offload (shared) ────────────────────────────────
+
+    async def offload_context(
+        self,
+        session_id: str,
+        msgs: list[Msg],
+    ) -> str:
+        """Persist compressed context for agentic retrieval.
+
+        Appends every message in ``msgs`` to
+        ``${workdir}/sessions/<session_id>/context.jsonl`` (one
+        message per JSONL line). Inline base64
+        :class:`DataBlock` payloads are extracted into ``data/`` and
+        rewritten as ``file://`` URL blocks before serialisation so
+        the JSONL line size stays bounded.
+
+        Args:
+            session_id (`str`):
+                Session-scope key used to partition offloaded data
+                (one subdirectory per session).
+            msgs (`list[Msg]`):
+                Conversation messages to offload. Not mutated — a
+                deep copy is used internally.
+
+        Returns:
+            `str`:
+                Backend-side path of the JSONL file that received
+                the new lines.
+        """
+        backend = self.get_backend()
+        base = backend.join_path(self._sessions_dir, session_id)
+        path = backend.join_path(base, "context.jsonl")
+
+        copied = deepcopy(msgs)
+        lines: list[str] = []
+        for msg in copied:
+            if not isinstance(msg.content, str):
+                content: list = []
+                for block in msg.content:
+                    if isinstance(block, DataBlock) and isinstance(
+                        block.source,
+                        Base64Source,
+                    ):
+                        block = await self._offload_data_block(block)
+                    content.append(block)
+                msg.content = content
+            lines.append(msg.model_dump_json())
+
+        payload = "\n".join(lines) + "\n"
+
+        existing = b""
+        try:
+            existing = await backend.read_file(path)
+        except (FileNotFoundError, OSError):
+            pass
+        await backend.write_file(path, existing + payload.encode("utf-8"))
+        return path
+
+    async def offload_tool_result(
+        self,
+        session_id: str,
+        tool_result: ToolResultBlock,
+    ) -> str:
+        """Persist a single tool result as a flat text file.
+
+        Writes ``${workdir}/sessions/<session_id>/tool_result-<id>.txt``.
+        Text blocks are concatenated verbatim; :class:`DataBlock` items
+        emit ``<data url='…' name='…' media_type='…'/>`` placeholders,
+        with inline base64 payloads first offloaded to ``data/``.
+
+        On a filename clash (same tool-result ``id`` written twice in
+        one session) the new file is suffixed with ``(1)``, ``(2)``,
+        … to avoid clobbering the prior content.
+
+        Args:
+            session_id (`str`):
+                Session-scope key used to partition offloaded data.
+            tool_result (`ToolResultBlock`):
+                The tool result block to persist.
+
+        Returns:
+            `str`:
+                Backend-side path of the offloaded text file.
+        """
+        backend = self.get_backend()
+        base = backend.join_path(self._sessions_dir, session_id)
+        path = backend.join_path(base, f"tool_result-{tool_result.id}.txt")
+
+        index = 1
+        while await backend.file_exists(path):
+            path = backend.join_path(
+                base,
+                f"tool_result-{tool_result.id}({index}).txt",
+            )
+            index += 1
+
+        parts: list[str] = []
+        if isinstance(tool_result.output, str):
+            parts.append(tool_result.output)
+        else:
+            for block in tool_result.output:
+                if isinstance(block, TextBlock):
+                    parts.append(block.text)
+                elif isinstance(block, DataBlock):
+                    if isinstance(block.source, Base64Source):
+                        d = await self._offload_data_block(block)
+                        url = str(d.source.url)
+                    else:
+                        url = str(block.source.url)
+                    parts.append(
+                        f"<data url='{url}' name='{block.name}' "
+                        f"media_type='{block.source.media_type}'/>",
+                    )
+
+        await backend.write_file(path, "".join(parts).encode("utf-8"))
+        return path
+
+    async def _offload_data_block(self, block: DataBlock) -> DataBlock:
+        """Persist a base64 :class:`DataBlock` under ``data/``.
+
+        The decoded payload is stored at
+        ``${workdir}/data/<sha256-of-base64>.<ext>``. Hashing the
+        *base64* text rather than the decoded bytes lets a second
+        offload of the same block short-circuit (same key → same
+        file → no write).
+
+        Args:
+            block (`DataBlock`):
+                A data block. Blocks already backed by a
+                :class:`URLSource` are returned unchanged.
+
+        Returns:
+            `DataBlock`:
+                A new :class:`DataBlock` whose source is a ``file://``
+                URL pointing at the persisted file inside the
+                workspace.
+        """
+        if not isinstance(block.source, Base64Source):
+            return block
+
+        backend = self.get_backend()
+        hash_str = hashlib.sha256(block.source.data.encode()).hexdigest()
+        ext = mimetypes.guess_extension(block.source.media_type) or ".bin"
+        path = backend.join_path(self._data_dir, f"{hash_str}{ext}")
+
+        if not await backend.file_exists(path):
+            await backend.write_file(
+                path,
+                base64.b64decode(block.source.data),
+            )
+
+        return DataBlock(
+            id=block.id,
+            name=block.name,
+            source=URLSource(
+                url=AnyUrl(self._path_to_file_uri(path)),
+                media_type=block.source.media_type,
+            ),
+        )
+
+    # ── skill management (shared, simple) ──────────────────────────
+
+    async def list_skills(self) -> list[Skill]:
+        """Enumerate skills under ``${workdir}/skills``.
+
+        Walks ``skills/`` recursively, parses every ``SKILL.md``'s
+        YAML front matter, and yields one :class:`Skill` per file
+        that has both ``name`` and ``description``.
+
+        Subclasses with richer indexing (e.g.
+        :class:`LocalWorkspace` with its ``.skills`` hash index)
+        override this method.
+
+        Returns:
+            `list[Skill]`:
+                Skills available to the agent. Empty when ``skills/``
+                is missing or contains no parseable ``SKILL.md``.
+        """
+        import frontmatter as fm
+
+        backend = self.get_backend()
+        if not await backend.is_dir(self._skills_dir):
+            return []
+
+        entries = await backend.list_dir(self._skills_dir, recursive=True)
+
+        skills: list[Skill] = []
+        for md_path in entries:
+            if backend.basename(md_path) != "SKILL.md":
+                continue
+            try:
+                raw = await backend.read_file(md_path)
+                doc = fm.loads(raw.decode("utf-8"))
+                name = doc.get("name")
+                desc = doc.get("description")
+                if not name or not desc:
+                    continue
+                skills.append(
+                    Skill(
+                        name=str(name),
+                        description=str(desc),
+                        dir=backend.dirname(md_path),
+                        markdown=doc.content or "",
+                        updated_at=0.0,
+                    ),
+                )
+            except Exception as e:
+                logger.warning("Failed to load skill %s: %s", md_path, e)
+        return skills
+
+    async def add_skill(self, skill_path: str) -> None:
+        """Copy a local skill directory into ``${workdir}/skills``.
+
+        Tars the directory on the host, writes the archive to the
+        backend's tmp area, and extracts it via ``python3 -c`` inside
+        the sandbox — two round trips regardless of skill size, and
+        portable across any backend whose image ships ``python3``
+        (same contract as the gateway shim).
+
+        Subclasses with richer dedup (e.g. :class:`LocalWorkspace`
+        with hash-indexed conflict resolution) override this method.
+
+        Args:
+            skill_path (`str`):
+                Path to a skill directory on the local filesystem.
+
+        Raises:
+            ValueError:
+                If ``SKILL.md`` is missing or a directory with the
+                same basename already exists in ``skills/``.
+            RuntimeError:
+                If extraction inside the sandbox fails.
+        """
+        skill_md = os.path.join(skill_path, "SKILL.md")
+        if not os.path.isfile(skill_md):
+            raise ValueError(
+                f"Invalid skill at {skill_path!r}: SKILL.md not found",
+            )
+
+        backend = self.get_backend()
+
+        async with self._skill_lock:
+            dir_name = os.path.basename(os.path.abspath(skill_path))
+            remote_dir = backend.join_path(self._skills_dir, dir_name)
+
+            if await backend.file_exists(remote_dir):
+                raise ValueError(
+                    f"Skill directory {dir_name!r} already exists in "
+                    f"{self._skills_dir}",
+                )
+
+            buf = io.BytesIO()
+            with tarfile.open(fileobj=buf, mode="w") as tf:
+                tf.add(skill_path, arcname=dir_name)
+            tar_bytes = buf.getvalue()
+
+            tmp_path = f"/tmp/skill-{_generate_id()}.tar"
+            await backend.write_file(tmp_path, tar_bytes)
+
+            await backend.exec_shell(
+                ["mkdir", "-p", self._skills_dir],
+            )
+            result = await backend.exec_shell(
+                [
+                    "python3",
+                    "-c",
+                    _EXTRACT_TAR_SHIM,
+                    tmp_path,
+                    self._skills_dir,
+                ],
+            )
+            if not result.ok():
+                raise RuntimeError(
+                    f"Failed to extract skill {dir_name!r}: "
+                    f"{result.stderr.decode('utf-8', 'replace')}",
+                )
+
+            logger.info("Added skill %r at %s", dir_name, remote_dir)
+
+    async def remove_skill(self, name: str) -> None:
+        """Remove a skill by its agent-facing ``name`` (front matter).
+
+        Looks up the skill via :meth:`list_skills` and ``rm -rf``-style
+        deletes its directory through the backend.
+
+        Args:
+            name (`str`):
+                The agent-facing name of the skill to remove.
+
+        Raises:
+            KeyError:
+                If the skill is not found in the workspace.
+        """
+        backend = self.get_backend()
+        skills = await self.list_skills()
+        target_dir: str | None = None
+        for s in skills:
+            if s.name == name:
+                target_dir = s.dir
+                break
+        if target_dir is None:
+            available = [s.name for s in skills]
+            raise KeyError(
+                f"Skill {name!r} not found. Available: {available}",
+            )
+        await backend.delete_path(target_dir)
+        logger.info("Removed skill %r at %s", name, target_dir)
+
+    async def _setup_skills(self) -> None:
+        """Copy :attr:`skill_paths` into ``${workdir}/skills`` once.
+
+        Skips seeding when:
+
+        - :attr:`skill_paths` is empty;
+        - the backend is not bound; or
+        - ``skills/`` already contains entries (assume the prior
+          run, or the user, is the source of truth).
+
+        Individual failures are logged and skipped — a single bad
+        skill cannot block startup.
+        """
+        if not self.skill_paths:
+            return
+        backend = self._backend
+        if backend is None:
+            return
+        entries = await backend.list_dir(self._skills_dir)
+        if entries:
+            return
+        for path in self.skill_paths:
+            try:
+                await self.add_skill(path)
+            except Exception as e:
+                logger.warning(
+                    "Skip skill %r: %s",
+                    path,
+                    e,
+                )
diff --git a/src/agentscope/workspace/_docker/Dockerfile.node_copy.template b/src/agentscope/workspace/_docker/Dockerfile.node_copy.template
new file mode 100644
index 0000000..928606c
--- /dev/null
+++ b/src/agentscope/workspace/_docker/Dockerfile.node_copy.template
@@ -0,0 +1,4 @@
+COPY --from=node_stage /usr/local/bin/node /usr/local/bin/node
+COPY --from=node_stage /usr/local/lib/node_modules /usr/local/lib/node_modules
+RUN ln -sf /usr/local/lib/node_modules/npm/bin/npm-cli.js /usr/local/bin/npm \
+ && ln -sf /usr/local/lib/node_modules/npm/bin/npx-cli.js /usr/local/bin/npx
diff --git a/src/agentscope/workspace/_docker/Dockerfile.node_from.template b/src/agentscope/workspace/_docker/Dockerfile.node_from.template
new file mode 100644
index 0000000..396843f
--- /dev/null
+++ b/src/agentscope/workspace/_docker/Dockerfile.node_from.template
@@ -0,0 +1 @@
+FROM node:{node_version}-slim AS node_stage
\ No newline at end of file
diff --git a/src/agentscope/workspace/_docker/Dockerfile.template b/src/agentscope/workspace/_docker/Dockerfile.template
new file mode 100644
index 0000000..7a56a0a
--- /dev/null
+++ b/src/agentscope/workspace/_docker/Dockerfile.template
@@ -0,0 +1,51 @@
+# syntax=docker/dockerfile:1.6
+# The filenames `.venv`, `_mcp_gateway_app.py`, `_glob_helper.py`,
+# `gateway.log` below MUST stay in sync with the DEFAULT_GATEWAY_*
+# constants in ``agentscope.workspace._utils`` — the base class derives
+# runtime paths from those and joins them under ``_gateway_home``.
+{node_from_block}FROM {base_image}
+
+# Install uv via Astral's official shell installer.
+# We use this rather than ``COPY --from=ghcr.io/astral-sh/uv`` to avoid
+# depending on GitHub Container Registry at build time (the GHCR blob CDN
+# has been observed to time out from some networks). ``curl`` and
+# ``ca-certificates`` are not present in ``python:*-slim`` so we apt them
+# in first, then drop the apt cache to keep the layer small.
+# ``UV_INSTALL_DIR`` redirects the installer's default ``~/.local/bin``
+# target to ``/usr/local/bin`` so ``uv`` lands directly on PATH;
+# ``INSTALLER_NO_MODIFY_PATH=1`` suppresses the installer's attempt to
+# patch shell rc files (we don't need it — PATH already covers it).
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends curl ca-certificates ripgrep \
+ && rm -rf /var/lib/apt/lists/* \
+ && curl -LsSf https://astral.sh/uv/install.sh \
+        | env UV_INSTALL_DIR=/usr/local/bin INSTALLER_NO_MODIFY_PATH=1 sh
+
+{node_copy_block}ENV UV_PROJECT_ENVIRONMENT={gateway_home}/.venv \
+    UV_LINK_MODE=copy \
+    PATH={gateway_home}/.venv/bin:$PATH
+WORKDIR {gateway_home}
+RUN uv venv {gateway_home}/.venv
+
+# TODO(release): once agentscope ships an extra such as `agentscope[gateway]`
+# bundling fastapi/uvicorn/mcp, drop requirements.txt and fold these pins into
+# the install step below — keeping a single `uv pip install agentscope[gateway]`.
+COPY requirements.txt {gateway_home}/requirements.txt
+# Note: aiodocker drives the legacy build endpoint, which does not
+# support BuildKit cache mounts (``--mount=type=cache,...``). uv's
+# in-package cache still works for single-build deduping; we just lose
+# inter-build layer cache reuse — acceptable since the image tag hash
+# already gates re-builds at the layer level.
+RUN uv pip install -r {gateway_home}/requirements.txt
+
+{install_agentscope_block}
+# Standalone gateway script. We invoke this directly (not via
+# ``python -m``) so Python does not auto-import
+# ``agentscope.workspace.__init__`` and pull in its heavy module
+# graph (skill, tool, …). The script imports only
+# ``agentscope.mcp.MCPClient``.
+COPY _mcp_gateway_app.py {gateway_home}/_mcp_gateway_app.py
+# Glob helper script used by the builtin Glob tool.
+COPY _glob_helper.py {gateway_home}/_glob_helper.py
+
+WORKDIR {container_workdir}
diff --git a/src/agentscope/workspace/_docker/__init__.py b/src/agentscope/workspace/_docker/__init__.py
new file mode 100644
index 0000000..1363a98
--- /dev/null
+++ b/src/agentscope/workspace/_docker/__init__.py
@@ -0,0 +1,13 @@
+# -*- coding: utf-8 -*-
+"""Docker-backed workspace.
+
+The container image is built on demand from a content-hashed Dockerfile
+(see :mod:`._make_dockerfile`); a tag cache hit skips the build. MCP
+servers run *inside* the container behind a FastAPI gateway and are
+reached over HTTP — see :mod:`agentscope.workspace._gateway_client`.
+"""
+
+from ._docker_workspace import DockerWorkspace
+from ._docker_backend import DockerBackend
+
+__all__ = ["DockerWorkspace", "DockerBackend"]
diff --git a/src/agentscope/workspace/_docker/_docker_backend.py b/src/agentscope/workspace/_docker/_docker_backend.py
new file mode 100644
index 0000000..7989f9d
--- /dev/null
+++ b/src/agentscope/workspace/_docker/_docker_backend.py
@@ -0,0 +1,193 @@
+# -*- coding: utf-8 -*-
+"""Docker container :class:`BackendBase` implementation.
+
+Wraps the ``aiodocker`` container APIs (``exec``, ``get_archive``,
+``put_archive``) into the three backend primitives (``exec_shell``,
+``read_file``, ``write_file``) so that builtin tools (Bash, Read,
+Write, Edit, Grep, Glob) can operate inside a Docker container
+transparently.  All derived filesystem helpers (``file_exists``,
+``is_dir``, ``list_dir``, ``stat_mtime``, ``delete_path``) are
+inherited from :class:`BackendBase`, which implements them via
+``exec_shell``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import io
+import posixpath
+import tarfile
+from typing import Any
+
+from ...tool import BackendBase, ExecResult
+
+
+class DockerBackend(BackendBase):
+    """Backend that delegates to a running Docker container.
+
+    Only the three abstract primitives (``exec_shell``, ``read_file``,
+    ``write_file``) are implemented here; the derived filesystem helpers
+    are inherited from :class:`BackendBase`.
+
+    Args:
+        container (`Any`):
+            An ``aiodocker`` container object (must already be started).
+        workdir (`str`):
+            Default working directory for ``exec_shell`` calls inside
+            the container.
+    """
+
+    def __init__(self, container: Any, workdir: str) -> None:
+        """Initialize the Docker backend.
+
+        Args:
+            container (`Any`):
+                A started ``aiodocker`` container object.
+            workdir (`str`):
+                Default working directory for ``exec_shell`` calls
+                inside the container.
+        """
+        self._container = container
+        self._workdir = workdir
+
+    # ── exec ───────────────────────────────────────────────────────
+
+    async def getcwd(self) -> str:
+        """Return the container's default working directory.
+
+        Overrides the base class default (which would shell out to
+        ``pwd``) with the cached ``workdir`` supplied at construction,
+        avoiding a per-call container ``exec`` round-trip.
+
+        Returns:
+            `str`:
+                The container's default working directory.
+        """
+        return self._workdir
+
+    async def exec_shell(
+        self,
+        command: list[str],
+        *,
+        cwd: str | None = None,
+        timeout: float | None = None,
+    ) -> ExecResult:
+        """Run a program directly inside the container.
+
+        *command* is an argv list executed via the container ``exec``
+        API without an intervening shell. Callers needing shell features
+        wrap their command line as ``["sh", "-c", line]``.
+
+        Args:
+            command (`list[str]`):
+                Executable path/name followed by its arguments.
+            cwd (`str | None`, optional):
+                Working directory inside the container. When ``None``
+                the backend's default ``workdir`` is used.
+            timeout (`float | None`, optional):
+                Maximum number of seconds to wait before returning an
+                ``exit_code`` of ``-1``. When ``None`` the call waits
+                indefinitely.
+
+        Returns:
+            `ExecResult`:
+                The captured exit code, stdout, and stderr.
+        """
+
+        async def _run() -> ExecResult:
+            exec_obj = await self._container.exec(
+                cmd=command,
+                workdir=cwd or self._workdir,
+            )
+            stdout_parts: list[bytes] = []
+            stderr_parts: list[bytes] = []
+            async with exec_obj.start() as stream:
+                while True:
+                    msg = await stream.read_out()
+                    if msg is None:
+                        break
+                    if msg.stream == 1:
+                        stdout_parts.append(msg.data)
+                    else:
+                        stderr_parts.append(msg.data)
+            inspect = await exec_obj.inspect()
+            code = inspect.get("ExitCode", -1)
+            if code is None:
+                code = -1
+            return ExecResult(
+                exit_code=int(code),
+                stdout=b"".join(stdout_parts),
+                stderr=b"".join(stderr_parts),
+            )
+
+        if timeout is None:
+            return await _run()
+        try:
+            return await asyncio.wait_for(_run(), timeout=timeout)
+        except asyncio.TimeoutError:
+            return ExecResult(
+                exit_code=-1,
+                stdout=b"",
+                stderr=b"timed out",
+            )
+
+    # ── file I/O ───────────────────────────────────────────────────
+
+    async def read_file(self, path: str) -> bytes:
+        """Fetch a file from the container via ``get_archive``.
+
+        Args:
+            path (`str`):
+                Path to the file inside the container.
+
+        Returns:
+            `bytes`:
+                The raw file contents.
+
+        Raises:
+            `FileNotFoundError`:
+                If the path does not exist inside the container.
+        """
+        from aiodocker import exceptions as aiodocker_exceptions
+
+        try:
+            tar = await self._container.get_archive(path)
+        except aiodocker_exceptions.DockerError as exc:
+            if exc.status == 404:
+                raise FileNotFoundError(
+                    f"not found in container: {path}",
+                ) from exc
+            raise
+
+        try:
+            for member in tar.getmembers():
+                if member.isfile():
+                    f = tar.extractfile(member)
+                    if f:
+                        return f.read()
+        finally:
+            tar.close()
+        raise FileNotFoundError(f"not found in container: {path}")
+
+    async def write_file(self, path: str, data: bytes) -> None:
+        """Write raw bytes to a file inside the container.
+
+        Creates the parent directory first since ``put_archive``
+        requires it to exist.
+
+        Args:
+            path (`str`):
+                Destination path inside the container.
+            data (`bytes`):
+                The raw bytes to write.
+        """
+        parent = posixpath.dirname(path) or "/"
+        name = posixpath.basename(path)
+
+        await self.exec_shell(["mkdir", "-p", parent])
+        buf = io.BytesIO()
+        with tarfile.open(fileobj=buf, mode="w") as tf:
+            info = tarfile.TarInfo(name=name)
+            info.size = len(data)
+            tf.addfile(info, io.BytesIO(data))
+        await self._container.put_archive(parent, buf.getvalue())
diff --git a/src/agentscope/workspace/_docker/_docker_workspace.py b/src/agentscope/workspace/_docker/_docker_workspace.py
new file mode 100644
index 0000000..e28efa6
--- /dev/null
+++ b/src/agentscope/workspace/_docker/_docker_workspace.py
@@ -0,0 +1,331 @@
+# -*- coding: utf-8 -*-
+"""DockerWorkspace — sandboxed workspace backed by a Docker container.
+
+* Container lifecycle (build + run + stop) via **aiodocker**.
+* MCP servers run inside the container behind a FastAPI gateway
+  (see :mod:`agentscope.workspace._mcp_gateway`); the host reaches it
+  through :class:`GatewayClient` via ``backend.exec_shell``.
+* Optional bind-mounted host ``workdir`` makes the workspace
+  persistent — ``.mcp``, ``skills/``, ``sessions/``, ``data/`` survive
+  restarts. Without ``workdir`` the container is ephemeral.
+* Image is content-hashed by Dockerfile + COPY payloads
+  (see :mod:`._make_dockerfile`); a cache hit skips the build.
+
+On each :meth:`initialize`, MCPs are restored from ``<workdir>/.mcp``
+(or seeded from ``default_mcps``); ``add_mcp`` / ``remove_mcp`` rewrite
+the file. The gateway reads ``.mcp`` directly as its config.
+"""
+
+import io
+import os
+import shutil
+import sys
+import tarfile
+from typing import Any
+
+from ..._logging import logger
+from ...mcp import MCPClient
+from .._sandboxed_base import SandboxedWorkspaceBase
+from ._docker_backend import DockerBackend
+from ._make_dockerfile import (
+    CONTAINER_WORKDIR,
+    DEFAULT_BASE_IMAGE,
+    DEFAULT_GATEWAY_PORT,
+    GATEWAY_HOME,
+    prepare_build_context,
+)
+
+_DEFAULT_INSTRUCTIONS = """<workspace>
+You have a Docker-based workspace. All tool calls execute **inside the
+container** at ``{workdir}``.
+
+Layout:
+
+```
+{workdir}
+├── data/        # offloaded multimodal files
+├── skills/      # reusable skills
+└── sessions/    # session context and tool results
+```
+</workspace>"""
+
+
+# ── the workspace ──────────────────────────────────────────────────
+
+
+class DockerWorkspace(SandboxedWorkspaceBase):
+    """Workspace backed by a Docker container.
+
+    ``default_mcps`` and ``skill_paths`` are seed-time inputs and are
+    not retained as instance state past :meth:`initialize`.
+    """
+
+    _gateway_home = GATEWAY_HOME
+
+    def __init__(
+        self,
+        *,
+        workspace_id: str | None = None,
+        base_image: str = DEFAULT_BASE_IMAGE,
+        host_workdir: str | None = None,
+        node_version: str | None = None,
+        extra_pip: list[str] | None = None,
+        gateway_port: int = DEFAULT_GATEWAY_PORT,
+        env: dict[str, str] | None = None,
+        instructions: str = _DEFAULT_INSTRUCTIONS,
+        default_mcps: list[MCPClient] | None = None,
+        skill_paths: list[str] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Construct a :class:`DockerWorkspace`.
+
+        The workspace is *not* started here — call :meth:`initialize`
+        (or use the workspace as an ``async`` context manager).
+
+        Args:
+            workspace_id (`str | None`, optional):
+                Existing workspace identifier to adopt; ``None`` mints
+                a fresh UUID.
+            base_image (`str`, defaults to `DEFAULT_BASE_IMAGE`):
+                Base Docker image. Must provide ``python3`` in
+                ``$PATH``.
+            host_workdir (`str | None`, optional):
+                Host directory bind-mounted to ``/workspace``. ``None``
+                makes the workspace ephemeral.
+            node_version (`str | None`, optional):
+                Major Node.js version to bake into the image.
+            extra_pip (`list[str] | None`, optional):
+                Extra Python packages installed into the gateway venv
+                at image-build time.
+            gateway_port (`int`, defaults to `DEFAULT_GATEWAY_PORT`):
+                TCP port the gateway listens on inside the container
+                (no host port mapping).
+            env (`dict[str, str] | None`, optional):
+                Environment variables to set inside the container.
+            instructions (`str`, defaults to `_DEFAULT_INSTRUCTIONS`):
+                System-prompt fragment template; supports ``{workdir}``.
+            default_mcps (`list[MCPClient] | None`, optional):
+                MCPs registered on first init when no persisted
+                ``.mcp`` exists.
+            skill_paths (`list[str] | None`, optional):
+                Local skill dirs seeded into ``skills/`` on first init.
+        """
+        # Backwards compatibility: accept legacy ``workdir`` kwarg.
+        if "workdir" in kwargs:
+            logger.warning(
+                "DockerWorkspace parameter 'workdir' is deprecated, "
+                "use 'host_workdir' instead.",
+            )
+            if host_workdir is None:
+                host_workdir = kwargs.pop("workdir")
+
+        super().__init__(
+            workspace_id=workspace_id,
+            default_mcps=default_mcps,
+            skill_paths=skill_paths,
+        )
+
+        # ── serializable config ─────────────────────────────────
+        self.workdir = CONTAINER_WORKDIR
+        self.base_image = base_image
+        self.host_workdir = host_workdir
+        self.node_version = node_version
+        self.extra_pip: list[str] = list(extra_pip or [])
+        self.gateway_port = gateway_port
+        self.env: dict[str, str] = dict(env or {})
+        self.instructions = instructions
+
+        # ── runtime state (Docker-only) ─────────────────────────
+        self._client: Any = None  # aiodocker.Docker
+        self._container: Any = None
+        self._backend: DockerBackend | None = None
+        self._image_tag: str = ""
+
+    @property
+    def is_persistent(self) -> bool:
+        """``True`` iff a host bind-mount preserves the workspace."""
+        return self.host_workdir is not None
+
+    # ── lifecycle hooks ─────────────────────────────────────────
+
+    async def _provision_backend(self) -> None:
+        """Build / reuse the image and start the container."""
+        import aiodocker
+
+        self._client = aiodocker.Docker()
+        await self._build_or_reuse_image()
+        await self._create_and_start_container()
+
+    async def _teardown_backend(self) -> None:
+        """Stop and remove the container; release the aiodocker client.
+
+        Errors are swallowed so teardown is always safe.
+        """
+        if self._container is not None:
+            # On Linux native docker, the in-container root process
+            # writes bind-mount files with container-side ownership;
+            # restore ownership to the host user so they can be
+            # removed. macOS/Windows Docker remap uids transparently.
+            if (
+                self.host_workdir is not None
+                and sys.platform == "linux"
+                and self._backend is not None
+            ):
+                try:
+                    await self._backend.exec_shell(
+                        [
+                            "chown",
+                            "-R",
+                            f"{os.getuid()}:{os.getgid()}",
+                            CONTAINER_WORKDIR,
+                        ],
+                        timeout=10.0,
+                    )
+                except Exception:
+                    pass
+            try:
+                await self._container.kill()
+            except Exception:
+                pass
+            try:
+                await self._container.delete(force=True)
+            except Exception:
+                pass
+            self._container = None
+
+        if self._client is not None:
+            try:
+                await self._client.close()
+            except Exception:
+                pass
+            self._client = None
+
+    # ── instructions ────────────────────────────────────────────
+
+    async def get_instructions(self) -> str:
+        """Return the system-prompt fragment, formatted with the
+        container-side ``{workdir}``."""
+        return self.instructions.format(workdir=CONTAINER_WORKDIR)
+
+    # ── internals: image build ──────────────────────────────────
+
+    async def _build_or_reuse_image(self) -> None:
+        """Build the workspace image, or reuse a tag-cache hit.
+
+        The tag is a content hash of the rendered Dockerfile plus
+        every file copied into the build context. ``self._image_tag``
+        is populated unconditionally so that the container-creation
+        step has a stable reference, even on cache hits.
+
+        Raises:
+            RuntimeError: If a build error message comes through the
+                docker stream.
+        """
+        ctx_dir, tag, _ = prepare_build_context(
+            base_image=self.base_image,
+            gateway_home=GATEWAY_HOME,
+            container_workdir=CONTAINER_WORKDIR,
+            node_version=self.node_version,
+            extra_pip=self.extra_pip,
+        )
+        self._image_tag = tag
+
+        try:
+            try:
+                await self._client.images.inspect(tag)
+                logger.info("DockerWorkspace: image cache hit %r", tag)
+                return
+            except Exception:
+                pass
+
+            logger.info("DockerWorkspace: building image %r", tag)
+            # The Docker daemon's POST /build endpoint requires the
+            # build context as a tar archive in the request body.
+            # docker-py hides this behind a ``path=`` shortcut that
+            # tars the directory for you; aiodocker does *not* — we
+            # have to tar ``ctx_dir`` ourselves and hand it over via
+            # ``fileobj``.  ``arcname="."`` puts every entry at the
+            # tar root so the daemon finds ``./Dockerfile`` (and the
+            # ``COPY`` source files) without an extra prefix.
+            tar_buf = io.BytesIO()
+            with tarfile.open(fileobj=tar_buf, mode="w") as tf:
+                tf.add(str(ctx_dir), arcname=".")
+            tar_buf.seek(0)
+            # ``encoding="identity"`` tells aiodocker the body is a
+            # plain (uncompressed) tar — without it, aiodocker would
+            # gzip our already-tarred bytes and the daemon would
+            # reject the malformed stream.
+            stream = self._client.images.build(
+                fileobj=tar_buf,
+                encoding="identity",
+                tag=tag,
+                stream=True,
+                rm=True,
+            )
+            # Buffer recent stream lines so that a failing RUN step's
+            # stderr is included in the RuntimeError below — the
+            # daemon's ``error`` chunk only carries a one-line summary
+            # ("command returned non-zero code: 1") and the actual
+            # diagnostic is in the preceding ``stream`` chunks.
+            tail: list[str] = []
+            tail_max = 200
+            async for chunk in stream:
+                if isinstance(chunk, dict):
+                    if "stream" in chunk:
+                        msg = str(chunk["stream"]).rstrip()
+                        if msg:
+                            logger.debug("[docker build] %s", msg)
+                            tail.append(msg)
+                            if len(tail) > tail_max:
+                                del tail[: len(tail) - tail_max]
+                    if "error" in chunk:
+                        log = "\n".join(tail)
+                        raise RuntimeError(
+                            f"docker build failed: {chunk['error']}\n"
+                            f"--- last {len(tail)} build log lines ---\n"
+                            f"{log}",
+                        )
+        finally:
+            logger.info("DockerWorkspace: finish building image %r", tag)
+            shutil.rmtree(ctx_dir, ignore_errors=True)
+
+    # ── internals: container lifecycle ──────────────────────────
+
+    async def _create_and_start_container(self) -> None:
+        """Create + start the workspace container.
+
+        * ``Cmd: ["sleep", "infinity"]`` keeps it up across gateway
+          restarts.
+        * Optional bind mount ``host workdir → /workspace``.
+        * The gateway port stays internal — calls run from inside the
+          sandbox via :class:`GatewayClient`, so no host port mapping.
+        """
+        config: dict[str, Any] = {
+            "Image": self._image_tag,
+            "Cmd": ["sleep", "infinity"],
+            "WorkingDir": CONTAINER_WORKDIR,
+            "Labels": {
+                "agentscope.workspace": "true",
+                "agentscope.workspace.id": self.workspace_id,
+            },
+        }
+        if self.env:
+            config["Env"] = [f"{k}={v}" for k, v in self.env.items()]
+
+        host_config: dict[str, Any] = {}
+        if self.host_workdir is not None:
+            os.makedirs(self.host_workdir, exist_ok=True)
+            host_config["Binds"] = [
+                f"{os.path.abspath(self.host_workdir)}:{CONTAINER_WORKDIR}:rw",
+            ]
+        config["HostConfig"] = host_config
+
+        self._container = await self._client.containers.create_or_replace(
+            name=f"as_ws_{self.workspace_id}",
+            config=config,
+        )
+        await self._container.start()
+
+        # Create the backend now that the container is running. All
+        # subsequent container I/O in this workspace goes through it.
+        self._backend = DockerBackend(self._container, CONTAINER_WORKDIR)
diff --git a/src/agentscope/workspace/_docker/_make_dockerfile.py b/src/agentscope/workspace/_docker/_make_dockerfile.py
new file mode 100644
index 0000000..651e8ef
--- /dev/null
+++ b/src/agentscope/workspace/_docker/_make_dockerfile.py
@@ -0,0 +1,196 @@
+# -*- coding: utf-8 -*-
+"""Dockerfile generation + build-context preparation for DockerWorkspace.
+
+The image is keyed by content hash of the Dockerfile text plus all
+files COPYed into it. If the tag already exists locally the build is
+skipped; otherwise the caller builds with the prepared context.
+
+The container installs the same ``agentscope`` version as the host via
+``uv pip install --no-deps`` inside the gateway venv.
+
+Public functions:
+
+* :func:`render_dockerfile` — substitute placeholders in
+  ``Dockerfile.template`` and return the rendered text.
+* :func:`compute_image_tag` — sha256 of Dockerfile + COPY files;
+  returns ``agentscope-workspace:<12hex>``.
+* :func:`prepare_build_context` — assemble a temp directory holding
+  the Dockerfile, ``requirements.txt``, and helper scripts. Returns
+  ``(ctx_dir, tag, copy_files)``.
+"""
+
+import hashlib
+import importlib.resources as _res
+import tempfile
+from pathlib import Path
+
+from .._utils import (
+    _GATEWAY_BASE_REQUIREMENTS,
+    _read_gateway_script_bytes,
+    _read_glob_helper_bytes,
+)
+
+# ── shared constants (also imported by _docker_workspace) ──────────
+
+DEFAULT_BASE_IMAGE = "python:3.11-slim"
+DEFAULT_GATEWAY_PORT = 5600
+
+CONTAINER_WORKDIR = "/workspace"
+
+GATEWAY_HOME = "/root/.agentscope"
+
+IMAGE_REPO = "agentscope-workspace"
+
+# ── template loading ───────────────────────────────────────────────
+
+_TEMPLATE_PKG = "agentscope.workspace._docker"
+_DOCKERFILE_TEMPLATE = "Dockerfile.template"
+_DOCKERFILE_NODE_FROM_TEMPLATE = "Dockerfile.node_from.template"
+_DOCKERFILE_NODE_COPY_TEMPLATE = "Dockerfile.node_copy.template"
+
+
+def _read_template(name: str) -> str:
+    """Read a packaged template file as text."""
+    return _res.files(_TEMPLATE_PKG).joinpath(name).read_text(encoding="utf-8")
+
+
+# ── public API ─────────────────────────────────────────────────────
+
+
+def render_dockerfile(
+    *,
+    base_image: str = DEFAULT_BASE_IMAGE,
+    gateway_home: str = GATEWAY_HOME,
+    container_workdir: str = CONTAINER_WORKDIR,
+    node_version: str | None = None,
+    install_agentscope_block: str = "",
+) -> str:
+    """Render the Dockerfile by substituting into the template files.
+
+    Args:
+        base_image: Base image (must already provide ``python3``).
+        gateway_home: In-container directory for the gateway venv,
+            script and config.
+        container_workdir: Container-side workdir; bind-mounted from
+            the host when the workspace's ``workdir`` is set, else
+            an empty in-image directory.
+        node_version: When given (e.g. ``"20"``) a ``node`` and ``npm``
+            of that version are copied from the official Node slim
+            image. ``None`` skips Node installation.
+        install_agentscope_block: Pre-rendered block (no surrounding
+            blank lines) that installs ``agentscope`` into the gateway
+            venv. Built by :func:`prepare_build_context`.
+
+    Returns:
+        The full Dockerfile text.
+    """
+    if node_version:
+        # Normalise trailing whitespace so the main template's surrounding
+        # newlines fully control inter-section spacing — the template files
+        # themselves are not relied on for exact terminal newlines.
+        nf_raw = _read_template(_DOCKERFILE_NODE_FROM_TEMPLATE).format(
+            node_version=node_version,
+        )
+        nc_raw = _read_template(_DOCKERFILE_NODE_COPY_TEMPLATE)
+        node_from_block = nf_raw.rstrip() + "\n"
+        node_copy_block = nc_raw.rstrip() + "\n\n"
+    else:
+        node_from_block = ""
+        node_copy_block = ""
+
+    return _read_template(_DOCKERFILE_TEMPLATE).format(
+        base_image=base_image,
+        gateway_home=gateway_home,
+        container_workdir=container_workdir,
+        node_from_block=node_from_block,
+        node_copy_block=node_copy_block,
+        install_agentscope_block=install_agentscope_block.rstrip() + "\n",
+    )
+
+
+def _render_requirements(extra_pip: list[str]) -> str:
+    """Render ``requirements.txt`` content for the gateway venv."""
+    pinned = list(_GATEWAY_BASE_REQUIREMENTS) + list(extra_pip or [])
+    return "\n".join(pinned) + "\n"
+
+
+def compute_image_tag(
+    dockerfile_text: str,
+    copy_files: dict[str, bytes],
+) -> str:
+    """Hash the Dockerfile and COPY payloads into a deterministic tag.
+
+    Args:
+        dockerfile_text: Full Dockerfile text.
+        copy_files: Mapping of context-relative filename → bytes for
+            every file referenced by a ``COPY`` instruction.
+
+    Returns:
+        Tag of the form ``agentscope-workspace:<12 hex chars>``.
+    """
+    h = hashlib.sha256()
+    h.update(b"DOCKERFILE\x00")
+    h.update(dockerfile_text.encode("utf-8"))
+    for name in sorted(copy_files):
+        h.update(b"\x00FILE\x00")
+        h.update(name.encode("utf-8"))
+        h.update(b"\x00")
+        h.update(copy_files[name])
+    return f"{IMAGE_REPO}:{h.hexdigest()[:12]}"
+
+
+def prepare_build_context(
+    *,
+    base_image: str = DEFAULT_BASE_IMAGE,
+    gateway_home: str = GATEWAY_HOME,
+    container_workdir: str = CONTAINER_WORKDIR,
+    node_version: str | None = None,
+    extra_pip: list[str] | None = None,
+) -> tuple[Path, str, dict[str, bytes]]:
+    """Assemble a temporary build context directory.
+
+    Writes Dockerfile, ``requirements.txt`` and helper scripts into a
+    fresh temp dir. The caller is responsible for removing the directory
+    after the build completes.
+
+    Returns:
+        ``(ctx_dir, tag, copy_files)`` — ``ctx_dir`` holds the
+        materialised files; ``tag`` is the deterministic image tag;
+        ``copy_files`` is the same mapping that was hashed into the
+        tag (handy for callers that want to recompute / verify).
+    """
+    extra_pip_list = list(extra_pip or [])
+
+    install_block = 'RUN uv pip install "agentscope"'
+
+    dockerfile_text = render_dockerfile(
+        base_image=base_image,
+        gateway_home=gateway_home,
+        container_workdir=container_workdir,
+        node_version=node_version,
+        install_agentscope_block=install_block,
+    )
+    requirements_text = _render_requirements(extra_pip_list)
+
+    # Read helper scripts once — we both hash them into the image tag
+    # (so edits invalidate the image cache) and write them into the
+    # build context so the Dockerfile can ``COPY`` them.
+    gateway_script_bytes = _read_gateway_script_bytes()
+    glob_helper_bytes = _read_glob_helper_bytes()
+
+    copy_files: dict[str, bytes] = {
+        "requirements.txt": requirements_text.encode("utf-8"),
+        "_mcp_gateway_app.py": gateway_script_bytes,
+        "_glob_helper.py": glob_helper_bytes,
+    }
+    tag = compute_image_tag(dockerfile_text, copy_files)
+
+    ctx_dir = Path(tempfile.mkdtemp(prefix="as-ws-build-"))
+    (ctx_dir / "Dockerfile").write_text(dockerfile_text, encoding="utf-8")
+    (ctx_dir / "requirements.txt").write_bytes(
+        copy_files["requirements.txt"],
+    )
+    (ctx_dir / "_mcp_gateway_app.py").write_bytes(gateway_script_bytes)
+    (ctx_dir / "_glob_helper.py").write_bytes(glob_helper_bytes)
+
+    return ctx_dir, tag, copy_files
diff --git a/src/agentscope/workspace/_e2b/__init__.py b/src/agentscope/workspace/_e2b/__init__.py
new file mode 100644
index 0000000..56f8f58
--- /dev/null
+++ b/src/agentscope/workspace/_e2b/__init__.py
@@ -0,0 +1,12 @@
+# -*- coding: utf-8 -*-
+"""E2B-backed workspace package.
+
+Re-exports :class:`E2BWorkspace` so callers can write
+``from agentscope.workspace._e2b import E2BWorkspace`` without having to
+poke at the underlying module layout.
+"""
+
+from ._e2b_workspace import E2BWorkspace
+from ._e2b_backend import E2BBackend
+
+__all__ = ["E2BWorkspace", "E2BBackend"]
diff --git a/src/agentscope/workspace/_e2b/_constants.py b/src/agentscope/workspace/_e2b/_constants.py
new file mode 100644
index 0000000..2513674
--- /dev/null
+++ b/src/agentscope/workspace/_e2b/_constants.py
@@ -0,0 +1,28 @@
+# -*- coding: utf-8 -*-
+"""E2B-specific constants for :class:`E2BWorkspace`.
+
+Path layout (venv, script, log, helper) is derived on the base class
+from ``_gateway_home``. This module only carries defaults that cannot
+be derived: template, timeouts, port, sandbox user, metadata key.
+"""
+
+#: Default E2B template. Matches the SDK's ``base`` template — has
+#: Ubuntu + python3 + curl out of the box.
+DEFAULT_TEMPLATE = "base"
+
+#: Default keep-alive timeout in seconds for newly-created sandboxes.
+DEFAULT_TIMEOUT = 300
+
+#: Default port the in-sandbox gateway listens on.
+DEFAULT_GATEWAY_PORT = 5600
+
+#: Sandbox-side runtime user (E2B ``base`` runs as ``user``, not root).
+SANDBOX_USER_HOME = "/home/user"
+
+#: Sandbox-side workdir and gateway home — derived once here so the
+#: E2B workspace and any hypothetical siblings share the layout.
+SANDBOX_WORKDIR = f"{SANDBOX_USER_HOME}/workspace"
+GATEWAY_HOME = f"{SANDBOX_USER_HOME}/.agentscope"
+
+#: Sandbox metadata key used to map workspace_id → sandbox_id.
+METADATA_WORKSPACE_ID_KEY = "agentscope.workspace.id"
diff --git a/src/agentscope/workspace/_e2b/_e2b_backend.py b/src/agentscope/workspace/_e2b/_e2b_backend.py
new file mode 100644
index 0000000..509c408
--- /dev/null
+++ b/src/agentscope/workspace/_e2b/_e2b_backend.py
@@ -0,0 +1,163 @@
+# -*- coding: utf-8 -*-
+"""E2B sandbox :class:`BackendBase` implementation.
+
+Wraps the E2B SDK's ``commands.run`` and ``files.*`` APIs into the
+three backend primitives (``exec_shell``, ``read_file``,
+``write_file``) so that builtin tools (Bash, Read, Write, Edit, Grep,
+Glob) can operate inside an E2B cloud sandbox transparently.  All
+derived filesystem helpers (``file_exists``, ``is_dir``, ``list_dir``,
+``stat_mtime``, ``delete_path``) are inherited from
+:class:`BackendBase`, which implements them via ``exec_shell``.
+"""
+
+from __future__ import annotations
+
+import posixpath
+import shlex
+from typing import Any
+
+from ...tool import BackendBase, ExecResult
+
+
+class E2BBackend(BackendBase):
+    """Backend that delegates to a running E2B sandbox.
+
+    Only the three abstract primitives (``exec_shell``, ``read_file``,
+    ``write_file``) are implemented here; the derived filesystem helpers
+    are inherited from :class:`BackendBase`.
+
+    Args:
+        sandbox (`Any`):
+            An ``e2b.AsyncSandbox`` object (must already be started /
+            connected).
+        workdir (`str`):
+            Default working directory for ``exec_shell`` calls inside
+            the sandbox.
+    """
+
+    def __init__(self, sandbox: Any, workdir: str) -> None:
+        """Initialize the E2B backend.
+
+        Args:
+            sandbox (`Any`):
+                A started / connected ``e2b.AsyncSandbox`` object.
+            workdir (`str`):
+                Default working directory for ``exec_shell`` calls
+                inside the sandbox.
+        """
+        self._sandbox = sandbox
+        self._workdir = workdir
+
+    # ── exec ───────────────────────────────────────────────────────
+
+    async def getcwd(self) -> str:
+        """Return the sandbox's default working directory.
+
+        Overrides the base class default (which would shell out to
+        ``pwd``) with the cached ``workdir`` supplied at construction,
+        avoiding a per-call sandbox round-trip.
+
+        Returns:
+            `str`:
+                The sandbox's default working directory.
+        """
+        return self._workdir
+
+    async def exec_shell(
+        self,
+        command: list[str],
+        *,
+        cwd: str | None = None,
+        timeout: float | None = None,
+    ) -> ExecResult:
+        """Run a program inside the sandbox via ``commands.run``.
+
+        *command* is an argv list. The E2B ``commands.run`` API takes a
+        single shell command line, so the argv is POSIX-quoted back into
+        a string before dispatch (the sandbox is always Linux). Callers
+        needing shell features pass ``["sh", "-c", line]``.
+
+        Args:
+            command (`list[str]`):
+                Executable path/name followed by its arguments.
+            cwd (`str | None`, optional):
+                Working directory inside the sandbox. When ``None`` the
+                backend's default ``workdir`` is used.
+            timeout (`float | None`, optional):
+                Maximum number of seconds to wait. When ``None`` the
+                SDK default applies.
+
+        Returns:
+            `ExecResult`:
+                The captured exit code, stdout, and stderr. A non-zero
+                command exit is reported as a normal result; transport
+                errors yield an ``exit_code`` of ``-1``.
+        """
+        from e2b import CommandExitException
+
+        command_line = " ".join(shlex.quote(arg) for arg in command)
+        kwargs: dict[str, Any] = {"cwd": cwd or self._workdir}
+        if timeout is not None:
+            kwargs["timeout"] = timeout
+        try:
+            res = await self._sandbox.commands.run(command_line, **kwargs)
+            return ExecResult(
+                exit_code=int(res.exit_code or 0),
+                stdout=(res.stdout or "").encode("utf-8"),
+                stderr=(res.stderr or "").encode("utf-8"),
+            )
+        except CommandExitException as e:
+            return ExecResult(
+                exit_code=int(e.exit_code or 1),
+                stdout=(e.stdout or "").encode("utf-8"),
+                stderr=(e.stderr or "").encode("utf-8"),
+            )
+        except Exception as e:  # noqa: BLE001
+            return ExecResult(
+                exit_code=-1,
+                stdout=b"",
+                stderr=str(e).encode("utf-8"),
+            )
+
+    # ── file I/O ───────────────────────────────────────────────────
+
+    async def read_file(self, path: str) -> bytes:
+        """Read a file from the sandbox via ``files.read``.
+
+        Args:
+            path (`str`):
+                Path to the file inside the sandbox.
+
+        Returns:
+            `bytes`:
+                The raw file contents.
+
+        Raises:
+            `FileNotFoundError`:
+                If the path does not exist inside the sandbox.
+        """
+        from e2b import FileNotFoundException
+
+        try:
+            data = await self._sandbox.files.read(path, format="bytes")
+        except FileNotFoundException as exc:
+            raise FileNotFoundError(
+                f"not found in sandbox: {path}",
+            ) from exc
+        return bytes(data)
+
+    async def write_file(self, path: str, data: bytes) -> None:
+        """Write *data* to a file inside the sandbox.
+
+        Creates parent directories via ``exec_shell`` first.
+
+        Args:
+            path (`str`):
+                Destination path inside the sandbox.
+            data (`bytes`):
+                The raw bytes to write.
+        """
+        parent = posixpath.dirname(path)
+        if parent:
+            await self.exec_shell(["mkdir", "-p", parent])
+        await self._sandbox.files.write(path, data)
diff --git a/src/agentscope/workspace/_e2b/_e2b_workspace.py b/src/agentscope/workspace/_e2b/_e2b_workspace.py
new file mode 100644
index 0000000..f08dcc6
--- /dev/null
+++ b/src/agentscope/workspace/_e2b/_e2b_workspace.py
@@ -0,0 +1,373 @@
+# -*- coding: utf-8 -*-
+"""E2BWorkspace — sandboxed workspace backed by an E2B cloud sandbox.
+
+Architecture
+------------
+
+Mirrors :class:`agentscope.workspace.DockerWorkspace` but swaps the
+Docker engine for the E2B SDK (``e2b.AsyncSandbox``):
+
+* **Lifecycle.** ``initialize()`` looks up an existing sandbox by
+  metadata and either resumes it (``connect(sandbox_id=...)``
+  auto-resumes paused sandboxes) or creates a fresh one and runs the
+  bootstrap shell sequence. ``close()`` calls ``sandbox.pause()`` so
+  the sandbox filesystem (skills, ``.mcp``, sessions, data) survives
+  for the next ``initialize()``. There is no ``kill()`` path in this
+  iteration.
+* **Persistence.** Sandbox filesystem state is the persistence layer —
+  there is no host-side ``workdir`` parameter. Pausing keeps the disk;
+  resuming brings it back wholesale.
+* **Bootstrap.** First-time provisioning installs uv + a gateway venv
+  + agentscope (``--no-deps``) and uploads the gateway script. The
+  probe + install loop lives on :class:`SandboxedWorkspaceBase`; this
+  subclass only supplies the sandbox-specific shell commands via
+  :meth:`_bootstrap_commands`. Bootstrap runs at most once per sandbox
+  lifetime (the presence of the gateway script on disk is the marker).
+* **MCP gateway.** Identical to Docker: a FastAPI process inside the
+  sandbox. All host-side calls drive the gateway through
+  :class:`GatewayClient`, which runs an in-sandbox ``python3 -c`` shim
+  via :meth:`E2BBackend.exec_shell` — no host→sandbox network
+  reachability is required.
+* **Service-layer index.** The host stores only ``workspace_id``;
+  the sandbox carries ``METADATA_WORKSPACE_ID_KEY = workspace_id`` in
+  its E2B metadata. Manager code calls ``AsyncSandbox.list(query=...)``
+  with that filter to find the sandbox on cache miss.
+
+Configuration is per-instance: every workspace owns one sandbox. The
+manager handles cache, TTL eviction and metadata-based reattachment.
+"""
+
+import asyncio
+import shlex
+from typing import Any
+
+from ..._logging import logger
+from ...mcp import MCPClient
+from .._sandboxed_base import SandboxedWorkspaceBase
+from .._utils import _GATEWAY_BASE_REQUIREMENTS
+from ._constants import (
+    DEFAULT_GATEWAY_PORT,
+    DEFAULT_TEMPLATE,
+    DEFAULT_TIMEOUT,
+    GATEWAY_HOME,
+    METADATA_WORKSPACE_ID_KEY,
+    SANDBOX_WORKDIR,
+)
+from ._e2b_backend import E2BBackend
+
+_DEFAULT_INSTRUCTIONS = """<workspace>
+You have an E2B-based cloud workspace. All tool calls execute **inside
+the sandbox** at ``{workdir}``.
+
+Layout:
+
+```
+{workdir}
+├── data/        # offloaded multimodal files
+├── skills/      # reusable skills
+└── sessions/    # session context and tool results
+```
+</workspace>"""
+
+
+# ── the workspace ──────────────────────────────────────────────────
+
+
+class E2BWorkspace(SandboxedWorkspaceBase):
+    """Workspace backed by an E2B cloud sandbox.
+
+    ``default_mcps`` and ``skill_paths`` are seed-time inputs and are
+    not retained as instance state past :meth:`initialize`.
+    """
+
+    _gateway_home = GATEWAY_HOME
+    # E2B ``base`` template already ships Python + curl, so every
+    # bootstrap step is expected to complete inside 10 minutes even on
+    # the slowest CI runners.
+    _bootstrap_cmd_timeout = 600.0
+
+    def __init__(
+        self,
+        *,
+        workspace_id: str | None = None,
+        template: str = DEFAULT_TEMPLATE,
+        api_key: str = "",
+        domain: str = "",
+        timeout_seconds: int = DEFAULT_TIMEOUT,
+        gateway_port: int = DEFAULT_GATEWAY_PORT,
+        env: dict[str, str] | None = None,
+        sandbox_metadata: dict[str, str] | None = None,
+        extra_pip: list[str] | None = None,
+        instructions: str = _DEFAULT_INSTRUCTIONS,
+        default_mcps: list[MCPClient] | None = None,
+        skill_paths: list[str] | None = None,
+    ) -> None:
+        """Construct an :class:`E2BWorkspace`.
+
+        The sandbox is *not* started here — call :meth:`initialize`
+        (or use the workspace as an ``async`` context manager).
+
+        Args:
+            workspace_id (`str | None`, optional):
+                Stable identifier; also stored in sandbox metadata for
+                reattachment.
+            template (`str`, defaults to `DEFAULT_TEMPLATE`):
+                E2B template id.
+            api_key (`str`, defaults to `""`):
+                E2B API key (``""`` falls back to ``E2B_API_KEY``).
+            domain (`str`, defaults to `""`):
+                Optional custom E2B domain.
+            timeout_seconds (`int`, defaults to `DEFAULT_TIMEOUT`):
+                Sandbox keep-alive timeout.
+            gateway_port (`int`, defaults to `DEFAULT_GATEWAY_PORT`):
+                TCP port the in-sandbox gateway listens on.
+            env (`dict[str, str] | None`, optional):
+                Environment variables baked into the sandbox.
+            sandbox_metadata (`dict[str, str] | None`, optional):
+                Extra metadata merged with the workspace-id tag.
+            extra_pip (`list[str] | None`, optional):
+                Extra Python packages installed into the gateway venv
+                during bootstrap.
+            instructions (`str`, defaults to `_DEFAULT_INSTRUCTIONS`):
+                System-prompt fragment template (supports ``{workdir}``).
+            default_mcps (`list[MCPClient] | None`, optional):
+                MCPs registered on first init when no persisted
+                ``.mcp`` exists.
+            skill_paths (`list[str] | None`, optional):
+                Local skill dirs seeded into ``skills/`` on first init.
+        """
+        super().__init__(
+            workspace_id=workspace_id,
+            default_mcps=default_mcps,
+            skill_paths=skill_paths,
+        )
+
+        # ── serializable config ─────────────────────────────────
+        self.workdir = SANDBOX_WORKDIR
+        self.template = template
+        self.api_key = api_key
+        self.domain = domain
+        self.timeout_seconds = timeout_seconds
+        self.gateway_port = gateway_port
+        self.env: dict[str, str] = dict(env or {})
+        self.sandbox_metadata: dict[str, str] = dict(sandbox_metadata or {})
+        self.extra_pip: list[str] = list(extra_pip or [])
+        self.instructions = instructions
+
+        # ── runtime state (E2B-only) ────────────────────────────
+        self._sandbox: Any = None  # e2b.AsyncSandbox
+        self._backend: E2BBackend | None = None
+
+    # ── lifecycle hooks ─────────────────────────────────────────
+
+    @property
+    def sandbox_id(self) -> str | None:
+        """E2B sandbox id, or ``None`` if not started."""
+        return self._sandbox.sandbox_id if self._sandbox else None
+
+    async def _provision_backend(self) -> None:
+        """Reattach or create the sandbox and bind the backend.
+
+        First-time bootstrap (uv → gateway venv → agentscope → gateway
+        script upload) is driven by
+        :meth:`SandboxedWorkspaceBase._ensure_bootstrapped` once
+        ``initialize`` has bound the backend; every step is idempotent
+        so an interrupted bootstrap re-runs cleanly.
+        """
+        await self._attach_or_create_sandbox()
+        self._backend = E2BBackend(self._sandbox, workdir=SANDBOX_WORKDIR)
+
+    async def _teardown_backend(self) -> None:
+        """Pause the sandbox (keep filesystem) and drop the handle.
+
+        ``sandbox.pause()`` — not ``kill()`` — so the next
+        :meth:`initialize` can reattach via metadata lookup and
+        auto-resume. Errors are swallowed.
+        """
+        if self._sandbox is not None:
+            try:
+                await self._sandbox.pause()
+            except Exception as e:
+                logger.warning("E2BWorkspace: pause failed: %s", e)
+            self._sandbox = None
+
+    # ── instructions ────────────────────────────────────────────
+
+    async def get_instructions(self) -> str:
+        """Return the system-prompt fragment for this workspace.
+
+        Substitutes ``{workdir}`` in the configured template with
+        the sandbox-side path (``/home/user/workspace``). The agent
+        always sees sandbox-internal paths.
+        """
+        return self.instructions.format(workdir=SANDBOX_WORKDIR)
+
+    # ── internals: sandbox attach / create ─────────────────────
+
+    async def _attach_or_create_sandbox(self) -> None:
+        """Reattach to an existing sandbox by metadata, or create one.
+
+        Resolution rule: a single sandbox is expected per
+        ``workspace_id``. If multiple are returned (e.g. a leaked
+        running + paused pair after an unclean shutdown) we attach to
+        the newest by ``started_at`` and log a warning — manual
+        cleanup is left to the operator.
+
+        Always blocks until the sandbox's envd answers
+        :meth:`AsyncSandbox.is_running` so the caller can issue
+        ``commands`` / ``files`` calls without hitting transient
+        "not yet routable" errors — typical on a paused sandbox that
+        has just been auto-resumed via ``connect``.
+        """
+        from e2b import AsyncSandbox
+
+        existing = await self._find_existing_sandbox()
+
+        api_opts = self._api_opts()
+        if existing is not None:
+            self._sandbox = await AsyncSandbox.connect(
+                sandbox_id=existing.sandbox_id,
+                timeout=self.timeout_seconds,
+                **api_opts,
+            )
+        else:
+            merged_metadata = {
+                METADATA_WORKSPACE_ID_KEY: self.workspace_id,
+                **self.sandbox_metadata,
+            }
+            create_kwargs: dict[str, Any] = {
+                "template": self.template,
+                "timeout": self.timeout_seconds,
+                "metadata": merged_metadata,
+                **api_opts,
+            }
+            if self.env:
+                create_kwargs["envs"] = self.env
+
+            self._sandbox = await AsyncSandbox.create(**create_kwargs)
+
+        await self._wait_until_running()
+
+    async def _wait_until_running(self, timeout: float = 30.0) -> None:
+        """Poll ``self._sandbox.is_running()`` until it answers ``True``.
+
+        ``AsyncSandbox.create`` / ``AsyncSandbox.connect`` can return
+        before the in-sandbox envd is routable. Subsequent
+        ``commands.run`` / ``files.exists`` calls against an
+        unrouted envd surface as transient SDK errors. We poll envd's
+        own ``/health`` (which is what :meth:`AsyncSandbox.is_running`
+        wraps — 502 → ``False``, 200 → ``True``) until it goes green.
+
+        Args:
+            timeout (`float`, defaults to `30.0`):
+                Hard ceiling in seconds. Raises :class:`RuntimeError`
+                if envd is still not routable after this long.
+        """
+        deadline = asyncio.get_event_loop().time() + timeout
+        delay = 0.1
+        while asyncio.get_event_loop().time() < deadline:
+            try:
+                if await self._sandbox.is_running():
+                    return
+            except Exception as e:  # noqa: BLE001
+                # SDK can raise on transient network / proxy errors
+                # while the sandbox is still provisioning. Treat as
+                # "not yet" and keep polling.
+                logger.debug(
+                    "E2BWorkspace: is_running probe error (will retry): %s",
+                    e,
+                )
+            await asyncio.sleep(delay)
+            delay = min(delay * 1.5, 1.0)
+        raise RuntimeError(
+            f"E2B sandbox did not become ready within {timeout}s "
+            f"(workspace_id={self.workspace_id!r})",
+        )
+
+    async def _find_existing_sandbox(self) -> Any:
+        """List sandboxes filtered by ``workspace_id`` metadata.
+
+        Returns the most recent :class:`SandboxInfo` (paused or
+        running) or ``None`` if no match exists.
+        """
+        from e2b import AsyncSandbox
+        from e2b.api.client.models.sandbox_state import SandboxState
+        from e2b.sandbox.sandbox_api import SandboxQuery
+
+        query = SandboxQuery(
+            metadata={METADATA_WORKSPACE_ID_KEY: self.workspace_id},
+            state=[SandboxState.PAUSED, SandboxState.RUNNING],
+        )
+
+        candidates: list[Any] = []
+        paginator = AsyncSandbox.list(query=query, **self._api_opts())
+        while paginator.has_next:
+            try:
+                page = await paginator.next_items()
+            except Exception as e:
+                logger.warning(
+                    "E2BWorkspace: list sandboxes failed: %s",
+                    e,
+                )
+                break
+            candidates.extend(page)
+
+        if not candidates:
+            return None
+        if len(candidates) > 1:
+            logger.warning(
+                "E2BWorkspace: %d sandboxes match workspace_id=%r; "
+                "attaching to most recent",
+                len(candidates),
+                self.workspace_id,
+            )
+        candidates.sort(key=lambda s: s.started_at, reverse=True)
+        return candidates[0]
+
+    def _api_opts(self) -> dict[str, Any]:
+        """Common ``api_key`` / ``domain`` opts forwarded to E2B SDK calls."""
+        opts: dict[str, Any] = {}
+        if self.api_key:
+            opts["api_key"] = self.api_key
+        if self.domain:
+            opts["domain"] = self.domain
+        return opts
+
+    # ── internals: bootstrap ────────────────────────────────────
+
+    def _bootstrap_commands(self) -> list[str]:
+        """Shell commands that provision this E2B sandbox once.
+
+        Only runs when the gateway script is missing (fresh sandbox or
+        a prior bootstrap that was interrupted). Every step is
+        idempotent so a resumed sandbox can re-run cleanly.
+
+        ``--no-deps`` on agentscope is mandatory: the gateway only
+        imports :class:`agentscope.mcp.MCPClient` whose transitive
+        needs (``mcp / pydantic / httpx``) are already installed via
+        the gateway base requirements. Pulling the full dep tree
+        drags in heavy / Rust-built packages the E2B image cannot
+        compile.
+        """
+        pip_pkgs = list(_GATEWAY_BASE_REQUIREMENTS) + list(self.extra_pip)
+        # Quote every requirement string so entries with spaces or
+        # shell metacharacters cannot break the ``sh -c`` command or
+        # become a command-injection vector inside the sandbox.
+        pip_args = " ".join(shlex.quote(p) for p in pip_pkgs)
+
+        return [
+            # 1. System deps + uv installer, both via sudo so uv lands
+            # at /usr/local/bin (on PATH — no absolute-path plumbing
+            # needed downstream).
+            "sudo apt-get update -qq "
+            "&& sudo apt-get install -y --no-install-recommends ripgrep "
+            "&& sudo rm -rf /var/lib/apt/lists/*",
+            "curl -LsSf https://astral.sh/uv/install.sh "
+            "| sudo env UV_INSTALL_DIR=/usr/local/bin "
+            "INSTALLER_NO_MODIFY_PATH=1 sh",
+            # 2. Gateway venv + base requirements + agentscope.
+            f"uv venv {self._gateway_venv}",
+            f"uv pip install --python {self._gateway_python} {pip_args}",
+            f"uv pip install --python {self._gateway_python} "
+            f"--no-deps 'agentscope'",
+        ]
diff --git a/src/agentscope/workspace/_gateway_client.py b/src/agentscope/workspace/_gateway_client.py
new file mode 100644
index 0000000..6749c6f
--- /dev/null
+++ b/src/agentscope/workspace/_gateway_client.py
@@ -0,0 +1,667 @@
+# -*- coding: utf-8 -*-
+"""Host-side client for the in-sandbox MCP gateway, driven through
+``backend.exec_shell``.
+
+Three classes:
+
+* :class:`GatewayClient` — workspace-side facade over ``/health`` and
+  ``/mcps``. Used by the sandboxed workspaces for top-level operations.
+* :class:`GatewayMCPClient` — an :class:`MCPClient` subclass whose
+  protocol behaviour is replaced by gateway-relayed calls. Local
+  stdio/HTTP machinery is bypassed; ``model_post_init`` is a no-op;
+  ``connect`` / ``close`` / ``list_raw_tools`` / ``get_tool`` all
+  round-trip through ``/mcps``.
+* :class:`GatewayMCPTool` — :class:`ToolBase` whose ``__call__``
+  invokes the upstream tool via ``POST /mcps/{name}/tools/{tool}``.
+
+Every request runs inside the sandbox: the host writes an optional
+body to a sandbox tempfile, spawns a small Python shim via
+:meth:`BackendBase.exec_shell` (see :mod:`._gateway_shim`), and parses
+the JSON envelope the shim prints on stdout. No host→sandbox network
+reachability is required — the gateway only binds sandbox loopback.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import uuid
+from typing import TYPE_CHECKING, Any
+
+import mcp.types
+from pydantic import PrivateAttr
+
+from .._logging import logger
+from ..mcp import MCPClient
+from ..message import ToolResultState
+from ..permission import (
+    PermissionBehavior,
+    PermissionDecision,
+)
+from ..tool import ToolBase, ToolChunk
+from ._gateway_shim import (
+    BODY_INLINE_LIMIT,
+    SANDBOX_TMP_DIR,
+    SHIM_SCRIPT,
+)
+
+if TYPE_CHECKING:
+    from ..tool import BackendBase, ExecResult
+
+
+# ── tool ───────────────────────────────────────────────────────────
+
+
+class GatewayMCPTool(ToolBase):
+    """An MCP tool whose ``__call__`` is one ``exec_shell``-driven
+    request to the gateway.
+
+    Mirrors :class:`agentscope.tool.MCPTool` field-by-field so the
+    toolkit treats it identically (same ``name`` format, same
+    permission policy) — only the call path changes.
+    """
+
+    is_mcp: bool = True
+    is_state_injected: bool = False
+
+    def __init__(
+        self,
+        mcp_name: str,
+        tool: mcp.types.Tool,
+        gateway: "GatewayClient",
+    ) -> None:
+        """Build a gateway-backed MCP tool.
+
+        Mirrors the field surface of :class:`agentscope.tool.MCPTool`
+        so the toolkit cannot tell the difference.
+
+        Args:
+            mcp_name (`str`):
+                Upstream MCP server name; drives the visible
+                ``mcp__{mcp}__{tool}`` name and the URL path.
+            tool (`mcp.types.Tool`):
+                Raw upstream tool descriptor as returned by the gateway.
+                ``inputSchema`` is forwarded verbatim;
+                ``annotations.readOnlyHint`` drives the permission
+                policy.
+            gateway (`GatewayClient`):
+                Facade dispatching every call through
+                :meth:`GatewayClient.exec_request`.
+        """
+        self.mcp_name = mcp_name
+        self.name = f"mcp__{mcp_name}__{tool.name}"
+        self.description = tool.description or ""
+
+        schema = dict(tool.inputSchema) if tool.inputSchema else {}
+        schema.setdefault("type", "object")
+        schema.setdefault("properties", {})
+        schema.setdefault("required", [])
+        self.input_schema = schema
+
+        self.is_concurrency_safe = False
+        self.is_external_tool = False
+
+        self.is_read_only = False
+        if tool.annotations and hasattr(tool.annotations, "readOnlyHint"):
+            self.is_read_only = tool.annotations.readOnlyHint or False
+
+        self._tool = tool
+        self._gateway = gateway
+
+    async def check_permissions(
+        self,
+        *_args: Any,
+        **_kwargs: Any,
+    ) -> PermissionDecision:
+        """Read-only tools auto-allow; everything else defers via
+        ``ASK``. Mirrors :meth:`MCPTool.check_permissions`.
+        """
+        if self.is_read_only:
+            return PermissionDecision(
+                behavior=PermissionBehavior.ALLOW,
+                message="This is a read-only MCP tool. Allowing execution.",
+            )
+        return PermissionDecision(
+            behavior=PermissionBehavior.ASK,
+            message="MCP tools must be explicitly allowed by the user.",
+        )
+
+    async def __call__(self, **kwargs: Any) -> ToolChunk:
+        """Relay ``POST /mcps/{mcp}/tools/{tool}`` to the gateway.
+
+        4xx / 5xx responses come back as ``ToolChunk(state=ERROR)`` so
+        the agent loop can reason about failure. Raises
+        :class:`RuntimeError` only if the gateway returns 2xx with no
+        ``chunk`` payload (protocol violation).
+        """
+        status, body = await self._gateway.exec_request(
+            "POST",
+            f"/mcps/{self.mcp_name}/tools/{self._tool.name}",
+            body={"arguments": kwargs},
+        )
+        if status >= 400:
+            return ToolChunk(
+                content=[{"type": "text", "text": _safe_detail(status, body)}],
+                state=ToolResultState.ERROR,
+            )
+        payload = json.loads(body)
+        chunk_dict = payload.get("chunk")
+        if chunk_dict is None:
+            raise RuntimeError(
+                f"gateway returned no chunk for {self.name!r}",
+            )
+        return ToolChunk.model_validate(chunk_dict)
+
+
+# ── pseudo MCP client ──────────────────────────────────────────────
+
+
+class GatewayMCPClient(MCPClient):
+    """An :class:`MCPClient` whose protocol logic is replaced by
+    gateway-relayed calls.
+
+    Constructed from the dict returned by ``GET /mcps`` (or freshly
+    from user input via :meth:`GatewayClient.make_client`). The local
+    MCP machinery is short-circuited entirely:
+
+    * ``model_post_init`` does nothing (parent's ``_initialize_client``
+      is never called — no stdio context manager is built).
+    * ``connect`` registers the MCP on the gateway via ``POST /mcps``.
+    * ``close`` deregisters via ``DELETE /mcps/{name}``.
+    * ``list_raw_tools`` / ``get_tool`` fetch and wrap upstream tools.
+    """
+
+    _gateway: "GatewayClient | None" = PrivateAttr(default=None)
+
+    def model_post_init(self, __context: Any) -> None:
+        """No-op — the parent builds local stdio/HTTP transport, which
+        the gateway-relayed client does not need.
+        """
+        return
+
+    # ── lifecycle ─────────────────────────────────────────────────
+
+    def attach(
+        self,
+        gateway: "GatewayClient",
+        *,
+        connected: bool = False,
+    ) -> None:
+        """Wire this client to a gateway facade.
+
+        Instances come out of ``model_validate(spec)`` with the public
+        field surface set but no transport wiring. ``attach`` injects
+        it so :meth:`connect` / :meth:`close` / :meth:`list_raw_tools`
+        can talk to the gateway.
+
+        Args:
+            gateway (`GatewayClient`):
+                Facade dispatching calls through
+                :meth:`GatewayClient.exec_request`.
+            connected (`bool`, defaults to `False`):
+                When ``True``, mark this client as already connected
+                (used by :meth:`GatewayClient.list_mcps` for entries
+                the gateway is already serving).
+        """
+        self._gateway = gateway
+        if connected:
+            self._is_connected = True
+
+    async def connect(self) -> None:
+        """Register this MCP on the gateway via ``POST /mcps``.
+
+        All MCPs (stateless and stateful) must be registered so that
+        ``/mcps/{name}/tools/{tool}`` can locate the client.
+
+        Raises:
+            `RuntimeError`:
+                Already connected, gateway unreachable, or gateway
+                returned 4xx/5xx.
+        """
+        if self._is_connected:
+            raise RuntimeError(
+                f"MCP {self.name!r} is already connected. "
+                "Call close() before reconnecting.",
+            )
+        assert self._gateway is not None
+        body = self.model_dump(mode="json")
+        status, resp_body = await self._gateway.exec_request(
+            "POST",
+            "/mcps",
+            body=body,
+        )
+        if status >= 400:
+            raise RuntimeError(
+                f"gateway failed to add MCP {self.name!r}: "
+                f"{_safe_detail(status, resp_body)}",
+            )
+        self._is_connected = True
+
+    async def close(self, ignore_errors: bool = True) -> None:
+        """Deregister this MCP via ``DELETE /mcps/{name}``.
+
+        Args:
+            ignore_errors (`bool`, defaults to `True`):
+                Suppress "not connected" precondition and gateway
+                4xx/5xx. Mirrors :meth:`MCPClient.close`.
+        """
+        if not self._is_connected:
+            if ignore_errors:
+                return
+            raise RuntimeError(
+                f"MCP {self.name!r} is not connected. Call connect() first.",
+            )
+        assert self._gateway is not None
+        try:
+            status, resp_body = await self._gateway.exec_request(
+                "DELETE",
+                f"/mcps/{self.name}",
+            )
+            if status >= 400 and not ignore_errors:
+                raise RuntimeError(
+                    f"gateway failed to remove MCP {self.name!r}: "
+                    f"{_safe_detail(status, resp_body)}",
+                )
+        except Exception:
+            if not ignore_errors:
+                raise
+        self._is_connected = False
+
+    # ── tool discovery ────────────────────────────────────────────
+
+    async def list_raw_tools(self) -> list[mcp.types.Tool]:
+        """Fetch upstream tools via ``GET /mcps/{name}/tools``.
+
+        Returns raw :class:`mcp.types.Tool` descriptors (upstream names,
+        no ``mcp__`` prefix) so the inherited :meth:`get_tool` can
+        re-wrap them like a local :class:`MCPClient`. The unfiltered
+        list is cached; the returned list has ``enable_tools`` /
+        ``disable_tools`` applied.
+
+        Raises:
+            `RuntimeError`:
+                Gateway returned non-2xx.
+        """
+        assert self._gateway is not None
+        status, body = await self._gateway.exec_request(
+            "GET",
+            f"/mcps/{self.name}/tools",
+        )
+        if status >= 400:
+            raise RuntimeError(
+                f"gateway failed to list tools for MCP {self.name!r}: "
+                f"{_safe_detail(status, body)}",
+            )
+        data = json.loads(body)
+
+        raw_tools = [mcp.types.Tool.model_validate(d) for d in data]
+        self._cached_tools = raw_tools
+
+        # Gateway returns the unfiltered upstream view; honour the same
+        # enable/disable filtering ``MCPClient`` applies locally.
+        if self.enable_tools is not None:
+            raw_tools = [t for t in raw_tools if t.name in self.enable_tools]
+        if self.disable_tools is not None:
+            raw_tools = [
+                t for t in raw_tools if t.name not in self.disable_tools
+            ]
+        return raw_tools
+
+    async def get_tool(  # type: ignore[override]
+        self,
+        name: str,
+    ) -> GatewayMCPTool:
+        """Look up a single tool by upstream name and wrap it.
+
+        Falls back to :meth:`list_raw_tools` on cache miss, then
+        searches the unfiltered cache so tools that ``enable_tools`` /
+        ``disable_tools`` would have hidden are still resolvable —
+        matching :meth:`MCPClient.get_tool`.
+
+        Raises:
+            `ValueError`:
+                No tool with that upstream name exists on the gateway.
+        """
+        if self._cached_tools is None:
+            await self.list_raw_tools()
+        for raw in self._cached_tools or []:
+            if raw.name == name:
+                return self._wrap_tool(raw)
+        raise ValueError(
+            f"Tool {name!r} not found in MCP {self.name!r}.",
+        )
+
+    # ── helpers ───────────────────────────────────────────────────
+
+    def _wrap_tool(self, tool: mcp.types.Tool) -> GatewayMCPTool:
+        """Build a :class:`GatewayMCPTool` bound to this client's
+        gateway facade.
+        """
+        assert self._gateway is not None
+        return GatewayMCPTool(
+            mcp_name=self.name,
+            tool=tool,
+            gateway=self._gateway,
+        )
+
+
+# ── workspace-side facade ──────────────────────────────────────────
+
+
+class GatewayClient:
+    """Workspace-side facade over the in-sandbox MCP gateway.
+
+    Every method dispatches through :meth:`exec_request`, which in
+    turn drives :meth:`BackendBase.exec_shell` on the workspace's
+    backend so the network call always happens **inside** the sandbox.
+    No host port mapping or HTTPS proxy is required.
+    """
+
+    def __init__(
+        self,
+        backend: "BackendBase",
+        gateway_port: int,
+        *,
+        timeout: float | None = None,
+        inline_limit: int = BODY_INLINE_LIMIT,
+        tmp_dir: str = SANDBOX_TMP_DIR,
+        gateway_log_path: str | None = None,
+    ) -> None:
+        """Build a workspace-side gateway facade.
+
+        Args:
+            backend (`BackendBase`):
+                Workspace backend; every request runs as
+                ``backend.exec_shell([...])`` inside the sandbox.
+            gateway_port (`int`):
+                TCP port the gateway listens on inside the sandbox.
+                The shim dials ``http://127.0.0.1:<gateway_port>``.
+            timeout (`float | None`, defaults to `None`):
+                Per-request timeout forwarded to
+                :meth:`BackendBase.exec_shell`; ``None`` waits
+                indefinitely.
+            inline_limit (`int`, defaults to `BODY_INLINE_LIMIT`):
+                Response bodies above this size spill through a sandbox
+                tempfile rather than base64-inline through stdout.
+            tmp_dir (`str`, defaults to `SANDBOX_TMP_DIR`):
+                Sandbox directory for request/response tempfiles. Must
+                be writable by the gateway process.
+            gateway_log_path (`str | None`, defaults to `None`):
+                Sandbox-side path of the gateway's stdout/stderr log
+                file. When set, :meth:`exec_request` failures trigger
+                a ``/health`` probe and — if the gateway is
+                unreachable — a tail of this log is emitted at
+                ``ERROR`` level to help diagnose crashes.
+        """
+        self.backend = backend
+        self.gateway_port = gateway_port
+        self.timeout = timeout
+        self.inline_limit = inline_limit
+        self.tmp_dir = tmp_dir
+        self.gateway_log_path = gateway_log_path
+        # Health-probe timeout is kept short so the diagnostic path adds
+        # little latency to the failing request. It only runs on the
+        # error path, never on the hot path.
+        self._health_probe_timeout: float = 5.0
+        # Number of bytes of the gateway log to tail into the error
+        # log on unreachable-gateway diagnosis.
+        self._log_tail_bytes: int = 4000
+
+    async def health(self) -> bool:
+        """Probe ``/health``. ``True`` iff the gateway answered 200;
+        any other outcome (shim transport failure, non-200) → ``False``.
+        Callers retry until this flips.
+
+        The ``/health`` path is treated specially by
+        :meth:`exec_request` — it never triggers the failure
+        diagnostic, so a dead gateway does not recursively probe
+        itself.
+        """
+        try:
+            status, _ = await self.exec_request("GET", "/health")
+        except Exception:
+            return False
+        return status == 200
+
+    async def list_mcps(self) -> list[GatewayMCPClient]:
+        """Fetch every MCP the gateway is currently serving.
+
+        Returned clients are marked already-connected (via
+        :meth:`GatewayMCPClient.attach`) — the gateway is already
+        maintaining their upstream sessions.
+
+        Raises:
+            `RuntimeError`:
+                Gateway returned non-2xx.
+        """
+        status, body = await self.exec_request("GET", "/mcps")
+        if status >= 400:
+            raise RuntimeError(
+                f"gateway failed to list MCPs: {_safe_detail(status, body)}",
+            )
+        specs = json.loads(body)
+        return [self.make_client(spec, connected=True) for spec in specs]
+
+    def make_client(
+        self,
+        spec: dict[str, Any],
+        *,
+        connected: bool = False,
+    ) -> GatewayMCPClient:
+        """Build a :class:`GatewayMCPClient` wired to this gateway.
+
+        Args:
+            spec (`dict[str, Any]`):
+                ``MCPClient.model_dump(mode="json")`` payload — either
+                from ``GET /mcps`` or from user input via ``add_mcp``.
+            connected (`bool`, defaults to `False`):
+                Mark the client as already-connected. Set by
+                :meth:`list_mcps`; leave ``False`` when the caller will
+                ``await client.connect()`` itself.
+        """
+        client = GatewayMCPClient.model_validate(spec)
+        client.attach(self, connected=connected)
+        return client
+
+    async def aclose(self) -> None:
+        """No-op kept for API parity — the transport holds no host-side
+        resources, but callers keep their shutdown idiom.
+        """
+        return
+
+    # ── transport ─────────────────────────────────────────────────
+
+    async def exec_request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Any = None,
+    ) -> tuple[int, bytes]:
+        """Relay one HTTP request through the sandbox.
+
+        Writes ``body`` (if any) to a sandbox tempfile, runs
+        ``python3 -c <SHIM_SCRIPT> ...`` inside the sandbox via
+        :meth:`BackendBase.exec_shell`, and parses the JSON envelope
+        the shim prints on stdout. Inline bodies are base64-decoded;
+        oversized bodies are pulled back through ``body_file``. Request
+        and response tempfiles are best-effort cleaned up.
+
+        On any failure — shim non-zero exit, non-JSON stdout, or
+        ``status == -1`` transport error — a self-diagnostic step
+        probes ``/health`` and, if the gateway is unreachable, tails
+        :attr:`gateway_log_path` at ``ERROR`` level so the real crash
+        cause reaches the host log stream. The original exception is
+        always re-raised so the caller's error contract is unchanged.
+        The ``/health`` path itself skips diagnosis to avoid recursing
+        on a dead gateway.
+
+        Args:
+            method (`str`):
+                HTTP verb (``GET`` / ``POST`` / ``DELETE``).
+            path (`str`):
+                Path-only URL, e.g. ``/mcps/<name>/tools/<tool>``.
+            body (`Any`, optional):
+                JSON-serializable request body; ``None`` for no body.
+
+        Returns:
+            `tuple[int, bytes]`:
+                Status code + raw response bytes (callers decode).
+
+        Raises:
+            `RuntimeError`:
+                Shim crash (non-zero exit / non-JSON stdout) or
+                transport failure (``status == -1``).
+        """
+        body_file = ""
+        wrote_body_file: str | None = None
+        if body is not None:
+            body_file = f"{self.tmp_dir}/{uuid.uuid4().hex}.json"
+            wrote_body_file = body_file
+            await self.backend.write_file(
+                body_file,
+                json.dumps(body, ensure_ascii=False).encode("utf-8"),
+            )
+
+        try:
+            try:
+                result: "ExecResult" = await self.backend.exec_shell(
+                    [
+                        "python3",
+                        "-c",
+                        SHIM_SCRIPT,
+                        method,
+                        f"http://127.0.0.1:{self.gateway_port}{path}",
+                        body_file,
+                        str(self.inline_limit),
+                        self.tmp_dir,
+                    ],
+                    timeout=self.timeout,
+                )
+            finally:
+                if wrote_body_file is not None:
+                    try:
+                        await self.backend.delete_path(wrote_body_file)
+                    except Exception:
+                        pass
+
+            if result.exit_code != 0:
+                raise RuntimeError(
+                    f"gateway shim exited with {result.exit_code}: "
+                    f"{result.stderr.decode(errors='replace')[:500]}",
+                )
+
+            try:
+                env = json.loads(result.stdout)
+            except Exception as e:
+                raise RuntimeError(
+                    "gateway shim produced non-JSON stdout: "
+                    f"{result.stdout[:200]!r}",
+                ) from e
+
+            status = int(env["status"])
+            if status == -1:
+                raise RuntimeError(
+                    "gateway request failed: "
+                    f"{env.get('error', 'unknown error')}",
+                )
+
+            if "body_file" in env:
+                spilled = env["body_file"]
+                body_bytes = await self.backend.read_file(spilled)
+                try:
+                    await self.backend.delete_path(spilled)
+                except Exception:
+                    pass
+            else:
+                body_bytes = base64.b64decode(env.get("body", ""))
+
+            return status, body_bytes
+        except Exception as exc:
+            # ``/health`` never triggers diagnosis — otherwise a dead
+            # gateway would recursively probe itself.
+            if path != "/health":
+                await self._diagnose_failure(method, path, exc)
+            raise
+
+    async def _diagnose_failure(
+        self,
+        method: str,
+        path: str,
+        exc: BaseException,
+    ) -> None:
+        """Best-effort post-failure diagnostic invoked by
+        :meth:`exec_request` on any request failure.
+
+        Probes ``/health`` (via :meth:`health`, which short-circuits
+        the diagnostic path); if the gateway does not answer, emits
+        the tail of :attr:`gateway_log_path` at ``ERROR`` level so the
+        real crash cause reaches the host log stream. Every step is
+        guarded — diagnosis must never raise, so the caller's original
+        exception is always the one that surfaces.
+
+        Args:
+            method (`str`):
+                HTTP verb of the failed request (for log context).
+            path (`str`):
+                Path of the failed request (for log context).
+            exc (`BaseException`):
+                Original exception raised by the shim call (for log
+                context; not re-raised here).
+        """
+        try:
+            healthy = await self.health()
+        except Exception:  # pragma: no cover — defensive
+            healthy = False
+
+        if healthy:
+            # Gateway is up — the failure came from the request itself
+            # (bad payload, upstream MCP error, etc.). Original error
+            # is enough context.
+            return
+
+        logger.error(
+            "Gateway unreachable during %s %s: %s. Probing /health failed. "
+            "Attempting to tail gateway log at %r ...",
+            method,
+            path,
+            exc,
+            self.gateway_log_path,
+        )
+
+        if self.gateway_log_path is None:
+            return
+
+        try:
+            log_bytes = await self.backend.read_file(self.gateway_log_path)
+        except Exception as read_exc:  # noqa: BLE001
+            logger.error(
+                "Failed to read gateway log at %r: %s",
+                self.gateway_log_path,
+                read_exc,
+            )
+            return
+
+        tail = log_bytes[-self._log_tail_bytes :].decode(errors="replace")
+        logger.error(
+            "Gateway log tail (last %d bytes of %r):\n%s",
+            len(tail),
+            self.gateway_log_path,
+            tail,
+        )
+
+
+# ── module-private utilities ───────────────────────────────────────
+
+
+def _safe_detail(status: int, body: bytes) -> str:
+    """Best-effort ``HTTP <status>: <detail>`` string from a gateway
+    error response — tolerates non-JSON, missing ``detail``, etc.
+    """
+    try:
+        data = json.loads(body)
+    except Exception:
+        return f"HTTP {status}: {body[:200].decode(errors='replace')}"
+    if isinstance(data, dict) and "detail" in data:
+        return f"HTTP {status}: {data['detail']}"
+    return f"HTTP {status}: {str(data)[:200]}"
diff --git a/src/agentscope/workspace/_gateway_shim.py b/src/agentscope/workspace/_gateway_shim.py
new file mode 100644
index 0000000..5ac4052
--- /dev/null
+++ b/src/agentscope/workspace/_gateway_shim.py
@@ -0,0 +1,92 @@
+# -*- coding: utf-8 -*-
+"""Tiny Python script that runs inside the sandbox to relay a single
+HTTP request to the gateway, plus the host-side constants that drive it
+through :meth:`BackendBase.exec_shell`.
+
+Flow: host spawns ``python3 -c <SHIM_SCRIPT> ...`` via ``exec_shell``;
+the shim calls the gateway's loopback port using ``urllib.request`` and
+emits one JSON envelope on stdout::
+
+    {
+        "status": <int>,                  # HTTP status, or -1 on error
+        "body":   "<base64-of-bytes>",    # inline when small
+        "body_file": "<sandbox-path>",    # spilled when > inline_limit
+        "error":  "<short message>"       # only when status == -1
+    }
+
+The gateway listens only on the sandbox's loopback; the host has no
+network reachability to it. The shim relies on ``python3`` (which the
+gateway venv already needs) rather than ``curl`` because we cannot
+assume ``curl`` on every backend image.
+"""
+
+from __future__ import annotations
+
+# Bodies larger than this spill to a tempfile so we don't accumulate
+# multi-MB payloads in the exec stdout channel.
+BODY_INLINE_LIMIT = 4 * 1024 * 1024
+
+# ``/tmp`` is writable on every backend image we support.
+SANDBOX_TMP_DIR = "/tmp"
+
+
+# The shim itself, embedded as a string so it ships with this module.
+# Conventions: stdlib-only; no shebang (always via ``python3 -c``);
+# exit code is always 0 — failures land in the envelope; stderr is
+# untouched so a Python traceback (e.g. syntax error after a botched
+# edit) surfaces to the caller.
+#
+# ``sys.argv`` layout when run via ``python3 -c``::
+#
+#     argv[0] = "-c"   (Python convention)
+#     argv[1] = method            (e.g. "GET" / "POST" / "DELETE")
+#     argv[2] = url               (e.g. "http://127.0.0.1:5600/health")
+#     argv[3] = body_file or ""   (path readable on the sandbox)
+#     argv[4] = inline_limit      (bytes; int as str)
+#     argv[5] = tmp_dir           (where to spill oversized responses)
+SHIM_SCRIPT = r"""
+import sys, json, base64, uuid, os
+import urllib.request, urllib.error
+
+method = sys.argv[1]
+url = sys.argv[2]
+body_file = sys.argv[3]
+inline_limit = int(sys.argv[4])
+tmp_dir = sys.argv[5]
+
+body = None
+if body_file:
+    with open(body_file, "rb") as f:
+        body = f.read()
+
+req = urllib.request.Request(url, data=body, method=method)
+if body is not None:
+    req.add_header("Content-Type", "application/json")
+
+try:
+    with urllib.request.urlopen(req) as resp:
+        status = int(resp.status)
+        resp_body = resp.read()
+except urllib.error.HTTPError as e:
+    status = int(e.code)
+    try:
+        resp_body = e.read()
+    except Exception:
+        resp_body = b""
+except Exception as e:
+    json.dump(
+        {"status": -1, "error": type(e).__name__ + ": " + str(e)},
+        sys.stdout,
+    )
+    sys.exit(0)
+
+env = {"status": status}
+if len(resp_body) > inline_limit:
+    p = os.path.join(tmp_dir, uuid.uuid4().hex + ".bin")
+    with open(p, "wb") as f:
+        f.write(resp_body)
+    env["body_file"] = p
+else:
+    env["body"] = base64.b64encode(resp_body).decode("ascii")
+json.dump(env, sys.stdout)
+"""
diff --git a/src/agentscope/workspace/_k8s/__init__.py b/src/agentscope/workspace/_k8s/__init__.py
new file mode 100644
index 0000000..68ce0b7
--- /dev/null
+++ b/src/agentscope/workspace/_k8s/__init__.py
@@ -0,0 +1,12 @@
+# -*- coding: utf-8 -*-
+"""Kubernetes-backed workspace package.
+
+Re-exports :class:`K8sWorkspace` and :class:`K8sBackend` so callers
+can write ``from agentscope.workspace._k8s import K8sWorkspace``
+without having to poke at the underlying module layout.
+"""
+
+from ._k8s_workspace import K8sWorkspace
+from ._k8s_backend import K8sBackend
+
+__all__ = ["K8sWorkspace", "K8sBackend"]
diff --git a/src/agentscope/workspace/_k8s/_constants.py b/src/agentscope/workspace/_k8s/_constants.py
new file mode 100644
index 0000000..8007828
--- /dev/null
+++ b/src/agentscope/workspace/_k8s/_constants.py
@@ -0,0 +1,42 @@
+# -*- coding: utf-8 -*-
+"""K8s-specific constants for :class:`K8sWorkspace`.
+
+Path layout (venv, script, log, helper) is derived on the base class
+from ``_gateway_home``. This module only carries defaults that cannot
+be derived: image, port, apt deps, workdir/gateway_home, and the
+K8s-name sanitiser.
+"""
+
+import re
+
+#: Default base image. Debian-slim with Python 3.11 — provides
+#: ``sh`` (dash), ``tar``, ``base64`` (coreutils) out of the box.
+#: Missing ``curl`` and ``ca-certificates`` — installed in bootstrap.
+DEFAULT_IMAGE = "python:3.11-slim"
+
+#: Default port the in-Pod gateway listens on.
+DEFAULT_GATEWAY_PORT = 5600
+
+#: apt packages the bootstrap installs before uv.
+#: ``curl`` + ``ca-certificates`` are needed for the uv installer;
+#: ``ripgrep`` is needed by the builtin Grep tool.
+SYSTEM_DEPS = ("curl", "ca-certificates", "ripgrep")
+
+#: Pod-side persistent layout — matches Docker/E2B semantics.
+POD_WORKDIR = "/workspace"
+GATEWAY_HOME = "/root/.agentscope"
+
+
+# ── K8s name sanitisation ─────────────────────────────────────────
+
+_K8S_UNSAFE_RE = re.compile(r"[^a-z0-9-]")
+
+
+def _k8s_safe_name(workspace_id: str, prefix: str = "as-ws-") -> str:
+    """Produce an RFC-1123 compliant K8s resource name.
+
+    Rules: lowercase alphanumeric + hyphens, max 63 characters,
+    must not end with a hyphen.
+    """
+    name = prefix + _K8S_UNSAFE_RE.sub("-", workspace_id.lower())
+    return name[:63].rstrip("-")
diff --git a/src/agentscope/workspace/_k8s/_k8s_backend.py b/src/agentscope/workspace/_k8s/_k8s_backend.py
new file mode 100644
index 0000000..aba7755
--- /dev/null
+++ b/src/agentscope/workspace/_k8s/_k8s_backend.py
@@ -0,0 +1,358 @@
+# -*- coding: utf-8 -*-
+"""Kubernetes Pod :class:`BackendBase` implementation.
+
+Wraps the ``kubernetes_asyncio`` exec API and tar-stream file transfer
+into the three backend primitives (``exec_shell``, ``read_file``,
+``write_file``) so that builtin tools (Bash, Read, Write, Edit, Grep,
+Glob) can operate inside a K8s Pod transparently.
+
+File I/O uses **tar streams** piped through ``exec`` — the same
+mechanism ``kubectl cp`` uses under the hood.  This mirrors
+:class:`DockerBackend`'s ``get_archive`` / ``put_archive`` approach
+and avoids the known reliability issues with raw stdin binary writes
+over the ``kubernetes_asyncio`` WebSocket channel
+(cf. kubernetes-client/python#1866).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import io
+import posixpath
+import shlex
+import tarfile
+from typing import Any
+
+from ...tool import BackendBase, ExecResult
+
+
+class K8sBackend(BackendBase):
+    """Backend that delegates to a running Kubernetes Pod.
+
+    Only the three abstract primitives (``exec_shell``, ``read_file``,
+    ``write_file``) are implemented here; the derived filesystem helpers
+    are inherited from :class:`BackendBase`.
+
+    Args:
+        api_client (`Any`):
+            A ``kubernetes_asyncio.client.ApiClient`` instance used
+            to build ``CoreV1Api`` for exec calls.
+        namespace (`str`):
+            Kubernetes namespace the Pod lives in.
+        pod_name (`str`):
+            Name of the target Pod.
+        container_name (`str`):
+            Container name within the Pod.
+        workdir (`str`):
+            Default working directory for ``exec_shell`` calls.
+    """
+
+    def __init__(
+        self,
+        api_client: Any,
+        namespace: str,
+        pod_name: str,
+        container_name: str,
+        workdir: str,
+    ) -> None:
+        """Initialize the K8s backend.
+
+        Args:
+            api_client (`Any`):
+                A ``kubernetes_asyncio.client.ApiClient`` instance.
+            namespace (`str`):
+                Kubernetes namespace the Pod lives in.
+            pod_name (`str`):
+                Name of the target Pod.
+            container_name (`str`):
+                Container name within the Pod.
+            workdir (`str`):
+                Default working directory for ``exec_shell`` calls.
+        """
+        self._api_client = api_client
+        self._namespace = namespace
+        self._pod_name = pod_name
+        self._container_name = container_name
+        self._workdir = workdir
+
+    # ── exec ───────────────────────────────────────────────────────
+
+    async def exec_shell(
+        self,
+        command: list[str],
+        *,
+        cwd: str | None = None,
+        timeout: float | None = None,
+    ) -> ExecResult:
+        """Run a program inside the Pod via WebSocket ``exec``.
+
+        Opens a multiplexed WebSocket channel with
+        ``_preload_content=False`` and reads channel-tagged frames to
+        separate stdout (channel 1), stderr (channel 2) and the exit
+        status (channel 3).  ``cwd`` is emulated by wrapping the
+        command in ``sh -c 'cd <cwd> && exec "$@"' -- <cmd...>``.
+
+        Args:
+            command (`list[str]`):
+                Executable path/name followed by its arguments.
+            cwd (`str | None`, optional):
+                Working directory inside the Pod. When ``None`` the
+                backend's default ``workdir`` is used.
+            timeout (`float | None`, optional):
+                Maximum number of seconds to wait. ``None`` waits
+                indefinitely.
+
+        Returns:
+            `ExecResult`:
+                The captured exit code, stdout, and stderr.
+        """
+        from kubernetes_asyncio import client as k8s_client
+        from kubernetes_asyncio.stream import WsApiClient
+
+        effective_cwd = cwd or self._workdir
+        wrapped = [
+            "sh",
+            "-c",
+            f'cd {shlex.quote(effective_cwd)} && exec "$@"',
+            "--",
+            *command,
+        ]
+
+        async def _run() -> ExecResult:
+            async with WsApiClient(
+                self._api_client.configuration,
+            ) as ws_api:
+                v1_ws = k8s_client.CoreV1Api(api_client=ws_api)
+                ws = await v1_ws.connect_get_namespaced_pod_exec(
+                    self._pod_name,
+                    self._namespace,
+                    command=wrapped,
+                    container=self._container_name,
+                    stderr=True,
+                    stdin=False,
+                    stdout=True,
+                    tty=False,
+                    _preload_content=False,
+                )
+                stdout_parts: list[bytes] = []
+                stderr_parts: list[bytes] = []
+                exit_code = 0
+
+                async with ws as sock:
+                    async for msg in sock:
+                        if msg.type in (
+                            1,  # WSMsgType.TEXT
+                            2,  # WSMsgType.BINARY
+                        ):
+                            data = (
+                                msg.data
+                                if isinstance(msg.data, bytes)
+                                else msg.data.encode("utf-8")
+                            )
+                            if not data:
+                                continue
+                            channel = data[0]
+                            payload = data[1:]
+                            if channel == 1:  # stdout
+                                stdout_parts.append(payload)
+                            elif channel == 2:  # stderr
+                                stderr_parts.append(payload)
+                            elif channel == 3:  # error/status
+                                import json
+
+                                try:
+                                    status = json.loads(
+                                        payload.decode("utf-8"),
+                                    )
+                                    if status.get("status") != "Success":
+                                        exit_code = int(
+                                            status.get(
+                                                "details",
+                                                {},
+                                            )
+                                            .get("causes", [{}])[0]
+                                            .get("message", "1"),
+                                        )
+                                except (
+                                    json.JSONDecodeError,
+                                    ValueError,
+                                    IndexError,
+                                    KeyError,
+                                ):
+                                    exit_code = 1
+                        else:
+                            break
+
+                return ExecResult(
+                    exit_code=exit_code,
+                    stdout=b"".join(stdout_parts),
+                    stderr=b"".join(stderr_parts),
+                )
+
+        if timeout is None:
+            return await _run()
+        try:
+            return await asyncio.wait_for(_run(), timeout=timeout)
+        except asyncio.TimeoutError:
+            return ExecResult(
+                exit_code=-1,
+                stdout=b"",
+                stderr=b"timed out",
+            )
+
+    # ── file I/O (tar-stream, mirroring DockerBackend) ─────────────
+
+    async def read_file(self, path: str) -> bytes:
+        """Read a file from the Pod via tar stream extraction.
+
+        Runs ``tar cf - -C <dir> <basename>`` inside the Pod, collects
+        the tar bytes from stdout, and extracts the file content.  This
+        handles binary files correctly — identical to DockerBackend's
+        ``get_archive`` approach.
+
+        Args:
+            path (`str`):
+                Path to the file inside the Pod.
+
+        Returns:
+            `bytes`:
+                The raw file contents.
+
+        Raises:
+            `FileNotFoundError`:
+                If the path does not exist inside the Pod.
+        """
+        dirname = posixpath.dirname(path) or "/"
+        basename = posixpath.basename(path)
+
+        result = await self.exec_shell(
+            ["tar", "cf", "-", "-C", dirname, basename],
+            cwd="/",
+        )
+        if not result.ok():
+            stderr_text = result.stderr.decode(errors="replace")
+            if "No such file" in stderr_text or "not found" in stderr_text:
+                raise FileNotFoundError(
+                    f"not found in Pod: {path}",
+                )
+            raise FileNotFoundError(
+                f"not found in Pod: {path} (tar stderr: {stderr_text})",
+            )
+
+        try:
+            tar = tarfile.open(fileobj=io.BytesIO(result.stdout), mode="r")
+        except tarfile.ReadError as exc:
+            raise FileNotFoundError(
+                f"not found in Pod: {path}",
+            ) from exc
+
+        try:
+            for member in tar.getmembers():
+                if member.isfile():
+                    f = tar.extractfile(member)
+                    if f:
+                        return f.read()
+        finally:
+            tar.close()
+
+        raise FileNotFoundError(f"not found in Pod: {path}")
+
+    async def write_file(self, path: str, data: bytes) -> None:
+        """Write raw bytes to a file inside the Pod via tar stream.
+
+        Creates the parent directory first, then constructs an in-memory
+        tar archive containing the file and pipes it to
+        ``tar xf - -C <parent>`` inside the Pod.  This mirrors
+        DockerBackend's ``put_archive`` approach and the mechanism
+        ``kubectl cp`` uses internally.
+
+        After sending the tar data, this method reads back the exec
+        stream to capture any ``tar`` stderr and exit status.  A
+        non-zero exit raises ``RuntimeError``.
+
+        Args:
+            path (`str`):
+                Destination path inside the Pod.
+            data (`bytes`):
+                The raw bytes to write.
+
+        Raises:
+            `RuntimeError`:
+                If ``tar xf`` exits non-zero inside the Pod.
+        """
+        parent = posixpath.dirname(path) or "/"
+        name = posixpath.basename(path)
+
+        await self.exec_shell(["mkdir", "-p", parent])
+
+        buf = io.BytesIO()
+        with tarfile.open(fileobj=buf, mode="w") as tf:
+            info = tarfile.TarInfo(name=name)
+            info.size = len(data)
+            tf.addfile(info, io.BytesIO(data))
+        tar_bytes = buf.getvalue()
+
+        from kubernetes_asyncio import client as k8s_client
+        from kubernetes_asyncio.stream import WsApiClient
+
+        async with WsApiClient(
+            self._api_client.configuration,
+        ) as ws_api:
+            v1_ws = k8s_client.CoreV1Api(api_client=ws_api)
+            ws = await v1_ws.connect_get_namespaced_pod_exec(
+                self._pod_name,
+                self._namespace,
+                command=["tar", "xf", "-", "-C", parent],
+                container=self._container_name,
+                stderr=True,
+                stdin=True,
+                stdout=True,
+                tty=False,
+                _preload_content=False,
+            )
+            stderr_parts: list[bytes] = []
+            exit_code = 0
+
+            async with ws as sock:
+                await sock.send_bytes(
+                    bytes([0]) + tar_bytes,
+                )
+                await sock.send_bytes(bytes([0]))
+
+                async for msg in sock:
+                    if msg.type not in (1, 2):
+                        break
+                    raw = (
+                        msg.data
+                        if isinstance(msg.data, bytes)
+                        else msg.data.encode("utf-8")
+                    )
+                    if not raw:
+                        continue
+                    channel = raw[0]
+                    payload = raw[1:]
+                    if channel == 2:
+                        stderr_parts.append(payload)
+                    elif channel == 3:
+                        import json
+
+                        try:
+                            status = json.loads(
+                                payload.decode("utf-8"),
+                            )
+                            if status.get("status") != "Success":
+                                exit_code = 1
+                        except (
+                            json.JSONDecodeError,
+                            ValueError,
+                        ):
+                            exit_code = 1
+
+            if exit_code != 0:
+                stderr_text = b"".join(stderr_parts).decode(
+                    errors="replace",
+                )
+                raise RuntimeError(
+                    f"write_file to {path!r} failed: "
+                    f"tar xf exited {exit_code}: {stderr_text}",
+                )
diff --git a/src/agentscope/workspace/_k8s/_k8s_workspace.py b/src/agentscope/workspace/_k8s/_k8s_workspace.py
new file mode 100644
index 0000000..61054b4
--- /dev/null
+++ b/src/agentscope/workspace/_k8s/_k8s_workspace.py
@@ -0,0 +1,626 @@
+# -*- coding: utf-8 -*-
+"""K8sWorkspace — sandboxed workspace backed by a Kubernetes Pod.
+
+Architecture
+------------
+
+Mirrors :class:`agentscope.workspace.DockerWorkspace` but swaps the
+Docker engine for the Kubernetes API (``kubernetes_asyncio``):
+
+* **Lifecycle.** ``initialize()`` looks up an existing Pod by label,
+  reuses it if Running, deletes-and-recreates if Failed/Unknown, or
+  creates a new one. PVCs survive Pod deletion for data persistence.
+  ``close()`` deletes the Pod but keeps the PVC (unless
+  ``delete_pvc_on_close=True`` was passed at construction).
+* **Persistence.** A PVC (``as-ws-{workspace_id}``) mounted at
+  ``/workspace`` provides cross-Pod-restart persistence. Skills,
+  ``.mcp``, sessions, and data survive restarts.
+* **Bootstrap.** First-time provisioning installs system deps +
+  uv + gateway venv + agentscope and uploads the gateway script.
+  The probe + install loop lives on :class:`SandboxedWorkspaceBase`;
+  this subclass only supplies Pod-specific shell commands via
+  :meth:`_bootstrap_commands`.
+* **MCP gateway.** Identical to Docker/E2B: a FastAPI process inside
+  the Pod, host talks to it via :class:`GatewayClient` through the
+  gateway shim (``exec_shell``-based transport, no host-to-Pod
+  network required).
+"""
+
+import asyncio
+import shlex
+from typing import Any
+
+from ..._logging import logger
+from ...mcp import MCPClient
+from .._sandboxed_base import SandboxedWorkspaceBase
+from .._utils import _GATEWAY_BASE_REQUIREMENTS
+from ._k8s_backend import K8sBackend
+from ._constants import (
+    DEFAULT_GATEWAY_PORT,
+    DEFAULT_IMAGE,
+    GATEWAY_HOME,
+    POD_WORKDIR,
+    SYSTEM_DEPS,
+    _k8s_safe_name,
+)
+
+_DEFAULT_INSTRUCTIONS = """<workspace>
+You have a Kubernetes-based workspace. All tool calls execute **inside
+the Pod** at ``{workdir}``.
+
+Layout:
+
+```
+{workdir}
+├── data/        # offloaded multimodal files
+├── skills/      # reusable skills
+└── sessions/    # session context and tool results
+```
+</workspace>"""
+
+
+# ── the workspace ──────────────────────────────────────────────────
+
+
+class K8sWorkspace(SandboxedWorkspaceBase):
+    """Workspace backed by a Kubernetes Pod with PVC persistence.
+
+    ``default_mcps`` and ``skill_paths`` are seed-time inputs and are
+    not retained as instance state past :meth:`initialize`.
+    """
+
+    _gateway_home = GATEWAY_HOME
+
+    def __init__(
+        self,
+        *,
+        workspace_id: str | None = None,
+        # ── K8s connection ──
+        kubeconfig: str | None = None,
+        namespace: str = "agentscope",
+        # ── Pod construction ──
+        image: str = DEFAULT_IMAGE,
+        image_pull_policy: str = "IfNotPresent",
+        image_pull_secrets: list[str] | None = None,
+        resources: dict[str, Any] | None = None,
+        node_selector: dict[str, str] | None = None,
+        tolerations: list[dict[str, Any]] | None = None,
+        service_account: str | None = None,
+        # ── Gateway ──
+        gateway_port: int = DEFAULT_GATEWAY_PORT,
+        extra_pip: list[str] | None = None,
+        # ── Persistence ──
+        storage_class: str | None = None,
+        storage_size: str = "1Gi",
+        delete_pvc_on_close: bool = False,
+        # ── Environment ──
+        env: dict[str, str] | None = None,
+        instructions: str = _DEFAULT_INSTRUCTIONS,
+        # ── Seed ──
+        default_mcps: list[MCPClient] | None = None,
+        skill_paths: list[str] | None = None,
+    ) -> None:
+        """Construct a :class:`K8sWorkspace`.
+
+        The Pod is *not* started here; call :meth:`initialize`
+        (or use the workspace as an ``async`` context manager).
+
+        Args:
+            workspace_id (`str | None`, optional):
+                Stable identifier. ``None`` generates a fresh UUID.
+            kubeconfig (`str | None`, optional):
+                Path to kubeconfig file. ``None`` uses in-cluster
+                config.
+            namespace (`str`, defaults to ``"agentscope"``):
+                K8s namespace for the Pod and PVC.
+            image (`str`, defaults to ``"python:3.11-slim"``):
+                Container image.
+            image_pull_policy (`str`, defaults to ``"IfNotPresent"``):
+                K8s imagePullPolicy.
+            image_pull_secrets (`list[str] | None`, optional):
+                Names of K8s image pull secrets.
+            resources (`dict[str, Any] | None`, optional):
+                K8s ResourceRequirements dict.
+            node_selector (`dict[str, str] | None`, optional):
+                K8s nodeSelector.
+            tolerations (`list[dict[str, Any]] | None`, optional):
+                K8s tolerations list.
+            service_account (`str | None`, optional):
+                K8s serviceAccountName.
+            gateway_port (`int`, defaults to `5600`):
+                Port the gateway listens on inside the Pod.
+            extra_pip (`list[str] | None`, optional):
+                Extra packages for the gateway venv.
+            storage_class (`str | None`, optional):
+                K8s StorageClass name. ``None`` uses cluster default.
+            storage_size (`str`, defaults to ``"1Gi"``):
+                PVC size.
+            delete_pvc_on_close (`bool`, defaults to ``False``):
+                When ``True``, :meth:`close` also deletes the PVC.
+            env (`dict[str, str] | None`, optional):
+                Environment variables for the container.
+            instructions (`str`):
+                System-prompt fragment template.
+            default_mcps (`list[MCPClient] | None`, optional):
+                MCPs seeded on first init.
+            skill_paths (`list[str] | None`, optional):
+                Skill directories seeded on first init.
+        """
+        super().__init__(
+            workspace_id=workspace_id,
+            default_mcps=default_mcps,
+            skill_paths=skill_paths,
+        )
+
+        # ── serializable config ─────────────────────────────────
+        self.workdir = POD_WORKDIR
+        self._kubeconfig = kubeconfig
+        self._namespace = namespace
+        self._image = image
+        self._image_pull_policy = image_pull_policy
+        self._image_pull_secrets = list(image_pull_secrets or [])
+        self._resources = resources
+        self._node_selector = node_selector
+        self._tolerations = tolerations
+        self._service_account = service_account
+        self.gateway_port = gateway_port
+        self.extra_pip: list[str] = list(extra_pip or [])
+        self._storage_class = storage_class
+        self._storage_size = storage_size
+        self._delete_pvc_on_close = delete_pvc_on_close
+        self.env: dict[str, str] = dict(env or {})
+        self.instructions = instructions
+
+        # ── runtime state (K8s-only) ────────────────────────────
+        self._api_client: Any = None
+        self._v1: Any = None  # CoreV1Api
+        self._pod_name: str = ""
+
+    # ── lifecycle hooks ─────────────────────────────────────────
+
+    async def _provision_backend(self) -> None:
+        """Create or reattach to the K8s Pod, bootstrap if needed."""
+        from kubernetes_asyncio import client as k8s_client
+        from kubernetes_asyncio import config as k8s_config
+
+        if self._kubeconfig:
+            await k8s_config.load_kube_config(
+                config_file=self._kubeconfig,
+            )
+        else:
+            try:
+                k8s_config.load_incluster_config()
+            except k8s_config.ConfigException:
+                await k8s_config.load_kube_config()
+
+        self._api_client = k8s_client.ApiClient()
+        self._v1 = k8s_client.CoreV1Api(self._api_client)
+
+        self._pod_name = _k8s_safe_name(self.workspace_id)
+
+        await self._ensure_namespace()
+        await self._ensure_pvc()
+        await self._ensure_pod()
+        await self._wait_pod_running()
+
+        self._backend = K8sBackend(
+            api_client=self._api_client,
+            namespace=self._namespace,
+            pod_name=self._pod_name,
+            container_name="workspace",
+            workdir=POD_WORKDIR,
+        )
+
+    async def _teardown_backend(self) -> None:
+        """Delete the Pod (and optionally the PVC), release the API
+        client. Errors are swallowed so teardown is always safe.
+        """
+        if self._v1 is not None and self._pod_name:
+            try:
+                await self._v1.delete_namespaced_pod(
+                    self._pod_name,
+                    self._namespace,
+                )
+            except Exception as e:
+                logger.warning("K8sWorkspace: Pod delete failed: %s", e)
+
+            if self._delete_pvc_on_close:
+                try:
+                    await self._v1.delete_namespaced_persistent_volume_claim(
+                        self._pod_name,
+                        self._namespace,
+                    )
+                except Exception as e:
+                    logger.warning(
+                        "K8sWorkspace: PVC delete failed: %s",
+                        e,
+                    )
+
+        if self._api_client is not None:
+            try:
+                await self._api_client.close()
+            except Exception:
+                pass
+            self._api_client = None
+            self._v1 = None
+
+    # ── instructions ────────────────────────────────────────────
+
+    async def get_instructions(self) -> str:
+        """Return the system-prompt fragment for this workspace."""
+        return self.instructions.format(workdir=POD_WORKDIR)
+
+    # ── internals: K8s resource management ─────────────────────
+
+    async def _ensure_namespace(self) -> None:
+        """Create the namespace if it doesn't exist."""
+        from kubernetes_asyncio.client.rest import ApiException
+
+        try:
+            await self._v1.read_namespace(self._namespace)
+        except ApiException as e:
+            if e.status == 404:
+                from kubernetes_asyncio import client as k8s_client
+
+                ns = k8s_client.V1Namespace(
+                    metadata=k8s_client.V1ObjectMeta(
+                        name=self._namespace,
+                    ),
+                )
+                await self._v1.create_namespace(ns)
+            else:
+                raise
+
+    async def _ensure_pvc(self) -> None:
+        """Create or reuse the PVC for workspace persistence.
+
+        Deletion-in-progress is detected via
+        ``metadata.deletion_timestamp`` (K8s sets this field when a
+        ``DELETE`` has been accepted but finalizers have not yet
+        completed).  ``status.phase`` does not have a
+        ``"Terminating"`` value in upstream Kubernetes.
+        """
+        from kubernetes_asyncio.client.rest import ApiException
+
+        pvc_name = self._pod_name
+        try:
+            pvc = await self._v1.read_namespaced_persistent_volume_claim(
+                pvc_name,
+                self._namespace,
+            )
+            if pvc.metadata and pvc.metadata.deletion_timestamp is not None:
+                logger.info(
+                    "K8sWorkspace: PVC %r is being deleted, waiting...",
+                    pvc_name,
+                )
+                await self._wait_pvc_deleted(pvc_name)
+                await self._create_pvc(pvc_name)
+        except ApiException as e:
+            if e.status == 404:
+                await self._create_pvc(pvc_name)
+            else:
+                raise
+
+    async def _create_pvc(self, pvc_name: str) -> None:
+        """Create a new PVC."""
+        from kubernetes_asyncio import client as k8s_client
+
+        spec_kwargs: dict[str, Any] = {
+            "access_modes": ["ReadWriteOnce"],
+            "resources": k8s_client.V1VolumeResourceRequirements(
+                requests={"storage": self._storage_size},
+            ),
+        }
+        if self._storage_class is not None:
+            spec_kwargs["storage_class_name"] = self._storage_class
+
+        pvc = k8s_client.V1PersistentVolumeClaim(
+            metadata=k8s_client.V1ObjectMeta(
+                name=pvc_name,
+                namespace=self._namespace,
+                labels={
+                    "app.kubernetes.io/managed-by": "agentscope",
+                    "agentscope.workspace.id": self.workspace_id,
+                },
+            ),
+            spec=k8s_client.V1PersistentVolumeClaimSpec(**spec_kwargs),
+        )
+        await self._v1.create_namespaced_persistent_volume_claim(
+            self._namespace,
+            pvc,
+        )
+
+    async def _wait_pvc_deleted(
+        self,
+        pvc_name: str,
+        timeout: float = 60.0,
+    ) -> None:
+        """Poll until the PVC is fully deleted."""
+        from kubernetes_asyncio.client.rest import ApiException
+
+        deadline = asyncio.get_event_loop().time() + timeout
+        while asyncio.get_event_loop().time() < deadline:
+            try:
+                await self._v1.read_namespaced_persistent_volume_claim(
+                    pvc_name,
+                    self._namespace,
+                )
+            except ApiException as e:
+                if e.status == 404:
+                    return
+                raise
+            await asyncio.sleep(1.0)
+        raise RuntimeError(
+            f"PVC {pvc_name!r} did not finish deleting " f"within {timeout}s",
+        )
+
+    async def _ensure_pod(self) -> None:
+        """Create or reuse the workspace Pod.
+
+        Only terminal phases (``Failed``, ``Unknown``, ``Succeeded``)
+        trigger a delete-and-recreate cycle.  ``Pending`` Pods are left
+        for :meth:`_wait_pod_running` which inspects container statuses
+        for early failure detection.
+
+        A Pod whose ``metadata.deletion_timestamp`` is set is already
+        being deleted (by a previous ``close()`` or an external actor)
+        — attaching to it would race the terminator, so we wait for it
+        to disappear and then create a fresh one.
+        """
+        from kubernetes_asyncio.client.rest import ApiException
+
+        _REBUILD_PHASES = frozenset({"Failed", "Unknown", "Succeeded"})
+
+        try:
+            pod = await self._v1.read_namespaced_pod(
+                self._pod_name,
+                self._namespace,
+            )
+            phase = pod.status.phase if pod.status else None
+            deletion_ts = (
+                pod.metadata.deletion_timestamp
+                if pod.metadata is not None
+                else None
+            )
+            if deletion_ts is not None:
+                logger.info(
+                    "K8sWorkspace: Pod %r is being deleted, "
+                    "waiting to recreate",
+                    self._pod_name,
+                )
+                await self._wait_pod_deleted()
+                await self._create_pod()
+                return
+            if phase in {"Running", "Pending"}:
+                return
+            if phase in _REBUILD_PHASES:
+                logger.info(
+                    "K8sWorkspace: Pod %r is %s, deleting and recreating",
+                    self._pod_name,
+                    phase,
+                )
+                try:
+                    await self._v1.delete_namespaced_pod(
+                        self._pod_name,
+                        self._namespace,
+                    )
+                except ApiException:
+                    pass
+                await self._wait_pod_deleted()
+                await self._create_pod()
+            else:
+                logger.warning(
+                    "K8sWorkspace: Pod %r has unexpected phase %r, "
+                    "deleting and recreating",
+                    self._pod_name,
+                    phase,
+                )
+                try:
+                    await self._v1.delete_namespaced_pod(
+                        self._pod_name,
+                        self._namespace,
+                    )
+                except ApiException:
+                    pass
+                await self._wait_pod_deleted()
+                await self._create_pod()
+        except ApiException as e:
+            if e.status == 404:
+                await self._create_pod()
+            else:
+                raise
+
+    async def _create_pod(self) -> None:
+        """Create the workspace Pod."""
+        from kubernetes_asyncio import client as k8s_client
+
+        container_env = None
+        if self.env:
+            container_env = [
+                k8s_client.V1EnvVar(name=k, value=v)
+                for k, v in self.env.items()
+            ]
+
+        container = k8s_client.V1Container(
+            name="workspace",
+            image=self._image,
+            image_pull_policy=self._image_pull_policy,
+            command=["sleep", "infinity"],
+            working_dir=POD_WORKDIR,
+            ports=[
+                k8s_client.V1ContainerPort(
+                    container_port=self.gateway_port,
+                ),
+            ],
+            resources=(
+                k8s_client.V1ResourceRequirements(**self._resources)
+                if self._resources
+                else None
+            ),
+            volume_mounts=[
+                k8s_client.V1VolumeMount(
+                    name="workspace-data",
+                    mount_path=POD_WORKDIR,
+                ),
+            ],
+            env=container_env,
+        )
+
+        volumes = [
+            k8s_client.V1Volume(
+                name="workspace-data",
+                persistent_volume_claim=(
+                    k8s_client.V1PersistentVolumeClaimVolumeSource(
+                        claim_name=self._pod_name,
+                    )
+                ),
+            ),
+        ]
+
+        spec_kwargs: dict[str, Any] = {
+            "restart_policy": "OnFailure",
+            "containers": [container],
+            "volumes": volumes,
+        }
+        if self._node_selector:
+            spec_kwargs["node_selector"] = self._node_selector
+        if self._tolerations:
+            spec_kwargs["tolerations"] = [
+                k8s_client.V1Toleration(**t) for t in self._tolerations
+            ]
+        if self._service_account:
+            spec_kwargs["service_account_name"] = self._service_account
+        if self._image_pull_secrets:
+            spec_kwargs["image_pull_secrets"] = [
+                k8s_client.V1LocalObjectReference(name=s)
+                for s in self._image_pull_secrets
+            ]
+
+        pod = k8s_client.V1Pod(
+            metadata=k8s_client.V1ObjectMeta(
+                name=self._pod_name,
+                namespace=self._namespace,
+                labels={
+                    "app.kubernetes.io/managed-by": "agentscope",
+                    "agentscope.workspace": "true",
+                    "agentscope.workspace.id": self.workspace_id,
+                },
+            ),
+            spec=k8s_client.V1PodSpec(**spec_kwargs),
+        )
+        await self._v1.create_namespaced_pod(self._namespace, pod)
+
+    async def _wait_pod_running(self, timeout: float = 120.0) -> None:
+        """Poll until the Pod phase is Running.
+
+        Also inspects container statuses during the Pending phase to
+        detect unrecoverable conditions (``ImagePullBackOff``,
+        ``ErrImagePull``, ``InvalidImageName``) early instead of
+        waiting for the full timeout.
+        """
+        _TERMINAL_WAITING_REASONS = frozenset(
+            {
+                "ImagePullBackOff",
+                "ErrImagePull",
+                "InvalidImageName",
+                "CrashLoopBackOff",
+            },
+        )
+        _UNSCHEDULABLE_TYPES = frozenset(
+            {"PodScheduled"},
+        )
+
+        deadline = asyncio.get_event_loop().time() + timeout
+        delay = 0.5
+        while asyncio.get_event_loop().time() < deadline:
+            pod = await self._v1.read_namespaced_pod(
+                self._pod_name,
+                self._namespace,
+            )
+            phase = pod.status.phase if pod.status else None
+            if phase == "Running":
+                return
+            if phase in ("Failed", "Unknown"):
+                raise RuntimeError(
+                    f"Pod {self._pod_name!r} entered {phase} state",
+                )
+
+            if phase == "Pending" and pod.status:
+                for cs in pod.status.container_statuses or []:
+                    if cs.state and cs.state.waiting:
+                        reason = cs.state.waiting.reason or ""
+                        if reason in _TERMINAL_WAITING_REASONS:
+                            msg = cs.state.waiting.message or reason
+                            raise RuntimeError(
+                                f"Pod {self._pod_name!r} container "
+                                f"is stuck: {msg}",
+                            )
+                for cond in pod.status.conditions or []:
+                    if (
+                        cond.type in _UNSCHEDULABLE_TYPES
+                        and cond.status == "False"
+                        and cond.reason == "Unschedulable"
+                    ):
+                        raise RuntimeError(
+                            f"Pod {self._pod_name!r} is "
+                            f"unschedulable: {cond.message}",
+                        )
+
+            await asyncio.sleep(delay)
+            delay = min(delay * 1.5, 3.0)
+        raise RuntimeError(
+            f"Pod {self._pod_name!r} did not become Running "
+            f"within {timeout}s",
+        )
+
+    async def _wait_pod_deleted(self, timeout: float = 30.0) -> None:
+        """Poll until the Pod is gone."""
+        from kubernetes_asyncio.client.rest import ApiException
+
+        deadline = asyncio.get_event_loop().time() + timeout
+        while asyncio.get_event_loop().time() < deadline:
+            try:
+                await self._v1.read_namespaced_pod(
+                    self._pod_name,
+                    self._namespace,
+                )
+            except ApiException as e:
+                if e.status == 404:
+                    return
+                raise
+            await asyncio.sleep(1.0)
+        raise RuntimeError(
+            f"Pod {self._pod_name!r} did not finish deleting "
+            f"within {timeout}s",
+        )
+
+    # ── internals: bootstrap ────────────────────────────────────
+
+    def _bootstrap_commands(self) -> list[str]:
+        """Shell commands that provision this Pod once.
+
+        Only runs when the gateway script is missing (fresh PVC, or a
+        Pod that died before the script was written). Slim base image
+        runs as root, so no ``sudo`` needed — uv lands at
+        ``/usr/local/bin/uv`` which is on the default PATH.
+        """
+        pip_pkgs = list(_GATEWAY_BASE_REQUIREMENTS) + list(self.extra_pip)
+        # Quote every requirement string so entries containing spaces
+        # or shell metacharacters (e.g. version specifiers wrapped in
+        # brackets, direct-URL installs) cannot break the ``sh -c``
+        # command or become an injection vector.
+        pip_args = " ".join(shlex.quote(p) for p in pip_pkgs)
+        sys_deps = " ".join(shlex.quote(d) for d in SYSTEM_DEPS)
+
+        return [
+            f"apt-get update -qq "
+            f"&& apt-get install -y --no-install-recommends {sys_deps} "
+            f"&& rm -rf /var/lib/apt/lists/*",
+            "curl -LsSf https://astral.sh/uv/install.sh "
+            "| env UV_INSTALL_DIR=/usr/local/bin "
+            "INSTALLER_NO_MODIFY_PATH=1 sh",
+            f"uv venv {self._gateway_venv}",
+            f"uv pip install --python {self._gateway_python} {pip_args}",
+            f"uv pip install --python {self._gateway_python} "
+            f"--no-deps 'agentscope'",
+        ]
diff --git a/src/agentscope/workspace/_local_workspace.py b/src/agentscope/workspace/_local_workspace.py
new file mode 100644
index 0000000..7db64c2
--- /dev/null
+++ b/src/agentscope/workspace/_local_workspace.py
@@ -0,0 +1,873 @@
+# -*- coding: utf-8 -*-
+"""The local workspace class."""
+
+import asyncio
+import hashlib
+import json
+import os
+import re
+import shutil
+from typing import TypedDict
+
+import frontmatter
+
+from .._logging import logger
+from ..mcp import MCPClient
+from ..skill import Skill
+from ..tool._builtin._backend import LocalBackend
+from ._base import WorkspaceBase
+
+
+class _SkillEntry(TypedDict):
+    """A single entry in the .skills index file."""
+
+    hash: str
+    """SHA-256 hash of the skill's SKILL.md content."""
+    skill_name: str
+    """The name exposed to the agent (may differ from the directory name)."""
+
+
+class _SkillsFile(TypedDict):
+    """Schema of the .skills index file stored inside skills_dir."""
+
+    skills_dir_mtime: float
+    """mtime of skills_dir at the time the index was last written."""
+    skills: dict[str, _SkillEntry]
+    """Mapping from directory name (relative to skills_dir) to skill entry."""
+
+
+def _sanitize_dir_name(name: str) -> str:
+    """Sanitize a skill name into a safe directory name.
+
+    Allowed characters: ASCII letters, digits, CJK unified ideographs,
+    hyphens, and underscores. Everything else is replaced with ``_``.
+
+    Args:
+        name (`str`):
+            The raw skill name from SKILL.md frontmatter.
+
+    Returns:
+        `str`:
+            A sanitized string safe to use as a directory name on Windows,
+            macOS, and Linux.
+    """
+    return re.sub(r"[^\w一-鿿-]", "_", name)
+
+
+_DEFAULT_WORKSPACE_INSTRUCTIONS = """<workspace>
+You have access to a local workspace at {workdir} with the following structure:
+
+```
+{workdir}
+├── data/        # offloaded multimodal files (images, etc.)
+├── skills/      # reusable skills, each in its own subdirectory
+└── sessions/    # session context and tool results
+```
+
+This workspace is your personal working environment for completing various tasks.
+You are responsible for keeping it clean, structured, and easy to navigate over time.
+
+### Project Directory
+- Create a dedicated subdirectory for each task or project under the workspace root.
+- Name the directory concisely and descriptively, e.g. `20240315_web-scraper`, so it remains identifiable long after creation.
+- Always create a `README.md` at the project root documenting:
+  - What the project is about
+  - When it was created
+  - Key decisions or context that would help you resume work later
+  - The changes you have made (and when)
+
+### Version Control
+- It is recommended to initialize a `git` repository in each project directory
+  to track changes and allow rollbacks.
+- Always create a `.gitignore` before the first commit to exclude unwanted files
+  (e.g. virtual environments, cache, secrets).
+
+### Python Environment
+- If a project requires Python, use `uv` to create an isolated virtual environment
+  inside the project directory:
+  ```shell
+  uv venv && uv pip install ...
+  ```
+- Never install packages into a shared or global environment — each project must
+  manage its own dependencies to avoid conflicts.
+</workspace>"""  # noqa: E501
+
+
+class LocalWorkspace(WorkspaceBase):
+    """Local-directory workspace.
+
+    Layout::
+
+        {workdir}/
+        ├── .mcp          # persisted MCP client configs (JSON array)
+        ├── data/         # offloaded multimodal files
+        ├── skills/       # skill subdirectories
+        └── sessions/     # per-session context and tool-result files
+    """
+
+    def __init__(
+        self,
+        *,
+        workdir: str,
+        workspace_id: str | None = None,
+        default_mcps: list[MCPClient] | None = None,
+        skill_paths: list[str] | None = None,
+        instructions: str = _DEFAULT_WORKSPACE_INSTRUCTIONS,
+    ) -> None:
+        """Construct a :class:`LocalWorkspace`.
+
+        Args:
+            workdir (`str`):
+                Filesystem path to the workspace root. Created on
+                demand. Always resolved to an absolute path.
+            workspace_id (`str | None`, optional):
+                Existing workspace identifier to adopt. ``None``
+                generates a fresh UUID.
+            default_mcps (`list[MCPClient] | None`, optional):
+                MCP clients seeded into a brand-new workspace.
+                Ignored on subsequent restarts that already have a
+                persisted ``<workdir>/.mcp`` file.
+            skill_paths (`list[str] | None`, optional):
+                Local skill directories seeded into
+                ``<workdir>/skills`` on first :meth:`initialize`.
+            instructions (`str`, defaults to \
+            `_DEFAULT_WORKSPACE_INSTRUCTIONS`):
+                System-prompt fragment template returned by
+                :meth:`get_instructions`. Supports the ``{workdir}``
+                placeholder.
+        """
+        super().__init__(workspace_id=workspace_id)
+
+        # ── serializable config ─────────────────────────────────
+        self.workdir = os.path.abspath(workdir)
+        self.instructions = instructions.format(workdir=self.workdir)
+
+        # ── seed-only ───────────────────────────────────────────
+        self.default_mcps: list[MCPClient] = list(default_mcps or [])
+        self.skill_paths: list[str] = list(skill_paths or [])
+
+        # ── runtime state ───────────────────────────────────────
+        self._backend = LocalBackend()
+        self._mcps: list[MCPClient] = []
+
+        self._skill_lock = asyncio.Lock()
+        self._mcp_lock = asyncio.Lock()
+
+    async def initialize(self) -> None:
+        """Initialise the workspace.
+
+        MCP state is restored from ``.mcp`` if it exists; otherwise
+        ``default_mcps`` are used and persisted so the next start picks
+        them up from disk. ``skill_paths`` are seeded on first use.
+
+        Idempotent: a no-op when the workspace is already alive.
+        """
+        if self.is_alive:
+            return
+
+        os.makedirs(self.workdir, exist_ok=True)
+
+        # Restore or seed MCPs
+        mcp_file = os.path.join(self.workdir, ".mcp")
+        if await self._backend.file_exists(mcp_file):
+            raw = await self._backend.read_file(mcp_file)
+            raw_list = json.loads(raw.decode("utf-8"))
+            for m in raw_list:
+                try:
+                    self._mcps.append(MCPClient.model_validate(m))
+                except Exception as e:
+                    logger.warning(
+                        "Skipping invalid MCP entry '%s': %s",
+                        m.get("name", "?"),
+                        e,
+                    )
+        else:
+            self._mcps = list(self.default_mcps)
+            await self._save_mcp_file()
+
+        failed: list[MCPClient] = []
+        for mcp in self._mcps:
+            if mcp.is_stateful and not mcp.is_connected:
+                try:
+                    await mcp.connect()
+                except Exception as e:
+                    logger.warning(
+                        "Failed to connect stateful MCP '%s': %s, removing.",
+                        mcp.name,
+                        e,
+                    )
+                    failed.append(mcp)
+        for mcp in failed:
+            self._mcps.remove(mcp)
+
+        # Seed skills
+        skills_dir = os.path.join(self.workdir, "skills")
+        os.makedirs(skills_dir, exist_ok=True)
+
+        skills_file = await self._load_skills_file(skills_dir)
+        existing: dict[str, _SkillEntry] = skills_file["skills"]
+
+        # Build fast-lookup sets from the current index
+        existing_hashes: set[str] = {e["hash"] for e in existing.values()}
+        existing_agent_names: set[str] = {
+            e["skill_name"] for e in existing.values()
+        }
+        existing_dir_names: set[str] = set(existing.keys())
+
+        updated = False
+        for skill_path in self.skill_paths:
+            result = await self._validate_and_hash_skill(skill_path)
+            if result is None:
+                continue
+
+            _, raw_name, skill_hash = result
+
+            # Skip if already present (by content hash)
+            if skill_hash in existing_hashes:
+                logger.info(
+                    "Skill '%s' (hash: %s...) already exists, skipping",
+                    raw_name,
+                    skill_hash[:8],
+                )
+                continue
+
+            # Resolve agent-facing name conflict
+            agent_name = raw_name
+            counter = 1
+            while agent_name in existing_agent_names:
+                agent_name = f"{raw_name} ({counter})"
+                counter += 1
+
+            # Resolve directory name conflict
+            base_dir = _sanitize_dir_name(raw_name)
+            dir_name = base_dir
+            counter = 1
+            while dir_name in existing_dir_names:
+                dir_name = f"{base_dir}_{counter}"
+                counter += 1
+
+            dest_path = os.path.join(skills_dir, dir_name)
+
+            # Defensive path-traversal check
+            if not os.path.realpath(dest_path).startswith(
+                os.path.realpath(skills_dir) + os.sep,
+            ):
+                logger.warning(
+                    "Skill '%s' resolves outside skills_dir, skipping",
+                    raw_name,
+                )
+                continue
+
+            try:
+                await asyncio.to_thread(
+                    shutil.copytree,
+                    skill_path,
+                    dest_path,
+                    dirs_exist_ok=False,
+                )
+            except Exception as e:
+                logger.warning(
+                    "Failed to copy skill '%s' from %s: %s",
+                    raw_name,
+                    skill_path,
+                    str(e),
+                )
+                continue
+
+            logger.info(
+                "Copied skill '%s' (agent name: '%s') from %s to %s",
+                raw_name,
+                agent_name,
+                skill_path,
+                dest_path,
+            )
+
+            entry: _SkillEntry = {"hash": skill_hash, "skill_name": agent_name}
+            existing[dir_name] = entry
+            existing_hashes.add(skill_hash)
+            existing_agent_names.add(agent_name)
+            existing_dir_names.add(dir_name)
+            updated = True
+
+        if updated:
+            skills_file["skills"] = existing
+            mtime = await self._backend.stat_mtime(skills_dir)
+            skills_file["skills_dir_mtime"] = (
+                mtime if mtime is not None else 0.0
+            )
+            await self._save_skills_file(skills_dir, skills_file)
+
+        self.is_alive = True
+
+    async def get_instructions(self) -> str:
+        """Get the workspace instructions."""
+        return self.instructions
+
+    async def _load_skills_file(self, skills_dir: str) -> _SkillsFile:
+        """Load the .skills index file, returning an empty structure if absent.
+
+        Args:
+            skills_dir (`str`): The skills directory path.
+
+        Returns:
+            `_SkillsFile`: The parsed index, or a fresh empty structure.
+        """
+        path = os.path.join(skills_dir, ".skills")
+        if not await self._backend.file_exists(path):
+            return {"skills_dir_mtime": 0.0, "skills": {}}
+
+        try:
+            raw = await self._backend.read_file(path)
+            data = json.loads(raw.decode("utf-8"))
+            return _SkillsFile(
+                skills_dir_mtime=float(data.get("skills_dir_mtime", 0.0)),
+                skills=data.get("skills", {}),
+            )
+        except Exception as e:
+            logger.warning("Failed to load .skills from %s: %s", path, str(e))
+            return {"skills_dir_mtime": 0.0, "skills": {}}
+
+    async def _save_skills_file(
+        self,
+        skills_dir: str,
+        data: _SkillsFile,
+    ) -> None:
+        """Persist the .skills index file.
+
+        Args:
+            skills_dir (`str`): The skills directory path.
+            data (`_SkillsFile`): The index to write.
+        """
+        path = os.path.join(skills_dir, ".skills")
+        try:
+            await self._backend.write_file(
+                path,
+                json.dumps(data, indent=2, ensure_ascii=False).encode("utf-8"),
+            )
+        except Exception as e:
+            logger.warning("Failed to save .skills to %s: %s", path, str(e))
+
+    async def _validate_skill(
+        self,
+        skill_path: str,
+    ) -> tuple[str, str, str] | None:
+        """Validate if a skill path contains a valid SKILL.md file.
+
+        Args:
+            skill_path (`str`):
+                The path to the skill directory.
+
+        Returns:
+            `tuple[str, str, str] | None`:
+                A tuple of (name, description, skill_md_content) if valid,
+                None otherwise.
+        """
+        skill_md_path = os.path.join(skill_path, "SKILL.md")
+
+        try:
+            # Check if SKILL.md exists
+            if not await self._backend.file_exists(skill_md_path):
+                logger.warning(
+                    "Invalid skill at %s: SKILL.md not found",
+                    skill_path,
+                )
+                return None
+
+            # Read and parse SKILL.md
+            raw = await self._backend.read_file(skill_md_path)
+            content_str = raw.decode("utf-8")
+
+            # Parse frontmatter
+            content = frontmatter.loads(content_str)
+            name = content.get("name")
+            description = content.get("description")
+
+            if not name or not description:
+                logger.warning(
+                    "Invalid skill at %s: SKILL.md missing required "
+                    "fields (name or description)",
+                    skill_path,
+                )
+                return None
+
+            return str(name), str(description), content_str
+
+        except Exception as e:
+            logger.warning(
+                "Failed to validate skill at %s: %s",
+                skill_path,
+                str(e),
+            )
+            return None
+
+    async def _validate_and_hash_skill(
+        self,
+        skill_path: str,
+    ) -> tuple[str, str, str] | None:
+        """Validate a skill and compute its hash.
+
+        Args:
+            skill_path (`str`):
+                The path to the skill directory.
+
+        Returns:
+            `tuple[str, str, str] | None`:
+                A tuple of (skill_path, skill_name, skill_hash) if valid,
+                None otherwise.
+        """
+        validation_result = await self._validate_skill(skill_path)
+        if validation_result is None:
+            return None
+
+        skill_name, _, skill_md_content = validation_result
+
+        # Compute hash
+        skill_hash = hashlib.sha256(
+            skill_md_content.encode("utf-8"),
+        ).hexdigest()
+
+        return skill_path, skill_name, skill_hash
+
+    async def close(self) -> None:
+        """Close every stateful MCP attached to this workspace.
+
+        ``LocalWorkspace`` itself owns no resources (the workdir is
+        the persistence layer and is left untouched), but stdio /
+        stateful HTTP MCPs hold long-lived sessions that have to be
+        closed explicitly. Stateless HTTP MCPs are skipped — they
+        spin up an ad-hoc session per call and have nothing to close.
+        """
+        async with self._mcp_lock:
+            for mcp in self._mcps:
+                if mcp.is_stateful and mcp.is_connected:
+                    try:
+                        await mcp.close()
+                    except Exception as e:
+                        logger.warning(
+                            (
+                                "Failed to close MCP %r "
+                                "when closing local workspace: %s"
+                            ),
+                            mcp.name,
+                            e,
+                        )
+        self.is_alive = False
+
+    async def reset(self) -> None:
+        """Return the workspace to an empty state.
+
+        Closes and drops all MCPs (including the persisted ``.mcp``)
+        and deletes ``skills/``, ``sessions/``, and ``data/``.
+        ``default_mcps`` and ``skill_paths`` are not re-seeded.
+        """
+        async with self._mcp_lock:
+            for mcp in self._mcps:
+                if mcp.is_stateful and mcp.is_connected:
+                    try:
+                        await mcp.close()
+                    except Exception as e:
+                        logger.warning(
+                            "MCP %r close failed during reset: %s",
+                            mcp.name,
+                            e,
+                        )
+            self._mcps = []
+
+            mcp_file = os.path.join(self.workdir, ".mcp")
+            await self._backend.delete_path(mcp_file)
+
+        async with self._skill_lock:
+            skills_path = os.path.join(self.workdir, "skills")
+            await self._backend.delete_path(skills_path)
+
+        for sub in ("sessions", "data"):
+            path = os.path.join(self.workdir, sub)
+            await self._backend.delete_path(path)
+
+    async def list_skills(self) -> list[Skill]:
+        """List all skills available in the workspace.
+
+        The method uses the .skills index for agent-facing names, compares the
+        skills directory mtime to detect manual additions/removals since the
+        last write, and reconciles the index when a change is found.
+
+        Returns:
+            `list[Skill]`:
+                A list of Skill objects found in the workspace.
+        """
+        skills_dir = os.path.join(self.workdir, "skills")
+        async with self._skill_lock:
+            if not await self._backend.is_dir(skills_dir):
+                return []
+
+            skills_file = await self._load_skills_file(skills_dir)
+            current_mtime = await self._backend.stat_mtime(skills_dir)
+            if current_mtime is None:
+                current_mtime = 0.0
+
+            # Detect if the skills directory has changed since last indexing
+            if current_mtime != skills_file["skills_dir_mtime"]:
+                skills_file = await self._reconcile_skills_dir(
+                    skills_dir,
+                    skills_file,
+                    current_mtime,
+                )
+
+            # Load skills from disk using the index for the agent-facing name
+            tasks = [
+                self._load_single_skill(
+                    os.path.join(skills_dir, dir_name),
+                    entry["skill_name"],
+                )
+                for dir_name, entry in skills_file["skills"].items()
+            ]
+            results = await asyncio.gather(*tasks, return_exceptions=True)
+
+            skills: list = []
+            for dir_name, result in zip(skills_file["skills"], results):
+                if isinstance(result, Exception):
+                    logger.warning(
+                        "Failed to load skill from %s: %s",
+                        dir_name,
+                        str(result),
+                    )
+                elif result is not None:
+                    skills.append(result)
+
+            return skills
+
+    async def _reconcile_skills_dir(
+        self,
+        skills_dir: str,
+        skills_file: _SkillsFile,
+        current_mtime: float,
+    ) -> _SkillsFile:
+        """Reconcile the .skills index after the skills directory has changed.
+
+        Handles:
+        - Manually deleted subdirectories: removed from the index.
+        - Manually added subdirectories: validated and added with conflict
+          resolution for both directory name and agent-facing skill name.
+
+        Args:
+            skills_dir (`str`): Path to the skills directory.
+            skills_file (`_SkillsFile`): The current (stale) index.
+            current_mtime (`float`): The freshly-read mtime of skills_dir.
+
+        Returns:
+            `_SkillsFile`: The updated index (also persisted to disk).
+        """
+        existing: dict[str, _SkillEntry] = skills_file["skills"]
+        original_mtime = skills_file["skills_dir_mtime"]
+
+        # Collect actual subdirectories on disk
+        entries = await self._backend.list_dir(skills_dir)
+        actual_dirs: set[str] = set()
+        for d in entries:
+            dir_path = os.path.join(skills_dir, d)
+            if await self._backend.is_dir(dir_path):
+                actual_dirs.add(d)
+
+        indexed_dirs = set(existing.keys())
+
+        updated = False
+
+        # Remove entries for directories that no longer exist
+        for removed in indexed_dirs - actual_dirs:
+            logger.info(
+                "Skill directory '%s' removed, updating index",
+                removed,
+            )
+            del existing[removed]
+            updated = True
+
+        # Add entries for directories not yet in the index
+        existing_agent_names: set[str] = {
+            e["skill_name"] for e in existing.values()
+        }
+        existing_hashes: set[str] = {e["hash"] for e in existing.values()}
+
+        for new_dir in actual_dirs - indexed_dirs:
+            skill_path = os.path.join(skills_dir, new_dir)
+            result = await self._validate_and_hash_skill(skill_path)
+            if result is None:
+                continue
+
+            _, raw_name, skill_hash = result
+
+            if skill_hash in existing_hashes:
+                logger.info(
+                    "Manually added skill '%s' already tracked by hash, "
+                    "skipping",
+                    new_dir,
+                )
+                continue
+
+            agent_name = raw_name
+            counter = 1
+            while agent_name in existing_agent_names:
+                agent_name = f"{raw_name} ({counter})"
+                counter += 1
+
+            entry: _SkillEntry = {"hash": skill_hash, "skill_name": agent_name}
+            existing[new_dir] = entry
+            existing_agent_names.add(agent_name)
+            existing_hashes.add(skill_hash)
+            updated = True
+            logger.info(
+                "Manually added skill '%s' indexed as agent name '%s'",
+                new_dir,
+                agent_name,
+            )
+
+        skills_file["skills"] = existing
+        skills_file["skills_dir_mtime"] = current_mtime
+
+        # Save if index changed OR if mtime needs updating
+        # (mtime change without index change means non-skill files were
+        # added/removed, we still need to record the new mtime to avoid
+        # re-reconciling on every list_skills call)
+        if updated or current_mtime != original_mtime:
+            await self._save_skills_file(skills_dir, skills_file)
+
+        return skills_file
+
+    async def _load_single_skill(
+        self,
+        skill_dir: str,
+        skill_name: str,
+    ) -> Skill | None:
+        """Load a single skill from disk using the agent-facing name from
+        the index.
+
+        Args:
+            skill_dir (`str`):
+                The skill directory path containing SKILL.md.
+            skill_name (`str`):
+                The agent-facing name stored in the .skills index.
+
+        Returns:
+            `Skill | None`:
+                A Skill object or None if the SKILL.md is missing/invalid.
+        """
+        skill_md_path = os.path.join(skill_dir, "SKILL.md")
+
+        try:
+            if not await self._backend.file_exists(skill_md_path):
+                return None
+
+            updated_at = await self._backend.stat_mtime(skill_md_path)
+            if updated_at is None:
+                updated_at = 0.0
+
+            raw = await self._backend.read_file(skill_md_path)
+            content_str = raw.decode("utf-8")
+            content = frontmatter.loads(content_str)
+
+            description = content.get("description")
+            if not description:
+                logger.warning(
+                    "SKILL.md in %s is missing 'description'. Skipping.",
+                    skill_dir,
+                )
+                return None
+
+            return Skill(
+                name=skill_name,
+                description=str(description),
+                dir=skill_dir,
+                markdown=content.content,
+                updated_at=updated_at,
+            )
+
+        except Exception as e:
+            logger.warning(
+                "Failed to load skill from %s: %s",
+                skill_dir,
+                str(e),
+            )
+            return None
+
+    async def add_mcp(self, mcp_client: MCPClient) -> None:
+        """Add an MCP client, connect it if stateful, and persist.
+
+        Args:
+            mcp_client (`MCPClient`):
+                The MCP client to add.
+        """
+        async with self._mcp_lock:
+            if mcp_client.is_stateful and not mcp_client.is_connected:
+                await mcp_client.connect()
+            self._mcps.append(mcp_client)
+            await self._save_mcp_file()
+
+    async def remove_mcp(self, name: str) -> None:
+        """Remove an MCP client by name, disconnecting it if stateful.
+
+        Args:
+            name (`str`):
+                The ``name`` field of the client to remove.
+        """
+        async with self._mcp_lock:
+            for i, mcp in enumerate(self._mcps):
+                if mcp.name == name:
+                    if mcp.is_stateful and mcp.is_connected:
+                        await mcp.close()
+                    self._mcps.pop(i)
+                    await self._save_mcp_file()
+                    return
+        logger.warning("MCP client %r not found in workspace", name)
+
+    async def add_skill(self, skill_path: str) -> None:
+        """Add a skill to the workspace by copying from the given path.
+
+        The skill directory must contain a valid ``SKILL.md`` file with
+        ``name`` and ``description`` frontmatter fields.  Duplicate skills
+        (identified by the SHA-256 hash of ``SKILL.md``) are silently skipped.
+        Name and directory conflicts are resolved by appending a numeric
+        suffix.
+
+        Args:
+            skill_path (`str`):
+                Absolute or relative path to the skill directory to copy.
+
+        Raises:
+            ValueError: If the skill at ``skill_path`` is invalid (missing or
+                malformed ``SKILL.md``).
+        """
+        skills_dir = os.path.join(self.workdir, "skills")
+        async with self._skill_lock:
+            os.makedirs(skills_dir, exist_ok=True)
+
+            result = await self._validate_and_hash_skill(skill_path)
+            if result is None:
+                raise ValueError(
+                    f"Invalid skill at {skill_path!r}: missing or malformed "
+                    "SKILL.md (requires 'name' and 'description' fields).",
+                )
+
+            _, raw_name, skill_hash = result
+
+            skills_file = await self._load_skills_file(skills_dir)
+            existing: dict[str, _SkillEntry] = skills_file["skills"]
+
+            existing_hashes: set[str] = {e["hash"] for e in existing.values()}
+            if skill_hash in existing_hashes:
+                logger.info(
+                    "Skill '%s' (hash: %s...) already exists, skipping",
+                    raw_name,
+                    skill_hash[:8],
+                )
+                return
+
+            existing_agent_names: set[str] = {
+                e["skill_name"] for e in existing.values()
+            }
+            existing_dir_names: set[str] = set(existing.keys())
+
+            # Resolve agent-facing name conflict
+            agent_name = raw_name
+            counter = 1
+            while agent_name in existing_agent_names:
+                agent_name = f"{raw_name} ({counter})"
+                counter += 1
+
+            # Resolve directory name conflict
+            base_dir = _sanitize_dir_name(raw_name)
+            dir_name = base_dir
+            counter = 1
+            while dir_name in existing_dir_names:
+                dir_name = f"{base_dir}_{counter}"
+                counter += 1
+
+            dest_path = os.path.join(skills_dir, dir_name)
+
+            if not os.path.realpath(dest_path).startswith(
+                os.path.realpath(skills_dir) + os.sep,
+            ):
+                raise ValueError(
+                    f"Skill path {skill_path!r} resolves outside skills_dir.",
+                )
+
+            await asyncio.to_thread(
+                shutil.copytree,
+                skill_path,
+                dest_path,
+                dirs_exist_ok=False,
+            )
+
+            logger.info(
+                "Copied skill '%s' (agent name: '%s') from %s to %s",
+                raw_name,
+                agent_name,
+                skill_path,
+                dest_path,
+            )
+
+            existing[dir_name] = {"hash": skill_hash, "skill_name": agent_name}
+            skills_file["skills"] = existing
+            mtime = await self._backend.stat_mtime(skills_dir)
+            skills_file["skills_dir_mtime"] = (
+                mtime if mtime is not None else 0.0
+            )
+            await self._save_skills_file(skills_dir, skills_file)
+
+    async def remove_skill(self, name: str) -> None:
+        """Remove a skill from the workspace by its agent-facing name.
+
+        The skill directory is deleted from disk and the ``.skills`` index is
+        updated.  If no skill with the given name is found, a warning is
+        logged and the method returns without error.
+
+        Args:
+            name (`str`):
+                The agent-facing name of the skill to remove (as stored in the
+                ``.skills`` index, i.e. the ``name`` field from ``SKILL.md``
+                possibly with a numeric suffix for de-duplication).
+        """
+        skills_dir = os.path.join(self.workdir, "skills")
+        async with self._skill_lock:
+            if not await self._backend.is_dir(skills_dir):
+                logger.warning(
+                    "Skills directory does not exist; cannot remove skill %r",
+                    name,
+                )
+                return
+
+            skills_file = await self._load_skills_file(skills_dir)
+            existing: dict[str, _SkillEntry] = skills_file["skills"]
+
+            target_dir: str | None = None
+            for dir_name, entry in existing.items():
+                if entry["skill_name"] == name:
+                    target_dir = dir_name
+                    break
+
+            if target_dir is None:
+                logger.warning("Skill %r not found in workspace", name)
+                return
+
+            skill_dir_path = os.path.join(skills_dir, target_dir)
+            if await self._backend.is_dir(skill_dir_path):
+                await self._backend.delete_path(skill_dir_path)
+                logger.info(
+                    "Removed skill '%s' from %s",
+                    name,
+                    skill_dir_path,
+                )
+            else:
+                logger.warning(
+                    (
+                        "Skill directory %r not found on disk; "
+                        "removing index entry"
+                    ),
+                    skill_dir_path,
+                )
+
+            del existing[target_dir]
+            skills_file["skills"] = existing
+            mtime = await self._backend.stat_mtime(skills_dir)
+            skills_file["skills_dir_mtime"] = (
+                mtime if mtime is not None else 0.0
+            )
+            await self._save_skills_file(skills_dir, skills_file)
diff --git a/src/agentscope/workspace/_mcp_gateway/__init__.py b/src/agentscope/workspace/_mcp_gateway/__init__.py
new file mode 100644
index 0000000..f54f9ad
--- /dev/null
+++ b/src/agentscope/workspace/_mcp_gateway/__init__.py
@@ -0,0 +1,11 @@
+# -*- coding: utf-8 -*-
+"""In-workspace MCP gateway package.
+
+The gateway is a single self-contained script that runs *inside* the
+workspace environment (Docker / E2B). It is copied into the container
+at image build time and executed by the workspace at startup.
+
+The script must remain importable without ``agentscope`` installed —
+the host reads it as raw text via :mod:`importlib.resources` and ships
+it into the container.
+"""
diff --git a/src/agentscope/workspace/_mcp_gateway/__main__.py b/src/agentscope/workspace/_mcp_gateway/__main__.py
new file mode 100644
index 0000000..1405c17
--- /dev/null
+++ b/src/agentscope/workspace/_mcp_gateway/__main__.py
@@ -0,0 +1,14 @@
+# -*- coding: utf-8 -*-
+"""``python -m agentscope.workspace._mcp_gateway`` entry point.
+
+Inside the workspace container the gateway is launched as::
+
+    python -m agentscope.workspace._mcp_gateway --config <path> --port <port>
+
+so this module simply forwards to :func:`_mcp_gateway_app.main`.
+"""
+
+from ._mcp_gateway_app import main
+
+if __name__ == "__main__":
+    main()
diff --git a/src/agentscope/workspace/_mcp_gateway/_mcp_gateway_app.py b/src/agentscope/workspace/_mcp_gateway/_mcp_gateway_app.py
new file mode 100644
index 0000000..8c8ed16
--- /dev/null
+++ b/src/agentscope/workspace/_mcp_gateway/_mcp_gateway_app.py
@@ -0,0 +1,190 @@
+# -*- coding: utf-8 -*-
+"""In-workspace MCP gateway — FastAPI router over agentscope MCPClients.
+
+Runs inside the workspace environment as a standalone script. Reads
+``--config`` — a JSON list of ``MCPClient.model_dump()`` dicts (same
+format as the workspace's ``.mcp`` file) — instantiates one client per
+entry, and exposes per-server HTTP endpoints. No auth: the gateway is
+only reachable via ``backend.exec_shell`` from inside the sandbox.
+
+Endpoints::
+
+    GET    /health
+    GET    /mcps                                # [MCPClient.model_dump(), ...]
+    POST   /mcps                                # body: MCPClient.model_dump()
+    DELETE /mcps/{name}
+    GET    /mcps/{name}/tools
+    POST   /mcps/{name}/tools/{tool}            # body: {arguments: {...}}
+
+The absolute import for ``agentscope.mcp`` avoids loading
+``agentscope.workspace.__init__`` (which pulls in skill/tool trees the
+gateway does not need).
+"""
+
+import argparse
+import asyncio
+import json
+from typing import Any
+
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.responses import PlainTextResponse
+
+from agentscope.mcp import MCPClient
+
+
+class _State:
+    """Mutable runtime state shared by FastAPI routes."""
+
+    def __init__(self) -> None:
+        self.clients: dict[str, MCPClient] = {}
+        self.lock = asyncio.Lock()
+
+
+async def _build_client(spec: dict[str, Any]) -> MCPClient:
+    """Validate a spec into an ``MCPClient``, connect if stateful,
+    and prime its tool cache.
+    """
+    client = MCPClient.model_validate(spec)
+    if client.is_stateful:
+        await client.connect()
+    await client.list_raw_tools()
+    return client
+
+
+def _build_app(state: _State) -> FastAPI:
+    """Build the FastAPI app with all routes wired against ``state``."""
+    app = FastAPI(title="agentscope-workspace-mcp-gateway")
+
+    @app.get("/health")
+    async def _health() -> PlainTextResponse:
+        return PlainTextResponse("ok")
+
+    @app.get("/mcps")
+    async def _list_mcps() -> list[dict[str, Any]]:
+        return [c.model_dump(mode="json") for c in state.clients.values()]
+
+    @app.post("/mcps")
+    async def _add_mcp(request: Request) -> dict[str, Any]:
+        body = await request.json()
+        name = body.get("name", "")
+        if not name:
+            raise HTTPException(400, "name required")
+        async with state.lock:
+            if name in state.clients:
+                raise HTTPException(409, f"{name!r} already exists")
+            try:
+                client = await _build_client(body)
+            except HTTPException:
+                raise
+            except Exception as e:  # noqa: BLE001
+                raise HTTPException(500, f"connect failed: {e}") from e
+            state.clients[name] = client
+        return {"ok": True}
+
+    @app.delete("/mcps/{name}")
+    async def _remove_mcp(name: str) -> dict[str, Any]:
+        async with state.lock:
+            client = state.clients.pop(name, None)
+            if client is None:
+                raise HTTPException(404, f"{name!r} not found")
+            if client.is_stateful and client.is_connected:
+                await client.close()
+        return {"ok": True}
+
+    @app.get("/mcps/{name}/tools")
+    async def _list_tools(name: str) -> list[dict[str, Any]]:
+        client = state.clients.get(name)
+        if client is None:
+            raise HTTPException(404, f"{name!r} not found")
+        raw = await client.list_raw_tools()
+        return [t.model_dump(mode="json") for t in raw]
+
+    @app.post("/mcps/{name}/tools/{tool}")
+    async def _call_tool(
+        name: str,
+        tool: str,
+        request: Request,
+    ) -> dict[str, Any]:
+        client = state.clients.get(name)
+        if client is None:
+            raise HTTPException(404, f"{name!r} not found")
+        body = await request.json()
+        arguments = body.get("arguments") or {}
+        try:
+            tool_obj = await client.get_tool(tool)
+            chunk = await tool_obj(**arguments)
+        except ValueError as e:
+            raise HTTPException(404, str(e)) from e
+        except Exception as e:  # noqa: BLE001
+            raise HTTPException(500, str(e)) from e
+        return {"chunk": chunk.model_dump(mode="json")}
+
+    return app
+
+
+async def _connect_initial(
+    state: _State,
+    server_cfgs: list[dict[str, Any]],
+) -> None:
+    """Connect every server listed in the config file."""
+    for cfg in server_cfgs:
+        client = await _build_client(cfg)
+        if client.name in state.clients:
+            if client.is_stateful and client.is_connected:
+                await client.close()
+            raise ValueError(
+                f"Duplicated server name in config: {client.name!r}",
+            )
+        state.clients[client.name] = client
+        print(f"[gateway] connected {client.name!r}", flush=True)
+
+
+async def _run(config_path: str, port: int) -> None:
+    """Read config, connect upstreams, start uvicorn, clean up on exit."""
+    with open(config_path, encoding="utf-8") as f:
+        servers = json.load(f)
+    if not isinstance(servers, list):
+        raise ValueError(
+            f"config file must be a JSON list of MCPClient specs, "
+            f"got {type(servers).__name__}",
+        )
+
+    state = _State()
+    await _connect_initial(state, servers)
+
+    app = _build_app(state)
+    print(
+        f"[gateway] serving {len(state.clients)} MCPs on :{port}",
+        flush=True,
+    )
+
+    import uvicorn
+
+    uvi_cfg = uvicorn.Config(
+        app,
+        host="127.0.0.1",
+        port=port,
+        log_level="info",
+    )
+    server = uvicorn.Server(uvi_cfg)
+    try:
+        await server.serve()
+    finally:
+        for client in list(state.clients.values()):
+            if client.is_stateful and client.is_connected:
+                await client.close()
+
+
+def main() -> None:
+    """CLI entry point."""
+    parser = argparse.ArgumentParser(
+        description="In-workspace MCP gateway (FastAPI)",
+    )
+    parser.add_argument("--config", required=True)
+    parser.add_argument("--port", type=int, default=5600)
+    args = parser.parse_args()
+    asyncio.run(_run(args.config, args.port))
+
+
+if __name__ == "__main__":
+    main()
diff --git a/src/agentscope/workspace/_offload_protocol.py b/src/agentscope/workspace/_offload_protocol.py
new file mode 100644
index 0000000..93a6ecb
--- /dev/null
+++ b/src/agentscope/workspace/_offload_protocol.py
@@ -0,0 +1,45 @@
+# -*- coding: utf-8 -*-
+"""The offload protocol."""
+from typing import Protocol
+
+from ..message import Msg, ToolResultBlock
+
+
+class Offloader(Protocol):
+    """The offloader protocol."""
+
+    async def offload_context(
+        self,
+        session_id: str,
+        msgs: list[Msg],
+    ) -> str:
+        """Offload compressed context to workspace-accessible storage.
+
+        Args:
+            session_id (`str`):
+                The session id.
+            msgs (`list[Msg]`):
+                The messages to offload.
+
+        Returns:
+            `str`:
+                The offloaded context reference.
+        """
+
+    async def offload_tool_result(
+        self,
+        session_id: str,
+        tool_result: ToolResultBlock,
+    ) -> str:
+        """Offload a tool result to workspace-accessible storage.
+
+        Args:
+            session_id (`str`):
+                The session id.
+            tool_result (`ToolResultBlock`):
+                The tool result.
+
+        Returns:
+            `str`:
+                The offloaded context reference.
+        """
diff --git a/src/agentscope/workspace/_opensandbox/__init__.py b/src/agentscope/workspace/_opensandbox/__init__.py
new file mode 100644
index 0000000..5ed9e0d
--- /dev/null
+++ b/src/agentscope/workspace/_opensandbox/__init__.py
@@ -0,0 +1,12 @@
+# -*- coding: utf-8 -*-
+"""OpenSandbox-backed workspace.
+
+OpenSandbox support follows the E2B remote-sandbox model: one sandbox
+per workspace id, filesystem persistence inside the sandbox, and MCPs
+reached through the in-sandbox gateway.
+"""
+
+from ._opensandbox_backend import OpenSandboxBackend
+from ._opensandbox_workspace import OpenSandboxWorkspace
+
+__all__ = ["OpenSandboxWorkspace", "OpenSandboxBackend"]
diff --git a/src/agentscope/workspace/_opensandbox/_constants.py b/src/agentscope/workspace/_opensandbox/_constants.py
new file mode 100644
index 0000000..5f5f1b2
--- /dev/null
+++ b/src/agentscope/workspace/_opensandbox/_constants.py
@@ -0,0 +1,46 @@
+# -*- coding: utf-8 -*-
+"""Constants for :class:`OpenSandboxWorkspace`, mirroring the E2B and
+K8s ``_constants`` modules.
+
+Only defaults that cannot be derived on the base class live here:
+image, timeouts, gateway port, sandbox metadata key, plus the two
+sandbox-side anchors the workspace must set (``SANDBOX_WORKDIR`` and
+``GATEWAY_HOME``). The bootstrap command sequence and every derived
+path (venv, python, script, glob helper, log) live on the workspace /
+base class, not here.
+"""
+
+#: Default OpenSandbox image. The slim Python image is small but still
+#: has enough package-manager support for installing curl, certificates,
+#: ripgrep, and procps during bootstrap.
+DEFAULT_IMAGE = "python:3.11-slim"
+
+#: Default keep-alive timeout in seconds for newly-created sandboxes.
+DEFAULT_TIMEOUT = 300
+
+#: Per-command timeout for first-time bootstrap shell commands.
+BOOTSTRAP_COMMAND_TIMEOUT = 600.0
+
+#: Default OpenSandbox SDK HTTP timeout in seconds. Bootstrap commands
+#: can legitimately stream for several minutes, so this must not be
+#: shorter than :data:`BOOTSTRAP_COMMAND_TIMEOUT`.
+DEFAULT_REQUEST_TIMEOUT = BOOTSTRAP_COMMAND_TIMEOUT
+
+#: Default port the in-sandbox gateway listens on.
+DEFAULT_GATEWAY_PORT = 5600
+
+# Workspace-side persistent layout. OpenSandbox's default Docker
+# runtime runs the image as root, so the workspace itself can live at a
+# short root-owned path. The data/skills/sessions subdirectories are
+# created by the base class from ``workdir``.
+SANDBOX_WORKDIR = "/workspace"
+
+# Gateway home — the single sandbox-side anchor the workspace must set.
+# The venv, entry script, glob helper, and log paths are all derived
+# from it by the base class.
+GATEWAY_HOME = "/root/.agentscope"
+
+#: Sandbox metadata key used to map workspace_id to sandbox id. The
+#: workspace filters ``list_sandbox_infos`` by this key on cache miss to
+#: locate and resume an existing sandbox.
+METADATA_WORKSPACE_ID_KEY = "agentscope.workspace.id"
diff --git a/src/agentscope/workspace/_opensandbox/_opensandbox_backend.py b/src/agentscope/workspace/_opensandbox/_opensandbox_backend.py
new file mode 100644
index 0000000..fb3f6be
--- /dev/null
+++ b/src/agentscope/workspace/_opensandbox/_opensandbox_backend.py
@@ -0,0 +1,277 @@
+# -*- coding: utf-8 -*-
+"""OpenSandbox :class:`BackendBase` implementation.
+
+Wraps the OpenSandbox SDK's ``commands.run`` and ``files.*`` APIs into
+the three backend primitives (``exec_shell``, ``read_file``,
+``write_file``) so builtin tools can operate inside an OpenSandbox
+sandbox transparently.  All derived filesystem helpers (``file_exists``,
+``is_dir``, ``list_dir``, ``stat_mtime``, ``delete_path``) are inherited
+from :class:`BackendBase`, which implements them via ``exec_shell``.
+"""
+
+from __future__ import annotations
+
+import posixpath
+import shlex
+from datetime import timedelta
+from typing import TYPE_CHECKING, Any
+
+from ...tool import BackendBase, ExecResult
+
+if TYPE_CHECKING:
+    from opensandbox.sandbox import Sandbox
+
+
+class _WriteEntry:
+    """Small SDK-compatible write entry used when the SDK type is absent."""
+
+    def __init__(self, path: str, data: bytes, mode: int) -> None:
+        self.path = path
+        self.data = data
+        self.mode = mode
+
+
+class OpenSandboxBackend(BackendBase):
+    """Backend that delegates to a running OpenSandbox sandbox.
+
+    Only the three abstract primitives (``exec_shell``, ``read_file``,
+    ``write_file``) are implemented here; the derived filesystem
+    helpers are inherited from :class:`BackendBase`.
+
+    Args:
+        sandbox (`Sandbox`):
+            A started / connected ``opensandbox.sandbox.Sandbox`` object.
+        workdir (`str`):
+            Default working directory for ``exec_shell`` calls inside the
+            sandbox.
+    """
+
+    def __init__(self, sandbox: "Sandbox", workdir: str) -> None:
+        """Initialize the OpenSandbox backend.
+
+        Args:
+            sandbox (`Sandbox`):
+                A started / connected ``opensandbox.sandbox.Sandbox``
+                object.
+            workdir (`str`):
+                Default working directory for ``exec_shell`` calls inside
+                the sandbox.
+        """
+        self._sandbox = sandbox
+        self._workdir = workdir
+
+    # ---- exec ---------------------------------------------------------
+
+    async def exec_shell(
+        self,
+        command: list[str],
+        *,
+        cwd: str | None = None,
+        timeout: float | None = None,
+    ) -> ExecResult:
+        """Run a program inside the sandbox via ``commands.run``.
+
+        *command* is an argv list. The OpenSandbox ``commands.run`` API
+        expects a single shell command line, so the argv is POSIX-quoted
+        back into a string before dispatch. Callers needing shell
+        features should pass ``["sh", "-c", line]``.
+
+        Args:
+            command (`list[str]`):
+                Executable path/name followed by its arguments.
+            cwd (`str | None`, optional):
+                Working directory inside the sandbox. When ``None`` the
+                backend's default ``workdir`` is used.
+            timeout (`float | None`, optional):
+                Maximum number of seconds to wait. When ``None`` the SDK
+                default applies.
+
+        Returns:
+            `ExecResult`:
+                The captured exit code, stdout, and stderr. A non-zero
+                command exit is returned as a normal result; transport
+                errors yield an ``exit_code`` of ``-1``.
+        """
+        command_line = " ".join(shlex.quote(arg) for arg in command)
+        opts = self._make_run_opts(cwd=cwd or self._workdir, timeout=timeout)
+        try:
+            res = await self._sandbox.commands.run(command_line, opts=opts)
+            return ExecResult(
+                exit_code=int(getattr(res, "exit_code", 0) or 0),
+                stdout=self._execution_stream_bytes(res, "stdout"),
+                stderr=self._execution_stream_bytes(res, "stderr"),
+            )
+        except Exception as e:  # noqa: BLE001
+            return ExecResult(
+                exit_code=-1,
+                stdout=b"",
+                stderr=str(e).encode("utf-8"),
+            )
+
+    # ---- file I/O -----------------------------------------------------
+
+    async def read_file(self, path: str) -> bytes:
+        """Read a file from the sandbox via ``files.read_bytes``.
+
+        Args:
+            path (`str`):
+                Path to the file inside the sandbox.
+
+        Returns:
+            `bytes`:
+                The raw file contents.
+
+        Raises:
+            `FileNotFoundError`:
+                If the path does not exist inside the sandbox.
+        """
+        try:
+            data = await self._sandbox.files.read_bytes(path)
+        except FileNotFoundError:
+            raise
+        except Exception as exc:  # noqa: BLE001
+            # OpenSandbox surfaces missing files through the HTTP
+            # transport today (httpx.HTTPStatusError with a 404
+            # response). Keep a message fallback for SDK wrappers that
+            # do not expose the response object.
+            if self._is_not_found_error(exc):
+                raise FileNotFoundError(
+                    f"not found in OpenSandbox sandbox: {path}",
+                ) from exc
+            raise
+        return data
+
+    async def write_file(self, path: str, data: bytes) -> None:
+        """Write raw bytes to a file inside the sandbox.
+
+        Creates parent directories via ``exec_shell`` first.
+
+        Args:
+            path (`str`):
+                Destination path inside the sandbox.
+            data (`bytes`):
+                The raw bytes to write.
+        """
+        parent = posixpath.dirname(path)
+        if parent:
+            await self.exec_shell(["mkdir", "-p", parent])
+
+        entry = self._make_write_entry(path, data)
+        await self._sandbox.files.write_files([entry])
+
+    @staticmethod
+    def _make_write_entry(path: str, data: bytes) -> Any:
+        """Build a binary-safe OpenSandbox write entry.
+
+        The implementation prefers the real
+        ``opensandbox.models.filesystem.WriteEntry`` type
+        when available, but falls back to a tiny local adapter to avoid
+        hard dependency on the SDK during tests.
+
+        Args:
+            path (`str`):
+                Destination path inside the sandbox.
+            data (`bytes`):
+                Raw bytes to write.
+
+        Returns:
+            `Any`:
+                A write entry object suitable for ``files.write_files``.
+        """
+        try:
+            from opensandbox.models.filesystem import WriteEntry
+
+            return WriteEntry(path=path, data=data, mode=0o644)
+        except Exception:  # noqa: BLE001
+            return _WriteEntry(path=path, data=data, mode=0o644)
+
+    @staticmethod
+    def _make_run_opts(cwd: str, timeout: float | None) -> Any:
+        """Build SDK command options, falling back to a test adapter."""
+        try:
+            from opensandbox.models.execd import RunCommandOpts
+
+            return RunCommandOpts(
+                working_directory=cwd,
+                timeout=(
+                    timedelta(seconds=timeout) if timeout is not None else None
+                ),
+            )
+        except Exception:  # noqa: BLE001
+            return type(
+                "RunCommandOpts",
+                (),
+                {
+                    "working_directory": cwd,
+                    "timeout": (
+                        timedelta(seconds=timeout)
+                        if timeout is not None
+                        else None
+                    ),
+                },
+            )()
+
+    @classmethod
+    def _is_not_found_error(cls, exc: BaseException) -> bool:
+        """Return whether an SDK/transport exception means HTTP 404."""
+        if cls._status_code(exc) == 404:
+            return True
+
+        for chained in (exc.__cause__, exc.__context__):
+            if chained is not None and chained is not exc:
+                if cls._is_not_found_error(chained):
+                    return True
+
+        return "not found" in str(exc).lower()
+
+    @staticmethod
+    def _status_code(exc: BaseException) -> int | None:
+        """Extract a response/status code from common SDK error shapes."""
+        response = getattr(exc, "response", None)
+        status_code = getattr(response, "status_code", None)
+        if status_code is None:
+            status_code = getattr(exc, "status_code", None)
+        if status_code is None:
+            return None
+        try:
+            return int(status_code)
+        except (TypeError, ValueError):
+            return None
+
+    @staticmethod
+    def _execution_stream_bytes(res: Any, stream: str) -> bytes:
+        """Extract stdout/stderr bytes from real or test execution shapes.
+
+        The real SDK returns an ``Execution`` with accumulated
+        ``logs.stdout`` / ``logs.stderr`` entries. Some unit tests use a
+        simpler direct ``stdout`` / ``stderr`` shape to mirror E2B-style
+        command results, so this helper normalizes both.
+        """
+        direct = getattr(res, stream, None)
+        if direct is not None:
+            if isinstance(direct, bytes):
+                return direct
+            return str(direct).encode("utf-8")
+
+        logs = getattr(res, "logs", None)
+        messages = getattr(logs, stream, []) if logs is not None else []
+        parts = [str(getattr(msg, "text", msg) or "") for msg in messages]
+        text = ""
+        for part in parts:
+            if text and part:
+                previous_is_tight = (
+                    not text.endswith(
+                        ("\n", "\r"),
+                    )
+                    and not text[-1].isspace()
+                )
+                next_is_tight = (
+                    not part.startswith(
+                        ("\n", "\r"),
+                    )
+                    and not part[0].isspace()
+                )
+                if previous_is_tight and next_is_tight:
+                    text += "\n"
+            text += part
+        return text.encode("utf-8")
diff --git a/src/agentscope/workspace/_opensandbox/_opensandbox_workspace.py b/src/agentscope/workspace/_opensandbox/_opensandbox_workspace.py
new file mode 100644
index 0000000..fbb5e06
--- /dev/null
+++ b/src/agentscope/workspace/_opensandbox/_opensandbox_workspace.py
@@ -0,0 +1,403 @@
+# -*- coding: utf-8 -*-
+"""OpenSandboxWorkspace -- sandboxed workspace backed by OpenSandbox."""
+
+from __future__ import annotations
+
+import asyncio
+from datetime import timedelta
+import shlex
+from typing import TYPE_CHECKING, Literal
+
+from ..._logging import logger
+from ...mcp import MCPClient
+from .._sandboxed_base import SandboxedWorkspaceBase
+from .._utils import _GATEWAY_BASE_REQUIREMENTS
+from ._constants import (
+    DEFAULT_GATEWAY_PORT,
+    DEFAULT_IMAGE,
+    BOOTSTRAP_COMMAND_TIMEOUT,
+    DEFAULT_REQUEST_TIMEOUT,
+    DEFAULT_TIMEOUT,
+    GATEWAY_HOME,
+    METADATA_WORKSPACE_ID_KEY,
+    SANDBOX_WORKDIR,
+)
+from ._opensandbox_backend import OpenSandboxBackend
+
+if TYPE_CHECKING:
+    from opensandbox import Sandbox
+    from opensandbox.config.connection import ConnectionConfig
+    from opensandbox.models.sandboxes import (
+        NetworkPolicy,
+        SandboxInfo,
+    )
+
+
+_DEFAULT_INSTRUCTIONS = """<workspace>
+You have an OpenSandbox-based workspace. All tool calls execute **inside
+the sandbox** at ``{workdir}``.
+
+Layout:
+
+```
+{workdir}
+├── data/        # offloaded multimodal files
+├── skills/      # reusable skills
+└── sessions/    # session context and tool results
+```
+</workspace>"""
+
+
+class OpenSandboxWorkspace(SandboxedWorkspaceBase):
+    """Workspace backed by an OpenSandbox sandbox.
+
+    ``default_mcps`` and ``skill_paths`` are seed-time inputs and are
+    not retained as instance state past :meth:`initialize`.
+    """
+
+    _gateway_home = GATEWAY_HOME
+    # The slim base image streams apt-get + uv + pip for several
+    # minutes on first bootstrap, so cap each bootstrap command at the
+    # same budget the SDK HTTP layer is configured for.
+    _bootstrap_cmd_timeout = BOOTSTRAP_COMMAND_TIMEOUT
+
+    def __init__(
+        self,
+        *,
+        workspace_id: str | None = None,
+        image: str = DEFAULT_IMAGE,
+        api_key: str = "",
+        domain: str = "",
+        protocol: Literal["http", "https"] = "http",
+        request_timeout_seconds: float | None = DEFAULT_REQUEST_TIMEOUT,
+        timeout_seconds: int = DEFAULT_TIMEOUT,
+        gateway_port: int = DEFAULT_GATEWAY_PORT,
+        env: dict[str, str] | None = None,
+        sandbox_metadata: dict[str, str] | None = None,
+        resource: dict[str, str] | None = None,
+        entrypoint: list[str] | None = None,
+        network_policy: NetworkPolicy | None = None,
+        extra_pip: list[str] | None = None,
+        instructions: str = _DEFAULT_INSTRUCTIONS,
+        default_mcps: list[MCPClient] | None = None,
+        skill_paths: list[str] | None = None,
+    ) -> None:
+        """Construct an :class:`OpenSandboxWorkspace`.
+
+        The sandbox is *not* started here — call :meth:`initialize`
+        (or use the workspace as an ``async`` context manager).
+
+        Args:
+            workspace_id (`str | None`, optional):
+                Stable identifier; also stored in sandbox metadata for
+                reattachment.
+            image (`str`, defaults to `DEFAULT_IMAGE`):
+                OpenSandbox image used when creating a fresh sandbox.
+            api_key (`str`, defaults to `""`):
+                OpenSandbox API key (``""`` lets the SDK use its
+                environment fallback).
+            domain (`str`, defaults to `""`):
+                Optional OpenSandbox server domain.
+            protocol (`str`, defaults to `"http"`):
+                Protocol to use (http/https)
+            request_timeout_seconds (`float | None`, optional):
+                SDK HTTP request timeout. ``None`` leaves the SDK
+                default in effect.
+            timeout_seconds (`int`, defaults to `DEFAULT_TIMEOUT`):
+                Sandbox keep-alive and create/connect/resume timeout.
+            gateway_port (`int`, defaults to `DEFAULT_GATEWAY_PORT`):
+                TCP port the in-sandbox gateway listens on.
+            env (`dict[str, str] | None`, optional):
+                Environment variables baked into newly-created sandboxes.
+            sandbox_metadata (`dict[str, str] | None`, optional):
+                Extra metadata merged with the workspace-id tag.
+            resource (`dict[str, str] | None`, optional):
+                OpenSandbox resource hints for newly-created sandboxes.
+            entrypoint (`list[str] | None`, optional):
+                Entrypoint override for newly-created sandboxes.
+            network_policy (`NetworkPolicy | None`, optional):
+                Creation-time OpenSandbox network policy. Runtime egress
+                mutation is intentionally left to a follow-up.
+            extra_pip (`list[str] | None`, optional):
+                Extra Python packages installed into the gateway venv
+                during bootstrap.
+            instructions (`str`, defaults to `_DEFAULT_INSTRUCTIONS`):
+                System-prompt fragment template (supports ``{workdir}``).
+            default_mcps (`list[MCPClient] | None`, optional):
+                MCPs registered on first init when no persisted
+                ``.mcp`` exists.
+            skill_paths (`list[str] | None`, optional):
+                Local skill dirs seeded into ``skills/`` on first init.
+        """
+        super().__init__(
+            workspace_id=workspace_id,
+            default_mcps=default_mcps,
+            skill_paths=skill_paths,
+        )
+        self.workdir = SANDBOX_WORKDIR
+        self.image = image
+        self.api_key = api_key
+        self.domain = domain
+        self.protocol = protocol
+        self.request_timeout_seconds = request_timeout_seconds
+        self.timeout_seconds = timeout_seconds
+        self.gateway_port = gateway_port
+        self.env = dict(env or {})
+        self.sandbox_metadata = dict(sandbox_metadata or {})
+        self.resource = dict(resource or {})
+        self.entrypoint = list(entrypoint or [])
+        self.network_policy = network_policy
+        self.extra_pip = list(extra_pip or [])
+        self.instructions = instructions
+
+        self._sandbox: Sandbox | None = None
+        self._backend: OpenSandboxBackend | None = None
+
+    @property
+    def sandbox_id(self) -> str | None:
+        """OpenSandbox sandbox id, or ``None`` before initialize."""
+        return self._sandbox.id if self._sandbox else None
+
+    async def _provision_backend(self) -> None:
+        """Reattach or create the sandbox and bind the backend.
+
+        First-time bootstrap (uv → gateway venv → agentscope → gateway
+        script upload) is driven by
+        :meth:`SandboxedWorkspaceBase._setup_mcp_gateway` once
+        ``initialize`` has bound the backend and created the workspace
+        layout (which lays down ``workdir`` / ``_gateway_home`` first),
+        so this hook only has to attach or create the sandbox. Every
+        bootstrap step is idempotent, so an interrupted bootstrap
+        re-runs cleanly on the next ``initialize``.
+        """
+        existing = await self._find_existing_sandbox()
+        if existing is not None:
+            self._sandbox = await self._attach_existing_sandbox(existing)
+        else:
+            self._sandbox = await self._create_sandbox()
+        await self._wait_until_running()
+
+        self._backend = OpenSandboxBackend(self._sandbox, SANDBOX_WORKDIR)
+
+    async def _teardown_backend(self) -> None:
+        """Pause the sandbox (keep filesystem) and drop the handle.
+
+        ``sandbox.pause()`` — not ``kill()`` — so the next
+        :meth:`initialize` can reattach via metadata lookup and
+        resume. Errors are swallowed.
+        """
+        if self._sandbox is not None:
+            try:
+                await self._sandbox.pause()
+            except Exception as exc:
+                logger.warning("OpenSandboxWorkspace: pause failed: %s", exc)
+            try:
+                await self._sandbox.close()
+            except Exception as exc:
+                logger.warning(
+                    "OpenSandboxWorkspace: local close failed: %s",
+                    exc,
+                )
+            self._sandbox = None
+
+    async def get_instructions(self) -> str:
+        """Return the system-prompt fragment for this workspace.
+
+        Substitutes ``{workdir}`` in the configured template with
+        the sandbox-side path (``/workspace``). The agent always sees
+        sandbox-internal paths.
+        """
+        return self.instructions.format(workdir=SANDBOX_WORKDIR)
+
+    def _connection_config(self) -> ConnectionConfig:
+        """Build OpenSandbox connection config on demand."""
+        from opensandbox.config.connection import ConnectionConfig
+
+        kwargs: dict = {"protocol": self.protocol}
+        if self.api_key:
+            kwargs["api_key"] = self.api_key
+        if self.domain:
+            kwargs["domain"] = self.domain
+        if self.request_timeout_seconds is not None:
+            kwargs["request_timeout"] = timedelta(
+                seconds=self.request_timeout_seconds,
+            )
+        return ConnectionConfig(**kwargs)
+
+    async def _find_existing_sandbox(self) -> SandboxInfo | None:
+        """Return the most recent sandbox matching this workspace id."""
+        from opensandbox.models.sandboxes import SandboxFilter
+        from opensandbox import SandboxManager
+
+        manager = await SandboxManager.create(
+            connection_config=self._connection_config(),
+        )
+        sandbox_filter = SandboxFilter(
+            states=["RUNNING", "PAUSED"],
+            metadata={METADATA_WORKSPACE_ID_KEY: self.workspace_id},
+        )
+        try:
+            infos = await manager.list_sandbox_infos(sandbox_filter)
+        finally:
+            try:
+                await manager.close()
+            except Exception as exc:  # noqa: BLE001
+                logger.warning(
+                    "OpenSandboxWorkspace: manager close failed: %s",
+                    exc,
+                )
+        candidates = infos.sandbox_infos
+        if not candidates:
+            return None
+        if len(candidates) > 1:
+            logger.warning(
+                "OpenSandboxWorkspace: %d sandboxes match workspace_id=%r; "
+                "attaching to most recent",
+                len(candidates),
+                self.workspace_id,
+            )
+        candidates.sort(key=lambda item: item.created_at, reverse=True)
+        return candidates[0]
+
+    async def _create_sandbox(self) -> Sandbox:
+        """Create a fresh sandbox with workspace metadata applied."""
+        from opensandbox import Sandbox
+
+        kwargs: dict = {
+            "image": self.image,
+            "connection_config": self._connection_config(),
+            "metadata": {
+                **self.sandbox_metadata,
+                METADATA_WORKSPACE_ID_KEY: self.workspace_id,
+            },
+            "timeout": timedelta(seconds=self.timeout_seconds),
+            "ready_timeout": timedelta(seconds=self.timeout_seconds),
+        }
+        if self.env:
+            kwargs["env"] = self.env
+        if self.resource:
+            kwargs["resource"] = self.resource
+        if self.entrypoint:
+            kwargs["entrypoint"] = self.entrypoint
+        if self.network_policy is not None:
+            kwargs["network_policy"] = self.network_policy
+        return await Sandbox.create(**kwargs)
+
+    async def _attach_existing_sandbox(self, info: SandboxInfo) -> Sandbox:
+        """Connect or resume depending on the OpenSandbox info state."""
+        from opensandbox import Sandbox
+
+        state = info.status.state.lower()
+
+        if state == "paused":
+            return await Sandbox.resume(
+                sandbox_id=info.id,
+                connection_config=self._connection_config(),
+                resume_timeout=timedelta(seconds=self.timeout_seconds),
+            )
+
+        if state == "running":
+            return await Sandbox.connect(
+                sandbox_id=info.id,
+                connection_config=self._connection_config(),
+                connect_timeout=timedelta(seconds=self.timeout_seconds),
+            )
+
+        raise RuntimeError(
+            f"OpenSandbox sandbox {info.id!r} is not attachable "
+            f"(state={state!r})",
+        )
+
+    async def _wait_until_running(self, timeout: float = 30.0) -> None:
+        """Poll until the sandbox reports healthy.
+
+        ``Sandbox.create`` / ``Sandbox.connect`` / ``Sandbox.resume``
+        normally perform their own readiness checks, but a freshly
+        created, connected, or resumed sandbox may still briefly reject
+        command / filesystem calls while the service endpoint settles.
+        We poll the SDK health probe, treating transient SDK errors as
+        "not yet" and retrying until the timeout.
+
+        Args:
+            timeout (`float`, defaults to `30.0`):
+                Hard ceiling in seconds. Raises :class:`RuntimeError`
+                if the sandbox is still not healthy after this long.
+        """
+        if hasattr(self._sandbox, "is_running"):
+            probe = self._sandbox.is_running
+            probe_name = "is_running"
+        elif hasattr(self._sandbox, "is_healthy"):
+            probe = self._sandbox.is_healthy
+            probe_name = "is_healthy"
+        else:
+            # The real SDK create/connect/resume calls perform readiness
+            # checks before returning; older/mocked SDK shapes may not expose
+            # an extra probe.
+            return
+
+        deadline = asyncio.get_event_loop().time() + timeout
+        delay = 0.1
+        while asyncio.get_event_loop().time() < deadline:
+            try:
+                if await probe():
+                    return
+            except Exception as exc:
+                logger.debug(
+                    "OpenSandboxWorkspace: %s probe error (will retry): %s",
+                    probe_name,
+                    exc,
+                )
+            await asyncio.sleep(delay)
+            delay = min(delay * 1.5, 1.0)
+        raise RuntimeError(
+            f"OpenSandbox sandbox did not become ready within {timeout}s "
+            f"(workspace_id={self.workspace_id!r})",
+        )
+
+    def _bootstrap_commands(self) -> list[str]:
+        """Return the provisioning shell command sequence.
+
+        Called once by :meth:`SandboxedWorkspaceBase._setup_mcp_gateway`
+        when the gateway script is missing (fresh sandbox, or a prior
+        bootstrap that was interrupted before the script was written).
+        The base class runs each command with
+        :attr:`_bootstrap_cmd_timeout` and then uploads the glob helper
+        and gateway script itself, so this hook only builds the command
+        list.
+
+        The workspace layout (``data/``, ``skills/``, ``sessions/``,
+        gateway home) is created by the base class
+        :meth:`_ensure_workspace_layout` before bootstrap runs, so
+        bootstrap only installs the runtime. ``uv`` lands at
+        ``/usr/local/bin`` (on the default PATH, root needs no sudo) and
+        is invoked bare, matching K8s/E2B.
+
+        Returns:
+            A list of shell command strings, to be executed in order. Each
+            must exit 0; a non-zero exit aborts bootstrap.
+        """
+        pip_pkgs = list(_GATEWAY_BASE_REQUIREMENTS) + list(self.extra_pip)
+        # Quote every requirement so entries with spaces or shell
+        # metacharacters cannot break ``sh -c`` or inject inside the sandbox.
+        pip_args = " ".join(shlex.quote(p) for p in pip_pkgs)
+
+        return [
+            # 1. System packages used by bootstrap and builtin tools. The
+            # default image runs as root, so no sudo is needed. ``procps``
+            # backs gateway-process cleanup; ``ripgrep`` backs the Grep tool.
+            "apt-get update -qq "
+            "&& apt-get install -y --no-install-recommends curl "
+            "ca-certificates procps ripgrep "
+            "&& rm -rf /var/lib/apt/lists/*",
+            # 2. Astral uv → /usr/local/bin (on PATH). INSTALLER_NO_MODIFY_PATH
+            # suppresses shell rc edits.
+            "curl -LsSf https://astral.sh/uv/install.sh "
+            "| env UV_INSTALL_DIR=/usr/local/bin "
+            "INSTALLER_NO_MODIFY_PATH=1 sh",
+            # 3. Gateway venv + base requirements + agentscope from PyPI.
+            # ``uv venv`` creates the gateway home as a parent dir.
+            f"uv venv {self._gateway_venv}",
+            f"uv pip install --python {self._gateway_python} {pip_args}",
+            f"uv pip install --python {self._gateway_python} "
+            f"--no-deps 'agentscope'",
+        ]
diff --git a/src/agentscope/workspace/_sandboxed_base.py b/src/agentscope/workspace/_sandboxed_base.py
new file mode 100644
index 0000000..279c10c
--- /dev/null
+++ b/src/agentscope/workspace/_sandboxed_base.py
@@ -0,0 +1,454 @@
+# -*- coding: utf-8 -*-
+"""SandboxedWorkspaceBase — shared implementation for gateway-backed
+sandbox workspaces (Docker, E2B, K8s, …).
+
+Extends :class:`WorkspaceBase` with a template-method lifecycle around
+an in-sandbox MCP gateway. Subclasses only need to provide:
+
+- :meth:`_provision_backend` — attach/create the sandbox, bind
+  ``self._backend``.
+- :meth:`_teardown_backend` — destroy/pause the sandbox.
+- :meth:`_bootstrap_commands` — shell commands to install the gateway
+  venv on first use (Docker skips this — the image already has it).
+- gateway-path class attributes (see below).
+
+Everything gateway-related — bootstrap, launch, health poll, MCP
+add/remove routing, ``.mcp`` persistence, reset — lives here.
+"""
+
+import asyncio
+import json
+import shlex
+from abc import abstractmethod
+
+from .._logging import logger
+from ..mcp import MCPClient
+from ._base import WorkspaceBase
+from ._gateway_client import GatewayClient
+from ._utils import (
+    DEFAULT_GATEWAY_LOG,
+    DEFAULT_GATEWAY_SCRIPT,
+    DEFAULT_GATEWAY_VENV,
+    DEFAULT_GLOB_HELPER_SCRIPT,
+    _read_gateway_script_bytes,
+    _read_glob_helper_bytes,
+)
+
+
+class SandboxedWorkspaceBase(WorkspaceBase):
+    """Base class for workspaces backed by an in-sandbox MCP gateway.
+
+    Subclasses only need to set:
+
+    - :attr:`workdir` — agent-visible root inside the sandbox.
+    - :attr:`_gateway_home` — directory holding the venv, script, log.
+    - :attr:`gateway_port` — TCP port the gateway listens on.
+
+    Every other gateway path (venv, python, script, log, glob helper)
+    is derived from :attr:`_gateway_home` via
+    :meth:`BackendBase.join_path`.
+    """
+
+    workdir: str
+    """Agent-visible root directory for workspace file operations."""
+
+    gateway_port: int
+    """TCP port the in-sandbox gateway listens on."""
+
+    _gateway_home: str
+    """Sandbox-side directory holding the gateway venv, script, log."""
+
+    _gateway: GatewayClient | None
+    """Workspace-side gateway facade. ``None`` before init / after close."""
+
+    _bootstrap_cmd_timeout: float = 1800.0
+    """Per-command timeout applied to every :meth:`_setup_mcp_gateway`
+    bootstrap step. Subclasses lower this for lighter base images
+    (E2B uses 600 s; K8s inherits the wider default for apt-get).
+    """
+
+    @property
+    def _gateway_venv(self) -> str:
+        """Sandbox-side path of the gateway venv root."""
+        return self.get_backend().join_path(
+            self._gateway_home,
+            DEFAULT_GATEWAY_VENV,
+        )
+
+    @property
+    def _gateway_python(self) -> str:
+        """Sandbox-side path of the gateway venv python interpreter."""
+        return self.get_backend().join_path(
+            self._gateway_venv,
+            "bin",
+            "python",
+        )
+
+    @property
+    def _gateway_script(self) -> str:
+        """Sandbox-side path of the gateway entry script."""
+        return self.get_backend().join_path(
+            self._gateway_home,
+            DEFAULT_GATEWAY_SCRIPT,
+        )
+
+    @property
+    def _gateway_log(self) -> str:
+        """Sandbox-side path of the gateway stdout/stderr log."""
+        return self.get_backend().join_path(
+            self._gateway_home,
+            DEFAULT_GATEWAY_LOG,
+        )
+
+    @property
+    def _glob_helper_path(self) -> str:
+        """Standalone glob helper script used by the builtin Glob tool."""
+        return self.get_backend().join_path(
+            self._gateway_home,
+            DEFAULT_GLOB_HELPER_SCRIPT,
+        )
+
+    def __init__(
+        self,
+        *,
+        workspace_id: str | None = None,
+        default_mcps: list[MCPClient] | None = None,
+        skill_paths: list[str] | None = None,
+    ) -> None:
+        """Initialise sandbox-workspace state.
+
+        Args:
+            workspace_id (`str | None`, optional):
+                Existing identifier; ``None`` mints a fresh UUID.
+            default_mcps (`list[MCPClient] | None`, optional):
+                MCPs registered when no persisted ``.mcp`` exists.
+            skill_paths (`list[str] | None`, optional):
+                Local skill dirs seeded on first start.
+        """
+        super().__init__(
+            workspace_id=workspace_id,
+            default_mcps=default_mcps,
+            skill_paths=skill_paths,
+        )
+        self._gateway = None
+
+    # ── subclass hooks ────────────────────────────────────────────
+
+    @abstractmethod
+    async def _provision_backend(self) -> None:
+        """Provision the sandbox and bind ``self._backend``.
+
+        Called once per :meth:`initialize`. Must leave ``self._backend``
+        as a live :class:`BackendBase` ready for
+        ``exec_shell`` / ``write_file`` / ``read_file``.
+        """
+
+    @abstractmethod
+    async def _teardown_backend(self) -> None:
+        """Destroy or pause the sandbox.
+
+        Called once per :meth:`close`, after the gateway facade has
+        been closed. Must be idempotent and swallow exceptions.
+        """
+
+    def _bootstrap_commands(self) -> list[str]:
+        """Shell commands that provision the gateway venv on first use.
+
+        Runs only when :attr:`_gateway_script` is missing. Subclasses
+        whose image already ships the venv (e.g. Docker) leave this
+        empty; the base's fast-path skips the whole bootstrap block.
+        """
+        return []
+
+    # ── lifecycle template methods ────────────────────────────────
+
+    async def initialize(self) -> None:
+        """Provision the sandbox, restore MCPs, start the gateway.
+
+        Idempotent — a no-op when already alive.
+        """
+        logger.info(
+            "Initialize workspace (id=%s) from %s ...",
+            self.workspace_id,
+            self.__class__.__name__,
+        )
+
+        if self.is_alive:
+            return
+
+        # Set up the backend connection
+        await self._provision_backend()
+        assert (
+            self._backend is not None
+        ), "_provision_backend must set self._backend before returning"
+
+        # Set up the workspace layout
+        await self._ensure_workspace_layout()
+
+        # Set up the MCP gateway server
+        await self._setup_mcp_gateway()
+
+        # Set up the skills if not exists
+        await self._setup_skills()
+
+        self.is_alive = True
+
+        logger.info(
+            "Finished initializing workspace (id=%s) from %s.",
+            self.workspace_id,
+            self.__class__.__name__,
+        )
+
+    async def close(self) -> None:
+        """Close the gateway facade, then tear down the sandbox.
+
+        Idempotent — errors are swallowed so ``close`` is always
+        safe to call.
+        """
+        if self._gateway is not None:
+            try:
+                await self._gateway.aclose()
+            except Exception:
+                pass
+            self._gateway = None
+
+        try:
+            await self._teardown_backend()
+        finally:
+            self._backend = None
+            self.is_alive = False
+
+    async def reset(self) -> None:
+        """Wipe workspace state; keep the sandbox and gateway alive.
+
+        Deregisters every MCP from the gateway, clears local handles,
+        and wipes ``.mcp``, ``skills/``, ``sessions/``, and ``data/``.
+        ``default_mcps`` / ``skill_paths`` are not re-seeded.
+        """
+        backend = self.get_backend()
+        async with self._mcp_lock, self._skill_lock:
+            for mcp in list(self._mcps):
+                try:
+                    await mcp.close()
+                except Exception as e:
+                    logger.warning(
+                        "MCP %r close failed during reset: %s",
+                        mcp.name,
+                        e,
+                    )
+            self._mcps = []
+
+            for path in (
+                self._sessions_dir,
+                self._data_dir,
+                self._skills_dir,
+            ):
+                await backend.delete_path(path)
+
+            # Empty out .mcp so a restart won't fall back to default_mcps.
+            await self._save_mcp_file()
+
+    # ── MCP management (gateway-routed) ───────────────────────────
+
+    async def list_mcps(self) -> list[MCPClient]:
+        """Gateway-wrapped MCP handles, one per registered MCP."""
+        return list(self._mcps)
+
+    async def add_mcp(self, mcp_client: MCPClient) -> None:
+        """Register a new MCP server through the in-sandbox gateway.
+
+        Args:
+            mcp_client (`MCPClient`):
+                The MCP to register.
+
+        Raises:
+            `ValueError`:
+                If an MCP with the same name already exists.
+            `RuntimeError`:
+                If the gateway is not attached or rejects the
+                registration.
+        """
+        if self._gateway is None:
+            raise RuntimeError("Workspace has no MCP gateway attached.")
+        async with self._mcp_lock:
+            if any(m.name == mcp_client.name for m in self._mcps):
+                raise ValueError(
+                    f"MCP {mcp_client.name!r} already exists in workspace.",
+                )
+            spec = mcp_client.model_dump(mode="json")
+            gw_client = self._gateway.make_client(spec)
+            await gw_client.connect()
+            self._mcps.append(gw_client)
+            await self._save_mcp_file()
+
+    async def remove_mcp(self, name: str) -> None:
+        """Deregister an MCP server by name.
+
+        Args:
+            name (`str`):
+                MCP name to remove. Unknown names log a warning and
+                return silently.
+
+        Raises:
+            `RuntimeError`:
+                If the gateway is not attached.
+        """
+        if self._gateway is None:
+            raise RuntimeError("Workspace has no MCP gateway attached.")
+        async with self._mcp_lock:
+            for i, mcp in enumerate(self._mcps):
+                if mcp.name == name:
+                    self._mcps.pop(i)
+                    try:
+                        await mcp.close()
+                    except Exception as e:
+                        logger.warning("MCP %r close failed: %s", name, e)
+                    await self._save_mcp_file()
+                    return
+            logger.warning("MCP %r not found in workspace", name)
+
+    # ── workspace layout helpers ──────────────────────────────────
+
+    async def _ensure_workspace_layout(self) -> None:
+        """Create the standard workspace directories inside the sandbox."""
+        backend = self.get_backend()
+        await backend.exec_shell(
+            [
+                "mkdir",
+                "-p",
+                self.workdir,
+                self._data_dir,
+                self._skills_dir,
+                self._sessions_dir,
+                self._gateway_home,
+            ],
+            cwd="/",
+        )
+
+        # Seed ``.mcp`` on first use. If a persisted file already
+        # exists we validate it: a partial/corrupted write (crash mid
+        # ``_save_mcp_file``) would otherwise brick the gateway on the
+        # next startup because it expects a JSON list.  When the
+        # payload is unusable we log and reseed the defaults instead
+        # of failing initialization.
+        payload = json.dumps(
+            [m.model_dump(mode="json") for m in self.default_mcps],
+            indent=2,
+            ensure_ascii=False,
+        ).encode("utf-8")
+
+        if await backend.file_exists(self._mcp_file):
+            try:
+                existing = await backend.read_file(self._mcp_file)
+                parsed = json.loads(existing.decode("utf-8"))
+            except (UnicodeDecodeError, json.JSONDecodeError) as e:
+                logger.warning(
+                    "%s: %s is corrupted (%s); reseeding defaults",
+                    type(self).__name__,
+                    self._mcp_file,
+                    e,
+                )
+            else:
+                if isinstance(parsed, list):
+                    return
+                logger.warning(
+                    "%s: %s does not contain a JSON list "
+                    "(got %s); reseeding defaults",
+                    type(self).__name__,
+                    self._mcp_file,
+                    type(parsed).__name__,
+                )
+        await backend.write_file(self._mcp_file, payload)
+
+    # ── gateway lifecycle helpers ─────────────────────────────────
+
+    async def _setup_mcp_gateway(self) -> None:
+        """Bootstrap (once) and launch the in-sandbox gateway.
+
+        Steps:
+
+        1. Bootstrap the venv + script if :attr:`_gateway_script` is
+           missing (Docker's image already has it → fast-path).
+        2. Kill any leftover gateway from a previous resume.
+        3. Launch a fresh gateway pointed at ``.mcp``.
+        4. Bind :attr:`_gateway` and poll ``/health``.
+        """
+        backend = self.get_backend()
+
+        # Provision the venv + script on first use. Fast-path skips
+        # when the script already exists (Docker image build, E2B
+        # resume, K8s PVC remount).
+        if not await backend.file_exists(self._gateway_script):
+            logger.info(
+                "%s: bootstrapping workspace_id=%r",
+                type(self).__name__,
+                self.workspace_id,
+            )
+            for cmd in self._bootstrap_commands():
+                r = await backend.exec_shell(
+                    ["sh", "-c", cmd],
+                    timeout=self._bootstrap_cmd_timeout,
+                )
+                if not r.ok():
+                    raise RuntimeError(
+                        f"{type(self).__name__} bootstrap failed "
+                        f"(exit {r.exit_code}) for: {cmd!r}\n"
+                        f"stderr: {r.stderr.decode(errors='replace')}\n"
+                        f"stdout: {r.stdout.decode(errors='replace')}",
+                    )
+            # Glob helper first, gateway script last — a partial
+            # bootstrap leaves _gateway_script absent so the next
+            # initialize retries cleanly.
+            if self._glob_helper_path is not None:
+                await backend.write_file(
+                    self._glob_helper_path,
+                    _read_glob_helper_bytes(),
+                )
+            await backend.write_file(
+                self._gateway_script,
+                _read_gateway_script_bytes(),
+            )
+
+        # Launch. ``pkill`` clears any gateway left running by a
+        # previous resume so the new one can bind the port cleanly.
+        # The gateway reads ``.mcp`` directly — no separate config file.
+        launch_cmd = (
+            "pkill -f _mcp_gateway_app.py || true; "
+            f"nohup {shlex.quote(self._gateway_python)} -u "
+            f"{shlex.quote(self._gateway_script)} "
+            f"--config {shlex.quote(self._mcp_file)} "
+            f"--port {self.gateway_port} "
+            f"> {shlex.quote(self._gateway_log)} 2>&1 &"
+        )
+        await backend.exec_shell(["sh", "-c", launch_cmd])
+
+        # Wait for ``/health``; on timeout, tail the gateway log.
+        self._gateway = GatewayClient(
+            backend=backend,
+            gateway_port=self.gateway_port,
+            timeout=30.0,
+            gateway_log_path=self._gateway_log,
+        )
+        health_timeout = 30.0
+        deadline = asyncio.get_event_loop().time() + health_timeout
+        delay = 0.1
+        while asyncio.get_event_loop().time() < deadline:
+            if await self._gateway.health():
+                break
+            await asyncio.sleep(delay)
+            delay = min(delay * 1.5, 1.0)
+        else:
+            try:
+                log = await backend.read_file(self._gateway_log)
+                tail = log[-2000:].decode(errors="replace")
+            except Exception:
+                tail = "<no gateway log available>"
+            raise RuntimeError(
+                f"gateway did not become healthy within {health_timeout}s. "
+                f"Tail of {self._gateway_log}:\n{tail}",
+            )
+
+        # Replace the seed specs with the gateway-side wrappers — same
+        # set, name-for-name — so subsequent list_mcps / add / remove
+        # operate on the live proxies.
+        self._mcps = list(await self._gateway.list_mcps())
diff --git a/src/agentscope/workspace/_utils.py b/src/agentscope/workspace/_utils.py
new file mode 100644
index 0000000..848ea37
--- /dev/null
+++ b/src/agentscope/workspace/_utils.py
@@ -0,0 +1,82 @@
+# -*- coding: utf-8 -*-
+"""Host-side helpers shared by workspace implementations.
+
+Constants for the standard workspace layout, plus pure functions for
+detecting the local ``agentscope`` version and reading scripts bundled
+with the package. No Docker / E2B SDK dependency lives here.
+
+This module is internal to ``agentscope.workspace``. Public-sounding
+constants are shared within the package, not exported as user-facing
+API.
+"""
+
+import importlib.resources as _res
+
+# ── shared constants ───────────────────────────────────────────────
+
+#: Standard workspace-relative directory for offloaded multimodal data.
+DEFAULT_DATA_DIR = "data"
+
+#: Standard workspace-relative directory for reusable skills.
+DEFAULT_SKILLS_DIR = "skills"
+
+#: Standard workspace-relative directory for session context and results.
+DEFAULT_SESSIONS_DIR = "sessions"
+
+#: Standard workspace-relative file for persisted MCP registrations.
+DEFAULT_MCP_FILE = ".mcp"
+
+DEFAULT_GATEWAY_VENV = ".venv"
+DEFAULT_GATEWAY_LOG = "gateway.log"
+DEFAULT_GATEWAY_SCRIPT = "_mcp_gateway_app.py"
+DEFAULT_GLOB_HELPER_SCRIPT = "_glob_helper.py"
+
+#: Minimum Python packages the gateway script needs at runtime.
+#: Both Docker (image build) and E2B (sandbox bootstrap) install this
+#: same tuple into the gateway venv before adding ``agentscope`` itself.
+_GATEWAY_BASE_REQUIREMENTS: tuple[str, ...] = (
+    "mcp",
+    "uvicorn",
+    "fastapi",
+)
+
+
+# ── gateway script ─────────────────────────────────────────────────
+
+
+def _read_gateway_script_bytes() -> bytes:
+    """Read the standalone gateway script as bytes via ``importlib.resources``.
+
+    The script ships at
+    ``agentscope/workspace/_mcp_gateway/_mcp_gateway_app.py``. Both
+    backends copy it to a fixed in-container / in-sandbox path so the
+    launch command can invoke it directly, avoiding ``python -m`` and
+    the heavy ``agentscope.workspace.__init__`` import graph.
+    """
+    return (
+        _res.files("agentscope.workspace._mcp_gateway")
+        .joinpath("_mcp_gateway_app.py")
+        .read_bytes()
+    )
+
+
+# ── builtin tool helper scripts ───────────────────────────────────
+
+
+def _read_glob_helper_bytes() -> bytes:
+    """Read the standalone glob helper script as bytes.
+
+    The script ships at
+    ``agentscope/tool/_builtin/_scripts/_glob_helper.py``. Both Docker
+    and E2B backends copy it into the workspace so the :class:`Glob`
+    tool can invoke it uniformly via ``exec_shell``.
+
+    Returns:
+        `bytes`:
+            The raw contents of the ``_glob_helper.py`` script.
+    """
+    return (
+        _res.files("agentscope.tool._builtin._scripts")
+        .joinpath("_glob_helper.py")
+        .read_bytes()
+    )
diff --git a/tests/agent_basic_test.py b/tests/agent_basic_test.py
new file mode 100644
index 0000000..14b3224
--- /dev/null
+++ b/tests/agent_basic_test.py
@@ -0,0 +1,1391 @@
+# -*- coding: utf-8 -*-
+"""The basic test of the agent class."""
+from typing import Any
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from utils import AnyString, MockModel
+
+from agentscope.agent import Agent
+from agentscope.model import ChatResponse
+from agentscope.tool import (
+    ToolBase,
+    Toolkit,
+    ToolChunk,
+)
+from agentscope.permission import (
+    PermissionDecision,
+    PermissionBehavior,
+    PermissionContext,
+)
+from agentscope.message import TextBlock, ToolCallBlock, UserMsg
+
+
+class MockSequentialTool(ToolBase):
+    """A mock tool that is not concurrency safe (sequential execution)."""
+
+    name: str = "mock_sequential_tool"
+    description: str = "A mock sequential tool for testing"
+    input_schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {
+            "input": {"type": "string", "description": "Input string"},
+        },
+        "required": ["input"],
+    }
+    is_concurrency_safe: bool = False
+    is_read_only: bool = True
+    is_external_tool: bool = False
+    is_mcp: bool = False
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        """Check permissions for the tool usage."""
+        return PermissionDecision(
+            behavior=PermissionBehavior.ALLOW,
+            decision_reason="Mock tool always allows",
+            message="Mock tool always allows",
+        )
+
+    # pylint: disable=redefined-builtin
+    async def __call__(self, input: str, **kwargs: Any) -> ToolChunk:
+        """Execute the tool."""
+        return ToolChunk(
+            content=[TextBlock(text=f"Sequential result: {input}")],
+        )
+
+
+class MockConcurrentTool(ToolBase):
+    """A mock tool that is concurrency safe (concurrent execution)."""
+
+    name: str = "mock_concurrent_tool"
+    description: str = "A mock concurrent tool for testing"
+    input_schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {
+            "input": {"type": "string", "description": "Input string"},
+        },
+        "required": ["input"],
+    }
+    is_concurrency_safe: bool = True
+    is_read_only: bool = True
+    is_external_tool: bool = False
+    is_mcp: bool = False
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        """Check permissions for the tool usage."""
+        return PermissionDecision(
+            behavior=PermissionBehavior.ALLOW,
+            decision_reason="Mock tool always allows",
+            message="Mock tool always allows",
+        )
+
+    # pylint: disable=redefined-builtin
+    async def __call__(self, input: str, **kwargs: Any) -> ToolChunk:
+        """Execute the tool."""
+        return ToolChunk(
+            content=[TextBlock(text=f"Concurrent result: {input}")],
+        )
+
+
+class AgentBasicTest(IsolatedAsyncioTestCase):
+    """The basic test of the agent class."""
+
+    async def asyncSetUp(self) -> None:
+        """The async setup method."""
+        self.model = MockModel()
+        self.agent = Agent(
+            name="Friday",
+            system_prompt="You are a helpful assistant.",
+            model=self.model,
+            toolkit=Toolkit(),
+        )
+
+    def _get_event_base(self, reply_id: str) -> dict:
+        """Get the dict with the basic fields for event assertion."""
+        return {
+            "id": AnyString(),
+            "created_at": AnyString(),
+            "metadata": {},
+            "reply_id": reply_id,
+        }
+
+    def _get_msg_base(self) -> dict:
+        """Get the dict with the basic fields for message assertion."""
+        return {
+            "id": AnyString(),
+            "created_at": AnyString(),
+            "finished_at": None,
+            "metadata": {},
+            "name": "Friday",
+            "role": "assistant",
+            "usage": None,
+        }
+
+    async def test_default_configs_are_not_shared_between_agents(
+        self,
+    ) -> None:
+        """Agents created with defaults own independent config objects."""
+        agent_1 = Agent(
+            name="agent-1",
+            system_prompt="You are agent 1.",
+            model=MockModel(),
+        )
+        agent_2 = Agent(
+            name="agent-2",
+            system_prompt="You are agent 2.",
+            model=MockModel(),
+        )
+
+        self.assertIsNot(agent_1.model_config, agent_2.model_config)
+        self.assertIsNot(agent_1.context_config, agent_2.context_config)
+        self.assertIsNot(agent_1.react_config, agent_2.react_config)
+
+        agent_1.model_config.max_retries = 3
+        agent_1.context_config.tool_result_limit = 123
+        agent_1.react_config.max_iters = 2
+
+        self.assertNotEqual(
+            agent_1.model_config.max_retries,
+            agent_2.model_config.max_retries,
+        )
+        self.assertNotEqual(
+            agent_1.context_config.tool_result_limit,
+            agent_2.context_config.tool_result_limit,
+        )
+        self.assertNotEqual(
+            agent_1.react_config.max_iters,
+            agent_2.react_config.max_iters,
+        )
+
+    async def test_streaming_reasoning(self) -> None:
+        """Test the streaming model inference without tool calls generated,
+        only text in model response.
+
+        Test both the reply and replyStream interfaces.
+        """
+        # Set up mock responses for streaming
+        self.model.set_responses(
+            [
+                [
+                    ChatResponse(
+                        content=[TextBlock(text="Hello")],
+                        is_last=False,
+                    ),
+                    ChatResponse(
+                        content=[TextBlock(text=" world")],
+                        is_last=False,
+                    ),
+                    ChatResponse(content=[TextBlock(text="!")], is_last=False),
+                    ChatResponse(
+                        content=[TextBlock(text="Hello world!")],
+                        is_last=True,
+                    ),
+                ],
+            ],
+        )
+
+        # Test replyStream interface
+        events = []
+        async for event in self.agent.reply_stream(
+            UserMsg(name="user", content="Hi"),
+        ):
+            events.append(event.model_dump())
+
+        # Verify events
+        session_id = self.agent.state.session_id
+        reply_id = self.agent.state.reply_id
+
+        expected_events = [
+            {
+                "type": "REPLY_START",
+                "session_id": session_id,
+                "name": "Friday",
+                "role": "assistant",
+            },
+            {
+                "type": "MODEL_CALL_START",
+                "model_name": "mock-model",
+            },
+            {
+                "type": "TEXT_BLOCK_START",
+                "block_id": AnyString(),
+            },
+            {
+                "type": "TEXT_BLOCK_DELTA",
+                "block_id": AnyString(),
+                "delta": "Hello",
+            },
+            {
+                "type": "TEXT_BLOCK_DELTA",
+                "block_id": AnyString(),
+                "delta": " world",
+            },
+            {
+                "type": "TEXT_BLOCK_DELTA",
+                "block_id": AnyString(),
+                "delta": "!",
+            },
+            {
+                "type": "TEXT_BLOCK_END",
+                "block_id": AnyString(),
+            },
+            {
+                "type": "MODEL_CALL_END",
+                "input_tokens": 0,
+                "output_tokens": 0,
+                "finished_reason": "completed",
+            },
+            {
+                "type": "REPLY_END",
+                "session_id": session_id,
+                "finished_reason": "completed",
+            },
+        ]
+
+        basic_dict = self._get_event_base(reply_id)
+        self.assertListEqual(
+            events,
+            [{**basic_dict, **_} for _ in expected_events],
+        )
+
+        # Assert context after reply_stream
+        msg_base = self._get_msg_base()
+        expected_context = [
+            {
+                **msg_base,
+                "name": "user",
+                "role": "user",
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": "Hi",
+                    },
+                ],
+                "finished_at": AnyString(),
+            },
+            {
+                **msg_base,
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": "Hello world!",
+                    },
+                ],
+            },
+        ]
+        context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+        self.assertListEqual(context_dicts, expected_context)
+
+        # Test reply interface
+        self.model.cnt = 0  # Reset mock model response index
+        msg = await self.agent.reply(UserMsg(name="user", content="Hi again"))
+        self.assertDictEqual(
+            msg.model_dump(),
+            {
+                "name": "Friday",
+                "role": "assistant",
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": "Hello world!",
+                    },
+                ],
+                "created_at": AnyString(),
+                "finished_at": None,
+                "id": AnyString(),
+                "metadata": {},
+                "usage": None,
+            },
+        )
+
+        # Assert context after reply
+        expected_context_after_reply = [
+            {
+                **msg_base,
+                "name": "user",
+                "role": "user",
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": "Hi",
+                    },
+                ],
+                "metadata": {},
+                "finished_at": AnyString(),
+            },
+            {
+                **msg_base,
+                "name": "Friday",
+                "role": "assistant",
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": "Hello world!",
+                    },
+                ],
+                "metadata": {},
+            },
+            {
+                **msg_base,
+                "name": "user",
+                "role": "user",
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": "Hi again",
+                    },
+                ],
+                "metadata": {},
+                "finished_at": AnyString(),
+            },
+            {
+                **msg_base,
+                "name": "Friday",
+                "role": "assistant",
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": "Hello world!",
+                    },
+                ],
+                "metadata": {},
+            },
+        ]
+        context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+        self.assertListEqual(context_dicts, expected_context_after_reply)
+
+    async def test_non_streaming_reasoning(self) -> None:
+        """Test the non-streaming model inference without tool calls generated,
+        only text in model response.
+
+        Test both the reply and replyStream interfaces.
+        """
+        # Set up mock response for non-streaming
+        self.model.set_responses(
+            [
+                ChatResponse(
+                    content=[TextBlock(text="Hello world!")],
+                    is_last=True,
+                    usage=None,
+                ),
+            ],
+        )
+
+        # Test replyStream interface
+        events = []
+        async for event in self.agent.reply_stream(
+            UserMsg(name="user", content="Hi"),
+        ):
+            events.append(event.model_dump())
+
+        # Verify events
+        session_id = self.agent.state.session_id
+        reply_id = self.agent.state.reply_id
+
+        expected_events = [
+            {
+                "type": "REPLY_START",
+                "session_id": session_id,
+                "name": "Friday",
+                "role": "assistant",
+            },
+            {
+                "type": "MODEL_CALL_START",
+                "model_name": "mock-model",
+            },
+            {
+                "type": "TEXT_BLOCK_START",
+                "block_id": AnyString(),
+            },
+            {
+                "type": "TEXT_BLOCK_DELTA",
+                "block_id": AnyString(),
+                "delta": "Hello world!",
+            },
+            {
+                "type": "TEXT_BLOCK_END",
+                "block_id": AnyString(),
+            },
+            {
+                "type": "MODEL_CALL_END",
+                "input_tokens": 0,
+                "output_tokens": 0,
+                "finished_reason": "completed",
+            },
+            {
+                "type": "REPLY_END",
+                "session_id": session_id,
+                "finished_reason": "completed",
+            },
+        ]
+
+        basic_dict = self._get_event_base(reply_id)
+        self.assertListEqual(
+            events,
+            [{**basic_dict, **_} for _ in expected_events],
+        )
+
+        # Assert context after reply_stream
+        msg_base = self._get_msg_base()
+        expected_context = [
+            {
+                **msg_base,
+                "name": "user",
+                "role": "user",
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": "Hi",
+                    },
+                ],
+                "metadata": {},
+                "finished_at": AnyString(),
+            },
+            {
+                **msg_base,
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": "Hello world!",
+                    },
+                ],
+                "metadata": {},
+            },
+        ]
+        context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+        self.assertListEqual(context_dicts, expected_context)
+
+        # Test reply interface
+        self.model.set_responses(
+            [
+                ChatResponse(
+                    content=[TextBlock(text="Hello world!")],
+                    is_last=True,
+                    usage=None,
+                ),
+            ],
+        )
+
+        msg = await self.agent.reply(UserMsg(name="user", content="Hi again"))
+        self.assertDictEqual(
+            msg.model_dump(),
+            {
+                "name": "Friday",
+                "role": "assistant",
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": "Hello world!",
+                    },
+                ],
+                "created_at": AnyString(),
+                "finished_at": None,
+                "id": AnyString(),
+                "metadata": {},
+                "usage": None,
+            },
+        )
+
+        # Assert context after reply
+        expected_context_after_reply = [
+            {
+                **msg_base,
+                "name": "user",
+                "role": "user",
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": "Hi",
+                    },
+                ],
+                "metadata": {},
+                "finished_at": AnyString(),
+            },
+            {
+                **msg_base,
+                "name": "Friday",
+                "role": "assistant",
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": "Hello world!",
+                    },
+                ],
+                "metadata": {},
+            },
+            {
+                **msg_base,
+                "name": "user",
+                "role": "user",
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": "Hi again",
+                    },
+                ],
+                "metadata": {},
+                "finished_at": AnyString(),
+            },
+            {
+                **msg_base,
+                "name": "Friday",
+                "role": "assistant",
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": "Hello world!",
+                    },
+                ],
+                "metadata": {},
+            },
+        ]
+        context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+        self.assertListEqual(context_dicts, expected_context_after_reply)
+
+    async def test_streaming_sequential_tool_calls(self) -> None:
+        """Test the streaming model inference with tool calls generated.
+
+        Test only the replyStream interface. The `is_concurrent_safe` of the
+        registered tools should be False to make sure the tool calls are
+        executed sequentially.
+
+        To assert:
+        1. The events (by assert the dict generated by model_dump)
+        2. The final reply message
+        3. The agent state (Before and after replyStream)
+        """
+        # Register sequential tools
+        seq_tool = MockSequentialTool()
+        self.agent.toolkit = Toolkit(tools=[seq_tool])
+
+        # Create tool call IDs
+        tool_call_id_1 = "tool_call_1"
+        tool_call_id_2 = "tool_call_2"
+
+        # Set up mock responses with tool calls
+        text_block = TextBlock(text="I'll call the tool")
+        tool_call_1 = ToolCallBlock(
+            id=tool_call_id_1,
+            name="mock_sequential_tool",
+            input='{"input": "test1"}',
+        )
+        tool_call_1_part1 = ToolCallBlock(
+            id=tool_call_id_1,
+            name="mock_sequential_tool",
+            input='{"input": ',
+        )
+        tool_call_1_part2 = ToolCallBlock(
+            id=tool_call_id_1,
+            name="mock_sequential_tool",
+            input='"test1"}',
+        )
+        tool_call_2 = ToolCallBlock(
+            id=tool_call_id_2,
+            name="mock_sequential_tool",
+            input='{"input": "test2"}',
+        )
+        self.model.set_responses(
+            [
+                [
+                    ChatResponse(
+                        content=[text_block, tool_call_1_part1],
+                        is_last=False,
+                    ),
+                    ChatResponse(
+                        content=[tool_call_1_part2],
+                        is_last=False,
+                    ),
+                    ChatResponse(
+                        content=[tool_call_2],
+                        is_last=False,
+                    ),
+                    ChatResponse(
+                        content=[text_block, tool_call_1, tool_call_2],
+                        is_last=True,
+                    ),
+                ],
+                [
+                    ChatResponse(
+                        content=[TextBlock(text="ended")],
+                        is_last=False,
+                    ),
+                    ChatResponse(
+                        content=[TextBlock(text="ended")],
+                        is_last=True,
+                    ),
+                ],
+            ],
+        )
+
+        # Collect all events
+        events = []
+        async for event in self.agent.reply_stream(
+            UserMsg(name="user", content="Test"),
+        ):
+            events.append(event.model_dump(mode="json"))
+
+        # Verify events
+        session_id = self.agent.state.session_id
+        reply_id = self.agent.state.reply_id
+
+        # Expected events for sequential tool calls
+        expected_events = [
+            {
+                "type": "REPLY_START",
+                "session_id": session_id,
+                "name": "Friday",
+                "role": "assistant",
+            },
+            {"type": "MODEL_CALL_START", "model_name": "mock-model"},
+            {"type": "TEXT_BLOCK_START", "block_id": AnyString()},
+            {
+                "type": "TEXT_BLOCK_DELTA",
+                "block_id": AnyString(),
+                "delta": "I'll call the tool",
+            },
+            {
+                "type": "TOOL_CALL_START",
+                "tool_call_id": tool_call_id_1,
+                "tool_call_name": "mock_sequential_tool",
+            },
+            {
+                "type": "TOOL_CALL_DELTA",
+                "tool_call_id": tool_call_id_1,
+                "delta": '{"input": ',
+            },
+            {"type": "TEXT_BLOCK_END", "block_id": AnyString()},
+            {
+                "type": "TOOL_CALL_DELTA",
+                "tool_call_id": tool_call_id_1,
+                "delta": '"test1"}',
+            },
+            {
+                "type": "TOOL_CALL_START",
+                "tool_call_id": tool_call_id_2,
+                "tool_call_name": "mock_sequential_tool",
+            },
+            {
+                "type": "TOOL_CALL_DELTA",
+                "tool_call_id": tool_call_id_2,
+                "delta": '{"input": "test2"}',
+            },
+            {"type": "TOOL_CALL_END", "tool_call_id": tool_call_id_1},
+            {"type": "TOOL_CALL_END", "tool_call_id": tool_call_id_2},
+            {
+                "type": "MODEL_CALL_END",
+                "input_tokens": 0,
+                "output_tokens": 0,
+                "finished_reason": "completed",
+            },
+            {
+                "type": "TOOL_RESULT_START",
+                "tool_call_id": tool_call_id_1,
+                "tool_call_name": "mock_sequential_tool",
+            },
+            {
+                "type": "TOOL_RESULT_TEXT_DELTA",
+                "tool_call_id": tool_call_id_1,
+                "delta": "Sequential result: test1",
+            },
+            {
+                "type": "TOOL_RESULT_END",
+                "tool_call_id": tool_call_id_1,
+                "state": "success",
+            },
+            {
+                "type": "TOOL_RESULT_START",
+                "tool_call_id": tool_call_id_2,
+                "tool_call_name": "mock_sequential_tool",
+            },
+            {
+                "type": "TOOL_RESULT_TEXT_DELTA",
+                "tool_call_id": tool_call_id_2,
+                "delta": "Sequential result: test2",
+            },
+            {
+                "type": "TOOL_RESULT_END",
+                "tool_call_id": tool_call_id_2,
+                "state": "success",
+            },
+            {"type": "MODEL_CALL_START", "model_name": "mock-model"},
+            {"type": "TEXT_BLOCK_START", "block_id": AnyString()},
+            {
+                "type": "TEXT_BLOCK_DELTA",
+                "block_id": AnyString(),
+                "delta": "ended",
+            },
+            {"type": "TEXT_BLOCK_END", "block_id": AnyString()},
+            {
+                "type": "MODEL_CALL_END",
+                "input_tokens": 0,
+                "output_tokens": 0,
+                "finished_reason": "completed",
+            },
+            {
+                "type": "REPLY_END",
+                "session_id": session_id,
+                "finished_reason": "completed",
+            },
+        ]
+
+        basic_dict = self._get_event_base(reply_id)
+        self.assertListEqual(
+            events,
+            [{**basic_dict, **_} for _ in expected_events],
+        )
+
+        # Assert context after reply_stream
+        msg_base = self._get_msg_base()
+        expected_context = [
+            {
+                "name": "user",
+                "role": "user",
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": "Test",
+                    },
+                ],
+                "finished_at": AnyString(),
+            },
+            {
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": "I'll call the tool",
+                    },
+                    {
+                        "type": "tool_call",
+                        "id": tool_call_id_1,
+                        "name": "mock_sequential_tool",
+                        "input": '{"input": "test1"}',
+                        "state": "finished",
+                        "suggested_rules": [],
+                    },
+                    {
+                        "type": "tool_call",
+                        "id": tool_call_id_2,
+                        "name": "mock_sequential_tool",
+                        "input": '{"input": "test2"}',
+                        "state": "finished",
+                        "suggested_rules": [],
+                    },
+                    {
+                        "type": "tool_result",
+                        "id": AnyString(),
+                        "output": [
+                            {
+                                "type": "text",
+                                "id": AnyString(),
+                                "text": "Sequential result: test1",
+                            },
+                        ],
+                        "name": "mock_sequential_tool",
+                        "state": "success",
+                        "metadata": {},
+                    },
+                    {
+                        "type": "tool_result",
+                        "id": AnyString(),
+                        "output": [
+                            {
+                                "type": "text",
+                                "id": AnyString(),
+                                "text": "Sequential result: test2",
+                            },
+                        ],
+                        "name": "mock_sequential_tool",
+                        "state": "success",
+                        "metadata": {},
+                    },
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": "ended",
+                    },
+                ],
+            },
+        ]
+
+        context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+        expected_context = [{**msg_base, **_} for _ in expected_context]
+        self.assertListEqual(context_dicts, expected_context)
+
+    async def test_streaming_concurrent_tool_calls(self) -> None:
+        """Test the streaming model inference with tool calls generated.
+
+        Test only the replyStream interface. The `is_concurrent_safe` of the
+        registered tools should be True to make sure the tool calls are
+        executed concurrently.
+
+        To assert:
+        1. The events (by assert the dict generated by model_dump)
+        2. The final reply message
+        3. The agent state (Before and after replyStream)
+        """
+        # Register concurrent tools
+        conc_tool = MockConcurrentTool()
+
+        self.agent.toolkit = Toolkit(
+            tools=[conc_tool],
+        )
+
+        # Create tool call IDs
+        tool_call_id_1 = "tool_call_1"
+        tool_call_id_2 = "tool_call_2"
+
+        # Set up mock responses with tool calls
+        self.model.set_responses(
+            [
+                [
+                    ChatResponse(
+                        content=[
+                            ToolCallBlock(
+                                id=tool_call_id_1,
+                                name="mock_concurrent_tool",
+                                input='{"input": "test1"}',
+                            ),
+                            ToolCallBlock(
+                                id=tool_call_id_2,
+                                name="mock_concurrent_tool",
+                                input='{"input": "test2"}',
+                            ),
+                        ],
+                        is_last=True,
+                        usage=None,
+                    ),
+                ],
+                [
+                    ChatResponse(
+                        content=[TextBlock(text="All done")],
+                        is_last=False,
+                    ),
+                    ChatResponse(
+                        content=[TextBlock(text="All done")],
+                        is_last=True,
+                    ),
+                ],
+            ],
+        )
+
+        # Collect all events
+        events = []
+        async for event in self.agent.reply_stream(
+            UserMsg(name="user", content="Test"),
+        ):
+            events.append(event.model_dump())
+
+        # Verify events
+        session_id = self.agent.state.session_id
+        reply_id = self.agent.state.reply_id
+
+        # For concurrent execution, the order of tool results may vary
+        # Split events into: prefix (before concurrent), concurrent part,
+        # suffix (after concurrent)
+
+        # Expected prefix events (before tool execution)
+        expected_prefix = [
+            {
+                "type": "REPLY_START",
+                "session_id": session_id,
+                "name": "Friday",
+                "role": "assistant",
+            },
+            {"type": "MODEL_CALL_START", "model_name": "mock-model"},
+            {
+                "type": "MODEL_CALL_END",
+                "input_tokens": 0,
+                "output_tokens": 0,
+                "finished_reason": "completed",
+            },
+        ]
+
+        # Expected concurrent events (order may vary)
+        expected_concurrent = [
+            {
+                "type": "TOOL_RESULT_START",
+                "tool_call_id": tool_call_id_1,
+                "tool_call_name": "mock_concurrent_tool",
+            },
+            {
+                "type": "TOOL_RESULT_TEXT_DELTA",
+                "tool_call_id": tool_call_id_1,
+                "delta": "Concurrent result: test1",
+            },
+            {
+                "type": "TOOL_RESULT_END",
+                "tool_call_id": tool_call_id_1,
+                "state": "success",
+            },
+            {
+                "type": "TOOL_RESULT_START",
+                "tool_call_id": tool_call_id_2,
+                "tool_call_name": "mock_concurrent_tool",
+            },
+            {
+                "type": "TOOL_RESULT_TEXT_DELTA",
+                "tool_call_id": tool_call_id_2,
+                "delta": "Concurrent result: test2",
+            },
+            {
+                "type": "TOOL_RESULT_END",
+                "tool_call_id": tool_call_id_2,
+                "state": "success",
+            },
+        ]
+
+        # Expected suffix events (final model call with pure text)
+        expected_suffix = [
+            {"type": "MODEL_CALL_START", "model_name": "mock-model"},
+            {"type": "TEXT_BLOCK_START", "block_id": AnyString()},
+            {
+                "type": "TEXT_BLOCK_DELTA",
+                "block_id": AnyString(),
+                "delta": "All done",
+            },
+            {"type": "TEXT_BLOCK_END", "block_id": AnyString()},
+            {
+                "type": "MODEL_CALL_END",
+                "input_tokens": 0,
+                "output_tokens": 0,
+                "finished_reason": "completed",
+            },
+            {
+                "type": "REPLY_END",
+                "session_id": session_id,
+                "finished_reason": "completed",
+            },
+        ]
+
+        # Assert prefix events (fixed order)
+        basic_dict = self._get_event_base(reply_id)
+        prefix_len = len(expected_prefix)
+        self.assertListEqual(
+            events[:prefix_len],
+            [{**basic_dict, **_} for _ in expected_prefix],
+        )
+
+        # Assert concurrent events (order may vary)
+        concurrent_len = len(expected_concurrent)
+        concurrent_events = events[prefix_len : prefix_len + concurrent_len]
+
+        # Check length matches
+        self.assertEqual(len(concurrent_events), len(expected_concurrent))
+
+        # Check each expected event is in the actual events
+        for expected_event in expected_concurrent:
+            expected_with_base = {**basic_dict, **expected_event}
+            self.assertIn(expected_with_base, concurrent_events)
+
+        # Assert suffix events (fixed order)
+        suffix_events = events[prefix_len + concurrent_len :]
+        self.assertListEqual(
+            suffix_events,
+            [{**basic_dict, **_} for _ in expected_suffix],
+        )
+
+        # Assert context after reply_stream
+        msg_base = self._get_msg_base()
+        expected_context = [
+            {
+                "name": "user",
+                "role": "user",
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": "Test",
+                    },
+                ],
+                "finished_at": AnyString(),
+            },
+            {
+                "content": [
+                    {
+                        "type": "tool_call",
+                        "id": tool_call_id_1,
+                        "name": "mock_concurrent_tool",
+                        "input": '{"input": "test1"}',
+                        "state": "finished",
+                        "suggested_rules": [],
+                    },
+                    {
+                        "type": "tool_call",
+                        "id": tool_call_id_2,
+                        "name": "mock_concurrent_tool",
+                        "input": '{"input": "test2"}',
+                        "state": "finished",
+                        "suggested_rules": [],
+                    },
+                    {
+                        "type": "tool_result",
+                        "id": AnyString(),
+                        "output": [
+                            {
+                                "type": "text",
+                                "id": AnyString(),
+                                "text": "Concurrent result: test1",
+                            },
+                        ],
+                        "name": "mock_concurrent_tool",
+                        "state": "success",
+                        "metadata": {},
+                    },
+                    {
+                        "type": "tool_result",
+                        "id": AnyString(),
+                        "output": [
+                            {
+                                "type": "text",
+                                "id": AnyString(),
+                                "text": "Concurrent result: test2",
+                            },
+                        ],
+                        "name": "mock_concurrent_tool",
+                        "state": "success",
+                        "metadata": {},
+                    },
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": "All done",
+                    },
+                ],
+            },
+        ]
+        context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+        expected_context = [{**msg_base, **_} for _ in expected_context]
+        self.assertListEqual(context_dicts, expected_context)
+
+    async def test_streaming_mixed_tool_calls(self) -> None:
+        """Test the streaming model inference with both sequential and
+        concurrent tool calls generated.
+
+        Test only the replyStream interface.
+
+        To assert:
+        1. The events (by assert the dict generated by model_dump)
+        2. The final reply message
+        3. The agent state (Before and after replyStream)
+        """
+        # Register both sequential and concurrent tools
+        seq_tool = MockSequentialTool()
+        conc_tool = MockConcurrentTool()
+
+        self.agent.toolkit = Toolkit(
+            tools=[seq_tool, conc_tool],
+        )
+
+        # Create tool call IDs
+        tool_call_id_1 = "tool_call_1"
+        tool_call_id_2 = "tool_call_2"
+        tool_call_id_3 = "tool_call_3"
+
+        # Set up mock responses with mixed tool calls
+        self.model.set_responses(
+            [
+                [
+                    ChatResponse(
+                        content=[
+                            ToolCallBlock(
+                                id=tool_call_id_1,
+                                name="mock_sequential_tool",
+                                input='{"input": "seq1"}',
+                            ),
+                            ToolCallBlock(
+                                id=tool_call_id_2,
+                                name="mock_concurrent_tool",
+                                input='{"input": "conc1"}',
+                            ),
+                            ToolCallBlock(
+                                id=tool_call_id_3,
+                                name="mock_concurrent_tool",
+                                input='{"input": "conc2"}',
+                            ),
+                        ],
+                        is_last=True,
+                        usage=None,
+                    ),
+                ],
+                [
+                    ChatResponse(
+                        content=[TextBlock(text="All done")],
+                        is_last=False,
+                    ),
+                    ChatResponse(
+                        content=[TextBlock(text="All done")],
+                        is_last=True,
+                    ),
+                ],
+            ],
+        )
+
+        # Collect all events
+        events = []
+        async for event in self.agent.reply_stream(
+            UserMsg(name="user", content="Test"),
+        ):
+            events.append(event.model_dump())
+
+        # Verify events
+        session_id = self.agent.state.session_id
+        reply_id = self.agent.state.reply_id
+
+        # For mixed execution: sequential tool first, then concurrent tools
+        # Split events into: prefix (before tool execution), sequential part,
+        # concurrent part, suffix (final model call)
+
+        # Expected prefix events (before tool execution)
+        expected_prefix = [
+            {
+                "type": "REPLY_START",
+                "session_id": session_id,
+                "name": "Friday",
+                "role": "assistant",
+            },
+            {"type": "MODEL_CALL_START", "model_name": "mock-model"},
+            {
+                "type": "MODEL_CALL_END",
+                "input_tokens": 0,
+                "output_tokens": 0,
+                "finished_reason": "completed",
+            },
+        ]
+
+        # Expected sequential tool execution events
+        expected_sequential = [
+            {
+                "type": "TOOL_RESULT_START",
+                "tool_call_id": tool_call_id_1,
+                "tool_call_name": "mock_sequential_tool",
+            },
+            {
+                "type": "TOOL_RESULT_TEXT_DELTA",
+                "tool_call_id": tool_call_id_1,
+                "delta": "Sequential result: seq1",
+            },
+            {
+                "type": "TOOL_RESULT_END",
+                "tool_call_id": tool_call_id_1,
+                "state": "success",
+                "metadata": {},
+            },
+        ]
+
+        # Expected concurrent events (order may vary)
+        expected_concurrent: list[dict[str, Any]] = [
+            {
+                "type": "TOOL_RESULT_START",
+                "tool_call_id": tool_call_id_2,
+                "tool_call_name": "mock_concurrent_tool",
+            },
+            {
+                "type": "TOOL_RESULT_TEXT_DELTA",
+                "tool_call_id": tool_call_id_2,
+                "delta": "Concurrent result: conc1",
+            },
+            {
+                "type": "TOOL_RESULT_END",
+                "tool_call_id": tool_call_id_2,
+                "state": "success",
+            },
+            {
+                "type": "TOOL_RESULT_START",
+                "tool_call_id": tool_call_id_3,
+                "tool_call_name": "mock_concurrent_tool",
+            },
+            {
+                "type": "TOOL_RESULT_TEXT_DELTA",
+                "tool_call_id": tool_call_id_3,
+                "delta": "Concurrent result: conc2",
+            },
+            {
+                "type": "TOOL_RESULT_END",
+                "tool_call_id": tool_call_id_3,
+                "state": "success",
+                "metadata": {},
+            },
+        ]
+
+        # Expected suffix events (final model call with pure text)
+        expected_suffix = [
+            {"type": "MODEL_CALL_START", "model_name": "mock-model"},
+            {"type": "TEXT_BLOCK_START", "block_id": AnyString()},
+            {
+                "type": "TEXT_BLOCK_DELTA",
+                "block_id": AnyString(),
+                "delta": "All done",
+            },
+            {"type": "TEXT_BLOCK_END", "block_id": AnyString()},
+            {
+                "type": "MODEL_CALL_END",
+                "input_tokens": 0,
+                "output_tokens": 0,
+                "finished_reason": "completed",
+            },
+            {
+                "type": "REPLY_END",
+                "session_id": session_id,
+                "finished_reason": "completed",
+            },
+        ]
+
+        # Assert prefix events (fixed order)
+        basic_dict = self._get_event_base(reply_id)
+        prefix_len = len(expected_prefix)
+        self.assertListEqual(
+            events[:prefix_len],
+            [{**basic_dict, **_} for _ in expected_prefix],
+        )
+
+        # Assert sequential events (fixed order)
+        sequential_len = len(expected_sequential)
+        self.assertListEqual(
+            events[prefix_len : prefix_len + sequential_len],
+            [{**basic_dict, **_} for _ in expected_sequential],
+        )
+
+        # Assert concurrent events (order may vary)
+        concurrent_len = len(expected_concurrent)
+        concurrent_events = events[
+            prefix_len
+            + sequential_len : prefix_len
+            + sequential_len
+            + concurrent_len
+        ]
+
+        # Check length matches
+        self.assertEqual(len(concurrent_events), len(expected_concurrent))
+
+        # Check each expected event is in the actual events
+        for expected_event in expected_concurrent:
+            expected_with_base = {**basic_dict, **expected_event}
+            self.assertIn(expected_with_base, concurrent_events)
+
+        # Assert suffix events (fixed order)
+        suffix_events = events[prefix_len + sequential_len + concurrent_len :]
+        self.assertListEqual(
+            suffix_events,
+            [{**basic_dict, **_} for _ in expected_suffix],
+        )
+
+        # Assert context after reply_stream
+        msg_base = self._get_msg_base()
+        expected_context = [
+            {
+                "name": "user",
+                "role": "user",
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": "Test",
+                    },
+                ],
+                "finished_at": AnyString(),
+            },
+            {
+                "content": [
+                    {
+                        "type": "tool_call",
+                        "id": tool_call_id_1,
+                        "name": "mock_sequential_tool",
+                        "input": '{"input": "seq1"}',
+                        "state": "finished",
+                        "suggested_rules": [],
+                    },
+                    {
+                        "type": "tool_call",
+                        "id": tool_call_id_2,
+                        "name": "mock_concurrent_tool",
+                        "input": '{"input": "conc1"}',
+                        "state": "finished",
+                        "suggested_rules": [],
+                    },
+                    {
+                        "type": "tool_call",
+                        "id": tool_call_id_3,
+                        "name": "mock_concurrent_tool",
+                        "input": '{"input": "conc2"}',
+                        "state": "finished",
+                        "suggested_rules": [],
+                    },
+                    {
+                        "type": "tool_result",
+                        "id": AnyString(),
+                        "name": "mock_sequential_tool",
+                        "state": "success",
+                        "output": [
+                            {
+                                "type": "text",
+                                "id": AnyString(),
+                                "text": "Sequential result: seq1",
+                            },
+                        ],
+                        "metadata": {},
+                    },
+                    {
+                        "type": "tool_result",
+                        "id": AnyString(),
+                        "name": "mock_concurrent_tool",
+                        "state": "success",
+                        "output": [
+                            {
+                                "type": "text",
+                                "id": AnyString(),
+                                "text": "Concurrent result: conc1",
+                            },
+                        ],
+                        "metadata": {},
+                    },
+                    {
+                        "type": "tool_result",
+                        "id": AnyString(),
+                        "name": "mock_concurrent_tool",
+                        "state": "success",
+                        "output": [
+                            {
+                                "type": "text",
+                                "id": AnyString(),
+                                "text": "Concurrent result: conc2",
+                            },
+                        ],
+                        "metadata": {},
+                    },
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": "All done",
+                    },
+                ],
+            },
+        ]
+        context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+        expected_context = [{**msg_base, **_} for _ in expected_context]
+        self.assertListEqual(context_dicts, expected_context)
+
+    async def asyncTearDown(self) -> None:
+        """The async teardown method."""
diff --git a/tests/agent_interrupt_test.py b/tests/agent_interrupt_test.py
new file mode 100644
index 0000000..359110b
--- /dev/null
+++ b/tests/agent_interrupt_test.py
@@ -0,0 +1,949 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=redefined-builtin
+"""Tests for agent interruption:
+
+- :class:`AgentInterruptCancelTest`: ``task.cancel()`` lands during tool
+  execution and the agent must close every pending tool call with an
+  ``INTERRUPTED`` result and end the reply with
+  ``ReplyEndReason.INTERRUPTED``.
+- :class:`AgentInterruptEventTest`: a :class:`UserInterruptEvent` is
+  delivered to a parked reply and the agent must close every pending
+  HITL tool call the same way, without entering the reasoning-acting
+  loop.
+"""
+import asyncio
+from typing import Any, AsyncGenerator
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from utils import AnyString, MockModel
+
+from agentscope.agent import Agent
+from agentscope.event import (
+    ReplyEndEvent,
+    UserInterruptEvent,
+)
+from agentscope.message import (
+    TextBlock,
+    ToolCallBlock,
+    UserMsg,
+)
+from agentscope.model import ChatResponse
+from agentscope.permission import (
+    PermissionBehavior,
+    PermissionContext,
+    PermissionDecision,
+)
+from agentscope.tool import (
+    ToolBase,
+    ToolChunk,
+    Toolkit,
+)
+
+# Sleep the too long enough that a ``task.cancel()`` scheduled a few
+# milliseconds later is guaranteed to land while the tool is still inside
+# its ``asyncio.sleep``.
+_SLOW = 5.0
+
+_INTERRUPT_MSG = (
+    "<system-reminder>The tool call has been interrupted by "
+    "the user.</system-reminder>"
+)
+
+_CONFIRM_SUGGESTED_RULES = [
+    {
+        "tool_name": "user_confirm_concurrent",
+        "rule_content": None,
+        "behavior": "allow",
+        "source": "suggested",
+    },
+]
+
+
+def _tool_input_schema() -> dict[str, Any]:
+    return {
+        "type": "object",
+        "properties": {
+            "input": {"type": "string"},
+            "timeout": {"type": "number"},
+        },
+        "required": [],
+    }
+
+
+class _TimeoutConcurrentTool(ToolBase):
+    """Concurrent tool that sleeps ``timeout`` seconds before finishing."""
+
+    name: str = "timeout_concurrent"
+    description: str = "Sleeps and returns."
+    input_schema: dict[str, Any] = _tool_input_schema()
+    is_concurrency_safe: bool = True
+    is_read_only: bool = True
+    is_external_tool: bool = False
+    is_mcp: bool = False
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        return PermissionDecision(
+            behavior=PermissionBehavior.ALLOW,
+            decision_reason="ok",
+            message="ok",
+        )
+
+    async def __call__(
+        self,
+        timeout: float = _SLOW,
+        input: str = "",
+        **kwargs: Any,
+    ) -> AsyncGenerator[ToolChunk, None]:
+        await asyncio.sleep(timeout)
+        yield ToolChunk(
+            content=[TextBlock(text=f"done:{input}")],
+            is_last=True,
+        )
+
+
+class _TimeoutSequentialTool(_TimeoutConcurrentTool):
+    """Sequential (not concurrency-safe) variant."""
+
+    name: str = "timeout_sequential"
+    is_concurrency_safe: bool = False
+
+
+class _UserConfirmConcurrentTool(_TimeoutConcurrentTool):
+    """Concurrent tool that always asks for user confirmation."""
+
+    name: str = "user_confirm_concurrent"
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        return PermissionDecision(
+            behavior=PermissionBehavior.ASK,
+            decision_reason="needs confirm",
+            message="needs confirm",
+        )
+
+
+class _ExternalConcurrentTool(_TimeoutConcurrentTool):
+    """Concurrent tool that requires external execution."""
+
+    name: str = "external_concurrent"
+    is_external_tool: bool = True
+
+
+# ---------------------------------------------------------------------------
+# Shared helpers
+# ---------------------------------------------------------------------------
+
+
+def _msg_base(name: str = "Friday") -> dict[str, Any]:
+    """Assistant message dict skeleton — ``finished_at`` stays ``None``
+    on assistant replies (only user inputs get a finish timestamp)."""
+    return {
+        "id": AnyString(),
+        "created_at": AnyString(),
+        "finished_at": None,
+        "metadata": {},
+        "name": name,
+        "role": "assistant",
+        "usage": None,
+    }
+
+
+def _user_msg_dict(content: str) -> dict[str, Any]:
+    return {
+        "id": AnyString(),
+        "created_at": AnyString(),
+        "finished_at": AnyString(),
+        "metadata": {},
+        "name": "user",
+        "role": "user",
+        "content": [
+            {"type": "text", "id": AnyString(), "text": content},
+        ],
+        "usage": None,
+    }
+
+
+def _tool_call_dict(
+    tc_id: str,
+    name: str,
+    input: str,
+    suggested_rules: list[dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+    return {
+        "type": "tool_call",
+        "id": tc_id,
+        "name": name,
+        "input": input,
+        "state": "finished",
+        "suggested_rules": suggested_rules or [],
+    }
+
+
+def _interrupted_tool_result_dict(
+    tc_id: str,
+    name: str,
+    output_is_blocks: bool,
+) -> dict[str, Any]:
+    """Interrupted tool_result dict.
+
+    ``output_is_blocks`` toggles between the two output shapes actually
+    produced by the framework:
+
+    - ``True`` — ``list[TextBlock]``, emitted by the toolkit's
+      ``CancelledError`` path (in-flight tool cancelled mid-run).
+    - ``False`` — raw ``str``, emitted by
+      :meth:`Agent._close_unfinished_tool_calls` for HITL tool calls
+      that never actually started (ASKING / SUBMITTED).
+    """
+    output: Any
+    if output_is_blocks:
+        output = [
+            {"type": "text", "id": AnyString(), "text": _INTERRUPT_MSG},
+        ]
+    else:
+        output = _INTERRUPT_MSG
+    return {
+        "type": "tool_result",
+        "id": tc_id,
+        "name": name,
+        "output": output,
+        "state": "interrupted",
+        "metadata": {},
+    }
+
+
+async def _run_and_cancel(
+    agent: Agent,
+    inputs: Any,
+    cancel_after: float = 0.05,
+) -> list[Any]:
+    """Drive ``agent.reply_stream(inputs)`` in a background task, cancel
+    after ``cancel_after`` seconds, and return the collected events."""
+    events: list[Any] = []
+
+    async def _drive() -> None:
+        async for evt in agent.reply_stream(inputs):
+            events.append(evt)
+
+    task = asyncio.create_task(_drive())
+    await asyncio.sleep(cancel_after)
+    task.cancel()
+    try:
+        await task
+    except asyncio.CancelledError:
+        pass
+    return events
+
+
+def _assert_interrupted_end(
+    testcase: IsolatedAsyncioTestCase,
+    events: list[Any],
+    reply_id: str,
+    session_id: str,
+) -> None:
+    """The final event must be a ``ReplyEndEvent`` with
+    ``finished_reason='interrupted'`` for the given reply/session."""
+    testcase.assertIsInstance(events[-1], ReplyEndEvent)
+    testcase.assertDictEqual(
+        events[-1].model_dump(mode="json"),
+        {
+            "id": AnyString(),
+            "created_at": AnyString(),
+            "metadata": {},
+            "type": "REPLY_END",
+            "session_id": session_id,
+            "reply_id": reply_id,
+            "finished_reason": "interrupted",
+        },
+    )
+
+
+class AgentInterruptCancelTest(IsolatedAsyncioTestCase):
+    """``task.cancel()`` lands during tool execution."""
+
+    def _make_agent(self, tools: list[ToolBase]) -> tuple[Agent, MockModel]:
+        model = MockModel(model="mock-model", stream=True)
+        agent = Agent(
+            name="Friday",
+            system_prompt="You are a test agent.",
+            model=model,
+            toolkit=Toolkit(tools=tools),
+        )
+        return agent, model
+
+    async def test_sequential_tool_cancelled_mid_execution(self) -> None:
+        """Sequential batch: model emits one slow sequential tool call,
+        ``task.cancel()`` fires while it sleeps, the tool call is patched
+        to FINISHED with an INTERRUPTED result (produced via the toolkit
+        cancel path, so ``output`` is a ``list[TextBlock]``) and the
+        reply ends with INTERRUPTED."""
+        agent, model = self._make_agent([_TimeoutSequentialTool()])
+        model.set_responses(
+            [
+                [
+                    ChatResponse(
+                        content=[
+                            TextBlock(text="Calling."),
+                            ToolCallBlock(
+                                id="tc-seq",
+                                name="timeout_sequential",
+                                input="{}",
+                            ),
+                        ],
+                        is_last=True,
+                    ),
+                ],
+            ],
+        )
+
+        events = await _run_and_cancel(
+            agent,
+            UserMsg(name="user", content="Hi"),
+        )
+
+        _assert_interrupted_end(
+            self,
+            events,
+            reply_id=agent.state.reply_id,
+            session_id=agent.state.session_id,
+        )
+
+        context_dicts = [
+            msg.model_dump(mode="json") for msg in agent.state.context
+        ]
+        self.assertListEqual(
+            context_dicts,
+            [
+                _user_msg_dict("Hi"),
+                {
+                    **_msg_base(),
+                    "content": [
+                        {
+                            "type": "text",
+                            "id": AnyString(),
+                            "text": "Calling.",
+                        },
+                        _tool_call_dict(
+                            "tc-seq",
+                            "timeout_sequential",
+                            "{}",
+                        ),
+                        _interrupted_tool_result_dict(
+                            "tc-seq",
+                            "timeout_sequential",
+                            output_is_blocks=True,
+                        ),
+                    ],
+                },
+            ],
+        )
+
+    async def test_concurrent_tool_cancelled_mid_execution(self) -> None:
+        """Concurrent batch: two slow concurrent tool calls running in
+        parallel, cancel patches both to INTERRUPTED via the toolkit
+        cancel path."""
+        agent, model = self._make_agent([_TimeoutConcurrentTool()])
+        model.set_responses(
+            [
+                [
+                    ChatResponse(
+                        content=[
+                            TextBlock(text="Calling both."),
+                            ToolCallBlock(
+                                id="tc-a",
+                                name="timeout_concurrent",
+                                input='{"input": "a"}',
+                            ),
+                            ToolCallBlock(
+                                id="tc-b",
+                                name="timeout_concurrent",
+                                input='{"input": "b"}',
+                            ),
+                        ],
+                        is_last=True,
+                    ),
+                ],
+            ],
+        )
+
+        events = await _run_and_cancel(
+            agent,
+            UserMsg(name="user", content="Hi"),
+        )
+
+        _assert_interrupted_end(
+            self,
+            events,
+            reply_id=agent.state.reply_id,
+            session_id=agent.state.session_id,
+        )
+
+        context_dicts = [
+            msg.model_dump(mode="json") for msg in agent.state.context
+        ]
+        self.assertListEqual(
+            context_dicts,
+            [
+                _user_msg_dict("Hi"),
+                {
+                    **_msg_base(),
+                    "content": [
+                        {
+                            "type": "text",
+                            "id": AnyString(),
+                            "text": "Calling both.",
+                        },
+                        _tool_call_dict(
+                            "tc-a",
+                            "timeout_concurrent",
+                            '{"input": "a"}',
+                        ),
+                        _tool_call_dict(
+                            "tc-b",
+                            "timeout_concurrent",
+                            '{"input": "b"}',
+                        ),
+                        _interrupted_tool_result_dict(
+                            "tc-a",
+                            "timeout_concurrent",
+                            output_is_blocks=True,
+                        ),
+                        _interrupted_tool_result_dict(
+                            "tc-b",
+                            "timeout_concurrent",
+                            output_is_blocks=True,
+                        ),
+                    ],
+                },
+            ],
+        )
+
+    async def test_cancel_during_user_confirm_and_running_tool(
+        self,
+    ) -> None:
+        """Concurrent batch mixes a user-confirmation tool (parks in
+        ASKING state without ever running, so its result comes from the
+        agent ``_close_unfinished_tool_calls`` path with a ``str``
+        output) and a slow running tool (whose result comes from the
+        toolkit cancel path with a ``list[TextBlock]`` output).
+
+        The running tool's result is appended first (flushed from the
+        concurrent queue), the ASKING tool's result is appended last
+        by the agent cleanup."""
+        agent, model = self._make_agent(
+            [_UserConfirmConcurrentTool(), _TimeoutConcurrentTool()],
+        )
+        model.set_responses(
+            [
+                [
+                    ChatResponse(
+                        content=[
+                            TextBlock(text="Mixed batch."),
+                            ToolCallBlock(
+                                id="tc-confirm",
+                                name="user_confirm_concurrent",
+                                input="{}",
+                            ),
+                            ToolCallBlock(
+                                id="tc-run",
+                                name="timeout_concurrent",
+                                input="{}",
+                            ),
+                        ],
+                        is_last=True,
+                    ),
+                ],
+            ],
+        )
+
+        events = await _run_and_cancel(
+            agent,
+            UserMsg(name="user", content="Hi"),
+        )
+
+        _assert_interrupted_end(
+            self,
+            events,
+            reply_id=agent.state.reply_id,
+            session_id=agent.state.session_id,
+        )
+
+        context_dicts = [
+            msg.model_dump(mode="json") for msg in agent.state.context
+        ]
+        self.assertListEqual(
+            context_dicts,
+            [
+                _user_msg_dict("Hi"),
+                {
+                    **_msg_base(),
+                    "content": [
+                        {
+                            "type": "text",
+                            "id": AnyString(),
+                            "text": "Mixed batch.",
+                        },
+                        _tool_call_dict(
+                            "tc-confirm",
+                            "user_confirm_concurrent",
+                            "{}",
+                            suggested_rules=_CONFIRM_SUGGESTED_RULES,
+                        ),
+                        _tool_call_dict(
+                            "tc-run",
+                            "timeout_concurrent",
+                            "{}",
+                        ),
+                        _interrupted_tool_result_dict(
+                            "tc-run",
+                            "timeout_concurrent",
+                            output_is_blocks=True,
+                        ),
+                        _interrupted_tool_result_dict(
+                            "tc-confirm",
+                            "user_confirm_concurrent",
+                            output_is_blocks=False,
+                        ),
+                    ],
+                },
+            ],
+        )
+
+    async def test_cancel_during_external_and_running_tool(self) -> None:
+        """Concurrent batch mixes an external-execution tool (parks in
+        SUBMITTED without running → ``str`` output on cleanup) and a
+        slow running tool (toolkit cancel → ``list[TextBlock]``)."""
+        agent, model = self._make_agent(
+            [_ExternalConcurrentTool(), _TimeoutConcurrentTool()],
+        )
+        model.set_responses(
+            [
+                [
+                    ChatResponse(
+                        content=[
+                            TextBlock(text="Mixed batch."),
+                            ToolCallBlock(
+                                id="tc-ext",
+                                name="external_concurrent",
+                                input="{}",
+                            ),
+                            ToolCallBlock(
+                                id="tc-run",
+                                name="timeout_concurrent",
+                                input="{}",
+                            ),
+                        ],
+                        is_last=True,
+                    ),
+                ],
+            ],
+        )
+
+        events = await _run_and_cancel(
+            agent,
+            UserMsg(name="user", content="Hi"),
+        )
+
+        _assert_interrupted_end(
+            self,
+            events,
+            reply_id=agent.state.reply_id,
+            session_id=agent.state.session_id,
+        )
+
+        context_dicts = [
+            msg.model_dump(mode="json") for msg in agent.state.context
+        ]
+        self.assertListEqual(
+            context_dicts,
+            [
+                _user_msg_dict("Hi"),
+                {
+                    **_msg_base(),
+                    "content": [
+                        {
+                            "type": "text",
+                            "id": AnyString(),
+                            "text": "Mixed batch.",
+                        },
+                        _tool_call_dict(
+                            "tc-ext",
+                            "external_concurrent",
+                            "{}",
+                        ),
+                        _tool_call_dict(
+                            "tc-run",
+                            "timeout_concurrent",
+                            "{}",
+                        ),
+                        _interrupted_tool_result_dict(
+                            "tc-run",
+                            "timeout_concurrent",
+                            output_is_blocks=True,
+                        ),
+                        _interrupted_tool_result_dict(
+                            "tc-ext",
+                            "external_concurrent",
+                            output_is_blocks=False,
+                        ),
+                    ],
+                },
+            ],
+        )
+
+    async def test_cancel_with_confirm_external_and_running_tool(
+        self,
+    ) -> None:
+        """Confirm + external + slow running, all three cancelled."""
+        agent, model = self._make_agent(
+            [
+                _UserConfirmConcurrentTool(),
+                _ExternalConcurrentTool(),
+                _TimeoutConcurrentTool(),
+            ],
+        )
+        model.set_responses(
+            [
+                [
+                    ChatResponse(
+                        content=[
+                            TextBlock(text="Mixed batch."),
+                            ToolCallBlock(
+                                id="tc-confirm",
+                                name="user_confirm_concurrent",
+                                input="{}",
+                            ),
+                            ToolCallBlock(
+                                id="tc-ext",
+                                name="external_concurrent",
+                                input="{}",
+                            ),
+                            ToolCallBlock(
+                                id="tc-run",
+                                name="timeout_concurrent",
+                                input="{}",
+                            ),
+                        ],
+                        is_last=True,
+                    ),
+                ],
+            ],
+        )
+
+        events = await _run_and_cancel(
+            agent,
+            UserMsg(name="user", content="Hi"),
+        )
+
+        _assert_interrupted_end(
+            self,
+            events,
+            reply_id=agent.state.reply_id,
+            session_id=agent.state.session_id,
+        )
+
+        context_dicts = [
+            msg.model_dump(mode="json") for msg in agent.state.context
+        ]
+        self.assertListEqual(
+            context_dicts,
+            [
+                _user_msg_dict("Hi"),
+                {
+                    **_msg_base(),
+                    "content": [
+                        {
+                            "type": "text",
+                            "id": AnyString(),
+                            "text": "Mixed batch.",
+                        },
+                        _tool_call_dict(
+                            "tc-confirm",
+                            "user_confirm_concurrent",
+                            "{}",
+                            suggested_rules=_CONFIRM_SUGGESTED_RULES,
+                        ),
+                        _tool_call_dict(
+                            "tc-ext",
+                            "external_concurrent",
+                            "{}",
+                        ),
+                        _tool_call_dict(
+                            "tc-run",
+                            "timeout_concurrent",
+                            "{}",
+                        ),
+                        _interrupted_tool_result_dict(
+                            "tc-run",
+                            "timeout_concurrent",
+                            output_is_blocks=True,
+                        ),
+                        _interrupted_tool_result_dict(
+                            "tc-confirm",
+                            "user_confirm_concurrent",
+                            output_is_blocks=False,
+                        ),
+                        _interrupted_tool_result_dict(
+                            "tc-ext",
+                            "external_concurrent",
+                            output_is_blocks=False,
+                        ),
+                    ],
+                },
+            ],
+        )
+
+
+class AgentInterruptEventTest(IsolatedAsyncioTestCase):
+    """A :class:`UserInterruptEvent` is delivered to a parked reply.
+
+    HITL tool calls that never actually ran are patched by
+    :meth:`Agent._close_unfinished_tool_calls`, whose ``tool_result``
+    output is always the raw interrupt ``str`` (never ``list[TextBlock]``)."""
+
+    def _make_agent(self, tools: list[ToolBase]) -> tuple[Agent, MockModel]:
+        model = MockModel(model="mock-model", stream=True)
+        agent = Agent(
+            name="Friday",
+            system_prompt="You are a test agent.",
+            model=model,
+            toolkit=Toolkit(tools=tools),
+        )
+        return agent, model
+
+    async def _park_with(
+        self,
+        agent: Agent,
+        model: MockModel,
+        pending_tool_calls: list[ToolCallBlock],
+    ) -> None:
+        """Drive one reply that yields the given tool calls so the reply
+        parks in either ASKING or SUBMITTED state."""
+        model.set_responses(
+            [
+                [
+                    ChatResponse(
+                        content=[
+                            TextBlock(text="Need HITL."),
+                            *pending_tool_calls,
+                        ],
+                        is_last=True,
+                    ),
+                ],
+            ],
+        )
+        async for _ in agent.reply_stream(
+            UserMsg(name="user", content="Hi"),
+        ):
+            pass
+
+    async def test_interrupt_event_on_idle_agent_is_noop(self) -> None:
+        """No parked HITL → ``UserInterruptEvent`` yields nothing and
+        leaves state untouched."""
+        agent, _ = self._make_agent([])
+
+        events = []
+        async for evt in agent.reply_stream(
+            UserInterruptEvent(reply_id="noop"),
+        ):
+            events.append(evt)
+
+        self.assertListEqual(events, [])
+        self.assertListEqual(agent.state.context, [])
+
+    async def test_interrupt_event_after_user_confirm(self) -> None:
+        """Parked in ASKING state: ``UserInterruptEvent`` patches the
+        tool call to FINISHED and appends an INTERRUPTED result (``str``
+        output) and ends the reply with INTERRUPTED."""
+        agent, model = self._make_agent([_UserConfirmConcurrentTool()])
+        await self._park_with(
+            agent,
+            model,
+            [
+                ToolCallBlock(
+                    id="tc-confirm",
+                    name="user_confirm_concurrent",
+                    input="{}",
+                ),
+            ],
+        )
+        reply_id = agent.state.reply_id
+        session_id = agent.state.session_id
+
+        events = []
+        async for evt in agent.reply_stream(
+            UserInterruptEvent(reply_id=reply_id),
+        ):
+            events.append(evt)
+
+        _assert_interrupted_end(self, events, reply_id, session_id)
+
+        context_dicts = [
+            msg.model_dump(mode="json") for msg in agent.state.context
+        ]
+        self.assertListEqual(
+            context_dicts,
+            [
+                _user_msg_dict("Hi"),
+                {
+                    **_msg_base(),
+                    "content": [
+                        {
+                            "type": "text",
+                            "id": AnyString(),
+                            "text": "Need HITL.",
+                        },
+                        _tool_call_dict(
+                            "tc-confirm",
+                            "user_confirm_concurrent",
+                            "{}",
+                            suggested_rules=_CONFIRM_SUGGESTED_RULES,
+                        ),
+                        _interrupted_tool_result_dict(
+                            "tc-confirm",
+                            "user_confirm_concurrent",
+                            output_is_blocks=False,
+                        ),
+                    ],
+                },
+            ],
+        )
+
+    async def test_interrupt_event_after_external_execution(self) -> None:
+        """Parked in SUBMITTED: ``UserInterruptEvent`` patches the same
+        way (``str`` output)."""
+        agent, model = self._make_agent([_ExternalConcurrentTool()])
+        await self._park_with(
+            agent,
+            model,
+            [
+                ToolCallBlock(
+                    id="tc-ext",
+                    name="external_concurrent",
+                    input="{}",
+                ),
+            ],
+        )
+        reply_id = agent.state.reply_id
+        session_id = agent.state.session_id
+
+        events = []
+        async for evt in agent.reply_stream(
+            UserInterruptEvent(reply_id=reply_id),
+        ):
+            events.append(evt)
+
+        _assert_interrupted_end(self, events, reply_id, session_id)
+
+        context_dicts = [
+            msg.model_dump(mode="json") for msg in agent.state.context
+        ]
+        self.assertListEqual(
+            context_dicts,
+            [
+                _user_msg_dict("Hi"),
+                {
+                    **_msg_base(),
+                    "content": [
+                        {
+                            "type": "text",
+                            "id": AnyString(),
+                            "text": "Need HITL.",
+                        },
+                        _tool_call_dict(
+                            "tc-ext",
+                            "external_concurrent",
+                            "{}",
+                        ),
+                        _interrupted_tool_result_dict(
+                            "tc-ext",
+                            "external_concurrent",
+                            output_is_blocks=False,
+                        ),
+                    ],
+                },
+            ],
+        )
+
+    async def test_interrupt_event_after_both_confirm_and_external(
+        self,
+    ) -> None:
+        """Parked with both ASKING and SUBMITTED tool calls: a single
+        ``UserInterruptEvent`` closes both."""
+        agent, model = self._make_agent(
+            [_UserConfirmConcurrentTool(), _ExternalConcurrentTool()],
+        )
+        await self._park_with(
+            agent,
+            model,
+            [
+                ToolCallBlock(
+                    id="tc-confirm",
+                    name="user_confirm_concurrent",
+                    input="{}",
+                ),
+                ToolCallBlock(
+                    id="tc-ext",
+                    name="external_concurrent",
+                    input="{}",
+                ),
+            ],
+        )
+        reply_id = agent.state.reply_id
+        session_id = agent.state.session_id
+
+        events = []
+        async for evt in agent.reply_stream(
+            UserInterruptEvent(reply_id=reply_id),
+        ):
+            events.append(evt)
+
+        _assert_interrupted_end(self, events, reply_id, session_id)
+
+        context_dicts = [
+            msg.model_dump(mode="json") for msg in agent.state.context
+        ]
+        self.assertListEqual(
+            context_dicts,
+            [
+                _user_msg_dict("Hi"),
+                {
+                    **_msg_base(),
+                    "content": [
+                        {
+                            "type": "text",
+                            "id": AnyString(),
+                            "text": "Need HITL.",
+                        },
+                        _tool_call_dict(
+                            "tc-confirm",
+                            "user_confirm_concurrent",
+                            "{}",
+                            suggested_rules=_CONFIRM_SUGGESTED_RULES,
+                        ),
+                        _tool_call_dict(
+                            "tc-ext",
+                            "external_concurrent",
+                            "{}",
+                        ),
+                        _interrupted_tool_result_dict(
+                            "tc-confirm",
+                            "user_confirm_concurrent",
+                            output_is_blocks=False,
+                        ),
+                        _interrupted_tool_result_dict(
+                            "tc-ext",
+                            "external_concurrent",
+                            output_is_blocks=False,
+                        ),
+                    ],
+                },
+            ],
+        )
diff --git a/tests/agui_protocol_test.py b/tests/agui_protocol_test.py
new file mode 100644
index 0000000..d07fb6c
--- /dev/null
+++ b/tests/agui_protocol_test.py
@@ -0,0 +1,716 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Test cases for AGUI protocol middleware."""
+
+import json
+from typing import AsyncGenerator
+from unittest.async_case import IsolatedAsyncioTestCase
+from unittest.mock import MagicMock
+
+from fastapi import FastAPI
+from fastapi.responses import JSONResponse
+from fastapi.responses import StreamingResponse
+from fastapi.testclient import TestClient
+
+from agentscope.app.middleware import AGUIProtocolMiddleware
+from agentscope.event import (
+    ConfirmResult,
+    DataBlockDeltaEvent,
+    DataBlockEndEvent,
+    DataBlockStartEvent,
+    ExceedMaxItersEvent,
+    ExternalExecutionResultEvent,
+    ModelCallEndEvent,
+    ModelCallStartEvent,
+    ReplyEndEvent,
+    ReplyStartEvent,
+    RequireExternalExecutionEvent,
+    RequireUserConfirmEvent,
+    TextBlockDeltaEvent,
+    TextBlockEndEvent,
+    TextBlockStartEvent,
+    ThinkingBlockDeltaEvent,
+    ThinkingBlockEndEvent,
+    ThinkingBlockStartEvent,
+    ToolCallDeltaEvent,
+    ToolCallEndEvent,
+    ToolCallStartEvent,
+    ToolResultDataDeltaEvent,
+    ToolResultEndEvent,
+    ToolResultStartEvent,
+    ToolResultTextDeltaEvent,
+    UserConfirmResultEvent,
+    ReplyEndReason,
+)
+from agentscope.message import ToolCallBlock, ToolResultBlock, ToolResultState
+from agentscope.model import FinishedReason
+
+
+async def _collect_stream(
+    mw: AGUIProtocolMiddleware,
+    chunks: list[str],
+) -> str:
+    """Collect converted stream chunks as text."""
+
+    async def _stream() -> AsyncGenerator[str, None]:
+        """Yield the provided chunks."""
+        for chunk in chunks:
+            yield chunk
+
+    out: list[str] = []
+    async for item in mw._convert_stream(_stream()):
+        out.append(item.decode("utf-8"))
+    return "".join(out)
+
+
+class AGUIProtocolStreamTest(IsolatedAsyncioTestCase):
+    """Test stream-level conversion behavior."""
+
+    async def asyncSetUp(self) -> None:
+        """The async setup method."""
+        self.mw = AGUIProtocolMiddleware(app=MagicMock())
+
+    async def test_raw_json_stream_is_converted(self) -> None:
+        """Test raw AgentEvent JSON stream conversion."""
+        event = ReplyStartEvent(
+            session_id="sess_1",
+            reply_id="reply_1",
+            name="agent",
+        )
+
+        body = await _collect_stream(self.mw, [event.model_dump_json()])
+        data = json.loads(body)
+
+        self.assertEqual(data["type"], "RUN_STARTED")
+        self.assertEqual(data["threadId"], "sess_1")
+        self.assertEqual(data["runId"], "reply_1")
+
+    async def test_sse_data_frame_is_converted(self) -> None:
+        """Test AgentEvent JSON inside an SSE data frame is converted."""
+        event = ReplyStartEvent(
+            session_id="sess_1",
+            reply_id="reply_1",
+            name="agent",
+        )
+
+        body = await _collect_stream(
+            self.mw,
+            [f"data: {event.model_dump_json()}\n\n"],
+        )
+        self.assertTrue(body.startswith("data: "))
+
+        data = json.loads(body.removeprefix("data: ").strip())
+        self.assertEqual(data["type"], "RUN_STARTED")
+        self.assertEqual(data["threadId"], "sess_1")
+        self.assertEqual(data["runId"], "reply_1")
+        self.assertNotIn("session_id", data)
+
+    async def test_sse_heartbeat_is_passed_through(self) -> None:
+        """Test SSE heartbeat frames are not modified."""
+        self.assertEqual(
+            await _collect_stream(self.mw, [":\n\n"]),
+            ":\n\n",
+        )
+
+    async def test_sse_data_frame_with_crlf_is_converted(self) -> None:
+        """Test AgentEvent JSON inside a CRLF SSE frame is converted."""
+        event = ReplyStartEvent(
+            session_id="sess_1",
+            reply_id="reply_1",
+            name="agent",
+        )
+
+        body = await _collect_stream(
+            self.mw,
+            [f"data: {event.model_dump_json()}\r\n\r\n"],
+        )
+        self.assertTrue(body.startswith("data: "))
+        self.assertTrue(body.endswith("\r\n\r\n"))
+
+        data = json.loads(body.removeprefix("data: ").strip())
+        self.assertEqual(data["type"], "RUN_STARTED")
+        self.assertEqual(data["threadId"], "sess_1")
+        self.assertEqual(data["runId"], "reply_1")
+
+    async def test_fastapi_sse_response_is_converted(self) -> None:
+        """Test middleware converts a real FastAPI SSE response."""
+        app = FastAPI()
+        app.add_middleware(AGUIProtocolMiddleware)
+
+        @app.get("/sessions/sess_1/stream")
+        async def stream() -> StreamingResponse:
+            event = ReplyStartEvent(
+                session_id="sess_1",
+                reply_id="reply_1",
+                name="agent",
+            )
+
+            async def gen() -> AsyncGenerator[str, None]:
+                yield f"data: {event.model_dump_json()}\n\n"
+
+            return StreamingResponse(gen(), media_type="text/event-stream")
+
+        client = TestClient(app)
+        with client.stream("GET", "/sessions/sess_1/stream") as response:
+            body = "".join(response.iter_text())
+
+        self.assertTrue(body.startswith("data: "))
+        data = json.loads(body.removeprefix("data: ").strip())
+        self.assertEqual(data["type"], "RUN_STARTED")
+        self.assertEqual(data["threadId"], "sess_1")
+        self.assertEqual(data["runId"], "reply_1")
+        self.assertNotIn("session_id", data)
+
+    async def test_fastapi_json_response_is_not_converted(self) -> None:
+        """Test non-SSE responses are outside protocol conversion scope."""
+        app = FastAPI()
+        app.add_middleware(AGUIProtocolMiddleware)
+
+        @app.get("/event")
+        def event() -> JSONResponse:
+            agent_event = ReplyStartEvent(
+                session_id="sess_1",
+                reply_id="reply_1",
+                name="agent",
+            )
+            return JSONResponse(agent_event.model_dump(mode="json"))
+
+        client = TestClient(app)
+        response = client.get("/event")
+
+        self.assertEqual(response.status_code, 200)
+        data = response.json()
+        self.assertEqual(data["type"], "REPLY_START")
+        self.assertEqual(data["session_id"], "sess_1")
+        self.assertNotIn("RUN_STARTED", response.text)
+
+    async def asyncTearDown(self) -> None:
+        """The async teardown method."""
+
+
+class AGUIProtocolLifecycleTest(IsolatedAsyncioTestCase):
+    """Test lifecycle event conversions."""
+
+    async def asyncSetUp(self) -> None:
+        """The async setup method."""
+        self.mw = AGUIProtocolMiddleware(app=MagicMock())
+
+    async def test_reply_start_to_run_started(self) -> None:
+        """Test ReplyStartEvent -> RUN_STARTED."""
+        event = ReplyStartEvent(
+            session_id="sess_1",
+            reply_id="reply_1",
+            name="agent",
+        )
+        result = self.mw._convert_to_protocol(event)
+
+        self.assertEqual(result["type"], "RUN_STARTED")
+        self.assertEqual(result["threadId"], "sess_1")
+        self.assertEqual(result["runId"], "reply_1")
+        self.assertNotIn("name", result)
+
+    async def test_reply_end_to_run_finished(self) -> None:
+        """Test ReplyEndEvent -> RUN_FINISHED."""
+        event = ReplyEndEvent(
+            session_id="sess_1",
+            reply_id="reply_1",
+            finished_reason=ReplyEndReason.COMPLETED,
+        )
+        result = self.mw._convert_to_protocol(event)
+
+        self.assertEqual(result["type"], "RUN_FINISHED")
+        self.assertEqual(result["threadId"], "sess_1")
+        self.assertEqual(result["runId"], "reply_1")
+
+    async def test_exceed_max_iters_to_run_error(self) -> None:
+        """Test ExceedMaxItersEvent -> RUN_ERROR."""
+        event = ExceedMaxItersEvent(
+            reply_id="reply_1",
+            name="my_agent",
+        )
+        result = self.mw._convert_to_protocol(event)
+
+        self.assertEqual(result["type"], "RUN_ERROR")
+        self.assertIn("my_agent", result["message"])
+        self.assertEqual(result["code"], "exceed_max_iters")
+
+    async def asyncTearDown(self) -> None:
+        """The async teardown method."""
+
+
+class AGUIProtocolStepTest(IsolatedAsyncioTestCase):
+    """Test model call -> step event conversions."""
+
+    async def asyncSetUp(self) -> None:
+        """The async setup method."""
+        self.mw = AGUIProtocolMiddleware(app=MagicMock())
+
+    async def test_model_call_start_to_step_started(self) -> None:
+        """Test ModelCallStartEvent -> STEP_STARTED."""
+        event = ModelCallStartEvent(
+            reply_id="reply_1",
+            model_name="gpt-4",
+        )
+        result = self.mw._convert_to_protocol(event)
+
+        self.assertEqual(result["type"], "STEP_STARTED")
+        self.assertEqual(result["stepName"], "gpt-4")
+
+    async def test_model_call_end_to_step_finished(self) -> None:
+        """Test ModelCallEndEvent -> STEP_FINISHED with matching step_name."""
+        start_event = ModelCallStartEvent(
+            reply_id="reply_1",
+            model_name="gpt-4",
+        )
+        self.mw._convert_to_protocol(start_event)
+
+        end_event = ModelCallEndEvent(
+            reply_id="reply_1",
+            input_tokens=100,
+            output_tokens=50,
+            finished_reason=FinishedReason.COMPLETED,
+        )
+        result = self.mw._convert_to_protocol(end_event)
+
+        self.assertEqual(result["type"], "STEP_FINISHED")
+        self.assertEqual(result["stepName"], "gpt-4")
+
+    async def asyncTearDown(self) -> None:
+        """The async teardown method."""
+
+
+class AGUIProtocolTextMessageTest(IsolatedAsyncioTestCase):
+    """Test text block -> text message event conversions."""
+
+    async def asyncSetUp(self) -> None:
+        """The async setup method."""
+        self.mw = AGUIProtocolMiddleware(app=MagicMock())
+
+    async def test_text_block_start(self) -> None:
+        """Test TextBlockStartEvent -> TEXT_MESSAGE_START."""
+        event = TextBlockStartEvent(
+            reply_id="reply_1",
+            block_id="block_1",
+        )
+        result = self.mw._convert_to_protocol(event)
+
+        self.assertEqual(result["type"], "TEXT_MESSAGE_START")
+        self.assertEqual(result["messageId"], "block_1")
+
+    async def test_text_block_delta(self) -> None:
+        """Test TextBlockDeltaEvent -> TEXT_MESSAGE_CONTENT."""
+        event = TextBlockDeltaEvent(
+            reply_id="reply_1",
+            block_id="block_1",
+            delta="Hello, ",
+        )
+        result = self.mw._convert_to_protocol(event)
+
+        self.assertEqual(result["type"], "TEXT_MESSAGE_CONTENT")
+        self.assertEqual(result["messageId"], "block_1")
+        self.assertEqual(result["delta"], "Hello, ")
+
+    async def test_text_block_end(self) -> None:
+        """Test TextBlockEndEvent -> TEXT_MESSAGE_END."""
+        event = TextBlockEndEvent(
+            reply_id="reply_1",
+            block_id="block_1",
+        )
+        result = self.mw._convert_to_protocol(event)
+
+        self.assertEqual(result["type"], "TEXT_MESSAGE_END")
+        self.assertEqual(result["messageId"], "block_1")
+
+    async def asyncTearDown(self) -> None:
+        """The async teardown method."""
+
+
+class AGUIProtocolReasoningTest(IsolatedAsyncioTestCase):
+    """Test thinking block -> reasoning message event conversions."""
+
+    async def asyncSetUp(self) -> None:
+        """The async setup method."""
+        self.mw = AGUIProtocolMiddleware(app=MagicMock())
+
+    async def test_thinking_block_start(self) -> None:
+        """Test ThinkingBlockStartEvent -> REASONING_MESSAGE_START."""
+        event = ThinkingBlockStartEvent(
+            reply_id="reply_1",
+            block_id="think_1",
+        )
+        result = self.mw._convert_to_protocol(event)
+
+        self.assertEqual(result["type"], "REASONING_MESSAGE_START")
+        self.assertEqual(result["messageId"], "think_1")
+        self.assertEqual(result["role"], "reasoning")
+
+    async def test_thinking_block_delta(self) -> None:
+        """Test ThinkingBlockDeltaEvent -> REASONING_MESSAGE_CONTENT."""
+        event = ThinkingBlockDeltaEvent(
+            reply_id="reply_1",
+            block_id="think_1",
+            delta="Let me think...",
+        )
+        result = self.mw._convert_to_protocol(event)
+
+        self.assertEqual(result["type"], "REASONING_MESSAGE_CONTENT")
+        self.assertEqual(result["messageId"], "think_1")
+        self.assertEqual(result["delta"], "Let me think...")
+
+    async def test_thinking_block_end(self) -> None:
+        """Test ThinkingBlockEndEvent -> REASONING_MESSAGE_END."""
+        event = ThinkingBlockEndEvent(
+            reply_id="reply_1",
+            block_id="think_1",
+        )
+        result = self.mw._convert_to_protocol(event)
+
+        self.assertEqual(result["type"], "REASONING_MESSAGE_END")
+        self.assertEqual(result["messageId"], "think_1")
+
+    async def asyncTearDown(self) -> None:
+        """The async teardown method."""
+
+
+class AGUIProtocolToolCallTest(IsolatedAsyncioTestCase):
+    """Test tool call event conversions."""
+
+    async def asyncSetUp(self) -> None:
+        """The async setup method."""
+        self.mw = AGUIProtocolMiddleware(app=MagicMock())
+
+    async def test_tool_call_start(self) -> None:
+        """Test ToolCallStartEvent -> TOOL_CALL_START."""
+        event = ToolCallStartEvent(
+            reply_id="reply_1",
+            tool_call_id="tc_1",
+            tool_call_name="search",
+        )
+        result = self.mw._convert_to_protocol(event)
+
+        self.assertEqual(result["type"], "TOOL_CALL_START")
+        self.assertEqual(result["toolCallId"], "tc_1")
+        self.assertEqual(result["toolCallName"], "search")
+        self.assertEqual(result["parentMessageId"], "reply_1")
+
+    async def test_tool_call_delta(self) -> None:
+        """Test ToolCallDeltaEvent -> TOOL_CALL_ARGS."""
+        event = ToolCallDeltaEvent(
+            reply_id="reply_1",
+            tool_call_id="tc_1",
+            delta='{"query": "hello"}',
+        )
+        result = self.mw._convert_to_protocol(event)
+
+        self.assertEqual(result["type"], "TOOL_CALL_ARGS")
+        self.assertEqual(result["toolCallId"], "tc_1")
+        self.assertEqual(result["delta"], '{"query": "hello"}')
+
+    async def test_tool_call_end(self) -> None:
+        """Test ToolCallEndEvent -> TOOL_CALL_END."""
+        event = ToolCallEndEvent(
+            reply_id="reply_1",
+            tool_call_id="tc_1",
+        )
+        result = self.mw._convert_to_protocol(event)
+
+        self.assertEqual(result["type"], "TOOL_CALL_END")
+        self.assertEqual(result["toolCallId"], "tc_1")
+
+    async def asyncTearDown(self) -> None:
+        """The async teardown method."""
+
+
+class AGUIProtocolToolResultTest(IsolatedAsyncioTestCase):
+    """Test tool result event conversions."""
+
+    async def asyncSetUp(self) -> None:
+        """The async setup method."""
+        self.mw = AGUIProtocolMiddleware(app=MagicMock())
+
+    async def test_tool_result_end_with_buffered_content(self) -> None:
+        """Test that ToolResultEndEvent carries accumulated text content."""
+        self.mw._convert_to_protocol(
+            ToolResultTextDeltaEvent(
+                reply_id="reply_1",
+                tool_call_id="tc_1",
+                delta="partial ",
+            ),
+        )
+        self.mw._convert_to_protocol(
+            ToolResultTextDeltaEvent(
+                reply_id="reply_1",
+                tool_call_id="tc_1",
+                delta="result",
+            ),
+        )
+
+        result = self.mw._convert_to_protocol(
+            ToolResultEndEvent(
+                reply_id="reply_1",
+                tool_call_id="tc_1",
+                state=ToolResultState.SUCCESS,
+            ),
+        )
+
+        self.assertEqual(result["type"], "TOOL_CALL_RESULT")
+        self.assertEqual(result["toolCallId"], "tc_1")
+        self.assertEqual(result["messageId"], "reply_1")
+        self.assertEqual(result["content"], "partial result")
+
+    async def test_tool_result_end_fallback_to_state(self) -> None:
+        """Test that ToolResultEndEvent falls back to state when no buffer."""
+        result = self.mw._convert_to_protocol(
+            ToolResultEndEvent(
+                reply_id="reply_1",
+                tool_call_id="tc_1",
+                state=ToolResultState.ERROR,
+            ),
+        )
+
+        self.assertEqual(result["type"], "TOOL_CALL_RESULT")
+        self.assertEqual(result["content"], "error")
+
+    async def test_tool_result_start_to_custom(self) -> None:
+        """Test ToolResultStartEvent -> CUSTOM."""
+        event = ToolResultStartEvent(
+            reply_id="reply_1",
+            tool_call_id="tc_1",
+            tool_call_name="search",
+        )
+        result = self.mw._convert_to_protocol(event)
+
+        self.assertEqual(result["type"], "CUSTOM")
+        self.assertEqual(result["name"], "tool_result_start")
+        self.assertIsInstance(result["value"], dict)
+
+    async def test_tool_result_text_delta_to_custom(self) -> None:
+        """Test ToolResultTextDeltaEvent -> CUSTOM."""
+        event = ToolResultTextDeltaEvent(
+            reply_id="reply_1",
+            tool_call_id="tc_1",
+            delta="partial result",
+        )
+        result = self.mw._convert_to_protocol(event)
+
+        self.assertEqual(result["type"], "CUSTOM")
+        self.assertEqual(result["name"], "tool_result_text_delta")
+        self.assertEqual(result["value"]["delta"], "partial result")
+
+    async def test_tool_result_data_delta_to_custom(self) -> None:
+        """Test ToolResultDataDeltaEvent -> CUSTOM."""
+        event = ToolResultDataDeltaEvent(
+            reply_id="reply_1",
+            tool_call_id="tc_1",
+            media_type="image/png",
+            data="base64data",
+        )
+        result = self.mw._convert_to_protocol(event)
+
+        self.assertEqual(result["type"], "CUSTOM")
+        self.assertEqual(result["name"], "tool_result_data_delta")
+        self.assertEqual(result["value"]["media_type"], "image/png")
+
+    async def asyncTearDown(self) -> None:
+        """The async teardown method."""
+
+
+class AGUIProtocolDataBlockTest(IsolatedAsyncioTestCase):
+    """Test data block -> custom event conversions."""
+
+    async def asyncSetUp(self) -> None:
+        """The async setup method."""
+        self.mw = AGUIProtocolMiddleware(app=MagicMock())
+
+    async def test_data_block_start(self) -> None:
+        """Test DataBlockStartEvent -> CUSTOM."""
+        event = DataBlockStartEvent(
+            reply_id="reply_1",
+            block_id="db_1",
+            media_type="image/png",
+        )
+        result = self.mw._convert_to_protocol(event)
+
+        self.assertEqual(result["type"], "CUSTOM")
+        self.assertEqual(result["name"], "data_block_start")
+        self.assertEqual(result["value"]["media_type"], "image/png")
+
+    async def test_data_block_delta(self) -> None:
+        """Test DataBlockDeltaEvent -> CUSTOM."""
+        event = DataBlockDeltaEvent(
+            reply_id="reply_1",
+            block_id="db_1",
+            data="base64chunk",
+            media_type="image/png",
+        )
+        result = self.mw._convert_to_protocol(event)
+
+        self.assertEqual(result["type"], "CUSTOM")
+        self.assertEqual(result["name"], "data_block_delta")
+        self.assertEqual(result["value"]["data"], "base64chunk")
+
+    async def test_data_block_end(self) -> None:
+        """Test DataBlockEndEvent -> CUSTOM."""
+        event = DataBlockEndEvent(
+            reply_id="reply_1",
+            block_id="db_1",
+        )
+        result = self.mw._convert_to_protocol(event)
+
+        self.assertEqual(result["type"], "CUSTOM")
+        self.assertEqual(result["name"], "data_block_end")
+
+    async def asyncTearDown(self) -> None:
+        """The async teardown method."""
+
+
+class AGUIProtocolPermissionTest(IsolatedAsyncioTestCase):
+    """Test permission-related event conversions."""
+
+    async def asyncSetUp(self) -> None:
+        """The async setup method."""
+        self.mw = AGUIProtocolMiddleware(app=MagicMock())
+
+    async def test_require_user_confirm(self) -> None:
+        """Test RequireUserConfirmEvent -> CUSTOM."""
+        event = RequireUserConfirmEvent(
+            reply_id="reply_1",
+            tool_calls=[
+                ToolCallBlock(
+                    id="tc_1",
+                    name="bash",
+                    input='{"command": "ls"}',
+                ),
+            ],
+        )
+        result = self.mw._convert_to_protocol(event)
+
+        self.assertEqual(result["type"], "CUSTOM")
+        self.assertEqual(result["name"], "require_user_confirm")
+        self.assertIn("tool_calls", result["value"])
+
+    async def test_require_external_execution(self) -> None:
+        """Test RequireExternalExecutionEvent -> CUSTOM."""
+        event = RequireExternalExecutionEvent(
+            reply_id="reply_1",
+            tool_calls=[
+                ToolCallBlock(
+                    id="tc_2",
+                    name="external_api",
+                    input="{}",
+                ),
+            ],
+        )
+        result = self.mw._convert_to_protocol(event)
+
+        self.assertEqual(result["type"], "CUSTOM")
+        self.assertEqual(result["name"], "require_external_execution")
+
+    async def test_user_confirm_result(self) -> None:
+        """Test UserConfirmResultEvent -> CUSTOM."""
+        event = UserConfirmResultEvent(
+            reply_id="reply_1",
+            confirm_results=[
+                ConfirmResult(
+                    confirmed=True,
+                    tool_call=ToolCallBlock(
+                        id="tc_1",
+                        name="bash",
+                        input='{"command": "ls"}',
+                    ),
+                ),
+            ],
+        )
+        result = self.mw._convert_to_protocol(event)
+
+        self.assertEqual(result["type"], "CUSTOM")
+        self.assertEqual(result["name"], "user_confirm_result")
+
+    async def test_external_execution_result(self) -> None:
+        """Test ExternalExecutionResultEvent -> CUSTOM."""
+        event = ExternalExecutionResultEvent(
+            reply_id="reply_1",
+            execution_results=[
+                ToolResultBlock(
+                    id="tc_2",
+                    name="external_api",
+                    output="result data",
+                ),
+            ],
+        )
+        result = self.mw._convert_to_protocol(event)
+
+        self.assertEqual(result["type"], "CUSTOM")
+        self.assertEqual(result["name"], "external_execution_result")
+
+    async def asyncTearDown(self) -> None:
+        """The async teardown method."""
+
+
+class AGUIProtocolCamelCaseTest(IsolatedAsyncioTestCase):
+    """Verify that all output dicts use camelCase keys as AGUI requires."""
+
+    async def asyncSetUp(self) -> None:
+        """The async setup method."""
+        self.mw = AGUIProtocolMiddleware(app=MagicMock())
+
+    def _assert_no_snake_case_keys(self, d: dict, context: str) -> None:
+        """Assert none of the top-level keys contain underscores."""
+        for key in d:
+            if key == "value":
+                continue
+            self.assertNotIn(
+                "_",
+                key,
+                f"Key '{key}' in {context} should be camelCase",
+            )
+
+    async def test_all_standard_events_produce_camel_case(self) -> None:
+        """Test that all directly-mapped events produce camelCase keys."""
+        events = [
+            ReplyStartEvent(
+                session_id="s",
+                reply_id="r",
+                name="a",
+            ),
+            ReplyEndEvent(
+                session_id="s",
+                reply_id="r",
+                finished_reason=ReplyEndReason.COMPLETED,
+            ),
+            ModelCallStartEvent(reply_id="r", model_name="m"),
+            ModelCallEndEvent(
+                reply_id="r",
+                input_tokens=1,
+                output_tokens=1,
+                finished_reason=FinishedReason.COMPLETED,
+            ),
+            TextBlockStartEvent(reply_id="r", block_id="b"),
+            TextBlockDeltaEvent(reply_id="r", block_id="b", delta="x"),
+            TextBlockEndEvent(reply_id="r", block_id="b"),
+            ThinkingBlockStartEvent(reply_id="r", block_id="b"),
+            ThinkingBlockDeltaEvent(reply_id="r", block_id="b", delta="x"),
+            ThinkingBlockEndEvent(reply_id="r", block_id="b"),
+            ToolCallStartEvent(
+                reply_id="r",
+                tool_call_id="t",
+                tool_call_name="n",
+            ),
+            ToolCallDeltaEvent(
+                reply_id="r",
+                tool_call_id="t",
+                delta="x",
+            ),
+            ToolCallEndEvent(reply_id="r", tool_call_id="t"),
+            ExceedMaxItersEvent(reply_id="r", name="a"),
+        ]
+
+        for event in events:
+            result = self.mw._convert_to_protocol(event)
+            self._assert_no_snake_case_keys(
+                result,
+                type(event).__name__,
+            )
+
+    async def asyncTearDown(self) -> None:
+        """The async teardown method."""
diff --git a/tests/app_lifespan_dedicated_test.py b/tests/app_lifespan_dedicated_test.py
new file mode 100644
index 0000000..df3cf03
--- /dev/null
+++ b/tests/app_lifespan_dedicated_test.py
@@ -0,0 +1,332 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""End-to-end wiring test for dedicated-deployment knowledge-base upload.
+
+Boots the FastAPI app with ``enable_index_worker=False`` so the API
+process does NOT host an :class:`IndexWorker`. Dispatch happens
+through the message bus: a ``MessageBusDispatcher`` writes the task
+to the shared queue and publishes the signal. In a real deployment
+a separate worker process would pick it up; here we run an
+:class:`IndexTaskConsumer` against a stub worker inside the test
+to confirm the producer side reaches the bus correctly.
+
+What this test guards:
+
+- the API's lifespan accepts ``enable_index_worker=False`` without
+  raising;
+- an upload returns ``201`` and persists a ``pending`` record;
+- the message bus carries the dispatch out of the API process so
+  a worker subscribed on the same bus can consume it;
+- the consumer's ``worker.process`` is invoked exactly once per
+  dispatch, with the same ids the API recorded in storage.
+
+We deliberately do NOT drive the document to ``ready`` here — that
+path is already covered by the embedded-mode upload test. The
+purpose of this test is to lock down the bus hop introduced by
+:class:`MessageBusDispatcher`.
+"""
+import asyncio
+import tempfile
+from typing import Any
+from unittest.async_case import IsolatedAsyncioTestCase
+
+import fakeredis.aioredis
+from fastapi.testclient import TestClient
+
+from agentscope.app import create_app
+from agentscope.app._service import IndexTaskConsumer
+from agentscope.app.rag.blob_store import LocalBlobStore
+from agentscope.app.rag.knowledge_base_manager import (
+    KnowledgeBaseManagerBase,
+    KnowledgeBaseNotFoundError,
+)
+from agentscope.app.rag.knowledge_base_manager._dimension_policy import (
+    DimensionPolicy,
+    DimensionPolicyKind,
+)
+from agentscope.app.message_bus import RedisMessageBus
+from agentscope.app.storage import (
+    EmbeddingModelConfig,
+    KnowledgeBaseRecord,
+    RedisStorage,
+)
+from agentscope.app.workspace_manager._base import WorkspaceManagerBase
+from agentscope.rag import VectorStoreBase
+from agentscope.rag._vdb._vector_store import (
+    DocumentSummary,
+    VectorRecord,
+    VectorSearchResult,
+)
+
+
+# ----------------------------------------------------------------------
+# Test doubles — borrowed in spirit from service_knowledge_base_upload_test
+# but trimmed: the dedicated-mode test does not drive embedding.
+# ----------------------------------------------------------------------
+
+
+class _FakeVectorStore(VectorStoreBase):
+    """Bare minimum to satisfy create_app's vector-store wiring."""
+
+    def __init__(self) -> None:
+        self._collections: dict[str, list[VectorRecord]] = {}
+
+    async def create_collection(self, name: str, dimensions: int) -> None:
+        self._collections.setdefault(name, [])
+
+    async def delete_collection(self, name: str) -> None:
+        self._collections.pop(name, None)
+
+    async def has_collection(self, name: str) -> bool:
+        return name in self._collections
+
+    async def insert(
+        self,
+        collection: str,
+        records: list[VectorRecord],
+    ) -> None:
+        self._collections.setdefault(collection, []).extend(records)
+
+    async def delete(self, collection: str, document_id: str) -> None:
+        self._collections[collection] = [
+            r
+            for r in self._collections.get(collection, [])
+            if r.document_id != document_id
+        ]
+
+    async def search(
+        self,
+        collection: str,
+        query_vector: list[float],
+        top_k: int = 5,
+        metadata_filter: dict[str, Any] | None = None,
+    ) -> list[VectorSearchResult]:
+        return []
+
+    async def list_documents(
+        self,
+        collection: str,
+        metadata_filter: dict[str, Any] | None = None,
+    ) -> list[DocumentSummary]:
+        return []
+
+
+class _FakeKbManager(KnowledgeBaseManagerBase):
+    """KB manager that resolves knowledge bases via storage only.
+
+    Returns a noop knowledge for ``get_knowledge`` because dedicated
+    mode does not exercise embedding in this test — the worker stub
+    intercepts ``process`` before the knowledge call.
+    """
+
+    async def get_dimension_policy(self) -> DimensionPolicy:
+        return DimensionPolicy(kind=DimensionPolicyKind.ANY, dimension=None)
+
+    async def create_knowledge_base(
+        self,
+        user_id: str,
+        name: str,
+        description: str,
+        embedding_model_config: EmbeddingModelConfig,
+    ) -> KnowledgeBaseRecord:
+        raise NotImplementedError
+
+    async def delete_knowledge_base(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+    ) -> bool:
+        return False
+
+    async def get_knowledge(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+    ) -> Any:
+        record = await self._storage.get_knowledge_base(
+            user_id,
+            knowledge_base_id,
+        )
+        if record is None:
+            raise KnowledgeBaseNotFoundError(
+                f"Knowledge base {knowledge_base_id!r} not found.",
+            )
+        raise NotImplementedError  # unused in this test
+
+
+class _NoopWorkspaceManager(WorkspaceManagerBase):
+    """Workspace manager that does nothing."""
+
+    async def get_workspace(self, *args: Any, **kwargs: Any) -> Any:
+        """Fake implementation."""
+        raise NotImplementedError
+
+    async def close(self, workspace_id: str) -> None:
+        """Fake implementation."""
+        return None
+
+    async def close_all(self) -> None:
+        """Fake implementation."""
+        return None
+
+
+def _make_storage(fr: fakeredis.aioredis.FakeRedis) -> RedisStorage:
+    class _FakeStorage(RedisStorage):
+        async def __aenter__(self) -> "_FakeStorage":  # type: ignore[override]
+            self._client = fr
+            return self
+
+        async def aclose(self) -> None:
+            self._client = None
+
+    return _FakeStorage()
+
+
+def _make_bus(fr: fakeredis.aioredis.FakeRedis) -> RedisMessageBus:
+    class _FakeBus(RedisMessageBus):
+        async def __aenter__(self) -> "_FakeBus":  # type: ignore[override]
+            self._client = fr
+            return self
+
+        async def aclose(self) -> None:
+            self._client = None
+
+    return _FakeBus()
+
+
+class _RecordingWorker:
+    """Stub worker that records each ``process`` invocation.
+
+    Stands in for :class:`IndexWorker` in the test so we can verify
+    that the dispatch hop landed without spinning up the full
+    parse → chunk → embed pipeline.
+    """
+
+    def __init__(self) -> None:
+        self.calls: list[dict] = []
+        self.notify = asyncio.Event()
+
+    async def process(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+        document_id: str,
+    ) -> None:
+        """Record the dispatched task and signal the test.
+
+        Stands in for :class:`IndexWorker.process_one` so the lifespan
+        tests can assert that the API process forwarded the right
+        ``user_id`` / ``knowledge_base_id`` / ``document_id`` triple.
+
+        Args:
+            user_id (`str`):
+                The owning user id.
+            knowledge_base_id (`str`):
+                The parent knowledge base id.
+            document_id (`str`):
+                The document id to "process".
+        """
+        self.calls.append(
+            {
+                "user_id": user_id,
+                "knowledge_base_id": knowledge_base_id,
+                "document_id": document_id,
+            },
+        )
+        self.notify.set()
+
+
+class DedicatedModeUploadFlowTest(IsolatedAsyncioTestCase):
+    """The producer side reaches the bus; a separate consumer sees it."""
+
+    async def asyncSetUp(self) -> None:
+        self._tmp = tempfile.TemporaryDirectory()
+        self._fr = fakeredis.aioredis.FakeRedis(decode_responses=True)
+        self._vector_store = _FakeVectorStore()
+        storage = _make_storage(self._fr)
+        self._api_message_bus = _make_bus(self._fr)
+
+        self._app = create_app(
+            storage=storage,
+            message_bus=self._api_message_bus,
+            workspace_manager=_NoopWorkspaceManager(),
+            knowledge_base_manager=_FakeKbManager(
+                storage=storage,
+                vector_store=self._vector_store,
+            ),
+            blob_store=LocalBlobStore(root_dir=self._tmp.name),
+            enable_index_worker=False,
+        )
+
+        # Seed a knowledge base directly so we don't have to mock the
+        # manager's create flow over HTTP.
+        kb_record = KnowledgeBaseRecord(
+            user_id="user-1",
+            name="kb",
+            description="",
+            embedding_model_config=EmbeddingModelConfig(
+                type="openai_credential",
+                credential_id="cred-1",
+                model="text-embedding-3-small",
+                dimensions=1,
+            ),
+            collection_name="",
+        )
+        kb_record.collection_name = f"kb_{kb_record.id}"
+        await self._vector_store.create_collection(
+            kb_record.collection_name,
+            1,
+        )
+        storage._client = self._fr
+        await storage.upsert_knowledge_base("user-1", kb_record)
+        storage._client = None
+        self._kb_id = kb_record.id
+
+    async def asyncTearDown(self) -> None:
+        await self._fr.aclose()
+        self._tmp.cleanup()
+
+    async def test_upload_dispatches_through_message_bus(self) -> None:
+        """An upload in dedicated mode reaches a separate consumer."""
+        # The consumer's bus is a SEPARATE RedisMessageBus instance
+        # bound to the same fakeredis store. Production wiring would
+        # be two TCP-connected clients; here they share the in-memory
+        # backend, which exercises the bus contract correctly.
+        consumer_bus = _make_bus(self._fr)
+        worker = _RecordingWorker()
+
+        async with consumer_bus, IndexTaskConsumer(
+            message_bus=consumer_bus,
+            worker=worker,
+        ):
+            headers = {"X-User-ID": "user-1"}
+            with TestClient(self._app) as client:
+                files = {
+                    "file": (
+                        "hello.txt",
+                        b"hello world\n" * 16,
+                        "text/plain",
+                    ),
+                }
+                resp = client.post(
+                    f"/knowledge_bases/{self._kb_id}/documents",
+                    files=files,
+                    headers=headers,
+                )
+                self.assertEqual(resp.status_code, 201, resp.text)
+                body = resp.json()
+                document_id = body["document_id"]
+
+            # The consumer's worker should see the dispatch.
+            await asyncio.wait_for(worker.notify.wait(), timeout=5.0)
+
+        self.assertEqual(
+            worker.calls,
+            [
+                {
+                    "user_id": "user-1",
+                    "knowledge_base_id": self._kb_id,
+                    "document_id": document_id,
+                },
+            ],
+        )
diff --git a/tests/backend_docker_test.py b/tests/backend_docker_test.py
new file mode 100644
index 0000000..6247374
--- /dev/null
+++ b/tests/backend_docker_test.py
@@ -0,0 +1,214 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Test cases for :class:`DockerBackend`.
+
+Validates that the three backend primitives (``exec_shell``,
+``read_file``, ``write_file``) and the inherited shell-based filesystem
+helpers behave correctly inside a real Docker container.
+
+The suite is skipped unless:
+
+* the Docker daemon is reachable (probed via ``docker info``), and
+* the host is Linux — the project only validates the Docker backend on
+  Ubuntu/Linux CI runners; spinning containers up on other hosts is
+  out of scope for these tests.
+
+A live container is obtained by initializing a :class:`DockerWorkspace`
+and reusing its already-wired :class:`DockerBackend` (``ws._backend``),
+which avoids duplicating the container bring-up logic here.
+"""
+
+import shutil
+import subprocess
+import sys
+import tempfile
+import unittest
+import uuid
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from agentscope.tool import ExecResult
+from agentscope.workspace import DockerWorkspace, DockerBackend
+from agentscope.workspace._docker._make_dockerfile import CONTAINER_WORKDIR
+
+
+# ── availability checks ────────────────────────────────────────────
+
+
+def _docker_available() -> bool:
+    """Return ``True`` iff the Docker daemon is reachable.
+
+    Probes via the ``docker`` CLI (cheap, synchronous) so the result can
+    gate the module at import time.
+    """
+    if shutil.which("docker") is None:
+        return False
+    try:
+        result = subprocess.run(
+            ["docker", "info"],
+            capture_output=True,
+            timeout=5,
+            check=False,
+        )
+        return result.returncode == 0
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        return False
+
+
+_IS_LINUX = sys.platform == "linux"
+_DOCKER_OK = _IS_LINUX and _docker_available()
+_SKIP_REASON = "Docker backend is only tested on Linux with a live daemon"
+
+
+@unittest.skipUnless(_DOCKER_OK, _SKIP_REASON)
+class TestDockerBackend(IsolatedAsyncioTestCase):
+    """Test cases for ``DockerBackend`` against a live container."""
+
+    async def asyncSetUp(self) -> None:
+        """Start a workspace and reuse its wired backend.
+
+        The ``workspace_id`` is randomised so concurrent / repeated runs
+        do not collide on the deterministic container name.
+        """
+        # pylint: disable=consider-using-with
+        self.temp_dir = tempfile.TemporaryDirectory()
+        self.workspace = DockerWorkspace(
+            workspace_id=f"test-{uuid.uuid4().hex[:8]}",
+            host_workdir=self.temp_dir.name,
+        )
+        await self.workspace.initialize()
+        self.backend = self.workspace._backend
+        self.assertIsInstance(self.backend, DockerBackend)
+
+    async def asyncTearDown(self) -> None:
+        """Stop the container and drop the temp host dir."""
+        try:
+            await self.workspace.close()
+        finally:
+            self.temp_dir.cleanup()
+
+    # ── exec ───────────────────────────────────────────────────────
+
+    async def test_exec_returns_stdout(self) -> None:
+        """A program's stdout/exit code are captured into ``ExecResult``."""
+        result = await self.backend.exec_shell(["echo", "hello world"])
+        self.assertIsInstance(result, ExecResult)
+        self.assertTrue(result.ok())
+        self.assertEqual(result.stdout.decode().strip(), "hello world")
+
+    async def test_exec_nonzero_exit(self) -> None:
+        """A non-zero exit is reported as a normal (non-raising) result."""
+        result = await self.backend.exec_shell(
+            ["sh", "-c", "echo oops >&2; exit 4"],
+        )
+        self.assertEqual(result.exit_code, 4)
+        self.assertIn("oops", result.stderr.decode())
+
+    async def test_exec_argv_not_shell_split(self) -> None:
+        """A single argv element with metacharacters reaches the program
+        intact (no shell interposed by the primitive)."""
+        tricky = "a b $(echo x) | ;"
+        result = await self.backend.exec_shell(["echo", tricky])
+        self.assertTrue(result.ok())
+        self.assertEqual(result.stdout.decode().rstrip("\n"), tricky)
+
+    async def test_exec_cwd_default_is_workdir(self) -> None:
+        """With no explicit ``cwd`` the container workdir is used."""
+        result = await self.backend.exec_shell(["pwd"])
+        self.assertTrue(result.ok())
+        self.assertEqual(result.stdout.decode().strip(), CONTAINER_WORKDIR)
+
+    async def test_exec_timeout_returns_minus_one(self) -> None:
+        """A command exceeding ``timeout`` reports the -1 sentinel."""
+        result = await self.backend.exec_shell(
+            ["sleep", "10"],
+            timeout=0.5,
+        )
+        self.assertEqual(result.exit_code, -1)
+        self.assertEqual(result.stderr, b"timed out")
+
+    # ── file I/O ───────────────────────────────────────────────────
+
+    async def test_write_then_read_roundtrip(self) -> None:
+        """Bytes written into the container are read back verbatim."""
+        path = f"{CONTAINER_WORKDIR}/roundtrip.txt"
+        payload = b"hello\nworld\n"
+        await self.backend.write_file(path, payload)
+        self.assertEqual(await self.backend.read_file(path), payload)
+
+    async def test_write_creates_parent_dirs(self) -> None:
+        """``write_file`` creates missing parent directories."""
+        path = f"{CONTAINER_WORKDIR}/a/b/c/file.txt"
+        await self.backend.write_file(path, b"x")
+        self.assertEqual(await self.backend.read_file(path), b"x")
+
+    async def test_write_preserves_binary(self) -> None:
+        """Raw bytes (incl. NULs and high bytes) survive the round-trip."""
+        path = f"{CONTAINER_WORKDIR}/bin.dat"
+        payload = b"a\r\nb\x00\xffc"
+        await self.backend.write_file(path, payload)
+        self.assertEqual(await self.backend.read_file(path), payload)
+
+    async def test_read_missing_file_raises(self) -> None:
+        """Reading a non-existent file raises ``FileNotFoundError``."""
+        with self.assertRaises(FileNotFoundError):
+            await self.backend.read_file(f"{CONTAINER_WORKDIR}/nope.txt")
+
+    # ── derived filesystem helpers (shell-based) ───────────────────
+
+    async def test_file_exists_and_is_dir(self) -> None:
+        """``file_exists`` / ``is_dir`` reflect the container filesystem."""
+        path = f"{CONTAINER_WORKDIR}/f.txt"
+        await self.backend.write_file(path, b"x")
+        self.assertTrue(await self.backend.file_exists(path))
+        self.assertTrue(await self.backend.file_exists(CONTAINER_WORKDIR))
+        self.assertTrue(await self.backend.is_dir(CONTAINER_WORKDIR))
+        self.assertFalse(await self.backend.is_dir(path))
+        self.assertFalse(
+            await self.backend.file_exists(
+                f"{CONTAINER_WORKDIR}/missing",
+            ),
+        )
+
+    async def test_list_dir(self) -> None:
+        """Non-recursive ``list_dir`` returns immediate child base names."""
+        base = f"{CONTAINER_WORKDIR}/listing"
+        await self.backend.write_file(f"{base}/a.txt", b"x")
+        await self.backend.write_file(f"{base}/b.txt", b"x")
+        entries = await self.backend.list_dir(base)
+        self.assertEqual(sorted(entries), ["a.txt", "b.txt"])
+
+    async def test_list_dir_recursive(self) -> None:
+        """Recursive ``list_dir`` returns file paths underneath the root."""
+        base = f"{CONTAINER_WORKDIR}/rec"
+        await self.backend.write_file(f"{base}/top.txt", b"x")
+        await self.backend.write_file(f"{base}/sub/nested.txt", b"x")
+        entries = await self.backend.list_dir(base, recursive=True)
+        basenames = sorted(e.rsplit("/", 1)[-1] for e in entries)
+        self.assertEqual(basenames, ["nested.txt", "top.txt"])
+
+    async def test_stat_mtime(self) -> None:
+        """``stat_mtime`` returns a float for an existing path, None else."""
+        path = f"{CONTAINER_WORKDIR}/stat.txt"
+        await self.backend.write_file(path, b"x")
+        mtime = await self.backend.stat_mtime(path)
+        self.assertIsInstance(mtime, float)
+        self.assertIsNone(
+            await self.backend.stat_mtime(
+                f"{CONTAINER_WORKDIR}/missing",
+            ),
+        )
+
+    async def test_delete_path(self) -> None:
+        """``delete_path`` removes files and trees; missing is a no-op."""
+        path = f"{CONTAINER_WORKDIR}/to_delete.txt"
+        await self.backend.write_file(path, b"x")
+        await self.backend.delete_path(path)
+        self.assertFalse(await self.backend.file_exists(path))
+
+        tree = f"{CONTAINER_WORKDIR}/tree"
+        await self.backend.write_file(f"{tree}/deep/f.txt", b"x")
+        await self.backend.delete_path(tree)
+        self.assertFalse(await self.backend.file_exists(tree))
+
+        # Deleting a non-existent path must not raise.
+        await self.backend.delete_path(f"{CONTAINER_WORKDIR}/missing")
diff --git a/tests/backend_e2b_test.py b/tests/backend_e2b_test.py
new file mode 100644
index 0000000..7da1412
--- /dev/null
+++ b/tests/backend_e2b_test.py
@@ -0,0 +1,149 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Test cases for :class:`E2BBackend`.
+
+Validates that the three backend primitives (``exec_shell``,
+``read_file``, ``write_file``) and the inherited shell-based filesystem
+helpers behave correctly inside a real E2B cloud sandbox.
+
+The whole module is skipped unless the ``E2B_API_KEY`` environment
+variable is set, because every test requires a live E2B sandbox.  CI
+runs without E2B credentials are therefore unaffected; when a key *is*
+present the tests exercise the real ``commands.run`` / ``files.*`` APIs.
+
+A live sandbox is obtained by initializing an :class:`E2BWorkspace` and
+reusing its already-wired :class:`E2BBackend` (``ws._backend``), which
+avoids duplicating the sandbox bring-up logic here.
+"""
+
+import os
+import unittest
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from agentscope.tool import ExecResult
+from agentscope.workspace import E2BWorkspace
+from agentscope.workspace import E2BBackend
+from agentscope.workspace._e2b._constants import SANDBOX_WORKDIR
+
+
+# ── E2B availability check ─────────────────────────────────────────
+
+_E2B_API_KEY = os.getenv("E2B_API_KEY", "")
+_SKIP_REASON = "E2B_API_KEY environment variable is not set"
+
+
+@unittest.skipUnless(_E2B_API_KEY, _SKIP_REASON)
+class TestE2BBackend(IsolatedAsyncioTestCase):
+    """Test cases for ``E2BBackend`` against a live sandbox.
+
+    Each test creates a real E2B cloud sandbox via ``E2BWorkspace`` and
+    tears it down (``close`` → sandbox pause) afterwards.
+    """
+
+    async def asyncSetUp(self) -> None:
+        """Start a workspace and reuse its wired backend."""
+        self.workspace = E2BWorkspace(api_key=_E2B_API_KEY)
+        await self.workspace.initialize()
+        self.backend = self.workspace._backend
+        self.assertIsInstance(self.backend, E2BBackend)
+
+    async def asyncTearDown(self) -> None:
+        """Pause / close the sandbox."""
+        await self.workspace.close()
+
+    # ── exec ───────────────────────────────────────────────────────
+
+    async def test_exec_returns_stdout(self) -> None:
+        """A program's stdout/exit code are captured into ``ExecResult``."""
+        result = await self.backend.exec_shell(["echo", "hello world"])
+        self.assertIsInstance(result, ExecResult)
+        self.assertTrue(result.ok())
+        self.assertEqual(result.stdout.decode().strip(), "hello world")
+
+    async def test_exec_nonzero_exit(self) -> None:
+        """A non-zero command exit is reported as a normal result."""
+        result = await self.backend.exec_shell(
+            ["sh", "-c", "echo oops >&2; exit 4"],
+        )
+        self.assertEqual(result.exit_code, 4)
+        self.assertIn("oops", result.stderr.decode())
+
+    async def test_exec_argv_quoting_preserved(self) -> None:
+        """An argv element with spaces / metacharacters survives the
+        POSIX-quote round-trip the backend does for ``commands.run``."""
+        tricky = "a b c | ;"
+        result = await self.backend.exec_shell(["echo", tricky])
+        self.assertTrue(result.ok())
+        self.assertEqual(result.stdout.decode().rstrip("\n"), tricky)
+
+    async def test_exec_cwd_default_is_workdir(self) -> None:
+        """With no explicit ``cwd`` the sandbox workdir is used."""
+        result = await self.backend.exec_shell(["pwd"])
+        self.assertTrue(result.ok())
+        self.assertEqual(result.stdout.decode().strip(), SANDBOX_WORKDIR)
+
+    # ── file I/O ───────────────────────────────────────────────────
+
+    async def test_write_then_read_roundtrip(self) -> None:
+        """Bytes written into the sandbox are read back verbatim."""
+        path = f"{SANDBOX_WORKDIR}/roundtrip.txt"
+        payload = b"hello\nworld\n"
+        await self.backend.write_file(path, payload)
+        self.assertEqual(await self.backend.read_file(path), payload)
+
+    async def test_write_creates_parent_dirs(self) -> None:
+        """``write_file`` creates missing parent directories."""
+        path = f"{SANDBOX_WORKDIR}/a/b/c/file.txt"
+        await self.backend.write_file(path, b"x")
+        self.assertEqual(await self.backend.read_file(path), b"x")
+
+    async def test_read_missing_file_raises(self) -> None:
+        """Reading a non-existent file raises ``FileNotFoundError``."""
+        with self.assertRaises(FileNotFoundError):
+            await self.backend.read_file(f"{SANDBOX_WORKDIR}/nope.txt")
+
+    # ── derived filesystem helpers (shell-based) ───────────────────
+
+    async def test_file_exists_and_is_dir(self) -> None:
+        """``file_exists`` / ``is_dir`` reflect the sandbox filesystem."""
+        path = f"{SANDBOX_WORKDIR}/f.txt"
+        await self.backend.write_file(path, b"x")
+        self.assertTrue(await self.backend.file_exists(path))
+        self.assertTrue(await self.backend.is_dir(SANDBOX_WORKDIR))
+        self.assertFalse(await self.backend.is_dir(path))
+        self.assertFalse(
+            await self.backend.file_exists(f"{SANDBOX_WORKDIR}/missing"),
+        )
+
+    async def test_list_dir(self) -> None:
+        """Non-recursive ``list_dir`` returns immediate child base names."""
+        base = f"{SANDBOX_WORKDIR}/listing"
+        await self.backend.write_file(f"{base}/a.txt", b"x")
+        await self.backend.write_file(f"{base}/b.txt", b"x")
+        entries = await self.backend.list_dir(base)
+        self.assertEqual(sorted(entries), ["a.txt", "b.txt"])
+
+    async def test_stat_mtime(self) -> None:
+        """``stat_mtime`` returns a float for an existing path, None else."""
+        path = f"{SANDBOX_WORKDIR}/stat.txt"
+        await self.backend.write_file(path, b"x")
+        mtime = await self.backend.stat_mtime(path)
+        self.assertIsInstance(mtime, float)
+        self.assertIsNone(
+            await self.backend.stat_mtime(f"{SANDBOX_WORKDIR}/missing"),
+        )
+
+    async def test_delete_path(self) -> None:
+        """``delete_path`` removes files and trees; missing is a no-op."""
+        path = f"{SANDBOX_WORKDIR}/to_delete.txt"
+        await self.backend.write_file(path, b"x")
+        await self.backend.delete_path(path)
+        self.assertFalse(await self.backend.file_exists(path))
+
+        tree = f"{SANDBOX_WORKDIR}/tree"
+        await self.backend.write_file(f"{tree}/deep/f.txt", b"x")
+        await self.backend.delete_path(tree)
+        self.assertFalse(await self.backend.file_exists(tree))
+
+        # Deleting a non-existent path must not raise.
+        await self.backend.delete_path(f"{SANDBOX_WORKDIR}/missing")
diff --git a/tests/backend_local_test.py b/tests/backend_local_test.py
new file mode 100644
index 0000000..3d23366
--- /dev/null
+++ b/tests/backend_local_test.py
@@ -0,0 +1,329 @@
+# -*- coding: utf-8 -*-
+"""Test cases for :class:`LocalBackend` and the backend helpers.
+
+Exercises the three abstract primitives (``exec_shell``, ``read_file``,
+``write_file``) plus the derived filesystem helpers (``file_exists``,
+``is_dir``, ``list_dir``, ``stat_mtime``, ``delete_path``) of the
+host-local backend, and the module-level ``normalize_newlines`` helper.
+
+``LocalBackend`` is designed to run on every platform (it spawns
+programs from an argv list without a shell and implements the
+filesystem helpers with native ``os.*`` calls), so the bulk of this
+module runs on Windows too.  Only the handful of cases that genuinely
+rely on a POSIX shell / POSIX-only utilities are skipped on Windows.
+"""
+
+import os
+import sys
+import tempfile
+import unittest
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from agentscope.tool import ExecResult, LocalBackend
+from agentscope.tool._builtin._backend import _normalize_newlines
+
+_IS_WINDOWS = sys.platform == "win32"
+
+
+class TestNormalizeNewlines(unittest.TestCase):
+    """Unit tests for the ``normalize_newlines`` helper (pure, no I/O)."""
+
+    def test_crlf_collapsed_to_lf(self) -> None:
+        """Windows ``\\r\\n`` is collapsed to a single ``\\n``."""
+        self.assertEqual(
+            _normalize_newlines("a\r\nb\r\nc"),
+            "a\nb\nc",
+        )
+
+    def test_lone_cr_collapsed_to_lf(self) -> None:
+        """Classic-Mac lone ``\\r`` is collapsed to ``\\n``."""
+        self.assertEqual(_normalize_newlines("a\rb\rc"), "a\nb\nc")
+
+    def test_mixed_endings(self) -> None:
+        """A mix of ``\\r\\n``, ``\\r`` and ``\\n`` normalizes uniformly."""
+        self.assertEqual(
+            _normalize_newlines("a\r\nb\rc\nd"),
+            "a\nb\nc\nd",
+        )
+
+    def test_plain_lf_unchanged(self) -> None:
+        """Text already using ``\\n`` is returned unchanged."""
+        self.assertEqual(_normalize_newlines("a\nb\nc"), "a\nb\nc")
+
+    def test_no_double_collapse(self) -> None:
+        """``\\r\\n`` becomes exactly one ``\\n`` (not two)."""
+        self.assertEqual(_normalize_newlines("a\r\n\r\nb"), "a\n\nb")
+
+
+class TestLocalBackendExec(IsolatedAsyncioTestCase):
+    """Test cases for ``LocalBackend.exec_shell``."""
+
+    async def asyncSetUp(self) -> None:
+        """Build a fresh backend per test."""
+        self.backend = LocalBackend()
+
+    async def test_exec_returns_stdout(self) -> None:
+        """A program's stdout/exit code are captured into ``ExecResult``.
+
+        Uses the current interpreter so the test is portable across
+        platforms (no reliance on ``echo`` / shell builtins).
+        """
+        result = await self.backend.exec_shell(
+            [sys.executable, "-c", "print('hello world')"],
+        )
+        self.assertIsInstance(result, ExecResult)
+        self.assertTrue(result.ok())
+        self.assertEqual(result.exit_code, 0)
+        self.assertEqual(result.stdout.decode().strip(), "hello world")
+        self.assertEqual(result.stderr, b"")
+
+    async def test_exec_captures_stderr_and_exit_code(self) -> None:
+        """A non-zero exit and stderr bytes are reported faithfully."""
+        result = await self.backend.exec_shell(
+            [
+                sys.executable,
+                "-c",
+                "import sys; sys.stderr.write('boom'); sys.exit(3)",
+            ],
+        )
+        self.assertFalse(result.ok())
+        self.assertEqual(result.exit_code, 3)
+        self.assertEqual(result.stderr.decode().strip(), "boom")
+
+    async def test_exec_argv_not_split_by_shell(self) -> None:
+        """Arguments are passed verbatim (no shell word-splitting/globbing).
+
+        A single argument containing spaces and shell metacharacters must
+        reach the program intact, proving no shell is interposed.
+        """
+        tricky = "a b $(echo x) | & ; '\""
+        result = await self.backend.exec_shell(
+            [sys.executable, "-c", "import sys; print(sys.argv[1])", tricky],
+        )
+        self.assertTrue(result.ok())
+        self.assertEqual(result.stdout.decode().rstrip("\r\n"), tricky)
+
+    async def test_exec_cwd_is_respected(self) -> None:
+        """``cwd`` sets the subprocess working directory."""
+        with tempfile.TemporaryDirectory() as tmp:
+            result = await self.backend.exec_shell(
+                [sys.executable, "-c", "import os; print(os.getcwd())"],
+                cwd=tmp,
+            )
+            self.assertTrue(result.ok())
+            self.assertEqual(
+                os.path.realpath(result.stdout.decode().strip()),
+                os.path.realpath(tmp),
+            )
+
+    async def test_missing_executable_returns_127(self) -> None:
+        """An unspawnable executable yields exit code 127 (not an exception).
+
+        Mirrors a shell's "command not found" so callers see a normal
+        non-zero ``ExecResult``.
+        """
+        result = await self.backend.exec_shell(
+            ["this_executable_does_not_exist_xyz", "--nope"],
+        )
+        self.assertEqual(result.exit_code, 127)
+        self.assertEqual(result.stdout, b"")
+        self.assertNotEqual(result.stderr, b"")
+
+    async def test_timeout_returns_minus_one(self) -> None:
+        """A command exceeding ``timeout`` is killed and reports -1.
+
+        The sentinel ``ExecResult(exit_code=-1, stderr=b"timed out")`` is
+        what Grep/Glob check for, so it is asserted exactly.
+        """
+        result = await self.backend.exec_shell(
+            [sys.executable, "-c", "import time; time.sleep(10)"],
+            timeout=0.2,
+        )
+        self.assertEqual(result.exit_code, -1)
+        self.assertEqual(result.stderr, b"timed out")
+
+
+class TestLocalBackendFileIO(IsolatedAsyncioTestCase):
+    """Test cases for ``read_file`` / ``write_file`` round-trips."""
+
+    async def asyncSetUp(self) -> None:
+        """Build a backend and a temp dir per test."""
+        # pylint: disable=consider-using-with
+        self.backend = LocalBackend()
+        self.temp_dir = tempfile.TemporaryDirectory()
+
+    async def asyncTearDown(self) -> None:
+        """Drop the temp dir."""
+        self.temp_dir.cleanup()
+
+    async def test_write_then_read_roundtrip(self) -> None:
+        """Bytes written are read back verbatim."""
+        path = os.path.join(self.temp_dir.name, "file.txt")
+        payload = b"hello\nworld\n"
+        await self.backend.write_file(path, payload)
+        self.assertEqual(await self.backend.read_file(path), payload)
+
+    async def test_write_creates_parent_dirs(self) -> None:
+        """``write_file`` creates missing parent directories."""
+        path = os.path.join(self.temp_dir.name, "a", "b", "c", "file.txt")
+        await self.backend.write_file(path, b"x")
+        self.assertTrue(os.path.exists(path))
+        self.assertEqual(await self.backend.read_file(path), b"x")
+
+    async def test_write_preserves_binary_and_crlf(self) -> None:
+        """Raw bytes (incl. ``\\r\\n`` and NULs) survive the round-trip.
+
+        The backend deals in raw bytes; newline normalization happens
+        later in the text layer, never here.
+        """
+        path = os.path.join(self.temp_dir.name, "bin.dat")
+        payload = b"a\r\nb\x00\xffc"
+        await self.backend.write_file(path, payload)
+        self.assertEqual(await self.backend.read_file(path), payload)
+
+    async def test_read_missing_file_raises(self) -> None:
+        """Reading a non-existent file raises ``FileNotFoundError``."""
+        path = os.path.join(self.temp_dir.name, "nope.txt")
+        with self.assertRaises(FileNotFoundError):
+            await self.backend.read_file(path)
+
+
+class TestLocalBackendFilesystemHelpers(IsolatedAsyncioTestCase):
+    """Test cases for the derived filesystem helpers (native ``os.*``)."""
+
+    async def asyncSetUp(self) -> None:
+        """Build a backend and a temp dir per test."""
+        # pylint: disable=consider-using-with
+        self.backend = LocalBackend()
+        self.temp_dir = tempfile.TemporaryDirectory()
+
+    async def asyncTearDown(self) -> None:
+        """Drop the temp dir."""
+        self.temp_dir.cleanup()
+
+    async def test_file_exists(self) -> None:
+        """``file_exists`` is True for files and dirs, False otherwise."""
+        path = os.path.join(self.temp_dir.name, "f.txt")
+        await self.backend.write_file(path, b"x")
+        self.assertTrue(await self.backend.file_exists(path))
+        self.assertTrue(await self.backend.file_exists(self.temp_dir.name))
+        self.assertFalse(
+            await self.backend.file_exists(
+                os.path.join(self.temp_dir.name, "missing"),
+            ),
+        )
+
+    async def test_is_dir(self) -> None:
+        """``is_dir`` distinguishes directories from files."""
+        path = os.path.join(self.temp_dir.name, "f.txt")
+        await self.backend.write_file(path, b"x")
+        self.assertTrue(await self.backend.is_dir(self.temp_dir.name))
+        self.assertFalse(await self.backend.is_dir(path))
+        self.assertFalse(
+            await self.backend.is_dir(
+                os.path.join(self.temp_dir.name, "missing"),
+            ),
+        )
+
+    async def test_list_dir_shallow(self) -> None:
+        """Non-recursive ``list_dir`` returns immediate child base names."""
+        for name in ("a.txt", "b.txt"):
+            await self.backend.write_file(
+                os.path.join(self.temp_dir.name, name),
+                b"x",
+            )
+        os.makedirs(os.path.join(self.temp_dir.name, "sub"))
+        entries = await self.backend.list_dir(self.temp_dir.name)
+        self.assertEqual(sorted(entries), ["a.txt", "b.txt", "sub"])
+
+    async def test_list_dir_recursive(self) -> None:
+        """Recursive ``list_dir`` returns file paths underneath the root."""
+        await self.backend.write_file(
+            os.path.join(self.temp_dir.name, "top.txt"),
+            b"x",
+        )
+        await self.backend.write_file(
+            os.path.join(self.temp_dir.name, "sub", "nested.txt"),
+            b"x",
+        )
+        entries = await self.backend.list_dir(
+            self.temp_dir.name,
+            recursive=True,
+        )
+        basenames = sorted(os.path.basename(e) for e in entries)
+        self.assertEqual(basenames, ["nested.txt", "top.txt"])
+
+    async def test_stat_mtime(self) -> None:
+        """``stat_mtime`` returns a float for an existing path, None else."""
+        path = os.path.join(self.temp_dir.name, "f.txt")
+        await self.backend.write_file(path, b"x")
+        mtime = await self.backend.stat_mtime(path)
+        self.assertIsInstance(mtime, float)
+        self.assertIsNone(
+            await self.backend.stat_mtime(
+                os.path.join(self.temp_dir.name, "missing"),
+            ),
+        )
+
+    async def test_delete_path_file(self) -> None:
+        """``delete_path`` removes a single file."""
+        path = os.path.join(self.temp_dir.name, "f.txt")
+        await self.backend.write_file(path, b"x")
+        await self.backend.delete_path(path)
+        self.assertFalse(os.path.exists(path))
+
+    async def test_delete_path_tree(self) -> None:
+        """``delete_path`` removes a directory tree recursively."""
+        nested = os.path.join(self.temp_dir.name, "d", "e")
+        os.makedirs(nested)
+        await self.backend.write_file(
+            os.path.join(nested, "f.txt"),
+            b"x",
+        )
+        target = os.path.join(self.temp_dir.name, "d")
+        await self.backend.delete_path(target)
+        self.assertFalse(os.path.exists(target))
+
+    async def test_delete_path_missing_is_noop(self) -> None:
+        """Deleting a non-existent path is a silent no-op (like rm -rf)."""
+        # Must not raise.
+        await self.backend.delete_path(
+            os.path.join(self.temp_dir.name, "missing"),
+        )
+
+
+@unittest.skipIf(
+    _IS_WINDOWS,
+    "POSIX shell (/bin/sh) is not available on Windows",
+)
+class TestLocalBackendShellWrapping(IsolatedAsyncioTestCase):
+    """Cases that explicitly use ``sh -c`` (POSIX-only, skipped on Windows).
+
+    The backend primitive never invokes a shell itself; these tests cover
+    the documented escape hatch where a *caller* wraps a command line as
+    ``["/bin/sh", "-c", line]`` to use pipes / redirects / ``&&``.
+    """
+
+    async def asyncSetUp(self) -> None:
+        """Build a backend per test."""
+        self.backend = LocalBackend()
+
+    async def test_sh_c_pipeline(self) -> None:
+        """A piped command line runs when wrapped in ``sh -c``."""
+        result = await self.backend.exec_shell(
+            ["/bin/sh", "-c", "printf 'a\\nb\\na\\n' | sort | uniq"],
+        )
+        self.assertTrue(result.ok())
+        self.assertEqual(result.stdout.decode().split(), ["a", "b"])
+
+    async def test_sh_c_and_chain(self) -> None:
+        """``&&`` chaining works through ``sh -c``."""
+        result = await self.backend.exec_shell(
+            ["/bin/sh", "-c", "true && echo chained"],
+        )
+        self.assertTrue(result.ok())
+        self.assertEqual(result.stdout.decode().strip(), "chained")
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/backend_opensandbox_test.py b/tests/backend_opensandbox_test.py
new file mode 100644
index 0000000..1be34df
--- /dev/null
+++ b/tests/backend_opensandbox_test.py
@@ -0,0 +1,155 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Test cases for :class:`OpenSandboxBackend`.
+
+Validates that the three backend primitives (``exec_shell``,
+``read_file``, ``write_file``) and the inherited shell-based filesystem
+helpers behave correctly inside a real OpenSandbox sandbox.
+
+The whole module is skipped unless the ``OPENSANDBOX_DOMAIN`` environment
+variable is set, because every test requires a live OpenSandbox service.
+CI runs without OpenSandbox access are therefore unaffected; when a
+domain *is* present the tests exercise the real ``commands.run`` /
+``files.*`` APIs.
+
+A live sandbox is obtained by initializing an :class:`OpenSandboxWorkspace`
+and reusing its already-wired :class:`OpenSandboxBackend` (``ws._backend``),
+which avoids duplicating the sandbox bring-up logic here.
+"""
+
+import os
+import unittest
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from agentscope.tool import ExecResult
+from agentscope.workspace import OpenSandboxWorkspace
+from agentscope.workspace import OpenSandboxBackend
+from agentscope.workspace._opensandbox._constants import SANDBOX_WORKDIR
+
+
+# ── OpenSandbox availability check ─────────────────────────────────
+
+_DOMAIN = os.getenv("OPENSANDBOX_DOMAIN", "")
+_API_KEY = os.getenv("OPENSANDBOX_API_KEY", "")
+_SKIP_REASON = "OPENSANDBOX_DOMAIN environment variable is not set"
+
+
+@unittest.skipUnless(_DOMAIN, _SKIP_REASON)
+class TestOpenSandboxBackend(IsolatedAsyncioTestCase):
+    """Test cases for ``OpenSandboxBackend`` against a live sandbox.
+
+    Each test creates a real OpenSandbox sandbox via
+    ``OpenSandboxWorkspace`` and tears it down (``close`` → sandbox
+    pause) afterwards.
+    """
+
+    async def asyncSetUp(self) -> None:
+        """Start a workspace and reuse its wired backend."""
+        self.workspace = OpenSandboxWorkspace(
+            domain=_DOMAIN,
+            api_key=_API_KEY,
+        )
+        await self.workspace.initialize()
+        self.backend = self.workspace._backend
+        self.assertIsInstance(self.backend, OpenSandboxBackend)
+
+    async def asyncTearDown(self) -> None:
+        """Pause / close the sandbox."""
+        await self.workspace.close()
+
+    # ── exec ───────────────────────────────────────────────────────
+
+    async def test_exec_returns_stdout(self) -> None:
+        """A program's stdout/exit code are captured into ``ExecResult``."""
+        result = await self.backend.exec_shell(["echo", "hello world"])
+        self.assertIsInstance(result, ExecResult)
+        self.assertTrue(result.ok())
+        self.assertEqual(result.stdout.decode().strip(), "hello world")
+
+    async def test_exec_nonzero_exit(self) -> None:
+        """A non-zero command exit is reported as a normal result."""
+        result = await self.backend.exec_shell(
+            ["sh", "-c", "echo oops >&2; exit 4"],
+        )
+        self.assertEqual(result.exit_code, 4)
+        self.assertIn("oops", result.stderr.decode())
+
+    async def test_exec_argv_quoting_preserved(self) -> None:
+        """An argv element with spaces / metacharacters survives the
+        POSIX-quote round-trip the backend does for ``commands.run``."""
+        tricky = "a b c | ;"
+        result = await self.backend.exec_shell(["echo", tricky])
+        self.assertTrue(result.ok())
+        self.assertEqual(result.stdout.decode().rstrip("\n"), tricky)
+
+    async def test_exec_cwd_default_is_workdir(self) -> None:
+        """With no explicit ``cwd`` the sandbox workdir is used."""
+        result = await self.backend.exec_shell(["pwd"])
+        self.assertTrue(result.ok())
+        self.assertEqual(result.stdout.decode().strip(), SANDBOX_WORKDIR)
+
+    # ── file I/O ───────────────────────────────────────────────────
+
+    async def test_write_then_read_roundtrip(self) -> None:
+        """Bytes written into the sandbox are read back verbatim."""
+        path = f"{SANDBOX_WORKDIR}/roundtrip.txt"
+        payload = b"hello\nworld\n"
+        await self.backend.write_file(path, payload)
+        self.assertEqual(await self.backend.read_file(path), payload)
+
+    async def test_write_creates_parent_dirs(self) -> None:
+        """``write_file`` creates missing parent directories."""
+        path = f"{SANDBOX_WORKDIR}/a/b/c/file.txt"
+        await self.backend.write_file(path, b"x")
+        self.assertEqual(await self.backend.read_file(path), b"x")
+
+    async def test_read_missing_file_raises(self) -> None:
+        """Reading a non-existent file raises ``FileNotFoundError``."""
+        with self.assertRaises(FileNotFoundError):
+            await self.backend.read_file(f"{SANDBOX_WORKDIR}/nope.txt")
+
+    # ── derived filesystem helpers (shell-based) ───────────────────
+
+    async def test_file_exists_and_is_dir(self) -> None:
+        """``file_exists`` / ``is_dir`` reflect the sandbox filesystem."""
+        path = f"{SANDBOX_WORKDIR}/f.txt"
+        await self.backend.write_file(path, b"x")
+        self.assertTrue(await self.backend.file_exists(path))
+        self.assertTrue(await self.backend.is_dir(SANDBOX_WORKDIR))
+        self.assertFalse(await self.backend.is_dir(path))
+        self.assertFalse(
+            await self.backend.file_exists(f"{SANDBOX_WORKDIR}/missing"),
+        )
+
+    async def test_list_dir(self) -> None:
+        """Non-recursive ``list_dir`` returns immediate child base names."""
+        base = f"{SANDBOX_WORKDIR}/listing"
+        await self.backend.write_file(f"{base}/a.txt", b"x")
+        await self.backend.write_file(f"{base}/b.txt", b"x")
+        entries = await self.backend.list_dir(base)
+        self.assertEqual(sorted(entries), ["a.txt", "b.txt"])
+
+    async def test_stat_mtime(self) -> None:
+        """``stat_mtime`` returns a float for an existing path, None else."""
+        path = f"{SANDBOX_WORKDIR}/stat.txt"
+        await self.backend.write_file(path, b"x")
+        mtime = await self.backend.stat_mtime(path)
+        self.assertIsInstance(mtime, float)
+        self.assertIsNone(
+            await self.backend.stat_mtime(f"{SANDBOX_WORKDIR}/missing"),
+        )
+
+    async def test_delete_path(self) -> None:
+        """``delete_path`` removes files and trees; missing is a no-op."""
+        path = f"{SANDBOX_WORKDIR}/to_delete.txt"
+        await self.backend.write_file(path, b"x")
+        await self.backend.delete_path(path)
+        self.assertFalse(await self.backend.file_exists(path))
+
+        tree = f"{SANDBOX_WORKDIR}/tree"
+        await self.backend.write_file(f"{tree}/deep/f.txt", b"x")
+        await self.backend.delete_path(tree)
+        self.assertFalse(await self.backend.file_exists(tree))
+
+        # Deleting a non-existent path must not raise.
+        await self.backend.delete_path(f"{SANDBOX_WORKDIR}/missing")
diff --git a/tests/blob_store_s3_test.py b/tests/blob_store_s3_test.py
new file mode 100644
index 0000000..67a865f
--- /dev/null
+++ b/tests/blob_store_s3_test.py
@@ -0,0 +1,159 @@
+# -*- coding: utf-8 -*-
+"""Tests for :class:`S3BlobStore`.
+
+Uses ``moto.server.ThreadedMotoServer``: a real HTTP S3 endpoint
+served in-process on a thread. The aioboto3 client talks to it over
+TCP the way it would talk to AWS / MinIO / R2 — so the test
+exercises the real wire path (and the ``endpoint_url`` plumbing the
+production deployment will rely on for non-AWS services).
+
+We deliberately avoid ``moto.mock_aws()`` because that decorator
+patches ``botocore``'s endpoint layer, which does not play nicely
+with ``aiobotocore``: the patched response object is sync, but
+aiobotocore awaits ``http_response.content`` and gets a TypeError.
+The threaded server bypasses every monkey-patch path and gives us
+end-to-end coverage.
+
+Properties under test:
+
+- A blob written through ``write_stream`` reads back identical
+  bytes via ``open``.
+- The URI emitted is ``s3://{bucket}/{key}`` and round-trips
+  through ``exists`` / ``delete``.
+- ``exists`` distinguishes present from missing without raising.
+- ``delete`` is idempotent.
+- Bad URIs raise ``ValueError`` before any network call.
+- A store used outside ``async with`` raises ``RuntimeError`` —
+  callers MUST manage lifecycle via :class:`AsyncExitStack`.
+"""
+import io
+import os
+import socket
+from typing import TYPE_CHECKING
+from unittest import IsolatedAsyncioTestCase
+
+import boto3
+from moto.server import ThreadedMotoServer
+
+if TYPE_CHECKING:
+    from agentscope.app.rag.blob_store import S3BlobStore
+
+
+_BUCKET = "test-blobs"
+_REGION = "us-east-1"
+
+
+def _pick_port() -> int:
+    """Find an unused TCP port to bind moto on."""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+class S3BlobStoreTest(IsolatedAsyncioTestCase):
+    """Round-trip + URI parsing + streaming behaviour."""
+
+    def setUp(self) -> None:
+        # ThreadedMotoServer needs explicit credentials — without
+        # them aiobotocore looks for the AWS config chain and may
+        # fail on CI runners without credentials baked in.
+        self._env_overrides = {
+            "AWS_ACCESS_KEY_ID": "testing",
+            "AWS_SECRET_ACCESS_KEY": "testing",
+            "AWS_SECURITY_TOKEN": "testing",
+            "AWS_SESSION_TOKEN": "testing",
+            "AWS_DEFAULT_REGION": _REGION,
+        }
+        self._saved_env = {k: os.environ.get(k) for k in self._env_overrides}
+        for k, v in self._env_overrides.items():
+            os.environ[k] = v
+
+        port = _pick_port()
+        self._endpoint_url = f"http://127.0.0.1:{port}"
+        self._server = ThreadedMotoServer(ip_address="127.0.0.1", port=port)
+        self._server.start()
+
+        client = boto3.client(
+            "s3",
+            region_name=_REGION,
+            endpoint_url=self._endpoint_url,
+        )
+        client.create_bucket(Bucket=_BUCKET)
+
+    def tearDown(self) -> None:
+        self._server.stop()
+        for k, prev in self._saved_env.items():
+            if prev is None:
+                os.environ.pop(k, None)
+            else:
+                os.environ[k] = prev
+
+    def _store(self) -> "S3BlobStore":
+        """Build a fresh :class:`S3BlobStore` pointing at the moto endpoint.
+
+        Returns:
+            `S3BlobStore`:
+                The store under test, configured for the moto-backed
+                ``_BUCKET`` in ``_REGION``.
+        """
+        # Import inside the method so the skip decorator can fire
+        # without the import path running.
+        from agentscope.app.rag.blob_store import S3BlobStore
+
+        return S3BlobStore(
+            bucket=_BUCKET,
+            region_name=_REGION,
+            endpoint_url=self._endpoint_url,
+            use_ssl=False,
+        )
+
+    async def test_write_open_round_trip(self) -> None:
+        """A blob written through ``write_stream`` reads back the
+        same bytes via ``open`` and the URI is the documented
+        ``s3://{bucket}/{key}`` shape."""
+        async with self._store() as store:
+            payload = b"hello world\n" * 100  # ~1.2 KiB
+            uri = await store.write_stream(
+                "kb/abc/doc-1",
+                io.BytesIO(payload),
+            )
+            self.assertEqual(uri, "s3://test-blobs/kb/abc/doc-1")
+
+            received: list[bytes] = []
+            async with store.open(uri) as fp:
+                while True:
+                    chunk = await fp.read(64)
+                    if not chunk:
+                        break
+                    received.append(chunk)
+            self.assertEqual(b"".join(received), payload)
+
+    async def test_exists_and_delete(self) -> None:
+        """``exists`` flips from ``True`` to ``False`` after
+        ``delete``; ``delete`` is idempotent on a missing key."""
+        async with self._store() as store:
+            uri = await store.write_stream(
+                "kb/abc/doc-2",
+                io.BytesIO(b"data"),
+            )
+            self.assertTrue(await store.exists(uri))
+            await store.delete(uri)
+            self.assertFalse(await store.exists(uri))
+            # Second delete is a no-op.
+            await store.delete(uri)
+
+    async def test_bad_uri_scheme_rejected(self) -> None:
+        """Non-``s3://`` URIs are refused before any network call."""
+        async with self._store() as store:
+            with self.assertRaises(ValueError):
+                await store.exists("local://kb/abc/doc-3")
+            with self.assertRaises(ValueError):
+                await store.delete("s3://wrong-bucket/kb/abc/doc-4")
+
+    async def test_methods_require_aenter(self) -> None:
+        """Calling a blob method without entering the context fails
+        loudly — production code MUST manage the lifecycle through
+        ``async with`` / ``AsyncExitStack``."""
+        store = self._store()  # not entered
+        with self.assertRaises(RuntimeError):
+            await store.write_stream("kb/abc/doc-5", io.BytesIO(b""))
diff --git a/tests/builtin_bash_test.py b/tests/builtin_bash_test.py
new file mode 100644
index 0000000..d78bc09
--- /dev/null
+++ b/tests/builtin_bash_test.py
@@ -0,0 +1,528 @@
+# -*- coding: utf-8 -*-
+"""Bash tool test case."""
+
+import os
+import sys
+import unittest
+from unittest.async_case import IsolatedAsyncioTestCase
+from unittest.mock import AsyncMock, MagicMock, patch
+
+from agentscope.message import TextBlock
+from agentscope.permission import (
+    PermissionBehavior,
+    PermissionContext,
+    PermissionRule,
+)
+from agentscope.tool import Bash, ToolChunk
+from agentscope.tool._builtin._backend import (
+    _subprocess_creation_kwargs,
+)
+
+
+class BashSubprocessKwargsTest(unittest.TestCase):
+    """Test platform-specific subprocess kwargs."""
+
+    def test_non_windows_subprocess_kwargs_are_empty(self) -> None:
+        """On non-Windows the helper returns no extra subprocess kwargs."""
+        with patch(
+            "agentscope.tool._builtin._backend.os.name",
+            "posix",
+        ):
+            self.assertEqual(_subprocess_creation_kwargs(), {})
+
+    def test_windows_subprocess_kwargs_hide_console(self) -> None:
+        """On Windows the helper sets ``creationflags`` to hide the console."""
+        with patch("agentscope.tool._builtin._backend.os.name", "nt"):
+            self.assertEqual(
+                _subprocess_creation_kwargs(),
+                {"creationflags": 0x08000000},
+            )
+
+
+class BashCwdTest(IsolatedAsyncioTestCase):
+    """Test Bash working-directory wiring."""
+
+    async def test_cwd_is_passed_to_subprocess(self) -> None:
+        """The constructor-level cwd should be used for each command."""
+        process = MagicMock()
+        process.returncode = 0
+        process.communicate = AsyncMock(return_value=(b"ok\n", b""))
+
+        create_process = AsyncMock(return_value=process)
+        with patch(
+            "agentscope.tool._builtin._backend."
+            "asyncio.create_subprocess_exec",
+            create_process,
+        ):
+            chunks = []
+            async for chunk in await Bash(cwd="workspace")(command="pwd"):
+                chunks.append(chunk)
+
+        # cwd is forwarded, and the command line is wrapped in the
+        # platform's native shell (the backend primitive runs an argv
+        # without a shell): ``cmd /c`` on Windows, ``/bin/sh -c`` else.
+        self.assertEqual(create_process.call_args.kwargs["cwd"], "workspace")
+        expected_argv = (
+            ("cmd", "/c", "pwd")
+            if os.name == "nt"
+            else ("/bin/sh", "-c", "pwd")
+        )
+        self.assertEqual(
+            create_process.call_args.args,
+            expected_argv,
+        )
+        self.assertEqual(chunks[0].state, "running")
+
+
+@unittest.skipIf(
+    sys.platform == "win32",
+    "Bash tool is not supported on Windows",
+)
+class BashToolTest(IsolatedAsyncioTestCase):
+    """The bash tool test case."""
+
+    async def asyncSetUp(self) -> None:
+        """The async setup method."""
+        self.bash_tool = Bash()
+
+    async def test_tool_properties(self) -> None:
+        """Test bash tool properties."""
+        self.assertEqual(self.bash_tool.name, "Bash")
+        self.assertIsInstance(self.bash_tool.description, str)
+        self.assertIsInstance(self.bash_tool.input_schema, dict)
+        self.assertFalse(self.bash_tool.is_mcp)
+        self.assertFalse(self.bash_tool.is_read_only)
+        self.assertFalse(self.bash_tool.is_concurrency_safe)
+
+    async def test_check_permissions(self) -> None:
+        """Test bash tool permission checking."""
+
+        context = PermissionContext()
+        tool_input = {"command": "echo hello"}
+        decision = await self.bash_tool.check_permissions(tool_input, context)
+
+        self.assertEqual(decision.behavior, PermissionBehavior.ALLOW)
+
+    async def test_simple_command(self) -> None:
+        """Test executing a simple bash command."""
+        chunks = []
+        async for chunk in await self.bash_tool(command="echo 'Hello World'"):
+            chunks.append(chunk)
+
+        self.assertEqual(len(chunks), 1)
+        self.assertIsInstance(chunks[0], ToolChunk)
+        self.assertEqual(chunks[0].state, "running")
+        self.assertTrue(chunks[0].is_last)
+        self.assertEqual(len(chunks[0].content), 1)
+        self.assertIsInstance(chunks[0].content[0], TextBlock)
+        self.assertIn("Hello World", chunks[0].content[0].text)
+
+    async def test_command_with_error(self) -> None:
+        """Test executing a command that fails."""
+        chunks = []
+        async for chunk in await self.bash_tool(command="exit 1"):
+            chunks.append(chunk)
+
+        self.assertEqual(len(chunks), 1)
+        self.assertEqual(chunks[0].state, "error")
+        self.assertTrue(chunks[0].is_last)
+
+    @unittest.skipIf(
+        sys.platform == "win32",
+        "sleep command not available on Windows",
+    )
+    async def test_command_timeout(self) -> None:
+        """Test command timeout."""
+        chunks = []
+        async for chunk in await self.bash_tool(
+            command="sleep 10",
+            timeout=100,  # 100ms timeout
+        ):
+            chunks.append(chunk)
+
+        self.assertEqual(len(chunks), 1)
+        self.assertEqual(chunks[0].state, "error")
+        self.assertIn("timed out", chunks[0].content[0].text.lower())
+
+
+@unittest.skipIf(
+    sys.platform == "win32",
+    "Bash tool is not supported on Windows",
+)
+class BashToolInjectionCheckTest(IsolatedAsyncioTestCase):
+    """Test injection detection in Bash tool permission checks."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up test fixtures."""
+        self.bash_tool = Bash()
+        self.context = PermissionContext()
+
+    async def test_command_substitution_blocked(self) -> None:
+        """Test that command substitution is blocked."""
+        test_cases = [
+            "ls $(pwd)",
+            "rm $(find . -name '*.tmp')",
+            "cat `which python`",
+        ]
+        for cmd in test_cases:
+            with self.subTest(cmd=cmd):
+                decision = await self.bash_tool.check_permissions(
+                    {"command": cmd},
+                    self.context,
+                )
+                self.assertEqual(decision.behavior, PermissionBehavior.ASK)
+                self.assertIn("command_substitution", decision.message)
+
+    async def test_control_flow_blocked(self) -> None:
+        """Test that control flow structures are blocked."""
+
+        test_cases = [
+            "for f in *.txt; do cat $f; done",
+            "while read line; do echo $line; done < file.txt",
+            "if [ -f file.txt ]; then cat file.txt; fi",
+        ]
+        for cmd in test_cases:
+            with self.subTest(cmd=cmd):
+                decision = await self.bash_tool.check_permissions(
+                    {"command": cmd},
+                    self.context,
+                )
+                self.assertEqual(decision.behavior, PermissionBehavior.ASK)
+                self.assertIn(
+                    "cannot be statically analyzed",
+                    decision.message,
+                )
+
+    async def test_subshell_blocked(self) -> None:
+        """Test that subshells are blocked."""
+
+        cmd = "(cd /tmp && ls)"
+        decision = await self.bash_tool.check_permissions(
+            {"command": cmd},
+            self.context,
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.ASK)
+        self.assertIn("subshell", decision.message)
+
+    async def test_injection_check_before_readonly(self) -> None:
+        """Test that injection check runs before read-only check."""
+
+        # ls is read-only, but $(rm -rf /) is dangerous
+        cmd = "ls $(rm -rf /)"
+        decision = await self.bash_tool.check_permissions(
+            {"command": cmd},
+            self.context,
+        )
+        # Should be blocked by injection check, not allowed as read-only
+        self.assertEqual(decision.behavior, PermissionBehavior.ASK)
+        self.assertIn("command_substitution", decision.message)
+
+    async def test_safe_commands_pass(self) -> None:
+        """Test that safe commands pass injection check."""
+
+        safe_commands = [
+            "ls -la",
+            "cat file.txt",
+            "git status",
+            "echo 'hello world'",
+        ]
+        for cmd in safe_commands:
+            with self.subTest(cmd=cmd):
+                decision = await self.bash_tool.check_permissions(
+                    {"command": cmd},
+                    self.context,
+                )
+                # Should pass injection check (either ALLOW or PASSTHROUGH)
+                self.assertNotEqual(decision.behavior, PermissionBehavior.ASK)
+                if decision.behavior == PermissionBehavior.ASK:
+                    self.assertNotIn(
+                        "cannot be statically analyzed",
+                        decision.message,
+                    )
+
+    async def asyncTearDown(self) -> None:
+        """Clean up test fixtures."""
+        self.bash_tool = None
+        self.context = None
+
+
+@unittest.skipIf(
+    sys.platform == "win32",
+    "Bash tool is not supported on Windows",
+)
+class BashToolMatchRuleTest(IsolatedAsyncioTestCase):
+    """Test cases for Bash tool match_rule and generate_suggestions."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up test fixtures."""
+        self.bash_tool = Bash()
+
+    async def test_match_rule_prefix_pattern(self) -> None:
+        """Test match_rule with prefix patterns (e.g., git:*)."""
+        # Test exact command match
+        self.assertTrue(
+            await self.bash_tool.match_rule(
+                "git:*",
+                {"command": "git"},
+            ),
+        )
+
+        # Test command with arguments
+        self.assertTrue(
+            await self.bash_tool.match_rule(
+                "git:*",
+                {"command": "git status"},
+            ),
+        )
+
+        # Test non-matching command
+        self.assertFalse(
+            await self.bash_tool.match_rule(
+                "git:*",
+                {"command": "npm install"},
+            ),
+        )
+
+    async def test_match_rule_wildcard_pattern(self) -> None:
+        """Test match_rule with wildcard patterns."""
+        # Test wildcard matching
+        self.assertTrue(
+            await self.bash_tool.match_rule(
+                "git * -m *",
+                {"command": "git commit -m 'test'"},
+            ),
+        )
+
+        # Test non-matching wildcard
+        self.assertFalse(
+            await self.bash_tool.match_rule(
+                "git * -m *",
+                {"command": "git status"},
+            ),
+        )
+
+    async def test_match_rule_substring_pattern(self) -> None:
+        """Test match_rule with substring patterns."""
+        # Test substring matching
+        self.assertTrue(
+            await self.bash_tool.match_rule(
+                "install",
+                {"command": "npm install package"},
+            ),
+        )
+
+        # Test non-matching substring
+        self.assertFalse(
+            await self.bash_tool.match_rule(
+                "install",
+                {"command": "npm run build"},
+            ),
+        )
+
+    async def test_match_rule_escaped_characters(self) -> None:
+        """Test match_rule with escaped characters."""
+        # Test escaped asterisk
+        self.assertTrue(
+            await self.bash_tool.match_rule(
+                r"echo \*",
+                {"command": "echo *"},
+            ),
+        )
+
+        # Test escaped backslash
+        self.assertTrue(
+            await self.bash_tool.match_rule(
+                r"echo \\",
+                {"command": "echo \\"},
+            ),
+        )
+
+    async def test_generate_suggestions(self) -> None:
+        """Test generate_suggestions for bash commands."""
+
+        # Test two-word command
+        suggestions = await self.bash_tool.generate_suggestions(
+            {"command": "git commit -m 'test'"},
+        )
+
+        self.assertIsInstance(suggestions, list)
+        self.assertGreater(len(suggestions), 0)
+        self.assertIsInstance(suggestions[0], PermissionRule)
+
+        # Should suggest "git commit:*"
+        suggestion_contents = [s.rule_content for s in suggestions]
+        self.assertIn("git commit:*", suggestion_contents)
+
+    async def test_generate_suggestions_single_word(self) -> None:
+        """Test generate_suggestions for single-word commands."""
+        suggestions = await self.bash_tool.generate_suggestions(
+            {"command": "npm install"},
+        )
+
+        self.assertGreater(len(suggestions), 0)
+
+        # Should suggest "npm install:*"
+        suggestion_contents = [s.rule_content for s in suggestions]
+        self.assertIn("npm install:*", suggestion_contents)
+
+    async def asyncTearDown(self) -> None:
+        """Clean up test fixtures."""
+        self.bash_tool = None
+
+
+@unittest.skipIf(
+    sys.platform == "win32",
+    "Bash tool is not supported on Windows",
+)
+class BashToolDangerousRemovalTest(IsolatedAsyncioTestCase):
+    """Test dangerous removal path detection in Bash tool."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up test fixtures."""
+        self.bash_tool = Bash()
+        self.context = PermissionContext()
+
+    async def test_rm_root_blocked(self) -> None:
+        """Test that rm -rf / is blocked."""
+
+        cmd = "rm -rf /"
+        decision = await self.bash_tool.check_permissions(
+            {"command": cmd},
+            self.context,
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.ASK)
+        # Can be blocked by either dangerous command pattern or dangerous
+        # removal path check
+        self.assertTrue(
+            "Dangerous removal operation" in decision.message
+            or "dangerous pattern" in decision.message,
+        )
+
+    async def test_rm_root_children_blocked(self) -> None:
+        """Test that rm -rf /usr, /etc, etc. are blocked."""
+
+        test_cases = [
+            "rm -rf /usr",
+            "rm -rf /etc",
+            "rm -rf /tmp",
+            "rm -rf /var",
+            "rm -rf /bin",
+        ]
+        for cmd in test_cases:
+            with self.subTest(cmd=cmd):
+                decision = await self.bash_tool.check_permissions(
+                    {"command": cmd},
+                    self.context,
+                )
+                self.assertEqual(decision.behavior, PermissionBehavior.ASK)
+                # Can be blocked by either dangerous command pattern or
+                # dangerous removal path check
+                self.assertTrue(
+                    "Dangerous removal operation" in decision.message
+                    or "dangerous pattern" in decision.message,
+                )
+
+    async def test_rm_home_blocked(self) -> None:
+        """Test that rm -rf ~ is blocked."""
+
+        cmd = "rm -rf ~"
+        decision = await self.bash_tool.check_permissions(
+            {"command": cmd},
+            self.context,
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.ASK)
+        # Can be blocked by either dangerous command pattern or dangerous
+        # removal path check
+        self.assertTrue(
+            "Dangerous removal operation" in decision.message
+            or "dangerous pattern" in decision.message,
+        )
+
+    async def test_rm_wildcard_blocked(self) -> None:
+        """Test that rm -rf * and rm -rf /* are blocked."""
+
+        test_cases = [
+            "rm -rf *",
+            "rm -rf /*",
+            "rm -rf /tmp/*",
+        ]
+        for cmd in test_cases:
+            with self.subTest(cmd=cmd):
+                decision = await self.bash_tool.check_permissions(
+                    {"command": cmd},
+                    self.context,
+                )
+                self.assertEqual(decision.behavior, PermissionBehavior.ASK)
+                # Can be blocked by either dangerous command pattern or
+                # dangerous removal path check
+                self.assertTrue(
+                    "Dangerous removal operation" in decision.message
+                    or "dangerous pattern" in decision.message,
+                )
+
+    async def test_rmdir_dangerous_paths_blocked(self) -> None:
+        """Test that rmdir on dangerous paths is blocked."""
+
+        test_cases = [
+            "rmdir /",
+            "rmdir /usr",
+            "rmdir ~",
+        ]
+        for cmd in test_cases:
+            with self.subTest(cmd=cmd):
+                decision = await self.bash_tool.check_permissions(
+                    {"command": cmd},
+                    self.context,
+                )
+                self.assertEqual(decision.behavior, PermissionBehavior.ASK)
+                self.assertIn("Dangerous removal operation", decision.message)
+
+    async def test_safe_rm_commands_pass(self) -> None:
+        """Test that safe rm commands pass dangerous removal check."""
+
+        safe_commands = [
+            "rm file.txt",
+            "rm -f temp.log",
+            "rm -rf /tmp/my_project/build",
+            "rm -rf ./node_modules",
+        ]
+        for cmd in safe_commands:
+            with self.subTest(cmd=cmd):
+                decision = await self.bash_tool.check_permissions(
+                    {"command": cmd},
+                    self.context,
+                )
+                # Should not be blocked by dangerous removal check
+                # (may still be blocked by other checks)
+                if decision.behavior == PermissionBehavior.ASK:
+                    self.assertNotIn(
+                        "Dangerous removal operation",
+                        decision.message,
+                    )
+
+    async def test_compound_commands_with_dangerous_removal(self) -> None:
+        """Test compound commands containing dangerous removal."""
+
+        test_cases = [
+            "ls && rm -rf /",
+            "cd /tmp && rm -rf /usr",
+            "echo start; rm -rf ~; echo end",
+        ]
+        for cmd in test_cases:
+            with self.subTest(cmd=cmd):
+                decision = await self.bash_tool.check_permissions(
+                    {"command": cmd},
+                    self.context,
+                )
+                self.assertEqual(decision.behavior, PermissionBehavior.ASK)
+                # Can be blocked by either dangerous command pattern or
+                # dangerous removal path check
+                self.assertTrue(
+                    "Dangerous removal operation" in decision.message
+                    or "dangerous pattern" in decision.message,
+                )
+
+    async def asyncTearDown(self) -> None:
+        """Clean up test fixtures."""
+        self.bash_tool = None
+        self.context = None
diff --git a/tests/builtin_edit_test.py b/tests/builtin_edit_test.py
new file mode 100644
index 0000000..9d4bbec
--- /dev/null
+++ b/tests/builtin_edit_test.py
@@ -0,0 +1,182 @@
+# -*- coding: utf-8 -*-
+"""Edit tool test case."""
+import os
+import tempfile
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from agentscope.tool import Edit
+from agentscope.permission import (
+    PermissionContext,
+    PermissionBehavior,
+    PermissionRule,
+)
+
+
+class EditToolTest(IsolatedAsyncioTestCase):
+    """The edit tool test case."""
+
+    async def asyncSetUp(self) -> None:
+        """The async setup method."""
+        self.edit_tool = Edit()
+        # Create a temporary file for testing
+        self.temp_file = tempfile.NamedTemporaryFile(
+            mode="w",
+            delete=False,
+            suffix=".txt",
+        )
+        self.temp_file.write("Hello World\nThis is a test\n")
+        self.temp_file.close()
+
+    async def asyncTearDown(self) -> None:
+        """Clean up temporary files."""
+        if os.path.exists(self.temp_file.name):
+            os.unlink(self.temp_file.name)
+
+    async def test_tool_properties(self) -> None:
+        """Test edit tool properties."""
+        self.assertEqual(self.edit_tool.name, "Edit")
+        self.assertIsInstance(self.edit_tool.description, str)
+        self.assertIsInstance(self.edit_tool.input_schema, dict)
+        self.assertFalse(self.edit_tool.is_mcp)
+        self.assertFalse(self.edit_tool.is_read_only)
+        self.assertFalse(self.edit_tool.is_concurrency_safe)
+
+    async def test_check_permissions(self) -> None:
+        """Test edit tool permission checking.
+
+        Edit tool should return PASSTHROUGH for non-dangerous paths,
+        allowing PermissionEngine to check allow rules.
+        """
+        context = PermissionContext()
+        tool_input = {"file_path": "/tmp/test.txt"}
+        decision = await self.edit_tool.check_permissions(tool_input, context)
+
+        self.assertEqual(decision.behavior, PermissionBehavior.PASSTHROUGH)
+
+    async def test_simple_edit(self) -> None:
+        """Test simple file editing."""
+        chunk = await self.edit_tool(
+            file_path=self.temp_file.name,
+            old_string="Hello World",
+            new_string="Hello Python",
+        )
+
+        self.assertEqual(chunk.state, "running")
+        self.assertTrue(chunk.is_last)
+
+        # Verify file content
+        with open(self.temp_file.name, "r", encoding="utf-8") as f:
+            content = f.read()
+        self.assertIn("Hello Python", content)
+        self.assertNotIn("Hello World", content)
+
+    async def test_edit_not_found(self) -> None:
+        """Test editing with string not found."""
+        chunk = await self.edit_tool(
+            file_path=self.temp_file.name,
+            old_string="NonExistent",
+            new_string="Something",
+        )
+
+        self.assertEqual(chunk.state, "error")
+        self.assertIn("not found", chunk.content[0].text)
+
+    async def test_edit_multiple_occurrences(self) -> None:
+        """Test editing with multiple occurrences."""
+        # Write file with duplicate content
+        with open(self.temp_file.name, "w", encoding="utf-8") as f:
+            f.write("test\ntest\ntest\n")
+
+        chunk = await self.edit_tool(
+            file_path=self.temp_file.name,
+            old_string="test",
+            new_string="replaced",
+        )
+
+        # Should fail without replace_all
+        self.assertEqual(chunk.state, "error")
+
+    async def test_edit_replace_all(self) -> None:
+        """Test editing with replace_all flag."""
+        # Write file with duplicate content
+        with open(self.temp_file.name, "w", encoding="utf-8") as f:
+            f.write("test\ntest\ntest\n")
+
+        chunk = await self.edit_tool(
+            file_path=self.temp_file.name,
+            old_string="test",
+            new_string="replaced",
+            replace_all=True,
+        )
+
+        self.assertEqual(chunk.state, "running")
+
+        # Verify all occurrences replaced
+        with open(self.temp_file.name, "r", encoding="utf-8") as f:
+            content = f.read()
+        self.assertEqual(content.count("replaced"), 3)
+        self.assertEqual(content.count("test"), 0)
+
+    async def test_match_rule_glob_pattern(self) -> None:
+        """Test match_rule with glob patterns."""
+        # Test exact match
+        self.assertTrue(
+            await self.edit_tool.match_rule(
+                "test.py",
+                {"file_path": "test.py"},
+            ),
+        )
+
+        # Test wildcard pattern
+        self.assertTrue(
+            await self.edit_tool.match_rule(
+                "*.py",
+                {"file_path": "test.py"},
+            ),
+        )
+
+        # Test directory pattern
+        self.assertTrue(
+            await self.edit_tool.match_rule(
+                "/tmp/**",
+                {"file_path": "/tmp/test.py"},
+            ),
+        )
+
+        # Test non-matching pattern
+        self.assertFalse(
+            await self.edit_tool.match_rule(
+                "*.txt",
+                {"file_path": "test.py"},
+            ),
+        )
+
+        # Test empty file_path
+        self.assertFalse(
+            await self.edit_tool.match_rule(
+                "*.py",
+                {"file_path": ""},
+            ),
+        )
+
+    async def test_generate_suggestions(self) -> None:
+        """Test generate_suggestions for file operations."""
+
+        # Test suggestion for file in subdirectory
+        suggestions = await self.edit_tool.generate_suggestions(
+            {"file_path": "/tmp/project/src/main.py"},
+        )
+
+        self.assertIsInstance(suggestions, list)
+        self.assertGreater(len(suggestions), 0)
+        self.assertIsInstance(suggestions[0], PermissionRule)
+
+        # Should suggest parent directory pattern
+        suggestion_contents = [s.rule_content for s in suggestions]
+        self.assertIn("/tmp/project/src/**", suggestion_contents)
+
+        # Test suggestion for file in root
+        suggestions = await self.edit_tool.generate_suggestions(
+            {"file_path": "/test.py"},
+        )
+        self.assertGreater(len(suggestions), 0)
diff --git a/tests/builtin_file_cache_test.py b/tests/builtin_file_cache_test.py
new file mode 100644
index 0000000..9e77019
--- /dev/null
+++ b/tests/builtin_file_cache_test.py
@@ -0,0 +1,432 @@
+# -*- coding: utf-8 -*-
+"""File cache test case for Read/Write/Edit tools."""
+import os
+import tempfile
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from agentscope.state import AgentState
+from agentscope.tool import Read, Write, Edit
+
+
+class FileCacheTest(IsolatedAsyncioTestCase):
+    """Test file cache functionality for Read/Write/Edit tools."""
+
+    async def asyncSetUp(self) -> None:
+        """The async setup method."""
+        self.read_tool = Read()
+        self.write_tool = Write()
+        self.edit_tool = Edit()
+        self.state = AgentState()
+
+        # Create a temporary directory
+        self.temp_dir = tempfile.mkdtemp()
+        self.test_file = os.path.join(self.temp_dir, "test.txt")
+
+    async def asyncTearDown(self) -> None:
+        """Clean up temporary files."""
+        import shutil
+
+        if os.path.exists(self.temp_dir):
+            shutil.rmtree(self.temp_dir)
+
+    async def test_edit_without_read(self) -> None:
+        """Test Edit fails when file not read first."""
+        # Create a file
+        with open(self.test_file, "w", encoding="utf-8") as f:
+            f.write("Hello World\n")
+
+        # Try to edit without reading first
+        chunk = await self.edit_tool(
+            file_path=self.test_file,
+            old_string="Hello",
+            new_string="Hi",
+            _agent_state=self.state,
+        )
+
+        # Should fail with error
+        self.assertEqual(chunk.state, "error")
+        self.assertIn("must first read", chunk.content[0].text)
+
+    async def test_write_without_read(self) -> None:
+        """Test Write fails when existing file not read first."""
+        # Create a file
+        with open(self.test_file, "w", encoding="utf-8") as f:
+            f.write("Existing content\n")
+
+        # Try to write without reading first
+        chunk = await self.write_tool(
+            file_path=self.test_file,
+            content="New content\n",
+            _agent_state=self.state,
+        )
+
+        # Should fail with error
+        self.assertEqual(chunk.state, "error")
+        self.assertIn("has not been read yet", chunk.content[0].text)
+
+    async def test_write_new_file_without_read(self) -> None:
+        """Test Write succeeds for new file without reading."""
+        new_file = os.path.join(self.temp_dir, "new_file.txt")
+
+        # Write to a new file (doesn't exist yet)
+        chunk = await self.write_tool(
+            file_path=new_file,
+            content="New file content\n",
+            _agent_state=self.state,
+        )
+
+        # Should succeed
+        self.assertEqual(chunk.state, "running")
+        self.assertTrue(os.path.exists(new_file))
+
+        with open(new_file, "r", encoding="utf-8") as f:
+            content = f.read()
+        self.assertEqual(content, "New file content\n")
+
+    async def test_edit_after_read(self) -> None:
+        """Test Edit succeeds after reading file."""
+        # Create a file
+        with open(self.test_file, "w", encoding="utf-8") as f:
+            f.write("Hello World\n")
+
+        # Read the file first
+        read_chunk = await self.read_tool(
+            file_path=self.test_file,
+            _agent_state=self.state,
+        )
+        self.assertEqual(read_chunk.state, "running")
+
+        # Now edit should succeed
+        edit_chunk = await self.edit_tool(
+            file_path=self.test_file,
+            old_string="Hello",
+            new_string="Hi",
+            _agent_state=self.state,
+        )
+
+        self.assertEqual(edit_chunk.state, "running")
+
+        # Verify file was edited
+        with open(self.test_file, "r", encoding="utf-8") as f:
+            content = f.read()
+        self.assertEqual(content, "Hi World\n")
+
+    async def test_write_after_read(self) -> None:
+        """Test Write succeeds after reading file."""
+        # Create a file
+        with open(self.test_file, "w", encoding="utf-8") as f:
+            f.write("Old content\n")
+
+        # Read the file first
+        read_chunk = await self.read_tool(
+            file_path=self.test_file,
+            _agent_state=self.state,
+        )
+        self.assertEqual(read_chunk.state, "running")
+
+        # Now write should succeed
+        write_chunk = await self.write_tool(
+            file_path=self.test_file,
+            content="New content\n",
+            _agent_state=self.state,
+        )
+
+        self.assertEqual(write_chunk.state, "running")
+
+        # Verify file was overwritten
+        with open(self.test_file, "r", encoding="utf-8") as f:
+            content = f.read()
+        self.assertEqual(content, "New content\n")
+
+    async def test_cache_invalidation_after_file_deletion(self) -> None:
+        """Test cache handles file deletion gracefully."""
+        # Create a file
+        with open(self.test_file, "w", encoding="utf-8") as f:
+            f.write("Test content\n")
+
+        # Read the file to cache it
+        read_chunk = await self.read_tool(
+            file_path=self.test_file,
+            _agent_state=self.state,
+        )
+        self.assertEqual(read_chunk.state, "running")
+
+        # Verify cache exists
+        self.assertEqual(len(self.state.tool_context.read_file_cache), 1)
+        self.assertEqual(
+            self.state.tool_context.read_file_cache[0].file_path,
+            self.test_file,
+        )
+
+        # Delete the file
+        os.unlink(self.test_file)
+
+        # Try to edit - should fail with "File not found" error
+        edit_chunk = await self.edit_tool(
+            file_path=self.test_file,
+            old_string="Test",
+            new_string="New",
+            _agent_state=self.state,
+        )
+
+        # Should fail with "File not found" error
+        self.assertEqual(edit_chunk.state, "error")
+        self.assertIn("not found", edit_chunk.content[0].text.lower())
+
+        # Try to read again - should also fail
+        read_chunk2 = await self.read_tool(
+            file_path=self.test_file,
+            _agent_state=self.state,
+        )
+        self.assertEqual(read_chunk2.state, "error")
+        self.assertIn("does not exist", read_chunk2.content[0].text)
+
+    async def test_cache_invalidation_after_file_modification(self) -> None:
+        """Test cache detects file modification."""
+        # Create a file
+        with open(self.test_file, "w", encoding="utf-8") as f:
+            f.write("Original content\n")
+
+        # Read the file to cache it
+        read_chunk = await self.read_tool(
+            file_path=self.test_file,
+            _agent_state=self.state,
+        )
+        self.assertEqual(read_chunk.state, "running")
+
+        # Modify the file externally
+        import time
+
+        time.sleep(0.1)  # Ensure mtime changes
+        with open(self.test_file, "w", encoding="utf-8") as f:
+            f.write("Modified content\n")
+
+        # Try to edit - should fail because cache is stale
+        edit_chunk = await self.edit_tool(
+            file_path=self.test_file,
+            old_string="Original",
+            new_string="New",
+            _agent_state=self.state,
+        )
+
+        # Should fail with error
+        self.assertEqual(edit_chunk.state, "error")
+        self.assertIn("must first read", edit_chunk.content[0].text)
+
+    async def test_cache_lru_eviction(self) -> None:
+        """Test LRU cache eviction when max_cache_files is exceeded."""
+        # Set a small cache limit
+        self.state.tool_context.max_cache_files = 3
+
+        # Create and read 4 files
+        files = []
+        for i in range(4):
+            file_path = os.path.join(self.temp_dir, f"file{i}.txt")
+            with open(file_path, "w", encoding="utf-8") as f:
+                f.write(f"Content {i}\n")
+            files.append(file_path)
+
+            # Read each file
+            await self.read_tool(
+                file_path=file_path,
+                _agent_state=self.state,
+            )
+
+        # Cache should only have 3 files (oldest evicted)
+        self.assertEqual(len(self.state.tool_context.read_file_cache), 3)
+
+        # The first file should have been evicted
+        cached_paths = [
+            entry.file_path
+            for entry in self.state.tool_context.read_file_cache
+        ]
+        self.assertNotIn(files[0], cached_paths)
+        self.assertIn(files[1], cached_paths)
+        self.assertIn(files[2], cached_paths)
+        self.assertIn(files[3], cached_paths)
+
+    async def test_cache_without_state(self) -> None:
+        """Test tools work without state (fallback mode)."""
+        # Create a file
+        with open(self.test_file, "w", encoding="utf-8") as f:
+            f.write("Hello World\n")
+
+        # Edit without state should work (fallback to reading from disk)
+        edit_chunk = await self.edit_tool(
+            file_path=self.test_file,
+            old_string="Hello",
+            new_string="Hi",
+            _agent_state=None,
+        )
+
+        self.assertEqual(edit_chunk.state, "running")
+
+        # Verify file was edited
+        with open(self.test_file, "r", encoding="utf-8") as f:
+            content = f.read()
+        self.assertEqual(content, "Hi World\n")
+
+    async def test_multiple_reads_update_cache(self) -> None:
+        """Test reading same file multiple times updates cache."""
+        # Create a file
+        with open(self.test_file, "w", encoding="utf-8") as f:
+            f.write("Content v1\n")
+
+        # Read the file
+        await self.read_tool(
+            file_path=self.test_file,
+            _agent_state=self.state,
+        )
+        self.assertEqual(len(self.state.tool_context.read_file_cache), 1)
+
+        # Read again - should update cache, not add duplicate
+        await self.read_tool(
+            file_path=self.test_file,
+            _agent_state=self.state,
+        )
+        self.assertEqual(len(self.state.tool_context.read_file_cache), 1)
+
+    async def test_read_cache_lines_contain_newlines(self) -> None:
+        """Test that cached lines from Read retain trailing newlines.
+
+        readlines() includes the newline character in each line. The cache
+        must store them as-is so that "".join(lines) reconstructs the exact
+        original file content.
+        """
+        with open(self.test_file, "w", encoding="utf-8") as f:
+            f.write("line1\nline2\nline3\n")
+
+        await self.read_tool(
+            file_path=self.test_file,
+            _agent_state=self.state,
+        )
+
+        cache = await self.state.tool_context.get_cache(self.test_file)
+        self.assertIsNotNone(cache)
+        # Each line from readlines() ends with \n
+        self.assertEqual(cache.lines, ["line1\n", "line2\n", "line3\n"])
+        # "".join reconstructs the exact original content
+        self.assertEqual("".join(cache.lines), "line1\nline2\nline3\n")
+
+    async def test_edit_multiline_match_from_cache(self) -> None:
+        """Test Edit correctly matches multi-line old_string from
+        cached content.
+
+        Regression test for the bug where "\n".join(cache.lines) doubled the
+        newlines (e.g. "line1\n\nline2\n" instead of "line1\nline2\n"),
+        making multi-line old_string matching fail.
+        """
+        with open(self.test_file, "w", encoding="utf-8") as f:
+            f.write("line1\nline2\nline3\n")
+
+        await self.read_tool(
+            file_path=self.test_file,
+            _agent_state=self.state,
+        )
+
+        # This multi-line old_string must match exactly in the reconstructed
+        # content; with the bug it would not be found.
+        chunk = await self.edit_tool(
+            file_path=self.test_file,
+            old_string="line1\nline2",
+            new_string="replaced",
+            _agent_state=self.state,
+        )
+
+        self.assertEqual(chunk.state, "running")
+
+        with open(self.test_file, "r", encoding="utf-8") as f:
+            content = f.read()
+        self.assertEqual(content, "replaced\nline3\n")
+
+    async def test_edit_single_line_match_from_cache(self) -> None:
+        """Test Edit correctly matches single-line old_string from cache."""
+        with open(self.test_file, "w", encoding="utf-8") as f:
+            f.write("Hello World\nThis is a test\n")
+
+        await self.read_tool(
+            file_path=self.test_file,
+            _agent_state=self.state,
+        )
+
+        chunk = await self.edit_tool(
+            file_path=self.test_file,
+            old_string="Hello World",
+            new_string="Hello Python",
+            _agent_state=self.state,
+        )
+
+        self.assertEqual(chunk.state, "running")
+
+        with open(self.test_file, "r", encoding="utf-8") as f:
+            content = f.read()
+        self.assertEqual(content, "Hello Python\nThis is a test\n")
+
+    async def test_write_invalidates_cache(self) -> None:
+        """Test that Write updates the cache so Edit can use it afterwards."""
+        with open(self.test_file, "w", encoding="utf-8") as f:
+            f.write("original content\n")
+
+        # Read to populate cache
+        await self.read_tool(
+            file_path=self.test_file,
+            _agent_state=self.state,
+        )
+
+        # Overwrite with Write (mtime changes, old cache becomes stale)
+        write_chunk = await self.write_tool(
+            file_path=self.test_file,
+            content="new content\n",
+            _agent_state=self.state,
+        )
+        self.assertEqual(write_chunk.state, "running")
+
+        # The old cache entry is now stale; Edit should require a new Read
+        edit_chunk = await self.edit_tool(
+            file_path=self.test_file,
+            old_string="new content",
+            new_string="updated content",
+            _agent_state=self.state,
+        )
+        self.assertEqual(edit_chunk.state, "error")
+        self.assertIn("must first read", edit_chunk.content[0].text)
+
+    async def test_write_cache_stale_then_reread(self) -> None:
+        """Test workflow: Read -> Write -> Read -> Edit works correctly."""
+        with open(self.test_file, "w", encoding="utf-8") as f:
+            f.write("original\n")
+
+        # First read
+        await self.read_tool(
+            file_path=self.test_file,
+            _agent_state=self.state,
+        )
+
+        # Overwrite
+        import time
+
+        time.sleep(0.01)  # ensure mtime changes
+        await self.write_tool(
+            file_path=self.test_file,
+            content="rewritten\n",
+            _agent_state=self.state,
+        )
+
+        # Re-read to refresh cache
+        await self.read_tool(
+            file_path=self.test_file,
+            _agent_state=self.state,
+        )
+
+        # Now Edit should succeed against the new content
+        edit_chunk = await self.edit_tool(
+            file_path=self.test_file,
+            old_string="rewritten",
+            new_string="final",
+            _agent_state=self.state,
+        )
+        self.assertEqual(edit_chunk.state, "running")
+
+        with open(self.test_file, "r", encoding="utf-8") as f:
+            content = f.read()
+        self.assertEqual(content, "final\n")
diff --git a/tests/builtin_glob_test.py b/tests/builtin_glob_test.py
new file mode 100644
index 0000000..22d2c03
--- /dev/null
+++ b/tests/builtin_glob_test.py
@@ -0,0 +1,236 @@
+# -*- coding: utf-8 -*-
+"""Glob tool test case."""
+import os
+import tempfile
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from utils import AnyString
+from agentscope.tool import Glob
+from agentscope.permission import (
+    PermissionContext,
+    PermissionBehavior,
+    PermissionRule,
+)
+
+
+class GlobToolTest(IsolatedAsyncioTestCase):
+    """The glob tool test case."""
+
+    async def asyncSetUp(self) -> None:
+        """The async setup method."""
+        self.glob_tool = Glob()
+        # Create a temporary directory with test files
+        self.temp_dir = tempfile.mkdtemp()
+
+        # Create test files
+        with open(
+            os.path.join(self.temp_dir, "test1.py"),
+            "w",
+            encoding="utf-8",
+        ):
+            pass
+        with open(
+            os.path.join(self.temp_dir, "test2.py"),
+            "w",
+            encoding="utf-8",
+        ):
+            pass
+        with open(
+            os.path.join(self.temp_dir, "test.txt"),
+            "w",
+            encoding="utf-8",
+        ):
+            pass
+
+        # Create subdirectory
+        sub_dir = os.path.join(self.temp_dir, "subdir")
+        os.makedirs(sub_dir)
+        with open(os.path.join(sub_dir, "test3.py"), "w", encoding="utf-8"):
+            pass
+
+    async def asyncTearDown(self) -> None:
+        """Clean up temporary files."""
+        import shutil
+
+        if os.path.exists(self.temp_dir):
+            shutil.rmtree(self.temp_dir)
+
+    async def test_tool_properties(self) -> None:
+        """Test glob tool properties."""
+        self.assertEqual(self.glob_tool.name, "Glob")
+        self.assertIsInstance(self.glob_tool.description, str)
+        self.assertIsInstance(self.glob_tool.input_schema, dict)
+        self.assertFalse(self.glob_tool.is_mcp)
+        self.assertTrue(self.glob_tool.is_read_only)
+        self.assertTrue(self.glob_tool.is_concurrency_safe)
+
+    async def test_check_permissions(self) -> None:
+        """Test glob tool permission checking."""
+        context = PermissionContext()
+        tool_input = {"pattern": "*.py"}
+        decision = await self.glob_tool.check_permissions(tool_input, context)
+
+        # Read/Glob/Grep are read-only, return PASSTHROUGH
+        self.assertEqual(decision.behavior, PermissionBehavior.PASSTHROUGH)
+
+    async def test_simple_pattern(self) -> None:
+        """Test simple glob pattern."""
+        chunk = await self.glob_tool(
+            pattern="*.py",
+            path=self.temp_dir,
+        )
+
+        self.assertEqual(chunk.state, "running")
+
+        # Should find test1.py and test2.py
+        content = chunk.content[0].text
+        self.assertIn("test1.py", content)
+        self.assertIn("test2.py", content)
+        self.assertNotIn("test.txt", content)
+
+    async def test_recursive_pattern(self) -> None:
+        """Test recursive glob pattern."""
+        chunk = await self.glob_tool(
+            pattern="**/*.py",
+            path=self.temp_dir,
+        )
+
+        content = chunk.content[0].text
+
+        # Should find all .py files including in subdirectory
+        self.assertIn("test1.py", content)
+        self.assertIn("test2.py", content)
+        self.assertIn("test3.py", content)
+
+    async def test_windows_style_separator_pattern(self) -> None:
+        """Test glob patterns that use backslashes as path separators."""
+        chunk = await self.glob_tool(
+            pattern=r"subdir\*.py",
+            path=self.temp_dir,
+        )
+
+        self.assertDictEqual(
+            chunk.model_dump(),
+            {
+                "content": [
+                    {
+                        "type": "text",
+                        "text": os.path.join(
+                            self.temp_dir,
+                            "subdir",
+                            "test3.py",
+                        ),
+                        "id": AnyString(),
+                    },
+                ],
+                "state": "running",
+                "is_last": True,
+                "metadata": {},
+                "id": AnyString(),
+            },
+        )
+
+    async def test_no_matches(self) -> None:
+        """Test pattern with no matches."""
+        chunk = await self.glob_tool(
+            pattern="*.nonexistent",
+            path=self.temp_dir,
+        )
+
+        self.assertEqual(chunk.state, "running")
+        self.assertIn("No files found", chunk.content[0].text)
+
+    async def test_match_rule_path(self) -> None:
+        """Test match_rule with path patterns."""
+        # Test matching explicit path
+        self.assertTrue(
+            await self.glob_tool.match_rule(
+                self.temp_dir,
+                {"path": self.temp_dir, "pattern": "*.py"},
+            ),
+        )
+
+        # Test wildcard pattern matching path
+        parent_dir = os.path.dirname(self.temp_dir)
+        self.assertTrue(
+            await self.glob_tool.match_rule(
+                parent_dir + "/**",
+                {"path": self.temp_dir, "pattern": "*.py"},
+            ),
+        )
+
+        # Test non-matching path
+        self.assertFalse(
+            await self.glob_tool.match_rule(
+                "/some/other/path/**",
+                {"path": self.temp_dir, "pattern": "*.py"},
+            ),
+        )
+
+    async def test_match_rule_pattern(self) -> None:
+        """Test match_rule with pattern matching."""
+        # Test matching against the pattern itself
+        self.assertTrue(
+            await self.glob_tool.match_rule(
+                "*.py",
+                {"pattern": "*.py"},
+            ),
+        )
+
+        # Test wildcard pattern matching
+        self.assertTrue(
+            await self.glob_tool.match_rule(
+                "**/*.py",
+                {"pattern": "src/**/*.py"},
+            ),
+        )
+
+        # Test non-matching pattern
+        self.assertFalse(
+            await self.glob_tool.match_rule(
+                "*.txt",
+                {"pattern": "*.py"},
+            ),
+        )
+
+    async def test_match_rule_path_priority(self) -> None:
+        """Test that path matching takes priority over pattern matching."""
+        # If path matches, should return True even if pattern doesn't
+        self.assertTrue(
+            await self.glob_tool.match_rule(
+                self.temp_dir,
+                {"path": self.temp_dir, "pattern": "*.txt"},
+            ),
+        )
+
+    async def test_generate_suggestions_with_path(self) -> None:
+        """Test generate_suggestions for glob with explicit path."""
+
+        suggestions = await self.glob_tool.generate_suggestions(
+            {"path": self.temp_dir, "pattern": "*.py"},
+        )
+
+        self.assertIsInstance(suggestions, list)
+        self.assertGreater(len(suggestions), 0)
+        self.assertIsInstance(suggestions[0], PermissionRule)
+
+        # Should suggest directory pattern
+        abs_path = os.path.abspath(self.temp_dir)
+        expected_pattern = abs_path.rstrip("/") + "/**"
+        suggestion_contents = [s.rule_content for s in suggestions]
+        self.assertIn(expected_pattern, suggestion_contents)
+
+    async def test_generate_suggestions_defaults_to_cwd(self) -> None:
+        """Test generate_suggestions defaults to cwd when no path provided."""
+
+        suggestions = await self.glob_tool.generate_suggestions(
+            {"pattern": "*.py"},
+        )
+
+        self.assertIsInstance(suggestions, list)
+        self.assertGreater(len(suggestions), 0)
+
+        cwd = os.getcwd()
+        expected_pattern = os.path.abspath(cwd).rstrip("/") + "/**"
+        suggestion_contents = [s.rule_content for s in suggestions]
+        self.assertIn(expected_pattern, suggestion_contents)
diff --git a/tests/builtin_grep_test.py b/tests/builtin_grep_test.py
new file mode 100644
index 0000000..17593f1
--- /dev/null
+++ b/tests/builtin_grep_test.py
@@ -0,0 +1,254 @@
+# -*- coding: utf-8 -*-
+"""Grep tool test case."""
+import os
+import tempfile
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from agentscope.message import ToolResultState
+from agentscope.tool import Grep
+from agentscope.permission import (
+    PermissionContext,
+    PermissionBehavior,
+    PermissionRule,
+)
+
+
+class GrepToolTest(IsolatedAsyncioTestCase):
+    """The grep tool test case."""
+
+    async def asyncSetUp(self) -> None:
+        """The async setup method."""
+        self.grep_tool = Grep()
+        # Create a temporary directory with test files
+        self.temp_dir = tempfile.mkdtemp()
+
+        # Create test files
+        with open(
+            os.path.join(self.temp_dir, "test1.py"),
+            "w",
+            encoding="utf-8",
+        ) as f:
+            f.write("def hello():\n    print('Hello World')\n")
+
+        with open(
+            os.path.join(self.temp_dir, "test2.py"),
+            "w",
+            encoding="utf-8",
+        ) as f:
+            f.write("def goodbye():\n    print('Goodbye')\n")
+
+        with open(
+            os.path.join(self.temp_dir, "test.txt"),
+            "w",
+            encoding="utf-8",
+        ) as f:
+            f.write("This is a text file\nHello from text\n")
+
+        # Create subdirectory with files for glob pattern testing
+        subdir = os.path.join(self.temp_dir, "subdir")
+        os.makedirs(subdir)
+        with open(
+            os.path.join(subdir, "nested.py"),
+            "w",
+            encoding="utf-8",
+        ) as f:
+            f.write("def nested():\n    print('Nested')\n")
+
+    async def asyncTearDown(self) -> None:
+        """Clean up temporary files."""
+        import shutil
+
+        if os.path.exists(self.temp_dir):
+            shutil.rmtree(self.temp_dir)
+
+    async def test_tool_properties(self) -> None:
+        """Test grep tool properties."""
+        self.assertEqual(self.grep_tool.name, "Grep")
+        self.assertIsInstance(self.grep_tool.description, str)
+        self.assertIsInstance(self.grep_tool.input_schema, dict)
+        self.assertFalse(self.grep_tool.is_mcp)
+        self.assertTrue(self.grep_tool.is_read_only)
+        self.assertTrue(self.grep_tool.is_concurrency_safe)
+
+    async def test_check_permissions(self) -> None:
+        """Test grep tool permission checking."""
+        context = PermissionContext()
+        tool_input = {"pattern": "hello"}
+        decision = await self.grep_tool.check_permissions(tool_input, context)
+
+        # Read/Glob/Grep are read-only, return PASSTHROUGH
+        self.assertEqual(decision.behavior, PermissionBehavior.PASSTHROUGH)
+
+    async def test_simple_search(self) -> None:
+        """Test simple grep search."""
+        chunk = await self.grep_tool(
+            pattern="Hello",
+            path=self.temp_dir,
+            output_mode="files_with_matches",
+        )
+
+        self.assertEqual(chunk.state, ToolResultState.SUCCESS)
+
+        content = chunk.content[0].text
+        # Should find files containing "Hello"
+        self.assertIn("test1.py", content)
+        self.assertIn("test.txt", content)
+
+    async def test_content_mode(self) -> None:
+        """Test grep with content output mode."""
+        chunk = await self.grep_tool(
+            pattern="def",
+            path=self.temp_dir,
+            output_mode="content",
+            type="py",
+        )
+
+        content = chunk.content[0].text
+
+        # Should show matching lines
+        self.assertIn("def hello", content)
+        self.assertIn("def goodbye", content)
+
+    async def test_case_insensitive(self) -> None:
+        """Test case-insensitive search."""
+        chunk = await self.grep_tool(
+            pattern="HELLO",
+            path=self.temp_dir,
+            case_insensitive=True,
+            output_mode="files_with_matches",
+        )
+
+        content = chunk.content[0].text
+        self.assertIn("test1.py", content)
+
+    async def test_no_matches(self) -> None:
+        """Test search with no matches."""
+        chunk = await self.grep_tool(
+            pattern="NonExistentPattern",
+            path=self.temp_dir,
+        )
+
+        self.assertIn("No matches found", chunk.content[0].text)
+
+    async def test_type_filter(self) -> None:
+        """Test filtering by file type."""
+        chunk = await self.grep_tool(
+            pattern="Hello",
+            path=self.temp_dir,
+            type="py",
+            output_mode="files_with_matches",
+        )
+
+        content = chunk.content[0].text
+
+        # Should only find .py files
+        self.assertIn("test1.py", content)
+        self.assertNotIn("test.txt", content)
+
+    async def test_invalid_regex(self) -> None:
+        """Test grep with invalid regex pattern."""
+        chunk = await self.grep_tool(
+            pattern="[invalid(regex",
+            path=self.temp_dir,
+        )
+
+        self.assertEqual(chunk.state, "error")
+        # ripgrep returns its own error message for regex parse errors
+        self.assertIn("regex parse error", chunk.content[0].text)
+
+    async def test_glob_pattern_with_subdirs(self) -> None:
+        """Test glob pattern matching with subdirectories like **/*.py."""
+        chunk = await self.grep_tool(
+            pattern="def",
+            path=self.temp_dir,
+            glob="**/*.py",
+            output_mode="files_with_matches",
+        )
+
+        content = chunk.content[0].text
+
+        # Should find all .py files including in subdirectories
+        self.assertIn("test1.py", content)
+        self.assertIn("test2.py", content)
+        self.assertIn("nested.py", content)
+        # Should not find .txt files
+        self.assertNotIn("test.txt", content)
+
+    async def test_match_rule_path(self) -> None:
+        """Test match_rule with search path patterns."""
+        # Test matching explicit path
+        self.assertTrue(
+            await self.grep_tool.match_rule(
+                self.temp_dir,
+                {"path": self.temp_dir},
+            ),
+        )
+
+        # Test wildcard pattern matching path
+        parent_dir = os.path.dirname(self.temp_dir)
+        self.assertTrue(
+            await self.grep_tool.match_rule(
+                parent_dir + "/**",
+                {"path": self.temp_dir},
+            ),
+        )
+
+        # Test non-matching path
+        self.assertFalse(
+            await self.grep_tool.match_rule(
+                "/some/other/path/**",
+                {"path": self.temp_dir},
+            ),
+        )
+
+    async def test_match_rule_defaults_to_cwd(self) -> None:
+        """Test match_rule defaults to cwd when no path is provided."""
+        cwd = os.getcwd()
+
+        # When no path provided, should match against cwd
+        self.assertTrue(
+            await self.grep_tool.match_rule(
+                cwd,
+                {"pattern": "hello"},
+            ),
+        )
+
+        # Should not match a different path
+        self.assertFalse(
+            await self.grep_tool.match_rule(
+                "/some/other/path",
+                {"pattern": "hello"},
+            ),
+        )
+
+    async def test_generate_suggestions_with_path(self) -> None:
+        """Test generate_suggestions for grep with explicit path."""
+
+        suggestions = await self.grep_tool.generate_suggestions(
+            {"path": self.temp_dir, "pattern": "hello"},
+        )
+
+        self.assertIsInstance(suggestions, list)
+        self.assertGreater(len(suggestions), 0)
+        self.assertIsInstance(suggestions[0], PermissionRule)
+
+        # Should suggest directory pattern
+        abs_path = os.path.abspath(self.temp_dir)
+        expected_pattern = abs_path.rstrip("/") + "/**"
+        suggestion_contents = [s.rule_content for s in suggestions]
+        self.assertIn(expected_pattern, suggestion_contents)
+
+    async def test_generate_suggestions_defaults_to_cwd(self) -> None:
+        """Test generate_suggestions defaults to cwd when no path provided."""
+
+        suggestions = await self.grep_tool.generate_suggestions(
+            {"pattern": "hello"},
+        )
+
+        self.assertIsInstance(suggestions, list)
+        self.assertGreater(len(suggestions), 0)
+
+        cwd = os.getcwd()
+        expected_pattern = os.path.abspath(cwd).rstrip("/") + "/**"
+        suggestion_contents = [s.rule_content for s in suggestions]
+        self.assertIn(expected_pattern, suggestion_contents)
diff --git a/tests/builtin_read_test.py b/tests/builtin_read_test.py
new file mode 100644
index 0000000..ad82659
--- /dev/null
+++ b/tests/builtin_read_test.py
@@ -0,0 +1,188 @@
+# -*- coding: utf-8 -*-
+"""Read tool test case."""
+import os
+import tempfile
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from agentscope.tool import ToolChunk, Read
+from agentscope.permission import (
+    PermissionContext,
+    PermissionBehavior,
+    PermissionRule,
+)
+from agentscope.message import TextBlock
+
+
+class ReadToolTest(IsolatedAsyncioTestCase):
+    """The read tool test case."""
+
+    async def asyncSetUp(self) -> None:
+        """The async setup method."""
+        self.read_tool = Read()
+        # Create a temporary file for testing
+        self.temp_file = tempfile.NamedTemporaryFile(
+            mode="w",
+            delete=False,
+            suffix=".txt",
+        )
+        # Write multiple lines
+        for i in range(1, 11):
+            self.temp_file.write(f"Line {i}\n")
+        self.temp_file.close()
+
+    async def asyncTearDown(self) -> None:
+        """Clean up temporary files."""
+        if os.path.exists(self.temp_file.name):
+            os.unlink(self.temp_file.name)
+
+    async def test_tool_properties(self) -> None:
+        """Test read tool properties."""
+        self.assertEqual(self.read_tool.name, "Read")
+        self.assertIsInstance(self.read_tool.description, str)
+        self.assertIsInstance(self.read_tool.input_schema, dict)
+        self.assertFalse(self.read_tool.is_mcp)
+        self.assertTrue(self.read_tool.is_read_only)
+        self.assertTrue(self.read_tool.is_concurrency_safe)
+
+    async def test_check_permissions(self) -> None:
+        """Test read tool permission checking."""
+        context = PermissionContext()
+        tool_input = {"file_path": "/tmp/test.txt"}
+        decision = await self.read_tool.check_permissions(tool_input, context)
+
+        # Read/Glob/Grep are read-only, return PASSTHROUGH
+        self.assertEqual(decision.behavior, PermissionBehavior.PASSTHROUGH)
+
+    async def test_simple_read(self) -> None:
+        """Test simple file reading."""
+        chunk = await self.read_tool(file_path=self.temp_file.name)
+
+        self.assertIsInstance(chunk, ToolChunk)
+        self.assertEqual(chunk.state, "running")
+        self.assertEqual(len(chunk.content), 1)
+        self.assertIsInstance(chunk.content[0], TextBlock)
+
+        content = chunk.content[0].text
+        # Should contain all lines with line numbers
+        self.assertIn("Line 1", content)
+        self.assertIn("Line 10", content)
+
+    async def test_read_with_offset(self) -> None:
+        """Test reading with offset."""
+        chunk = await self.read_tool(
+            file_path=self.temp_file.name,
+            offset=5,
+        )
+
+        self.assertEqual(chunk.state, "running")
+        content = chunk.content[0].text
+
+        # Should start from line 5
+        self.assertIn("Line 5", content)
+        # Line 1 should not appear (but Line 10 contains "1",
+        # so check more specifically)
+        lines = content.split("\n")
+        line_numbers = [
+            int(line.split("\t")[0].strip()) for line in lines if line.strip()
+        ]
+        self.assertNotIn(1, line_numbers)
+        self.assertIn(5, line_numbers)
+
+    async def test_read_with_limit(self) -> None:
+        """Test reading with limit."""
+        chunk = await self.read_tool(
+            file_path=self.temp_file.name,
+            offset=1,
+            limit=3,
+        )
+
+        self.assertEqual(chunk.state, "running")
+        content = chunk.content[0].text
+
+        # Should only read 3 lines
+        self.assertIn("Line 1", content)
+        self.assertIn("Line 2", content)
+        self.assertIn("Line 3", content)
+        self.assertNotIn("Line 4", content)
+
+    async def test_read_nonexistent_file(self) -> None:
+        """Test reading a non-existent file."""
+        chunk = await self.read_tool(file_path="/nonexistent/file.txt")
+
+        self.assertEqual(chunk.state, "error")
+        self.assertIn("does not exist", chunk.content[0].text)
+
+    async def test_read_directory(self) -> None:
+        """Test reading a directory (should fail)."""
+        temp_dir = tempfile.mkdtemp()
+        try:
+            chunk = await self.read_tool(file_path=temp_dir)
+
+            self.assertEqual(chunk.state, "error")
+            self.assertIn("directory", chunk.content[0].text.lower())
+        finally:
+            os.rmdir(temp_dir)
+
+    async def test_match_rule_glob_pattern(self) -> None:
+        """Test match_rule with glob patterns."""
+        # Test exact match
+        self.assertTrue(
+            await self.read_tool.match_rule(
+                "test.py",
+                {"file_path": "test.py"},
+            ),
+        )
+
+        # Test wildcard pattern
+        self.assertTrue(
+            await self.read_tool.match_rule(
+                "*.py",
+                {"file_path": "test.py"},
+            ),
+        )
+
+        # Test directory pattern
+        self.assertTrue(
+            await self.read_tool.match_rule(
+                "/tmp/**",
+                {"file_path": "/tmp/test.py"},
+            ),
+        )
+
+        # Test non-matching pattern
+        self.assertFalse(
+            await self.read_tool.match_rule(
+                "*.txt",
+                {"file_path": "test.py"},
+            ),
+        )
+
+        # Test empty file_path
+        self.assertFalse(
+            await self.read_tool.match_rule(
+                "*.py",
+                {"file_path": ""},
+            ),
+        )
+
+    async def test_generate_suggestions(self) -> None:
+        """Test generate_suggestions for file operations."""
+
+        # Test suggestion for file in subdirectory
+        suggestions = await self.read_tool.generate_suggestions(
+            {"file_path": "/tmp/project/src/main.py"},
+        )
+
+        self.assertIsInstance(suggestions, list)
+        self.assertGreater(len(suggestions), 0)
+        self.assertIsInstance(suggestions[0], PermissionRule)
+
+        # Should suggest parent directory pattern
+        suggestion_contents = [s.rule_content for s in suggestions]
+        self.assertIn("/tmp/project/src/**", suggestion_contents)
+
+        # Test suggestion for file in root
+        suggestions = await self.read_tool.generate_suggestions(
+            {"file_path": "/test.py"},
+        )
+        self.assertGreater(len(suggestions), 0)
diff --git a/tests/builtin_write_test.py b/tests/builtin_write_test.py
new file mode 100644
index 0000000..29b7744
--- /dev/null
+++ b/tests/builtin_write_test.py
@@ -0,0 +1,212 @@
+# -*- coding: utf-8 -*-
+"""Write tool test case."""
+import os
+import tempfile
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from agentscope.tool import Write
+from agentscope.permission import (
+    PermissionContext,
+    PermissionBehavior,
+    PermissionRule,
+)
+from agentscope.state import AgentState
+from agentscope.message import ToolResultState
+
+
+class WriteToolTest(IsolatedAsyncioTestCase):
+    """The write tool test case."""
+
+    async def asyncSetUp(self) -> None:
+        """The async setup method."""
+        self.write_tool = Write()
+        self.temp_dir = tempfile.mkdtemp()
+
+    async def asyncTearDown(self) -> None:
+        """Clean up temporary files."""
+        import shutil
+
+        if os.path.exists(self.temp_dir):
+            shutil.rmtree(self.temp_dir)
+
+    async def test_tool_properties(self) -> None:
+        """Test write tool properties."""
+        self.assertEqual(self.write_tool.name, "Write")
+        self.assertIsInstance(self.write_tool.description, str)
+        self.assertIsInstance(self.write_tool.input_schema, dict)
+        self.assertFalse(self.write_tool.is_mcp)
+        self.assertFalse(self.write_tool.is_read_only)
+        self.assertFalse(self.write_tool.is_concurrency_safe)
+
+    async def test_check_permissions(self) -> None:
+        """Test write tool permission checking.
+
+        Write tool should return PASSTHROUGH for non-dangerous paths,
+        allowing PermissionEngine to check allow rules.
+        """
+        context = PermissionContext()
+        tool_input = {"file_path": "/tmp/test.txt"}
+        decision = await self.write_tool.check_permissions(tool_input, context)
+
+        self.assertEqual(decision.behavior, PermissionBehavior.PASSTHROUGH)
+
+    async def test_simple_write(self) -> None:
+        """Test simple file writing."""
+        file_path = os.path.join(self.temp_dir, "test.txt")
+        content = "Hello World\nThis is a test\n"
+
+        chunk = await self.write_tool(
+            file_path=file_path,
+            content=content,
+        )
+
+        self.assertEqual(chunk.state, "running")
+        self.assertTrue(chunk.is_last)
+
+        # Verify file was created and content is correct
+        self.assertTrue(os.path.exists(file_path))
+        with open(file_path, "r", encoding="utf-8") as f:
+            written_content = f.read()
+        self.assertEqual(written_content, content)
+
+    async def test_write_creates_directory(self) -> None:
+        """Test that write creates parent directories."""
+        file_path = os.path.join(self.temp_dir, "subdir", "test.txt")
+        content = "Test content"
+
+        chunk = await self.write_tool(
+            file_path=file_path,
+            content=content,
+        )
+
+        self.assertEqual(chunk.state, "running")
+
+        # Verify directory and file were created
+        self.assertTrue(os.path.exists(file_path))
+        with open(file_path, "r", encoding="utf-8") as f:
+            written_content = f.read()
+        self.assertEqual(written_content, content)
+
+    async def test_write_overwrites_existing(self) -> None:
+        """Test that write overwrites existing files."""
+        file_path = os.path.join(self.temp_dir, "test.txt")
+
+        # Write initial content
+        with open(file_path, "w", encoding="utf-8") as f:
+            f.write("Initial content")
+
+        # Overwrite with new content
+        new_content = "New content"
+        chunk = await self.write_tool(
+            file_path=file_path,
+            content=new_content,
+        )
+
+        self.assertEqual(len([chunk]), 1)
+
+        # Verify content was overwritten
+        with open(file_path, "r", encoding="utf-8") as f:
+            written_content = f.read()
+        self.assertEqual(written_content, new_content)
+        self.assertNotIn("Initial", written_content)
+
+    async def test_write_empty_content(self) -> None:
+        """Test writing empty content."""
+        file_path = os.path.join(self.temp_dir, "empty.txt")
+
+        chunk = await self.write_tool(
+            file_path=file_path,
+            content="",
+        )
+
+        self.assertEqual(len([chunk]), 1)
+        self.assertTrue(os.path.exists(file_path))
+
+        with open(file_path, "r", encoding="utf-8") as f:
+            content = f.read()
+        self.assertEqual(content, "")
+
+    async def test_overwrite_existing_without_prior_read_errors(self) -> None:
+        """Overwriting an existing file via state-injected call requires
+        the file to have been read first (cached in tool_context).
+        """
+        file_path = os.path.join(self.temp_dir, "existing.txt")
+        with open(file_path, "w", encoding="utf-8") as f:
+            f.write("original")
+
+        state = AgentState()
+        chunk = await self.write_tool(
+            file_path=file_path,
+            content="new",
+            _agent_state=state,
+        )
+
+        self.assertEqual(chunk.state, ToolResultState.ERROR)
+        self.assertIn("has not been read", chunk.content[0].text)
+        # File must not have been mutated
+        with open(file_path, "r", encoding="utf-8") as f:
+            self.assertEqual(f.read(), "original")
+
+    async def test_match_rule_glob_pattern(self) -> None:
+        """Test match_rule with glob patterns."""
+        # Test exact match
+        self.assertTrue(
+            await self.write_tool.match_rule(
+                "test.py",
+                {"file_path": "test.py"},
+            ),
+        )
+
+        # Test wildcard pattern
+        self.assertTrue(
+            await self.write_tool.match_rule(
+                "*.py",
+                {"file_path": "test.py"},
+            ),
+        )
+
+        # Test directory pattern
+        self.assertTrue(
+            await self.write_tool.match_rule(
+                "/tmp/**",
+                {"file_path": "/tmp/test.py"},
+            ),
+        )
+
+        # Test non-matching pattern
+        self.assertFalse(
+            await self.write_tool.match_rule(
+                "*.txt",
+                {"file_path": "test.py"},
+            ),
+        )
+
+        # Test empty file_path
+        self.assertFalse(
+            await self.write_tool.match_rule(
+                "*.py",
+                {"file_path": ""},
+            ),
+        )
+
+    async def test_generate_suggestions(self) -> None:
+        """Test generate_suggestions for file operations."""
+
+        # Test suggestion for file in subdirectory
+        suggestions = await self.write_tool.generate_suggestions(
+            {"file_path": "/tmp/project/src/main.py"},
+        )
+
+        self.assertIsInstance(suggestions, list)
+        self.assertGreater(len(suggestions), 0)
+        self.assertIsInstance(suggestions[0], PermissionRule)
+
+        # Should suggest parent directory pattern
+        suggestion_contents = [s.rule_content for s in suggestions]
+        self.assertIn("/tmp/project/src/**", suggestion_contents)
+
+        # Test suggestion for file in root
+        suggestions = await self.write_tool.generate_suggestions(
+            {"file_path": "/test.py"},
+        )
+        self.assertGreater(len(suggestions), 0)
diff --git a/tests/compress_context_test.py b/tests/compress_context_test.py
new file mode 100644
index 0000000..e589a2e
--- /dev/null
+++ b/tests/compress_context_test.py
@@ -0,0 +1,1083 @@
+# -*- coding: utf-8 -*-
+"""A template test case."""
+# pylint: disable=protected-access
+import json
+import os
+import tempfile
+from typing import Any
+
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from utils import MockModel, AnyString
+
+from agentscope.model import StructuredResponse
+from agentscope.agent import Agent, ContextConfig
+from agentscope.state import AgentState
+from agentscope.message import (
+    UserMsg,
+    AssistantMsg,
+    TextBlock,
+    ToolCallBlock,
+    HintBlock,
+    Msg,
+)
+from agentscope.tool import Toolkit
+
+
+class RecordingStructuredMockModel(MockModel):
+    """A mock model that records structured-output compression calls."""
+
+    def __init__(
+        self,
+        *args: Any,
+        fail_structured_output_times: int = 0,
+        force_compression_overflow: bool = False,
+        **kwargs: Any,
+    ) -> None:
+        """Initialize the recording mock model."""
+        super().__init__(*args, **kwargs)
+        self.recorded_structured_messages: list[list[Msg]] = []
+        self._fail_structured_output_times = fail_structured_output_times
+        self._force_compression_overflow = force_compression_overflow
+        self._compression_count_calls = 0
+
+    async def count_tokens(
+        self,
+        messages: list[Msg],
+        tools: list[dict] | None,
+    ) -> int:
+        """Force the overflow branch when counting compression messages."""
+        is_compression_count = bool(
+            tools
+            and tools[0].get("function", {}).get("name")
+            == "generate_structured_output",
+        )
+        if self._force_compression_overflow and is_compression_count:
+            self._compression_count_calls += 1
+            if self._compression_count_calls == 1:
+                return self.context_size + 1
+            return 1
+        return await super().count_tokens(messages, tools)
+
+    async def _call_api_with_structured_output(
+        self,
+        model_name: str,
+        messages: list[Msg],
+        structured_model: Any,
+        **kwargs: Any,
+    ) -> StructuredResponse:
+        """Record the structured-output call and optionally fail first."""
+        self.recorded_structured_messages.append(list(messages))
+        if self._fail_structured_output_times > 0:
+            self._fail_structured_output_times -= 1
+            raise RuntimeError("simulated compression overflow")
+        return await super()._call_api_with_structured_output(
+            model_name,
+            messages,
+            structured_model,
+            **kwargs,
+        )
+
+
+def _has_instruction_hint(
+    messages: list[Msg],
+    instructions: HintBlock,
+) -> bool:
+    """Return True if messages contain instructions as an assistant hint."""
+    for msg in messages:
+        if msg.role != "assistant":
+            continue
+        for hint_block in msg.get_content_blocks("hint"):
+            if hint_block.id == instructions.id:
+                return hint_block.hint == instructions.hint
+    return False
+
+
+class ContextCompressionTest(IsolatedAsyncioTestCase):
+    """The template test case."""
+
+    async def asyncSetUp(self) -> None:
+        """The async setup method."""
+
+    async def test_split_function(self) -> None:
+        """The template test."""
+        agent = Agent(
+            name="Friday",
+            system_prompt="".join(["0" for _ in range(60 * 4)]),
+            model=MockModel(),
+            context_config=ContextConfig(
+                trigger_ratio=0.8,
+                reserve_ratio=0.1,
+            ),
+            state=AgentState(
+                session_id="123",
+                context=[
+                    UserMsg(
+                        "User",
+                        "".join(["1" for _ in range(30 * 4)]),
+                        id="1",
+                    ),
+                    AssistantMsg(
+                        "Friday",
+                        "".join(["2" for _ in range(10 * 4)]),
+                        id="2",
+                    ),
+                    UserMsg(
+                        "User",
+                        "".join(["3" for _ in range(10 * 4)]),
+                        id="3",
+                    ),
+                ],
+            ),
+            toolkit=Toolkit(),
+        )
+
+        # When the length of last two messages is exactly appropriate
+        to_compress, to_reserve = await agent._split_context_for_compression(
+            to_reserved_tokens=80,
+            tools=[],
+        )
+
+        self.assertListEqual(
+            [_.id for _ in to_compress],
+            ["1"],
+        )
+        self.assertListEqual(
+            [_.id for _ in to_reserve],
+            ["2", "3"],
+        )
+
+        # When one message is in the dividing line
+        agent.state.context = [
+            UserMsg("User", "".join(["2" for _ in range(30 * 4)]), id="1"),
+            AssistantMsg(
+                "Friday",
+                "".join(["3" for _ in range(15 * 4)]),
+                id="2",
+            ),
+            UserMsg("User", "".join(["3" for _ in range(10 * 4)]), id="3"),
+        ]
+
+        to_compress, to_reserve = await agent._split_context_for_compression(
+            to_reserved_tokens=80,
+            tools=[],
+        )
+        self.assertListEqual(
+            [_.id for _ in to_compress],
+            ["1", "2"],
+        )
+        self.assertListEqual(
+            [_.id for _ in to_reserve],
+            ["3"],
+        )
+
+        # When compress all messages
+        agent.state.context = [
+            UserMsg("User", "".join(["2" for _ in range(30 * 4)]), id="1"),
+            AssistantMsg(
+                "Friday",
+                "".join(["3" for _ in range(15 * 4)]),
+                id="2",
+            ),
+            UserMsg("User", "".join(["3" for _ in range(30 * 4)]), id="3"),
+        ]
+        to_compress, to_reserve = await agent._split_context_for_compression(
+            to_reserved_tokens=80,
+            tools=[],
+        )
+        self.assertListEqual(
+            [_.id for _ in to_compress],
+            ["1", "2", "3"],
+        )
+        self.assertListEqual(
+            [_.id for _ in to_reserve],
+            [],
+        )
+
+        # When the boundary message has multiple blocks
+        agent.state.context = [
+            UserMsg("User", "".join(["a" for _ in range(30 * 4)]), id="1"),
+            AssistantMsg(
+                "Friday",
+                [
+                    TextBlock(
+                        text="".join(["b" for _ in range(10 * 4)]),
+                        id="b",
+                    ),
+                    TextBlock(
+                        text="".join(["c" for _ in range(10 * 4)]),
+                        id="c",
+                    ),
+                ],
+                id="2",
+            ),
+            UserMsg("User", "".join(["d" for _ in range(10 * 4)]), id="3"),
+        ]
+        to_compress, to_reserve = await agent._split_context_for_compression(
+            to_reserved_tokens=80,
+            tools=[],
+        )
+        self.assertListEqual(
+            [_.model_dump() for _ in to_compress],
+            [
+                {
+                    "id": "1",
+                    "created_at": AnyString(),
+                    "finished_at": AnyString(),
+                    "name": "User",
+                    "role": "user",
+                    "content": [
+                        {
+                            "id": AnyString(),
+                            "type": "text",
+                            "text": "a" * 120,
+                        },
+                    ],
+                    "metadata": {},
+                    "usage": None,
+                },
+                {
+                    "id": "2",
+                    "created_at": AnyString(),
+                    "finished_at": None,
+                    "name": "Friday",
+                    "role": "assistant",
+                    "content": [
+                        {
+                            "id": "b",
+                            "text": "b" * 40,
+                            "type": "text",
+                        },
+                    ],
+                    "metadata": {},
+                    "usage": None,
+                },
+            ],
+        )
+        self.assertListEqual(
+            [_.model_dump() for _ in to_reserve],
+            [
+                {
+                    "id": "2",
+                    "created_at": AnyString(),
+                    "finished_at": None,
+                    "name": "Friday",
+                    "role": "assistant",
+                    "content": [
+                        {
+                            "id": AnyString(),
+                            "text": "c" * 40,
+                            "type": "text",
+                        },
+                    ],
+                    "metadata": {},
+                    "usage": None,
+                },
+                {
+                    "id": "3",
+                    "created_at": AnyString(),
+                    "finished_at": AnyString(),
+                    "name": "User",
+                    "role": "user",
+                    "content": [
+                        {
+                            "id": AnyString(),
+                            "type": "text",
+                            "text": "d" * 40,
+                        },
+                    ],
+                    "metadata": {},
+                    "usage": None,
+                },
+            ],
+        )
+
+        # When the boundary message has multiple blocks
+        # Cannot leave any blocks
+        agent.state.context = [
+            UserMsg("User", "".join(["a" for _ in range(30 * 4)]), id="1"),
+            AssistantMsg(
+                "Friday",
+                [
+                    TextBlock(
+                        text="".join(["b" for _ in range(10 * 4)]),
+                        id="b",
+                    ),
+                    TextBlock(
+                        text="".join(["c" for _ in range(15 * 4)]),
+                        id="c",
+                    ),
+                ],
+                id="2",
+            ),
+            UserMsg("User", "".join(["d" for _ in range(10 * 4)]), id="3"),
+        ]
+        to_compress, to_reserve = await agent._split_context_for_compression(
+            to_reserved_tokens=80,
+            tools=[],
+        )
+        self.assertListEqual(
+            [_.model_dump() for _ in to_compress],
+            [
+                {
+                    "id": "1",
+                    "created_at": AnyString(),
+                    "finished_at": AnyString(),
+                    "name": "User",
+                    "role": "user",
+                    "content": [
+                        {
+                            "id": AnyString(),
+                            "type": "text",
+                            "text": "a" * 120,
+                        },
+                    ],
+                    "metadata": {},
+                    "usage": None,
+                },
+                {
+                    "id": "2",
+                    "created_at": AnyString(),
+                    "finished_at": None,
+                    "name": "Friday",
+                    "role": "assistant",
+                    "content": [
+                        {
+                            "id": "b",
+                            "text": "b" * 40,
+                            "type": "text",
+                        },
+                        {
+                            "id": "c",
+                            "text": "c" * 60,
+                            "type": "text",
+                        },
+                    ],
+                    "metadata": {},
+                    "usage": None,
+                },
+            ],
+        )
+        self.assertListEqual(
+            [_.model_dump() for _ in to_reserve],
+            [
+                {
+                    "id": "3",
+                    "created_at": AnyString(),
+                    "finished_at": AnyString(),
+                    "name": "User",
+                    "role": "user",
+                    "content": [
+                        {
+                            "id": AnyString(),
+                            "type": "text",
+                            "text": "d" * 40,
+                        },
+                    ],
+                    "metadata": {},
+                    "usage": None,
+                },
+            ],
+        )
+
+        # Leave the last block of the boundary message
+        agent.state.context = [
+            UserMsg("User", "".join(["a" for _ in range(30 * 4)]), id="1"),
+            AssistantMsg(
+                "Friday",
+                [
+                    TextBlock(
+                        text="".join(["b" for _ in range(10 * 4)]),
+                        id="b",
+                    ),
+                    TextBlock(
+                        text="".join(["c" for _ in range(5 * 4)]),
+                        id="c",
+                    ),
+                ],
+                id="2",
+            ),
+            UserMsg("User", "".join(["d" for _ in range(10 * 4)]), id="3"),
+        ]
+        to_compress, to_reserve = await agent._split_context_for_compression(
+            to_reserved_tokens=80,
+            tools=[],
+        )
+        self.assertListEqual(
+            [_.model_dump() for _ in to_compress],
+            [
+                {
+                    "id": "1",
+                    "created_at": AnyString(),
+                    "finished_at": AnyString(),
+                    "name": "User",
+                    "role": "user",
+                    "content": [
+                        {
+                            "id": AnyString(),
+                            "type": "text",
+                            "text": "a" * 120,
+                        },
+                    ],
+                    "metadata": {},
+                    "usage": None,
+                },
+                {
+                    "id": "2",
+                    "created_at": AnyString(),
+                    "finished_at": None,
+                    "name": "Friday",
+                    "role": "assistant",
+                    "content": [
+                        {
+                            "id": "b",
+                            "text": "b" * 40,
+                            "type": "text",
+                        },
+                    ],
+                    "metadata": {},
+                    "usage": None,
+                },
+            ],
+        )
+        self.assertListEqual(
+            [_.model_dump() for _ in to_reserve],
+            [
+                {
+                    "id": "2",
+                    "created_at": AnyString(),
+                    "finished_at": None,
+                    "name": "Friday",
+                    "role": "assistant",
+                    "content": [
+                        {
+                            "id": "c",
+                            "text": "c" * 20,
+                            "type": "text",
+                        },
+                    ],
+                    "metadata": {},
+                    "usage": None,
+                },
+                {
+                    "id": "3",
+                    "created_at": AnyString(),
+                    "finished_at": AnyString(),
+                    "name": "User",
+                    "role": "user",
+                    "content": [
+                        {
+                            "id": AnyString(),
+                            "type": "text",
+                            "text": "d" * 40,
+                        },
+                    ],
+                    "metadata": {},
+                    "usage": None,
+                },
+            ],
+        )
+
+        # Leave all the blocks
+        agent.state.context = [
+            UserMsg("User", "".join(["a" for _ in range(30 * 4)]), id="1"),
+            AssistantMsg(
+                "Friday",
+                [
+                    TextBlock(
+                        text="".join(["b" for _ in range(5 * 4)]),
+                        id="b",
+                    ),
+                    TextBlock(
+                        text="".join(["c" for _ in range(5 * 4)]),
+                        id="c",
+                    ),
+                ],
+                id="2",
+            ),
+            UserMsg("User", "".join(["d" for _ in range(10 * 4)]), id="3"),
+        ]
+        to_compress, to_reserve = await agent._split_context_for_compression(
+            to_reserved_tokens=80,
+            tools=[],
+        )
+        self.assertListEqual(
+            [_.model_dump() for _ in to_compress],
+            [
+                {
+                    "id": "1",
+                    "created_at": AnyString(),
+                    "finished_at": AnyString(),
+                    "name": "User",
+                    "role": "user",
+                    "content": [
+                        {
+                            "id": AnyString(),
+                            "type": "text",
+                            "text": "a" * 120,
+                        },
+                    ],
+                    "metadata": {},
+                    "usage": None,
+                },
+            ],
+        )
+        self.assertListEqual(
+            [_.model_dump() for _ in to_reserve],
+            [
+                {
+                    "id": "2",
+                    "created_at": AnyString(),
+                    "finished_at": None,
+                    "name": "Friday",
+                    "role": "assistant",
+                    "content": [
+                        {
+                            "id": "b",
+                            "text": "b" * 20,
+                            "type": "text",
+                        },
+                        {
+                            "id": "c",
+                            "text": "c" * 20,
+                            "type": "text",
+                        },
+                    ],
+                    "metadata": {},
+                    "usage": None,
+                },
+                {
+                    "id": "3",
+                    "created_at": AnyString(),
+                    "finished_at": AnyString(),
+                    "name": "User",
+                    "role": "user",
+                    "content": [
+                        {
+                            "id": AnyString(),
+                            "type": "text",
+                            "text": "d" * 40,
+                        },
+                    ],
+                    "metadata": {},
+                    "usage": None,
+                },
+            ],
+        )
+
+        # Leave all the messages
+        agent.state.context = [
+            AssistantMsg(
+                "Friday",
+                [
+                    TextBlock(
+                        text="".join(["b" for _ in range(5 * 4)]),
+                        id="b",
+                    ),
+                    TextBlock(
+                        text="".join(["c" for _ in range(5 * 4)]),
+                        id="c",
+                    ),
+                ],
+                id="2",
+            ),
+            UserMsg("User", "".join(["d" for _ in range(10 * 4)]), id="3"),
+        ]
+        to_compress, to_reserve = await agent._split_context_for_compression(
+            to_reserved_tokens=80,
+            tools=[],
+        )
+        self.assertListEqual(
+            [_.model_dump() for _ in to_compress],
+            [],
+        )
+        self.assertListEqual(
+            [_.model_dump() for _ in to_reserve],
+            [
+                {
+                    "id": "2",
+                    "created_at": AnyString(),
+                    "finished_at": None,
+                    "name": "Friday",
+                    "role": "assistant",
+                    "content": [
+                        {
+                            "id": "b",
+                            "text": "b" * 20,
+                            "type": "text",
+                        },
+                        {
+                            "id": "c",
+                            "text": "c" * 20,
+                            "type": "text",
+                        },
+                    ],
+                    "metadata": {},
+                    "usage": None,
+                },
+                {
+                    "id": "3",
+                    "created_at": AnyString(),
+                    "finished_at": AnyString(),
+                    "name": "User",
+                    "role": "user",
+                    "content": [
+                        {
+                            "id": AnyString(),
+                            "type": "text",
+                            "text": "d" * 40,
+                        },
+                    ],
+                    "metadata": {},
+                    "usage": None,
+                },
+            ],
+        )
+
+    async def test_context_compression(self) -> None:
+        """Test the context compression logic."""
+        model = MockModel(context_size=100)
+        agent = Agent(
+            name="Friday",
+            system_prompt="".join(["0" for _ in range(20 * 4)]),
+            model=model,
+            context_config=ContextConfig(
+                trigger_ratio=0.7,
+                reserve_ratio=0.4,
+            ),
+            state=AgentState(
+                session_id="123",
+                context=[
+                    UserMsg(
+                        "User",
+                        "".join(["1" for _ in range(30 * 4)]),
+                        id="1",
+                    ),
+                    AssistantMsg(
+                        "Friday",
+                        "".join(["2" for _ in range(10 * 4)]),
+                        id="2",
+                    ),
+                    UserMsg(
+                        "User",
+                        "".join(["3" for _ in range(10 * 4)]),
+                        id="3",
+                    ),
+                ],
+            ),
+            toolkit=Toolkit(),
+        )
+
+        model.set_structured_response(
+            StructuredResponse(
+                content={
+                    "task_overview": "1",
+                    "current_state": "2",
+                    "important_discoveries": "3",
+                    "next_steps": "4",
+                    "context_to_preserve": "5",
+                },
+            ),
+        )
+
+        await agent.compress_context()
+
+        self.assertEqual(
+            agent.state.summary,
+            """<system-info>Here is a summary of your previous work
+# Task Overview
+1
+
+# Current State
+2
+
+# Important Discoveries
+3
+
+# Next Steps
+4
+
+# Context to Preserve
+5</system-info>""",
+        )
+
+        self.assertListEqual(
+            [_.model_dump() for _ in agent.state.context],
+            [
+                {
+                    "id": "2",
+                    "created_at": AnyString(),
+                    "finished_at": None,
+                    "name": "Friday",
+                    "role": "assistant",
+                    "content": [
+                        {
+                            "id": AnyString(),
+                            "text": "2" * 40,
+                            "type": "text",
+                        },
+                    ],
+                    "metadata": {},
+                    "usage": None,
+                },
+                {
+                    "id": "3",
+                    "created_at": AnyString(),
+                    "finished_at": AnyString(),
+                    "name": "User",
+                    "role": "user",
+                    "content": [
+                        {
+                            "id": AnyString(),
+                            "text": "3" * 40,
+                            "type": "text",
+                        },
+                    ],
+                    "metadata": {},
+                    "usage": None,
+                },
+            ],
+        )
+
+    async def test_context_compression_clears_evicted_read_cache(self) -> None:
+        """Read cache is cleared when its Read block is compressed out."""
+        with tempfile.TemporaryDirectory() as temp_dir:
+            file_path = os.path.join(temp_dir, "test.txt")
+            with open(file_path, "w", encoding="utf-8") as f:
+                f.write("content\n")
+
+            model = MockModel(context_size=100)
+            agent = Agent(
+                name="Friday",
+                system_prompt="".join(["0" for _ in range(20 * 4)]),
+                model=model,
+                context_config=ContextConfig(
+                    trigger_ratio=0.7,
+                    reserve_ratio=0.4,
+                ),
+                state=AgentState(
+                    session_id="123",
+                    context=[
+                        AssistantMsg(
+                            "Friday",
+                            [
+                                ToolCallBlock(
+                                    id="read-call-1",
+                                    name="Read",
+                                    input=json.dumps(
+                                        {"file_path": file_path},
+                                    ),
+                                ),
+                            ],
+                            id="1",
+                        ),
+                        UserMsg(
+                            "User",
+                            "".join(["2" for _ in range(30 * 4)]),
+                            id="2",
+                        ),
+                        UserMsg(
+                            "User",
+                            "".join(["3" for _ in range(10 * 4)]),
+                            id="3",
+                        ),
+                    ],
+                ),
+                toolkit=Toolkit(),
+            )
+            await agent.state.tool_context.cache_file(
+                file_path=file_path,
+                lines=["content\n"],
+            )
+            self.assertIsNotNone(
+                await agent.state.tool_context.get_cache(file_path),
+            )
+
+            model.set_structured_response(
+                StructuredResponse(
+                    content={
+                        "task_overview": "1",
+                        "current_state": "2",
+                        "important_discoveries": "3",
+                        "next_steps": "4",
+                        "context_to_preserve": "5",
+                    },
+                ),
+            )
+
+            await agent.compress_context()
+
+            self.assertIsNone(
+                await agent.state.tool_context.get_cache(file_path),
+            )
+
+    async def test_context_compression_keeps_reserved_read_cache(
+        self,
+    ) -> None:
+        """Read cache is kept when the same file is still read in context."""
+        with tempfile.TemporaryDirectory() as temp_dir:
+            file_path = os.path.join(temp_dir, "test.txt")
+            with open(file_path, "w", encoding="utf-8") as f:
+                f.write("content\n")
+
+            model = MockModel(context_size=100)
+            agent = Agent(
+                name="Friday",
+                system_prompt="".join(["0" for _ in range(20 * 4)]),
+                model=model,
+                context_config=ContextConfig(
+                    trigger_ratio=0.7,
+                    reserve_ratio=0.6,
+                ),
+                state=AgentState(
+                    session_id="123",
+                    context=[
+                        AssistantMsg(
+                            "Friday",
+                            [
+                                ToolCallBlock(
+                                    id="read-call-1",
+                                    name="Read",
+                                    input=json.dumps(
+                                        {"file_path": file_path},
+                                    ),
+                                ),
+                            ],
+                            id="1",
+                        ),
+                        UserMsg(
+                            "User",
+                            "".join(["2" for _ in range(30 * 4)]),
+                            id="2",
+                        ),
+                        AssistantMsg(
+                            "Friday",
+                            [
+                                ToolCallBlock(
+                                    id="read-call-2",
+                                    name="Read",
+                                    input=json.dumps(
+                                        {"file_path": file_path},
+                                    ),
+                                ),
+                            ],
+                            id="3",
+                        ),
+                    ],
+                ),
+                toolkit=Toolkit(),
+            )
+            await agent.state.tool_context.cache_file(
+                file_path=file_path,
+                lines=["content\n"],
+            )
+
+            model.set_structured_response(
+                StructuredResponse(
+                    content={
+                        "task_overview": "1",
+                        "current_state": "2",
+                        "important_discoveries": "3",
+                        "next_steps": "4",
+                        "context_to_preserve": "5",
+                    },
+                ),
+            )
+
+            await agent.compress_context()
+
+            self.assertIsNotNone(
+                await agent.state.tool_context.get_cache(file_path),
+            )
+
+    async def test_context_compression_clears_unreferenced_read_cache(
+        self,
+    ) -> None:
+        """Read cache is cleared when no reserved Read references it."""
+        with tempfile.TemporaryDirectory() as temp_dir:
+            file_path = os.path.join(temp_dir, "test.txt")
+            with open(file_path, "w", encoding="utf-8") as f:
+                f.write("content\n")
+
+            model = MockModel(context_size=100)
+            agent = Agent(
+                name="Friday",
+                system_prompt="".join(["0" for _ in range(20 * 4)]),
+                model=model,
+                context_config=ContextConfig(
+                    trigger_ratio=0.7,
+                    reserve_ratio=0.4,
+                ),
+                state=AgentState(
+                    session_id="123",
+                    context=[
+                        UserMsg(
+                            "User",
+                            "".join(["2" for _ in range(60 * 4)]),
+                            id="1",
+                        ),
+                        UserMsg(
+                            "User",
+                            "".join(["3" for _ in range(30 * 4)]),
+                            id="2",
+                        ),
+                    ],
+                ),
+                toolkit=Toolkit(),
+            )
+            await agent.state.tool_context.cache_file(
+                file_path=file_path,
+                lines=["content\n"],
+            )
+
+            model.set_structured_response(
+                StructuredResponse(
+                    content={
+                        "task_overview": "1",
+                        "current_state": "2",
+                        "important_discoveries": "3",
+                        "next_steps": "4",
+                        "context_to_preserve": "5",
+                    },
+                ),
+            )
+
+            await agent.compress_context()
+
+            self.assertIsNone(
+                await agent.state.tool_context.get_cache(file_path),
+            )
+
+    async def test_context_compression_injects_instructions_as_hint(
+        self,
+    ) -> None:
+        """Instructions are injected as a HintBlock only for compression."""
+        model = RecordingStructuredMockModel(context_size=100)
+        agent = Agent(
+            name="Friday",
+            system_prompt="".join(["0" for _ in range(20 * 4)]),
+            model=model,
+            context_config=ContextConfig(
+                trigger_ratio=0.7,
+                reserve_ratio=0.4,
+            ),
+            state=AgentState(
+                session_id="123",
+                context=[
+                    UserMsg(
+                        "User",
+                        "".join(["1" for _ in range(30 * 4)]),
+                        id="1",
+                    ),
+                    AssistantMsg(
+                        "Friday",
+                        "".join(["2" for _ in range(10 * 4)]),
+                        id="2",
+                    ),
+                    UserMsg(
+                        "User",
+                        "".join(["3" for _ in range(10 * 4)]),
+                        id="3",
+                    ),
+                ],
+            ),
+            toolkit=Toolkit(),
+        )
+
+        model.set_structured_response(
+            StructuredResponse(
+                content={
+                    "task_overview": "1",
+                    "current_state": "2",
+                    "important_discoveries": "3",
+                    "next_steps": "4",
+                    "context_to_preserve": "5",
+                },
+            ),
+        )
+        instructions = HintBlock(
+            hint="Keep user requirements and file paths.",
+            source="user",
+        )
+
+        await agent.compress_context(instructions=instructions)
+
+        self.assertEqual(len(model.recorded_structured_messages), 1)
+        self.assertTrue(
+            _has_instruction_hint(
+                model.recorded_structured_messages[0],
+                instructions,
+            ),
+        )
+        self.assertFalse(
+            any(msg.get_content_blocks("hint") for msg in agent.state.context),
+        )
+
+    async def test_context_compression_overflow_retry_keeps_instructions(
+        self,
+    ) -> None:
+        """Overflow retry preserves instructions when rebuilding messages."""
+        model = RecordingStructuredMockModel(
+            context_size=100,
+            fail_structured_output_times=1,
+            force_compression_overflow=True,
+        )
+        agent = Agent(
+            name="Friday",
+            system_prompt="".join(["0" for _ in range(20 * 4)]),
+            model=model,
+            context_config=ContextConfig(
+                trigger_ratio=0.7,
+                reserve_ratio=0.4,
+            ),
+            state=AgentState(
+                session_id="123",
+                context=[
+                    UserMsg(
+                        "User",
+                        "".join(["1" for _ in range(30 * 4)]),
+                        id="1",
+                    ),
+                    AssistantMsg(
+                        "Friday",
+                        "".join(["2" for _ in range(10 * 4)]),
+                        id="2",
+                    ),
+                    UserMsg(
+                        "User",
+                        "".join(["3" for _ in range(10 * 4)]),
+                        id="3",
+                    ),
+                ],
+            ),
+            toolkit=Toolkit(),
+        )
+
+        model.set_structured_response(
+            StructuredResponse(
+                content={
+                    "task_overview": "1",
+                    "current_state": "2",
+                    "important_discoveries": "3",
+                    "next_steps": "4",
+                    "context_to_preserve": "5",
+                },
+            ),
+        )
+        instructions = HintBlock(
+            hint="Keep the user's original success criteria.",
+            source="user",
+        )
+
+        await agent.compress_context(instructions=instructions)
+
+        self.assertEqual(len(model.recorded_structured_messages), 2)
+        self.assertTrue(
+            _has_instruction_hint(
+                model.recorded_structured_messages[-1],
+                instructions,
+            ),
+        )
+
+    async def asyncTearDown(self) -> None:
+        """The async teardown method."""
diff --git a/tests/compress_tool_result_test.py b/tests/compress_tool_result_test.py
new file mode 100644
index 0000000..33cc166
--- /dev/null
+++ b/tests/compress_tool_result_test.py
@@ -0,0 +1,480 @@
+# -*- coding: utf-8 -*-
+"""The unittests for the tool result compression."""
+# pylint: disable=protected-access, unused-argument
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from utils import MockModel
+
+from agentscope.agent import Agent, ContextConfig
+from agentscope.message import (
+    ToolResultBlock,
+    TextBlock,
+    DataBlock,
+    Base64Source,
+)
+from agentscope.state import AgentState
+from agentscope.tool import Toolkit
+
+
+class ToolResultCompressionTest(IsolatedAsyncioTestCase):
+    """Test cases for tool result compression."""
+
+    async def asyncSetUp(self) -> None:
+        """The async setup method."""
+        self.mock_model = MockModel()
+        self.agent = Agent(
+            name="TestAgent",
+            system_prompt="Test system prompt",
+            model=self.mock_model,
+            toolkit=Toolkit(),
+            context_config=ContextConfig(
+                tool_result_limit=100,
+            ),
+            state=AgentState(session_id="test_session"),
+        )
+
+    async def test_below_limit(self) -> None:
+        """Test when tool result is below the token limit."""
+        tool_result = ToolResultBlock(
+            id="test_1",
+            name="test_tool",
+            output=[
+                TextBlock(text="Short text 1"),
+                TextBlock(text="Short text 2"),
+            ],
+        )
+
+        async def mock_count_tokens(
+            messages: list,
+            tools: list | None = None,
+        ) -> int:
+            """Mock token counting function that returns a fixed count."""
+            return 50
+
+        self.mock_model.count_tokens = mock_count_tokens
+        (
+            reserved,
+            offload,
+        ) = await self.agent._split_tool_result_for_compression(
+            tool_result,
+        )
+
+        self.assertEqual(reserved, tool_result)
+        self.assertIsNone(offload)
+
+    async def test_equal_to_limit(self) -> None:
+        """Test when tool result is exactly at the token limit."""
+        tool_result = ToolResultBlock(
+            id="test_2",
+            name="test_tool",
+            output=[TextBlock(text="Text at limit")],
+        )
+
+        async def mock_count_tokens(
+            messages: list,
+            tools: list | None = None,
+        ) -> int:
+            """Mock token counting function that returns a fixed count."""
+            return 100
+
+        self.mock_model.count_tokens = mock_count_tokens
+        (
+            reserved,
+            offload,
+        ) = await self.agent._split_tool_result_for_compression(
+            tool_result,
+        )
+
+        self.assertEqual(reserved, tool_result)
+        self.assertIsNone(offload)
+
+    async def test_boundary_last_block_text(self) -> None:
+        """Test when boundary is the last block and it is a TextBlock."""
+        block1 = TextBlock(text="A" * 20, id="block1")
+        block2 = TextBlock(text="B" * 20, id="block2")
+        block3 = TextBlock(text="C" * 100, id="block3")
+
+        tool_result = ToolResultBlock(
+            id="test_3",
+            name="test_tool",
+            output=[block1, block2, block3],
+        )
+
+        async def mock_count_tokens(
+            messages: list,
+            tools: list | None = None,
+        ) -> int:
+            """Mock token counting function that counts text length in
+            blocks."""
+            content = messages[0].content
+            if isinstance(content, list):
+                total = sum(len(b.text) for b in content if hasattr(b, "text"))
+                return total
+            return 0
+
+        self.mock_model.count_tokens = mock_count_tokens
+        (
+            reserved,
+            offload,
+        ) = await self.agent._split_tool_result_for_compression(
+            tool_result,
+        )
+
+        # Verify results
+        self.assertIsNotNone(reserved)
+        self.assertIsNotNone(offload)
+
+        # Verify ToolResultBlock metadata
+        self.assertEqual(reserved.id, tool_result.id)
+        self.assertEqual(reserved.name, tool_result.name)
+        self.assertEqual(reserved.state, tool_result.state)
+        self.assertEqual(offload.id, tool_result.id)
+        self.assertEqual(offload.name, tool_result.name)
+        self.assertEqual(offload.state, tool_result.state)
+
+        # Verify results using assertListEqual
+        expected_reserved = [
+            {"type": "text", "text": "A" * 20, "id": "block1"},
+            {"type": "text", "text": "B" * 20 + "C" * 60, "id": "block2"},
+        ]
+        expected_offload = [
+            {"type": "text", "text": "C" * 40, "id": "block3"},
+        ]
+
+        self.assertListEqual(
+            [b.model_dump() for b in reserved.output],
+            expected_reserved,
+        )
+        self.assertListEqual(
+            [b.model_dump() for b in offload.output],
+            expected_offload,
+        )
+
+    async def test_boundary_last_block_data(self) -> None:
+        """Test when boundary is the last block and it is a DataBlock."""
+        block1 = TextBlock(text="A" * 20, id="block1")
+        block2 = TextBlock(text="B" * 20, id="block2")
+        block3 = DataBlock(
+            source=Base64Source(data="base64data", media_type="image/png"),
+            id="block3",
+        )
+
+        tool_result = ToolResultBlock(
+            id="test_4",
+            name="test_tool",
+            output=[block1, block2, block3],
+        )
+
+        async def mock_count_tokens(
+            messages: list,
+            tools: list | None = None,
+        ) -> int:
+            """Mock token counting function based on content length."""
+            content = messages[0].content
+            if isinstance(content, list):
+                if len(content) == 3:
+                    return 150
+                elif len(content) == 2:
+                    return 80
+            return 50
+
+        self.mock_model.count_tokens = mock_count_tokens
+        (
+            reserved,
+            offload,
+        ) = await self.agent._split_tool_result_for_compression(
+            tool_result,
+        )
+
+        # Verify results
+        self.assertIsNotNone(reserved)
+        self.assertIsNotNone(offload)
+
+        # Verify ToolResultBlock metadata
+        self.assertEqual(reserved.id, tool_result.id)
+        self.assertEqual(offload.id, tool_result.id)
+
+        # Verify results using assertListEqual
+        expected_reserved = [
+            {"type": "text", "text": "A" * 20, "id": "block1"},
+            {"type": "text", "text": "B" * 20, "id": "block2"},
+        ]
+        expected_offload = [
+            {
+                "type": "data",
+                "id": "block3",
+                "source": {
+                    "type": "base64",
+                    "data": "base64data",
+                    "media_type": "image/png",
+                },
+                "name": None,
+            },
+        ]
+
+        self.assertListEqual(
+            [b.model_dump() for b in reserved.output],
+            expected_reserved,
+        )
+        self.assertListEqual(
+            [b.model_dump() for b in offload.output],
+            expected_offload,
+        )
+
+    async def test_boundary_first_block_text(self) -> None:
+        """Test when boundary is the first block and it is a TextBlock."""
+        block1 = TextBlock(text="A" * 100, id="block1")
+        block2 = TextBlock(text="B" * 20, id="block2")
+        block3 = TextBlock(text="C" * 20, id="block3")
+
+        tool_result = ToolResultBlock(
+            id="test_5",
+            name="test_tool",
+            output=[block1, block2, block3],
+        )
+
+        async def mock_count_tokens(
+            messages: list,
+            tools: list | None = None,
+        ) -> int:
+            """Mock token counting function that counts text length in
+            blocks."""
+            content = messages[0].content
+            if isinstance(content, list):
+                total = sum(len(b.text) for b in content if hasattr(b, "text"))
+                return total
+            return 0
+
+        self.mock_model.count_tokens = mock_count_tokens
+        (
+            reserved,
+            offload,
+        ) = await self.agent._split_tool_result_for_compression(
+            tool_result,
+        )
+
+        # Verify results using assertListEqual
+        expected_reserved = [
+            {"type": "text", "text": "A" * 100, "id": "block1"},
+        ]
+        expected_offload = [
+            {"type": "text", "text": "B" * 20, "id": "block2"},
+            {"type": "text", "text": "C" * 20, "id": "block3"},
+        ]
+
+        self.assertListEqual(
+            [b.model_dump() for b in reserved.output],
+            expected_reserved,
+        )
+        print(offload.output)
+        self.assertListEqual(
+            [b.model_dump() for b in offload.output],
+            expected_offload,
+        )
+
+    async def test_boundary_first_block_data(self) -> None:
+        """Test when boundary is the first block and it is a DataBlock."""
+        block1 = DataBlock(
+            source=Base64Source(data="base64data", media_type="image/png"),
+            id="block1",
+        )
+        block2 = TextBlock(text="B" * 20, id="block2")
+        block3 = TextBlock(text="C" * 20, id="block3")
+
+        tool_result = ToolResultBlock(
+            id="test_6",
+            name="test_tool",
+            output=[block1, block2, block3],
+        )
+
+        async def mock_count_tokens(
+            messages: list,
+            tools: list | None = None,
+        ) -> int:
+            """Mock token counting function based on content length."""
+            content = messages[0].content
+            if isinstance(content, list):
+                if len(content) == 3:
+                    return 150
+                elif len(content) == 2:
+                    return 80
+                elif len(content) == 1:
+                    return 60
+            return 50
+
+        self.mock_model.count_tokens = mock_count_tokens
+        (
+            reserved,
+            offload,
+        ) = await self.agent._split_tool_result_for_compression(
+            tool_result,
+        )
+
+        # Verify results
+        self.assertIsNotNone(reserved)
+        self.assertIsNotNone(offload)
+
+        # Verify ToolResultBlock metadata
+        self.assertEqual(reserved.id, tool_result.id)
+        self.assertEqual(offload.id, tool_result.id)
+
+        # Verify results using assertListEqual
+        expected_reserved = [
+            {
+                "type": "data",
+                "id": "block1",
+                "source": {
+                    "type": "base64",
+                    "data": "base64data",
+                    "media_type": "image/png",
+                },
+                "name": None,
+            },
+            {"type": "text", "text": "B" * 20 + "C" * 5, "id": "block2"},
+        ]
+        expected_offload = [
+            {"type": "text", "text": "C" * 15, "id": "block3"},
+        ]
+
+        self.assertListEqual(
+            [b.model_dump() for b in reserved.output],
+            expected_reserved,
+        )
+        self.assertListEqual(
+            [b.model_dump() for b in offload.output],
+            expected_offload,
+        )
+
+    async def test_boundary_middle_block_text(self) -> None:
+        """Test when boundary is a middle block and it is a TextBlock."""
+        block1 = TextBlock(text="A" * 20, id="block1")
+        block2 = TextBlock(text="B" * 100, id="block2")
+        block3 = TextBlock(text="C" * 20, id="block3")
+
+        tool_result = ToolResultBlock(
+            id="test_7",
+            name="test_tool",
+            output=[block1, block2, block3],
+        )
+
+        async def mock_count_tokens(
+            messages: list,
+            tools: list | None = None,
+        ) -> int:
+            """Mock token counting function that counts text length in
+            blocks."""
+            content = messages[0].content
+            if isinstance(content, list):
+                total = sum(len(b.text) for b in content if hasattr(b, "text"))
+                return total
+            return 0
+
+        self.mock_model.count_tokens = mock_count_tokens
+        (
+            reserved,
+            offload,
+        ) = await self.agent._split_tool_result_for_compression(
+            tool_result,
+        )
+
+        # Verify results
+        self.assertIsNotNone(reserved)
+        self.assertIsNotNone(offload)
+
+        # Verify ToolResultBlock metadata
+        self.assertEqual(reserved.id, tool_result.id)
+        self.assertEqual(offload.id, tool_result.id)
+
+        # Verify results using assertListEqual
+        expected_reserved = [
+            {"type": "text", "text": "A" * 20 + "B" * 80, "id": "block1"},
+        ]
+        expected_offload = [
+            {"type": "text", "text": "B" * 20 + "C" * 20, "id": "block3"},
+        ]
+
+        self.assertListEqual(
+            [b.model_dump() for b in reserved.output],
+            expected_reserved,
+        )
+        self.assertListEqual(
+            [b.model_dump() for b in offload.output],
+            expected_offload,
+        )
+
+    async def test_boundary_middle_block_data(self) -> None:
+        """Test when boundary is a middle block and it is a DataBlock."""
+        block1 = TextBlock(text="A" * 20, id="block1")
+        block2 = DataBlock(
+            source=Base64Source(data="base64data", media_type="image/png"),
+            id="block2",
+        )
+        block3 = TextBlock(text="C" * 20, id="block3")
+
+        tool_result = ToolResultBlock(
+            id="test_8",
+            name="test_tool",
+            output=[block1, block2, block3],
+        )
+
+        async def mock_count_tokens(
+            messages: list,
+            tools: list | None = None,
+        ) -> int:
+            """Mock token counting function based on content length."""
+            content = messages[0].content
+            if isinstance(content, list):
+                if len(content) == 3:
+                    return 150
+                elif len(content) == 2:
+                    return 80
+                elif len(content) == 1:
+                    return 40
+            return 50
+
+        self.mock_model.count_tokens = mock_count_tokens
+        (
+            reserved,
+            offload,
+        ) = await self.agent._split_tool_result_for_compression(
+            tool_result,
+        )
+
+        # Verify results
+        self.assertIsNotNone(reserved)
+        self.assertIsNotNone(offload)
+
+        # Verify ToolResultBlock metadata
+        self.assertEqual(reserved.id, tool_result.id)
+        self.assertEqual(offload.id, tool_result.id)
+
+        # Verify results using assertListEqual
+        expected_reserved = [
+            {"type": "text", "text": "A" * 20, "id": "block1"},
+            {
+                "type": "data",
+                "id": "block2",
+                "source": {
+                    "type": "base64",
+                    "data": "base64data",
+                    "media_type": "image/png",
+                },
+                "name": None,
+            },
+            {"type": "text", "text": "C" * 5, "id": "block3"},
+        ]
+        expected_offload = [
+            {"type": "text", "text": "C" * 15, "id": "block3"},
+        ]
+
+        self.assertListEqual(
+            [b.model_dump() for b in reserved.output],
+            expected_reserved,
+        )
+        self.assertListEqual(
+            [b.model_dump() for b in offload.output],
+            expected_offload,
+        )
+
+    async def asyncTearDown(self) -> None:
+        """The async teardown method."""
diff --git a/tests/docker/k8s_workspace_test.Dockerfile b/tests/docker/k8s_workspace_test.Dockerfile
new file mode 100644
index 0000000..d5067ba
--- /dev/null
+++ b/tests/docker/k8s_workspace_test.Dockerfile
@@ -0,0 +1,67 @@
+# syntax=docker/dockerfile:1.6
+# ---------------------------------------------------------------------------
+# Pre-baked image for K8sWorkspace integration tests.
+#
+# Rationale
+# ---------
+# K8sWorkspace's ``_setup_mcp_gateway`` skips the bootstrap phase when the
+# gateway script already exists inside the sandbox (see
+# ``SandboxedWorkspaceBase._setup_mcp_gateway`` — fast-path skip).
+# By pre-installing every dependency the bootstrap would install and by
+# copying the gateway/glob-helper scripts to ``GATEWAY_HOME`` at build time,
+# ``initialize()`` skips ``apt-get`` + ``uv install`` + ``pip install`` and
+# starts in ~10 s instead of ~5 min.
+#
+# Build context MUST be the repository root:
+#   docker build \
+#       -f tests/docker/k8s_workspace_test.Dockerfile \
+#       -t agentscope-k8s-test:ci .
+#
+# In CI the image is loaded into the kind cluster with:
+#   kind load docker-image agentscope-k8s-test:ci --name <cluster>
+# ---------------------------------------------------------------------------
+
+FROM python:3.11-slim
+
+# Keep in sync with agentscope.workspace._k8s._k8s_bootstrap.SYSTEM_DEPS
+RUN apt-get update -qq \
+ && apt-get install -y --no-install-recommends \
+        curl ca-certificates ripgrep \
+ && rm -rf /var/lib/apt/lists/*
+
+# uv — matches the bootstrap command exactly.
+RUN curl -LsSf https://astral.sh/uv/install.sh \
+  | env UV_INSTALL_DIR=/usr/local/bin INSTALLER_NO_MODIFY_PATH=1 sh
+
+# Keep in sync with agentscope.workspace._k8s._k8s_bootstrap.GATEWAY_HOME
+ENV GATEWAY_HOME=/root/.agentscope
+
+# Gateway venv + base runtime requirements
+# (mirrors ``_GATEWAY_BASE_REQUIREMENTS`` in _sandboxed_base.py)
+RUN mkdir -p "${GATEWAY_HOME}" \
+ && uv venv "${GATEWAY_HOME}/.venv" \
+ && uv pip install --python "${GATEWAY_HOME}/.venv/bin/python" \
+        mcp uvicorn fastapi
+
+# Install agentscope itself from the local checkout.
+# Build context is repo root, so pyproject.toml + src/ are visible at /src.
+COPY pyproject.toml README.md /src/
+COPY src /src/src
+RUN uv pip install --python "${GATEWAY_HOME}/.venv/bin/python" \
+        --no-deps /src
+
+# Copy the gateway script + glob helper into GATEWAY_HOME so that
+# ``_setup_mcp_gateway`` sees ``_gateway_script`` on disk and skips bootstrap.
+COPY src/agentscope/workspace/_mcp_gateway/_mcp_gateway_app.py \
+     "${GATEWAY_HOME}/_mcp_gateway_app.py"
+COPY src/agentscope/tool/_builtin/_scripts/_glob_helper.py \
+     "${GATEWAY_HOME}/_glob_helper.py"
+
+# The workdir is created lazily by ``_provision_sandbox``; leaving it here
+# just makes ad-hoc `docker run` debugging friendlier.
+WORKDIR /workspace
+
+# Container has nothing to run by itself — K8s Pod spec will override CMD
+# with the sleep loop from ``_build_pod_spec``.
+CMD ["sleep", "infinity"]
+
diff --git a/tests/embedding_dashscope_test.py b/tests/embedding_dashscope_test.py
new file mode 100644
index 0000000..68e0cd3
--- /dev/null
+++ b/tests/embedding_dashscope_test.py
@@ -0,0 +1,233 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access,unused-argument
+"""Unit tests for DashScopeEmbeddingModel."""
+from dataclasses import asdict
+from typing import Any
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import AsyncMock, MagicMock, patch
+
+from utils import AnyValue
+
+from agentscope.credential import DashScopeCredential
+from agentscope.embedding import (
+    DashScopeEmbeddingModel,
+    EmbeddingResponse,
+    EmbeddingUsage,
+)
+from agentscope.message import DataBlock, Base64Source, URLSource
+
+A = AnyValue()
+
+
+def _text_resp(
+    embeddings: list[list[float]],
+    total_tokens: int = 10,
+    status_code: int = 200,
+) -> MagicMock:
+    """Build a mock DashScope text embedding response."""
+    resp = MagicMock()
+    resp.status_code = status_code
+    resp.output = {"embeddings": [{"embedding": e} for e in embeddings]}
+    resp.usage = {"total_tokens": total_tokens}
+    return resp
+
+
+def _cred() -> DashScopeCredential:
+    """Create a test credential."""
+    return DashScopeCredential(api_key="k")
+
+
+def _img() -> DataBlock:
+    """Create a test image DataBlock."""
+    return DataBlock(
+        source=Base64Source(data="aWltYWdl", media_type="image/png"),
+    )
+
+
+def _vid() -> DataBlock:
+    """Create a test video DataBlock."""
+    return DataBlock(
+        source=URLSource(url="https://x.com/v.mp4", media_type="video/mp4"),
+    )
+
+
+def _mock_resp(embeddings: list[list[float]]) -> EmbeddingResponse:
+    """Create a mock EmbeddingResponse."""
+    return EmbeddingResponse(
+        embeddings=embeddings,
+        usage=EmbeddingUsage(tokens=len(embeddings), time=0.01),
+    )
+
+
+class DashScopeListModelsTest(IsolatedAsyncioTestCase):
+    """Test list_models for DashScope."""
+
+    async def test_list_models(self) -> None:
+        """Should list 7 models (text + multimodal)."""
+        cards = DashScopeEmbeddingModel.list_models()
+        names = sorted(c.name for c in cards)
+        self.assertEqual(len(cards), 7)
+        self.assertIn("text-embedding-v4", names)
+        self.assertIn("qwen3-vl-embedding", names)
+        self.assertIn("multimodal-embedding-v1", names)
+
+    async def test_hidden_dimensions(self) -> None:
+        """multimodal-embedding-v1 declares a fixed dimension (no enum)."""
+        cards = DashScopeEmbeddingModel.list_models()
+        v1 = next(c for c in cards if c.name == "multimodal-embedding-v1")
+        self.assertDictEqual(
+            v1.model_dump(),
+            {
+                "type": "embedding_model",
+                "name": "multimodal-embedding-v1",
+                "label": "Multimodal Embedding v1",
+                "status": "active",
+                "input_types": [
+                    "text/plain",
+                    "image/jpeg",
+                    "image/png",
+                    "image/bmp",
+                ],
+                "output_types": ["application/x-embedding"],
+                "dimensions": 1024,
+                "supported_dimensions": None,
+                "context_size": 512,
+                "parameter_schema": {
+                    "type": "object",
+                    "properties": {},
+                    "required": [],
+                },
+                "parameter_overrides": {},
+            },
+        )
+
+    async def test_visible_dimensions(self) -> None:
+        """qwen3-vl-embedding exposes dimension choices on the card."""
+        cards = DashScopeEmbeddingModel.list_models()
+        qwen = next(c for c in cards if c.name == "qwen3-vl-embedding")
+        self.assertEqual(qwen.dimensions, 2560)
+        self.assertEqual(
+            qwen.supported_dimensions,
+            [2560, 2048, 1536, 1024, 768, 512, 256],
+        )
+
+
+class DashScopeTextCallTest(IsolatedAsyncioTestCase):
+    """Test DashScope text embedding API calls."""
+
+    @patch("dashscope.embeddings.TextEmbedding.call")
+    async def test_text_call(self, mock_api: Any) -> None:
+        """Text mode returns correct embeddings."""
+        mock_api.return_value = _text_resp([[0.1, 0.2], [0.3, 0.4]], 12)
+        model = DashScopeEmbeddingModel(
+            credential=_cred(),
+            model="text-embedding-v4",
+            dimensions=2,
+        )
+        result = await model(["hello", "world"])
+        self.assertDictEqual(
+            asdict(result),
+            {
+                "embeddings": [[0.1, 0.2], [0.3, 0.4]],
+                "id": A,
+                "created_at": A,
+                "type": "embedding",
+                "usage": {"tokens": 12, "time": A, "type": "embedding"},
+                "source": "api",
+            },
+        )
+
+    @patch("dashscope.embeddings.TextEmbedding.call")
+    async def test_text_rejects_datablock(self, mock_api: Any) -> None:
+        """Text mode rejects DataBlock inputs."""
+        model = DashScopeEmbeddingModel(
+            credential=_cred(),
+            model="text-embedding-v4",
+            dimensions=1024,
+        )
+        with self.assertRaises(ValueError):
+            await model([_img()])
+
+    @patch("dashscope.embeddings.TextEmbedding.call")
+    async def test_text_api_error_raises(self, mock_api: Any) -> None:
+        """Non-200 status code raises RuntimeError after retries."""
+        mock_api.return_value = _text_resp([], status_code=400)
+        model = DashScopeEmbeddingModel(
+            credential=_cred(),
+            model="text-embedding-v4",
+            dimensions=1024,
+            retry_delay=0.0,
+        )
+        with self.assertRaises(RuntimeError):
+            await model(["hello"])
+
+
+class DashScopeMultimodalCallTest(IsolatedAsyncioTestCase):
+    """Test DashScope multimodal embedding via mocked _call_multimodal."""
+
+    async def test_multimodal_text_and_image(self) -> None:
+        """Multimodal call with text + image."""
+        model = DashScopeEmbeddingModel(
+            credential=_cred(),
+            model="qwen3-vl-embedding",
+            dimensions=2,
+        )
+        model._call_multimodal = AsyncMock(
+            return_value=_mock_resp([[0.1, 0.2], [0.3, 0.4]]),
+        )
+        result = await model(["describe this", _img()])
+        self.assertDictEqual(
+            asdict(result),
+            {
+                "embeddings": [[0.1, 0.2], [0.3, 0.4]],
+                "id": A,
+                "created_at": A,
+                "type": "embedding",
+                "usage": {"tokens": 2, "time": 0.01, "type": "embedding"},
+                "source": "api",
+            },
+        )
+
+    async def test_multimodal_batching_by_image_limit(self) -> None:
+        """8 images with max_images=5 produces 2 batches (5+3)."""
+        model = DashScopeEmbeddingModel(
+            credential=_cred(),
+            model="qwen3-vl-embedding",
+            dimensions=1,
+        )
+        call_count = 0
+
+        async def _mock(inputs: list, **_kw: Any) -> EmbeddingResponse:
+            nonlocal call_count
+            call_count += 1
+            return _mock_resp([[0.1]] * len(inputs))
+
+        model._call_multimodal = _mock  # type: ignore[assignment]
+        result = await model([_img() for _ in range(8)])
+        self.assertEqual(result["embeddings"], [[0.1]] * 8)
+        self.assertEqual(call_count, 2)
+
+    async def test_multimodal_batching_by_video_limit(self) -> None:
+        """3 videos with max_videos=1 produces 3 batches."""
+        model = DashScopeEmbeddingModel(
+            credential=_cred(),
+            model="qwen3-vl-embedding",
+            dimensions=1,
+        )
+        call_count = 0
+
+        async def _mock(inputs: list, **_kw: Any) -> EmbeddingResponse:
+            nonlocal call_count
+            call_count += 1
+            return _mock_resp([[0.1]] * len(inputs))
+
+        model._call_multimodal = _mock  # type: ignore[assignment]
+        result = await model([_vid(), _vid(), _vid()])
+        self.assertEqual(result["embeddings"], [[0.1]] * 3)
+        self.assertEqual(call_count, 3)
+
+    async def test_video_base64_rejected(self) -> None:
+        """Video with Base64Source raises ValueError."""
+        bad = DataBlock(source=Base64Source(data="x", media_type="video/mp4"))
+        with self.assertRaises(ValueError):
+            DashScopeEmbeddingModel._format_data_block(bad)
diff --git a/tests/embedding_gemini_test.py b/tests/embedding_gemini_test.py
new file mode 100644
index 0000000..67fa05b
--- /dev/null
+++ b/tests/embedding_gemini_test.py
@@ -0,0 +1,179 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Unit tests for GeminiEmbeddingModel."""
+from dataclasses import asdict
+from typing import Any
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import AsyncMock
+
+from utils import AnyValue
+
+from agentscope.embedding import (
+    GeminiEmbeddingModel,
+    EmbeddingResponse,
+    EmbeddingUsage,
+)
+from agentscope.message import DataBlock, Base64Source
+
+A = AnyValue()
+
+
+def _mock_resp(embeddings: list[list[float]]) -> EmbeddingResponse:
+    """Create a mock EmbeddingResponse."""
+    return EmbeddingResponse(
+        embeddings=embeddings,
+        usage=EmbeddingUsage(tokens=len(embeddings), time=0.01),
+    )
+
+
+def _img() -> DataBlock:
+    """Create a test image DataBlock."""
+    return DataBlock(
+        source=Base64Source(data="aWltYWdl", media_type="image/png"),
+    )
+
+
+class GeminiListModelsTest(IsolatedAsyncioTestCase):
+    """Test list_models for Gemini."""
+
+    async def test_list_models(self) -> None:
+        """Should list 2 models."""
+        cards = GeminiEmbeddingModel.list_models()
+        names = sorted(c.name for c in cards)
+        self.assertEqual(names, ["gemini-embedding-001", "gemini-embedding-2"])
+
+    async def test_text_model_card(self) -> None:
+        """gemini-embedding-001 is text-only with 2048 context."""
+        cards = GeminiEmbeddingModel.list_models()
+        card = next(c for c in cards if c.name == "gemini-embedding-001")
+        self.assertDictEqual(
+            card.model_dump(),
+            {
+                "type": "embedding_model",
+                "name": "gemini-embedding-001",
+                "label": "Gemini Embedding 001",
+                "status": "active",
+                "input_types": ["text/plain"],
+                "output_types": ["application/x-embedding"],
+                "dimensions": 3072,
+                "supported_dimensions": [3072, 1536, 768, 512, 256, 128],
+                "context_size": 2048,
+                "parameter_schema": {
+                    "type": "object",
+                    "properties": {},
+                    "required": [],
+                },
+                "parameter_overrides": {},
+            },
+        )
+
+    async def test_multimodal_model_card(self) -> None:
+        """gemini-embedding-2 is multimodal with 8192 context."""
+        cards = GeminiEmbeddingModel.list_models()
+        card = next(c for c in cards if c.name == "gemini-embedding-2")
+        self.assertIn("image/png", card.input_types)
+        self.assertIn("application/pdf", card.input_types)
+        self.assertEqual(card.context_size, 8192)
+        self.assertEqual(card.supported_dimensions, [3072, 1536, 768])
+
+
+class GeminiTextCallTest(IsolatedAsyncioTestCase):
+    """Test Gemini text embedding via mocked _call_text."""
+
+    def _make_text_model(self) -> GeminiEmbeddingModel:
+        """Create a text-mode model bypassing __init__ (no genai)."""
+        model = GeminiEmbeddingModel.__new__(GeminiEmbeddingModel)
+        model.model = "gemini-embedding-001"
+        model.dimensions = 2
+        model.context_size = 2048
+        model.batch_size = 100
+        model.max_retries = 3
+        model.retry_delay = 1.0
+        model._is_multimodal = False
+        model.embedding_cache = None
+        return model
+
+    async def test_text_call(self) -> None:
+        """Text mode delegates to _call_text."""
+        model = self._make_text_model()
+        model._call_text = AsyncMock(
+            return_value=_mock_resp([[0.1, 0.2], [0.3, 0.4]]),
+        )
+        result = await model(["hello", "world"])
+        self.assertDictEqual(
+            asdict(result),
+            {
+                "embeddings": [[0.1, 0.2], [0.3, 0.4]],
+                "id": A,
+                "created_at": A,
+                "type": "embedding",
+                "usage": {"tokens": 2, "time": 0.01, "type": "embedding"},
+                "source": "api",
+            },
+        )
+
+    async def test_text_rejects_datablock(self) -> None:
+        """Text mode rejects DataBlock inputs."""
+        model = self._make_text_model()
+        with self.assertRaises(ValueError):
+            await GeminiEmbeddingModel._call_text(model, [_img()])
+
+
+class GeminiMultimodalCallTest(IsolatedAsyncioTestCase):
+    """Test Gemini multimodal embedding via mocked _call_multimodal."""
+
+    def _make_multimodal_model(self) -> GeminiEmbeddingModel:
+        """Create a multimodal-mode model bypassing __init__."""
+        model = GeminiEmbeddingModel.__new__(GeminiEmbeddingModel)
+        model.model = "gemini-embedding-2"
+        model.dimensions = 1
+        model.context_size = 8192
+        model.batch_size = 100
+        model.max_retries = 3
+        model.retry_delay = 1.0
+        model._is_multimodal = True
+        model.embedding_cache = None
+        from agentscope.embedding._gemini._model import _MultimodalLimits
+
+        model._limits = _MultimodalLimits(
+            max_elements=20,
+            max_images=6,
+            max_videos=1,
+            max_audios=1,
+            max_pdfs=1,
+        )
+        return model
+
+    async def test_multimodal_delegates(self) -> None:
+        """Multimodal mode delegates to _call_multimodal."""
+        model = self._make_multimodal_model()
+        model._call_multimodal = AsyncMock(
+            return_value=_mock_resp([[0.1], [0.2]]),
+        )
+        result = await model(["hello", "world"])
+        self.assertDictEqual(
+            asdict(result),
+            {
+                "embeddings": [[0.1], [0.2]],
+                "id": A,
+                "created_at": A,
+                "type": "embedding",
+                "usage": {"tokens": 2, "time": 0.01, "type": "embedding"},
+                "source": "api",
+            },
+        )
+
+    async def test_multimodal_batching_by_image_limit(self) -> None:
+        """8 images with max_images=6 produces 2 batches (6+2)."""
+        model = self._make_multimodal_model()
+        call_count = 0
+
+        async def _mock(inputs: list, **_kw: Any) -> EmbeddingResponse:
+            nonlocal call_count
+            call_count += 1
+            return _mock_resp([[0.1]] * len(inputs))
+
+        model._call_multimodal = _mock  # type: ignore[assignment]
+        result = await model([_img() for _ in range(8)])
+        self.assertEqual(result["embeddings"], [[0.1]] * 8)
+        self.assertEqual(call_count, 2)
diff --git a/tests/embedding_ollama_test.py b/tests/embedding_ollama_test.py
new file mode 100644
index 0000000..202f23d
--- /dev/null
+++ b/tests/embedding_ollama_test.py
@@ -0,0 +1,106 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Unit tests for OllamaEmbeddingModel."""
+from dataclasses import asdict
+from typing import Any
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import AsyncMock
+
+from utils import AnyValue
+
+from agentscope.credential import OllamaCredential
+from agentscope.embedding import (
+    OllamaEmbeddingModel,
+    EmbeddingResponse,
+    EmbeddingUsage,
+)
+
+A = AnyValue()
+
+
+def _cred() -> OllamaCredential:
+    """Create a test credential."""
+    return OllamaCredential(host="http://localhost:11434")
+
+
+def _mock_resp(embeddings: list[list[float]]) -> EmbeddingResponse:
+    """Create a mock EmbeddingResponse."""
+    return EmbeddingResponse(
+        embeddings=embeddings,
+        usage=EmbeddingUsage(tokens=len(embeddings), time=0.01),
+    )
+
+
+class OllamaListModelsTest(IsolatedAsyncioTestCase):
+    """Test list_models for Ollama."""
+
+    async def test_list_models_empty(self) -> None:
+        """Ollama has no pre-defined YAMLs, returns empty list."""
+        self.assertEqual(OllamaEmbeddingModel.list_models(), [])
+
+
+class OllamaEmbeddingCallTest(IsolatedAsyncioTestCase):
+    """Test Ollama embedding via mocked _call_api."""
+
+    async def test_basic_call(self) -> None:
+        """Basic call returns correct embeddings."""
+        model = OllamaEmbeddingModel(
+            credential=_cred(),
+            model="nomic-embed-text",
+            dimensions=2,
+        )
+        model._call_api = AsyncMock(
+            return_value=_mock_resp([[0.1, 0.2], [0.3, 0.4]]),
+        )
+        result = await model(["hello", "world"])
+        self.assertDictEqual(
+            asdict(result),
+            {
+                "embeddings": [[0.1, 0.2], [0.3, 0.4]],
+                "id": A,
+                "created_at": A,
+                "type": "embedding",
+                "usage": {"tokens": 2, "time": 0.01, "type": "embedding"},
+                "source": "api",
+            },
+        )
+
+    async def test_dimensions_and_host(self) -> None:
+        """Dimensions and host are set correctly from constructor."""
+        model = OllamaEmbeddingModel(
+            credential=OllamaCredential(host="http://gpu:11434"),
+            model="test",
+            dimensions=768,
+        )
+        self.assertEqual(model.dimensions, 768)
+        self.assertEqual(model.host, "http://gpu:11434")
+
+    async def test_multi_batch(self) -> None:
+        """Batching splits inputs correctly."""
+        model = OllamaEmbeddingModel(
+            credential=_cred(),
+            model="test",
+            dimensions=1,
+        )
+        model.batch_size = 2
+        call_count = 0
+
+        async def _mock(inputs: list[str], **_kw: Any) -> EmbeddingResponse:
+            nonlocal call_count
+            call_count += 1
+            return _mock_resp([[0.1]] * len(inputs))
+
+        model._call_api = _mock  # type: ignore[assignment]
+        result = await model(["a", "b", "c"])
+        self.assertDictEqual(
+            asdict(result),
+            {
+                "embeddings": [[0.1], [0.1], [0.1]],
+                "id": A,
+                "created_at": A,
+                "type": "embedding",
+                "usage": {"tokens": A, "time": A, "type": "embedding"},
+                "source": "api",
+            },
+        )
+        self.assertEqual(call_count, 2)
diff --git a/tests/embedding_openai_test.py b/tests/embedding_openai_test.py
new file mode 100644
index 0000000..a796116
--- /dev/null
+++ b/tests/embedding_openai_test.py
@@ -0,0 +1,183 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Unit tests for OpenAIEmbeddingModel."""
+from dataclasses import asdict
+from typing import Any
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import AsyncMock, MagicMock, patch
+
+from utils import AnyValue
+
+from agentscope.credential import OpenAICredential
+from agentscope.embedding import OpenAIEmbeddingModel
+
+A = AnyValue()
+
+
+def _make_response(
+    embeddings: list[list[float]],
+    total_tokens: int = 10,
+) -> MagicMock:
+    """Build a mock ``openai.embeddings.create`` response."""
+    resp = MagicMock()
+    resp.data = [MagicMock(embedding=e) for e in embeddings]
+    resp.usage = MagicMock(total_tokens=total_tokens)
+    return resp
+
+
+class OpenAIListModelsTest(IsolatedAsyncioTestCase):
+    """Test ``list_models()`` for OpenAI."""
+
+    async def test_list_models(self) -> None:
+        """Should list 2 models with correct parameter_schema."""
+        cards = OpenAIEmbeddingModel.list_models()
+        names = sorted(c.name for c in cards)
+        self.assertEqual(
+            names,
+            ["text-embedding-3-large", "text-embedding-3-small"],
+        )
+
+        card = next(c for c in cards if c.name == "text-embedding-3-small")
+        self.assertDictEqual(
+            card.model_dump(),
+            {
+                "type": "embedding_model",
+                "name": "text-embedding-3-small",
+                "label": "Text Embedding 3 Small",
+                "status": "active",
+                "input_types": ["text/plain"],
+                "output_types": ["application/x-embedding"],
+                "dimensions": 1536,
+                "supported_dimensions": [1536, 1024, 768, 512, 256],
+                "context_size": 8191,
+                "parameter_schema": {
+                    "type": "object",
+                    "properties": {},
+                    "required": [],
+                },
+                "parameter_overrides": {},
+            },
+        )
+
+
+class OpenAIEmbeddingCallTest(IsolatedAsyncioTestCase):
+    """Test OpenAI embedding API calls with mocked responses."""
+
+    @patch("openai.AsyncClient")
+    async def test_single_batch(self, mock_client_cls: Any) -> None:
+        """Single batch call returns correct embeddings."""
+        mock_client = MagicMock()
+        mock_client.embeddings.create = AsyncMock(
+            return_value=_make_response([[0.1, 0.2], [0.3, 0.4]], 8),
+        )
+        mock_client_cls.return_value = mock_client
+
+        model = OpenAIEmbeddingModel(
+            credential=OpenAICredential(api_key="k"),
+            model="text-embedding-3-small",
+            dimensions=2,
+        )
+        result = await model(["hello", "world"])
+
+        self.assertDictEqual(
+            asdict(result),
+            {
+                "embeddings": [[0.1, 0.2], [0.3, 0.4]],
+                "id": A,
+                "created_at": A,
+                "type": "embedding",
+                "usage": {"tokens": 8, "time": A, "type": "embedding"},
+                "source": "api",
+            },
+        )
+
+    @patch("openai.AsyncClient")
+    async def test_multi_batch(self, mock_client_cls: Any) -> None:
+        """Inputs exceeding batch_size are split and merged."""
+        mock_client = MagicMock()
+        mock_client.embeddings.create = AsyncMock(
+            side_effect=[
+                _make_response([[0.1], [0.2]], 4),
+                _make_response([[0.3]], 2),
+            ],
+        )
+        mock_client_cls.return_value = mock_client
+
+        model = OpenAIEmbeddingModel(
+            credential=OpenAICredential(api_key="k"),
+            model="text-embedding-3-small",
+            dimensions=1,
+        )
+        model.batch_size = 2
+
+        result = await model(["a", "b", "c"])
+
+        self.assertDictEqual(
+            asdict(result),
+            {
+                "embeddings": [[0.1], [0.2], [0.3]],
+                "id": A,
+                "created_at": A,
+                "type": "embedding",
+                "usage": {"tokens": 6, "time": A, "type": "embedding"},
+                "source": "api",
+            },
+        )
+
+    @patch("openai.AsyncClient")
+    async def test_empty_input(self, mock_client_cls: Any) -> None:
+        """Empty input returns empty response without API call."""
+        mock_client = MagicMock()
+        mock_client_cls.return_value = mock_client
+
+        model = OpenAIEmbeddingModel(
+            credential=OpenAICredential(api_key="k"),
+            model="text-embedding-3-small",
+            dimensions=1536,
+        )
+        result = await model([])
+
+        self.assertDictEqual(
+            asdict(result),
+            {
+                "embeddings": [],
+                "id": A,
+                "created_at": A,
+                "type": "embedding",
+                "usage": {"tokens": 0, "time": 0, "type": "embedding"},
+                "source": "api",
+            },
+        )
+        mock_client.embeddings.create.assert_not_called()
+
+    @patch("openai.AsyncClient")
+    async def test_retry_on_transient_error(
+        self,
+        mock_client_cls: Any,
+    ) -> None:
+        """Retryable OpenAI errors are retried."""
+        import openai
+
+        mock_client = MagicMock()
+        mock_client.embeddings.create = AsyncMock(
+            side_effect=[
+                openai.RateLimitError(
+                    message="rate limit",
+                    response=MagicMock(status_code=429),
+                    body=None,
+                ),
+                _make_response([[0.1]], 1),
+            ],
+        )
+        mock_client_cls.return_value = mock_client
+
+        model = OpenAIEmbeddingModel(
+            credential=OpenAICredential(api_key="k"),
+            model="text-embedding-3-small",
+            dimensions=1,
+            retry_delay=0.0,
+        )
+        result = await model(["hello"])
+
+        self.assertEqual(result["embeddings"], [[0.1]])
+        self.assertEqual(mock_client.embeddings.create.await_count, 2)
diff --git a/tests/event_test.py b/tests/event_test.py
new file mode 100644
index 0000000..f766d95
--- /dev/null
+++ b/tests/event_test.py
@@ -0,0 +1,50 @@
+# -*- coding: utf-8 -*-
+"""Event test"""
+from unittest.async_case import IsolatedAsyncioTestCase
+from utils import AnyString
+from agentscope.event import ReplyStartEvent
+
+
+class EventTest(IsolatedAsyncioTestCase):
+    """The event test case."""
+
+    async def asyncSetUp(self) -> None:
+        """The async setup method."""
+
+    async def test_model_dump(self) -> None:
+        """Test model dump."""
+        event = ReplyStartEvent(
+            session_id="test_session",
+            reply_id="test_reply",
+            name="Friday",
+        ).model_dump()
+        self.assertDictEqual(
+            event,
+            {
+                "type": "REPLY_START",
+                "id": AnyString(),
+                "created_at": AnyString(),
+                "metadata": {},
+                "session_id": "test_session",
+                "reply_id": "test_reply",
+                "name": "Friday",
+                "role": "assistant",
+            },
+        )
+        self.assertIsInstance(event["type"], str)
+
+    async def test_model_validate(self) -> None:
+        """Test model validate."""
+        data = {
+            "type": "REPLY_START",
+            "id": "test_id",
+            "created_at": "2024-01-01T00:00:00",
+            "session_id": "test_session",
+            "reply_id": "test_reply",
+            "name": "Friday",
+            "role": "assistant",
+        }
+        ReplyStartEvent.model_validate(data)
+
+    async def asyncTearDown(self) -> None:
+        """The async teardown method."""
diff --git a/tests/event_to_message_test.py b/tests/event_to_message_test.py
new file mode 100644
index 0000000..08c06f6
--- /dev/null
+++ b/tests/event_to_message_test.py
@@ -0,0 +1,928 @@
+# -*- coding: utf-8 -*-
+"""Unit tests for Msg.append_event – event-stream-to-Msg accumulation.
+
+The test drives a single Msg object through a full, realistic streaming
+sequence and asserts the complete model_dump() after every individual event.
+
+Coverage
+--------
+* TextBlock  : start / delta (×2) / end
+* ThinkingBlock : start / delta (×2) / end
+* DataBlock (base-64) : start / delta (×2) / end
+* ToolCallBlock streaming : start / delta (×2) / end
+* RequireUserConfirmEvent  → ASKING state
+* UserConfirmResultEvent (confirmed=True)  → ALLOWED state
+* UserConfirmResultEvent (confirmed=False) → FINISHED state
+* ToolResultBlock text output : start / text-delta (×2) / end (SUCCESS)
+* RequireExternalExecutionEvent → SUBMITTED state
+* ExternalExecutionResultEvent  → ToolResultBlock appended directly
+* ToolResultBlock data output   : base-64 delta + URL delta / end (ERROR)
+* ModelCallEndEvent (×2) → usage initialized then accumulated
+* ReplyEndEvent → finished_at stamped
+* Wrong reply_id → event silently skipped
+* Missing block  → warning, no crash
+"""
+from typing import Any
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from utils import AnyString
+
+from agentscope.event import (
+    ConfirmResult,
+    DataBlockDeltaEvent,
+    DataBlockEndEvent,
+    DataBlockStartEvent,
+    ExternalExecutionResultEvent,
+    ModelCallEndEvent,
+    ReplyEndEvent,
+    ReplyEndReason,
+    RequireExternalExecutionEvent,
+    RequireUserConfirmEvent,
+    TextBlockDeltaEvent,
+    TextBlockEndEvent,
+    TextBlockStartEvent,
+    ThinkingBlockDeltaEvent,
+    ThinkingBlockEndEvent,
+    ThinkingBlockStartEvent,
+    ToolCallDeltaEvent,
+    ToolCallEndEvent,
+    ToolCallStartEvent,
+    ToolResultDataDeltaEvent,
+    ToolResultEndEvent,
+    ToolResultStartEvent,
+    ToolResultTextDeltaEvent,
+    UserConfirmResultEvent,
+)
+from agentscope.message import (
+    Msg,
+    ToolCallBlock,
+    ToolResultBlock,
+    ToolResultState,
+)
+from agentscope.model import FinishedReason
+
+# ---------------------------------------------------------------------------
+# Fixed IDs used throughout – hard-coded so ground-truth dicts are readable.
+# ---------------------------------------------------------------------------
+_REPLY_ID = "reply_001"
+_SESSION_ID = "session_001"
+
+_B_TEXT = "b_text_001"  # TextBlock id
+_B_THINK = "b_think_001"  # ThinkingBlock id
+_B_DATA = "b_data_001"  # DataBlock id
+
+_TC_ALLOW = "tc_allow_001"  # tool call that gets confirmed → allowed
+_TC_DENY = "tc_deny_001"  # tool call that gets denied  → finished
+_TC_EXT = "tc_ext_001"  # tool call for external execution
+_TC_IMG = "tc_img_001"  # tool call whose result has data blocks
+
+_RES_DATA_B = "res_data_001"  # DataBlock inside tool-result (base-64)
+_RES_URL_B = "res_url_001"  # DataBlock inside tool-result (URL)
+
+_FIXED_END_TS = "2026-01-01T12:00:00"  # deterministic finished_at
+
+
+# ---------------------------------------------------------------------------
+# Block-dict helpers – each call returns a fresh dict to avoid aliasing.
+# ---------------------------------------------------------------------------
+
+
+def _tb(block_id: str, text: str) -> dict:
+    """Text block dict."""
+    return {"type": "text", "id": block_id, "text": text}
+
+
+def _thb(block_id: str, thinking: str) -> dict:
+    """Thinking block dict."""
+    return {"type": "thinking", "id": block_id, "thinking": thinking}
+
+
+def _db_b64(block_id: str, data: str, media_type: str) -> dict:
+    """DataBlock (base-64 source) dict."""
+    return {
+        "type": "data",
+        "id": block_id,
+        "source": {"type": "base64", "data": data, "media_type": media_type},
+        "name": None,
+    }
+
+
+def _db_url(block_id: str, url: str, media_type: str) -> dict:
+    """DataBlock (URL source) dict."""
+    return {
+        "type": "data",
+        "id": block_id,
+        "source": {"type": "url", "url": url, "media_type": media_type},
+        "name": None,
+    }
+
+
+def _tcb(tc_id: str, name: str, inp: str, state: str) -> dict:
+    """ToolCallBlock dict."""
+    return {
+        "type": "tool_call",
+        "id": tc_id,
+        "name": name,
+        "input": inp,
+        "state": state,
+        "suggested_rules": [],
+    }
+
+
+def _trb(tc_id: str, name: str, output: Any, state: str) -> dict:
+    """ToolResultBlock dict."""
+    return {
+        "type": "tool_result",
+        "id": tc_id,
+        "name": name,
+        "output": output,
+        "state": state,
+        "metadata": {},
+    }
+
+
+class EventToMessageTest(IsolatedAsyncioTestCase):
+    """Test Msg.append_event across a full streaming event sequence."""
+
+    # ------------------------------------------------------------------
+    # asyncSetUp: build self.events and self.ground_truths in lock-step.
+    # ------------------------------------------------------------------
+
+    async def asyncSetUp(self) -> None:
+        """Build the Msg, the event list, and the ground-truth list."""
+        self.msg = Msg(
+            id=_REPLY_ID,
+            name="TestAgent",
+            role="assistant",
+            content=[],
+        )
+        _created_at = self.msg.created_at
+
+        def _base(
+            content: list,
+            finished_at: str | None = None,
+            usage: dict | None = None,
+        ) -> dict:
+            """Return the expected model_dump() of self.msg."""
+            return {
+                "name": "TestAgent",
+                "role": "assistant",
+                "id": _REPLY_ID,
+                "metadata": {},
+                "created_at": _created_at,
+                "finished_at": finished_at,
+                "content": content,
+                "usage": usage,
+            }
+
+        # ================================================================
+        # Stage 1 – Text block streaming
+        # ================================================================
+        ev_text_start = TextBlockStartEvent(
+            reply_id=_REPLY_ID,
+            block_id=_B_TEXT,
+        )
+        gt_text_start = _base([_tb(_B_TEXT, "")])
+
+        ev_text_delta1 = TextBlockDeltaEvent(
+            reply_id=_REPLY_ID,
+            block_id=_B_TEXT,
+            delta="Hello",
+        )
+        gt_text_delta1 = _base([_tb(_B_TEXT, "Hello")])
+
+        ev_text_delta2 = TextBlockDeltaEvent(
+            reply_id=_REPLY_ID,
+            block_id=_B_TEXT,
+            delta=" World",
+        )
+        gt_text_delta2 = _base([_tb(_B_TEXT, "Hello World")])
+
+        ev_text_end = TextBlockEndEvent(reply_id=_REPLY_ID, block_id=_B_TEXT)
+        gt_text_end = _base([_tb(_B_TEXT, "Hello World")])  # unchanged
+
+        # ================================================================
+        # Stage 2 – Thinking block streaming
+        # ================================================================
+        ev_think_start = ThinkingBlockStartEvent(
+            reply_id=_REPLY_ID,
+            block_id=_B_THINK,
+        )
+        gt_think_start = _base(
+            [
+                _tb(_B_TEXT, "Hello World"),
+                _thb(_B_THINK, ""),
+            ],
+        )
+
+        ev_think_delta1 = ThinkingBlockDeltaEvent(
+            reply_id=_REPLY_ID,
+            block_id=_B_THINK,
+            delta="Let me",
+        )
+        gt_think_delta1 = _base(
+            [
+                _tb(_B_TEXT, "Hello World"),
+                _thb(_B_THINK, "Let me"),
+            ],
+        )
+
+        ev_think_delta2 = ThinkingBlockDeltaEvent(
+            reply_id=_REPLY_ID,
+            block_id=_B_THINK,
+            delta=" think",
+        )
+        gt_think_delta2 = _base(
+            [
+                _tb(_B_TEXT, "Hello World"),
+                _thb(_B_THINK, "Let me think"),
+            ],
+        )
+
+        ev_think_end = ThinkingBlockEndEvent(
+            reply_id=_REPLY_ID,
+            block_id=_B_THINK,
+        )
+        gt_think_end = _base(
+            [  # unchanged
+                _tb(_B_TEXT, "Hello World"),
+                _thb(_B_THINK, "Let me think"),
+            ],
+        )
+
+        # ================================================================
+        # Stage 3 – Data block streaming (base-64)
+        # ================================================================
+        ev_data_start = DataBlockStartEvent(
+            reply_id=_REPLY_ID,
+            block_id=_B_DATA,
+            media_type="image/png",
+        )
+        gt_data_start = _base(
+            [
+                _tb(_B_TEXT, "Hello World"),
+                _thb(_B_THINK, "Let me think"),
+                _db_b64(_B_DATA, "", "image/png"),
+            ],
+        )
+
+        # Each delta carries an independently base64-encoded chunk (with its
+        # own padding); ``append_event`` decodes -> concats bytes -> re-encodes
+        # so the message reflects the concatenated underlying bytes, not a
+        # string-concat of the chunks. Here: b"abc" + b"def" -> "YWJjZGVm".
+        ev_data_delta1 = DataBlockDeltaEvent(
+            reply_id=_REPLY_ID,
+            block_id=_B_DATA,
+            data="YWJj",  # base64(b"abc")
+            media_type="image/png",
+        )
+        gt_data_delta1 = _base(
+            [
+                _tb(_B_TEXT, "Hello World"),
+                _thb(_B_THINK, "Let me think"),
+                _db_b64(_B_DATA, "YWJj", "image/png"),
+            ],
+        )
+
+        ev_data_delta2 = DataBlockDeltaEvent(
+            reply_id=_REPLY_ID,
+            block_id=_B_DATA,
+            data="ZGVm",  # base64(b"def")
+            media_type="image/png",
+        )
+        gt_data_delta2 = _base(
+            [
+                _tb(_B_TEXT, "Hello World"),
+                _thb(_B_THINK, "Let me think"),
+                _db_b64(_B_DATA, "YWJjZGVm", "image/png"),
+            ],
+        )
+
+        ev_data_end = DataBlockEndEvent(reply_id=_REPLY_ID, block_id=_B_DATA)
+        gt_data_end = _base(
+            [  # unchanged
+                _tb(_B_TEXT, "Hello World"),
+                _thb(_B_THINK, "Let me think"),
+                _db_b64(_B_DATA, "YWJjZGVm", "image/png"),
+            ],
+        )
+
+        # ================================================================
+        # Stage 4 – ToolCall (TC_ALLOW): stream → confirm → allowed
+        #           + text tool-result (SUCCESS)
+        # ================================================================
+        ev_tc_allow_start = ToolCallStartEvent(
+            reply_id=_REPLY_ID,
+            tool_call_id=_TC_ALLOW,
+            tool_call_name="search",
+        )
+        _s4_prefix = [
+            _tb(_B_TEXT, "Hello World"),
+            _thb(_B_THINK, "Let me think"),
+            _db_b64(_B_DATA, "YWJjZGVm", "image/png"),
+        ]
+        gt_tc_allow_start = _base(
+            _s4_prefix + [_tcb(_TC_ALLOW, "search", "", "pending")],
+        )
+
+        ev_tc_allow_delta1 = ToolCallDeltaEvent(
+            reply_id=_REPLY_ID,
+            tool_call_id=_TC_ALLOW,
+            delta='{"q"',
+        )
+        gt_tc_allow_delta1 = _base(
+            _s4_prefix + [_tcb(_TC_ALLOW, "search", '{"q"', "pending")],
+        )
+
+        ev_tc_allow_delta2 = ToolCallDeltaEvent(
+            reply_id=_REPLY_ID,
+            tool_call_id=_TC_ALLOW,
+            delta=': "hi"}',
+        )
+        gt_tc_allow_delta2 = _base(
+            _s4_prefix + [_tcb(_TC_ALLOW, "search", '{"q": "hi"}', "pending")],
+        )
+
+        ev_tc_allow_end = ToolCallEndEvent(
+            reply_id=_REPLY_ID,
+            tool_call_id=_TC_ALLOW,
+        )
+        gt_tc_allow_end = _base(  # unchanged
+            _s4_prefix + [_tcb(_TC_ALLOW, "search", '{"q": "hi"}', "pending")],
+        )
+
+        # RequireUserConfirmEvent  → state: pending → asking
+        _tc_allow_block = ToolCallBlock(
+            id=_TC_ALLOW,
+            name="search",
+            input='{"q": "hi"}',
+        )
+        ev_require_confirm = RequireUserConfirmEvent(
+            reply_id=_REPLY_ID,
+            tool_calls=[_tc_allow_block],
+        )
+        gt_require_confirm = _base(
+            _s4_prefix + [_tcb(_TC_ALLOW, "search", '{"q": "hi"}', "asking")],
+        )
+
+        # UserConfirmResultEvent (confirmed=True)  → state: asking → allowed
+        ev_user_confirmed = UserConfirmResultEvent(
+            reply_id=_REPLY_ID,
+            confirm_results=[
+                ConfirmResult(confirmed=True, tool_call=_tc_allow_block),
+            ],
+        )
+        gt_user_confirmed = _base(
+            _s4_prefix + [_tcb(_TC_ALLOW, "search", '{"q": "hi"}', "allowed")],
+        )
+
+        # ToolResult for _TC_ALLOW – text output
+        ev_result_start = ToolResultStartEvent(
+            reply_id=_REPLY_ID,
+            tool_call_id=_TC_ALLOW,
+            tool_call_name="search",
+        )
+        _s4b_prefix = _s4_prefix + [
+            _tcb(_TC_ALLOW, "search", '{"q": "hi"}', "allowed"),
+        ]
+        gt_result_start = _base(
+            _s4b_prefix + [_trb(_TC_ALLOW, "search", [], "running")],
+        )
+
+        # First text-delta creates a new TextBlock with auto-generated ID.
+        ev_result_text1 = ToolResultTextDeltaEvent(
+            reply_id=_REPLY_ID,
+            tool_call_id=_TC_ALLOW,
+            delta="Found:",
+        )
+        gt_result_text1 = _base(
+            _s4b_prefix
+            + [
+                _trb(
+                    _TC_ALLOW,
+                    "search",
+                    [{"type": "text", "id": AnyString(), "text": "Found:"}],
+                    "running",
+                ),
+            ],
+        )
+
+        # Second text-delta appends to the SAME TextBlock.
+        ev_result_text2 = ToolResultTextDeltaEvent(
+            reply_id=_REPLY_ID,
+            tool_call_id=_TC_ALLOW,
+            delta=" 3 items",
+        )
+        gt_result_text2 = _base(
+            _s4b_prefix
+            + [
+                _trb(
+                    _TC_ALLOW,
+                    "search",
+                    [
+                        {
+                            "type": "text",
+                            "id": AnyString(),
+                            "text": "Found: 3 items",
+                        },
+                    ],
+                    "running",
+                ),
+            ],
+        )
+
+        ev_result_end_ok = ToolResultEndEvent(
+            reply_id=_REPLY_ID,
+            tool_call_id=_TC_ALLOW,
+            state=ToolResultState.SUCCESS,
+        )
+        # TOOL_RESULT_END flips the paired ToolCallBlock to FINISHED, so the
+        # tool_call state in the prefix changes from "allowed" to "finished"
+        # from this point onward.
+        _s4b_done_prefix = _s4_prefix + [
+            _tcb(_TC_ALLOW, "search", '{"q": "hi"}', "finished"),
+        ]
+        gt_result_end_ok = _base(
+            _s4b_done_prefix
+            + [
+                _trb(
+                    _TC_ALLOW,
+                    "search",
+                    [
+                        {
+                            "type": "text",
+                            "id": AnyString(),
+                            "text": "Found: 3 items",
+                        },
+                    ],
+                    "success",
+                ),
+            ],
+        )
+
+        # ================================================================
+        # Stage 5 – ToolCall (TC_DENY): stream → confirm → denied (finished)
+        # ================================================================
+        _s5_prefix = _s4b_done_prefix + [
+            _trb(
+                _TC_ALLOW,
+                "search",
+                [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": "Found: 3 items",
+                    },
+                ],
+                "success",
+            ),
+        ]
+
+        ev_tc_deny_start = ToolCallStartEvent(
+            reply_id=_REPLY_ID,
+            tool_call_id=_TC_DENY,
+            tool_call_name="delete",
+        )
+        gt_tc_deny_start = _base(
+            _s5_prefix + [_tcb(_TC_DENY, "delete", "", "pending")],
+        )
+
+        ev_tc_deny_end = ToolCallEndEvent(
+            reply_id=_REPLY_ID,
+            tool_call_id=_TC_DENY,
+        )
+        gt_tc_deny_end = _base(  # unchanged
+            _s5_prefix + [_tcb(_TC_DENY, "delete", "", "pending")],
+        )
+
+        _tc_deny_block = ToolCallBlock(id=_TC_DENY, name="delete", input="")
+        ev_require_confirm_deny = RequireUserConfirmEvent(
+            reply_id=_REPLY_ID,
+            tool_calls=[_tc_deny_block],
+        )
+        gt_require_confirm_deny = _base(
+            _s5_prefix + [_tcb(_TC_DENY, "delete", "", "asking")],
+        )
+
+        # UserConfirmResultEvent (confirmed=False)  → state: asking → finished
+        ev_user_denied = UserConfirmResultEvent(
+            reply_id=_REPLY_ID,
+            confirm_results=[
+                ConfirmResult(confirmed=False, tool_call=_tc_deny_block),
+            ],
+        )
+        gt_user_denied = _base(
+            _s5_prefix + [_tcb(_TC_DENY, "delete", "", "finished")],
+        )
+
+        # ================================================================
+        # Stage 6 – ToolCall (TC_EXT): external execution flow
+        # ================================================================
+        _s6_prefix = _s5_prefix + [_tcb(_TC_DENY, "delete", "", "finished")]
+
+        ev_tc_ext_start = ToolCallStartEvent(
+            reply_id=_REPLY_ID,
+            tool_call_id=_TC_EXT,
+            tool_call_name="run_code",
+        )
+        gt_tc_ext_start = _base(
+            _s6_prefix + [_tcb(_TC_EXT, "run_code", "", "pending")],
+        )
+
+        ev_tc_ext_end = ToolCallEndEvent(
+            reply_id=_REPLY_ID,
+            tool_call_id=_TC_EXT,
+        )
+        gt_tc_ext_end = _base(  # unchanged
+            _s6_prefix + [_tcb(_TC_EXT, "run_code", "", "pending")],
+        )
+
+        _tc_ext_block = ToolCallBlock(id=_TC_EXT, name="run_code", input="")
+        ev_require_ext = RequireExternalExecutionEvent(
+            reply_id=_REPLY_ID,
+            tool_calls=[_tc_ext_block],
+        )
+        gt_require_ext = _base(
+            _s6_prefix + [_tcb(_TC_EXT, "run_code", "", "submitted")],
+        )
+
+        # ExternalExecutionResultEvent – appends a ToolResultBlock directly.
+        _ext_result_block = ToolResultBlock(
+            id=_TC_EXT,
+            name="run_code",
+            output="output: hello",
+            state=ToolResultState.SUCCESS,
+        )
+        ev_ext_result = ExternalExecutionResultEvent(
+            reply_id=_REPLY_ID,
+            execution_results=[_ext_result_block],
+        )
+        _s6b_prefix = _s6_prefix + [_tcb(_TC_EXT, "run_code", "", "submitted")]
+        gt_ext_result = _base(
+            _s6b_prefix
+            + [_trb(_TC_EXT, "run_code", "output: hello", "success")],
+        )
+
+        # ================================================================
+        # Stage 7 – ToolResult with data output: base-64 + URL blocks
+        # ================================================================
+        _s7_prefix = _s6b_prefix + [
+            _trb(_TC_EXT, "run_code", "output: hello", "success"),
+        ]
+
+        ev_tc_img_start = ToolCallStartEvent(
+            reply_id=_REPLY_ID,
+            tool_call_id=_TC_IMG,
+            tool_call_name="screenshot",
+        )
+        gt_tc_img_start = _base(
+            _s7_prefix + [_tcb(_TC_IMG, "screenshot", "", "pending")],
+        )
+
+        ev_tc_img_end = ToolCallEndEvent(
+            reply_id=_REPLY_ID,
+            tool_call_id=_TC_IMG,
+        )
+        gt_tc_img_end = _base(  # unchanged
+            _s7_prefix + [_tcb(_TC_IMG, "screenshot", "", "pending")],
+        )
+
+        ev_res_img_start = ToolResultStartEvent(
+            reply_id=_REPLY_ID,
+            tool_call_id=_TC_IMG,
+            tool_call_name="screenshot",
+        )
+        _s7b_prefix = _s7_prefix + [_tcb(_TC_IMG, "screenshot", "", "pending")]
+        gt_res_img_start = _base(
+            _s7b_prefix + [_trb(_TC_IMG, "screenshot", [], "running")],
+        )
+
+        # Base-64 data delta → DataBlock(base64) appended to output
+        ev_res_img_b64 = ToolResultDataDeltaEvent(
+            reply_id=_REPLY_ID,
+            tool_call_id=_TC_IMG,
+            block_id=_RES_DATA_B,
+            media_type="image/png",
+            data="iVBOR==",
+        )
+        gt_res_img_b64 = _base(
+            _s7b_prefix
+            + [
+                _trb(
+                    _TC_IMG,
+                    "screenshot",
+                    [_db_b64(_RES_DATA_B, "iVBOR==", "image/png")],
+                    "running",
+                ),
+            ],
+        )
+
+        # URL data delta → DataBlock(url) appended to output
+        ev_res_img_url = ToolResultDataDeltaEvent(
+            reply_id=_REPLY_ID,
+            tool_call_id=_TC_IMG,
+            block_id=_RES_URL_B,
+            media_type="image/jpeg",
+            url="https://example.com/img.jpg",
+        )
+        gt_res_img_url = _base(
+            _s7b_prefix
+            + [
+                _trb(
+                    _TC_IMG,
+                    "screenshot",
+                    [
+                        _db_b64(_RES_DATA_B, "iVBOR==", "image/png"),
+                        _db_url(
+                            _RES_URL_B,
+                            "https://example.com/img.jpg",
+                            "image/jpeg",
+                        ),
+                    ],
+                    "running",
+                ),
+            ],
+        )
+
+        ev_res_img_end = ToolResultEndEvent(
+            reply_id=_REPLY_ID,
+            tool_call_id=_TC_IMG,
+            state=ToolResultState.ERROR,
+        )
+        # TOOL_RESULT_END flips the paired ToolCallBlock to FINISHED.
+        _s7b_done_prefix = _s7_prefix + [
+            _tcb(_TC_IMG, "screenshot", "", "finished"),
+        ]
+        gt_res_img_end = _base(
+            _s7b_done_prefix
+            + [
+                _trb(
+                    _TC_IMG,
+                    "screenshot",
+                    [
+                        _db_b64(_RES_DATA_B, "iVBOR==", "image/png"),
+                        _db_url(
+                            _RES_URL_B,
+                            "https://example.com/img.jpg",
+                            "image/jpeg",
+                        ),
+                    ],
+                    "error",
+                ),
+            ],
+        )
+
+        # ================================================================
+        # Stage 8 – ModelCallEndEvent (first call: usage initialized;
+        #          second call: usage accumulated)
+        # ================================================================
+        _final_content = _s7b_done_prefix + [
+            _trb(
+                _TC_IMG,
+                "screenshot",
+                [
+                    _db_b64(_RES_DATA_B, "iVBOR==", "image/png"),
+                    _db_url(
+                        _RES_URL_B,
+                        "https://example.com/img.jpg",
+                        "image/jpeg",
+                    ),
+                ],
+                "error",
+            ),
+        ]
+        ev_model_call_end_1 = ModelCallEndEvent(
+            reply_id=_REPLY_ID,
+            input_tokens=10,
+            output_tokens=20,
+            finished_reason=FinishedReason.COMPLETED,
+        )
+        gt_model_call_end_1 = _base(
+            _final_content,
+            usage={"input_tokens": 10, "output_tokens": 20},
+        )
+
+        ev_model_call_end_2 = ModelCallEndEvent(
+            reply_id=_REPLY_ID,
+            input_tokens=5,
+            output_tokens=8,
+            finished_reason=FinishedReason.COMPLETED,
+        )
+        gt_model_call_end_2 = _base(
+            _final_content,
+            usage={"input_tokens": 15, "output_tokens": 28},
+        )
+
+        # ================================================================
+        # Stage 9 – ReplyEndEvent
+        # ================================================================
+        ev_reply_end = ReplyEndEvent(
+            reply_id=_REPLY_ID,
+            session_id=_SESSION_ID,
+            created_at=_FIXED_END_TS,
+            finished_reason=ReplyEndReason.COMPLETED,
+        )
+        gt_reply_end = _base(
+            _final_content,
+            finished_at=_FIXED_END_TS,
+            usage={"input_tokens": 15, "output_tokens": 28},
+        )
+
+        # ================================================================
+        # Assemble the two parallel lists
+        # ================================================================
+        self.events = [
+            # Stage 1: Text
+            ev_text_start,
+            ev_text_delta1,
+            ev_text_delta2,
+            ev_text_end,
+            # Stage 2: Thinking
+            ev_think_start,
+            ev_think_delta1,
+            ev_think_delta2,
+            ev_think_end,
+            # Stage 3: Data (base-64)
+            ev_data_start,
+            ev_data_delta1,
+            ev_data_delta2,
+            ev_data_end,
+            # Stage 4: ToolCall → confirm (allowed) + text result (success)
+            ev_tc_allow_start,
+            ev_tc_allow_delta1,
+            ev_tc_allow_delta2,
+            ev_tc_allow_end,
+            ev_require_confirm,
+            ev_user_confirmed,
+            ev_result_start,
+            ev_result_text1,
+            ev_result_text2,
+            ev_result_end_ok,
+            # Stage 5: ToolCall → confirm (denied)
+            ev_tc_deny_start,
+            ev_tc_deny_end,
+            ev_require_confirm_deny,
+            ev_user_denied,
+            # Stage 6: ToolCall → external execution
+            ev_tc_ext_start,
+            ev_tc_ext_end,
+            ev_require_ext,
+            ev_ext_result,
+            # Stage 7: ToolResult with data output (base-64 + URL)
+            ev_tc_img_start,
+            ev_tc_img_end,
+            ev_res_img_start,
+            ev_res_img_b64,
+            ev_res_img_url,
+            ev_res_img_end,
+            # Stage 8: MODEL_CALL_END (init + accumulate)
+            ev_model_call_end_1,
+            ev_model_call_end_2,
+            # Stage 9: REPLY_END
+            ev_reply_end,
+        ]
+        self.ground_truths = [
+            # Stage 1
+            gt_text_start,
+            gt_text_delta1,
+            gt_text_delta2,
+            gt_text_end,
+            # Stage 2
+            gt_think_start,
+            gt_think_delta1,
+            gt_think_delta2,
+            gt_think_end,
+            # Stage 3
+            gt_data_start,
+            gt_data_delta1,
+            gt_data_delta2,
+            gt_data_end,
+            # Stage 4
+            gt_tc_allow_start,
+            gt_tc_allow_delta1,
+            gt_tc_allow_delta2,
+            gt_tc_allow_end,
+            gt_require_confirm,
+            gt_user_confirmed,
+            gt_result_start,
+            gt_result_text1,
+            gt_result_text2,
+            gt_result_end_ok,
+            # Stage 5
+            gt_tc_deny_start,
+            gt_tc_deny_end,
+            gt_require_confirm_deny,
+            gt_user_denied,
+            # Stage 6
+            gt_tc_ext_start,
+            gt_tc_ext_end,
+            gt_require_ext,
+            gt_ext_result,
+            # Stage 7
+            gt_tc_img_start,
+            gt_tc_img_end,
+            gt_res_img_start,
+            gt_res_img_b64,
+            gt_res_img_url,
+            gt_res_img_end,
+            # Stage 8
+            gt_model_call_end_1,
+            gt_model_call_end_2,
+            # Stage 9
+            gt_reply_end,
+        ]
+
+    # ------------------------------------------------------------------
+    # Tests
+    # ------------------------------------------------------------------
+
+    async def test_append_event_stream(self) -> None:
+        """Apply every event in order and assert the full Msg state after each.
+
+        Uses a zip loop over self.events / self.ground_truths so that the
+        event index is clear from the assertion failure message.
+        """
+        self.assertEqual(
+            len(self.events),
+            len(self.ground_truths),
+            "events and ground_truths must have equal length",
+        )
+        for idx, (event, expected) in enumerate(
+            zip(self.events, self.ground_truths),
+        ):
+            self.msg.append_event(event)
+            self.assertDictEqual(
+                self.msg.model_dump(),
+                expected,
+                msg=f"Mismatch after event[{idx}] ({event.type})",
+            )
+
+    async def test_wrong_reply_id_is_skipped(self) -> None:
+        """An event whose reply_id does not match msg.id must be ignored."""
+        original_dump = self.msg.model_dump()
+        wrong_event = TextBlockStartEvent(
+            reply_id="totally_wrong_id",
+            block_id="should_not_appear",
+        )
+        self.msg.append_event(wrong_event)
+        self.assertDictEqual(
+            self.msg.model_dump(),
+            original_dump,
+            msg="Msg must not change when event.reply_id does not match",
+        )
+
+    async def test_missing_block_does_not_crash(self) -> None:
+        """Sending a delta for a non-existent block must log a warning only."""
+        original_dump = self.msg.model_dump()
+
+        # Delta events for blocks that were never started
+        ghost_events = [
+            TextBlockDeltaEvent(
+                reply_id=_REPLY_ID,
+                block_id="ghost_text",
+                delta="x",
+            ),
+            ThinkingBlockDeltaEvent(
+                reply_id=_REPLY_ID,
+                block_id="ghost_think",
+                delta="x",
+            ),
+            DataBlockDeltaEvent(
+                reply_id=_REPLY_ID,
+                block_id="ghost_data",
+                data="x",
+                media_type="image/png",
+            ),
+            ToolCallDeltaEvent(
+                reply_id=_REPLY_ID,
+                tool_call_id="ghost_tc",
+                delta="x",
+            ),
+            ToolResultTextDeltaEvent(
+                reply_id=_REPLY_ID,
+                tool_call_id="ghost_tr",
+                delta="x",
+            ),
+            ToolResultDataDeltaEvent(
+                reply_id=_REPLY_ID,
+                tool_call_id="ghost_tr",
+                media_type="image/png",
+                data="x",
+            ),
+            ToolResultEndEvent(
+                reply_id=_REPLY_ID,
+                tool_call_id="ghost_tr",
+                state=ToolResultState.SUCCESS,
+            ),
+        ]
+        for ev in ghost_events:
+            self.msg.append_event(ev)  # must not raise
+
+        self.assertDictEqual(
+            self.msg.model_dump(),
+            original_dump,
+            msg="Msg must not change when delta targets a missing block",
+        )
+
+    async def asyncTearDown(self) -> None:
+        """No teardown needed."""
diff --git a/tests/formatter_anthropic_test.py b/tests/formatter_anthropic_test.py
new file mode 100644
index 0000000..46a9ec5
--- /dev/null
+++ b/tests/formatter_anthropic_test.py
@@ -0,0 +1,1167 @@
+# -*- coding: utf-8 -*-
+"""Comprehensive formatter unit tests for AnthropicChatFormatter and
+AnthropicMultiAgentFormatter, following the reference test style with exact
+ground-truth comparisons.
+"""
+from unittest import IsolatedAsyncioTestCase
+
+from agentscope.formatter import (
+    AnthropicChatFormatter,
+    AnthropicMultiAgentFormatter,
+)
+from agentscope.message import (
+    UserMsg,
+    AssistantMsg,
+    SystemMsg,
+    TextBlock,
+    DataBlock,
+    ToolCallBlock,
+    ToolResultBlock,
+    ToolResultState,
+    Base64Source,
+    ThinkingBlock,
+    HintBlock,
+)
+
+
+class TestAnthropicFormatter(IsolatedAsyncioTestCase):
+    """Comprehensive tests for Anthropic Chat and MultiAgent formatters."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up shared message fixtures and expected ground-truth dicts."""
+        self.image_b64 = "ZmFrZSBpbWFnZSBkYXRh"
+
+        # ---------------------------------------------------------------
+        # Message fixtures
+        # (No URL images: Anthropic URL handling downloads from the network)
+        # ---------------------------------------------------------------
+        self.msgs_system = [
+            SystemMsg(
+                name="system",
+                content="You're a helpful assistant.",
+            ),
+        ]
+
+        self.msgs_conversation = [
+            UserMsg(
+                name="user",
+                content="What is the capital of France?",
+            ),
+            AssistantMsg(
+                name="assistant",
+                content="The capital of France is Paris.",
+            ),
+            UserMsg(
+                name="user",
+                content="What is the capital of Germany?",
+            ),
+            AssistantMsg(
+                name="assistant",
+                content="The capital of Germany is Berlin.",
+            ),
+            UserMsg(
+                name="user",
+                content="What is the capital of Japan?",
+            ),
+        ]
+
+        self.msgs_tools = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ToolCallBlock(
+                        id="call_1",
+                        name="get_capital",
+                        input='{"country": "Japan"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_1",
+                        name="get_capital",
+                        output=[
+                            TextBlock(text="The capital of Japan is Tokyo."),
+                        ],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    TextBlock(text="The capital of Japan is Tokyo."),
+                ],
+            ),
+        ]
+
+        # ---------------------------------------------------------------
+        # Ground truth: AnthropicChatFormatter
+        #   - No "name" field.
+        #   - Content is always a list of {"type": ..., ...} dicts.
+        #   - ToolResultBlock forces role to "user".
+        #   - ToolCallBlock "input" is a dict (parsed from JSON string).
+        # ---------------------------------------------------------------
+        self.gt_chat = [
+            {
+                "role": "system",
+                "content": [
+                    {"type": "text", "text": "You're a helpful assistant."},
+                ],
+            },
+            {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "text",
+                        "text": "What is the capital of France?",
+                    },
+                ],
+            },
+            {
+                "role": "assistant",
+                "content": [
+                    {
+                        "type": "text",
+                        "text": "The capital of France is Paris.",
+                    },
+                ],
+            },
+            {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "text",
+                        "text": "What is the capital of Germany?",
+                    },
+                ],
+            },
+            {
+                "role": "assistant",
+                "content": [
+                    {
+                        "type": "text",
+                        "text": "The capital of Germany is Berlin.",
+                    },
+                ],
+            },
+            {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "text",
+                        "text": "What is the capital of Japan?",
+                    },
+                ],
+            },
+            {
+                "role": "assistant",
+                "content": [
+                    {
+                        "type": "tool_use",
+                        "id": "call_1",
+                        "name": "get_capital",
+                        "input": {"country": "Japan"},
+                    },
+                ],
+            },
+            {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "tool_result",
+                        "tool_use_id": "call_1",
+                        "content": [
+                            {
+                                "type": "text",
+                                "text": "The capital of Japan is Tokyo.",
+                            },
+                        ],
+                    },
+                ],
+            },
+            {
+                "role": "assistant",
+                "content": [
+                    {
+                        "type": "text",
+                        "text": "The capital of Japan is Tokyo.",
+                    },
+                ],
+            },
+        ]
+
+        # ---------------------------------------------------------------
+        # Ground truth: AnthropicMultiAgentFormatter
+        #   - System: {"role": "system", "content": [{"type": "text", ...}]}
+        #   - Agent messages (is_first=True): wrapped in hist_prompt +
+        #     <history>...</history>.
+        #   - Agent messages (is_first=False): no wrapping at all.
+        # ---------------------------------------------------------------
+        _hist_prompt = (
+            AnthropicMultiAgentFormatter().conversation_history_prompt
+        )
+
+        _conv_text = (
+            "user: What is the capital of France?\n"
+            "assistant: The capital of France is Paris.\n"
+            "user: What is the capital of Germany?\n"
+            "assistant: The capital of Germany is Berlin.\n"
+            "user: What is the capital of Japan?"
+        )
+
+        self._gt_trailing_asst = {
+            "role": "assistant",
+            "content": [
+                {
+                    "type": "text",
+                    "text": "The capital of Japan is Tokyo.",
+                },
+            ],
+        }
+
+        self._gt_tool_call = {
+            "role": "assistant",
+            "content": [
+                {
+                    "type": "tool_use",
+                    "id": "call_1",
+                    "name": "get_capital",
+                    "input": {"country": "Japan"},
+                },
+            ],
+        }
+        self._gt_tool_result = {
+            "role": "user",
+            "content": [
+                {
+                    "type": "tool_result",
+                    "tool_use_id": "call_1",
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": "The capital of Japan is Tokyo.",
+                        },
+                    ],
+                },
+            ],
+        }
+
+        self.gt_multiagent = [
+            {
+                "role": "system",
+                "content": [
+                    {"type": "text", "text": "You're a helpful assistant."},
+                ],
+            },
+            {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "text",
+                        "text": (
+                            _hist_prompt
+                            + "<history>\n"
+                            + _conv_text
+                            + "\n</history>"
+                        ),
+                    },
+                ],
+            },
+            self._gt_tool_call,
+            self._gt_tool_result,
+            self._gt_trailing_asst,
+        ]
+
+    # -------------------------------------------------------------------
+    # AnthropicChatFormatter tests
+    # -------------------------------------------------------------------
+
+    async def test_chat_formatter(self) -> None:
+        """Chat formatter produces exact output for various subsets."""
+        fmt = AnthropicChatFormatter()
+
+        # Full history
+        res = await fmt.format(
+            [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+        )
+        self.assertListEqual(self.gt_chat, res)
+
+        # Without system
+        res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])
+        self.assertListEqual(self.gt_chat[1:], res)
+
+        # Without conversation
+        n_tools_gt = len(self.gt_chat) - 1 - len(self.msgs_conversation)
+        res = await fmt.format([*self.msgs_system, *self.msgs_tools])
+        self.assertListEqual(
+            [self.gt_chat[0]] + self.gt_chat[-n_tools_gt:],
+            res,
+        )
+
+        # Without tools
+        res = await fmt.format([*self.msgs_system, *self.msgs_conversation])
+        self.assertListEqual(self.gt_chat[:-n_tools_gt], res)
+
+        # Empty
+        res = await fmt.format([])
+        self.assertListEqual([], res)
+
+    async def test_chat_formatter_base64_image(self) -> None:
+        """Base64-encoded image is formatted as Anthropic image source."""
+        fmt = AnthropicChatFormatter()
+        msgs = [
+            UserMsg(
+                name="user",
+                content=[
+                    TextBlock(text="What's in this image?"),
+                    DataBlock(
+                        source=Base64Source(
+                            data=self.image_b64,
+                            media_type="image/png",
+                        ),
+                    ),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "user",
+                    "content": [
+                        {"type": "text", "text": "What's in this image?"},
+                        {
+                            "type": "image",
+                            "source": {
+                                "type": "base64",
+                                "media_type": "image/png",
+                                "data": self.image_b64,
+                            },
+                        },
+                    ],
+                },
+            ],
+            res,
+        )
+
+    async def test_chat_formatter_thinking_preserved(self) -> None:
+        """ThinkingBlock with a signature is passed back as a thinking
+        content block."""
+        fmt = AnthropicChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ThinkingBlock(
+                        thinking="inner thoughts",
+                        signature="sig_abc",
+                    ),
+                    TextBlock(text="reply"),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "assistant",
+                    "content": [
+                        {
+                            "type": "thinking",
+                            "thinking": "inner thoughts",
+                            "signature": "sig_abc",
+                        },
+                        {"type": "text", "text": "reply"},
+                    ],
+                },
+            ],
+            res,
+        )
+
+    async def test_chat_formatter_thinking_without_signature_dropped(
+        self,
+    ) -> None:
+        """ThinkingBlock from another provider (no signature) is dropped
+        rather than forwarded with an empty signature, which Anthropic
+        rejects with `Invalid signature in thinking block`. An empty-string
+        signature is treated the same as a missing one."""
+        fmt = AnthropicChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ThinkingBlock(thinking="from another provider"),
+                    ThinkingBlock(thinking="empty sig", signature=""),
+                    TextBlock(text="reply"),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "assistant",
+                    "content": [
+                        {"type": "text", "text": "reply"},
+                    ],
+                },
+            ],
+            res,
+        )
+
+        # Thinking-only message produces no output (no empty assistant msg).
+        res = await fmt.format(
+            [
+                AssistantMsg(
+                    name="assistant",
+                    content=[ThinkingBlock(thinking="only thinking")],
+                ),
+            ],
+        )
+        self.assertListEqual([], res)
+
+    async def test_chat_formatter_tool_result_role_forced_to_user(
+        self,
+    ) -> None:
+        """Anthropic forces tool_result messages to role='user'."""
+        fmt = AnthropicChatFormatter()
+        res = await fmt.format(
+            [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+        )
+        tool_result_roles = [
+            m["role"]
+            for m in res
+            if any(
+                b.get("type") == "tool_result"
+                for b in (m.get("content") or [])
+            )
+        ]
+        self.assertListEqual(tool_result_roles, ["user"])
+
+    async def test_chat_formatter_tool_result_with_image(self) -> None:
+        """Tool result containing an image DataBlock inlines the image in the
+        tool_result content without crashing on TextBlock system-reminders."""
+        fmt = AnthropicChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ToolCallBlock(
+                        id="call_img",
+                        name="get_chart",
+                        input="{}",
+                    ),
+                    ToolResultBlock(
+                        id="call_img",
+                        name="get_chart",
+                        output=[
+                            TextBlock(text="Here is the chart."),
+                            DataBlock(
+                                source=Base64Source(
+                                    data=self.image_b64,
+                                    media_type="image/png",
+                                ),
+                            ),
+                        ],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    TextBlock(text="Here is the chart analysis."),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "assistant",
+                    "content": [
+                        {
+                            "type": "tool_use",
+                            "id": "call_img",
+                            "name": "get_chart",
+                            "input": {},
+                        },
+                    ],
+                },
+                {
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "tool_result",
+                            "tool_use_id": "call_img",
+                            "content": [
+                                {
+                                    "type": "text",
+                                    "text": "Here is the chart.",
+                                },
+                                {
+                                    "type": "image",
+                                    "source": {
+                                        "type": "base64",
+                                        "media_type": "image/png",
+                                        "data": self.image_b64,
+                                    },
+                                },
+                            ],
+                        },
+                    ],
+                },
+                {
+                    "role": "assistant",
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": "Here is the chart analysis.",
+                        },
+                    ],
+                },
+            ],
+            res,
+        )
+
+    # -------------------------------------------------------------------
+    # AnthropicMultiAgentFormatter tests
+    # -------------------------------------------------------------------
+
+    async def test_multiagent_formatter(self) -> None:
+        """MultiAgent formatter produces exact output for various subsets."""
+        fmt = AnthropicMultiAgentFormatter()
+
+        # Full history
+        res = await fmt.format(
+            [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+        )
+        self.assertListEqual(self.gt_multiagent, res)
+
+        # Without system
+        res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])
+        self.assertListEqual(self.gt_multiagent[1:], res)
+
+        # Without tools
+        res = await fmt.format([*self.msgs_system, *self.msgs_conversation])
+        self.assertListEqual(self.gt_multiagent[:2], res)
+
+        # System only
+        res = await fmt.format(self.msgs_system)
+        self.assertListEqual([self.gt_multiagent[0]], res)
+
+        # Conversation only
+        res = await fmt.format(self.msgs_conversation)
+        self.assertListEqual([self.gt_multiagent[1]], res)
+
+        # Tools only
+        res = await fmt.format(self.msgs_tools)
+        self.assertListEqual(
+            [
+                self._gt_tool_call,
+                self._gt_tool_result,
+                self._gt_trailing_asst,
+            ],
+            res,
+        )
+
+        # System + tools (no conversation)
+        res = await fmt.format([*self.msgs_system, *self.msgs_tools])
+        self.assertListEqual(
+            [
+                self.gt_multiagent[0],
+                self._gt_tool_call,
+                self._gt_tool_result,
+                self._gt_trailing_asst,
+            ],
+            res,
+        )
+
+        # Empty
+        res = await fmt.format([])
+        self.assertListEqual([], res)
+
+    async def test_chat_formatter_complex_multi_step(self) -> None:
+        """Complex multi-step sequence with interleaved thinking, text,
+        tool calls, and tool results."""
+        fmt = AnthropicChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ThinkingBlock(thinking="thinking_1", signature="sig_1"),
+                    TextBlock(text="text_1"),
+                    ToolCallBlock(
+                        id="call_1",
+                        name="func_1",
+                        input='{"arg": "value1"}',
+                    ),
+                    ToolCallBlock(
+                        id="call_2",
+                        name="func_2",
+                        input='{"arg": "value2"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_1",
+                        name="func_1",
+                        output=[TextBlock(text="result_1")],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    ToolResultBlock(
+                        id="call_2",
+                        name="func_2",
+                        output=[TextBlock(text="result_2")],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    ThinkingBlock(thinking="thinking_2", signature="sig_2"),
+                    TextBlock(text="text_2"),
+                    ToolCallBlock(
+                        id="call_3",
+                        name="func_3",
+                        input='{"arg": "value3"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_3",
+                        name="func_3",
+                        output=[TextBlock(text="result_3")],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    ToolCallBlock(
+                        id="call_4",
+                        name="func_4",
+                        input='{"arg": "value4"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_4",
+                        name="func_4",
+                        output=[TextBlock(text="result_4")],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    ThinkingBlock(thinking="thinking_3", signature="sig_3"),
+                    TextBlock(text="text_3"),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "assistant",
+                    "content": [
+                        {
+                            "type": "thinking",
+                            "thinking": "thinking_1",
+                            "signature": "sig_1",
+                        },
+                        {"type": "text", "text": "text_1"},
+                        {
+                            "type": "tool_use",
+                            "id": "call_1",
+                            "name": "func_1",
+                            "input": {"arg": "value1"},
+                        },
+                        {
+                            "type": "tool_use",
+                            "id": "call_2",
+                            "name": "func_2",
+                            "input": {"arg": "value2"},
+                        },
+                    ],
+                },
+                {
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "tool_result",
+                            "tool_use_id": "call_1",
+                            "content": [
+                                {"type": "text", "text": "result_1"},
+                            ],
+                        },
+                        {
+                            "type": "tool_result",
+                            "tool_use_id": "call_2",
+                            "content": [
+                                {"type": "text", "text": "result_2"},
+                            ],
+                        },
+                    ],
+                },
+                {
+                    "role": "assistant",
+                    "content": [
+                        {
+                            "type": "thinking",
+                            "thinking": "thinking_2",
+                            "signature": "sig_2",
+                        },
+                        {"type": "text", "text": "text_2"},
+                        {
+                            "type": "tool_use",
+                            "id": "call_3",
+                            "name": "func_3",
+                            "input": {"arg": "value3"},
+                        },
+                    ],
+                },
+                {
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "tool_result",
+                            "tool_use_id": "call_3",
+                            "content": [
+                                {"type": "text", "text": "result_3"},
+                            ],
+                        },
+                    ],
+                },
+                {
+                    "role": "assistant",
+                    "content": [
+                        {
+                            "type": "tool_use",
+                            "id": "call_4",
+                            "name": "func_4",
+                            "input": {"arg": "value4"},
+                        },
+                    ],
+                },
+                {
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "tool_result",
+                            "tool_use_id": "call_4",
+                            "content": [
+                                {"type": "text", "text": "result_4"},
+                            ],
+                        },
+                    ],
+                },
+                {
+                    "role": "assistant",
+                    "content": [
+                        {
+                            "type": "thinking",
+                            "thinking": "thinking_3",
+                            "signature": "sig_3",
+                        },
+                        {"type": "text", "text": "text_3"},
+                    ],
+                },
+            ],
+            res,
+        )
+
+    async def test_chat_formatter_hint_block(self) -> None:
+        """HintBlock flushes preceding content and becomes a user message."""
+        fmt = AnthropicChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    TextBlock(text="Let me think about that."),
+                    HintBlock(hint="Remember to be concise."),
+                    TextBlock(text="Here is my answer."),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "assistant",
+                    "content": [
+                        {"type": "text", "text": "Let me think about that."},
+                    ],
+                },
+                {
+                    "role": "user",
+                    "content": [
+                        {"type": "text", "text": "Remember to be concise."},
+                    ],
+                },
+                {
+                    "role": "assistant",
+                    "content": [
+                        {"type": "text", "text": "Here is my answer."},
+                    ],
+                },
+            ],
+            res,
+        )
+
+    async def test_chat_formatter_hint_block_multimodal(self) -> None:
+        """Multimodal HintBlock becomes a single user message with text
+        + image."""
+        fmt = AnthropicChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    HintBlock(
+                        hint=[
+                            TextBlock(text="Inspect this screenshot:"),
+                            DataBlock(
+                                source=Base64Source(
+                                    data=self.image_b64,
+                                    media_type="image/png",
+                                ),
+                            ),
+                        ],
+                    ),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": "Inspect this screenshot:",
+                        },
+                        {
+                            "type": "image",
+                            "source": {
+                                "type": "base64",
+                                "media_type": "image/png",
+                                "data": self.image_b64,
+                            },
+                        },
+                    ],
+                },
+            ],
+            res,
+        )
+
+    async def test_chat_formatter_parallel_tool_results_merged(
+        self,
+    ) -> None:
+        """Parallel tool_results must be grouped into ONE user message.
+
+        Regression test for Issue #1892: AnthropicChatFormatter was flushing
+        content_blocks on every ToolResultBlock, which split N parallel results
+        into N separate user messages. Strict endpoints such as DeepSeek's
+        Anthropic-compatible API reject this with HTTP 400.
+        """
+        fmt = AnthropicChatFormatter()
+        msgs = [
+            UserMsg(
+                name="user",
+                content="Get weather for Beijing, Shanghai, and Guangzhou.",
+            ),
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    TextBlock(text="Let me check all three cities."),
+                    ToolCallBlock(
+                        id="call_01",
+                        name="get_weather",
+                        input='{"city": "Beijing"}',
+                    ),
+                    ToolCallBlock(
+                        id="call_02",
+                        name="get_weather",
+                        input='{"city": "Shanghai"}',
+                    ),
+                    ToolCallBlock(
+                        id="call_03",
+                        name="get_weather",
+                        input='{"city": "Guangzhou"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_01",
+                        name="get_weather",
+                        output="Sunny, 28\u00b0C",
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    ToolResultBlock(
+                        id="call_02",
+                        name="get_weather",
+                        output="Cloudy, 24\u00b0C",
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    ToolResultBlock(
+                        id="call_03",
+                        name="get_weather",
+                        output="Rainy, 22\u00b0C",
+                        state=ToolResultState.SUCCESS,
+                    ),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+
+        # Expected: 3 messages total
+        #   [0] user  -> original question
+        #   [1] assistant -> text + 3x tool_use
+        #   [2] user  -> ALL 3 tool_results in ONE message  (the fix)
+        self.assertListEqual(
+            [
+                {
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": "Get weather for Beijing, Shanghai, "
+                            "and Guangzhou.",
+                        },
+                    ],
+                },
+                {
+                    "role": "assistant",
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": "Let me check all three cities.",
+                        },
+                        {
+                            "type": "tool_use",
+                            "id": "call_01",
+                            "name": "get_weather",
+                            "input": {"city": "Beijing"},
+                        },
+                        {
+                            "type": "tool_use",
+                            "id": "call_02",
+                            "name": "get_weather",
+                            "input": {"city": "Shanghai"},
+                        },
+                        {
+                            "type": "tool_use",
+                            "id": "call_03",
+                            "name": "get_weather",
+                            "input": {"city": "Guangzhou"},
+                        },
+                    ],
+                },
+                {
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "tool_result",
+                            "tool_use_id": "call_01",
+                            "content": [
+                                {"type": "text", "text": "Sunny, 28\u00b0C"},
+                            ],
+                        },
+                        {
+                            "type": "tool_result",
+                            "tool_use_id": "call_02",
+                            "content": [
+                                {"type": "text", "text": "Cloudy, 24\u00b0C"},
+                            ],
+                        },
+                        {
+                            "type": "tool_result",
+                            "tool_use_id": "call_03",
+                            "content": [
+                                {"type": "text", "text": "Rainy, 22\u00b0C"},
+                            ],
+                        },
+                    ],
+                },
+            ],
+            res,
+        )
+
+    async def test_tool_call_with_incomplete_input_does_not_crash(
+        self,
+    ) -> None:
+        """A truncated ``block.input`` must not crash the formatter.
+
+        Context compression or interrupted streaming can leave a
+        ``ToolCallBlock.input`` as an incomplete JSON fragment (e.g.
+        ``'{"key'``). The formatter must repair it into a dict (here
+        ``{}``) instead of raising ``JSONDecodeError``.
+        """
+        fmt = AnthropicChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ToolCallBlock(
+                        id="call_1",
+                        name="get_weather",
+                        input='{"city": "Tok',
+                    ),
+                ],
+            ),
+        ]
+
+        res = await fmt.format(msgs)
+
+        tool_use = [
+            b for b in res[0]["content"] if b.get("type") == "tool_use"
+        ][0]
+        # Repaired to a dict rather than crashing.
+        self.assertIsInstance(tool_use["input"], dict)
+
+    async def test_empty_text_block_is_dropped(self) -> None:
+        """Empty ``TextBlock`` must be skipped, not forwarded.
+
+        Anthropic rejects ``{"type": "text", "text": ""}`` with a 400
+        ("text blocks must be non-empty"). Empty text blocks arise in
+        practice after a tool-call-only assistant turn whose streamed text
+        block is empty. The formatter must drop them rather than emit them.
+        """
+        fmt = AnthropicChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    TextBlock(text=""),
+                    ToolCallBlock(
+                        id="call_1",
+                        name="get_weather",
+                        input='{"city": "Tokyo"}',
+                    ),
+                ],
+            ),
+        ]
+
+        res = await fmt.format(msgs)
+
+        # The empty TextBlock is dropped — the assistant message contains
+        # only the tool_use block, nothing else.
+        self.assertListEqual(
+            [
+                {
+                    "role": "assistant",
+                    "content": [
+                        {
+                            "type": "tool_use",
+                            "id": "call_1",
+                            "name": "get_weather",
+                            "input": {"city": "Tokyo"},
+                        },
+                    ],
+                },
+            ],
+            res,
+        )
+
+    async def test_empty_tool_result_text_is_dropped(self) -> None:
+        """Empty text inside a tool result is skipped too.
+
+        A ``ToolResultBlock`` whose only output is an empty TextBlock must
+        not produce an empty text content entry, which Anthropic would
+        reject. The formatter falls back to a non-empty placeholder so the
+        tool_result content list stays valid.
+        """
+        fmt = AnthropicChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ToolCallBlock(
+                        id="call_1",
+                        name="get_weather",
+                        input='{"city": "Tokyo"}',
+                    ),
+                ],
+            ),
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ToolResultBlock(
+                        id="call_1",
+                        name="get_weather",
+                        output=[TextBlock(text="")],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                ],
+            ),
+        ]
+
+        res = await fmt.format(msgs)
+
+        self.assertListEqual(
+            [
+                {
+                    "role": "assistant",
+                    "content": [
+                        {
+                            "type": "tool_use",
+                            "id": "call_1",
+                            "name": "get_weather",
+                            "input": {"city": "Tokyo"},
+                        },
+                    ],
+                },
+                {
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "tool_result",
+                            "tool_use_id": "call_1",
+                            "content": [
+                                {
+                                    "type": "text",
+                                    "text": "(empty tool output)",
+                                },
+                            ],
+                        },
+                    ],
+                },
+            ],
+            res,
+        )
+
+    async def test_empty_string_tool_output_uses_placeholder(self) -> None:
+        """An empty-string tool output becomes a placeholder text block.
+
+        Anthropic rejects both empty text blocks and a tool_result whose
+        content list is empty, so a wholly-empty output must be replaced
+        with a non-empty placeholder.
+        """
+        fmt = AnthropicChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ToolCallBlock(
+                        id="call_1",
+                        name="noop",
+                        input="{}",
+                    ),
+                ],
+            ),
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ToolResultBlock(
+                        id="call_1",
+                        name="noop",
+                        output="",
+                        state=ToolResultState.SUCCESS,
+                    ),
+                ],
+            ),
+        ]
+
+        res = await fmt.format(msgs)
+
+        self.assertListEqual(
+            [
+                {
+                    "role": "assistant",
+                    "content": [
+                        {
+                            "type": "tool_use",
+                            "id": "call_1",
+                            "name": "noop",
+                            "input": {},
+                        },
+                    ],
+                },
+                {
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "tool_result",
+                            "tool_use_id": "call_1",
+                            "content": [
+                                {
+                                    "type": "text",
+                                    "text": "(empty tool output)",
+                                },
+                            ],
+                        },
+                    ],
+                },
+            ],
+            res,
+        )
diff --git a/tests/formatter_dashscope_test.py b/tests/formatter_dashscope_test.py
new file mode 100644
index 0000000..8d64914
--- /dev/null
+++ b/tests/formatter_dashscope_test.py
@@ -0,0 +1,1035 @@
+# -*- coding: utf-8 -*-
+"""Comprehensive formatter unit tests for DashScopeChatFormatter and
+DashScopeMultiAgentFormatter, following the reference test style with exact
+ground-truth comparisons.
+"""
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import patch
+
+from agentscope.formatter import (
+    DashScopeChatFormatter,
+    DashScopeMultiAgentFormatter,
+)
+from agentscope.message import (
+    UserMsg,
+    AssistantMsg,
+    SystemMsg,
+    TextBlock,
+    DataBlock,
+    ToolCallBlock,
+    ToolResultBlock,
+    ToolResultState,
+    Base64Source,
+    URLSource,
+    ThinkingBlock,
+    HintBlock,
+)
+
+
+# A fixed short-uuid used to make promote-to-multimodal tests deterministic.
+_FIXED_ID = "TESTID1234567"
+
+
+class TestDashScopeFormatter(IsolatedAsyncioTestCase):
+    """Comprehensive tests for DashScope Chat and MultiAgent formatters."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up shared message fixtures and expected ground-truth dicts."""
+        # --- URL strings ---
+        # Normalise through URLSource so that pydantic URL normalisation is
+        # applied consistently to both input and expected values.
+        _img_src = URLSource(
+            url="https://example.com/image.png",
+            media_type="image/png",
+        )
+        _aud_src = URLSource(
+            url="https://example.com/audio.mp3",
+            media_type="audio/mpeg",
+        )
+        self.image_url = str(_img_src.url)
+        self.audio_url = str(_aud_src.url)
+
+        # --- Base64 fixtures ---
+        self.image_b64 = "ZmFrZSBpbWFnZSBkYXRh"
+        self.image_data_uri = f"data:image/png;base64,{self.image_b64}"
+
+        # ---------------------------------------------------------------
+        # Message fixtures
+        # ---------------------------------------------------------------
+        self.msgs_system = [
+            SystemMsg(
+                name="system",
+                content="You're a helpful assistant.",
+            ),
+        ]
+
+        self.msgs_conversation = [
+            UserMsg(
+                name="user",
+                content=[
+                    TextBlock(text="What is the capital of France?"),
+                    DataBlock(
+                        source=URLSource(
+                            url=self.image_url,
+                            media_type="image/png",
+                        ),
+                    ),
+                ],
+            ),
+            AssistantMsg(
+                name="assistant",
+                content="The capital of France is Paris.",
+            ),
+            UserMsg(
+                name="user",
+                content=[
+                    TextBlock(text="What is the capital of Germany?"),
+                    DataBlock(
+                        source=URLSource(
+                            url=self.audio_url,
+                            media_type="audio/mpeg",
+                        ),
+                    ),
+                ],
+            ),
+            AssistantMsg(
+                name="assistant",
+                content="The capital of Germany is Berlin.",
+            ),
+            UserMsg(
+                name="user",
+                content="What is the capital of Japan?",
+            ),
+        ]
+
+        # Messages with ToolResultBlock must use role="assistant" because the
+        # system-role validator rejects non-text blocks.
+        self.msgs_tools = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ToolCallBlock(
+                        id="call_1",
+                        name="get_capital",
+                        input='{"country": "Japan"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_1",
+                        name="get_capital",
+                        output=[
+                            TextBlock(text="The capital of Japan is Tokyo."),
+                        ],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    TextBlock(text="The capital of Japan is Tokyo."),
+                ],
+            ),
+        ]
+
+        # ---------------------------------------------------------------
+        # Ground truth: DashScopeChatFormatter (OpenAI-compatible format)
+        #   - Content blocks use {"type": "text", "text": ...} format.
+        #   - Images use {"type": "image_url", "image_url": {"url": ...}}.
+        #   - Audio uses {"type": "input_audio", "input_audio": {...}}.
+        #   - Tool-result content is a plain string.
+        # ---------------------------------------------------------------
+        self.gt_chat = [
+            {
+                "role": "system",
+                "content": [
+                    {"type": "text", "text": "You're a helpful assistant."},
+                ],
+            },
+            {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "text",
+                        "text": "What is the capital of France?",
+                    },
+                    {
+                        "type": "image_url",
+                        "image_url": {"url": self.image_url},
+                    },
+                ],
+            },
+            {
+                "role": "assistant",
+                "content": [
+                    {
+                        "type": "text",
+                        "text": "The capital of France is Paris.",
+                    },
+                ],
+            },
+            {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "text",
+                        "text": "What is the capital of Germany?",
+                    },
+                    {
+                        "type": "input_audio",
+                        "input_audio": {
+                            "data": self.audio_url,
+                            "format": "mpeg",
+                        },
+                    },
+                ],
+            },
+            {
+                "role": "assistant",
+                "content": [
+                    {
+                        "type": "text",
+                        "text": "The capital of Germany is Berlin.",
+                    },
+                ],
+            },
+            {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "text",
+                        "text": "What is the capital of Japan?",
+                    },
+                ],
+            },
+            {
+                "role": "assistant",
+                "content": None,
+                "tool_calls": [
+                    {
+                        "id": "call_1",
+                        "type": "function",
+                        "function": {
+                            "name": "get_capital",
+                            "arguments": '{"country": "Japan"}',
+                        },
+                    },
+                ],
+            },
+            {
+                "role": "tool",
+                "tool_call_id": "call_1",
+                "content": "The capital of Japan is Tokyo.",
+                "name": "get_capital",
+            },
+            {
+                "role": "assistant",
+                "content": [
+                    {
+                        "type": "text",
+                        "text": "The capital of Japan is Tokyo.",
+                    },
+                ],
+            },
+        ]
+
+        # ---------------------------------------------------------------
+        # Ground truth: DashScopeMultiAgentFormatter
+        #   - System content is a plain string (via get_text_content()).
+        #   - Conversation history is collapsed into a single user message.
+        # ---------------------------------------------------------------
+        _hist_prompt = (
+            DashScopeMultiAgentFormatter().conversation_history_prompt
+        )
+
+        self._gt_trailing_asst = {
+            "role": "assistant",
+            "content": [
+                {
+                    "type": "text",
+                    "text": "The capital of Japan is Tokyo.",
+                },
+            ],
+        }
+
+        self._gt_tool_call = {
+            "role": "assistant",
+            "content": None,
+            "tool_calls": [
+                {
+                    "id": "call_1",
+                    "type": "function",
+                    "function": {
+                        "name": "get_capital",
+                        "arguments": '{"country": "Japan"}',
+                    },
+                },
+            ],
+        }
+        self._gt_tool_result = {
+            "role": "tool",
+            "tool_call_id": "call_1",
+            "content": "The capital of Japan is Tokyo.",
+            "name": "get_capital",
+        }
+
+        self.gt_multiagent = [
+            {
+                "role": "system",
+                "content": "You're a helpful assistant.",
+            },
+            {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "text",
+                        "text": (
+                            _hist_prompt + "<history>\n"
+                            "user: What is the capital of France?\n"
+                            "assistant: The capital of France is Paris.\n"
+                            "user: What is the capital of Germany?\n"
+                            "assistant: The capital of Germany is Berlin.\n"
+                            "user: What is the capital of Japan?\n"
+                            "</history>"
+                        ),
+                    },
+                    {
+                        "type": "image_url",
+                        "image_url": {"url": self.image_url},
+                    },
+                    {
+                        "type": "input_audio",
+                        "input_audio": {
+                            "data": self.audio_url,
+                            "format": "mpeg",
+                        },
+                    },
+                ],
+            },
+            self._gt_tool_call,
+            self._gt_tool_result,
+            self._gt_trailing_asst,
+        ]
+
+    # -------------------------------------------------------------------
+    # DashScopeChatFormatter tests
+    # -------------------------------------------------------------------
+
+    async def test_chat_formatter(self) -> None:
+        """Chat formatter produces exact output for various subsets."""
+        fmt = DashScopeChatFormatter()
+
+        # Full history
+        res = await fmt.format(
+            [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+        )
+        self.assertListEqual(self.gt_chat, res)
+
+        # Without system
+        res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])
+        self.assertListEqual(self.gt_chat[1:], res)
+
+        # Without conversation
+        n_tools_gt = len(self.gt_chat) - 1 - len(self.msgs_conversation)
+        res = await fmt.format([*self.msgs_system, *self.msgs_tools])
+        self.assertListEqual(
+            [self.gt_chat[0]] + self.gt_chat[-n_tools_gt:],
+            res,
+        )
+
+        # Without tools
+        res = await fmt.format([*self.msgs_system, *self.msgs_conversation])
+        self.assertListEqual(self.gt_chat[:-n_tools_gt], res)
+
+        # Empty
+        res = await fmt.format([])
+        self.assertListEqual([], res)
+
+    async def test_chat_formatter_base64_image(self) -> None:
+        """Base64-encoded image is inlined as a data URI."""
+        fmt = DashScopeChatFormatter()
+        msgs = [
+            UserMsg(
+                name="user",
+                content=[
+                    TextBlock(text="What's in this image?"),
+                    DataBlock(
+                        source=Base64Source(
+                            data=self.image_b64,
+                            media_type="image/png",
+                        ),
+                    ),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "user",
+                    "content": [
+                        {"type": "text", "text": "What's in this image?"},
+                        {
+                            "type": "image_url",
+                            "image_url": {"url": self.image_data_uri},
+                        },
+                    ],
+                },
+            ],
+            res,
+        )
+
+    @patch(
+        "agentscope.formatter._formatter_base.shortuuid.uuid",
+        return_value=_FIXED_ID,
+    )
+    async def test_chat_formatter_url_image_in_tool_result(
+        self,
+        _mock_uuid: object,
+    ) -> None:
+        """URL images in tool results are promoted to a follow-up user message.
+
+        The textual part of the tool result contains a system-reminder with a
+        unique identifier; the identifier is mocked to be deterministic.
+        """
+        fmt = DashScopeChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ToolCallBlock(
+                        id="call_img",
+                        name="get_map",
+                        input='{"city": "Tokyo"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_img",
+                        name="get_map",
+                        output=[
+                            TextBlock(text="Here is the map."),
+                            DataBlock(
+                                source=URLSource(
+                                    url=self.image_url,
+                                    media_type="image/png",
+                                ),
+                            ),
+                        ],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    TextBlock(text="Here is the map of Tokyo."),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+
+        expected_tool_content = (
+            "Here is the map.\n"
+            f"<system-reminder>A(n) image file is returned "
+            f"and will be presented to you with the identifier "
+            f"[{_FIXED_ID}].</system-reminder>"
+        )
+        self.assertListEqual(
+            [
+                {
+                    "role": "assistant",
+                    "content": None,
+                    "tool_calls": [
+                        {
+                            "id": "call_img",
+                            "type": "function",
+                            "function": {
+                                "name": "get_map",
+                                "arguments": '{"city": "Tokyo"}',
+                            },
+                        },
+                    ],
+                },
+                {
+                    "role": "tool",
+                    "tool_call_id": "call_img",
+                    "content": expected_tool_content,
+                    "name": "get_map",
+                },
+                {
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": (
+                                "<system-reminder>The multimodal data "
+                                "and their identifiers are listed as "
+                                "follows:"
+                            ),
+                        },
+                        {
+                            "type": "text",
+                            "text": f"- {_FIXED_ID} (image file): ",
+                        },
+                        {
+                            "type": "image_url",
+                            "image_url": {"url": self.image_url},
+                        },
+                        {
+                            "type": "text",
+                            "text": "</system-reminder>",
+                        },
+                    ],
+                },
+                {
+                    "role": "assistant",
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": "Here is the map of Tokyo.",
+                        },
+                    ],
+                },
+            ],
+            res,
+        )
+
+    async def test_chat_formatter_thinking_dropped_without_flag(self) -> None:
+        """ThinkingBlock is silently dropped when application/x-thinking is
+        absent from input_types."""
+        fmt = DashScopeChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ThinkingBlock(thinking="inner thoughts"),
+                    TextBlock(text="reply"),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "assistant",
+                    "content": [{"type": "text", "text": "reply"}],
+                },
+            ],
+            res,
+        )
+
+    async def test_chat_formatter_thinking_becomes_reasoning_content(
+        self,
+    ) -> None:
+        """ThinkingBlock becomes reasoning_content when application/x-thinking
+        is in input_types."""
+        fmt = DashScopeChatFormatter(
+            input_types=["text/plain", "application/x-thinking"],
+        )
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ThinkingBlock(thinking="inner thoughts"),
+                    TextBlock(text="reply"),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "assistant",
+                    "content": [{"type": "text", "text": "reply"}],
+                    "reasoning_content": "inner thoughts",
+                },
+            ],
+            res,
+        )
+
+    async def test_chat_formatter_multiple_thinking_blocks_joined(
+        self,
+    ) -> None:
+        """Multiple ThinkingBlocks are joined with a newline into a single
+        reasoning_content field."""
+        fmt = DashScopeChatFormatter(
+            input_types=["text/plain", "application/x-thinking"],
+        )
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ThinkingBlock(thinking="part one"),
+                    ThinkingBlock(thinking="part two"),
+                    TextBlock(text="answer"),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "assistant",
+                    "content": [{"type": "text", "text": "answer"}],
+                    "reasoning_content": "part one\npart two",
+                },
+            ],
+            res,
+        )
+
+    # -------------------------------------------------------------------
+    # DashScopeMultiAgentFormatter tests
+    # -------------------------------------------------------------------
+
+    async def test_multiagent_formatter(self) -> None:
+        """MultiAgent formatter produces exact output for various subsets."""
+        fmt = DashScopeMultiAgentFormatter()
+
+        # Full history
+        res = await fmt.format(
+            [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+        )
+        self.assertListEqual(self.gt_multiagent, res)
+
+        # Without system
+        res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])
+        self.assertListEqual(self.gt_multiagent[1:], res)
+
+        # Without tools
+        res = await fmt.format([*self.msgs_system, *self.msgs_conversation])
+        self.assertListEqual(self.gt_multiagent[:2], res)
+
+        # System only
+        res = await fmt.format(self.msgs_system)
+        self.assertListEqual([self.gt_multiagent[0]], res)
+
+        # Conversation only
+        res = await fmt.format(self.msgs_conversation)
+        self.assertListEqual([self.gt_multiagent[1]], res)
+
+        # Tools only — no prior agent_message group, so the trailing assistant
+        # is formatted with is_first=True (includes the full history prompt).
+        res = await fmt.format(self.msgs_tools)
+        self.assertListEqual(
+            [
+                self._gt_tool_call,
+                self._gt_tool_result,
+                self._gt_trailing_asst,
+            ],
+            res,
+        )
+
+        # System + tools (no conversation)
+        res = await fmt.format([*self.msgs_system, *self.msgs_tools])
+        self.assertListEqual(
+            [
+                self.gt_multiagent[0],
+                self._gt_tool_call,
+                self._gt_tool_result,
+                self._gt_trailing_asst,
+            ],
+            res,
+        )
+
+        # Empty
+        res = await fmt.format([])
+        self.assertListEqual([], res)
+
+    async def test_multiagent_formatter_thinking_in_tool_sequence(
+        self,
+    ) -> None:
+        """ThinkingBlocks inside a tool sequence are forwarded as
+        reasoning_content when application/x-thinking is in input_types."""
+        fmt = DashScopeMultiAgentFormatter(
+            input_types=["text/plain", "application/x-thinking"],
+        )
+        tc = ToolCallBlock(
+            id="call_1",
+            name="get_capital",
+            input='{"country": "Japan"}',
+        )
+        tr = ToolResultBlock(
+            id="call_1",
+            name="get_capital",
+            output=[TextBlock(text="Tokyo")],
+            state=ToolResultState.SUCCESS,
+        )
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[ThinkingBlock(thinking="Need to check"), tc, tr],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        asst_msgs = [m for m in res if m.get("role") == "assistant"]
+        self.assertListEqual(
+            [m["reasoning_content"] for m in asst_msgs],
+            ["Need to check"],
+        )
+
+    async def test_chat_formatter_complex_multi_step(self) -> None:
+        """Complex multi-step sequence with interleaved thinking, text,
+        tool calls, and tool results (thinking dropped without flag)."""
+        fmt = DashScopeChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ThinkingBlock(thinking="thinking_1"),
+                    TextBlock(text="text_1"),
+                    ToolCallBlock(
+                        id="call_1",
+                        name="func_1",
+                        input='{"arg": "value1"}',
+                    ),
+                    ToolCallBlock(
+                        id="call_2",
+                        name="func_2",
+                        input='{"arg": "value2"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_1",
+                        name="func_1",
+                        output=[TextBlock(text="result_1")],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    ToolResultBlock(
+                        id="call_2",
+                        name="func_2",
+                        output=[TextBlock(text="result_2")],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    ThinkingBlock(thinking="thinking_2"),
+                    TextBlock(text="text_2"),
+                    ToolCallBlock(
+                        id="call_3",
+                        name="func_3",
+                        input='{"arg": "value3"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_3",
+                        name="func_3",
+                        output=[TextBlock(text="result_3")],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    ToolCallBlock(
+                        id="call_4",
+                        name="func_4",
+                        input='{"arg": "value4"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_4",
+                        name="func_4",
+                        output=[TextBlock(text="result_4")],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    ThinkingBlock(thinking="thinking_3"),
+                    TextBlock(text="text_3"),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "assistant",
+                    "content": [{"type": "text", "text": "text_1"}],
+                    "tool_calls": [
+                        {
+                            "id": "call_1",
+                            "type": "function",
+                            "function": {
+                                "name": "func_1",
+                                "arguments": '{"arg": "value1"}',
+                            },
+                        },
+                        {
+                            "id": "call_2",
+                            "type": "function",
+                            "function": {
+                                "name": "func_2",
+                                "arguments": '{"arg": "value2"}',
+                            },
+                        },
+                    ],
+                },
+                {
+                    "role": "tool",
+                    "tool_call_id": "call_1",
+                    "content": "result_1",
+                    "name": "func_1",
+                },
+                {
+                    "role": "tool",
+                    "tool_call_id": "call_2",
+                    "content": "result_2",
+                    "name": "func_2",
+                },
+                {
+                    "role": "assistant",
+                    "content": [{"type": "text", "text": "text_2"}],
+                    "tool_calls": [
+                        {
+                            "id": "call_3",
+                            "type": "function",
+                            "function": {
+                                "name": "func_3",
+                                "arguments": '{"arg": "value3"}',
+                            },
+                        },
+                    ],
+                },
+                {
+                    "role": "tool",
+                    "tool_call_id": "call_3",
+                    "content": "result_3",
+                    "name": "func_3",
+                },
+                {
+                    "role": "assistant",
+                    "content": None,
+                    "tool_calls": [
+                        {
+                            "id": "call_4",
+                            "type": "function",
+                            "function": {
+                                "name": "func_4",
+                                "arguments": '{"arg": "value4"}',
+                            },
+                        },
+                    ],
+                },
+                {
+                    "role": "tool",
+                    "tool_call_id": "call_4",
+                    "content": "result_4",
+                    "name": "func_4",
+                },
+                {
+                    "role": "assistant",
+                    "content": [{"type": "text", "text": "text_3"}],
+                },
+            ],
+            res,
+        )
+
+    async def test_chat_formatter_complex_multi_step_with_thinking(
+        self,
+    ) -> None:
+        """Complex multi-step sequence with thinking preserved via
+        application/x-thinking flag."""
+        fmt = DashScopeChatFormatter(
+            input_types=["text/plain", "application/x-thinking"],
+        )
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ThinkingBlock(thinking="thinking_1"),
+                    TextBlock(text="text_1"),
+                    ToolCallBlock(
+                        id="call_1",
+                        name="func_1",
+                        input='{"arg": "value1"}',
+                    ),
+                    ToolCallBlock(
+                        id="call_2",
+                        name="func_2",
+                        input='{"arg": "value2"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_1",
+                        name="func_1",
+                        output=[TextBlock(text="result_1")],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    ToolResultBlock(
+                        id="call_2",
+                        name="func_2",
+                        output=[TextBlock(text="result_2")],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    ThinkingBlock(thinking="thinking_2"),
+                    TextBlock(text="text_2"),
+                    ToolCallBlock(
+                        id="call_3",
+                        name="func_3",
+                        input='{"arg": "value3"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_3",
+                        name="func_3",
+                        output=[TextBlock(text="result_3")],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    ToolCallBlock(
+                        id="call_4",
+                        name="func_4",
+                        input='{"arg": "value4"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_4",
+                        name="func_4",
+                        output=[TextBlock(text="result_4")],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    ThinkingBlock(thinking="thinking_3"),
+                    TextBlock(text="text_3"),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "assistant",
+                    "content": [{"type": "text", "text": "text_1"}],
+                    "tool_calls": [
+                        {
+                            "id": "call_1",
+                            "type": "function",
+                            "function": {
+                                "name": "func_1",
+                                "arguments": '{"arg": "value1"}',
+                            },
+                        },
+                        {
+                            "id": "call_2",
+                            "type": "function",
+                            "function": {
+                                "name": "func_2",
+                                "arguments": '{"arg": "value2"}',
+                            },
+                        },
+                    ],
+                    "reasoning_content": "thinking_1",
+                },
+                {
+                    "role": "tool",
+                    "tool_call_id": "call_1",
+                    "content": "result_1",
+                    "name": "func_1",
+                },
+                {
+                    "role": "tool",
+                    "tool_call_id": "call_2",
+                    "content": "result_2",
+                    "name": "func_2",
+                },
+                {
+                    "role": "assistant",
+                    "content": [{"type": "text", "text": "text_2"}],
+                    "tool_calls": [
+                        {
+                            "id": "call_3",
+                            "type": "function",
+                            "function": {
+                                "name": "func_3",
+                                "arguments": '{"arg": "value3"}',
+                            },
+                        },
+                    ],
+                    "reasoning_content": "thinking_2",
+                },
+                {
+                    "role": "tool",
+                    "tool_call_id": "call_3",
+                    "content": "result_3",
+                    "name": "func_3",
+                },
+                {
+                    "role": "assistant",
+                    "content": None,
+                    "tool_calls": [
+                        {
+                            "id": "call_4",
+                            "type": "function",
+                            "function": {
+                                "name": "func_4",
+                                "arguments": '{"arg": "value4"}',
+                            },
+                        },
+                    ],
+                },
+                {
+                    "role": "tool",
+                    "tool_call_id": "call_4",
+                    "content": "result_4",
+                    "name": "func_4",
+                },
+                {
+                    "role": "assistant",
+                    "content": [{"type": "text", "text": "text_3"}],
+                    "reasoning_content": "thinking_3",
+                },
+            ],
+            res,
+        )
+
+    async def test_chat_formatter_hint_block(self) -> None:
+        """HintBlock flushes preceding content and becomes a user message."""
+        fmt = DashScopeChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    TextBlock(text="Let me think about that."),
+                    HintBlock(hint="Remember to be concise."),
+                    TextBlock(text="Here is my answer."),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "assistant",
+                    "content": [
+                        {"type": "text", "text": "Let me think about that."},
+                    ],
+                },
+                {
+                    "role": "user",
+                    "content": [
+                        {"type": "text", "text": "Remember to be concise."},
+                    ],
+                },
+                {
+                    "role": "assistant",
+                    "content": [
+                        {"type": "text", "text": "Here is my answer."},
+                    ],
+                },
+            ],
+            res,
+        )
+
+    async def test_chat_formatter_hint_block_multimodal(self) -> None:
+        """Multimodal HintBlock becomes a single user message with text
+        + image."""
+        fmt = DashScopeChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    HintBlock(
+                        hint=[
+                            TextBlock(text="Inspect this screenshot:"),
+                            DataBlock(
+                                source=Base64Source(
+                                    data=self.image_b64,
+                                    media_type="image/png",
+                                ),
+                            ),
+                        ],
+                    ),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": "Inspect this screenshot:",
+                        },
+                        {
+                            "type": "image_url",
+                            "image_url": {"url": self.image_data_uri},
+                        },
+                    ],
+                },
+            ],
+            res,
+        )
diff --git a/tests/formatter_deepseek_test.py b/tests/formatter_deepseek_test.py
new file mode 100644
index 0000000..c9b7e6c
--- /dev/null
+++ b/tests/formatter_deepseek_test.py
@@ -0,0 +1,532 @@
+# -*- coding: utf-8 -*-
+"""Comprehensive formatter unit tests for DeepSeekChatFormatter and
+DeepSeekMultiAgentFormatter, with exact ground-truth comparisons.
+"""
+from unittest import IsolatedAsyncioTestCase
+
+from agentscope.formatter import (
+    DeepSeekChatFormatter,
+    DeepSeekMultiAgentFormatter,
+)
+from agentscope.message import (
+    UserMsg,
+    AssistantMsg,
+    SystemMsg,
+    TextBlock,
+    DataBlock,
+    Base64Source,
+    ToolCallBlock,
+    ToolResultBlock,
+    ToolResultState,
+    ThinkingBlock,
+    HintBlock,
+)
+
+
+class TestDeepSeekFormatter(IsolatedAsyncioTestCase):
+    """Comprehensive tests for DeepSeek Chat and MultiAgent formatters."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up shared fixtures and ground-truth dicts."""
+        _hist_prompt = (
+            DeepSeekMultiAgentFormatter().conversation_history_prompt
+        )
+
+        self.msgs_system = [
+            SystemMsg(
+                name="system",
+                content="You're a helpful assistant.",
+            ),
+        ]
+        self.msgs_conversation = [
+            UserMsg(
+                name="user",
+                content="What is the capital of France?",
+            ),
+            AssistantMsg(
+                name="assistant",
+                content="The capital of France is Paris.",
+            ),
+            UserMsg(
+                name="user",
+                content="What is the capital of Germany?",
+            ),
+            AssistantMsg(
+                name="assistant",
+                content="The capital of Germany is Berlin.",
+            ),
+            UserMsg(
+                name="user",
+                content="What is the capital of Japan?",
+            ),
+        ]
+        self.msgs_tools = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ToolCallBlock(
+                        id="call_1",
+                        name="get_capital",
+                        input='{"country": "Japan"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_1",
+                        name="get_capital",
+                        output=[
+                            TextBlock(text="The capital of Japan is Tokyo."),
+                        ],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    TextBlock(text="The capital of Japan is Tokyo."),
+                ],
+            ),
+        ]
+
+        # --- Chat formatter ground truth ---
+        # DeepSeek content is a plain string (not a list of blocks).
+        # All assistant messages include `reasoning_content` (empty string if
+        # no ThinkingBlock).
+        self.gt_chat = [
+            {"role": "system", "content": "You're a helpful assistant."},
+            {"role": "user", "content": "What is the capital of France?"},
+            {
+                "role": "assistant",
+                "content": "The capital of France is Paris.",
+                "reasoning_content": "",
+            },
+            {"role": "user", "content": "What is the capital of Germany?"},
+            {
+                "role": "assistant",
+                "content": "The capital of Germany is Berlin.",
+                "reasoning_content": "",
+            },
+            {"role": "user", "content": "What is the capital of Japan?"},
+            {
+                "role": "assistant",
+                "content": None,
+                "reasoning_content": "",
+                "tool_calls": [
+                    {
+                        "id": "call_1",
+                        "type": "function",
+                        "function": {
+                            "name": "get_capital",
+                            "arguments": '{"country": "Japan"}',
+                        },
+                    },
+                ],
+            },
+            {
+                "role": "tool",
+                "tool_call_id": "call_1",
+                "content": "The capital of Japan is Tokyo.",
+                "name": "get_capital",
+            },
+            {
+                "role": "assistant",
+                "content": "The capital of Japan is Tokyo.",
+                "reasoning_content": "",
+            },
+        ]
+
+        # --- MultiAgent formatter ground truth ---
+        # System content is a plain string.
+        # History is a plain string (not a list) with <history> tags.
+        # The trailing assistant message (is_first=False) is wrapped in a
+        # minimal <history> block without the full prompt prefix.
+        self._gt_trailing_asst = {
+            "role": "assistant",
+            "content": "The capital of Japan is Tokyo.",
+            "reasoning_content": "",
+        }
+        self._gt_tool_call = {
+            "role": "assistant",
+            "content": None,
+            "reasoning_content": "",
+            "tool_calls": [
+                {
+                    "id": "call_1",
+                    "type": "function",
+                    "function": {
+                        "name": "get_capital",
+                        "arguments": '{"country": "Japan"}',
+                    },
+                },
+            ],
+        }
+        self._gt_tool_result = {
+            "role": "tool",
+            "tool_call_id": "call_1",
+            "content": "The capital of Japan is Tokyo.",
+            "name": "get_capital",
+        }
+
+        self.gt_multiagent = [
+            {"role": "system", "content": "You're a helpful assistant."},
+            {
+                "role": "user",
+                "content": (
+                    _hist_prompt + "<history>\n"
+                    "user: What is the capital of France?\n"
+                    "assistant: The capital of France is Paris.\n"
+                    "user: What is the capital of Germany?\n"
+                    "assistant: The capital of Germany is Berlin.\n"
+                    "user: What is the capital of Japan?\n"
+                    "</history>"
+                ),
+            },
+            self._gt_tool_call,
+            self._gt_tool_result,
+            self._gt_trailing_asst,
+        ]
+
+    # ------------------------------------------------------------------
+    # DeepSeekChatFormatter tests
+    # ------------------------------------------------------------------
+
+    async def test_chat_formatter(self) -> None:
+        """Chat formatter produces exact output for various subsets."""
+        fmt = DeepSeekChatFormatter()
+
+        # Full history
+        res = await fmt.format(
+            [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+        )
+        self.assertListEqual(self.gt_chat, res)
+
+        # Without system
+        res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])
+        self.assertListEqual(self.gt_chat[1:], res)
+
+        # Without conversation
+        n_tools_gt = len(self.gt_chat) - 1 - len(self.msgs_conversation)
+        res = await fmt.format([*self.msgs_system, *self.msgs_tools])
+        self.assertListEqual(
+            [self.gt_chat[0]] + self.gt_chat[-n_tools_gt:],
+            res,
+        )
+
+        # Without tools
+        res = await fmt.format([*self.msgs_system, *self.msgs_conversation])
+        self.assertListEqual(self.gt_chat[:-n_tools_gt], res)
+
+        # Empty
+        self.assertListEqual([], await fmt.format([]))
+
+    async def test_chat_formatter_reasoning_content_always_present(
+        self,
+    ) -> None:
+        """Every assistant message always has a reasoning_content field."""
+        fmt = DeepSeekChatFormatter()
+        msgs = [AssistantMsg(name="assistant", content="Answer")]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "assistant",
+                    "content": "Answer",
+                    "reasoning_content": "",
+                },
+            ],
+            res,
+        )
+
+    async def test_chat_formatter_thinking_block(self) -> None:
+        """ThinkingBlock is placed into reasoning_content."""
+        fmt = DeepSeekChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ThinkingBlock(thinking="Let me think..."),
+                    TextBlock(text="Answer"),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "assistant",
+                    "content": "Answer",
+                    "reasoning_content": "Let me think...",
+                },
+            ],
+            res,
+        )
+
+    # ------------------------------------------------------------------
+    # DeepSeekMultiAgentFormatter tests
+    # ------------------------------------------------------------------
+
+    async def test_multiagent_formatter(self) -> None:
+        """MultiAgent formatter produces exact output for various subsets."""
+        fmt = DeepSeekMultiAgentFormatter()
+
+        # Full
+        res = await fmt.format(
+            [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+        )
+        self.assertListEqual(self.gt_multiagent, res)
+
+        # Without system
+        res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])
+        self.assertListEqual(self.gt_multiagent[1:], res)
+
+        # Without tools
+        res = await fmt.format([*self.msgs_system, *self.msgs_conversation])
+        self.assertListEqual(self.gt_multiagent[:2], res)
+
+        # System only
+        res = await fmt.format(self.msgs_system)
+        self.assertListEqual([self.gt_multiagent[0]], res)
+
+        # Conversation only
+        res = await fmt.format(self.msgs_conversation)
+        self.assertListEqual([self.gt_multiagent[1]], res)
+
+        # Tools only
+        res = await fmt.format(self.msgs_tools)
+        self.assertListEqual(
+            [
+                self._gt_tool_call,
+                self._gt_tool_result,
+                self._gt_trailing_asst,
+            ],
+            res,
+        )
+
+        # System + tools
+        res = await fmt.format([*self.msgs_system, *self.msgs_tools])
+        self.assertListEqual(
+            [
+                self.gt_multiagent[0],
+                self._gt_tool_call,
+                self._gt_tool_result,
+                self._gt_trailing_asst,
+            ],
+            res,
+        )
+
+        # Empty
+        self.assertListEqual([], await fmt.format([]))
+
+    async def test_chat_formatter_complex_multi_step(self) -> None:
+        """Complex multi-step sequence with interleaved thinking, text,
+        tool calls, and tool results."""
+        fmt = DeepSeekChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ThinkingBlock(thinking="thinking_1"),
+                    TextBlock(text="text_1"),
+                    ToolCallBlock(
+                        id="call_1",
+                        name="func_1",
+                        input='{"arg": "value1"}',
+                    ),
+                    ToolCallBlock(
+                        id="call_2",
+                        name="func_2",
+                        input='{"arg": "value2"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_1",
+                        name="func_1",
+                        output=[TextBlock(text="result_1")],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    ToolResultBlock(
+                        id="call_2",
+                        name="func_2",
+                        output=[TextBlock(text="result_2")],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    ThinkingBlock(thinking="thinking_2"),
+                    TextBlock(text="text_2"),
+                    ToolCallBlock(
+                        id="call_3",
+                        name="func_3",
+                        input='{"arg": "value3"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_3",
+                        name="func_3",
+                        output=[TextBlock(text="result_3")],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    ToolCallBlock(
+                        id="call_4",
+                        name="func_4",
+                        input='{"arg": "value4"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_4",
+                        name="func_4",
+                        output=[TextBlock(text="result_4")],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    ThinkingBlock(thinking="thinking_3"),
+                    TextBlock(text="text_3"),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "assistant",
+                    "content": "text_1",
+                    "reasoning_content": "thinking_1",
+                    "tool_calls": [
+                        {
+                            "id": "call_1",
+                            "type": "function",
+                            "function": {
+                                "name": "func_1",
+                                "arguments": '{"arg": "value1"}',
+                            },
+                        },
+                        {
+                            "id": "call_2",
+                            "type": "function",
+                            "function": {
+                                "name": "func_2",
+                                "arguments": '{"arg": "value2"}',
+                            },
+                        },
+                    ],
+                },
+                {
+                    "role": "tool",
+                    "tool_call_id": "call_1",
+                    "content": "result_1",
+                    "name": "func_1",
+                },
+                {
+                    "role": "tool",
+                    "tool_call_id": "call_2",
+                    "content": "result_2",
+                    "name": "func_2",
+                },
+                {
+                    "role": "assistant",
+                    "content": "text_2",
+                    "reasoning_content": "thinking_2",
+                    "tool_calls": [
+                        {
+                            "id": "call_3",
+                            "type": "function",
+                            "function": {
+                                "name": "func_3",
+                                "arguments": '{"arg": "value3"}',
+                            },
+                        },
+                    ],
+                },
+                {
+                    "role": "tool",
+                    "tool_call_id": "call_3",
+                    "content": "result_3",
+                    "name": "func_3",
+                },
+                {
+                    "role": "assistant",
+                    "content": None,
+                    "reasoning_content": "",
+                    "tool_calls": [
+                        {
+                            "id": "call_4",
+                            "type": "function",
+                            "function": {
+                                "name": "func_4",
+                                "arguments": '{"arg": "value4"}',
+                            },
+                        },
+                    ],
+                },
+                {
+                    "role": "tool",
+                    "tool_call_id": "call_4",
+                    "content": "result_4",
+                    "name": "func_4",
+                },
+                {
+                    "role": "assistant",
+                    "content": "text_3",
+                    "reasoning_content": "thinking_3",
+                },
+            ],
+            res,
+        )
+
+    async def test_chat_formatter_hint_block(self) -> None:
+        """HintBlock flushes preceding content and becomes a user message."""
+        fmt = DeepSeekChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    TextBlock(text="Let me think about that."),
+                    HintBlock(hint="Remember to be concise."),
+                    TextBlock(text="Here is my answer."),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "assistant",
+                    "content": "Let me think about that.",
+                    "reasoning_content": "",
+                },
+                {
+                    "role": "user",
+                    "content": "Remember to be concise.",
+                },
+                {
+                    "role": "assistant",
+                    "content": "Here is my answer.",
+                    "reasoning_content": "",
+                },
+            ],
+            res,
+        )
+
+    async def test_chat_formatter_hint_block_multimodal(self) -> None:
+        """DeepSeek is text-only — DataBlock degrades to a placeholder
+        string."""
+        fmt = DeepSeekChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    HintBlock(
+                        hint=[
+                            TextBlock(text="Inspect this screenshot:"),
+                            DataBlock(
+                                source=Base64Source(
+                                    data="ZmFrZSBpbWFnZSBkYXRh",
+                                    media_type="image/png",
+                                ),
+                            ),
+                        ],
+                    ),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "user",
+                    "content": (
+                        "Inspect this screenshot:\n"
+                        "[image/png attached, not supported by this provider]"
+                    ),
+                },
+            ],
+            res,
+        )
diff --git a/tests/formatter_gemini_test.py b/tests/formatter_gemini_test.py
new file mode 100644
index 0000000..21cd23d
--- /dev/null
+++ b/tests/formatter_gemini_test.py
@@ -0,0 +1,782 @@
+# -*- coding: utf-8 -*-
+"""Comprehensive formatter unit tests for GeminiChatFormatter and
+GeminiMultiAgentFormatter, following the reference test style with exact
+ground-truth comparisons.
+"""
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import patch
+
+from agentscope.formatter import (
+    GeminiChatFormatter,
+    GeminiMultiAgentFormatter,
+)
+from agentscope.message import (
+    UserMsg,
+    AssistantMsg,
+    SystemMsg,
+    TextBlock,
+    DataBlock,
+    ToolCallBlock,
+    ToolResultBlock,
+    ToolResultState,
+    Base64Source,
+    ThinkingBlock,
+    HintBlock,
+)
+
+
+_FIXED_ID = "TESTID1234567"
+
+
+class TestGeminiFormatter(IsolatedAsyncioTestCase):
+    """Comprehensive tests for Gemini Chat and MultiAgent formatters."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up shared message fixtures and expected ground-truth dicts."""
+        self.image_b64 = "ZmFrZSBpbWFnZSBkYXRh"
+
+        # ---------------------------------------------------------------
+        # Message fixtures
+        # (Use base64 images: Gemini URL handling downloads from the network)
+        # ---------------------------------------------------------------
+        self.msgs_system = [
+            SystemMsg(
+                name="system",
+                content="You're a helpful assistant.",
+            ),
+        ]
+
+        self.msgs_conversation = [
+            UserMsg(
+                name="user",
+                content=[
+                    TextBlock(text="What is the capital of France?"),
+                    DataBlock(
+                        source=Base64Source(
+                            data=self.image_b64,
+                            media_type="image/png",
+                        ),
+                    ),
+                ],
+            ),
+            AssistantMsg(
+                name="assistant",
+                content="The capital of France is Paris.",
+            ),
+            UserMsg(
+                name="user",
+                content="What is the capital of Germany?",
+            ),
+            AssistantMsg(
+                name="assistant",
+                content="The capital of Germany is Berlin.",
+            ),
+            UserMsg(
+                name="user",
+                content="What is the capital of Japan?",
+            ),
+        ]
+
+        self.msgs_tools = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ToolCallBlock(
+                        id="call_1",
+                        name="get_capital",
+                        input='{"country": "Japan"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_1",
+                        name="get_capital",
+                        output=[
+                            TextBlock(text="The capital of Japan is Tokyo."),
+                        ],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    TextBlock(text="The capital of Japan is Tokyo."),
+                ],
+            ),
+        ]
+
+        _inline_img = {
+            "inline_data": {"data": self.image_b64, "mime_type": "image/png"},
+        }
+
+        # ---------------------------------------------------------------
+        # Ground truth: GeminiChatFormatter
+        #   - System message becomes role="user" (no special system role).
+        #   - Assistant messages become role="model".
+        #   - Content is in "parts" (not "content") as a list of dicts.
+        #   - ToolCallBlock becomes "function_call" part.
+        #   - ToolResultBlock becomes a separate role="user" message with
+        #     "function_response" part.
+        # ---------------------------------------------------------------
+        self.gt_chat = [
+            {
+                "role": "user",
+                "parts": [{"text": "You're a helpful assistant."}],
+            },
+            {
+                "role": "user",
+                "parts": [
+                    {"text": "What is the capital of France?"},
+                    _inline_img,
+                ],
+            },
+            {
+                "role": "model",
+                "parts": [{"text": "The capital of France is Paris."}],
+            },
+            {
+                "role": "user",
+                "parts": [{"text": "What is the capital of Germany?"}],
+            },
+            {
+                "role": "model",
+                "parts": [{"text": "The capital of Germany is Berlin."}],
+            },
+            {
+                "role": "user",
+                "parts": [{"text": "What is the capital of Japan?"}],
+            },
+            {
+                "role": "model",
+                "parts": [
+                    {
+                        "function_call": {
+                            "id": "call_1",
+                            "name": "get_capital",
+                            "args": {"country": "Japan"},
+                        },
+                    },
+                ],
+            },
+            {
+                "role": "user",
+                "parts": [
+                    {
+                        "function_response": {
+                            "id": "call_1",
+                            "name": "get_capital",
+                            "response": {
+                                "output": "The capital of Japan is Tokyo.",
+                            },
+                        },
+                    },
+                ],
+            },
+            {
+                "role": "model",
+                "parts": [{"text": "The capital of Japan is Tokyo."}],
+            },
+        ]
+
+        # ---------------------------------------------------------------
+        # Ground truth: GeminiMultiAgentFormatter
+        #   - System message: role="user" (same as chat formatter).
+        #   - Agent messages: collapsed into role="user" with parts list.
+        #   - Media blocks interleaved (text flushed before each DataBlock).
+        #   - is_first=False still wraps with <history> (no hist_prompt
+        #     prefix).
+        # ---------------------------------------------------------------
+        _hist_prompt = GeminiMultiAgentFormatter().conversation_history_prompt
+
+        self._gt_trailing_asst = {
+            "role": "model",
+            "parts": [
+                {"text": "The capital of Japan is Tokyo."},
+            ],
+        }
+
+        self._gt_tool_call = {
+            "role": "model",
+            "parts": [
+                {
+                    "function_call": {
+                        "id": "call_1",
+                        "name": "get_capital",
+                        "args": {"country": "Japan"},
+                    },
+                },
+            ],
+        }
+        self._gt_tool_result = {
+            "role": "user",
+            "parts": [
+                {
+                    "function_response": {
+                        "id": "call_1",
+                        "name": "get_capital",
+                        "response": {
+                            "output": "The capital of Japan is Tokyo.",
+                        },
+                    },
+                },
+            ],
+        }
+
+        self.gt_multiagent = [
+            {
+                "role": "user",
+                "parts": [{"text": "You're a helpful assistant."}],
+            },
+            {
+                "role": "user",
+                "parts": [
+                    {
+                        "text": (
+                            _hist_prompt + "<history>\n"
+                            "user: What is the capital of France?"
+                        ),
+                    },
+                    _inline_img,
+                    {
+                        "text": (
+                            "assistant: The capital of France is Paris.\n"
+                            "user: What is the capital of Germany?\n"
+                            "assistant: The capital of Germany is Berlin.\n"
+                            "user: What is the capital of Japan?\n"
+                            "</history>"
+                        ),
+                    },
+                ],
+            },
+            self._gt_tool_call,
+            self._gt_tool_result,
+            self._gt_trailing_asst,
+        ]
+
+    # -------------------------------------------------------------------
+    # GeminiChatFormatter tests
+    # -------------------------------------------------------------------
+
+    async def test_chat_formatter(self) -> None:
+        """Chat formatter produces exact output for various subsets."""
+        fmt = GeminiChatFormatter()
+
+        # Full history
+        res = await fmt.format(
+            [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+        )
+        self.assertListEqual(self.gt_chat, res)
+
+        # Without system
+        res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])
+        self.assertListEqual(self.gt_chat[1:], res)
+
+        # Without conversation
+        n_tools_gt = len(self.gt_chat) - 1 - len(self.msgs_conversation)
+        res = await fmt.format([*self.msgs_system, *self.msgs_tools])
+        self.assertListEqual(
+            [self.gt_chat[0]] + self.gt_chat[-n_tools_gt:],
+            res,
+        )
+
+        # Without tools
+        res = await fmt.format([*self.msgs_system, *self.msgs_conversation])
+        self.assertListEqual(self.gt_chat[:-n_tools_gt], res)
+
+        # Empty
+        res = await fmt.format([])
+        self.assertListEqual([], res)
+
+    async def test_chat_formatter_thinking_preserved(self) -> None:
+        """ThinkingBlock becomes a part with thought=True in Gemini format."""
+        fmt = GeminiChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ThinkingBlock(thinking="inner thoughts"),
+                    TextBlock(text="reply"),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "model",
+                    "parts": [
+                        {"thought": True, "text": "inner thoughts"},
+                        {"text": "reply"},
+                    ],
+                },
+            ],
+            res,
+        )
+
+    async def test_empty_thinking_block_is_dropped(self) -> None:
+        """An empty ``ThinkingBlock`` must be skipped, not forwarded.
+
+        Gemini rejects a thought part whose text is empty with a 400
+        ("contents.parts must not be empty"). Empty thinking blocks occur
+        when a reasoning model returns no summary, so the formatter must
+        drop them rather than emit ``{"thought": True, "text": ""}``.
+        """
+        fmt = GeminiChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ThinkingBlock(thinking=""),
+                    TextBlock(text="reply"),
+                ],
+            ),
+        ]
+
+        res = await fmt.format(msgs)
+
+        # Only the text part remains — no empty thought part.
+        self.assertEqual(len(res), 1)
+        self.assertEqual(res[0]["role"], "model")
+        thought_parts = [
+            p for p in res[0]["parts"] if p.get("thought") is True
+        ]
+        self.assertEqual(thought_parts, [])
+        self.assertEqual(res[0]["parts"], [{"text": "reply"}])
+
+    @patch(
+        "agentscope.formatter._formatter_base.shortuuid.uuid",
+        return_value=_FIXED_ID,
+    )
+    async def test_chat_formatter_base64_image_in_tool_result(
+        self,
+        _mock_uuid: object,
+    ) -> None:
+        """Base64 images in tool results are promoted to a follow-up user
+        message."""
+        fmt = GeminiChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ToolCallBlock(
+                        id="call_img",
+                        name="get_map",
+                        input='{"city": "Tokyo"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_img",
+                        name="get_map",
+                        output=[
+                            TextBlock(text="Here is the map."),
+                            DataBlock(
+                                source=Base64Source(
+                                    data=self.image_b64,
+                                    media_type="image/png",
+                                ),
+                            ),
+                        ],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    TextBlock(text="Here is the map of Tokyo."),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+
+        expected_tool_output = (
+            "Here is the map.\n"
+            f"<system-reminder>A(n) image file is returned "
+            f"and will be presented to you with the identifier "
+            f"[{_FIXED_ID}].</system-reminder>"
+        )
+        self.assertListEqual(
+            [
+                {
+                    "role": "model",
+                    "parts": [
+                        {
+                            "function_call": {
+                                "id": "call_img",
+                                "name": "get_map",
+                                "args": {"city": "Tokyo"},
+                            },
+                        },
+                    ],
+                },
+                {
+                    "role": "user",
+                    "parts": [
+                        {
+                            "function_response": {
+                                "id": "call_img",
+                                "name": "get_map",
+                                "response": {"output": expected_tool_output},
+                            },
+                        },
+                    ],
+                },
+                {
+                    "role": "user",
+                    "parts": [
+                        {
+                            "text": (
+                                "<system-reminder>The multimodal data "
+                                "and their identifiers are listed as "
+                                "follows:"
+                            ),
+                        },
+                        {
+                            "text": f"- {_FIXED_ID} (image file): ",
+                        },
+                        {
+                            "inline_data": {
+                                "data": self.image_b64,
+                                "mime_type": "image/png",
+                            },
+                        },
+                        {"text": "</system-reminder>"},
+                    ],
+                },
+                {
+                    "role": "model",
+                    "parts": [
+                        {"text": "Here is the map of Tokyo."},
+                    ],
+                },
+            ],
+            res,
+        )
+
+    # -------------------------------------------------------------------
+    # GeminiMultiAgentFormatter tests
+    # -------------------------------------------------------------------
+
+    async def test_multiagent_formatter(self) -> None:
+        """MultiAgent formatter produces exact output for various subsets."""
+        fmt = GeminiMultiAgentFormatter()
+
+        # Full history
+        res = await fmt.format(
+            [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+        )
+        self.assertListEqual(self.gt_multiagent, res)
+
+        # Without system
+        res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])
+        self.assertListEqual(self.gt_multiagent[1:], res)
+
+        # Without tools
+        res = await fmt.format([*self.msgs_system, *self.msgs_conversation])
+        self.assertListEqual(self.gt_multiagent[:2], res)
+
+        # System only
+        res = await fmt.format(self.msgs_system)
+        self.assertListEqual([self.gt_multiagent[0]], res)
+
+        # Conversation only
+        res = await fmt.format(self.msgs_conversation)
+        self.assertListEqual([self.gt_multiagent[1]], res)
+
+        # Tools only
+        res = await fmt.format(self.msgs_tools)
+        self.assertListEqual(
+            [
+                self._gt_tool_call,
+                self._gt_tool_result,
+                self._gt_trailing_asst,
+            ],
+            res,
+        )
+
+        # System + tools
+        res = await fmt.format([*self.msgs_system, *self.msgs_tools])
+        self.assertListEqual(
+            [
+                self.gt_multiagent[0],
+                self._gt_tool_call,
+                self._gt_tool_result,
+                self._gt_trailing_asst,
+            ],
+            res,
+        )
+
+        # Empty
+        res = await fmt.format([])
+        self.assertListEqual([], res)
+
+    async def test_chat_formatter_complex_multi_step(self) -> None:
+        """Complex multi-step sequence with interleaved thinking, text,
+        tool calls, and tool results."""
+        fmt = GeminiChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ThinkingBlock(thinking="thinking_1"),
+                    TextBlock(text="text_1"),
+                    ToolCallBlock(
+                        id="call_1",
+                        name="func_1",
+                        input='{"arg": "value1"}',
+                    ),
+                    ToolCallBlock(
+                        id="call_2",
+                        name="func_2",
+                        input='{"arg": "value2"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_1",
+                        name="func_1",
+                        output=[TextBlock(text="result_1")],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    ToolResultBlock(
+                        id="call_2",
+                        name="func_2",
+                        output=[TextBlock(text="result_2")],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    ThinkingBlock(thinking="thinking_2"),
+                    TextBlock(text="text_2"),
+                    ToolCallBlock(
+                        id="call_3",
+                        name="func_3",
+                        input='{"arg": "value3"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_3",
+                        name="func_3",
+                        output=[TextBlock(text="result_3")],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    ToolCallBlock(
+                        id="call_4",
+                        name="func_4",
+                        input='{"arg": "value4"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_4",
+                        name="func_4",
+                        output=[TextBlock(text="result_4")],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    ThinkingBlock(thinking="thinking_3"),
+                    TextBlock(text="text_3"),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "model",
+                    "parts": [
+                        {"thought": True, "text": "thinking_1"},
+                        {"text": "text_1"},
+                        {
+                            "function_call": {
+                                "id": "call_1",
+                                "name": "func_1",
+                                "args": {"arg": "value1"},
+                            },
+                        },
+                        {
+                            "function_call": {
+                                "id": "call_2",
+                                "name": "func_2",
+                                "args": {"arg": "value2"},
+                            },
+                        },
+                    ],
+                },
+                {
+                    "role": "user",
+                    "parts": [
+                        {
+                            "function_response": {
+                                "id": "call_1",
+                                "name": "func_1",
+                                "response": {"output": "result_1"},
+                            },
+                        },
+                    ],
+                },
+                {
+                    "role": "user",
+                    "parts": [
+                        {
+                            "function_response": {
+                                "id": "call_2",
+                                "name": "func_2",
+                                "response": {"output": "result_2"},
+                            },
+                        },
+                    ],
+                },
+                {
+                    "role": "model",
+                    "parts": [
+                        {"thought": True, "text": "thinking_2"},
+                        {"text": "text_2"},
+                        {
+                            "function_call": {
+                                "id": "call_3",
+                                "name": "func_3",
+                                "args": {"arg": "value3"},
+                            },
+                        },
+                    ],
+                },
+                {
+                    "role": "user",
+                    "parts": [
+                        {
+                            "function_response": {
+                                "id": "call_3",
+                                "name": "func_3",
+                                "response": {"output": "result_3"},
+                            },
+                        },
+                    ],
+                },
+                {
+                    "role": "model",
+                    "parts": [
+                        {
+                            "function_call": {
+                                "id": "call_4",
+                                "name": "func_4",
+                                "args": {"arg": "value4"},
+                            },
+                        },
+                    ],
+                },
+                {
+                    "role": "user",
+                    "parts": [
+                        {
+                            "function_response": {
+                                "id": "call_4",
+                                "name": "func_4",
+                                "response": {"output": "result_4"},
+                            },
+                        },
+                    ],
+                },
+                {
+                    "role": "model",
+                    "parts": [
+                        {"thought": True, "text": "thinking_3"},
+                        {"text": "text_3"},
+                    ],
+                },
+            ],
+            res,
+        )
+
+    async def test_chat_formatter_hint_block(self) -> None:
+        """HintBlock flushes preceding content and becomes a user message."""
+        fmt = GeminiChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    TextBlock(text="Let me think about that."),
+                    HintBlock(hint="Remember to be concise."),
+                    TextBlock(text="Here is my answer."),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "model",
+                    "parts": [
+                        {"text": "Let me think about that."},
+                    ],
+                },
+                {
+                    "role": "user",
+                    "parts": [
+                        {"text": "Remember to be concise."},
+                    ],
+                },
+                {
+                    "role": "model",
+                    "parts": [
+                        {"text": "Here is my answer."},
+                    ],
+                },
+            ],
+            res,
+        )
+
+    async def test_chat_formatter_hint_block_multimodal(self) -> None:
+        """Multimodal HintBlock becomes a single user message with text +
+        image."""
+        fmt = GeminiChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    HintBlock(
+                        hint=[
+                            TextBlock(text="Inspect this screenshot:"),
+                            DataBlock(
+                                source=Base64Source(
+                                    data=self.image_b64,
+                                    media_type="image/png",
+                                ),
+                            ),
+                        ],
+                    ),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "user",
+                    "parts": [
+                        {"text": "Inspect this screenshot:"},
+                        {
+                            "inline_data": {
+                                "data": self.image_b64,
+                                "mime_type": "image/png",
+                            },
+                        },
+                    ],
+                },
+            ],
+            res,
+        )
+
+    async def test_tool_call_with_incomplete_input_does_not_crash(
+        self,
+    ) -> None:
+        """A truncated ``block.input`` must not crash the formatter.
+
+        Context compression or interrupted streaming can leave a
+        ``ToolCallBlock.input`` as an incomplete JSON fragment. The
+        formatter must repair it into a dict instead of raising
+        ``JSONDecodeError``.
+        """
+        fmt = GeminiChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ToolCallBlock(
+                        id="call_1",
+                        name="get_weather",
+                        input='{"city": "Tok',
+                    ),
+                ],
+            ),
+        ]
+
+        res = await fmt.format(msgs)
+
+        function_call = [
+            part
+            for m in res
+            for part in m.get("parts", [])
+            if "function_call" in part
+        ][0]["function_call"]
+        self.assertIsInstance(function_call["args"], dict)
diff --git a/tests/formatter_moonshot_test.py b/tests/formatter_moonshot_test.py
new file mode 100644
index 0000000..2e36803
--- /dev/null
+++ b/tests/formatter_moonshot_test.py
@@ -0,0 +1,826 @@
+# -*- coding: utf-8 -*-
+"""Comprehensive formatter unit tests for MoonshotChatFormatter and
+MoonshotMultiAgentFormatter, following the reference test style with exact
+ground-truth comparisons.
+"""
+import base64
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import patch, MagicMock
+
+from agentscope.formatter import (
+    MoonshotChatFormatter,
+    MoonshotMultiAgentFormatter,
+)
+from agentscope.message import (
+    UserMsg,
+    AssistantMsg,
+    SystemMsg,
+    TextBlock,
+    DataBlock,
+    ToolCallBlock,
+    ToolResultBlock,
+    ToolResultState,
+    Base64Source,
+    URLSource,
+    ThinkingBlock,
+    HintBlock,
+)
+
+
+_FIXED_ID = "TESTID1234567"
+
+
+class TestMoonshotFormatter(IsolatedAsyncioTestCase):
+    """Comprehensive tests for Moonshot Chat and MultiAgent formatters."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up shared message fixtures and expected ground-truth dicts."""
+        _img_src = URLSource(
+            url="https://example.com/image.png",
+            media_type="image/png",
+        )
+        self.image_url = str(_img_src.url)
+
+        # The Moonshot formatter downloads remote image URLs and inlines
+        # them as base64 data URIs (the Moonshot vision API rejects raw
+        # HTTPS URLs). Patch `requests.get` so tests don't hit the network
+        # and produce a deterministic payload that matches `image_b64`.
+        self.image_b64 = "ZmFrZSBpbWFnZSBkYXRh"
+        self.image_bytes = base64.b64decode(self.image_b64)
+        self.image_data_uri = f"data:image/png;base64,{self.image_b64}"
+
+        mock_response = MagicMock()
+        mock_response.content = self.image_bytes
+        mock_response.raise_for_status = MagicMock()
+        self._requests_get_patcher = patch(
+            "agentscope.formatter._moonshot_formatter.requests.get",
+            return_value=mock_response,
+        )
+        self._requests_get_patcher.start()
+        self.addCleanup(self._requests_get_patcher.stop)
+
+        # ---------------------------------------------------------------
+        # Message fixtures (no audio to avoid downloads)
+        # ---------------------------------------------------------------
+        self.msgs_system = [
+            SystemMsg(
+                name="system",
+                content="You're a helpful assistant.",
+            ),
+        ]
+
+        self.msgs_conversation = [
+            UserMsg(
+                name="user",
+                content=[
+                    TextBlock(text="What is the capital of France?"),
+                    DataBlock(
+                        source=URLSource(
+                            url=self.image_url,
+                            media_type="image/png",
+                        ),
+                    ),
+                ],
+            ),
+            AssistantMsg(
+                name="assistant",
+                content="The capital of France is Paris.",
+            ),
+            UserMsg(
+                name="user",
+                content="What is the capital of Germany?",
+            ),
+            AssistantMsg(
+                name="assistant",
+                content="The capital of Germany is Berlin.",
+            ),
+            UserMsg(
+                name="user",
+                content="What is the capital of Japan?",
+            ),
+        ]
+
+        self.msgs_tools = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ToolCallBlock(
+                        id="call_1",
+                        name="get_capital",
+                        input='{"country": "Japan"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_1",
+                        name="get_capital",
+                        output=[
+                            TextBlock(text="The capital of Japan is Tokyo."),
+                        ],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    TextBlock(text="The capital of Japan is Tokyo."),
+                ],
+            ),
+        ]
+
+        # ---------------------------------------------------------------
+        # Ground truth: MoonshotChatFormatter
+        #   - Same as OpenAI except ALL assistant messages have an extra
+        #     "reasoning_content" field (empty string when no ThinkingBlock).
+        # ---------------------------------------------------------------
+        self.gt_chat = [
+            {
+                "role": "system",
+                "name": "system",
+                "content": [
+                    {"type": "text", "text": "You're a helpful assistant."},
+                ],
+            },
+            {
+                "role": "user",
+                "name": "user",
+                "content": [
+                    {"type": "text", "text": "What is the capital of France?"},
+                    {
+                        "type": "image_url",
+                        "image_url": {"url": self.image_data_uri},
+                    },
+                ],
+            },
+            {
+                "role": "assistant",
+                "name": "assistant",
+                "content": [
+                    {
+                        "type": "text",
+                        "text": "The capital of France is Paris.",
+                    },
+                ],
+                "reasoning_content": "",
+            },
+            {
+                "role": "user",
+                "name": "user",
+                "content": [
+                    {
+                        "type": "text",
+                        "text": "What is the capital of Germany?",
+                    },
+                ],
+            },
+            {
+                "role": "assistant",
+                "name": "assistant",
+                "content": [
+                    {
+                        "type": "text",
+                        "text": "The capital of Germany is Berlin.",
+                    },
+                ],
+                "reasoning_content": "",
+            },
+            {
+                "role": "user",
+                "name": "user",
+                "content": [
+                    {"type": "text", "text": "What is the capital of Japan?"},
+                ],
+            },
+            {
+                "role": "assistant",
+                "name": "assistant",
+                "content": None,
+                "reasoning_content": "",
+                "tool_calls": [
+                    {
+                        "id": "call_1",
+                        "type": "function",
+                        "function": {
+                            "name": "get_capital",
+                            "arguments": '{"country": "Japan"}',
+                        },
+                    },
+                ],
+            },
+            {
+                "role": "tool",
+                "tool_call_id": "call_1",
+                "content": "The capital of Japan is Tokyo.",
+                "name": "get_capital",
+            },
+            {
+                "role": "assistant",
+                "name": "assistant",
+                "content": [
+                    {"type": "text", "text": "The capital of Japan is Tokyo."},
+                ],
+                "reasoning_content": "",
+            },
+        ]
+
+        # ---------------------------------------------------------------
+        # Ground truth: MoonshotMultiAgentFormatter
+        #   - Same as OpenAI MultiAgent, but tool-sequence assistant messages
+        #     carry "reasoning_content": "".
+        # ---------------------------------------------------------------
+        _hist_prompt = (
+            MoonshotMultiAgentFormatter().conversation_history_prompt
+        )
+
+        _conv_text = (
+            "user: What is the capital of France?\n"
+            "assistant: The capital of France is Paris.\n"
+            "user: What is the capital of Germany?\n"
+            "assistant: The capital of Germany is Berlin.\n"
+            "user: What is the capital of Japan?"
+        )
+
+        self._gt_trailing_asst = {
+            "role": "assistant",
+            "name": "assistant",
+            "content": [
+                {
+                    "type": "text",
+                    "text": "The capital of Japan is Tokyo.",
+                },
+            ],
+            "reasoning_content": "",
+        }
+
+        self._gt_tool_call = {
+            "role": "assistant",
+            "name": "assistant",
+            "content": None,
+            "reasoning_content": "",
+            "tool_calls": [
+                {
+                    "id": "call_1",
+                    "type": "function",
+                    "function": {
+                        "name": "get_capital",
+                        "arguments": '{"country": "Japan"}',
+                    },
+                },
+            ],
+        }
+        self._gt_tool_result = {
+            "role": "tool",
+            "tool_call_id": "call_1",
+            "content": "The capital of Japan is Tokyo.",
+            "name": "get_capital",
+        }
+
+        self.gt_multiagent = [
+            {
+                "role": "system",
+                "content": "You're a helpful assistant.",
+            },
+            {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "text",
+                        "text": (
+                            _hist_prompt
+                            + "<history>\n"
+                            + _conv_text
+                            + "\n</history>"
+                        ),
+                    },
+                    {
+                        "type": "image_url",
+                        "image_url": {"url": self.image_data_uri},
+                    },
+                ],
+            },
+            self._gt_tool_call,
+            self._gt_tool_result,
+            self._gt_trailing_asst,
+        ]
+
+    # -------------------------------------------------------------------
+    # MoonshotChatFormatter tests
+    # -------------------------------------------------------------------
+
+    async def test_chat_formatter(self) -> None:
+        """Chat formatter produces exact output for various subsets."""
+        fmt = MoonshotChatFormatter()
+
+        # Full history
+        res = await fmt.format(
+            [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+        )
+        self.assertListEqual(self.gt_chat, res)
+
+        # Without system
+        res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])
+        self.assertListEqual(self.gt_chat[1:], res)
+
+        # Without conversation
+        n_tools_gt = len(self.gt_chat) - 1 - len(self.msgs_conversation)
+        res = await fmt.format([*self.msgs_system, *self.msgs_tools])
+        self.assertListEqual(
+            [self.gt_chat[0]] + self.gt_chat[-n_tools_gt:],
+            res,
+        )
+
+        # Without tools
+        res = await fmt.format([*self.msgs_system, *self.msgs_conversation])
+        self.assertListEqual(self.gt_chat[:-n_tools_gt], res)
+
+        # Empty
+        res = await fmt.format([])
+        self.assertListEqual([], res)
+
+    async def test_chat_formatter_thinking_to_reasoning_content(
+        self,
+    ) -> None:
+        """ThinkingBlock becomes reasoning_content in Moonshot (Preserved
+        Thinking)."""
+        fmt = MoonshotChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ThinkingBlock(thinking="inner thoughts"),
+                    TextBlock(text="reply"),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "assistant",
+                    "name": "assistant",
+                    "content": [{"type": "text", "text": "reply"}],
+                    "reasoning_content": "inner thoughts",
+                },
+            ],
+            res,
+        )
+
+    async def test_chat_formatter_assistant_always_has_reasoning_content(
+        self,
+    ) -> None:
+        """All assistant messages always have reasoning_content (even when
+        empty)."""
+        fmt = MoonshotChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content="Hello!",
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "assistant",
+                    "name": "assistant",
+                    "content": [{"type": "text", "text": "Hello!"}],
+                    "reasoning_content": "",
+                },
+            ],
+            res,
+        )
+
+    async def test_chat_formatter_base64_image(self) -> None:
+        """Base64-encoded image is inlined as a data URI."""
+        fmt = MoonshotChatFormatter()
+        msgs = [
+            UserMsg(
+                name="user",
+                content=[
+                    TextBlock(text="What's in this image?"),
+                    DataBlock(
+                        source=Base64Source(
+                            data=self.image_b64,
+                            media_type="image/png",
+                        ),
+                    ),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "user",
+                    "name": "user",
+                    "content": [
+                        {"type": "text", "text": "What's in this image?"},
+                        {
+                            "type": "image_url",
+                            "image_url": {"url": self.image_data_uri},
+                        },
+                    ],
+                },
+            ],
+            res,
+        )
+
+    @patch(
+        "agentscope.formatter._formatter_base.shortuuid.uuid",
+        return_value=_FIXED_ID,
+    )
+    async def test_chat_formatter_url_image_in_tool_result(
+        self,
+        _mock_uuid: object,
+    ) -> None:
+        """URL images in tool results are promoted to a follow-up user
+        message."""
+        fmt = MoonshotChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ToolCallBlock(
+                        id="call_img",
+                        name="get_map",
+                        input='{"city": "Tokyo"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_img",
+                        name="get_map",
+                        output=[
+                            TextBlock(text="Here is the map."),
+                            DataBlock(
+                                source=URLSource(
+                                    url=self.image_url,
+                                    media_type="image/png",
+                                ),
+                            ),
+                        ],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    TextBlock(text="Here is the map of Tokyo."),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+
+        expected_tool_content = (
+            "Here is the map.\n"
+            f"<system-reminder>A(n) image file is returned "
+            f"and will be presented to you with the identifier "
+            f"[{_FIXED_ID}].</system-reminder>"
+        )
+        self.assertListEqual(
+            [
+                {
+                    "role": "assistant",
+                    "name": "assistant",
+                    "content": None,
+                    "reasoning_content": "",
+                    "tool_calls": [
+                        {
+                            "id": "call_img",
+                            "type": "function",
+                            "function": {
+                                "name": "get_map",
+                                "arguments": '{"city": "Tokyo"}',
+                            },
+                        },
+                    ],
+                },
+                {
+                    "role": "tool",
+                    "tool_call_id": "call_img",
+                    "content": expected_tool_content,
+                    "name": "get_map",
+                },
+                {
+                    "role": "user",
+                    "name": "system-reminder",
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": (
+                                "<system-reminder>The multimodal data "
+                                "and their identifiers are listed as "
+                                "follows:"
+                            ),
+                        },
+                        {
+                            "type": "text",
+                            "text": f"- {_FIXED_ID} (image file): ",
+                        },
+                        {
+                            "type": "image_url",
+                            "image_url": {"url": self.image_data_uri},
+                        },
+                        {
+                            "type": "text",
+                            "text": "</system-reminder>",
+                        },
+                    ],
+                },
+                {
+                    "role": "assistant",
+                    "name": "assistant",
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": "Here is the map of Tokyo.",
+                        },
+                    ],
+                    "reasoning_content": "",
+                },
+            ],
+            res,
+        )
+
+    # -------------------------------------------------------------------
+    # MoonshotMultiAgentFormatter tests
+    # -------------------------------------------------------------------
+
+    async def test_multiagent_formatter(self) -> None:
+        """MultiAgent formatter produces exact output for various subsets."""
+        fmt = MoonshotMultiAgentFormatter()
+
+        # Full history
+        res = await fmt.format(
+            [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+        )
+        self.assertListEqual(self.gt_multiagent, res)
+
+        # Without system
+        res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])
+        self.assertListEqual(self.gt_multiagent[1:], res)
+
+        # Without tools
+        res = await fmt.format([*self.msgs_system, *self.msgs_conversation])
+        self.assertListEqual(self.gt_multiagent[:2], res)
+
+        # System only
+        res = await fmt.format(self.msgs_system)
+        self.assertListEqual([self.gt_multiagent[0]], res)
+
+        # Conversation only
+        res = await fmt.format(self.msgs_conversation)
+        self.assertListEqual([self.gt_multiagent[1]], res)
+
+        # Tools only
+        res = await fmt.format(self.msgs_tools)
+        self.assertListEqual(
+            [
+                self._gt_tool_call,
+                self._gt_tool_result,
+                self._gt_trailing_asst,
+            ],
+            res,
+        )
+
+        # System + tools
+        res = await fmt.format([*self.msgs_system, *self.msgs_tools])
+        self.assertListEqual(
+            [
+                self.gt_multiagent[0],
+                self._gt_tool_call,
+                self._gt_tool_result,
+                self._gt_trailing_asst,
+            ],
+            res,
+        )
+
+        # Empty
+        res = await fmt.format([])
+        self.assertListEqual([], res)
+
+    async def test_chat_formatter_complex_multi_step(self) -> None:
+        """Complex multi-step sequence with interleaved thinking, text,
+        tool calls, and tool results."""
+        fmt = MoonshotChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ThinkingBlock(thinking="thinking_1"),
+                    TextBlock(text="text_1"),
+                    ToolCallBlock(
+                        id="call_1",
+                        name="func_1",
+                        input='{"arg": "value1"}',
+                    ),
+                    ToolCallBlock(
+                        id="call_2",
+                        name="func_2",
+                        input='{"arg": "value2"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_1",
+                        name="func_1",
+                        output=[TextBlock(text="result_1")],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    ToolResultBlock(
+                        id="call_2",
+                        name="func_2",
+                        output=[TextBlock(text="result_2")],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    ThinkingBlock(thinking="thinking_2"),
+                    TextBlock(text="text_2"),
+                    ToolCallBlock(
+                        id="call_3",
+                        name="func_3",
+                        input='{"arg": "value3"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_3",
+                        name="func_3",
+                        output=[TextBlock(text="result_3")],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    ToolCallBlock(
+                        id="call_4",
+                        name="func_4",
+                        input='{"arg": "value4"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_4",
+                        name="func_4",
+                        output=[TextBlock(text="result_4")],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    ThinkingBlock(thinking="thinking_3"),
+                    TextBlock(text="text_3"),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "assistant",
+                    "name": "assistant",
+                    "content": [{"type": "text", "text": "text_1"}],
+                    "reasoning_content": "thinking_1",
+                    "tool_calls": [
+                        {
+                            "id": "call_1",
+                            "type": "function",
+                            "function": {
+                                "name": "func_1",
+                                "arguments": '{"arg": "value1"}',
+                            },
+                        },
+                        {
+                            "id": "call_2",
+                            "type": "function",
+                            "function": {
+                                "name": "func_2",
+                                "arguments": '{"arg": "value2"}',
+                            },
+                        },
+                    ],
+                },
+                {
+                    "role": "tool",
+                    "tool_call_id": "call_1",
+                    "content": "result_1",
+                    "name": "func_1",
+                },
+                {
+                    "role": "tool",
+                    "tool_call_id": "call_2",
+                    "content": "result_2",
+                    "name": "func_2",
+                },
+                {
+                    "role": "assistant",
+                    "name": "assistant",
+                    "content": [{"type": "text", "text": "text_2"}],
+                    "reasoning_content": "thinking_2",
+                    "tool_calls": [
+                        {
+                            "id": "call_3",
+                            "type": "function",
+                            "function": {
+                                "name": "func_3",
+                                "arguments": '{"arg": "value3"}',
+                            },
+                        },
+                    ],
+                },
+                {
+                    "role": "tool",
+                    "tool_call_id": "call_3",
+                    "content": "result_3",
+                    "name": "func_3",
+                },
+                {
+                    "role": "assistant",
+                    "name": "assistant",
+                    "content": None,
+                    "reasoning_content": "",
+                    "tool_calls": [
+                        {
+                            "id": "call_4",
+                            "type": "function",
+                            "function": {
+                                "name": "func_4",
+                                "arguments": '{"arg": "value4"}',
+                            },
+                        },
+                    ],
+                },
+                {
+                    "role": "tool",
+                    "tool_call_id": "call_4",
+                    "content": "result_4",
+                    "name": "func_4",
+                },
+                {
+                    "role": "assistant",
+                    "name": "assistant",
+                    "content": [{"type": "text", "text": "text_3"}],
+                    "reasoning_content": "thinking_3",
+                },
+            ],
+            res,
+        )
+
+    async def test_chat_formatter_hint_block(self) -> None:
+        """HintBlock flushes preceding content and becomes a user message."""
+        fmt = MoonshotChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    TextBlock(text="Let me think about that."),
+                    HintBlock(hint="Remember to be concise."),
+                    TextBlock(text="Here is my answer."),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "assistant",
+                    "name": "assistant",
+                    "content": [
+                        {"type": "text", "text": "Let me think about that."},
+                    ],
+                    "reasoning_content": "",
+                },
+                {
+                    "role": "user",
+                    "content": [
+                        {"type": "text", "text": "Remember to be concise."},
+                    ],
+                },
+                {
+                    "role": "assistant",
+                    "name": "assistant",
+                    "content": [
+                        {"type": "text", "text": "Here is my answer."},
+                    ],
+                    "reasoning_content": "",
+                },
+            ],
+            res,
+        )
+
+    async def test_chat_formatter_hint_block_multimodal(self) -> None:
+        """Multimodal HintBlock becomes a single user message with text +
+        image."""
+        fmt = MoonshotChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    HintBlock(
+                        hint=[
+                            TextBlock(text="Inspect this screenshot:"),
+                            DataBlock(
+                                source=Base64Source(
+                                    data=self.image_b64,
+                                    media_type="image/png",
+                                ),
+                            ),
+                        ],
+                    ),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": "Inspect this screenshot:",
+                        },
+                        {
+                            "type": "image_url",
+                            "image_url": {"url": self.image_data_uri},
+                        },
+                    ],
+                },
+            ],
+            res,
+        )
diff --git a/tests/formatter_ollama_test.py b/tests/formatter_ollama_test.py
new file mode 100644
index 0000000..c354c53
--- /dev/null
+++ b/tests/formatter_ollama_test.py
@@ -0,0 +1,647 @@
+# -*- coding: utf-8 -*-
+"""Comprehensive formatter unit tests for OllamaChatFormatter and
+OllamaMultiAgentFormatter, with exact ground-truth comparisons.
+"""
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import patch
+
+from agentscope.formatter import OllamaChatFormatter, OllamaMultiAgentFormatter
+from agentscope.message import (
+    UserMsg,
+    AssistantMsg,
+    SystemMsg,
+    TextBlock,
+    DataBlock,
+    ToolCallBlock,
+    ToolResultBlock,
+    ToolResultState,
+    Base64Source,
+    ThinkingBlock,
+    HintBlock,
+)
+
+
+_FIXED_ID = "TESTID1234567"
+
+
+class TestOllamaFormatter(IsolatedAsyncioTestCase):
+    """Comprehensive tests for Ollama Chat and MultiAgent formatters."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up shared fixtures and ground-truth dicts."""
+        _hist_prompt = OllamaMultiAgentFormatter().conversation_history_prompt
+
+        # Base64 image fixture
+        self.image_b64 = "ZmFrZSBpbWFnZSBkYXRh"
+
+        self.msgs_system = [
+            SystemMsg(
+                name="system",
+                content="You're a helpful assistant.",
+            ),
+        ]
+        self.msgs_conversation = [
+            UserMsg(
+                name="user",
+                content="What is the capital of France?",
+            ),
+            AssistantMsg(
+                name="assistant",
+                content="The capital of France is Paris.",
+            ),
+            UserMsg(
+                name="user",
+                content="What is the capital of Germany?",
+            ),
+            AssistantMsg(
+                name="assistant",
+                content="The capital of Germany is Berlin.",
+            ),
+            UserMsg(
+                name="user",
+                content="What is the capital of Japan?",
+            ),
+        ]
+        self.msgs_tools = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ToolCallBlock(
+                        id="call_1",
+                        name="get_capital",
+                        input='{"country": "Japan"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_1",
+                        name="get_capital",
+                        output=[
+                            TextBlock(text="The capital of Japan is Tokyo."),
+                        ],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    TextBlock(text="The capital of Japan is Tokyo."),
+                ],
+            ),
+        ]
+
+        # --- Chat formatter ground truth ---
+        # Ollama content is always a plain string.
+        # Tool calls use dict arguments (not JSON string).
+        self.gt_chat = [
+            {"role": "system", "content": "You're a helpful assistant."},
+            {"role": "user", "content": "What is the capital of France?"},
+            {
+                "role": "assistant",
+                "content": "The capital of France is Paris.",
+            },
+            {"role": "user", "content": "What is the capital of Germany?"},
+            {
+                "role": "assistant",
+                "content": "The capital of Germany is Berlin.",
+            },
+            {"role": "user", "content": "What is the capital of Japan?"},
+            {
+                "role": "assistant",
+                "content": "",
+                "tool_calls": [
+                    {
+                        "function": {
+                            "name": "get_capital",
+                            "arguments": {"country": "Japan"},
+                        },
+                    },
+                ],
+            },
+            {
+                "role": "tool",
+                "tool_name": "get_capital",
+                "content": "The capital of Japan is Tokyo.",
+            },
+            {"role": "assistant", "content": "The capital of Japan is Tokyo."},
+        ]
+
+        # --- MultiAgent formatter ground truth ---
+        # System content is a plain string.
+        # History is a plain string with format "name:\ntext" per message.
+        # For is_first=False, there are NO <history> tags (only in
+        # is_first=True).
+        _conv_text = (
+            "user:\nWhat is the capital of France?\n"
+            "assistant:\nThe capital of France is Paris.\n"
+            "user:\nWhat is the capital of Germany?\n"
+            "assistant:\nThe capital of Germany is Berlin.\n"
+            "user:\nWhat is the capital of Japan?"
+        )
+        self._gt_trailing_asst = {
+            "role": "assistant",
+            "content": "The capital of Japan is Tokyo.",
+        }
+        self._gt_tool_call = {
+            "role": "assistant",
+            "content": "",
+            "tool_calls": [
+                {
+                    "function": {
+                        "name": "get_capital",
+                        "arguments": {"country": "Japan"},
+                    },
+                },
+            ],
+        }
+        self._gt_tool_result = {
+            "role": "tool",
+            "tool_name": "get_capital",
+            "content": "The capital of Japan is Tokyo.",
+        }
+
+        self.gt_multiagent = [
+            {"role": "system", "content": "You're a helpful assistant."},
+            {
+                "role": "user",
+                "content": (
+                    _hist_prompt + "<history>\n" + _conv_text + "\n</history>"
+                ),
+            },
+            self._gt_tool_call,
+            self._gt_tool_result,
+            self._gt_trailing_asst,
+        ]
+
+    # ------------------------------------------------------------------
+    # OllamaChatFormatter tests
+    # ------------------------------------------------------------------
+
+    async def test_chat_formatter(self) -> None:
+        """Chat formatter produces exact output for various subsets."""
+        fmt = OllamaChatFormatter()
+
+        # Full history
+        res = await fmt.format(
+            [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+        )
+        self.assertListEqual(self.gt_chat, res)
+
+        # Without system
+        res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])
+        self.assertListEqual(self.gt_chat[1:], res)
+
+        # Without conversation
+        n_tools_gt = len(self.gt_chat) - 1 - len(self.msgs_conversation)
+        res = await fmt.format([*self.msgs_system, *self.msgs_tools])
+        self.assertListEqual(
+            [self.gt_chat[0]] + self.gt_chat[-n_tools_gt:],
+            res,
+        )
+
+        # Without tools
+        res = await fmt.format([*self.msgs_system, *self.msgs_conversation])
+        self.assertListEqual(self.gt_chat[:-n_tools_gt], res)
+
+        # Empty
+        self.assertListEqual([], await fmt.format([]))
+
+    async def test_chat_formatter_tool_call_arguments_are_dict(self) -> None:
+        """Ollama requires tool call arguments as a dict, not a JSON string."""
+        fmt = OllamaChatFormatter()
+        tc = ToolCallBlock(id="c1", name="search", input='{"q": "weather"}')
+        res = await fmt.format(
+            [AssistantMsg(name="assistant", content=[tc])],
+        )
+        self.assertListEqual(
+            [
+                {
+                    "role": "assistant",
+                    "content": "",
+                    "tool_calls": [
+                        {
+                            "function": {
+                                "name": "search",
+                                "arguments": {"q": "weather"},
+                            },
+                        },
+                    ],
+                },
+            ],
+            res,
+        )
+
+    async def test_chat_formatter_base64_image(self) -> None:
+        """Base64 image is placed in the 'images' list as a raw base64
+        string."""
+        fmt = OllamaChatFormatter()
+        msgs = [
+            UserMsg(
+                name="user",
+                content=[
+                    TextBlock(text="What is this?"),
+                    DataBlock(
+                        source=Base64Source(
+                            data=self.image_b64,
+                            media_type="image/png",
+                        ),
+                    ),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "user",
+                    "content": "What is this?",
+                    "images": [self.image_b64],
+                },
+            ],
+            res,
+        )
+
+    @patch(
+        "agentscope.formatter._formatter_base.shortuuid.uuid",
+        return_value=_FIXED_ID,
+    )
+    async def test_chat_formatter_base64_image_in_tool_result(
+        self,
+        _mock_uuid: object,
+    ) -> None:
+        """Base64 images in tool results are promoted to a follow-up user
+        message with images list."""
+        fmt = OllamaChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ToolCallBlock(
+                        id="call_img",
+                        name="get_map",
+                        input='{"city": "Tokyo"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_img",
+                        name="get_map",
+                        output=[
+                            TextBlock(text="Here is the map."),
+                            DataBlock(
+                                source=Base64Source(
+                                    data=self.image_b64,
+                                    media_type="image/png",
+                                ),
+                            ),
+                        ],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    TextBlock(text="Here is the map of Tokyo."),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+
+        expected_tool_content = (
+            "Here is the map.\n"
+            f"<system-reminder>A(n) image file is returned "
+            f"and will be presented to you with the identifier "
+            f"[{_FIXED_ID}].</system-reminder>"
+        )
+        self.assertListEqual(
+            [
+                {
+                    "role": "assistant",
+                    "content": "",
+                    "tool_calls": [
+                        {
+                            "function": {
+                                "name": "get_map",
+                                "arguments": {"city": "Tokyo"},
+                            },
+                        },
+                    ],
+                },
+                {
+                    "role": "tool",
+                    "tool_name": "get_map",
+                    "content": expected_tool_content,
+                },
+                {
+                    "role": "user",
+                    "content": (
+                        "<system-reminder>The multimodal data "
+                        "and their identifiers are listed as follows:\n"
+                        f"- {_FIXED_ID} (image file): \n"
+                        "</system-reminder>"
+                    ),
+                    "images": [self.image_b64],
+                },
+                {
+                    "role": "assistant",
+                    "content": "Here is the map of Tokyo.",
+                },
+            ],
+            res,
+        )
+
+    # ------------------------------------------------------------------
+    # OllamaMultiAgentFormatter tests
+    # ------------------------------------------------------------------
+
+    async def test_multiagent_formatter(self) -> None:
+        """MultiAgent formatter produces exact output for various subsets."""
+        fmt = OllamaMultiAgentFormatter()
+
+        # Full
+        res = await fmt.format(
+            [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+        )
+        self.assertListEqual(self.gt_multiagent, res)
+
+        # Without system
+        res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])
+        self.assertListEqual(self.gt_multiagent[1:], res)
+
+        # Without tools
+        res = await fmt.format([*self.msgs_system, *self.msgs_conversation])
+        self.assertListEqual(self.gt_multiagent[:2], res)
+
+        # System only
+        res = await fmt.format(self.msgs_system)
+        self.assertListEqual([self.gt_multiagent[0]], res)
+
+        # Conversation only
+        res = await fmt.format(self.msgs_conversation)
+        self.assertListEqual([self.gt_multiagent[1]], res)
+
+        # Tools only
+        res = await fmt.format(self.msgs_tools)
+        self.assertListEqual(
+            [
+                self._gt_tool_call,
+                self._gt_tool_result,
+                self._gt_trailing_asst,
+            ],
+            res,
+        )
+
+        # System + tools
+        res = await fmt.format([*self.msgs_system, *self.msgs_tools])
+        self.assertListEqual(
+            [
+                self.gt_multiagent[0],
+                self._gt_tool_call,
+                self._gt_tool_result,
+                self._gt_trailing_asst,
+            ],
+            res,
+        )
+
+        # Empty
+        self.assertListEqual([], await fmt.format([]))
+
+    async def test_chat_formatter_complex_multi_step(self) -> None:
+        """Complex multi-step sequence with interleaved thinking, text,
+        tool calls, and tool results."""
+        fmt = OllamaChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ThinkingBlock(thinking="thinking_1"),
+                    TextBlock(text="text_1"),
+                    ToolCallBlock(
+                        id="call_1",
+                        name="func_1",
+                        input='{"arg": "value1"}',
+                    ),
+                    ToolCallBlock(
+                        id="call_2",
+                        name="func_2",
+                        input='{"arg": "value2"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_1",
+                        name="func_1",
+                        output=[TextBlock(text="result_1")],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    ToolResultBlock(
+                        id="call_2",
+                        name="func_2",
+                        output=[TextBlock(text="result_2")],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    ThinkingBlock(thinking="thinking_2"),
+                    TextBlock(text="text_2"),
+                    ToolCallBlock(
+                        id="call_3",
+                        name="func_3",
+                        input='{"arg": "value3"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_3",
+                        name="func_3",
+                        output=[TextBlock(text="result_3")],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    ToolCallBlock(
+                        id="call_4",
+                        name="func_4",
+                        input='{"arg": "value4"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_4",
+                        name="func_4",
+                        output=[TextBlock(text="result_4")],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    ThinkingBlock(thinking="thinking_3"),
+                    TextBlock(text="text_3"),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "assistant",
+                    "content": "text_1",
+                    "tool_calls": [
+                        {
+                            "function": {
+                                "name": "func_1",
+                                "arguments": {"arg": "value1"},
+                            },
+                        },
+                    ],
+                },
+                {
+                    "role": "assistant",
+                    "content": "",
+                    "tool_calls": [
+                        {
+                            "function": {
+                                "name": "func_2",
+                                "arguments": {"arg": "value2"},
+                            },
+                        },
+                    ],
+                },
+                {"role": "tool", "tool_name": "func_1", "content": "result_1"},
+                {"role": "tool", "tool_name": "func_2", "content": "result_2"},
+                {
+                    "role": "assistant",
+                    "content": "text_2",
+                    "tool_calls": [
+                        {
+                            "function": {
+                                "name": "func_3",
+                                "arguments": {"arg": "value3"},
+                            },
+                        },
+                    ],
+                },
+                {"role": "tool", "tool_name": "func_3", "content": "result_3"},
+                {
+                    "role": "assistant",
+                    "content": "",
+                    "tool_calls": [
+                        {
+                            "function": {
+                                "name": "func_4",
+                                "arguments": {"arg": "value4"},
+                            },
+                        },
+                    ],
+                },
+                {"role": "tool", "tool_name": "func_4", "content": "result_4"},
+                {"role": "assistant", "content": "text_3"},
+            ],
+            res,
+        )
+
+    async def test_chat_formatter_hint_block(self) -> None:
+        """HintBlock flushes preceding content and becomes a user message."""
+        fmt = OllamaChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    TextBlock(text="Let me think about that."),
+                    HintBlock(hint="Remember to be concise."),
+                    TextBlock(text="Here is my answer."),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "assistant",
+                    "content": "Let me think about that.",
+                },
+                {
+                    "role": "user",
+                    "content": "Remember to be concise.",
+                },
+                {
+                    "role": "assistant",
+                    "content": "Here is my answer.",
+                },
+            ],
+            res,
+        )
+
+    async def test_chat_formatter_hint_block_multimodal(self) -> None:
+        """Multimodal HintBlock becomes one user message with text + images
+        list."""
+        fmt = OllamaChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    HintBlock(
+                        hint=[
+                            TextBlock(text="Inspect this screenshot:"),
+                            DataBlock(
+                                source=Base64Source(
+                                    data=self.image_b64,
+                                    media_type="image/png",
+                                ),
+                            ),
+                        ],
+                    ),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "user",
+                    "content": "Inspect this screenshot:",
+                    "images": [self.image_b64],
+                },
+            ],
+            res,
+        )
+
+    async def test_tool_call_with_incomplete_input_does_not_crash(
+        self,
+    ) -> None:
+        """A truncated ``block.input`` must not crash the formatter.
+
+        Context compression or interrupted streaming can leave a
+        ``ToolCallBlock.input`` as an incomplete JSON fragment. Ollama
+        expects ``arguments`` as a dict, so the formatter must repair the
+        fragment instead of raising ``JSONDecodeError``.
+        """
+        fmt = OllamaChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ToolCallBlock(
+                        id="call_1",
+                        name="get_weather",
+                        input='{"city": "Tok',
+                    ),
+                ],
+            ),
+        ]
+
+        res = await fmt.format(msgs)
+
+        args = res[0]["tool_calls"][0]["function"]["arguments"]
+        self.assertIsInstance(args, dict)
+
+    async def test_tool_result_message_carries_tool_name(self) -> None:
+        """``role: tool`` messages must carry ``tool_name`` per Ollama spec.
+
+        Ollama's tool-calling API correlates a tool result with its function
+        via the ``tool_name`` field (not OpenAI's ``tool_call_id``). Emitting
+        a ``tool`` message without it breaks multi-turn tool use.  See
+        https://docs.ollama.com/capabilities/tool-calling.
+        """
+        fmt = OllamaChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ToolCallBlock(
+                        id="call_1",
+                        name="get_capital",
+                        input='{"country": "Japan"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_1",
+                        name="get_capital",
+                        output=[TextBlock(text="Tokyo")],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                ],
+            ),
+        ]
+
+        res = await fmt.format(msgs)
+
+        tool_messages = [m for m in res if m.get("role") == "tool"]
+        self.assertEqual(len(tool_messages), 1)
+        self.assertEqual(tool_messages[0]["tool_name"], "get_capital")
+        # The OpenAI-style tool_call_id must NOT be emitted for Ollama.
+        self.assertNotIn("tool_call_id", tool_messages[0])
diff --git a/tests/formatter_openai_chat_test.py b/tests/formatter_openai_chat_test.py
new file mode 100644
index 0000000..7ca7a42
--- /dev/null
+++ b/tests/formatter_openai_chat_test.py
@@ -0,0 +1,772 @@
+# -*- coding: utf-8 -*-
+"""Comprehensive formatter unit tests for OpenAIChatFormatter and
+OpenAIMultiAgentFormatter, following the reference test style with exact
+ground-truth comparisons.
+"""
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import patch
+
+from agentscope.formatter import (
+    OpenAIChatFormatter,
+    OpenAIMultiAgentFormatter,
+)
+from agentscope.message import (
+    UserMsg,
+    AssistantMsg,
+    SystemMsg,
+    TextBlock,
+    DataBlock,
+    ToolCallBlock,
+    ToolResultBlock,
+    ToolResultState,
+    Base64Source,
+    URLSource,
+    ThinkingBlock,
+    HintBlock,
+)
+
+
+_FIXED_ID = "TESTID1234567"
+
+
+class TestOpenAIFormatter(IsolatedAsyncioTestCase):
+    """Comprehensive tests for OpenAI Chat and MultiAgent formatters."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up shared message fixtures and expected ground-truth dicts."""
+        _img_src = URLSource(
+            url="https://example.com/image.png",
+            media_type="image/png",
+        )
+        self.image_url = str(_img_src.url)
+
+        self.image_b64 = "ZmFrZSBpbWFnZSBkYXRh"
+        self.image_data_uri = f"data:image/png;base64,{self.image_b64}"
+
+        # ---------------------------------------------------------------
+        # Message fixtures
+        # (No audio in conversation: OpenAI URL audio requires a download)
+        # ---------------------------------------------------------------
+        self.msgs_system = [
+            SystemMsg(
+                name="system",
+                content="You're a helpful assistant.",
+            ),
+        ]
+
+        self.msgs_conversation = [
+            UserMsg(
+                name="user",
+                content=[
+                    TextBlock(text="What is the capital of France?"),
+                    DataBlock(
+                        source=URLSource(
+                            url=self.image_url,
+                            media_type="image/png",
+                        ),
+                    ),
+                ],
+            ),
+            AssistantMsg(
+                name="assistant",
+                content="The capital of France is Paris.",
+            ),
+            UserMsg(
+                name="user",
+                content="What is the capital of Germany?",
+            ),
+            AssistantMsg(
+                name="assistant",
+                content="The capital of Germany is Berlin.",
+            ),
+            UserMsg(
+                name="user",
+                content="What is the capital of Japan?",
+            ),
+        ]
+
+        self.msgs_tools = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ToolCallBlock(
+                        id="call_1",
+                        name="get_capital",
+                        input='{"country": "Japan"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_1",
+                        name="get_capital",
+                        output=[
+                            TextBlock(text="The capital of Japan is Tokyo."),
+                        ],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    TextBlock(text="The capital of Japan is Tokyo."),
+                ],
+            ),
+        ]
+
+        # ---------------------------------------------------------------
+        # Ground truth: OpenAIChatFormatter
+        #   - Content is a list of {"type": ..., ...} dicts.
+        #   - Tool-result content is a plain string.
+        #   - Messages have a "name" field.
+        # ---------------------------------------------------------------
+        self.gt_chat = [
+            {
+                "role": "system",
+                "name": "system",
+                "content": [
+                    {"type": "text", "text": "You're a helpful assistant."},
+                ],
+            },
+            {
+                "role": "user",
+                "name": "user",
+                "content": [
+                    {"type": "text", "text": "What is the capital of France?"},
+                    {
+                        "type": "image_url",
+                        "image_url": {"url": self.image_url},
+                    },
+                ],
+            },
+            {
+                "role": "assistant",
+                "name": "assistant",
+                "content": [
+                    {
+                        "type": "text",
+                        "text": "The capital of France is Paris.",
+                    },
+                ],
+            },
+            {
+                "role": "user",
+                "name": "user",
+                "content": [
+                    {
+                        "type": "text",
+                        "text": "What is the capital of Germany?",
+                    },
+                ],
+            },
+            {
+                "role": "assistant",
+                "name": "assistant",
+                "content": [
+                    {
+                        "type": "text",
+                        "text": "The capital of Germany is Berlin.",
+                    },
+                ],
+            },
+            {
+                "role": "user",
+                "name": "user",
+                "content": [
+                    {"type": "text", "text": "What is the capital of Japan?"},
+                ],
+            },
+            {
+                "role": "assistant",
+                "name": "assistant",
+                "content": None,
+                "tool_calls": [
+                    {
+                        "id": "call_1",
+                        "type": "function",
+                        "function": {
+                            "name": "get_capital",
+                            "arguments": '{"country": "Japan"}',
+                        },
+                    },
+                ],
+            },
+            {
+                "role": "tool",
+                "tool_call_id": "call_1",
+                "content": "The capital of Japan is Tokyo.",
+                "name": "get_capital",
+            },
+            {
+                "role": "assistant",
+                "name": "assistant",
+                "content": [
+                    {
+                        "type": "text",
+                        "text": "The capital of Japan is Tokyo.",
+                    },
+                ],
+            },
+        ]
+
+        # ---------------------------------------------------------------
+        # Ground truth: OpenAIMultiAgentFormatter
+        #   - System content is a plain string.
+        #   - All conversation text is collapsed into a single text block,
+        #     with media blocks appended after.
+        #   - No "name" field on the user wrapper message.
+        # ---------------------------------------------------------------
+        _hist_prompt = OpenAIMultiAgentFormatter().conversation_history_prompt
+
+        _conv_text = (
+            "user: What is the capital of France?\n"
+            "assistant: The capital of France is Paris.\n"
+            "user: What is the capital of Germany?\n"
+            "assistant: The capital of Germany is Berlin.\n"
+            "user: What is the capital of Japan?"
+        )
+
+        self._gt_trailing_asst = {
+            "role": "assistant",
+            "name": "assistant",
+            "content": [
+                {
+                    "type": "text",
+                    "text": "The capital of Japan is Tokyo.",
+                },
+            ],
+        }
+
+        self._gt_tool_call = {
+            "role": "assistant",
+            "name": "assistant",
+            "content": None,
+            "tool_calls": [
+                {
+                    "id": "call_1",
+                    "type": "function",
+                    "function": {
+                        "name": "get_capital",
+                        "arguments": '{"country": "Japan"}',
+                    },
+                },
+            ],
+        }
+        self._gt_tool_result = {
+            "role": "tool",
+            "tool_call_id": "call_1",
+            "content": "The capital of Japan is Tokyo.",
+            "name": "get_capital",
+        }
+
+        self.gt_multiagent = [
+            {
+                "role": "system",
+                "content": "You're a helpful assistant.",
+            },
+            {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "text",
+                        "text": (
+                            _hist_prompt
+                            + "<history>\n"
+                            + _conv_text
+                            + "\n</history>"
+                        ),
+                    },
+                    {
+                        "type": "image_url",
+                        "image_url": {"url": self.image_url},
+                    },
+                ],
+            },
+            self._gt_tool_call,
+            self._gt_tool_result,
+            self._gt_trailing_asst,
+        ]
+
+    # -------------------------------------------------------------------
+    # OpenAIChatFormatter tests
+    # -------------------------------------------------------------------
+
+    async def test_chat_formatter(self) -> None:
+        """Chat formatter produces exact output for various subsets."""
+        fmt = OpenAIChatFormatter()
+
+        # Full history
+        res = await fmt.format(
+            [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+        )
+        self.assertListEqual(self.gt_chat, res)
+
+        # Without system
+        res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])
+        self.assertListEqual(self.gt_chat[1:], res)
+
+        # Without conversation
+        n_tools_gt = len(self.gt_chat) - 1 - len(self.msgs_conversation)
+        res = await fmt.format([*self.msgs_system, *self.msgs_tools])
+        self.assertListEqual(
+            [self.gt_chat[0]] + self.gt_chat[-n_tools_gt:],
+            res,
+        )
+
+        # Without tools
+        res = await fmt.format([*self.msgs_system, *self.msgs_conversation])
+        self.assertListEqual(self.gt_chat[:-n_tools_gt], res)
+
+        # Empty
+        res = await fmt.format([])
+        self.assertListEqual([], res)
+
+    async def test_chat_formatter_base64_image(self) -> None:
+        """Base64-encoded image is inlined as a data URI."""
+        fmt = OpenAIChatFormatter()
+        msgs = [
+            UserMsg(
+                name="user",
+                content=[
+                    TextBlock(text="What's in this image?"),
+                    DataBlock(
+                        source=Base64Source(
+                            data=self.image_b64,
+                            media_type="image/png",
+                        ),
+                    ),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "user",
+                    "name": "user",
+                    "content": [
+                        {"type": "text", "text": "What's in this image?"},
+                        {
+                            "type": "image_url",
+                            "image_url": {"url": self.image_data_uri},
+                        },
+                    ],
+                },
+            ],
+            res,
+        )
+
+    async def test_chat_formatter_thinking_dropped(self) -> None:
+        """ThinkingBlock is silently dropped by OpenAI formatter."""
+        fmt = OpenAIChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ThinkingBlock(thinking="inner thoughts"),
+                    TextBlock(text="reply"),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "assistant",
+                    "name": "assistant",
+                    "content": [{"type": "text", "text": "reply"}],
+                },
+            ],
+            res,
+        )
+
+    @patch(
+        "agentscope.formatter._formatter_base.shortuuid.uuid",
+        return_value=_FIXED_ID,
+    )
+    async def test_chat_formatter_url_image_in_tool_result(
+        self,
+        _mock_uuid: object,
+    ) -> None:
+        """URL images in tool results are promoted to a follow-up user
+        message."""
+        fmt = OpenAIChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ToolCallBlock(
+                        id="call_img",
+                        name="get_map",
+                        input='{"city": "Tokyo"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_img",
+                        name="get_map",
+                        output=[
+                            TextBlock(text="Here is the map."),
+                            DataBlock(
+                                source=URLSource(
+                                    url=self.image_url,
+                                    media_type="image/png",
+                                ),
+                            ),
+                        ],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    TextBlock(text="Here is the map of Tokyo."),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+
+        expected_tool_content = (
+            "Here is the map.\n"
+            f"<system-reminder>A(n) image file is returned "
+            f"and will be presented to you with the identifier "
+            f"[{_FIXED_ID}].</system-reminder>"
+        )
+        self.assertListEqual(
+            [
+                {
+                    "role": "assistant",
+                    "name": "assistant",
+                    "content": None,
+                    "tool_calls": [
+                        {
+                            "id": "call_img",
+                            "type": "function",
+                            "function": {
+                                "name": "get_map",
+                                "arguments": '{"city": "Tokyo"}',
+                            },
+                        },
+                    ],
+                },
+                {
+                    "role": "tool",
+                    "tool_call_id": "call_img",
+                    "content": expected_tool_content,
+                    "name": "get_map",
+                },
+                {
+                    "role": "user",
+                    "name": "system-reminder",
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": (
+                                "<system-reminder>The multimodal data "
+                                "and their identifiers are listed as "
+                                "follows:"
+                            ),
+                        },
+                        {
+                            "type": "text",
+                            "text": f"- {_FIXED_ID} (image file): ",
+                        },
+                        {
+                            "type": "image_url",
+                            "image_url": {"url": self.image_url},
+                        },
+                        {
+                            "type": "text",
+                            "text": "</system-reminder>",
+                        },
+                    ],
+                },
+                {
+                    "role": "assistant",
+                    "name": "assistant",
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": "Here is the map of Tokyo.",
+                        },
+                    ],
+                },
+            ],
+            res,
+        )
+
+    # -------------------------------------------------------------------
+    # OpenAIMultiAgentFormatter tests
+    # -------------------------------------------------------------------
+
+    async def test_multiagent_formatter(self) -> None:
+        """MultiAgent formatter produces exact output for various subsets."""
+        fmt = OpenAIMultiAgentFormatter()
+
+        # Full history
+        res = await fmt.format(
+            [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+        )
+        self.assertListEqual(self.gt_multiagent, res)
+
+        # Without system
+        res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])
+        self.assertListEqual(self.gt_multiagent[1:], res)
+
+        # Without tools
+        res = await fmt.format([*self.msgs_system, *self.msgs_conversation])
+        self.assertListEqual(self.gt_multiagent[:2], res)
+
+        # System only
+        res = await fmt.format(self.msgs_system)
+        self.assertListEqual([self.gt_multiagent[0]], res)
+
+        # Conversation only
+        res = await fmt.format(self.msgs_conversation)
+        self.assertListEqual([self.gt_multiagent[1]], res)
+
+        # Tools only
+        res = await fmt.format(self.msgs_tools)
+        self.assertListEqual(
+            [
+                self._gt_tool_call,
+                self._gt_tool_result,
+                self._gt_trailing_asst,
+            ],
+            res,
+        )
+
+        # System + tools (no conversation)
+        res = await fmt.format([*self.msgs_system, *self.msgs_tools])
+        self.assertListEqual(
+            [
+                self.gt_multiagent[0],
+                self._gt_tool_call,
+                self._gt_tool_result,
+                self._gt_trailing_asst,
+            ],
+            res,
+        )
+
+        # Empty
+        res = await fmt.format([])
+        self.assertListEqual([], res)
+
+    async def test_chat_formatter_complex_multi_step(self) -> None:
+        """Complex multi-step sequence with interleaved thinking, text,
+        tool calls, and tool results."""
+        fmt = OpenAIChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ThinkingBlock(thinking="thinking_1"),
+                    TextBlock(text="text_1"),
+                    ToolCallBlock(
+                        id="call_1",
+                        name="func_1",
+                        input='{"arg": "value1"}',
+                    ),
+                    ToolCallBlock(
+                        id="call_2",
+                        name="func_2",
+                        input='{"arg": "value2"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_1",
+                        name="func_1",
+                        output=[TextBlock(text="result_1")],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    ToolResultBlock(
+                        id="call_2",
+                        name="func_2",
+                        output=[TextBlock(text="result_2")],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    ThinkingBlock(thinking="thinking_2"),
+                    TextBlock(text="text_2"),
+                    ToolCallBlock(
+                        id="call_3",
+                        name="func_3",
+                        input='{"arg": "value3"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_3",
+                        name="func_3",
+                        output=[TextBlock(text="result_3")],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    ToolCallBlock(
+                        id="call_4",
+                        name="func_4",
+                        input='{"arg": "value4"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_4",
+                        name="func_4",
+                        output=[TextBlock(text="result_4")],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    ThinkingBlock(thinking="thinking_3"),
+                    TextBlock(text="text_3"),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "assistant",
+                    "name": "assistant",
+                    "content": [{"type": "text", "text": "text_1"}],
+                    "tool_calls": [
+                        {
+                            "id": "call_1",
+                            "type": "function",
+                            "function": {
+                                "name": "func_1",
+                                "arguments": '{"arg": "value1"}',
+                            },
+                        },
+                        {
+                            "id": "call_2",
+                            "type": "function",
+                            "function": {
+                                "name": "func_2",
+                                "arguments": '{"arg": "value2"}',
+                            },
+                        },
+                    ],
+                },
+                {
+                    "role": "tool",
+                    "tool_call_id": "call_1",
+                    "content": "result_1",
+                    "name": "func_1",
+                },
+                {
+                    "role": "tool",
+                    "tool_call_id": "call_2",
+                    "content": "result_2",
+                    "name": "func_2",
+                },
+                {
+                    "role": "assistant",
+                    "name": "assistant",
+                    "content": [{"type": "text", "text": "text_2"}],
+                    "tool_calls": [
+                        {
+                            "id": "call_3",
+                            "type": "function",
+                            "function": {
+                                "name": "func_3",
+                                "arguments": '{"arg": "value3"}',
+                            },
+                        },
+                    ],
+                },
+                {
+                    "role": "tool",
+                    "tool_call_id": "call_3",
+                    "content": "result_3",
+                    "name": "func_3",
+                },
+                {
+                    "role": "assistant",
+                    "name": "assistant",
+                    "content": None,
+                    "tool_calls": [
+                        {
+                            "id": "call_4",
+                            "type": "function",
+                            "function": {
+                                "name": "func_4",
+                                "arguments": '{"arg": "value4"}',
+                            },
+                        },
+                    ],
+                },
+                {
+                    "role": "tool",
+                    "tool_call_id": "call_4",
+                    "content": "result_4",
+                    "name": "func_4",
+                },
+                {
+                    "role": "assistant",
+                    "name": "assistant",
+                    "content": [{"type": "text", "text": "text_3"}],
+                },
+            ],
+            res,
+        )
+
+    async def test_chat_formatter_hint_block(self) -> None:
+        """HintBlock flushes preceding content and becomes a user message."""
+        fmt = OpenAIChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    TextBlock(text="Let me think about that."),
+                    HintBlock(hint="Remember to be concise."),
+                    TextBlock(text="Here is my answer."),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "assistant",
+                    "name": "assistant",
+                    "content": [
+                        {"type": "text", "text": "Let me think about that."},
+                    ],
+                },
+                {
+                    "role": "user",
+                    "content": [
+                        {"type": "text", "text": "Remember to be concise."},
+                    ],
+                },
+                {
+                    "role": "assistant",
+                    "name": "assistant",
+                    "content": [
+                        {"type": "text", "text": "Here is my answer."},
+                    ],
+                },
+            ],
+            res,
+        )
+
+    async def test_chat_formatter_hint_block_multimodal(self) -> None:
+        """Multimodal HintBlock becomes a single user message with text +
+        image."""
+        fmt = OpenAIChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    HintBlock(
+                        hint=[
+                            TextBlock(text="Inspect this screenshot:"),
+                            DataBlock(
+                                source=Base64Source(
+                                    data=self.image_b64,
+                                    media_type="image/png",
+                                ),
+                            ),
+                        ],
+                    ),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": "Inspect this screenshot:",
+                        },
+                        {
+                            "type": "image_url",
+                            "image_url": {"url": self.image_data_uri},
+                        },
+                    ],
+                },
+            ],
+            res,
+        )
diff --git a/tests/formatter_openai_response_test.py b/tests/formatter_openai_response_test.py
new file mode 100644
index 0000000..c431892
--- /dev/null
+++ b/tests/formatter_openai_response_test.py
@@ -0,0 +1,812 @@
+# -*- coding: utf-8 -*-
+"""Comprehensive formatter unit tests for OpenAIResponseFormatter and
+OpenAIResponseMultiAgentFormatter, following the reference test style with
+exact ground-truth comparisons.
+
+Key differences from OpenAI Chat formatter:
+  - Text content type is "input_text" (not "text").
+  - Image content type is "input_image" with flat "image_url" string.
+  - Tool calls become top-level "function_call" items (not nested in a msg).
+  - Tool results become top-level "function_call_output" items.
+  - ThinkingBlock: only echoed when it has a "reasoning_item_id" attribute.
+"""
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import patch
+
+from agentscope.formatter import (
+    OpenAIResponseFormatter,
+    OpenAIResponseMultiAgentFormatter,
+)
+from agentscope.message import (
+    UserMsg,
+    AssistantMsg,
+    SystemMsg,
+    TextBlock,
+    DataBlock,
+    ToolCallBlock,
+    ToolResultBlock,
+    ToolResultState,
+    Base64Source,
+    URLSource,
+    ThinkingBlock,
+    HintBlock,
+)
+
+
+_FIXED_ID = "TESTID1234567"
+
+
+class TestOpenAIResponseFormatter(IsolatedAsyncioTestCase):
+    """Comprehensive tests for OpenAI Responses API formatters."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up shared message fixtures and expected ground-truth dicts."""
+        _img_src = URLSource(
+            url="https://example.com/image.png",
+            media_type="image/png",
+        )
+        self.image_url = str(_img_src.url)
+
+        self.image_b64 = "ZmFrZSBpbWFnZSBkYXRh"
+        self.image_data_uri = f"data:image/png;base64,{self.image_b64}"
+
+        # ---------------------------------------------------------------
+        # Message fixtures (no audio to avoid downloads)
+        # ---------------------------------------------------------------
+        self.msgs_system = [
+            SystemMsg(
+                name="system",
+                content="You're a helpful assistant.",
+            ),
+        ]
+
+        self.msgs_conversation = [
+            UserMsg(
+                name="user",
+                content=[
+                    TextBlock(text="What is the capital of France?"),
+                    DataBlock(
+                        source=URLSource(
+                            url=self.image_url,
+                            media_type="image/png",
+                        ),
+                    ),
+                ],
+            ),
+            AssistantMsg(
+                name="assistant",
+                content="The capital of France is Paris.",
+            ),
+            UserMsg(
+                name="user",
+                content="What is the capital of Germany?",
+            ),
+            AssistantMsg(
+                name="assistant",
+                content="The capital of Germany is Berlin.",
+            ),
+            UserMsg(
+                name="user",
+                content="What is the capital of Japan?",
+            ),
+        ]
+
+        self.msgs_tools = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ToolCallBlock(
+                        id="call_1",
+                        name="get_capital",
+                        input='{"country": "Japan"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_1",
+                        name="get_capital",
+                        output=[
+                            TextBlock(text="The capital of Japan is Tokyo."),
+                        ],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    TextBlock(text="The capital of Japan is Tokyo."),
+                ],
+            ),
+        ]
+
+        # ---------------------------------------------------------------
+        # Ground truth: OpenAIResponseFormatter
+        #   - Text: {"type": "input_text", "text": ...}
+        #   - Image: {"type": "input_image", "image_url": url_string}
+        #   - ToolCallBlock → top-level {"type": "function_call", ...} item
+        #   - ToolResultBlock → top-level {"type": "function_call_output", ...}
+        #   - No "name" field on messages.
+        # ---------------------------------------------------------------
+        self.gt_chat = [
+            {
+                "role": "system",
+                "content": [
+                    {
+                        "type": "input_text",
+                        "text": "You're a helpful assistant.",
+                    },
+                ],
+            },
+            {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "input_text",
+                        "text": "What is the capital of France?",
+                    },
+                    {"type": "input_image", "image_url": self.image_url},
+                ],
+            },
+            {
+                "role": "assistant",
+                "content": [
+                    {
+                        "type": "output_text",
+                        "text": "The capital of France is Paris.",
+                    },
+                ],
+            },
+            {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "input_text",
+                        "text": "What is the capital of Germany?",
+                    },
+                ],
+            },
+            {
+                "role": "assistant",
+                "content": [
+                    {
+                        "type": "output_text",
+                        "text": "The capital of Germany is Berlin.",
+                    },
+                ],
+            },
+            {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "input_text",
+                        "text": "What is the capital of Japan?",
+                    },
+                ],
+            },
+            {
+                "type": "function_call",
+                "call_id": "call_1",
+                "name": "get_capital",
+                "arguments": '{"country": "Japan"}',
+            },
+            {
+                "type": "function_call_output",
+                "call_id": "call_1",
+                "output": "The capital of Japan is Tokyo.",
+            },
+            {
+                "role": "assistant",
+                "content": [
+                    {
+                        "type": "output_text",
+                        "text": "The capital of Japan is Tokyo.",
+                    },
+                ],
+            },
+        ]
+
+        # ---------------------------------------------------------------
+        # Ground truth: OpenAIResponseMultiAgentFormatter
+        #   - System: {"role": "system", "content": plain_string}
+        #   - Conversation history: input_text with history wrapping.
+        #   - Tool sequences use OpenAIResponseFormatter (function_call /
+        #     function_call_output top-level items).
+        # ---------------------------------------------------------------
+        _hist_prompt = (
+            OpenAIResponseMultiAgentFormatter().conversation_history_prompt
+        )
+
+        _conv_text = (
+            "user: What is the capital of France?\n"
+            "assistant: The capital of France is Paris.\n"
+            "user: What is the capital of Germany?\n"
+            "assistant: The capital of Germany is Berlin.\n"
+            "user: What is the capital of Japan?"
+        )
+
+        self._gt_trailing_asst = {
+            "role": "assistant",
+            "content": [
+                {
+                    "type": "output_text",
+                    "text": "The capital of Japan is Tokyo.",
+                },
+            ],
+        }
+
+        self._gt_tool_call = {
+            "type": "function_call",
+            "call_id": "call_1",
+            "name": "get_capital",
+            "arguments": '{"country": "Japan"}',
+        }
+        self._gt_tool_result = {
+            "type": "function_call_output",
+            "call_id": "call_1",
+            "output": "The capital of Japan is Tokyo.",
+        }
+
+        self.gt_multiagent = [
+            {
+                "role": "system",
+                "content": "You're a helpful assistant.",
+            },
+            {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "input_text",
+                        "text": (
+                            _hist_prompt
+                            + "<history>\n"
+                            + _conv_text
+                            + "\n</history>"
+                        ),
+                    },
+                    {"type": "input_image", "image_url": self.image_url},
+                ],
+            },
+            self._gt_tool_call,
+            self._gt_tool_result,
+            self._gt_trailing_asst,
+        ]
+
+    # -------------------------------------------------------------------
+    # OpenAIResponseFormatter tests
+    # -------------------------------------------------------------------
+
+    async def test_chat_formatter(self) -> None:
+        """Chat formatter produces exact output for various subsets."""
+        fmt = OpenAIResponseFormatter()
+
+        # Full history
+        res = await fmt.format(
+            [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+        )
+        self.assertListEqual(self.gt_chat, res)
+
+        # Without system
+        res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])
+        self.assertListEqual(self.gt_chat[1:], res)
+
+        # Without conversation
+        n_tools_gt = len(self.gt_chat) - 1 - len(self.msgs_conversation)
+        res = await fmt.format([*self.msgs_system, *self.msgs_tools])
+        self.assertListEqual(
+            [self.gt_chat[0]] + self.gt_chat[-n_tools_gt:],
+            res,
+        )
+
+        # Without tools
+        res = await fmt.format([*self.msgs_system, *self.msgs_conversation])
+        self.assertListEqual(self.gt_chat[:-n_tools_gt], res)
+
+        # Empty
+        res = await fmt.format([])
+        self.assertListEqual([], res)
+
+    async def test_chat_formatter_base64_image(self) -> None:
+        """Base64-encoded image becomes an input_image item with data URI."""
+        fmt = OpenAIResponseFormatter()
+        msgs = [
+            UserMsg(
+                name="user",
+                content=[
+                    TextBlock(text="What's in this image?"),
+                    DataBlock(
+                        source=Base64Source(
+                            data=self.image_b64,
+                            media_type="image/png",
+                        ),
+                    ),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "input_text",
+                            "text": "What's in this image?",
+                        },
+                        {
+                            "type": "input_image",
+                            "image_url": self.image_data_uri,
+                        },
+                    ],
+                },
+            ],
+            res,
+        )
+
+    async def test_chat_formatter_thinking_dropped_without_reasoning_item_id(
+        self,
+    ) -> None:
+        """ThinkingBlock without reasoning_item_id is silently skipped."""
+        fmt = OpenAIResponseFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ThinkingBlock(thinking="inner thoughts"),
+                    TextBlock(text="reply"),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "assistant",
+                    "content": [
+                        {"type": "output_text", "text": "reply"},
+                    ],
+                },
+            ],
+            res,
+        )
+
+    async def test_chat_formatter_thinking_echoed_with_reasoning_item_id(
+        self,
+    ) -> None:
+        """ThinkingBlock with reasoning_item_id is echoed as a reasoning
+        item."""
+        fmt = OpenAIResponseFormatter()
+        thinking = ThinkingBlock(thinking="my reasoning")
+        thinking.reasoning_item_id = "rs_001"
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[thinking, TextBlock(text="reply")],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "type": "reasoning",
+                    "id": "rs_001",
+                    "summary": [
+                        {"type": "summary_text", "text": "my reasoning"},
+                    ],
+                    "content": [],
+                },
+                {
+                    "role": "assistant",
+                    "content": [
+                        {"type": "output_text", "text": "reply"},
+                    ],
+                },
+            ],
+            res,
+        )
+
+    @patch(
+        "agentscope.formatter._formatter_base.shortuuid.uuid",
+        return_value=_FIXED_ID,
+    )
+    async def test_chat_formatter_url_image_in_tool_result(
+        self,
+        _mock_uuid: object,
+    ) -> None:
+        """URL images in tool results are promoted to a follow-up user
+        message."""
+        fmt = OpenAIResponseFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ToolCallBlock(
+                        id="call_img",
+                        name="get_map",
+                        input='{"city": "Tokyo"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_img",
+                        name="get_map",
+                        output=[
+                            TextBlock(text="Here is the map."),
+                            DataBlock(
+                                source=URLSource(
+                                    url=self.image_url,
+                                    media_type="image/png",
+                                ),
+                            ),
+                        ],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    TextBlock(text="Here is the map of Tokyo."),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+
+        expected_tool_content = (
+            "Here is the map.\n"
+            f"<system-reminder>A(n) image file is returned "
+            f"and will be presented to you with the identifier "
+            f"[{_FIXED_ID}].</system-reminder>"
+        )
+        self.assertListEqual(
+            [
+                {
+                    "type": "function_call",
+                    "call_id": "call_img",
+                    "name": "get_map",
+                    "arguments": '{"city": "Tokyo"}',
+                },
+                {
+                    "type": "function_call_output",
+                    "call_id": "call_img",
+                    "output": expected_tool_content,
+                },
+                {
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "input_text",
+                            "text": (
+                                "<system-reminder>The multimodal data "
+                                "and their identifiers are listed as "
+                                "follows:"
+                            ),
+                        },
+                        {
+                            "type": "input_text",
+                            "text": f"- {_FIXED_ID} (image file): ",
+                        },
+                        {
+                            "type": "input_image",
+                            "image_url": self.image_url,
+                        },
+                        {
+                            "type": "input_text",
+                            "text": "</system-reminder>",
+                        },
+                    ],
+                },
+                {
+                    "role": "assistant",
+                    "content": [
+                        {
+                            "type": "output_text",
+                            "text": "Here is the map of Tokyo.",
+                        },
+                    ],
+                },
+            ],
+            res,
+        )
+
+    # -------------------------------------------------------------------
+    # OpenAIResponseMultiAgentFormatter tests
+    # -------------------------------------------------------------------
+
+    async def test_multiagent_formatter(self) -> None:
+        """MultiAgent formatter produces exact output for various subsets."""
+        fmt = OpenAIResponseMultiAgentFormatter()
+
+        # Full history
+        res = await fmt.format(
+            [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+        )
+        self.assertListEqual(self.gt_multiagent, res)
+
+        # Without system
+        res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])
+        self.assertListEqual(self.gt_multiagent[1:], res)
+
+        # Without tools
+        res = await fmt.format([*self.msgs_system, *self.msgs_conversation])
+        self.assertListEqual(self.gt_multiagent[:2], res)
+
+        # System only
+        res = await fmt.format(self.msgs_system)
+        self.assertListEqual([self.gt_multiagent[0]], res)
+
+        # Conversation only
+        res = await fmt.format(self.msgs_conversation)
+        self.assertListEqual([self.gt_multiagent[1]], res)
+
+        # Tools only
+        res = await fmt.format(self.msgs_tools)
+        self.assertListEqual(
+            [
+                self._gt_tool_call,
+                self._gt_tool_result,
+                self._gt_trailing_asst,
+            ],
+            res,
+        )
+
+        # System + tools
+        res = await fmt.format([*self.msgs_system, *self.msgs_tools])
+        self.assertListEqual(
+            [
+                self.gt_multiagent[0],
+                self._gt_tool_call,
+                self._gt_tool_result,
+                self._gt_trailing_asst,
+            ],
+            res,
+        )
+
+        # Empty
+        res = await fmt.format([])
+        self.assertListEqual([], res)
+
+    async def test_chat_formatter_complex_multi_step(self) -> None:
+        """Complex multi-step sequence with interleaved thinking, text,
+        tool calls, and tool results."""
+        fmt = OpenAIResponseFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ThinkingBlock(thinking="thinking_1"),
+                    TextBlock(text="text_1"),
+                    ToolCallBlock(
+                        id="call_1",
+                        name="func_1",
+                        input='{"arg": "value1"}',
+                    ),
+                    ToolCallBlock(
+                        id="call_2",
+                        name="func_2",
+                        input='{"arg": "value2"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_1",
+                        name="func_1",
+                        output=[TextBlock(text="result_1")],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    ToolResultBlock(
+                        id="call_2",
+                        name="func_2",
+                        output=[TextBlock(text="result_2")],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    ThinkingBlock(thinking="thinking_2"),
+                    TextBlock(text="text_2"),
+                    ToolCallBlock(
+                        id="call_3",
+                        name="func_3",
+                        input='{"arg": "value3"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_3",
+                        name="func_3",
+                        output=[TextBlock(text="result_3")],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    ToolCallBlock(
+                        id="call_4",
+                        name="func_4",
+                        input='{"arg": "value4"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_4",
+                        name="func_4",
+                        output=[TextBlock(text="result_4")],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    ThinkingBlock(thinking="thinking_3"),
+                    TextBlock(text="text_3"),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "assistant",
+                    "content": [
+                        {"type": "output_text", "text": "text_1"},
+                    ],
+                },
+                {
+                    "type": "function_call",
+                    "call_id": "call_1",
+                    "name": "func_1",
+                    "arguments": '{"arg": "value1"}',
+                },
+                {
+                    "type": "function_call",
+                    "call_id": "call_2",
+                    "name": "func_2",
+                    "arguments": '{"arg": "value2"}',
+                },
+                {
+                    "type": "function_call_output",
+                    "call_id": "call_1",
+                    "output": "result_1",
+                },
+                {
+                    "type": "function_call_output",
+                    "call_id": "call_2",
+                    "output": "result_2",
+                },
+                {
+                    "role": "assistant",
+                    "content": [
+                        {"type": "output_text", "text": "text_2"},
+                    ],
+                },
+                {
+                    "type": "function_call",
+                    "call_id": "call_3",
+                    "name": "func_3",
+                    "arguments": '{"arg": "value3"}',
+                },
+                {
+                    "type": "function_call_output",
+                    "call_id": "call_3",
+                    "output": "result_3",
+                },
+                {
+                    "type": "function_call",
+                    "call_id": "call_4",
+                    "name": "func_4",
+                    "arguments": '{"arg": "value4"}',
+                },
+                {
+                    "type": "function_call_output",
+                    "call_id": "call_4",
+                    "output": "result_4",
+                },
+                {
+                    "role": "assistant",
+                    "content": [
+                        {"type": "output_text", "text": "text_3"},
+                    ],
+                },
+            ],
+            res,
+        )
+
+    async def test_chat_formatter_hint_block(self) -> None:
+        """HintBlock flushes preceding content and becomes a user message."""
+        fmt = OpenAIResponseFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    TextBlock(text="Let me think about that."),
+                    HintBlock(hint="Remember to be concise."),
+                    TextBlock(text="Here is my answer."),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "assistant",
+                    "content": [
+                        {
+                            "type": "output_text",
+                            "text": "Let me think about that.",
+                        },
+                    ],
+                },
+                {
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "input_text",
+                            "text": "Remember to be concise.",
+                        },
+                    ],
+                },
+                {
+                    "role": "assistant",
+                    "content": [
+                        {
+                            "type": "output_text",
+                            "text": "Here is my answer.",
+                        },
+                    ],
+                },
+            ],
+            res,
+        )
+
+    async def test_chat_formatter_hint_block_multimodal(self) -> None:
+        """Multimodal HintBlock becomes a single user message with text +
+        image."""
+        fmt = OpenAIResponseFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    HintBlock(
+                        hint=[
+                            TextBlock(text="Inspect this screenshot:"),
+                            DataBlock(
+                                source=Base64Source(
+                                    data=self.image_b64,
+                                    media_type="image/png",
+                                ),
+                            ),
+                        ],
+                    ),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "input_text",
+                            "text": "Inspect this screenshot:",
+                        },
+                        {
+                            "type": "input_image",
+                            "image_url": self.image_data_uri,
+                        },
+                    ],
+                },
+            ],
+            res,
+        )
+
+    async def test_tool_call_id_used_as_call_id(self) -> None:
+        """The formatter uses ToolCallBlock.id as function_call.call_id
+        and ToolResultBlock.id as function_call_output.call_id."""
+        fmt = OpenAIResponseFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ToolCallBlock(
+                        id="call-1",
+                        name="search",
+                        input='{"q": "test"}',
+                    ),
+                    ToolResultBlock(
+                        id="call-1",
+                        name="search",
+                        output=[TextBlock(text="result")],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                {
+                    "type": "function_call",
+                    "call_id": "call-1",
+                    "name": "search",
+                    "arguments": '{"q": "test"}',
+                },
+                {
+                    "type": "function_call_output",
+                    "call_id": "call-1",
+                    "output": "result",
+                },
+            ],
+            res,
+        )
diff --git a/tests/formatter_xai_test.py b/tests/formatter_xai_test.py
new file mode 100644
index 0000000..1dd5da4
--- /dev/null
+++ b/tests/formatter_xai_test.py
@@ -0,0 +1,596 @@
+# -*- coding: utf-8 -*-
+"""Comprehensive formatter unit tests for XAIChatFormatter and
+XAIMultiAgentFormatter (xAI), following the reference test style.
+
+Because these formatters return xai_sdk protobuf Message objects (not plain
+dicts), a lightweight xai_sdk stub is built at module load so that tests run
+without the real package.  The stub objects support __eq__ and __repr__ so
+full assertListEqual comparisons work.
+"""
+import sys
+from typing import Any
+from types import ModuleType
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import MagicMock
+
+from agentscope.formatter import XAIChatFormatter, XAIMultiAgentFormatter
+from agentscope.message import (
+    UserMsg,
+    AssistantMsg,
+    SystemMsg,
+    TextBlock,
+    DataBlock,
+    Base64Source,
+    ToolCallBlock,
+    ToolResultBlock,
+    ThinkingBlock,
+    ToolResultState,
+    HintBlock,
+)
+
+
+# ---------------------------------------------------------------------------
+# Comparable stub objects for xai_sdk protobuf messages.
+# ---------------------------------------------------------------------------
+
+
+class _StubMessage:
+    """Comparable stub for xai_sdk.chat.{user,assistant,system,tool_result}."""
+
+    def __init__(
+        self,
+        role: str,
+        args: tuple = (),
+        kwargs: dict | None = None,
+    ) -> None:
+        self.role = role
+        self.args = args
+        self.kwargs = kwargs or {}
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, _StubMessage):
+            return NotImplemented
+        return (
+            self.role == other.role
+            and self.args == other.args
+            and self.kwargs == other.kwargs
+        )
+
+    def __repr__(self) -> str:
+        parts = [f"role={self.role!r}", f"args={self.args!r}"]
+        if self.kwargs:
+            parts.append(f"kwargs={self.kwargs!r}")
+        return f"_StubMessage({', '.join(parts)})"
+
+
+class _StubImage:
+    """Comparable stub for xai_sdk.chat.image()."""
+
+    def __init__(self, url: str) -> None:
+        self.type = "image"
+        self.url = url
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, _StubImage):
+            return NotImplemented
+        return self.url == other.url
+
+    def __repr__(self) -> str:
+        return f"_StubImage(url={self.url!r})"
+
+
+def user(*args: Any) -> _StubMessage:
+    """Create a comparable stub user message."""
+    return _StubMessage(role="user", args=args)
+
+
+def assistant(*args: Any) -> _StubMessage:
+    """Create a comparable stub assistant message."""
+    return _StubMessage(role="assistant", args=args)
+
+
+def system(*args: Any) -> _StubMessage:
+    """Create a comparable stub system message."""
+    return _StubMessage(role="system", args=args)
+
+
+def tool_result(*args: Any, **kwargs: Any) -> _StubMessage:
+    """Create a comparable stub tool_result message."""
+    return _StubMessage(role="tool", args=args, kwargs=kwargs)
+
+
+def image(url: str) -> _StubImage:
+    """Create a comparable stub image object."""
+    return _StubImage(url=url)
+
+
+# ---------------------------------------------------------------------------
+# Build a lightweight xai_sdk stub so tests run without the real package.
+# ---------------------------------------------------------------------------
+
+
+def _build_xai_sdk_stub() -> None:
+    if "xai_sdk" in sys.modules:
+        return
+
+    chat_pb2 = ModuleType("xai_sdk.chat.chat_pb2")
+
+    class _EnumHelper:
+        _mapping = {
+            "ROLE_ASSISTANT": 2,
+            "TOOL_CALL_TYPE_CLIENT_SIDE_TOOL": 1,
+        }
+
+        def Value(self, name: str) -> int:
+            """Return the integer value for the given enum name."""
+            return self._mapping.get(name, 0)
+
+    chat_pb2.MessageRole = _EnumHelper()
+    chat_pb2.ToolCallType = _EnumHelper()
+
+    class _RepeatedField(list):
+        def __init__(self, factory: Any) -> None:
+            super().__init__()
+            self._factory = factory
+
+        def add(self) -> Any:
+            """Add a new item using the factory and return it."""
+            item = self._factory()
+            self.append(item)
+            return item
+
+    class _FunctionSpec:
+        def __init__(self) -> None:
+            self.name = ""
+            self.arguments = ""
+
+    class _ToolCallProto:
+        def __init__(self) -> None:
+            self.id = ""
+            self.type = 0
+            self.function = _FunctionSpec()
+
+    class _ContentPart:
+        text: str = ""
+
+    class _MessageProto:
+        def __init__(self) -> None:
+            self.role = 0
+            self.content = _RepeatedField(_ContentPart)
+            self.tool_calls = _RepeatedField(_ToolCallProto)
+
+    chat_pb2.Message = _MessageProto
+
+    xai_chat = ModuleType("xai_sdk.chat")
+    xai_chat.chat_pb2 = chat_pb2
+    xai_chat.user = user
+    xai_chat.assistant = assistant
+    xai_chat.system = system
+    xai_chat.tool_result = tool_result
+    xai_chat.image = image
+
+    xai_sdk = ModuleType("xai_sdk")
+    xai_sdk.chat = xai_chat
+    xai_sdk.AsyncClient = MagicMock()
+
+    sys.modules["xai_sdk"] = xai_sdk
+    sys.modules["xai_sdk.chat"] = xai_chat
+    sys.modules["xai_sdk.chat.chat_pb2"] = chat_pb2
+
+
+_build_xai_sdk_stub()
+
+
+class TestXAIFormatter(IsolatedAsyncioTestCase):
+    """Comprehensive tests for XAI Chat and MultiAgent formatters.
+
+    The stub objects support __eq__, so full assertListEqual works for
+    user/assistant/system/tool_result messages.  Tool-call messages use
+    _MessageProto which is checked via attribute assertions.
+    """
+
+    async def asyncSetUp(self) -> None:
+        self.msgs_system = [
+            SystemMsg(
+                name="system",
+                content="You're a helpful assistant.",
+            ),
+        ]
+
+        self.msgs_conversation = [
+            UserMsg(
+                name="user",
+                content="What is the capital of France?",
+            ),
+            AssistantMsg(
+                name="assistant",
+                content="The capital of France is Paris.",
+            ),
+            UserMsg(
+                name="user",
+                content="What is the capital of Germany?",
+            ),
+            AssistantMsg(
+                name="assistant",
+                content="The capital of Germany is Berlin.",
+            ),
+            UserMsg(
+                name="user",
+                content="What is the capital of Japan?",
+            ),
+        ]
+
+        self.msgs_tools = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ToolCallBlock(
+                        id="call_1",
+                        name="get_capital",
+                        input='{"country": "Japan"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_1",
+                        name="get_capital",
+                        output=[
+                            TextBlock(text="The capital of Japan is Tokyo."),
+                        ],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    TextBlock(text="The capital of Japan is Tokyo."),
+                ],
+            ),
+        ]
+
+        self._hist_prompt = (
+            XAIMultiAgentFormatter().conversation_history_prompt
+        )
+
+    # -------------------------------------------------------------------
+    # XAIChatFormatter tests
+    # -------------------------------------------------------------------
+
+    async def test_chat_formatter_system_message(self) -> None:
+        """System message becomes a system() stub."""
+        fmt = XAIChatFormatter()
+        res = await fmt.format(self.msgs_system)
+        self.assertListEqual(
+            [system("You're a helpful assistant.")],
+            res,
+        )
+
+    async def test_chat_formatter_user_assistant(self) -> None:
+        """User and assistant text messages are passed through correctly."""
+        fmt = XAIChatFormatter()
+        res = await fmt.format(self.msgs_conversation)
+        self.assertListEqual(
+            [
+                user("What is the capital of France?"),
+                assistant("The capital of France is Paris."),
+                user("What is the capital of Germany?"),
+                assistant("The capital of Germany is Berlin."),
+                user("What is the capital of Japan?"),
+            ],
+            res,
+        )
+
+    async def test_chat_formatter_tool_call(self) -> None:
+        """Assistant tool call becomes a _MessageProto with tool_calls set."""
+        fmt = XAIChatFormatter()
+        res = await fmt.format(
+            [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+        )
+        # Find the tool call proto (has tool_calls list, role=ROLE_ASSISTANT=2)
+        tool_call_msgs = [
+            m
+            for m in res
+            if hasattr(m, "tool_calls") and len(m.tool_calls) > 0
+        ]
+        self.assertListEqual(
+            [len(tool_call_msgs)],
+            [1],
+        )
+        tc = tool_call_msgs[0].tool_calls[0]
+        self.assertListEqual(
+            [tc.id, tc.function.name, tc.function.arguments],
+            ["call_1", "get_capital", '{"country": "Japan"}'],
+        )
+
+    async def test_chat_formatter_tool_result(self) -> None:
+        """Tool result becomes a tool_result() stub with the right id."""
+        fmt = XAIChatFormatter()
+        res = await fmt.format(self.msgs_tools)
+        tool_msgs = [m for m in res if m.role == "tool"]
+        self.assertListEqual(
+            tool_msgs,
+            [
+                tool_result(
+                    "The capital of Japan is Tokyo.",
+                    tool_call_id="call_1",
+                ),
+            ],
+        )
+
+    async def test_chat_formatter_thinking_dropped(self) -> None:
+        """ThinkingBlock is silently ignored in user/assistant xAI
+        messages."""
+        fmt = XAIChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ThinkingBlock(thinking="inner thoughts"),
+                    TextBlock(text="reply"),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual([assistant("reply")], res)
+
+    async def test_chat_formatter_empty(self) -> None:
+        """Empty input returns empty list."""
+        fmt = XAIChatFormatter()
+        res = await fmt.format([])
+        self.assertListEqual([], res)
+
+    # -------------------------------------------------------------------
+    # XAIMultiAgentFormatter tests
+    # -------------------------------------------------------------------
+
+    async def test_multiagent_formatter_system_message(self) -> None:
+        """System message is passed through as a system() stub."""
+        fmt = XAIMultiAgentFormatter()
+        res = await fmt.format(
+            [*self.msgs_system, *self.msgs_conversation],
+        )
+        self.assertEqual(res[0], system("You're a helpful assistant."))
+
+    async def test_multiagent_formatter_conversation_history(self) -> None:
+        """Non-tool agent messages are collapsed into a user() history
+        stub."""
+        fmt = XAIMultiAgentFormatter()
+        res = await fmt.format(self.msgs_conversation)
+        self.assertListEqual(
+            [
+                user(
+                    self._hist_prompt + "<history>\n"
+                    "user: What is the capital of France?\n"
+                    "assistant: The capital of France is Paris.\n"
+                    "user: What is the capital of Germany?\n"
+                    "assistant: The capital of Germany is Berlin.\n"
+                    "user: What is the capital of Japan?\n"
+                    "</history>",
+                ),
+            ],
+            res,
+        )
+
+    async def test_multiagent_formatter_first_group_has_hist_prompt(
+        self,
+    ) -> None:
+        """First agent message group includes the conversation history
+        prompt."""
+        fmt = XAIMultiAgentFormatter()
+        res = await fmt.format(self.msgs_conversation)
+        hist_text = res[0].args[0]
+        self.assertListEqual(
+            [hist_text.startswith(self._hist_prompt)],
+            [True],
+        )
+
+    async def test_multiagent_formatter_full_history(self) -> None:
+        """Full history produces system + conv_history + tool_call +
+        tool_result + trailing assistant."""
+        fmt = XAIMultiAgentFormatter()
+        res = await fmt.format(
+            [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+        )
+        roles = [m.role for m in res]
+        self.assertListEqual(
+            sorted(r for r in roles if isinstance(r, str)),
+            sorted(["system", "user", "tool", "assistant"]),
+        )
+
+    async def test_multiagent_formatter_tools_only_is_first(self) -> None:
+        """When only tools are given, trailing text is formatted as
+        assistant."""
+        fmt = XAIMultiAgentFormatter()
+        res = await fmt.format(self.msgs_tools)
+        trailing = [m for m in res if m.role == "assistant"]
+        self.assertListEqual([len(trailing)], [1])
+
+    async def test_multiagent_formatter_nonfirst_trailing_is_assistant(
+        self,
+    ) -> None:
+        """Trailing text after a tool sequence is formatted as assistant."""
+        fmt = XAIMultiAgentFormatter()
+        res = await fmt.format(
+            [*self.msgs_conversation, *self.msgs_tools],
+        )
+        trailing = [m for m in res if m.role == "assistant"]
+        self.assertListEqual([len(trailing)], [1])
+
+    async def test_multiagent_formatter_empty(self) -> None:
+        """Empty input returns empty list."""
+        fmt = XAIMultiAgentFormatter()
+        res = await fmt.format([])
+        self.assertListEqual([], res)
+
+    async def test_chat_formatter_complex_multi_step(self) -> None:
+        """Complex multi-step sequence with interleaved thinking, text,
+        tool calls, and tool results."""
+        fmt = XAIChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    ThinkingBlock(thinking="thinking_1"),
+                    TextBlock(text="text_1"),
+                    ToolCallBlock(
+                        id="call_1",
+                        name="func_1",
+                        input='{"arg": "value1"}',
+                    ),
+                    ToolCallBlock(
+                        id="call_2",
+                        name="func_2",
+                        input='{"arg": "value2"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_1",
+                        name="func_1",
+                        output=[TextBlock(text="result_1")],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    ToolResultBlock(
+                        id="call_2",
+                        name="func_2",
+                        output=[TextBlock(text="result_2")],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    ThinkingBlock(thinking="thinking_2"),
+                    TextBlock(text="text_2"),
+                    ToolCallBlock(
+                        id="call_3",
+                        name="func_3",
+                        input='{"arg": "value3"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_3",
+                        name="func_3",
+                        output=[TextBlock(text="result_3")],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    ToolCallBlock(
+                        id="call_4",
+                        name="func_4",
+                        input='{"arg": "value4"}',
+                    ),
+                    ToolResultBlock(
+                        id="call_4",
+                        name="func_4",
+                        output=[TextBlock(text="result_4")],
+                        state=ToolResultState.SUCCESS,
+                    ),
+                    ThinkingBlock(thinking="thinking_3"),
+                    TextBlock(text="text_3"),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+
+        # First message: proto with text_1 content + 2 tool_calls
+        self.assertTrue(hasattr(res[0], "tool_calls"))
+        self.assertEqual(len(res[0].tool_calls), 2)
+        self.assertEqual(len(res[0].content), 1)
+        self.assertEqual(res[0].tool_calls[0].id, "call_1")
+        self.assertEqual(res[0].tool_calls[0].function.name, "func_1")
+        self.assertEqual(
+            res[0].tool_calls[0].function.arguments,
+            '{"arg": "value1"}',
+        )
+        self.assertEqual(res[0].tool_calls[1].id, "call_2")
+        self.assertEqual(res[0].tool_calls[1].function.name, "func_2")
+        self.assertEqual(
+            res[0].tool_calls[1].function.arguments,
+            '{"arg": "value2"}',
+        )
+
+        # Tool results
+        self.assertEqual(
+            res[1],
+            tool_result("result_1", tool_call_id="call_1"),
+        )
+        self.assertEqual(
+            res[2],
+            tool_result("result_2", tool_call_id="call_2"),
+        )
+
+        # Second proto: text_2 + 1 tool_call
+        self.assertTrue(hasattr(res[3], "tool_calls"))
+        self.assertEqual(len(res[3].tool_calls), 1)
+        self.assertEqual(len(res[3].content), 1)
+        self.assertEqual(res[3].tool_calls[0].id, "call_3")
+        self.assertEqual(res[3].tool_calls[0].function.name, "func_3")
+
+        # Tool result for call_3
+        self.assertEqual(
+            res[4],
+            tool_result("result_3", tool_call_id="call_3"),
+        )
+
+        # Third proto: no content + 1 tool_call
+        self.assertTrue(hasattr(res[5], "tool_calls"))
+        self.assertEqual(len(res[5].tool_calls), 1)
+        self.assertEqual(len(res[5].content), 0)
+        self.assertEqual(res[5].tool_calls[0].id, "call_4")
+        self.assertEqual(res[5].tool_calls[0].function.name, "func_4")
+
+        # Tool result for call_4
+        self.assertEqual(
+            res[6],
+            tool_result("result_4", tool_call_id="call_4"),
+        )
+
+        # Final assistant text
+        self.assertEqual(res[7], assistant("text_3"))
+
+        # Total 8 items
+        self.assertEqual(len(res), 8)
+
+    async def test_chat_formatter_hint_block(self) -> None:
+        """HintBlock flushes preceding content and becomes a user message."""
+        fmt = XAIChatFormatter()
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    TextBlock(text="Let me think about that."),
+                    HintBlock(hint="Remember to be concise."),
+                    TextBlock(text="Here is my answer."),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                assistant("Let me think about that."),
+                user("Remember to be concise."),
+                assistant("Here is my answer."),
+            ],
+            res,
+        )
+
+    async def test_chat_formatter_hint_block_multimodal(self) -> None:
+        """Multimodal HintBlock becomes one user() stub carrying text +
+        image."""
+        fmt = XAIChatFormatter()
+        image_b64 = "ZmFrZSBpbWFnZSBkYXRh"
+        msgs = [
+            AssistantMsg(
+                name="assistant",
+                content=[
+                    HintBlock(
+                        hint=[
+                            TextBlock(text="Inspect this screenshot:"),
+                            DataBlock(
+                                source=Base64Source(
+                                    data=image_b64,
+                                    media_type="image/png",
+                                ),
+                            ),
+                        ],
+                    ),
+                ],
+            ),
+        ]
+        res = await fmt.format(msgs)
+        self.assertListEqual(
+            [
+                user(
+                    "Inspect this screenshot:",
+                    image(f"data:image/png;base64,{image_b64}"),
+                ),
+            ],
+            res,
+        )
diff --git a/tests/hitl_external_execution_test.py b/tests/hitl_external_execution_test.py
new file mode 100644
index 0000000..f59454e
--- /dev/null
+++ b/tests/hitl_external_execution_test.py
@@ -0,0 +1,1359 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=redefined-builtin
+"""Test the external execution events in the agent class."""
+from typing import Any
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from utils import AnyString, MockModel
+
+from agentscope.agent import Agent
+from agentscope.model import ChatResponse
+from agentscope.tool import (
+    ToolBase,
+    Toolkit,
+    ToolChunk,
+)
+from agentscope.permission import (
+    PermissionDecision,
+    PermissionBehavior,
+    PermissionContext,
+)
+from agentscope.message import (
+    TextBlock,
+    ToolCallBlock,
+    ToolResultBlock,
+    UserMsg,
+    ToolResultState,
+)
+from agentscope.event import ExternalExecutionResultEvent
+
+
+class MockExternalSequentialTool(ToolBase):
+    """A mock tool that requires external execution (sequential)."""
+
+    name: str = "mock_external_sequential_tool"
+    description: str = "A mock external sequential tool for testing"
+    input_schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {
+            "input": {"type": "string", "description": "Input string"},
+        },
+        "required": ["input"],
+    }
+    is_concurrency_safe: bool = False
+    is_read_only: bool = True
+    is_external_tool: bool = True
+    is_mcp: bool = False
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        """Check permissions for the tool usage."""
+        return PermissionDecision(
+            behavior=PermissionBehavior.ALLOW,
+            decision_reason="Mock external tool always allows",
+            message="Mock external tool always allows",
+        )
+
+    async def __call__(self, input: str, **kwargs: Any) -> ToolChunk:
+        """Execute the tool."""
+        return ToolChunk(
+            content=[TextBlock(text=f"External sequential result: {input}")],
+        )
+
+
+class MockExternalConcurrentTool(ToolBase):
+    """A mock tool that requires external execution (concurrent)."""
+
+    name: str = "mock_external_concurrent_tool"
+    description: str = "A mock external concurrent tool for testing"
+    input_schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {
+            "input": {"type": "string", "description": "Input string"},
+        },
+        "required": ["input"],
+    }
+    is_concurrency_safe: bool = True
+    is_read_only: bool = True
+    is_external_tool: bool = True
+    is_mcp: bool = False
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        """Check permissions for the tool usage."""
+        return PermissionDecision(
+            behavior=PermissionBehavior.ALLOW,
+            decision_reason="Mock external tool always allows",
+            message="Mock external tool always allows",
+        )
+
+    async def __call__(self, input: str, **kwargs: Any) -> ToolChunk:
+        """Execute the tool."""
+        return ToolChunk(
+            content=[TextBlock(text=f"External concurrent result: {input}")],
+        )
+
+
+class AgentExternalExecutionTest(IsolatedAsyncioTestCase):
+    """Test the external execution events in the agent class."""
+
+    async def asyncSetUp(self) -> None:
+        """The async setup method."""
+        self.model = MockModel()
+        self.agent = Agent(
+            name="Friday",
+            system_prompt="You are a helpful assistant.",
+            model=self.model,
+            toolkit=Toolkit(),
+        )
+        self.tool_call_id_1 = "tool_call_1"
+        self.tool_call_id_2 = "tool_call_2"
+        self.user_input_text = "Test"
+        self.tool_input_1 = '{"input": "test1"}'
+        self.tool_input_2 = '{"input": "test2"}'
+        self.sequential_tool_name = "mock_external_sequential_tool"
+        self.concurrent_tool_name = "mock_external_concurrent_tool"
+        self.sequential_result_1 = "External sequential result: test1"
+        self.sequential_result_2 = "External sequential result: test2"
+        self.concurrent_result_1 = "External concurrent result: test1"
+        self.concurrent_result_2 = "External concurrent result: test2"
+        self.final_response_text = "Final response after external execution"
+        self.final_text_events = [
+            {
+                "type": "MODEL_CALL_START",
+                "model_name": "mock-model",
+            },
+            {
+                "type": "TEXT_BLOCK_START",
+                "block_id": AnyString(),
+            },
+            {
+                "type": "TEXT_BLOCK_DELTA",
+                "block_id": AnyString(),
+                "delta": self.final_response_text,
+            },
+            {
+                "type": "TEXT_BLOCK_END",
+                "block_id": AnyString(),
+            },
+            {
+                "type": "MODEL_CALL_END",
+                "input_tokens": 0,
+                "output_tokens": 0,
+                "finished_reason": "completed",
+            },
+        ]
+        self.final_mock_responses = [
+            ChatResponse(
+                content=[
+                    TextBlock(text=self.final_response_text),
+                ],
+                is_last=False,
+                usage=None,
+            ),
+            ChatResponse(
+                content=[
+                    TextBlock(text=self.final_response_text),
+                ],
+                is_last=True,
+                usage=None,
+            ),
+        ]
+
+    def _get_event_base(self, reply_id: str) -> dict:
+        """Get the dict with the basic fields for event assertion."""
+        return {
+            "id": AnyString(),
+            "created_at": AnyString(),
+            "metadata": {},
+            "reply_id": reply_id,
+        }
+
+    def _get_msg_base(self) -> dict:
+        """Get the dict with the basic fields for message assertion."""
+        return {
+            "id": AnyString(),
+            "created_at": AnyString(),
+            "finished_at": None,
+            "metadata": {},
+            "name": "Friday",
+            "role": "assistant",
+            "usage": None,
+        }
+
+    def _get_tool_call_events(
+        self,
+        id: str,
+        name: str,
+        delta: str,
+    ) -> list[dict]:
+        """Helper method to get the expected tool call events."""
+        return [
+            {
+                "type": "TOOL_CALL_START",
+                "tool_call_id": id,
+                "tool_call_name": name,
+            },
+            {
+                "type": "TOOL_CALL_DELTA",
+                "tool_call_id": id,
+                "delta": delta,
+            },
+            {
+                "type": "TOOL_CALL_END",
+                "tool_call_id": id,
+            },
+        ]
+
+    def _get_tool_result_events(
+        self,
+        id: str,
+        result: str,
+        state: str = "success",
+    ) -> list[dict]:
+        """Helper method to get the expected tool result events."""
+        return [
+            {
+                "type": "TOOL_RESULT_TEXT_DELTA",
+                "tool_call_id": id,
+                "delta": result,
+            },
+            {
+                "type": "TOOL_RESULT_END",
+                "tool_call_id": id,
+                "state": state,
+            },
+        ]
+
+    def _get_require_external_execution_events(
+        self,
+        reply_id: str,
+        id: str,
+        name: str,
+        tool_input: str,
+    ) -> list[dict]:
+        """Helper method to get the expected external execution events."""
+        return [
+            {
+                "type": "TOOL_RESULT_START",
+                "tool_call_id": id,
+                "tool_call_name": name,
+            },
+            {
+                "type": "REQUIRE_EXTERNAL_EXECUTION",
+                "reply_id": reply_id,
+                "tool_calls": [
+                    {
+                        "type": "tool_call",
+                        "id": id,
+                        "name": name,
+                        "input": tool_input,
+                        "state": "submitted",
+                        "suggested_rules": [],
+                    },
+                ],
+            },
+        ]
+
+    async def test_single_external_execution(self) -> None:
+        """Test single external execution tool call.
+
+        The agent should:
+        1. Generate a tool call that requires external execution
+        2. Emit REQUIRE_EXTERNAL_EXECUTION event and pause
+        3. Resume when ExternalExecutionResultEvent is provided
+        4. Continue execution without calling the model again
+        """
+        # Register external tool
+        ext_tool = MockExternalSequentialTool()
+        self.agent.toolkit = Toolkit(
+            tools=[ext_tool],
+        )
+
+        # Set up mock response with tool call (no final text response)
+        self.model.set_responses(
+            [
+                [
+                    ChatResponse(
+                        content=[
+                            ToolCallBlock(
+                                id=self.tool_call_id_1,
+                                name=self.sequential_tool_name,
+                                input=self.tool_input_1,
+                            ),
+                        ],
+                        is_last=False,
+                        usage=None,
+                    ),
+                    ChatResponse(
+                        content=[
+                            ToolCallBlock(
+                                id=self.tool_call_id_1,
+                                name=self.sequential_tool_name,
+                                input=self.tool_input_1,
+                            ),
+                        ],
+                        is_last=True,
+                        usage=None,
+                    ),
+                ],
+                self.final_mock_responses,
+            ],
+        )
+
+        # First call: collect events until REQUIRE_EXTERNAL_EXECUTION
+        events = []
+        async for event in self.agent.reply_stream(
+            UserMsg(name="user", content=self.user_input_text),
+        ):
+            events.append(event.model_dump())
+
+        # Verify events
+        session_id = self.agent.state.session_id
+        reply_id = self.agent.state.reply_id
+
+        expected_events = [
+            {
+                "type": "REPLY_START",
+                "session_id": session_id,
+                "name": "Friday",
+                "role": "assistant",
+            },
+            {"type": "MODEL_CALL_START", "model_name": "mock-model"},
+            *self._get_tool_call_events(
+                self.tool_call_id_1,
+                self.sequential_tool_name,
+                self.tool_input_1,
+            ),
+            {
+                "type": "MODEL_CALL_END",
+                "input_tokens": 0,
+                "output_tokens": 0,
+                "finished_reason": "completed",
+            },
+            *self._get_require_external_execution_events(
+                reply_id,
+                self.tool_call_id_1,
+                self.sequential_tool_name,
+                self.tool_input_1,
+            ),
+        ]
+
+        basic_dict = self._get_event_base(reply_id)
+        self.assertListEqual(
+            events,
+            [{**basic_dict, **_} for _ in expected_events],
+        )
+
+        # Assert context after first call
+        msg_base = self._get_msg_base()
+        expected_context = [
+            {
+                "name": "user",
+                "role": "user",
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": self.user_input_text,
+                    },
+                ],
+                "finished_at": AnyString(),
+            },
+            {
+                "content": [
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_1,
+                        "name": self.sequential_tool_name,
+                        "input": self.tool_input_1,
+                        "state": "submitted",
+                        "suggested_rules": [],
+                    },
+                ],
+            },
+        ]
+        context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+        expected_context = [{**msg_base, **_} for _ in expected_context]
+        self.assertListEqual(context_dicts, expected_context)
+
+        # Create external execution result event
+        external_result_event = ExternalExecutionResultEvent(
+            reply_id=reply_id,
+            execution_results=[
+                ToolResultBlock(
+                    id=self.tool_call_id_1,
+                    name=self.sequential_tool_name,
+                    output=[
+                        TextBlock(text=self.sequential_result_1),
+                    ],
+                    state=ToolResultState.SUCCESS,
+                ),
+            ],
+        )
+
+        # Second call: resume with external execution result
+        events = []
+        async for event in self.agent.reply_stream(
+            inputs=external_result_event,
+        ):
+            events.append(event.model_dump())
+
+        # Verify events after resumption
+        expected_events_resume = [
+            *self._get_tool_result_events(
+                self.tool_call_id_1,
+                self.sequential_result_1,
+            ),
+            *self.final_text_events,
+            {
+                "type": "REPLY_END",
+                "session_id": session_id,
+                "finished_reason": "completed",
+            },
+        ]
+        self.assertListEqual(
+            events,
+            [{**basic_dict, **_} for _ in expected_events_resume],
+        )
+
+        # Assert final context
+        expected_context_final = [
+            {
+                "name": "user",
+                "role": "user",
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": self.user_input_text,
+                    },
+                ],
+                "finished_at": AnyString(),
+            },
+            {
+                "content": [
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_1,
+                        "name": self.sequential_tool_name,
+                        "input": self.tool_input_1,
+                        "state": "finished",
+                        "suggested_rules": [],
+                    },
+                    {
+                        "type": "tool_result",
+                        "id": AnyString(),
+                        "name": self.sequential_tool_name,
+                        "output": [
+                            {
+                                "type": "text",
+                                "id": AnyString(),
+                                "text": self.sequential_result_1,
+                            },
+                        ],
+                        "state": "success",
+                        "metadata": {},
+                    },
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": self.final_response_text,
+                    },
+                ],
+            },
+        ]
+        context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+        expected_context_final = [
+            {**msg_base, **_} for _ in expected_context_final
+        ]
+        self.assertListEqual(context_dicts, expected_context_final)
+
+    async def test_sequential_external_execution(self) -> None:
+        """Test multiple external execution tool calls in sequential execution.
+
+        The agent should:
+        1. Generate multiple tool calls that require external execution
+        2. All tools have is_concurrent_safe=False (sequential)
+        3. Emit REQUIRE_EXTERNAL_EXECUTION event and pause
+        4. Resume when ExternalExecutionResultEvent is provided
+        5. Continue execution without calling the model again
+        """
+        # Register external sequential tool
+        ext_tool = MockExternalSequentialTool()
+        self.agent.toolkit = Toolkit(
+            tools=[ext_tool],
+        )
+
+        # Set up mock response with multiple tool calls
+        self.model.set_responses(
+            [
+                [
+                    ChatResponse(
+                        content=[
+                            ToolCallBlock(
+                                id=self.tool_call_id_1,
+                                name=self.sequential_tool_name,
+                                input=self.tool_input_1,
+                            ),
+                            ToolCallBlock(
+                                id=self.tool_call_id_2,
+                                name=self.sequential_tool_name,
+                                input=self.tool_input_2,
+                            ),
+                        ],
+                        is_last=False,
+                        usage=None,
+                    ),
+                    ChatResponse(
+                        content=[
+                            ToolCallBlock(
+                                id=self.tool_call_id_1,
+                                name=self.sequential_tool_name,
+                                input=self.tool_input_1,
+                            ),
+                            ToolCallBlock(
+                                id=self.tool_call_id_2,
+                                name=self.sequential_tool_name,
+                                input=self.tool_input_2,
+                            ),
+                        ],
+                        is_last=True,
+                        usage=None,
+                    ),
+                ],
+                self.final_mock_responses,
+            ],
+        )
+
+        # First call: collect events until REQUIRE_EXTERNAL_EXECUTION
+        events = []
+        async for event in self.agent.reply_stream(
+            UserMsg(name="user", content=self.user_input_text),
+        ):
+            events.append(event.model_dump())
+
+        # Verify events
+        session_id = self.agent.state.session_id
+        reply_id = self.agent.state.reply_id
+        tool_call_1_events = self._get_tool_call_events(
+            self.tool_call_id_1,
+            self.sequential_tool_name,
+            self.tool_input_1,
+        )
+        tool_call_2_events = self._get_tool_call_events(
+            self.tool_call_id_2,
+            self.sequential_tool_name,
+            self.tool_input_2,
+        )
+
+        expected_events = [
+            {
+                "type": "REPLY_START",
+                "session_id": session_id,
+                "name": "Friday",
+                "role": "assistant",
+            },
+            {"type": "MODEL_CALL_START", "model_name": "mock-model"},
+            *tool_call_1_events[:2],
+            *tool_call_2_events[:2],
+            tool_call_1_events[2],
+            tool_call_2_events[2],
+            {
+                "type": "MODEL_CALL_END",
+                "input_tokens": 0,
+                "output_tokens": 0,
+                "finished_reason": "completed",
+            },
+            *self._get_require_external_execution_events(
+                reply_id,
+                self.tool_call_id_1,
+                self.sequential_tool_name,
+                self.tool_input_1,
+            ),
+        ]
+
+        basic_dict = self._get_event_base(reply_id)
+        self.assertListEqual(
+            events,
+            [{**basic_dict, **_} for _ in expected_events],
+        )
+
+        # Assert context after first call
+        msg_base = self._get_msg_base()
+        expected_context = [
+            {
+                "name": "user",
+                "role": "user",
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": self.user_input_text,
+                    },
+                ],
+                "finished_at": AnyString(),
+            },
+            {
+                "content": [
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_1,
+                        "name": self.sequential_tool_name,
+                        "input": self.tool_input_1,
+                        "state": "submitted",
+                        "suggested_rules": [],
+                    },
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_2,
+                        "name": self.sequential_tool_name,
+                        "input": self.tool_input_2,
+                        "state": "pending",
+                        "suggested_rules": [],
+                    },
+                ],
+            },
+        ]
+        context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+        expected_context = [{**msg_base, **_} for _ in expected_context]
+        self.assertListEqual(context_dicts, expected_context)
+
+        # Create external execution result event
+        external_result_event = ExternalExecutionResultEvent(
+            reply_id=reply_id,
+            execution_results=[
+                ToolResultBlock(
+                    id=self.tool_call_id_1,
+                    name=self.sequential_tool_name,
+                    output=[
+                        TextBlock(text=self.sequential_result_1),
+                    ],
+                    state=ToolResultState.SUCCESS,
+                ),
+            ],
+        )
+
+        # Second call: resume with external execution result
+        events = []
+        async for event in self.agent.reply_stream(
+            inputs=external_result_event,
+        ):
+            events.append(event.model_dump())
+
+        # Verify events after resumption (sequential execution)
+        expected_events_resume = [
+            *self._get_tool_result_events(
+                self.tool_call_id_1,
+                self.sequential_result_1,
+            ),
+            *self._get_require_external_execution_events(
+                reply_id,
+                self.tool_call_id_2,
+                self.sequential_tool_name,
+                self.tool_input_2,
+            ),
+        ]
+        self.assertListEqual(
+            events,
+            [{**basic_dict, **_} for _ in expected_events_resume],
+        )
+
+        # Given the external execution result of the second tool call
+        external_result_event = ExternalExecutionResultEvent(
+            reply_id=reply_id,
+            execution_results=[
+                ToolResultBlock(
+                    id=self.tool_call_id_2,
+                    name=self.sequential_tool_name,
+                    output=[
+                        TextBlock(text=self.sequential_result_2),
+                    ],
+                    state=ToolResultState.ERROR,
+                ),
+            ],
+        )
+
+        events = []
+        async for evnt in self.agent.reply_stream(
+            inputs=external_result_event,
+        ):
+            events.append(evnt.model_dump())
+
+        # Assert the events
+        expected_events_after_second_result = [
+            *self._get_tool_result_events(
+                self.tool_call_id_2,
+                self.sequential_result_2,
+                state="error",
+            ),
+            *self.final_text_events,
+            {
+                "type": "REPLY_END",
+                "session_id": session_id,
+                "finished_reason": "completed",
+            },
+        ]
+
+        self.assertListEqual(
+            events,
+            [{**basic_dict, **_} for _ in expected_events_after_second_result],
+        )
+
+        # Assert final context
+        expected_context_final = [
+            {
+                "name": "user",
+                "role": "user",
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": self.user_input_text,
+                    },
+                ],
+                "finished_at": AnyString(),
+            },
+            {
+                "content": [
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_1,
+                        "name": self.sequential_tool_name,
+                        "input": self.tool_input_1,
+                        "state": "finished",
+                        "suggested_rules": [],
+                    },
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_2,
+                        "name": self.sequential_tool_name,
+                        "input": self.tool_input_2,
+                        "state": "finished",
+                        "suggested_rules": [],
+                    },
+                    {
+                        "type": "tool_result",
+                        "id": AnyString(),
+                        "name": self.sequential_tool_name,
+                        "output": [
+                            {
+                                "type": "text",
+                                "id": AnyString(),
+                                "text": self.sequential_result_1,
+                            },
+                        ],
+                        "state": "success",
+                        "metadata": {},
+                    },
+                    {
+                        "type": "tool_result",
+                        "id": AnyString(),
+                        "name": self.sequential_tool_name,
+                        "output": [
+                            {
+                                "type": "text",
+                                "id": AnyString(),
+                                "text": self.sequential_result_2,
+                            },
+                        ],
+                        "state": "error",
+                        "metadata": {},
+                    },
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": self.final_response_text,
+                    },
+                ],
+            },
+        ]
+        context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+        expected_context_final = [
+            {**msg_base, **_} for _ in expected_context_final
+        ]
+        self.assertListEqual(context_dicts, expected_context_final)
+
+    async def test_concurrent_external_execution(self) -> None:
+        """Test multiple external execution tool calls in concurrent execution.
+
+        The agent should:
+        1. Generate multiple tool calls that require external execution
+        2. All tools have is_concurrent_safe=True (concurrent)
+        3. Emit REQUIRE_EXTERNAL_EXECUTION event and pause
+        4. Resume when ExternalExecutionResultEvent is provided
+        5. Continue execution without calling the model again
+        """
+        # Register external concurrent tool
+        ext_tool = MockExternalConcurrentTool()
+        self.agent.toolkit = Toolkit(
+            tools=[ext_tool],
+        )
+
+        # Set up mock response with multiple tool calls
+        self.model.set_responses(
+            [
+                [
+                    ChatResponse(
+                        content=[
+                            ToolCallBlock(
+                                id=self.tool_call_id_1,
+                                name=self.concurrent_tool_name,
+                                input=self.tool_input_1,
+                            ),
+                            ToolCallBlock(
+                                id=self.tool_call_id_2,
+                                name=self.concurrent_tool_name,
+                                input=self.tool_input_2,
+                            ),
+                        ],
+                        is_last=False,
+                        usage=None,
+                    ),
+                    ChatResponse(
+                        content=[
+                            ToolCallBlock(
+                                id=self.tool_call_id_1,
+                                name=self.concurrent_tool_name,
+                                input=self.tool_input_1,
+                            ),
+                            ToolCallBlock(
+                                id=self.tool_call_id_2,
+                                name=self.concurrent_tool_name,
+                                input=self.tool_input_2,
+                            ),
+                        ],
+                        is_last=True,
+                        usage=None,
+                    ),
+                ],
+                self.final_mock_responses,
+            ],
+        )
+
+        # First call: collect events until REQUIRE_EXTERNAL_EXECUTION
+        events = []
+        async for event in self.agent.reply_stream(
+            UserMsg(name="user", content=self.user_input_text),
+        ):
+            events.append(event.model_dump())
+
+        # Verify events
+        session_id = self.agent.state.session_id
+        reply_id = self.agent.state.reply_id
+        tool_call_1_events = self._get_tool_call_events(
+            self.tool_call_id_1,
+            self.concurrent_tool_name,
+            self.tool_input_1,
+        )
+        tool_call_2_events = self._get_tool_call_events(
+            self.tool_call_id_2,
+            self.concurrent_tool_name,
+            self.tool_input_2,
+        )
+
+        expected_events = [
+            {
+                "type": "REPLY_START",
+                "session_id": session_id,
+                "name": "Friday",
+                "role": "assistant",
+            },
+            {"type": "MODEL_CALL_START", "model_name": "mock-model"},
+            *tool_call_1_events[:2],
+            *tool_call_2_events[:2],
+            tool_call_1_events[2],
+            tool_call_2_events[2],
+            {
+                "type": "MODEL_CALL_END",
+                "input_tokens": 0,
+                "output_tokens": 0,
+                "finished_reason": "completed",
+            },
+            *self._get_require_external_execution_events(
+                reply_id,
+                self.tool_call_id_1,
+                self.concurrent_tool_name,
+                self.tool_input_1,
+            ),
+            *self._get_require_external_execution_events(
+                reply_id,
+                self.tool_call_id_2,
+                self.concurrent_tool_name,
+                self.tool_input_2,
+            ),
+        ]
+
+        basic_dict = self._get_event_base(reply_id)
+        self.assertListEqual(
+            events,
+            [{**basic_dict, **_} for _ in expected_events],
+        )
+
+        # Assert context after first call
+        msg_base = self._get_msg_base()
+        expected_context = [
+            {
+                "name": "user",
+                "role": "user",
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": self.user_input_text,
+                    },
+                ],
+                "finished_at": AnyString(),
+            },
+            {
+                "content": [
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_1,
+                        "name": self.concurrent_tool_name,
+                        "input": self.tool_input_1,
+                        "state": "submitted",
+                        "suggested_rules": [],
+                    },
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_2,
+                        "name": self.concurrent_tool_name,
+                        "input": self.tool_input_2,
+                        "state": "submitted",
+                        "suggested_rules": [],
+                    },
+                ],
+            },
+        ]
+        context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+        expected_context = [{**msg_base, **_} for _ in expected_context]
+        self.assertListEqual(context_dicts, expected_context)
+
+        # Create external execution result event
+        external_result_event = ExternalExecutionResultEvent(
+            reply_id=reply_id,
+            execution_results=[
+                ToolResultBlock(
+                    id=self.tool_call_id_1,
+                    name=self.concurrent_tool_name,
+                    output=[
+                        TextBlock(text=self.concurrent_result_1),
+                    ],
+                    state=ToolResultState.SUCCESS,
+                ),
+            ],
+        )
+
+        # Second call: resume with external execution result
+        events = []
+        async for event in self.agent.reply_stream(
+            inputs=external_result_event,
+        ):
+            events.append(event.model_dump())
+
+        expected_concurrent = [
+            *self._get_tool_result_events(
+                self.tool_call_id_1,
+                self.concurrent_result_1,
+            ),
+        ]
+
+        self.assertListEqual(
+            events,
+            [{**basic_dict, **_} for _ in expected_concurrent],
+        )
+
+        # The second tool call result
+        external_result_event = ExternalExecutionResultEvent(
+            reply_id=reply_id,
+            execution_results=[
+                ToolResultBlock(
+                    id=self.tool_call_id_2,
+                    name=self.concurrent_tool_name,
+                    output=[
+                        TextBlock(text=self.concurrent_result_2),
+                    ],
+                    state=ToolResultState.SUCCESS,
+                ),
+            ],
+        )
+
+        events = []
+        async for event in self.agent.reply_stream(
+            inputs=external_result_event,
+        ):
+            events.append(event.model_dump())
+
+        expected_concurrent = [
+            *self._get_tool_result_events(
+                self.tool_call_id_2,
+                self.concurrent_result_2,
+            ),
+            *self.final_text_events,
+            {
+                "type": "REPLY_END",
+                "session_id": session_id,
+                "finished_reason": "completed",
+            },
+        ]
+
+        self.assertListEqual(
+            events,
+            [{**basic_dict, **_} for _ in expected_concurrent],
+        )
+
+        # Assert final context
+        expected_context_final = [
+            {
+                "name": "user",
+                "role": "user",
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": self.user_input_text,
+                    },
+                ],
+                "finished_at": AnyString(),
+            },
+            {
+                "content": [
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_1,
+                        "name": self.concurrent_tool_name,
+                        "input": self.tool_input_1,
+                        "state": "finished",
+                        "suggested_rules": [],
+                    },
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_2,
+                        "name": self.concurrent_tool_name,
+                        "input": self.tool_input_2,
+                        "state": "finished",
+                        "suggested_rules": [],
+                    },
+                    {
+                        "type": "tool_result",
+                        "id": AnyString(),
+                        "name": self.concurrent_tool_name,
+                        "output": [
+                            {
+                                "type": "text",
+                                "id": AnyString(),
+                                "text": self.concurrent_result_1,
+                            },
+                        ],
+                        "state": "success",
+                        "metadata": {},
+                    },
+                    {
+                        "type": "tool_result",
+                        "id": AnyString(),
+                        "name": self.concurrent_tool_name,
+                        "output": [
+                            {
+                                "type": "text",
+                                "id": AnyString(),
+                                "text": self.concurrent_result_2,
+                            },
+                        ],
+                        "state": "success",
+                        "metadata": {},
+                    },
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": self.final_response_text,
+                    },
+                ],
+            },
+        ]
+        context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+        expected_context_final = [
+            {**msg_base, **_} for _ in expected_context_final
+        ]
+        self.assertListEqual(context_dicts, expected_context_final)
+
+    async def test_concurrent_external_execution_in_single_event(self) -> None:
+        """Test concurrent external execution when two results arrive together.
+
+        The agent should:
+        1. Generate multiple external tool calls in concurrent mode
+        2. Emit one require event per tool call during the initial run
+        3. Resume when a single ExternalExecutionResultEvent carries both
+           results
+        4. Continue reasoning only after both results are applied
+        """
+        ext_tool = MockExternalConcurrentTool()
+        self.agent.toolkit = Toolkit(
+            tools=[ext_tool],
+        )
+
+        self.model.set_responses(
+            [
+                [
+                    ChatResponse(
+                        content=[
+                            ToolCallBlock(
+                                id=self.tool_call_id_1,
+                                name=self.concurrent_tool_name,
+                                input=self.tool_input_1,
+                            ),
+                            ToolCallBlock(
+                                id=self.tool_call_id_2,
+                                name=self.concurrent_tool_name,
+                                input=self.tool_input_2,
+                            ),
+                        ],
+                        is_last=False,
+                        usage=None,
+                    ),
+                    ChatResponse(
+                        content=[
+                            ToolCallBlock(
+                                id=self.tool_call_id_1,
+                                name=self.concurrent_tool_name,
+                                input=self.tool_input_1,
+                            ),
+                            ToolCallBlock(
+                                id=self.tool_call_id_2,
+                                name=self.concurrent_tool_name,
+                                input=self.tool_input_2,
+                            ),
+                        ],
+                        is_last=True,
+                        usage=None,
+                    ),
+                ],
+                self.final_mock_responses,
+            ],
+        )
+
+        events = []
+        async for event in self.agent.reply_stream(
+            UserMsg(name="user", content=self.user_input_text),
+        ):
+            events.append(event.model_dump())
+
+        session_id = self.agent.state.session_id
+        reply_id = self.agent.state.reply_id
+        basic_dict = self._get_event_base(reply_id)
+        msg_base = self._get_msg_base()
+        tool_call_1_events = self._get_tool_call_events(
+            self.tool_call_id_1,
+            self.concurrent_tool_name,
+            self.tool_input_1,
+        )
+        tool_call_2_events = self._get_tool_call_events(
+            self.tool_call_id_2,
+            self.concurrent_tool_name,
+            self.tool_input_2,
+        )
+
+        expected_events = [
+            {
+                "type": "REPLY_START",
+                "session_id": session_id,
+                "name": "Friday",
+                "role": "assistant",
+            },
+            {"type": "MODEL_CALL_START", "model_name": "mock-model"},
+            *tool_call_1_events[:2],
+            *tool_call_2_events[:2],
+            tool_call_1_events[2],
+            tool_call_2_events[2],
+            {
+                "type": "MODEL_CALL_END",
+                "input_tokens": 0,
+                "output_tokens": 0,
+                "finished_reason": "completed",
+            },
+            *self._get_require_external_execution_events(
+                reply_id,
+                self.tool_call_id_1,
+                self.concurrent_tool_name,
+                self.tool_input_1,
+            ),
+            *self._get_require_external_execution_events(
+                reply_id,
+                self.tool_call_id_2,
+                self.concurrent_tool_name,
+                self.tool_input_2,
+            ),
+        ]
+        self.assertListEqual(
+            events,
+            [{**basic_dict, **_} for _ in expected_events],
+        )
+
+        expected_context = [
+            {
+                "name": "user",
+                "role": "user",
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": self.user_input_text,
+                    },
+                ],
+                "finished_at": AnyString(),
+            },
+            {
+                "content": [
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_1,
+                        "name": self.concurrent_tool_name,
+                        "input": self.tool_input_1,
+                        "state": "submitted",
+                        "suggested_rules": [],
+                    },
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_2,
+                        "name": self.concurrent_tool_name,
+                        "input": self.tool_input_2,
+                        "state": "submitted",
+                        "suggested_rules": [],
+                    },
+                ],
+            },
+        ]
+        context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+        expected_context = [{**msg_base, **_} for _ in expected_context]
+        self.assertListEqual(context_dicts, expected_context)
+
+        external_result_event = ExternalExecutionResultEvent(
+            reply_id=reply_id,
+            execution_results=[
+                ToolResultBlock(
+                    id=self.tool_call_id_1,
+                    name=self.concurrent_tool_name,
+                    output=[
+                        TextBlock(text=self.concurrent_result_1),
+                    ],
+                    state=ToolResultState.SUCCESS,
+                ),
+                ToolResultBlock(
+                    id=self.tool_call_id_2,
+                    name=self.concurrent_tool_name,
+                    output=[
+                        TextBlock(text=self.concurrent_result_2),
+                    ],
+                    state=ToolResultState.SUCCESS,
+                ),
+            ],
+        )
+
+        events = []
+        async for event in self.agent.reply_stream(
+            inputs=external_result_event,
+        ):
+            events.append(event.model_dump())
+
+        expected_events_resume = [
+            *self._get_tool_result_events(
+                self.tool_call_id_1,
+                self.concurrent_result_1,
+            ),
+            *self._get_tool_result_events(
+                self.tool_call_id_2,
+                self.concurrent_result_2,
+            ),
+            *self.final_text_events,
+            {
+                "type": "REPLY_END",
+                "session_id": session_id,
+                "finished_reason": "completed",
+            },
+        ]
+        self.assertListEqual(
+            events,
+            [{**basic_dict, **_} for _ in expected_events_resume],
+        )
+
+        expected_context_final = [
+            {
+                "name": "user",
+                "role": "user",
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": self.user_input_text,
+                    },
+                ],
+                "finished_at": AnyString(),
+            },
+            {
+                "content": [
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_1,
+                        "name": self.concurrent_tool_name,
+                        "input": self.tool_input_1,
+                        "state": "finished",
+                        "suggested_rules": [],
+                    },
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_2,
+                        "name": self.concurrent_tool_name,
+                        "input": self.tool_input_2,
+                        "state": "finished",
+                        "suggested_rules": [],
+                    },
+                    {
+                        "type": "tool_result",
+                        "id": AnyString(),
+                        "name": self.concurrent_tool_name,
+                        "output": [
+                            {
+                                "type": "text",
+                                "id": AnyString(),
+                                "text": self.concurrent_result_1,
+                            },
+                        ],
+                        "state": "success",
+                        "metadata": {},
+                    },
+                    {
+                        "type": "tool_result",
+                        "id": AnyString(),
+                        "name": self.concurrent_tool_name,
+                        "output": [
+                            {
+                                "type": "text",
+                                "id": AnyString(),
+                                "text": self.concurrent_result_2,
+                            },
+                        ],
+                        "state": "success",
+                        "metadata": {},
+                    },
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": self.final_response_text,
+                    },
+                ],
+            },
+        ]
+        context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+        expected_context_final = [
+            {**msg_base, **_} for _ in expected_context_final
+        ]
+        self.assertListEqual(context_dicts, expected_context_final)
+
+    async def asyncTearDown(self) -> None:
+        """The async teardown method."""
diff --git a/tests/hitl_mixed_interrupt.py b/tests/hitl_mixed_interrupt.py
new file mode 100644
index 0000000..bee97b1
--- /dev/null
+++ b/tests/hitl_mixed_interrupt.py
@@ -0,0 +1,1201 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=redefined-builtin
+"""Test mixed user confirmation and external execution in the agent."""
+from typing import Any
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from utils import AnyString, MockModel
+
+from agentscope.agent import Agent
+from agentscope.model import ChatResponse
+from agentscope.tool import (
+    ToolBase,
+    Toolkit,
+    ToolChunk,
+)
+from agentscope.permission import (
+    PermissionDecision,
+    PermissionBehavior,
+    PermissionContext,
+)
+from agentscope.message import (
+    TextBlock,
+    ToolCallBlock,
+    ToolResultBlock,
+    UserMsg,
+    ToolResultState,
+)
+from agentscope.event import (
+    UserConfirmResultEvent,
+    ExternalExecutionResultEvent,
+    ConfirmResult,
+)
+
+
+class MockMixedSequentialTool(ToolBase):
+    """A mock tool that requires confirmation and external execution."""
+
+    name: str = "mock_mixed_sequential_tool"
+    description: str = "A mock mixed sequential tool for testing"
+    input_schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {
+            "input": {"type": "string", "description": "Input string"},
+        },
+        "required": ["input"],
+    }
+    is_concurrency_safe: bool = False
+    is_read_only: bool = False
+    is_external_tool: bool = True
+    is_mcp: bool = False
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        """Check permissions for the tool usage."""
+        return PermissionDecision(
+            behavior=PermissionBehavior.ASK,
+            decision_reason="Mock mixed tool requires user confirmation",
+            message="Mock mixed tool requires user confirmation",
+        )
+
+    async def __call__(self, input: str, **kwargs: Any) -> ToolChunk:
+        """Execute the tool."""
+        return ToolChunk(
+            content=[TextBlock(text=f"Mixed sequential result: {input}")],
+        )
+
+
+class MockMixedConcurrentTool(ToolBase):
+    """A mock tool that requires confirmation and external execution."""
+
+    name: str = "mock_mixed_concurrent_tool"
+    description: str = "A mock mixed concurrent tool for testing"
+    input_schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {
+            "input": {"type": "string", "description": "Input string"},
+        },
+        "required": ["input"],
+    }
+    is_concurrency_safe: bool = True
+    is_read_only: bool = False
+    is_external_tool: bool = True
+    is_mcp: bool = False
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        """Check permissions for the tool usage."""
+        return PermissionDecision(
+            behavior=PermissionBehavior.ASK,
+            decision_reason="Mock mixed tool requires user confirmation",
+            message="Mock mixed tool requires user confirmation",
+        )
+
+    async def __call__(self, input: str, **kwargs: Any) -> ToolChunk:
+        """Execute the tool."""
+        return ToolChunk(
+            content=[TextBlock(text=f"Mixed concurrent result: {input}")],
+        )
+
+
+class AgentMixTest(IsolatedAsyncioTestCase):
+    """Test mixed user confirmation and external execution."""
+
+    async def asyncSetUp(self) -> None:
+        """The async setup method."""
+        self.model = MockModel()
+        self.agent = Agent(
+            name="Friday",
+            system_prompt="You are a helpful assistant.",
+            model=self.model,
+            toolkit=Toolkit(),
+        )
+        self.tool_call_id_1 = "tool_call_1"
+        self.tool_call_id_2 = "tool_call_2"
+        self.user_input_text = "Test"
+        self.tool_input_1 = '{"input": "test1"}'
+        self.tool_input_2 = '{"input": "test2"}'
+        self.sequential_tool_name = "mock_mixed_sequential_tool"
+        self.concurrent_tool_name = "mock_mixed_concurrent_tool"
+        self.sequential_result_1 = "Mixed sequential result: test1"
+        self.sequential_result_2 = "Mixed sequential result: test2"
+        self.concurrent_result_1 = "Mixed concurrent result: test1"
+        self.concurrent_result_2 = "Mixed concurrent result: test2"
+        self.final_response_text = "Final response after mixed execution"
+        self.final_text_events = [
+            {
+                "type": "MODEL_CALL_START",
+                "model_name": "mock-model",
+            },
+            {
+                "type": "TEXT_BLOCK_START",
+                "block_id": AnyString(),
+            },
+            {
+                "type": "TEXT_BLOCK_DELTA",
+                "block_id": AnyString(),
+                "delta": self.final_response_text,
+            },
+            {
+                "type": "TEXT_BLOCK_END",
+                "block_id": AnyString(),
+            },
+            {
+                "type": "MODEL_CALL_END",
+                "input_tokens": 0,
+                "output_tokens": 0,
+            },
+        ]
+        self.final_mock_responses = [
+            ChatResponse(
+                content=[TextBlock(text=self.final_response_text)],
+                is_last=False,
+                usage=None,
+            ),
+            ChatResponse(
+                content=[TextBlock(text=self.final_response_text)],
+                is_last=True,
+                usage=None,
+            ),
+        ]
+
+    def _get_event_base(self, reply_id: str) -> dict:
+        """Get the dict with the basic fields for event assertion."""
+        return {
+            "id": AnyString(),
+            "created_at": AnyString(),
+            "reply_id": reply_id,
+        }
+
+    def _get_msg_base(self) -> dict:
+        """Get the dict with the basic fields for message assertion."""
+        return {
+            "id": AnyString(),
+            "created_at": AnyString(),
+            "metadata": {},
+            "name": "Friday",
+            "role": "assistant",
+        }
+
+    def _get_tool_call_events(
+        self,
+        id: str,
+        name: str,
+        delta: str,
+    ) -> list[dict]:
+        """Helper method to get the expected tool call events."""
+        return [
+            {
+                "type": "TOOL_CALL_START",
+                "tool_call_id": id,
+                "tool_call_name": name,
+            },
+            {
+                "type": "TOOL_CALL_DELTA",
+                "tool_call_id": id,
+                "delta": delta,
+            },
+            {
+                "type": "TOOL_CALL_END",
+                "tool_call_id": id,
+            },
+        ]
+
+    def _get_tool_result_events(
+        self,
+        id: str,
+        result: str,
+        state: str = "success",
+    ) -> list[dict]:
+        """Helper method to get the expected tool result events."""
+        return [
+            {
+                "type": "TOOL_RESULT_TEXT_DELTA",
+                "tool_call_id": id,
+                "delta": result,
+            },
+            {
+                "type": "TOOL_RESULT_END",
+                "tool_call_id": id,
+                "state": state,
+            },
+        ]
+
+    def _get_require_user_confirm_event(
+        self,
+        reply_id: str,
+        id: str,
+        name: str,
+        tool_input: str,
+    ) -> dict:
+        """Helper method to get the expected user confirmation event."""
+        return {
+            "type": "REQUIRE_USER_CONFIRM",
+            "reply_id": reply_id,
+            "tool_calls": [
+                {
+                    "type": "tool_call",
+                    "id": id,
+                    "name": name,
+                    "input": tool_input,
+                    "state": "asking",
+                },
+            ],
+        }
+
+    def _get_require_external_execution_events(
+        self,
+        reply_id: str,
+        id: str,
+        name: str,
+        tool_input: str,
+    ) -> list[dict]:
+        """Helper method to get the expected external execution events."""
+        return [
+            {
+                "type": "TOOL_RESULT_START",
+                "tool_call_id": id,
+                "tool_call_name": name,
+            },
+            {
+                "type": "REQUIRE_EXTERNAL_EXECUTION",
+                "reply_id": reply_id,
+                "tool_calls": [
+                    {
+                        "type": "tool_call",
+                        "id": id,
+                        "name": name,
+                        "input": tool_input,
+                        "state": "submitted",
+                    },
+                ],
+            },
+        ]
+
+    def _get_tool_call_block(
+        self,
+        id: str,
+        name: str,
+        tool_input: str,
+    ) -> ToolCallBlock:
+        """Build a tool call block."""
+        return ToolCallBlock(id=id, name=name, input=tool_input)
+
+    def _get_tool_result_block(
+        self,
+        id: str,
+        name: str,
+        result: str,
+        state: ToolResultState = ToolResultState.SUCCESS,
+    ) -> ToolResultBlock:
+        """Build a tool result block."""
+        return ToolResultBlock(
+            id=id,
+            name=name,
+            output=[TextBlock(text=result)],
+            state=state,
+        )
+
+    def _get_confirm_result(
+        self,
+        id: str,
+        name: str,
+        tool_input: str,
+    ) -> ConfirmResult:
+        """Build a confirmation result."""
+        return ConfirmResult(
+            confirmed=True,
+            tool_call=self._get_tool_call_block(id, name, tool_input),
+        )
+
+    def _build_tool_calls(
+        self,
+        tool_calls: list[tuple[str, str, str]],
+    ) -> list[ToolCallBlock]:
+        """Build tool call blocks for mock model responses."""
+        return [
+            self._get_tool_call_block(id, name, tool_input)
+            for id, name, tool_input in tool_calls
+        ]
+
+    def _set_model_tool_call_responses(
+        self,
+        tool_calls: list[tuple[str, str, str]],
+    ) -> None:
+        """Set mock model responses that emit tool calls then final text."""
+        self.model.set_responses(
+            [
+                [
+                    ChatResponse(
+                        content=self._build_tool_calls(tool_calls),
+                        is_last=False,
+                        usage=None,
+                    ),
+                    ChatResponse(
+                        content=self._build_tool_calls(tool_calls),
+                        is_last=True,
+                        usage=None,
+                    ),
+                ],
+                self.final_mock_responses,
+            ],
+        )
+
+    async def test_single_user_confirmation_and_external_execution(
+        self,
+    ) -> None:
+        """Test one tool call that needs confirmation and external
+        execution."""
+        mixed_tool = MockMixedSequentialTool()
+        self.agent.toolkit = Toolkit(tools=[mixed_tool])
+
+        self._set_model_tool_call_responses(
+            [
+                (
+                    self.tool_call_id_1,
+                    self.sequential_tool_name,
+                    self.tool_input_1,
+                ),
+            ],
+        )
+
+        events = []
+        async for event in self.agent.reply_stream(
+            UserMsg(name="user", content=self.user_input_text),
+        ):
+            events.append(event.model_dump())
+
+        session_id = self.agent.state.session_id
+        reply_id = self.agent.state.reply_id
+        basic_dict = self._get_event_base(reply_id)
+        msg_base = self._get_msg_base()
+
+        expected_events = [
+            {
+                "type": "REPLY_START",
+                "session_id": session_id,
+                "name": "Friday",
+                "role": "assistant",
+            },
+            {"type": "MODEL_CALL_START", "model_name": "mock-model"},
+            *self._get_tool_call_events(
+                self.tool_call_id_1,
+                self.sequential_tool_name,
+                self.tool_input_1,
+            ),
+            {
+                "type": "MODEL_CALL_END",
+                "input_tokens": 0,
+                "output_tokens": 0,
+            },
+            self._get_require_user_confirm_event(
+                reply_id,
+                self.tool_call_id_1,
+                self.sequential_tool_name,
+                self.tool_input_1,
+            ),
+        ]
+        self.assertListEqual(
+            events,
+            [{**basic_dict, **_} for _ in expected_events],
+        )
+
+        expected_context = [
+            {
+                "name": "user",
+                "role": "user",
+                "content": self.user_input_text,
+            },
+            {
+                "content": [
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_1,
+                        "name": self.sequential_tool_name,
+                        "input": self.tool_input_1,
+                        "state": "asking",
+                    },
+                ],
+            },
+        ]
+        context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+        expected_context = [{**msg_base, **_} for _ in expected_context]
+        self.assertListEqual(context_dicts, expected_context)
+
+        user_confirm_event = UserConfirmResultEvent(
+            reply_id=reply_id,
+            confirm_results=[
+                self._get_confirm_result(
+                    self.tool_call_id_1,
+                    self.sequential_tool_name,
+                    self.tool_input_1,
+                ),
+            ],
+        )
+
+        events = []
+        async for event in self.agent.reply_stream(inputs=user_confirm_event):
+            events.append(event.model_dump())
+
+        expected_events_resume = self._get_require_external_execution_events(
+            reply_id,
+            self.tool_call_id_1,
+            self.sequential_tool_name,
+            self.tool_input_1,
+        )
+        self.assertListEqual(
+            events,
+            [{**basic_dict, **_} for _ in expected_events_resume],
+        )
+
+        expected_context = [
+            {
+                "name": "user",
+                "role": "user",
+                "content": self.user_input_text,
+            },
+            {
+                "content": [
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_1,
+                        "name": self.sequential_tool_name,
+                        "input": self.tool_input_1,
+                        "state": "submitted",
+                    },
+                ],
+            },
+        ]
+        context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+        expected_context = [{**msg_base, **_} for _ in expected_context]
+        self.assertListEqual(context_dicts, expected_context)
+
+        external_result_event = ExternalExecutionResultEvent(
+            reply_id=reply_id,
+            execution_results=[
+                self._get_tool_result_block(
+                    self.tool_call_id_1,
+                    self.sequential_tool_name,
+                    self.sequential_result_1,
+                ),
+            ],
+        )
+
+        events = []
+        async for event in self.agent.reply_stream(
+            inputs=external_result_event,
+        ):
+            events.append(event.model_dump())
+
+        expected_events_after_result = [
+            *self._get_tool_result_events(
+                self.tool_call_id_1,
+                self.sequential_result_1,
+            ),
+            *self.final_text_events,
+            {"type": "REPLY_END", "session_id": session_id},
+        ]
+        self.assertListEqual(
+            events,
+            [{**basic_dict, **_} for _ in expected_events_after_result],
+        )
+
+        expected_context_final = [
+            {
+                "name": "user",
+                "role": "user",
+                "content": self.user_input_text,
+            },
+            {
+                "content": [
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_1,
+                        "name": self.sequential_tool_name,
+                        "input": self.tool_input_1,
+                        "state": "finished",
+                    },
+                    {
+                        "type": "tool_result",
+                        "id": AnyString(),
+                        "name": self.sequential_tool_name,
+                        "output": [
+                            {
+                                "type": "text",
+                                "id": AnyString(),
+                                "text": self.sequential_result_1,
+                            },
+                        ],
+                        "state": "success",
+                    },
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": self.final_response_text,
+                    },
+                ],
+            },
+        ]
+        context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+        expected_context_final = [
+            {**msg_base, **_} for _ in expected_context_final
+        ]
+        self.assertListEqual(context_dicts, expected_context_final)
+
+    async def test_sequential_user_confirmation_and_external_execution(
+        self,
+    ) -> None:
+        """Test sequential tool calls that need confirmation and external
+        execution."""
+        mixed_tool = MockMixedSequentialTool()
+        self.agent.toolkit = Toolkit(tools=[mixed_tool])
+
+        self._set_model_tool_call_responses(
+            [
+                (
+                    self.tool_call_id_1,
+                    self.sequential_tool_name,
+                    self.tool_input_1,
+                ),
+                (
+                    self.tool_call_id_2,
+                    self.sequential_tool_name,
+                    self.tool_input_2,
+                ),
+            ],
+        )
+
+        events = []
+        async for event in self.agent.reply_stream(
+            UserMsg(name="user", content=self.user_input_text),
+        ):
+            events.append(event.model_dump())
+
+        session_id = self.agent.state.session_id
+        reply_id = self.agent.state.reply_id
+        basic_dict = self._get_event_base(reply_id)
+        msg_base = self._get_msg_base()
+        tool_call_1_events = self._get_tool_call_events(
+            self.tool_call_id_1,
+            self.sequential_tool_name,
+            self.tool_input_1,
+        )
+        tool_call_2_events = self._get_tool_call_events(
+            self.tool_call_id_2,
+            self.sequential_tool_name,
+            self.tool_input_2,
+        )
+
+        expected_events = [
+            {
+                "type": "REPLY_START",
+                "session_id": session_id,
+                "name": "Friday",
+                "role": "assistant",
+            },
+            {"type": "MODEL_CALL_START", "model_name": "mock-model"},
+            *tool_call_1_events[:2],
+            *tool_call_2_events[:2],
+            tool_call_1_events[2],
+            tool_call_2_events[2],
+            {
+                "type": "MODEL_CALL_END",
+                "input_tokens": 0,
+                "output_tokens": 0,
+            },
+            self._get_require_user_confirm_event(
+                reply_id,
+                self.tool_call_id_1,
+                self.sequential_tool_name,
+                self.tool_input_1,
+            ),
+        ]
+        self.assertListEqual(
+            events,
+            [{**basic_dict, **_} for _ in expected_events],
+        )
+
+        expected_context = [
+            {
+                "name": "user",
+                "role": "user",
+                "content": self.user_input_text,
+            },
+            {
+                "content": [
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_1,
+                        "name": self.sequential_tool_name,
+                        "input": self.tool_input_1,
+                        "state": "asking",
+                    },
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_2,
+                        "name": self.sequential_tool_name,
+                        "input": self.tool_input_2,
+                        "state": "pending",
+                    },
+                ],
+            },
+        ]
+        context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+        expected_context = [{**msg_base, **_} for _ in expected_context]
+        self.assertListEqual(context_dicts, expected_context)
+
+        user_confirm_event = UserConfirmResultEvent(
+            reply_id=reply_id,
+            confirm_results=[
+                self._get_confirm_result(
+                    self.tool_call_id_1,
+                    self.sequential_tool_name,
+                    self.tool_input_1,
+                ),
+            ],
+        )
+
+        events = []
+        async for event in self.agent.reply_stream(inputs=user_confirm_event):
+            events.append(event.model_dump())
+
+        expected_events_resume = self._get_require_external_execution_events(
+            reply_id,
+            self.tool_call_id_1,
+            self.sequential_tool_name,
+            self.tool_input_1,
+        )
+        self.assertListEqual(
+            events,
+            [{**basic_dict, **_} for _ in expected_events_resume],
+        )
+
+        expected_context = [
+            {
+                "name": "user",
+                "role": "user",
+                "content": self.user_input_text,
+            },
+            {
+                "content": [
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_1,
+                        "name": self.sequential_tool_name,
+                        "input": self.tool_input_1,
+                        "state": "submitted",
+                    },
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_2,
+                        "name": self.sequential_tool_name,
+                        "input": self.tool_input_2,
+                        "state": "pending",
+                    },
+                ],
+            },
+        ]
+        context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+        expected_context = [{**msg_base, **_} for _ in expected_context]
+        self.assertListEqual(context_dicts, expected_context)
+
+        external_result_event = ExternalExecutionResultEvent(
+            reply_id=reply_id,
+            execution_results=[
+                self._get_tool_result_block(
+                    self.tool_call_id_1,
+                    self.sequential_tool_name,
+                    self.sequential_result_1,
+                ),
+            ],
+        )
+
+        events = []
+        async for event in self.agent.reply_stream(
+            inputs=external_result_event,
+        ):
+            events.append(event.model_dump())
+
+        expected_events_after_first_result = [
+            *self._get_tool_result_events(
+                self.tool_call_id_1,
+                self.sequential_result_1,
+            ),
+            self._get_require_user_confirm_event(
+                reply_id,
+                self.tool_call_id_2,
+                self.sequential_tool_name,
+                self.tool_input_2,
+            ),
+        ]
+        self.assertListEqual(
+            events,
+            [{**basic_dict, **_} for _ in expected_events_after_first_result],
+        )
+
+        expected_context = [
+            {
+                "name": "user",
+                "role": "user",
+                "content": self.user_input_text,
+            },
+            {
+                "content": [
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_1,
+                        "name": self.sequential_tool_name,
+                        "input": self.tool_input_1,
+                        "state": "finished",
+                    },
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_2,
+                        "name": self.sequential_tool_name,
+                        "input": self.tool_input_2,
+                        "state": "asking",
+                    },
+                    {
+                        "type": "tool_result",
+                        "id": AnyString(),
+                        "name": self.sequential_tool_name,
+                        "output": [
+                            {
+                                "type": "text",
+                                "id": AnyString(),
+                                "text": self.sequential_result_1,
+                            },
+                        ],
+                        "state": "success",
+                    },
+                ],
+            },
+        ]
+        context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+        expected_context = [{**msg_base, **_} for _ in expected_context]
+        self.assertListEqual(context_dicts, expected_context)
+
+        user_confirm_event = UserConfirmResultEvent(
+            reply_id=reply_id,
+            confirm_results=[
+                self._get_confirm_result(
+                    self.tool_call_id_2,
+                    self.sequential_tool_name,
+                    self.tool_input_2,
+                ),
+            ],
+        )
+
+        events = []
+        async for event in self.agent.reply_stream(inputs=user_confirm_event):
+            events.append(event.model_dump())
+
+        expected_events_after_second_confirm = (
+            self._get_require_external_execution_events(
+                reply_id,
+                self.tool_call_id_2,
+                self.sequential_tool_name,
+                self.tool_input_2,
+            )
+        )
+        self.assertListEqual(
+            events,
+            [
+                {**basic_dict, **_}
+                for _ in expected_events_after_second_confirm
+            ],
+        )
+
+        external_result_event = ExternalExecutionResultEvent(
+            reply_id=reply_id,
+            execution_results=[
+                self._get_tool_result_block(
+                    self.tool_call_id_2,
+                    self.sequential_tool_name,
+                    self.sequential_result_2,
+                ),
+            ],
+        )
+
+        events = []
+        async for event in self.agent.reply_stream(
+            inputs=external_result_event,
+        ):
+            events.append(event.model_dump())
+
+        expected_events_after_second_result = [
+            *self._get_tool_result_events(
+                self.tool_call_id_2,
+                self.sequential_result_2,
+            ),
+            *self.final_text_events,
+            {"type": "REPLY_END", "session_id": session_id},
+        ]
+        self.assertListEqual(
+            events,
+            [{**basic_dict, **_} for _ in expected_events_after_second_result],
+        )
+
+        expected_context_final = [
+            {
+                "name": "user",
+                "role": "user",
+                "content": self.user_input_text,
+            },
+            {
+                "content": [
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_1,
+                        "name": self.sequential_tool_name,
+                        "input": self.tool_input_1,
+                        "state": "finished",
+                    },
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_2,
+                        "name": self.sequential_tool_name,
+                        "input": self.tool_input_2,
+                        "state": "finished",
+                    },
+                    {
+                        "type": "tool_result",
+                        "id": AnyString(),
+                        "name": self.sequential_tool_name,
+                        "output": [
+                            {
+                                "type": "text",
+                                "id": AnyString(),
+                                "text": self.sequential_result_1,
+                            },
+                        ],
+                        "state": "success",
+                    },
+                    {
+                        "type": "tool_result",
+                        "id": AnyString(),
+                        "name": self.sequential_tool_name,
+                        "output": [
+                            {
+                                "type": "text",
+                                "id": AnyString(),
+                                "text": self.sequential_result_2,
+                            },
+                        ],
+                        "state": "success",
+                    },
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": self.final_response_text,
+                    },
+                ],
+            },
+        ]
+        context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+        expected_context_final = [
+            {**msg_base, **_} for _ in expected_context_final
+        ]
+        self.assertListEqual(context_dicts, expected_context_final)
+
+    async def test_concurrent_user_confirmation_and_external_execution(
+        self,
+    ) -> None:
+        """Test concurrent tool calls that need confirmation and external
+        execution."""
+        mixed_tool = MockMixedConcurrentTool()
+        self.agent.toolkit = Toolkit(tools=[mixed_tool])
+
+        self._set_model_tool_call_responses(
+            [
+                (
+                    self.tool_call_id_1,
+                    self.concurrent_tool_name,
+                    self.tool_input_1,
+                ),
+                (
+                    self.tool_call_id_2,
+                    self.concurrent_tool_name,
+                    self.tool_input_2,
+                ),
+            ],
+        )
+
+        events = []
+        async for event in self.agent.reply_stream(
+            UserMsg(name="user", content=self.user_input_text),
+        ):
+            events.append(event.model_dump())
+
+        session_id = self.agent.state.session_id
+        reply_id = self.agent.state.reply_id
+        basic_dict = self._get_event_base(reply_id)
+        msg_base = self._get_msg_base()
+        tool_call_1_events = self._get_tool_call_events(
+            self.tool_call_id_1,
+            self.concurrent_tool_name,
+            self.tool_input_1,
+        )
+        tool_call_2_events = self._get_tool_call_events(
+            self.tool_call_id_2,
+            self.concurrent_tool_name,
+            self.tool_input_2,
+        )
+
+        expected_events = [
+            {
+                "type": "REPLY_START",
+                "session_id": session_id,
+                "name": "Friday",
+                "role": "assistant",
+            },
+            {"type": "MODEL_CALL_START", "model_name": "mock-model"},
+            *tool_call_1_events[:2],
+            *tool_call_2_events[:2],
+            tool_call_1_events[2],
+            tool_call_2_events[2],
+            {
+                "type": "MODEL_CALL_END",
+                "input_tokens": 0,
+                "output_tokens": 0,
+            },
+            self._get_require_user_confirm_event(
+                reply_id,
+                self.tool_call_id_1,
+                self.concurrent_tool_name,
+                self.tool_input_1,
+            ),
+            self._get_require_user_confirm_event(
+                reply_id,
+                self.tool_call_id_2,
+                self.concurrent_tool_name,
+                self.tool_input_2,
+            ),
+        ]
+        self.assertListEqual(
+            events,
+            [{**basic_dict, **_} for _ in expected_events],
+        )
+
+        expected_context = [
+            {
+                "name": "user",
+                "role": "user",
+                "content": self.user_input_text,
+            },
+            {
+                "content": [
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_1,
+                        "name": self.concurrent_tool_name,
+                        "input": self.tool_input_1,
+                        "state": "asking",
+                    },
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_2,
+                        "name": self.concurrent_tool_name,
+                        "input": self.tool_input_2,
+                        "state": "asking",
+                    },
+                ],
+            },
+        ]
+        context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+        expected_context = [{**msg_base, **_} for _ in expected_context]
+        self.assertListEqual(context_dicts, expected_context)
+
+        user_confirm_event = UserConfirmResultEvent(
+            reply_id=reply_id,
+            confirm_results=[
+                self._get_confirm_result(
+                    self.tool_call_id_1,
+                    self.concurrent_tool_name,
+                    self.tool_input_1,
+                ),
+                self._get_confirm_result(
+                    self.tool_call_id_2,
+                    self.concurrent_tool_name,
+                    self.tool_input_2,
+                ),
+            ],
+        )
+
+        events = []
+        async for event in self.agent.reply_stream(inputs=user_confirm_event):
+            events.append(event.model_dump())
+
+        self.assertEqual(len(events), 4)
+        expected_tool_events = {
+            self.tool_call_id_1: [
+                {**basic_dict, **_}
+                for _ in self._get_require_external_execution_events(
+                    reply_id,
+                    self.tool_call_id_1,
+                    self.concurrent_tool_name,
+                    self.tool_input_1,
+                )
+            ],
+            self.tool_call_id_2: [
+                {**basic_dict, **_}
+                for _ in self._get_require_external_execution_events(
+                    reply_id,
+                    self.tool_call_id_2,
+                    self.concurrent_tool_name,
+                    self.tool_input_2,
+                )
+            ],
+        }
+        for tool_call_id, expected_tool_event in expected_tool_events.items():
+            self.assertListEqual(
+                [
+                    event
+                    for event in events
+                    if event.get("tool_call_id") == tool_call_id
+                    or (
+                        event["type"] == "REQUIRE_EXTERNAL_EXECUTION"
+                        and event["tool_calls"][0]["id"] == tool_call_id
+                    )
+                ],
+                expected_tool_event,
+            )
+
+        expected_context = [
+            {
+                "name": "user",
+                "role": "user",
+                "content": self.user_input_text,
+            },
+            {
+                "content": [
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_1,
+                        "name": self.concurrent_tool_name,
+                        "input": self.tool_input_1,
+                        "state": "submitted",
+                    },
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_2,
+                        "name": self.concurrent_tool_name,
+                        "input": self.tool_input_2,
+                        "state": "submitted",
+                    },
+                ],
+            },
+        ]
+        context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+        expected_context = [{**msg_base, **_} for _ in expected_context]
+        self.assertListEqual(context_dicts, expected_context)
+
+        external_result_event = ExternalExecutionResultEvent(
+            reply_id=reply_id,
+            execution_results=[
+                self._get_tool_result_block(
+                    self.tool_call_id_1,
+                    self.concurrent_tool_name,
+                    self.concurrent_result_1,
+                ),
+                self._get_tool_result_block(
+                    self.tool_call_id_2,
+                    self.concurrent_tool_name,
+                    self.concurrent_result_2,
+                ),
+            ],
+        )
+
+        events = []
+        async for event in self.agent.reply_stream(
+            inputs=external_result_event,
+        ):
+            events.append(event.model_dump())
+
+        expected_events_after_result = [
+            *self._get_tool_result_events(
+                self.tool_call_id_1,
+                self.concurrent_result_1,
+            ),
+            *self._get_tool_result_events(
+                self.tool_call_id_2,
+                self.concurrent_result_2,
+            ),
+            *self.final_text_events,
+            {"type": "REPLY_END", "session_id": session_id},
+        ]
+        self.assertListEqual(
+            events,
+            [{**basic_dict, **_} for _ in expected_events_after_result],
+        )
+
+        expected_context_final = [
+            {
+                "name": "user",
+                "role": "user",
+                "content": self.user_input_text,
+            },
+            {
+                "content": [
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_1,
+                        "name": self.concurrent_tool_name,
+                        "input": self.tool_input_1,
+                        "state": "finished",
+                    },
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_2,
+                        "name": self.concurrent_tool_name,
+                        "input": self.tool_input_2,
+                        "state": "finished",
+                    },
+                    {
+                        "type": "tool_result",
+                        "id": AnyString(),
+                        "name": self.concurrent_tool_name,
+                        "output": [
+                            {
+                                "type": "text",
+                                "id": AnyString(),
+                                "text": self.concurrent_result_1,
+                            },
+                        ],
+                        "state": "success",
+                    },
+                    {
+                        "type": "tool_result",
+                        "id": AnyString(),
+                        "name": self.concurrent_tool_name,
+                        "output": [
+                            {
+                                "type": "text",
+                                "id": AnyString(),
+                                "text": self.concurrent_result_2,
+                            },
+                        ],
+                        "state": "success",
+                    },
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": self.final_response_text,
+                    },
+                ],
+            },
+        ]
+        context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+        expected_context_final = [
+            {**msg_base, **_} for _ in expected_context_final
+        ]
+        self.assertListEqual(context_dicts, expected_context_final)
+
+    async def asyncTearDown(self) -> None:
+        """The async teardown method."""
diff --git a/tests/hitl_user_confirmation_test.py b/tests/hitl_user_confirmation_test.py
new file mode 100644
index 0000000..7e27cf9
--- /dev/null
+++ b/tests/hitl_user_confirmation_test.py
@@ -0,0 +1,1518 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=redefined-builtin
+"""Test the user confirmation events in the agent class."""
+from typing import Any
+from unittest.async_case import IsolatedAsyncioTestCase
+from utils import AnyString, MockModel
+
+from agentscope.agent import Agent
+from agentscope.model import ChatResponse
+from agentscope.tool import (
+    ToolBase,
+    Toolkit,
+    ToolChunk,
+)
+from agentscope.permission import (
+    PermissionDecision,
+    PermissionBehavior,
+    PermissionContext,
+)
+from agentscope.message import (
+    TextBlock,
+    ToolCallBlock,
+    UserMsg,
+)
+from agentscope.event import UserConfirmResultEvent, ConfirmResult
+
+
+class MockUserConfirmSequentialTool(ToolBase):
+    """A mock tool that requires user confirmation (sequential)."""
+
+    name: str = "mock_user_confirm_sequential_tool"
+    description: str = "A mock user confirm sequential tool for testing"
+    input_schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {
+            "input": {"type": "string", "description": "Input string"},
+        },
+        "required": ["input"],
+    }
+    is_concurrency_safe: bool = False
+    is_read_only: bool = False
+    is_external_tool: bool = False
+    is_mcp: bool = False
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        """Check permissions for the tool usage."""
+        return PermissionDecision(
+            behavior=PermissionBehavior.ASK,
+            decision_reason="Mock tool requires user confirmation",
+            message="Mock tool requires user confirmation",
+        )
+
+    async def __call__(self, input: str, **kwargs: Any) -> ToolChunk:
+        """Execute the tool."""
+        return ToolChunk(
+            content=[
+                TextBlock(text=f"User confirm sequential result: {input}"),
+            ],
+        )
+
+
+class MockUserConfirmConcurrentTool(ToolBase):
+    """A mock tool that requires user confirmation (concurrent)."""
+
+    name: str = "mock_user_confirm_concurrent_tool"
+    description: str = "A mock user confirm concurrent tool for testing"
+    input_schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {
+            "input": {"type": "string", "description": "Input string"},
+        },
+        "required": ["input"],
+    }
+    is_concurrency_safe: bool = True
+    is_read_only: bool = False
+    is_external_tool: bool = False
+    is_mcp: bool = False
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        """Check permissions for the tool usage."""
+        return PermissionDecision(
+            behavior=PermissionBehavior.ASK,
+            decision_reason="Mock tool requires user confirmation",
+            message="Mock tool requires user confirmation",
+        )
+
+    async def __call__(self, input: str, **kwargs: Any) -> ToolChunk:
+        """Execute the tool."""
+        return ToolChunk(
+            content=[
+                TextBlock(text=f"User confirm concurrent result: {input}"),
+            ],
+        )
+
+
+class AgentUserConfirmationTest(IsolatedAsyncioTestCase):
+    """Test the user confirmation events in the agent class."""
+
+    def _get_tool_call_events(
+        self,
+        id: str,
+        name: str,
+        delta: str,
+    ) -> list[dict]:
+        """Helper method to get the expected tool call events."""
+        return [
+            {
+                "type": "TOOL_CALL_START",
+                "tool_call_id": id,
+                "tool_call_name": name,
+            },
+            {
+                "type": "TOOL_CALL_DELTA",
+                "tool_call_id": id,
+                "delta": delta,
+            },
+            {
+                "type": "TOOL_CALL_END",
+                "tool_call_id": id,
+            },
+        ]
+
+    def _get_tool_result_events(
+        self,
+        id: str,
+        name: str,
+        result: str,
+    ) -> list[dict]:
+        """Helper method to get the expected tool result events."""
+        return [
+            {
+                "type": "TOOL_RESULT_START",
+                "tool_call_id": id,
+                "tool_call_name": name,
+            },
+            {
+                "type": "TOOL_RESULT_TEXT_DELTA",
+                "tool_call_id": id,
+                "delta": result,
+            },
+            {
+                "type": "TOOL_RESULT_END",
+                "tool_call_id": id,
+                "state": "success",
+            },
+        ]
+
+    async def asyncSetUp(self) -> None:
+        """The async setup method."""
+        self.model = MockModel()
+        self.agent = Agent(
+            name="Friday",
+            system_prompt="You are a helpful assistant.",
+            model=self.model,
+            toolkit=Toolkit(),
+        )
+        self.tool_call_id_1 = "tool_call_1"
+        self.tool_call_id_2 = "tool_call_2"
+        self.user_input_text = "Test"
+        self.tool_input_1 = '{"input": "test1"}'
+        self.tool_input_2 = '{"input": "test2"}'
+        self.sequential_tool_name = "mock_user_confirm_sequential_tool"
+        self.concurrent_tool_name = "mock_user_confirm_concurrent_tool"
+        self.sequential_result_1 = "User confirm sequential result: test1"
+        self.sequential_result_2 = "User confirm sequential result: test2"
+        self.concurrent_result_1 = "User confirm concurrent result: test1"
+        self.concurrent_result_2 = "User confirm concurrent result: test2"
+        self.final_response_text = "Result 1"
+        self.final_text_events = [
+            {
+                "type": "MODEL_CALL_START",
+                "model_name": "mock-model",
+            },
+            {
+                "type": "TEXT_BLOCK_START",
+                "block_id": AnyString(),
+            },
+            {
+                "type": "TEXT_BLOCK_DELTA",
+                "block_id": AnyString(),
+                "delta": self.final_response_text,
+            },
+            {
+                "type": "TEXT_BLOCK_END",
+                "block_id": AnyString(),
+            },
+            {
+                "type": "MODEL_CALL_END",
+                "input_tokens": 0,
+                "output_tokens": 0,
+                "finished_reason": "completed",
+            },
+        ]
+
+        self.final_mock_responses = [
+            ChatResponse(
+                content=[
+                    TextBlock(text=self.final_response_text),
+                ],
+                is_last=False,
+            ),
+            ChatResponse(
+                content=[
+                    TextBlock(text=self.final_response_text),
+                ],
+                is_last=True,
+            ),
+        ]
+
+    def _get_event_base(self, reply_id: str) -> dict:
+        """Get the dict with the basic fields for event assertion."""
+        return {
+            "id": AnyString(),
+            "created_at": AnyString(),
+            "metadata": {},
+            "reply_id": reply_id,
+        }
+
+    def _get_msg_base(self) -> dict:
+        """Get the dict with the basic fields for message assertion."""
+        return {
+            "id": AnyString(),
+            "created_at": AnyString(),
+            "finished_at": None,
+            "metadata": {},
+            "name": "Friday",
+            "role": "assistant",
+            "usage": None,
+        }
+
+    async def test_single_user_confirmation(self) -> None:
+        """Test single user confirmation tool call.
+
+        The agent should:
+        1. Generate a tool call that requires user confirmation
+        2. Emit REQUIRE_USER_CONFIRM event and pause
+        3. Resume when UserConfirmResultEvent is provided
+        4. Execute the tool and continue
+        """
+        # Register user confirm tool
+        confirm_tool = MockUserConfirmSequentialTool()
+        self.agent.toolkit = Toolkit(
+            tools=[confirm_tool],
+        )
+
+        # Set up mock response with tool call (no final text response)
+        self.model.set_responses(
+            [
+                [
+                    ChatResponse(
+                        content=[
+                            ToolCallBlock(
+                                id=self.tool_call_id_1,
+                                name=self.sequential_tool_name,
+                                input=self.tool_input_1,
+                            ),
+                        ],
+                        is_last=False,
+                    ),
+                    ChatResponse(
+                        content=[
+                            ToolCallBlock(
+                                id=self.tool_call_id_1,
+                                name=self.sequential_tool_name,
+                                input=self.tool_input_1,
+                            ),
+                        ],
+                        is_last=True,
+                    ),
+                ],
+                self.final_mock_responses,
+            ],
+        )
+
+        # First call: collect events until REQUIRE_USER_CONFIRM
+        events = []
+        async for event in self.agent.reply_stream(
+            UserMsg(name="user", content=self.user_input_text),
+        ):
+            events.append(event.model_dump())
+
+        # Verify events
+        session_id = self.agent.state.session_id
+        reply_id = self.agent.state.reply_id
+
+        expected_events = [
+            {
+                "type": "REPLY_START",
+                "session_id": session_id,
+                "name": "Friday",
+                "role": "assistant",
+            },
+            {"type": "MODEL_CALL_START", "model_name": "mock-model"},
+            *self._get_tool_call_events(
+                self.tool_call_id_1,
+                self.sequential_tool_name,
+                self.tool_input_1,
+            ),
+            {
+                "type": "MODEL_CALL_END",
+                "input_tokens": 0,
+                "output_tokens": 0,
+                "finished_reason": "completed",
+            },
+            {
+                "type": "REQUIRE_USER_CONFIRM",
+                "reply_id": reply_id,
+                "tool_calls": [
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_1,
+                        "name": self.sequential_tool_name,
+                        "input": self.tool_input_1,
+                        "state": "asking",
+                        "suggested_rules": [
+                            {
+                                "tool_name": self.sequential_tool_name,
+                                "rule_content": None,
+                                "behavior": PermissionBehavior.ALLOW,
+                                "source": "suggested",
+                            },
+                        ],
+                    },
+                ],
+            },
+        ]
+
+        basic_dict = self._get_event_base(reply_id)
+        self.assertListEqual(
+            events,
+            [{**basic_dict, **_} for _ in expected_events],
+        )
+
+        # Assert context after first call
+        msg_base = self._get_msg_base()
+        expected_context = [
+            {
+                "name": "user",
+                "role": "user",
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": self.user_input_text,
+                    },
+                ],
+                "finished_at": AnyString(),
+            },
+            {
+                "content": [
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_1,
+                        "name": self.sequential_tool_name,
+                        "input": self.tool_input_1,
+                        "state": "asking",
+                        "suggested_rules": [
+                            {
+                                "tool_name": self.sequential_tool_name,
+                                "rule_content": None,
+                                "behavior": PermissionBehavior.ALLOW,
+                                "source": "suggested",
+                            },
+                        ],
+                    },
+                ],
+            },
+        ]
+        context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+        expected_context = [{**msg_base, **_} for _ in expected_context]
+        self.assertListEqual(context_dicts, expected_context)
+
+        # Create user confirmation result event
+        user_confirm_event = UserConfirmResultEvent(
+            reply_id=reply_id,
+            confirm_results=[
+                ConfirmResult(
+                    confirmed=True,
+                    tool_call=ToolCallBlock(
+                        id=self.tool_call_id_1,
+                        name=self.sequential_tool_name,
+                        input=self.tool_input_1,
+                    ),
+                ),
+            ],
+        )
+
+        # Second call: resume with user confirmation result
+        events = []
+        async for event in self.agent.reply_stream(inputs=user_confirm_event):
+            events.append(event.model_dump())
+
+        # Verify events after resumption
+        expected_events_resume = [
+            *self._get_tool_result_events(
+                self.tool_call_id_1,
+                self.sequential_tool_name,
+                self.sequential_result_1,
+            ),
+            *self.final_text_events,
+            {
+                "type": "REPLY_END",
+                "session_id": session_id,
+                "finished_reason": "completed",
+            },
+        ]
+
+        self.assertListEqual(
+            events,
+            [{**basic_dict, **_} for _ in expected_events_resume],
+        )
+
+        # Assert final context
+        expected_context_final = [
+            {
+                "name": "user",
+                "role": "user",
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": self.user_input_text,
+                    },
+                ],
+                "finished_at": AnyString(),
+            },
+            {
+                "content": [
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_1,
+                        "name": self.sequential_tool_name,
+                        "input": self.tool_input_1,
+                        "state": "finished",
+                        "suggested_rules": [
+                            {
+                                "tool_name": self.sequential_tool_name,
+                                "rule_content": None,
+                                "behavior": PermissionBehavior.ALLOW,
+                                "source": "suggested",
+                            },
+                        ],
+                    },
+                    {
+                        "type": "tool_result",
+                        "id": AnyString(),
+                        "name": self.sequential_tool_name,
+                        "output": [
+                            {
+                                "type": "text",
+                                "id": AnyString(),
+                                "text": self.sequential_result_1,
+                            },
+                        ],
+                        "state": "success",
+                        "metadata": {},
+                    },
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": self.final_response_text,
+                    },
+                ],
+            },
+        ]
+        context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+        expected_context_final = [
+            {**msg_base, **_} for _ in expected_context_final
+        ]
+        self.assertListEqual(context_dicts, expected_context_final)
+
+    async def test_sequential_user_confirmation(self) -> None:
+        """Test multiple user confirmation tool calls in sequential execution.
+
+        The agent should:
+        1. Generate multiple tool calls that require user confirmation
+        2. All tools have is_concurrent_safe=False (sequential)
+        3. Emit REQUIRE_USER_CONFIRM event and pause
+        4. Resume when UserConfirmResultEvent is provided
+        5. Execute the tools and continue
+        """
+        # Register user confirm sequential tool
+        confirm_tool = MockUserConfirmSequentialTool()
+        self.agent.toolkit = Toolkit(
+            tools=[confirm_tool],
+        )
+
+        # Set up mock response with multiple tool calls
+        self.model.set_responses(
+            [
+                [
+                    ChatResponse(
+                        content=[
+                            ToolCallBlock(
+                                id=self.tool_call_id_1,
+                                name=self.sequential_tool_name,
+                                input=self.tool_input_1,
+                            ),
+                            ToolCallBlock(
+                                id=self.tool_call_id_2,
+                                name=self.sequential_tool_name,
+                                input=self.tool_input_2,
+                            ),
+                        ],
+                        is_last=False,
+                        usage=None,
+                    ),
+                    ChatResponse(
+                        content=[
+                            ToolCallBlock(
+                                id=self.tool_call_id_1,
+                                name=self.sequential_tool_name,
+                                input=self.tool_input_1,
+                            ),
+                            ToolCallBlock(
+                                id=self.tool_call_id_2,
+                                name=self.sequential_tool_name,
+                                input=self.tool_input_2,
+                            ),
+                        ],
+                        is_last=True,
+                        usage=None,
+                    ),
+                ],
+                self.final_mock_responses,
+            ],
+        )
+
+        # First call: collect events until REQUIRE_USER_CONFIRM
+        events = []
+        async for event in self.agent.reply_stream(
+            UserMsg(name="user", content=self.user_input_text),
+        ):
+            events.append(event.model_dump())
+
+        # Verify events
+        session_id = self.agent.state.session_id
+        reply_id = self.agent.state.reply_id
+
+        tool_call_1_events = self._get_tool_call_events(
+            self.tool_call_id_1,
+            self.sequential_tool_name,
+            self.tool_input_1,
+        )
+        tool_call_2_events = self._get_tool_call_events(
+            self.tool_call_id_2,
+            self.sequential_tool_name,
+            self.tool_input_2,
+        )
+
+        expected_events = [
+            {
+                "type": "REPLY_START",
+                "session_id": session_id,
+                "name": "Friday",
+                "role": "assistant",
+            },
+            {"type": "MODEL_CALL_START", "model_name": "mock-model"},
+            *tool_call_1_events[:2],
+            *tool_call_2_events[:2],
+            tool_call_1_events[2],
+            tool_call_2_events[2],
+            {
+                "type": "MODEL_CALL_END",
+                "input_tokens": 0,
+                "output_tokens": 0,
+                "finished_reason": "completed",
+            },
+            {
+                "type": "REQUIRE_USER_CONFIRM",
+                "reply_id": reply_id,
+                "tool_calls": [
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_1,
+                        "name": self.sequential_tool_name,
+                        "input": self.tool_input_1,
+                        "state": "asking",
+                        "suggested_rules": [
+                            {
+                                "tool_name": self.sequential_tool_name,
+                                "rule_content": None,
+                                "behavior": PermissionBehavior.ALLOW,
+                                "source": "suggested",
+                            },
+                        ],
+                    },
+                ],
+            },
+        ]
+
+        basic_dict = self._get_event_base(reply_id)
+        self.assertListEqual(
+            events,
+            [{**basic_dict, **_} for _ in expected_events],
+        )
+
+        # Assert context after first call
+        msg_base = self._get_msg_base()
+        expected_context = [
+            {
+                "name": "user",
+                "role": "user",
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": self.user_input_text,
+                    },
+                ],
+                "finished_at": AnyString(),
+            },
+            {
+                "content": [
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_1,
+                        "name": self.sequential_tool_name,
+                        "input": self.tool_input_1,
+                        "state": "asking",
+                        "suggested_rules": [
+                            {
+                                "tool_name": self.sequential_tool_name,
+                                "rule_content": None,
+                                "behavior": PermissionBehavior.ALLOW,
+                                "source": "suggested",
+                            },
+                        ],
+                    },
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_2,
+                        "name": self.sequential_tool_name,
+                        "input": self.tool_input_2,
+                        "state": "pending",
+                        "suggested_rules": [],
+                    },
+                ],
+            },
+        ]
+        context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+        expected_context = [{**msg_base, **_} for _ in expected_context]
+        self.assertListEqual(context_dicts, expected_context)
+
+        # Create user confirmation result event
+        user_confirm_event = UserConfirmResultEvent(
+            reply_id=reply_id,
+            confirm_results=[
+                ConfirmResult(
+                    confirmed=True,
+                    tool_call=ToolCallBlock(
+                        id=self.tool_call_id_1,
+                        name=self.sequential_tool_name,
+                        input=self.tool_input_1,
+                    ),
+                ),
+            ],
+        )
+
+        # resume with user confirmation result
+        events = []
+        async for event in self.agent.reply_stream(inputs=user_confirm_event):
+            events.append(event.model_dump())
+
+        # Verify events after resumption (sequential execution)
+        expected_events_resume = [
+            *self._get_tool_result_events(
+                self.tool_call_id_1,
+                self.sequential_tool_name,
+                self.sequential_result_1,
+            ),
+            {
+                "type": "REQUIRE_USER_CONFIRM",
+                "tool_calls": [
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_2,
+                        "name": self.sequential_tool_name,
+                        "input": self.tool_input_2,
+                        "state": "asking",
+                        "suggested_rules": [
+                            {
+                                "tool_name": self.sequential_tool_name,
+                                "rule_content": None,
+                                "behavior": PermissionBehavior.ALLOW,
+                                "source": "suggested",
+                            },
+                        ],
+                    },
+                ],
+            },
+        ]
+
+        self.assertListEqual(
+            events,
+            [{**basic_dict, **_} for _ in expected_events_resume],
+        )
+
+        # Confirm the second tool call
+        user_confirm_event = UserConfirmResultEvent(
+            reply_id=reply_id,
+            confirm_results=[
+                ConfirmResult(
+                    confirmed=True,
+                    tool_call=ToolCallBlock(
+                        id=self.tool_call_id_2,
+                        name=self.sequential_tool_name,
+                        input=self.tool_input_2,
+                    ),
+                ),
+            ],
+        )
+
+        # Second call: resume with user confirmation result
+        events = []
+        async for event in self.agent.reply_stream(inputs=user_confirm_event):
+            events.append(event.model_dump())
+
+        expected_events_resume_2 = [
+            *self._get_tool_result_events(
+                self.tool_call_id_2,
+                self.sequential_tool_name,
+                self.sequential_result_2,
+            ),
+            *self.final_text_events,
+            {
+                "type": "REPLY_END",
+                "session_id": session_id,
+                "finished_reason": "completed",
+            },
+        ]
+        self.assertListEqual(
+            events,
+            [{**basic_dict, **_} for _ in expected_events_resume_2],
+        )
+
+        # Assert final context
+        expected_context_final = [
+            {
+                "name": "user",
+                "role": "user",
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": self.user_input_text,
+                    },
+                ],
+                "finished_at": AnyString(),
+            },
+            {
+                "content": [
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_1,
+                        "name": self.sequential_tool_name,
+                        "input": self.tool_input_1,
+                        "state": "finished",
+                        "suggested_rules": [
+                            {
+                                "tool_name": self.sequential_tool_name,
+                                "rule_content": None,
+                                "behavior": PermissionBehavior.ALLOW,
+                                "source": "suggested",
+                            },
+                        ],
+                    },
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_2,
+                        "name": self.sequential_tool_name,
+                        "input": self.tool_input_2,
+                        "state": "finished",
+                        "suggested_rules": [
+                            {
+                                "tool_name": self.sequential_tool_name,
+                                "rule_content": None,
+                                "behavior": PermissionBehavior.ALLOW,
+                                "source": "suggested",
+                            },
+                        ],
+                    },
+                    {
+                        "type": "tool_result",
+                        "id": AnyString(),
+                        "name": self.sequential_tool_name,
+                        "output": [
+                            {
+                                "type": "text",
+                                "id": AnyString(),
+                                "text": self.sequential_result_1,
+                            },
+                        ],
+                        "state": "success",
+                        "metadata": {},
+                    },
+                    {
+                        "type": "tool_result",
+                        "id": AnyString(),
+                        "name": self.sequential_tool_name,
+                        "output": [
+                            {
+                                "type": "text",
+                                "id": AnyString(),
+                                "text": self.sequential_result_2,
+                            },
+                        ],
+                        "state": "success",
+                        "metadata": {},
+                    },
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": self.final_response_text,
+                    },
+                ],
+            },
+        ]
+        context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+        expected_context_final = [
+            {**msg_base, **_} for _ in expected_context_final
+        ]
+        self.assertListEqual(context_dicts, expected_context_final)
+
+    async def test_concurrent_user_confirmation(self) -> None:
+        """Test multiple user confirmation tool calls in concurrent execution.
+
+        The agent should:
+        1. Generate multiple tool calls that require user confirmation
+        2. All tools have is_concurrent_safe=True (concurrent)
+        3. Emit REQUIRE_USER_CONFIRM event and pause
+        4. Resume when UserConfirmResultEvent is provided
+        5. Execute the tools and continue
+        """
+        # Register user confirm concurrent tool
+        confirm_tool = MockUserConfirmConcurrentTool()
+        self.agent.toolkit = Toolkit(
+            tools=[confirm_tool],
+        )
+
+        # Set up mock response with multiple tool calls
+        self.model.set_responses(
+            [
+                [
+                    ChatResponse(
+                        content=[
+                            ToolCallBlock(
+                                id=self.tool_call_id_1,
+                                name=self.concurrent_tool_name,
+                                input=self.tool_input_1,
+                            ),
+                            ToolCallBlock(
+                                id=self.tool_call_id_2,
+                                name=self.concurrent_tool_name,
+                                input=self.tool_input_2,
+                            ),
+                        ],
+                        is_last=False,
+                    ),
+                    ChatResponse(
+                        content=[
+                            ToolCallBlock(
+                                id=self.tool_call_id_1,
+                                name=self.concurrent_tool_name,
+                                input=self.tool_input_1,
+                            ),
+                            ToolCallBlock(
+                                id=self.tool_call_id_2,
+                                name=self.concurrent_tool_name,
+                                input=self.tool_input_2,
+                            ),
+                        ],
+                        is_last=True,
+                    ),
+                ],
+                self.final_mock_responses,
+            ],
+        )
+
+        # First call: collect events until REQUIRE_USER_CONFIRM
+        events = []
+        async for event in self.agent.reply_stream(
+            UserMsg(name="user", content=self.user_input_text),
+        ):
+            events.append(event.model_dump())
+
+        # Verify events
+        session_id = self.agent.state.session_id
+        reply_id = self.agent.state.reply_id
+
+        tool_call_1_events = self._get_tool_call_events(
+            self.tool_call_id_1,
+            self.concurrent_tool_name,
+            self.tool_input_1,
+        )
+        tool_call_2_events = self._get_tool_call_events(
+            self.tool_call_id_2,
+            self.concurrent_tool_name,
+            self.tool_input_2,
+        )
+
+        expected_events = [
+            {
+                "type": "REPLY_START",
+                "session_id": session_id,
+                "name": "Friday",
+                "role": "assistant",
+            },
+            {"type": "MODEL_CALL_START", "model_name": "mock-model"},
+            *tool_call_1_events[:2],
+            *tool_call_2_events[:2],
+            tool_call_1_events[2],
+            tool_call_2_events[2],
+            {
+                "type": "MODEL_CALL_END",
+                "input_tokens": 0,
+                "output_tokens": 0,
+                "finished_reason": "completed",
+            },
+            {
+                "type": "REQUIRE_USER_CONFIRM",
+                "reply_id": reply_id,
+                "tool_calls": [
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_1,
+                        "name": self.concurrent_tool_name,
+                        "input": self.tool_input_1,
+                        "state": "asking",
+                        "suggested_rules": [
+                            {
+                                "tool_name": self.concurrent_tool_name,
+                                "rule_content": None,
+                                "behavior": PermissionBehavior.ALLOW,
+                                "source": "suggested",
+                            },
+                        ],
+                    },
+                ],
+            },
+            {
+                "type": "REQUIRE_USER_CONFIRM",
+                "reply_id": reply_id,
+                "tool_calls": [
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_2,
+                        "name": self.concurrent_tool_name,
+                        "input": self.tool_input_2,
+                        "state": "asking",
+                        "suggested_rules": [
+                            {
+                                "tool_name": self.concurrent_tool_name,
+                                "rule_content": None,
+                                "behavior": PermissionBehavior.ALLOW,
+                                "source": "suggested",
+                            },
+                        ],
+                    },
+                ],
+            },
+        ]
+
+        basic_dict = self._get_event_base(reply_id)
+        self.assertListEqual(
+            events,
+            [{**basic_dict, **_} for _ in expected_events],
+        )
+
+        # Assert context after first call
+        msg_base = self._get_msg_base()
+        expected_context = [
+            {
+                "name": "user",
+                "role": "user",
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": self.user_input_text,
+                    },
+                ],
+                "finished_at": AnyString(),
+            },
+            {
+                "content": [
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_1,
+                        "name": self.concurrent_tool_name,
+                        "input": self.tool_input_1,
+                        "state": "asking",
+                        "suggested_rules": [
+                            {
+                                "tool_name": self.concurrent_tool_name,
+                                "rule_content": None,
+                                "behavior": PermissionBehavior.ALLOW,
+                                "source": "suggested",
+                            },
+                        ],
+                    },
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_2,
+                        "name": self.concurrent_tool_name,
+                        "input": self.tool_input_2,
+                        "state": "asking",
+                        "suggested_rules": [
+                            {
+                                "tool_name": self.concurrent_tool_name,
+                                "rule_content": None,
+                                "behavior": PermissionBehavior.ALLOW,
+                                "source": "suggested",
+                            },
+                        ],
+                    },
+                ],
+            },
+        ]
+        context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+        expected_context = [{**msg_base, **_} for _ in expected_context]
+        self.assertListEqual(context_dicts, expected_context)
+
+        # Create user confirmation result event
+        user_confirm_event = UserConfirmResultEvent(
+            reply_id=reply_id,
+            confirm_results=[
+                ConfirmResult(
+                    confirmed=True,
+                    tool_call=ToolCallBlock(
+                        id=self.tool_call_id_1,
+                        name=self.concurrent_tool_name,
+                        input=self.tool_input_1,
+                    ),
+                ),
+            ],
+        )
+
+        # resume with user confirmation result
+        events = []
+        async for event in self.agent.reply_stream(inputs=user_confirm_event):
+            events.append(event.model_dump())
+
+        # Verify events for tool call 1 after resumption
+        expected_events = [
+            *self._get_tool_result_events(
+                self.tool_call_id_1,
+                self.concurrent_tool_name,
+                self.concurrent_result_1,
+            ),
+        ]
+        self.assertListEqual(
+            events,
+            [{**basic_dict, **_} for _ in expected_events],
+        )
+
+        # The second tool call
+        user_confirm_event = UserConfirmResultEvent(
+            reply_id=reply_id,
+            confirm_results=[
+                ConfirmResult(
+                    confirmed=True,
+                    tool_call=ToolCallBlock(
+                        id=self.tool_call_id_2,
+                        name=self.concurrent_tool_name,
+                        input=self.tool_input_2,
+                    ),
+                ),
+            ],
+        )
+
+        events = []
+        async for event in self.agent.reply_stream(inputs=user_confirm_event):
+            events.append(event.model_dump())
+
+        expected_events = [
+            *self._get_tool_result_events(
+                self.tool_call_id_2,
+                self.concurrent_tool_name,
+                self.concurrent_result_2,
+            ),
+            *self.final_text_events,
+            {
+                "type": "REPLY_END",
+                "session_id": session_id,
+                "finished_reason": "completed",
+            },
+        ]
+        self.assertListEqual(
+            events,
+            [{**basic_dict, **_} for _ in expected_events],
+        )
+
+        # Assert final context
+        expected_context_final = [
+            {
+                "name": "user",
+                "role": "user",
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": self.user_input_text,
+                    },
+                ],
+                "finished_at": AnyString(),
+            },
+            {
+                "content": [
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_1,
+                        "name": self.concurrent_tool_name,
+                        "input": self.tool_input_1,
+                        "state": "finished",
+                        "suggested_rules": [
+                            {
+                                "tool_name": self.concurrent_tool_name,
+                                "rule_content": None,
+                                "behavior": PermissionBehavior.ALLOW,
+                                "source": "suggested",
+                            },
+                        ],
+                    },
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_2,
+                        "name": self.concurrent_tool_name,
+                        "input": self.tool_input_2,
+                        "state": "finished",
+                        "suggested_rules": [
+                            {
+                                "tool_name": self.concurrent_tool_name,
+                                "rule_content": None,
+                                "behavior": PermissionBehavior.ALLOW,
+                                "source": "suggested",
+                            },
+                        ],
+                    },
+                    {
+                        "type": "tool_result",
+                        "id": AnyString(),
+                        "name": self.concurrent_tool_name,
+                        "output": [
+                            {
+                                "type": "text",
+                                "id": AnyString(),
+                                "text": self.concurrent_result_1,
+                            },
+                        ],
+                        "state": "success",
+                        "metadata": {},
+                    },
+                    {
+                        "type": "tool_result",
+                        "id": AnyString(),
+                        "name": self.concurrent_tool_name,
+                        "output": [
+                            {
+                                "type": "text",
+                                "id": AnyString(),
+                                "text": self.concurrent_result_2,
+                            },
+                        ],
+                        "state": "success",
+                        "metadata": {},
+                    },
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": self.final_response_text,
+                    },
+                ],
+            },
+        ]
+        context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+        expected_context_final = [
+            {**msg_base, **_} for _ in expected_context_final
+        ]
+        self.assertListEqual(context_dicts, expected_context_final)
+
+    async def test_concurrent_user_confirmation_in_single_event(self) -> None:
+        """Test concurrent user confirmation when two approvals arrive
+        together.
+
+        The agent should:
+        1. Generate multiple tool calls that require user confirmation
+        2. Pause in concurrent mode with two asking tool calls
+        3. Resume when one UserConfirmResultEvent carries both confirmations
+        4. Execute both tools and continue reasoning after both complete
+        """
+        confirm_tool = MockUserConfirmConcurrentTool()
+        self.agent.toolkit = Toolkit(
+            tools=[confirm_tool],
+        )
+
+        self.model.set_responses(
+            [
+                [
+                    ChatResponse(
+                        content=[
+                            ToolCallBlock(
+                                id=self.tool_call_id_1,
+                                name=self.concurrent_tool_name,
+                                input=self.tool_input_1,
+                            ),
+                            ToolCallBlock(
+                                id=self.tool_call_id_2,
+                                name=self.concurrent_tool_name,
+                                input=self.tool_input_2,
+                            ),
+                        ],
+                        is_last=False,
+                    ),
+                    ChatResponse(
+                        content=[
+                            ToolCallBlock(
+                                id=self.tool_call_id_1,
+                                name=self.concurrent_tool_name,
+                                input=self.tool_input_1,
+                            ),
+                            ToolCallBlock(
+                                id=self.tool_call_id_2,
+                                name=self.concurrent_tool_name,
+                                input=self.tool_input_2,
+                            ),
+                        ],
+                        is_last=True,
+                    ),
+                ],
+                self.final_mock_responses,
+            ],
+        )
+
+        events = []
+        async for event in self.agent.reply_stream(
+            UserMsg(name="user", content=self.user_input_text),
+        ):
+            events.append(event.model_dump())
+
+        session_id = self.agent.state.session_id
+        reply_id = self.agent.state.reply_id
+        basic_dict = self._get_event_base(reply_id)
+        msg_base = self._get_msg_base()
+
+        tool_call_1_events = self._get_tool_call_events(
+            self.tool_call_id_1,
+            self.concurrent_tool_name,
+            self.tool_input_1,
+        )
+        tool_call_2_events = self._get_tool_call_events(
+            self.tool_call_id_2,
+            self.concurrent_tool_name,
+            self.tool_input_2,
+        )
+
+        expected_events = [
+            {
+                "type": "REPLY_START",
+                "session_id": session_id,
+                "name": "Friday",
+                "role": "assistant",
+            },
+            {"type": "MODEL_CALL_START", "model_name": "mock-model"},
+            *tool_call_1_events[:2],
+            *tool_call_2_events[:2],
+            tool_call_1_events[2],
+            tool_call_2_events[2],
+            {
+                "type": "MODEL_CALL_END",
+                "input_tokens": 0,
+                "output_tokens": 0,
+                "finished_reason": "completed",
+            },
+            {
+                "type": "REQUIRE_USER_CONFIRM",
+                "reply_id": reply_id,
+                "tool_calls": [
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_1,
+                        "name": self.concurrent_tool_name,
+                        "input": self.tool_input_1,
+                        "state": "asking",
+                        "suggested_rules": [
+                            {
+                                "tool_name": self.concurrent_tool_name,
+                                "rule_content": None,
+                                "behavior": PermissionBehavior.ALLOW,
+                                "source": "suggested",
+                            },
+                        ],
+                    },
+                ],
+            },
+            {
+                "type": "REQUIRE_USER_CONFIRM",
+                "reply_id": reply_id,
+                "tool_calls": [
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_2,
+                        "name": self.concurrent_tool_name,
+                        "input": self.tool_input_2,
+                        "state": "asking",
+                        "suggested_rules": [
+                            {
+                                "tool_name": self.concurrent_tool_name,
+                                "rule_content": None,
+                                "behavior": PermissionBehavior.ALLOW,
+                                "source": "suggested",
+                            },
+                        ],
+                    },
+                ],
+            },
+        ]
+        self.assertListEqual(
+            events,
+            [{**basic_dict, **_} for _ in expected_events],
+        )
+
+        expected_context = [
+            {
+                "name": "user",
+                "role": "user",
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": self.user_input_text,
+                    },
+                ],
+                "finished_at": AnyString(),
+            },
+            {
+                "content": [
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_1,
+                        "name": self.concurrent_tool_name,
+                        "input": self.tool_input_1,
+                        "state": "asking",
+                        "suggested_rules": [
+                            {
+                                "tool_name": self.concurrent_tool_name,
+                                "rule_content": None,
+                                "behavior": PermissionBehavior.ALLOW,
+                                "source": "suggested",
+                            },
+                        ],
+                    },
+                    {
+                        "type": "tool_call",
+                        "id": self.tool_call_id_2,
+                        "name": self.concurrent_tool_name,
+                        "input": self.tool_input_2,
+                        "state": "asking",
+                        "suggested_rules": [
+                            {
+                                "tool_name": self.concurrent_tool_name,
+                                "rule_content": None,
+                                "behavior": PermissionBehavior.ALLOW,
+                                "source": "suggested",
+                            },
+                        ],
+                    },
+                ],
+            },
+        ]
+        context_dicts = [msg.model_dump() for msg in self.agent.state.context]
+        expected_context = [{**msg_base, **_} for _ in expected_context]
+        self.assertListEqual(context_dicts, expected_context)
+
+        user_confirm_event = UserConfirmResultEvent(
+            reply_id=reply_id,
+            confirm_results=[
+                ConfirmResult(
+                    confirmed=True,
+                    tool_call=ToolCallBlock(
+                        id=self.tool_call_id_1,
+                        name=self.concurrent_tool_name,
+                        input=self.tool_input_1,
+                    ),
+                ),
+                ConfirmResult(
+                    confirmed=True,
+                    tool_call=ToolCallBlock(
+                        id=self.tool_call_id_2,
+                        name=self.concurrent_tool_name,
+                        input=self.tool_input_2,
+                    ),
+                ),
+            ],
+        )
+
+        events = []
+        async for event in self.agent.reply_stream(inputs=user_confirm_event):
+            events.append(event.model_dump())
+
+        tool_events = events[:6]
+        final_events = events[6:]
+        self.assertEqual(len(tool_events), 6)
+
+        expected_tool_events = {
+            self.tool_call_id_1: [
+                {**basic_dict, **_}
+                for _ in self._get_tool_result_events(
+                    self.tool_call_id_1,
+                    self.concurrent_tool_name,
+                    self.concurrent_result_1,
+                )
+            ],
+            self.tool_call_id_2: [
+                {**basic_dict, **_}
+                for _ in self._get_tool_result_events(
+                    self.tool_call_id_2,
+                    self.concurrent_tool_name,
+                    self.concurrent_result_2,
+                )
+            ],
+        }
+        for tool_call_id, expected_tool_event in expected_tool_events.items():
+            self.assertListEqual(
+                [
+                    event
+                    for event in tool_events
+                    if event["tool_call_id"] == tool_call_id
+                ],
+                expected_tool_event,
+            )
+
+        expected_final_events = [
+            *self.final_text_events,
+            {
+                "type": "REPLY_END",
+                "session_id": session_id,
+                "finished_reason": "completed",
+            },
+        ]
+        self.assertListEqual(
+            final_events,
+            [{**basic_dict, **_} for _ in expected_final_events],
+        )
+
+        self.assertEqual(len(self.agent.state.context), 2)
+        self.assertEqual(
+            self.agent.state.context[0].model_dump(),
+            {
+                "id": AnyString(),
+                "created_at": AnyString(),
+                "finished_at": AnyString(),
+                "metadata": {},
+                "name": "user",
+                "role": "user",
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": self.user_input_text,
+                    },
+                ],
+                "usage": None,
+            },
+        )
+
+        assistant_msg = self.agent.state.context[-1]
+        self.assertEqual(
+            [
+                _.model_dump()["state"]
+                for _ in assistant_msg.get_content_blocks("tool_call")
+            ],
+            ["finished", "finished"],
+        )
+        self.assertEqual(
+            [
+                _.model_dump()["id"]
+                for _ in assistant_msg.get_content_blocks("tool_call")
+            ],
+            [self.tool_call_id_1, self.tool_call_id_2],
+        )
+        self.assertEqual(
+            {
+                (
+                    _.model_dump()["name"],
+                    _.model_dump()["state"],
+                    _.output[0].text,
+                )
+                for _ in assistant_msg.get_content_blocks("tool_result")
+            },
+            {
+                (
+                    self.concurrent_tool_name,
+                    "success",
+                    self.concurrent_result_1,
+                ),
+                (
+                    self.concurrent_tool_name,
+                    "success",
+                    self.concurrent_result_2,
+                ),
+            },
+        )
+        self.assertEqual(
+            [_.text for _ in assistant_msg.get_content_blocks("text")],
+            [self.final_response_text],
+        )
+
+    async def asyncTearDown(self) -> None:
+        """The async teardown method."""
diff --git a/tests/id_factory_test.py b/tests/id_factory_test.py
new file mode 100644
index 0000000..b3f5846
--- /dev/null
+++ b/tests/id_factory_test.py
@@ -0,0 +1,49 @@
+# -*- coding: utf-8 -*-
+"""Tests for the configurable ID factory."""
+import re
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from agentscope import set_id_factory
+from agentscope.message import Msg, TextBlock
+
+_HEX32_RE = re.compile(r"^[0-9a-f]{32}$")
+
+
+class IdFactoryTest(IsolatedAsyncioTestCase):
+    """Tests for set_id_factory."""
+
+    async def asyncSetUp(self) -> None:
+        """Save the current factory before each test."""
+        import agentscope._utils._common as common
+
+        # pylint: disable=protected-access
+        self._saved_factory = common._id_factory
+
+    async def test_default_id_factory_returns_hex32(self) -> None:
+        """The default ID factory returns uuid.uuid4().hex."""
+        msg = Msg(
+            name="test",
+            content=[TextBlock(text="hello")],
+            role="user",
+        )
+        self.assertRegex(msg.id, _HEX32_RE)
+        self.assertRegex(msg.content[0].id, _HEX32_RE)
+
+    async def test_custom_factory_affects_entities(self) -> None:
+        """After ``set_id_factory``, entities use the custom factory."""
+        set_id_factory(lambda: "custom-entity-id")
+
+        msg = Msg(
+            name="test",
+            content=[TextBlock(text="hello")],
+            role="user",
+        )
+        self.assertEqual(msg.id, "custom-entity-id")
+        self.assertEqual(msg.content[0].id, "custom-entity-id")
+
+    async def asyncTearDown(self) -> None:
+        """Restore the original factory after each test."""
+        import agentscope._utils._common as common
+
+        # pylint: disable=protected-access
+        common._id_factory = self._saved_factory
diff --git a/tests/in_memory_message_bus_test.py b/tests/in_memory_message_bus_test.py
new file mode 100644
index 0000000..0ee0c05
--- /dev/null
+++ b/tests/in_memory_message_bus_test.py
@@ -0,0 +1,503 @@
+# -*- coding: utf-8 -*-
+"""Tests for :class:`InMemoryMessageBus`.
+
+The same abstract surface exercised in ``service_message_bus_test.py``
+(queue / log / pubsub / lock / registry) is tested here against the
+pure-Python in-memory backend, plus the domain helpers inherited from
+the base :class:`MessageBus` class.
+
+No external dependencies (no Redis, no fakeredis) — just asyncio.
+"""
+import asyncio
+from contextlib import AsyncExitStack
+from unittest import IsolatedAsyncioTestCase
+
+from agentscope.app.message_bus import InMemoryMessageBus
+
+
+class TestQueuePrimitive(IsolatedAsyncioTestCase):
+    """Mode A — ``queue_push`` + ``queue_drain`` semantics."""
+
+    async def asyncSetUp(self) -> None:
+        self._stack = AsyncExitStack()
+        self.bus = await self._stack.enter_async_context(
+            InMemoryMessageBus(),
+        )
+
+    async def asyncTearDown(self) -> None:
+        await self._stack.aclose()
+
+    async def test_push_drain_returns_payloads_in_order(self) -> None:
+        """Entries pushed in order come back out in order, once each."""
+        await self.bus.queue_push("k", {"i": 1})
+        await self.bus.queue_push("k", {"i": 2})
+        entries = await self.bus.queue_drain("k", max_count=10)
+        self.assertEqual([p for _id, p in entries], [{"i": 1}, {"i": 2}])
+
+    async def test_drain_is_destructive(self) -> None:
+        """A drained entry is gone; a second drain yields nothing."""
+        await self.bus.queue_push("k", {"x": 1})
+        await self.bus.queue_drain("k", max_count=10)
+        self.assertEqual(await self.bus.queue_drain("k", max_count=10), [])
+
+    async def test_drain_respects_max_count(self) -> None:
+        """``max_count`` caps the batch size; remaining entries persist."""
+        for i in range(5):
+            await self.bus.queue_push("k", {"i": i})
+        first = await self.bus.queue_drain("k", max_count=3)
+        rest = await self.bus.queue_drain("k", max_count=10)
+        self.assertEqual([p["i"] for _id, p in first], [0, 1, 2])
+        self.assertEqual([p["i"] for _id, p in rest], [3, 4])
+
+    async def test_drain_empty_queue_returns_empty(self) -> None:
+        """Draining a key that was never pushed returns an empty list."""
+        self.assertEqual(await self.bus.queue_drain("nope"), [])
+
+    async def test_push_returns_unique_ids(self) -> None:
+        """Each ``queue_push`` returns a distinct entry id."""
+        id1 = await self.bus.queue_push("k", {"a": 1})
+        id2 = await self.bus.queue_push("k", {"a": 2})
+        self.assertNotEqual(id1, id2)
+
+    async def test_queue_delete_removes_all(self) -> None:
+        """``queue_delete`` drops the entire queue."""
+        await self.bus.queue_push("k", {"i": 1})
+        await self.bus.queue_push("k", {"i": 2})
+        await self.bus.queue_delete("k")
+        self.assertEqual(await self.bus.queue_drain("k", max_count=10), [])
+
+    async def test_queue_delete_missing_is_noop(self) -> None:
+        """Deleting a non-existent queue does not raise."""
+        await self.bus.queue_delete("never-existed")
+
+    async def test_queue_isolation_between_keys(self) -> None:
+        """Pushes to different keys are independent."""
+        await self.bus.queue_push("a", {"x": 1})
+        await self.bus.queue_push("b", {"x": 2})
+        a = await self.bus.queue_drain("a", max_count=10)
+        b = await self.bus.queue_drain("b", max_count=10)
+        self.assertEqual([p for _id, p in a], [{"x": 1}])
+        self.assertEqual([p for _id, p in b], [{"x": 2}])
+
+
+class TestLogPrimitive(IsolatedAsyncioTestCase):
+    """Mode C — replay log: append / read with cursor / trim."""
+
+    async def asyncSetUp(self) -> None:
+        self._stack = AsyncExitStack()
+        self.bus = await self._stack.enter_async_context(
+            InMemoryMessageBus(),
+        )
+
+    async def asyncTearDown(self) -> None:
+        await self._stack.aclose()
+
+    async def test_read_returns_everything_when_no_cursor(self) -> None:
+        """Without a ``since`` cursor, the whole log comes back."""
+        await self.bus.log_append("k", {"i": 1})
+        await self.bus.log_append("k", {"i": 2})
+        entries = await self.bus.log_read("k")
+        self.assertEqual([p["i"] for _id, p in entries], [1, 2])
+
+    async def test_read_with_cursor_is_exclusive(self) -> None:
+        """``since=last_id`` skips that id and returns only newer."""
+        await self.bus.log_append("k", {"i": 1})
+        await self.bus.log_append("k", {"i": 2})
+        await self.bus.log_append("k", {"i": 3})
+        all_entries = await self.bus.log_read("k")
+        cursor = all_entries[1][0]  # id of entry 2
+        rest = await self.bus.log_read("k", since=cursor)
+        self.assertEqual([p["i"] for _id, p in rest], [3])
+
+    async def test_read_respects_max_count(self) -> None:
+        """``max_count`` caps the batch; remaining entries persist."""
+        for i in range(5):
+            await self.bus.log_append("k", {"i": i})
+        first = await self.bus.log_read("k", max_count=3)
+        self.assertEqual([p["i"] for _id, p in first], [0, 1, 2])
+
+    async def test_read_is_non_destructive(self) -> None:
+        """Multiple reads on the same log return the same data."""
+        await self.bus.log_append("k", {"i": 1})
+        r1 = await self.bus.log_read("k")
+        r2 = await self.bus.log_read("k")
+        self.assertEqual(
+            [p["i"] for _id, p in r1],
+            [p["i"] for _id, p in r2],
+        )
+
+    async def test_read_empty_log(self) -> None:
+        """Reading a log that never had entries returns ``[]``."""
+        self.assertEqual(await self.bus.log_read("nope"), [])
+
+    async def test_read_all_before_cursor(self) -> None:
+        """When all entries are at or before the cursor, result is ``[]``."""
+        id2 = await self.bus.log_append("k", {"i": 2})
+        self.assertEqual(await self.bus.log_read("k", since=id2), [])
+
+    async def test_trim_without_before_drops_entire_log(self) -> None:
+        """``log_trim(key)`` empties the log."""
+        await self.bus.log_append("k", {"i": 1})
+        await self.bus.log_append("k", {"i": 2})
+        await self.bus.log_trim("k")
+        self.assertEqual(await self.bus.log_read("k"), [])
+
+    async def test_trim_with_before_id_keeps_newer(self) -> None:
+        """``log_trim(key, before_id)`` drops older entries only."""
+        await self.bus.log_append("k", {"i": 1})
+        id2 = await self.bus.log_append("k", {"i": 2})
+        await self.bus.log_append("k", {"i": 3})
+        await self.bus.log_trim("k", before_id=id2)
+        entries = await self.bus.log_read("k")
+        self.assertEqual([p["i"] for _id, p in entries], [2, 3])
+
+    async def test_trim_missing_key_is_noop(self) -> None:
+        """Trimming a non-existent log does not raise."""
+        await self.bus.log_trim("nope")
+
+    async def test_max_len_caps_log_size(self) -> None:
+        """``max_len`` on ``log_append`` trims older entries when the
+        log exceeds the cap."""
+        for i in range(10):
+            await self.bus.log_append("k", {"i": i}, max_len=5)
+        entries = await self.bus.log_read("k", max_count=100)
+        self.assertLessEqual(len(entries), 5)
+        # The newest entries must survive.
+        self.assertEqual(entries[-1][1]["i"], 9)
+
+
+class TestPubSubPrimitive(IsolatedAsyncioTestCase):
+    """Mode D — transient broadcast: publish / subscribe."""
+
+    async def asyncSetUp(self) -> None:
+        self._stack = AsyncExitStack()
+        self.bus = await self._stack.enter_async_context(
+            InMemoryMessageBus(),
+        )
+
+    async def asyncTearDown(self) -> None:
+        await self._stack.aclose()
+
+    async def test_subscribe_receives_messages_published_after_ready(
+        self,
+    ) -> None:
+        """Subscribers receive payloads published after the subscription
+        is established."""
+        ready = asyncio.Event()
+        received: list[dict] = []
+
+        async def _consumer() -> None:
+            async for payload in self.bus.subscribe(
+                "ch",
+                on_ready=ready.set,
+            ):
+                received.append(payload)
+                if len(received) == 2:
+                    break
+
+        task = asyncio.create_task(_consumer())
+        await asyncio.wait_for(ready.wait(), timeout=2.0)
+
+        await self.bus.publish("ch", {"i": 1})
+        await self.bus.publish("ch", {"i": 2})
+        await asyncio.wait_for(task, timeout=2.0)
+        self.assertEqual([p["i"] for p in received], [1, 2])
+
+    async def test_publish_without_subscribers_is_noop(self) -> None:
+        """Publishing when no one is listening does not raise."""
+        await self.bus.publish("ch", {"i": 1})
+
+    async def test_multiple_subscribers_each_receive(self) -> None:
+        """All active subscribers on a channel receive the payload."""
+        ready1 = asyncio.Event()
+        ready2 = asyncio.Event()
+        r1: list[dict] = []
+        r2: list[dict] = []
+
+        async def _c1() -> None:
+            async for payload in self.bus.subscribe(
+                "ch",
+                on_ready=ready1.set,
+            ):
+                r1.append(payload)
+                break
+
+        async def _c2() -> None:
+            async for payload in self.bus.subscribe(
+                "ch",
+                on_ready=ready2.set,
+            ):
+                r2.append(payload)
+                break
+
+        t1 = asyncio.create_task(_c1())
+        t2 = asyncio.create_task(_c2())
+        await asyncio.wait_for(ready1.wait(), timeout=2.0)
+        await asyncio.wait_for(ready2.wait(), timeout=2.0)
+
+        await self.bus.publish("ch", {"x": 42})
+
+        await asyncio.wait_for(t1, timeout=2.0)
+        await asyncio.wait_for(t2, timeout=2.0)
+        self.assertEqual(r1, [{"x": 42}])
+        self.assertEqual(r2, [{"x": 42}])
+
+
+class TestLockPrimitive(IsolatedAsyncioTestCase):
+    """Mode E — distributed mutex (process-local asyncio.Lock)."""
+
+    async def asyncSetUp(self) -> None:
+        self._stack = AsyncExitStack()
+        self.bus = await self._stack.enter_async_context(
+            InMemoryMessageBus(),
+        )
+
+    async def asyncTearDown(self) -> None:
+        await self._stack.aclose()
+
+    async def test_is_locked_reflects_acquire_release(self) -> None:
+        """``is_locked`` flips to True while the body runs and back to
+        False once the context exits."""
+        self.assertFalse(await self.bus.is_locked("k"))
+        async with self.bus.acquire_lock("k", ttl_secs=10):
+            self.assertTrue(await self.bus.is_locked("k"))
+        self.assertFalse(await self.bus.is_locked("k"))
+
+    async def test_second_acquirer_waits_until_release(self) -> None:
+        """A second ``acquire_lock`` on the same key blocks until the
+        first releases."""
+        order: list[str] = []
+
+        async def _holder() -> None:
+            async with self.bus.acquire_lock("k", ttl_secs=10):
+                order.append("first-in")
+                await asyncio.sleep(0.05)
+                order.append("first-out")
+
+        async def _challenger() -> None:
+            await asyncio.sleep(0.005)
+            async with self.bus.acquire_lock("k", ttl_secs=10):
+                order.append("second-in")
+
+        await asyncio.gather(_holder(), _challenger())
+        self.assertEqual(
+            order,
+            ["first-in", "first-out", "second-in"],
+        )
+
+
+class TestRegistryPrimitive(IsolatedAsyncioTestCase):
+    """Mode F — ``registry_*`` hash-keyed namespace operations."""
+
+    async def asyncSetUp(self) -> None:
+        self._stack = AsyncExitStack()
+        self.bus = await self._stack.enter_async_context(
+            InMemoryMessageBus(),
+        )
+
+    async def asyncTearDown(self) -> None:
+        await self._stack.aclose()
+
+    async def test_set_then_exists_and_getall(self) -> None:
+        """``registry_set`` stores a field; ``exists`` and ``getall``
+        round-trip correctly."""
+        await self.bus.registry_set("ns", "f1", "v1")
+        await self.bus.registry_set("ns", "f2", "v2")
+
+        self.assertTrue(await self.bus.registry_exists("ns", "f1"))
+        self.assertTrue(await self.bus.registry_exists("ns", "f2"))
+        self.assertFalse(await self.bus.registry_exists("ns", "missing"))
+        self.assertFalse(await self.bus.registry_exists("other-ns", "f1"))
+
+        self.assertEqual(
+            await self.bus.registry_getall("ns"),
+            {"f1": "v1", "f2": "v2"},
+        )
+
+    async def test_set_overwrites_existing_field(self) -> None:
+        """A second ``registry_set`` for the same field overwrites."""
+        await self.bus.registry_set("ns", "f", "v1")
+        await self.bus.registry_set("ns", "f", "v2")
+        self.assertEqual(
+            await self.bus.registry_getall("ns"),
+            {"f": "v2"},
+        )
+
+    async def test_del_removes_only_the_named_field(self) -> None:
+        """``registry_del`` removes a single field; siblings survive."""
+        await self.bus.registry_set("ns", "keep", "k")
+        await self.bus.registry_set("ns", "drop", "d")
+        await self.bus.registry_del("ns", "drop")
+        self.assertFalse(await self.bus.registry_exists("ns", "drop"))
+        self.assertTrue(await self.bus.registry_exists("ns", "keep"))
+
+    async def test_del_missing_field_is_noop(self) -> None:
+        """Deleting a non-existent field does not raise."""
+        await self.bus.registry_del("ns", "nope")
+
+    async def test_getall_on_missing_namespace_returns_empty(self) -> None:
+        """``registry_getall`` for an unknown namespace returns ``{}``."""
+        self.assertEqual(await self.bus.registry_getall("ghost"), {})
+
+    async def test_drop_deletes_entire_namespace(self) -> None:
+        """``registry_drop`` removes every field under the namespace."""
+        await self.bus.registry_set("ns", "f1", "v1")
+        await self.bus.registry_set("ns", "f2", "v2")
+        await self.bus.registry_drop("ns")
+        self.assertEqual(await self.bus.registry_getall("ns"), {})
+
+    async def test_drop_missing_namespace_is_noop(self) -> None:
+        """Dropping a namespace that was never written does not raise."""
+        await self.bus.registry_drop("never-existed")
+
+    async def test_getall_returns_copy(self) -> None:
+        """Mutating the returned dict does not affect bus state."""
+        await self.bus.registry_set("ns", "f", "v")
+        out = await self.bus.registry_getall("ns")
+        out["injected"] = "evil"
+        self.assertEqual(
+            await self.bus.registry_getall("ns"),
+            {"f": "v"},
+        )
+
+
+class TestDomainHelpers(IsolatedAsyncioTestCase):
+    """Domain helpers inherited from ``MessageBus`` work end-to-end
+    on the in-memory backend."""
+
+    async def asyncSetUp(self) -> None:
+        self._stack = AsyncExitStack()
+        self.bus = await self._stack.enter_async_context(
+            InMemoryMessageBus(),
+        )
+
+    async def asyncTearDown(self) -> None:
+        await self._stack.aclose()
+
+    async def test_session_run_trims_log_on_exit(self) -> None:
+        """``session_run`` + ``session_publish_event`` + auto trim."""
+        sid = "s-trim"
+        async with self.bus.session_run(sid):
+            await self.bus.session_publish_event(sid, {"i": 1})
+            await self.bus.session_publish_event(sid, {"i": 2})
+            mid = await self.bus.session_read_events(sid)
+            self.assertEqual([p["i"] for _id, p in mid], [1, 2])
+        self.assertEqual(await self.bus.session_read_events(sid), [])
+
+    async def test_session_is_running_reflects_lock(self) -> None:
+        """``session_is_running`` is True while inside ``session_run``."""
+        sid = "s-isrun"
+        self.assertFalse(await self.bus.session_is_running(sid))
+        async with self.bus.session_run(sid):
+            self.assertTrue(await self.bus.session_is_running(sid))
+        self.assertFalse(await self.bus.session_is_running(sid))
+
+    async def test_inbox_round_trip(self) -> None:
+        """``inbox_push`` + ``inbox_drain`` FIFO semantics."""
+        sid = "s-inbox"
+        await self.bus.inbox_push(sid, {"hint": "a"})
+        await self.bus.inbox_push(sid, {"hint": "b"})
+        entries = await self.bus.inbox_drain(sid, max_count=10)
+        self.assertEqual(
+            [p["hint"] for _id, p in entries],
+            ["a", "b"],
+        )
+        self.assertEqual(
+            await self.bus.inbox_drain(sid, max_count=10),
+            [],
+        )
+
+    async def test_enqueue_wakeup_round_trip(self) -> None:
+        """``enqueue_wakeup`` → ``dequeue_wakeups`` round-trip."""
+        ready = asyncio.Event()
+        received: list[dict] = []
+
+        async def _signal_consumer() -> None:
+            async for payload in self.bus.subscribe_wakeup_signal(
+                on_ready=ready.set,
+            ):
+                received.append(payload)
+                break
+
+        task = asyncio.create_task(_signal_consumer())
+        await asyncio.wait_for(ready.wait(), timeout=2.0)
+
+        await self.bus.enqueue_wakeup(
+            user_id="u",
+            session_id="s",
+            agent_id="a",
+        )
+        await asyncio.wait_for(task, timeout=2.0)
+        self.assertEqual(len(received), 1)
+
+        entries = await self.bus.dequeue_wakeups(max_count=10)
+        self.assertEqual(len(entries), 1)
+        self.assertEqual(
+            entries[0],
+            {
+                "user_id": "u",
+                "session_id": "s",
+                "agent_id": "a",
+                "kind": "wake",
+                "input": None,
+            },
+        )
+
+    async def test_bg_task_round_trip(self) -> None:
+        """``bg_task_register / exists / list / unregister / purge``
+        work on the in-memory backend."""
+        sid = "s-bg"
+        self.assertFalse(await self.bus.bg_task_exists(sid, "t1"))
+
+        await self.bus.bg_task_register(sid, "t1", '{"tool":"a"}')
+        await self.bus.bg_task_register(sid, "t2", '{"tool":"b"}')
+
+        self.assertTrue(await self.bus.bg_task_exists(sid, "t1"))
+        self.assertEqual(
+            await self.bus.bg_task_list(sid),
+            {"t1": '{"tool":"a"}', "t2": '{"tool":"b"}'},
+        )
+
+        await self.bus.bg_task_unregister(sid, "t1")
+        self.assertFalse(await self.bus.bg_task_exists(sid, "t1"))
+
+        await self.bus.bg_task_purge(sid)
+        self.assertEqual(await self.bus.bg_task_list(sid), {})
+
+    async def test_session_purge_clears_all_bus_state(self) -> None:
+        """``session_purge`` deletes the session's events + inbox +
+        bg_tasks in one call."""
+        sid = "s-purge"
+        await self.bus.session_publish_event(sid, {"e": 1})
+        await self.bus.inbox_push(sid, {"m": 1})
+        await self.bus.bg_task_register(sid, "t1", "{}")
+
+        await self.bus.session_purge(sid)
+
+        self.assertEqual(await self.bus.session_read_events(sid), [])
+        self.assertEqual(
+            await self.bus.inbox_drain(sid, max_count=10),
+            [],
+        )
+        self.assertEqual(await self.bus.bg_task_list(sid), {})
+
+    async def test_task_cancel_pub_sub(self) -> None:
+        """``task_publish_cancel`` → ``task_subscribe_cancel``
+        round-trip."""
+        ready = asyncio.Event()
+        received: list[str] = []
+
+        async def _consumer() -> None:
+            async for tid in self.bus.task_subscribe_cancel(
+                on_ready=ready.set,
+            ):
+                received.append(tid)
+                break
+
+        task = asyncio.create_task(_consumer())
+        await asyncio.wait_for(ready.wait(), timeout=2.0)
+
+        await self.bus.task_publish_cancel("task-X")
+        await asyncio.wait_for(task, timeout=2.0)
+
+        self.assertEqual(received, ["task-X"])
diff --git a/tests/index_worker_lease_test.py b/tests/index_worker_lease_test.py
new file mode 100644
index 0000000..f5399b6
--- /dev/null
+++ b/tests/index_worker_lease_test.py
@@ -0,0 +1,196 @@
+# -*- coding: utf-8 -*-
+"""Regression tests for :class:`IndexWorker.process` lease handling.
+
+The pipeline must stop the moment the lease has been stolen by the
+sweeper — otherwise the original worker and the worker that just took
+over both write the same document into the vector store, producing
+duplicate chunks (PR #1926 unresolved review #discussion_r3479544207).
+"""
+import asyncio
+from datetime import timedelta
+from typing import Any
+from unittest import IsolatedAsyncioTestCase
+
+from agentscope.app._service._index_worker import IndexWorker
+
+
+class _LeaseStorage:
+    """Minimal storage stub recording lifecycle calls.
+
+    Driven by a per-document ``renew_results`` queue so tests can stage
+    a "renew returns True a few times, then False" pattern that mirrors
+    a sweeper reaping a slow worker.
+    """
+
+    def __init__(self) -> None:
+        self.acquire_returns: bool = True
+        self.renew_results: list[bool] = []
+        self.released: list[dict] = []
+        self.status_updates: list[dict] = []
+        self.renew_calls = 0
+
+    async def acquire_knowledge_document_lease(
+        self,
+        **kwargs: Any,
+    ) -> bool:
+        """Return the staged ``acquire_returns`` flag."""
+        del kwargs
+        return self.acquire_returns
+
+    async def renew_knowledge_document_lease(
+        self,
+        **kwargs: Any,
+    ) -> bool:
+        """Pop next staged renew result; default to ``True`` once drained."""
+        del kwargs
+        self.renew_calls += 1
+        if not self.renew_results:
+            return True
+        return self.renew_results.pop(0)
+
+    async def release_knowledge_document_lease(
+        self,
+        **kwargs: Any,
+    ) -> None:
+        """Record the release call so tests can assert it ran."""
+        self.released.append(kwargs)
+
+    async def update_knowledge_document_status(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+        document_id: str,
+        status: str,
+        error: str | None = None,
+        chunk_count: int | None = None,
+    ) -> None:
+        """Record the status transition for later assertion."""
+        del user_id, knowledge_base_id, document_id
+        self.status_updates.append(
+            {
+                "status": status,
+                "error": error,
+                "chunk_count": chunk_count,
+            },
+        )
+
+
+class _SlowPipelineWorker(IndexWorker):
+    """Replaces ``_run_pipeline`` with a long sleep so we can race the
+    lease timer.
+
+    The whole point of the regression is "what happens if a worker is
+    *still in_progress* when its lease is taken away" — the only way to
+    test that deterministically without standing up an embedding model
+    and a vector store is to make the pipeline trivially long-running.
+    """
+
+    def __init__(self, storage: _LeaseStorage, pipeline_seconds: float):
+        # Skip the real __init__ — we only need a handful of fields.
+        self._storage = storage  # type: ignore[assignment]
+        self._node_id = "test-node"
+        self._lease_ttl = timedelta(seconds=10)
+        self._sem = asyncio.Semaphore(4)
+        # Renew quickly so a False result is visible within the test.
+        self._renew_interval = timedelta(seconds=0.05)
+        self._pipeline_seconds = pipeline_seconds
+        self.pipeline_started = asyncio.Event()
+        self.pipeline_cancelled = False
+        self.pipeline_completed = False
+
+    async def _run_pipeline(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+        document_id: str,
+    ) -> None:
+        """Sleep ``pipeline_seconds`` so the test can race the heartbeat."""
+        del user_id, knowledge_base_id, document_id
+        self.pipeline_started.set()
+        try:
+            await asyncio.sleep(self._pipeline_seconds)
+            self.pipeline_completed = True
+        except asyncio.CancelledError:
+            self.pipeline_cancelled = True
+            raise
+
+
+class IndexWorkerLeaseTest(IsolatedAsyncioTestCase):
+    """Pipeline-vs-heartbeat race coverage."""
+
+    async def test_lost_lease_cancels_pipeline_and_marks_error(self) -> None:
+        """Renew returning False mid-pipeline must abort the pipeline.
+
+        Otherwise the original worker keeps running while the new
+        worker (that took over the lease) also runs — both end up
+        inserting the same chunks into the vector store.
+        """
+        storage = _LeaseStorage()
+        # First renew succeeds, second renew fails (sweeper stole it).
+        storage.renew_results = [True, False]
+
+        worker = _SlowPipelineWorker(storage, pipeline_seconds=5.0)
+        # Bound the test so a regression hangs visibly rather than
+        # silently passing.
+        await asyncio.wait_for(
+            worker.process("u", "kb", "doc-1"),
+            timeout=3.0,
+        )
+
+        self.assertTrue(
+            worker.pipeline_started.is_set(),
+            "Pipeline never started.",
+        )
+        self.assertTrue(
+            worker.pipeline_cancelled,
+            "Pipeline was NOT cancelled after the lease was lost — "
+            "this is the regression PR #1926 review flagged.",
+        )
+        self.assertFalse(
+            worker.pipeline_completed,
+            "Pipeline ran to completion despite the lost lease.",
+        )
+
+        # _mark_error must have recorded the lost-lease reason.
+        errors = [u for u in storage.status_updates if u["status"] == "error"]
+        self.assertEqual(len(errors), 1)
+        self.assertIn("Lost lease", errors[0]["error"])
+
+        # Release is still called (and is a safe no-op server-side).
+        self.assertEqual(len(storage.released), 1)
+
+    async def test_happy_path_cancels_heartbeat_and_releases(self) -> None:
+        """Normal completion still tears the heartbeat down cleanly."""
+        storage = _LeaseStorage()
+        # Heartbeat always succeeds.
+        storage.renew_results = []
+
+        worker = _SlowPipelineWorker(storage, pipeline_seconds=0.05)
+        await asyncio.wait_for(
+            worker.process("u", "kb", "doc-ok"),
+            timeout=2.0,
+        )
+
+        self.assertTrue(worker.pipeline_completed)
+        self.assertFalse(worker.pipeline_cancelled)
+        # No error update on the happy path.
+        self.assertEqual(
+            [u for u in storage.status_updates if u["status"] == "error"],
+            [],
+        )
+        self.assertEqual(len(storage.released), 1)
+
+    async def test_not_acquired_short_circuits(self) -> None:
+        """When the lease is already held by another worker, do nothing."""
+        storage = _LeaseStorage()
+        storage.acquire_returns = False
+
+        worker = _SlowPipelineWorker(storage, pipeline_seconds=5.0)
+        await asyncio.wait_for(
+            worker.process("u", "kb", "doc-locked"),
+            timeout=1.0,
+        )
+
+        self.assertFalse(worker.pipeline_started.is_set())
+        # No release either — we never held the lease.
+        self.assertEqual(storage.released, [])
diff --git a/tests/mcp_sse_client_test.py b/tests/mcp_sse_client_test.py
new file mode 100644
index 0000000..f7df710
--- /dev/null
+++ b/tests/mcp_sse_client_test.py
@@ -0,0 +1,376 @@
+# -*- coding: utf-8 -*-
+"""The MCP client test module in agentscope."""
+import asyncio
+import json
+from multiprocessing import Process
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from mcp.server import FastMCP
+from pydantic import BaseModel
+
+from agentscope.mcp import MCPClient, HttpMCPConfig
+from agentscope.message import ToolCallBlock
+from agentscope.tool import ToolResponse, ToolChunk, Toolkit
+from agentscope.state import AgentState
+
+
+async def tool_1(arg1: str, arg2: list[int]) -> str:
+    """A test tool function.
+
+    Args:
+        arg1 (`str`):
+            The first argument named arg1.
+        arg2 (`list[int]`):
+            The second argument named arg2.
+    """
+    return f"arg1: {arg1}, arg2: {arg2}"
+
+
+def setup_server() -> None:
+    """Set up the streamable HTTP MCP server."""
+    sse_server = FastMCP("SSE", port=8003)
+    sse_server.tool(description="A test tool function.")(tool_1)
+    sse_server.run(transport="sse")
+
+
+# ---------------------------------------------------------------------------
+# Server / tool definitions for $defs preservation test
+# ---------------------------------------------------------------------------
+
+
+class _ItemConfig(BaseModel):
+    """Config sub-model to generate $defs in the MCP inputSchema."""
+
+    key: str
+    count: int
+
+
+async def tool_with_model(name: str, config: _ItemConfig) -> str:
+    """A tool whose parameter uses a Pydantic sub-model.
+
+    Args:
+        name: Item name.
+        config: Item configuration.
+    """
+    return f"name={name}, key={config.key}, count={config.count}"
+
+
+def setup_defs_server() -> None:
+    """Set up an SSE MCP server that exposes a tool with Pydantic
+    sub-models."""
+    server = FastMCP("DefsSSE", port=8005)
+    server.tool()(tool_with_model)
+    server.run(transport="sse")
+
+
+class SseMCPClientTest(IsolatedAsyncioTestCase):
+    """Test class for MCP server functionality."""
+
+    async def asyncTearDown(self) -> None:
+        """Tear down the test environment."""
+        del self.toolkit
+
+        while self.process.is_alive():
+            self.process.terminate()
+            await asyncio.sleep(5)
+
+    async def asyncSetUp(self) -> None:
+        """Set up the test environment."""
+        self.port = 8003
+        self.process = Process(target=setup_server)
+        self.process.start()
+        await asyncio.sleep(10)
+
+        self.toolkit = Toolkit()
+        self.schemas = [
+            {
+                "type": "function",
+                "function": {
+                    "name": "mcp__test_sse_client__tool_1",
+                    "description": "A test tool function.",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {
+                            "arg1": {
+                                "type": "string",
+                            },
+                            "arg2": {
+                                "items": {
+                                    "type": "integer",
+                                },
+                                "type": "array",
+                            },
+                        },
+                        "required": [
+                            "arg1",
+                            "arg2",
+                        ],
+                    },
+                },
+            },
+        ]
+
+    async def test_stateless_client(self) -> None:
+        """Test the stateless sse MCP client."""
+        # Create stateless client (is_stateful=False)
+        stateless_client = MCPClient(
+            name="test_sse_client",
+            is_stateful=False,
+            mcp_config=HttpMCPConfig(
+                type="http_mcp",
+                url=f"http://127.0.0.1:{self.port}/sse",
+            ),
+        )
+
+        mcp_tool_1 = await stateless_client.get_tool("tool_1")
+        # Repeat to ensure idempotency
+        res_1: ToolChunk = await mcp_tool_1(arg1="123", arg2=[1, 2, 3])
+        res_2: ToolChunk = await mcp_tool_1(arg1="345", arg2=[4, 5, 6])
+        res_3: ToolChunk = await mcp_tool_1(arg1="345", arg2=[4, 5, 6])
+
+        self.assertEqual(
+            res_1.content[0].text,
+            "arg1: 123, arg2: [1, 2, 3]",
+        )
+        self.assertEqual(
+            res_2.content[0].text,
+            "arg1: 345, arg2: [4, 5, 6]",
+        )
+        self.assertEqual(
+            res_3.content[0].text,
+            "arg1: 345, arg2: [4, 5, 6]",
+        )
+
+        # Register MCPTool via Toolkit constructor
+        toolkit_with_mcp = Toolkit(tools=[mcp_tool_1])
+
+        schemas = await toolkit_with_mcp.get_tool_schemas()
+
+        self.assertListEqual(
+            schemas,
+            self.schemas,
+        )
+
+        state = AgentState()
+        res_gen = toolkit_with_mcp.call_tool(
+            ToolCallBlock(
+                id="xx",
+                type="tool_call",
+                name="mcp__test_sse_client__tool_1",
+                input=json.dumps(
+                    {
+                        "arg1": "789",
+                        "arg2": [7, 8, 9],
+                    },
+                ),
+            ),
+            state=state,
+        )
+
+        final_response = None
+        async for chunk in res_gen:
+            if isinstance(chunk, ToolResponse):
+                final_response = chunk
+            else:
+                self.assertIsInstance(chunk, ToolChunk)
+
+        self.assertIsNotNone(final_response)
+        self.assertEqual(
+            final_response.content[0].text,
+            "arg1: 789, arg2: [7, 8, 9]",
+        )
+
+        self.toolkit.clear()
+        self.assertListEqual(self.toolkit.tool_groups, [])
+
+        # Try to add the mcp client
+        self.toolkit = Toolkit(mcps=[stateless_client])
+        self.assertListEqual(
+            await self.toolkit.get_tool_schemas(),
+            self.schemas,
+        )
+
+        self.toolkit.clear()
+
+    async def test_stateful_client(self) -> None:
+        """Test the stateful sse MCP client."""
+
+        # Test stateful client (is_stateful=True)
+        stateful_client = MCPClient(
+            name="test_sse_client",
+            is_stateful=True,
+            mcp_config=HttpMCPConfig(
+                type="http_mcp",
+                url=f"http://127.0.0.1:{self.port}/sse",
+            ),
+        )
+
+        self.assertFalse(stateful_client.is_connected)
+        await stateful_client.connect()
+
+        self.assertTrue(stateful_client.is_connected)
+
+        mcp_tool_1 = await stateful_client.get_tool("tool_1")
+        # Repeat to ensure idempotency
+        res_1: ToolChunk = await mcp_tool_1(arg1="12", arg2=[1, 2])
+        res_2: ToolChunk = await mcp_tool_1(arg1="34", arg2=[4, 5])
+        res_3: ToolChunk = await mcp_tool_1(arg1="34", arg2=[4, 5])
+
+        self.assertEqual(
+            res_1.content[0].text,
+            "arg1: 12, arg2: [1, 2]",
+        )
+        self.assertEqual(
+            res_2.content[0].text,
+            "arg1: 34, arg2: [4, 5]",
+        )
+        self.assertEqual(
+            res_3.content[0].text,
+            "arg1: 34, arg2: [4, 5]",
+        )
+
+        # with toolkit - Register MCPTool via Toolkit constructor
+        toolkit_with_mcp = Toolkit(tools=[mcp_tool_1])
+
+        self.assertListEqual(
+            await toolkit_with_mcp.get_tool_schemas(),
+            self.schemas,
+        )
+
+        state = AgentState()
+        res_gen = toolkit_with_mcp.call_tool(
+            ToolCallBlock(
+                id="xx",
+                type="tool_call",
+                name="mcp__test_sse_client__tool_1",
+                input=json.dumps(
+                    {
+                        "arg1": "56",
+                        "arg2": [5, 6],
+                    },
+                ),
+            ),
+            state=state,
+        )
+
+        final_response = None
+        async for chunk in res_gen:
+            if isinstance(chunk, ToolResponse):
+                final_response = chunk
+            else:
+                self.assertIsInstance(chunk, ToolChunk)
+
+        self.assertIsNotNone(final_response)
+        self.assertEqual(
+            final_response.content[0].text,
+            "arg1: 56, arg2: [5, 6]",
+        )
+
+        # mcp client level test
+        self.toolkit.clear()
+        self.assertListEqual(self.toolkit.tool_groups, [])
+
+        self.toolkit = Toolkit(mcps=[stateful_client])
+        self.assertListEqual(
+            await self.toolkit.get_tool_schemas(),
+            self.schemas,
+        )
+
+        await stateful_client.close()
+        self.assertFalse(stateful_client.is_connected)
+
+
+class SseSchemaDefsPreservationTest(IsolatedAsyncioTestCase):
+    """End-to-end tests for $defs preservation in MCP tool schemas.
+
+    These tests start a real FastMCP server that exposes a tool whose
+    parameter is a Pydantic sub-model.  FastMCP generates an inputSchema with
+    ``$defs`` for the sub-model.  We verify that the schema returned by
+    ``await toolkit.get_tool_schemas()`` preserves those ``$defs`` and that
+    Pydantic-generated ``title`` fields inside ``$defs`` are stripped.
+    """
+
+    async def asyncSetUp(self) -> None:
+        """Start the $defs test server."""
+        self.port = 8005
+        self.process = Process(target=setup_defs_server)
+        self.process.start()
+        await asyncio.sleep(10)
+
+        self.schemas = [
+            {
+                "type": "function",
+                "function": {
+                    "name": "mcp__test_defs_client__tool_with_model",
+                    "description": "A tool whose parameter uses a "
+                    "Pydantic sub-model.\n\n    Args:\n        "
+                    "name: Item name.\n        "
+                    "config: Item configuration.\n    ",
+                    "parameters": {
+                        "$defs": {
+                            "_ItemConfig": {
+                                "description": "Config sub-model to "
+                                "generate $defs in the "
+                                "MCP inputSchema.",
+                                "properties": {
+                                    "key": {"type": "string"},
+                                    "count": {"type": "integer"},
+                                },
+                                "required": ["key", "count"],
+                                "type": "object",
+                            },
+                        },
+                        "properties": {
+                            "name": {"type": "string"},
+                            "config": {"$ref": "#/$defs/_ItemConfig"},
+                        },
+                        "required": ["name", "config"],
+                        "type": "object",
+                    },
+                },
+            },
+        ]
+
+    async def asyncTearDown(self) -> None:
+        """Stop the $defs test server."""
+        while self.process.is_alive():
+            self.process.terminate()
+            await asyncio.sleep(5)
+
+    async def test_defs_preserved_and_titles_stripped(self) -> None:
+        """$defs from Pydantic sub-model parameters must survive the full
+        pipeline.
+
+        Failure scenario (before fix):
+            MCPTool.__init__ only copied ``properties`` and ``required``,
+            so ``$defs._ItemConfig`` was silently dropped.  The LLM would
+            receive a schema where ``config`` had an unresolvable
+            ``$ref: "#/$defs/_ItemConfig"``.
+
+        Expected behaviour (after fix):
+            - ``MCPTool.input_schema`` contains ``$defs._ItemConfig``
+            - ``await toolkit.get_tool_schemas()`` output contains ``$defs``
+              with the ref resolved and Pydantic titles stripped.
+        """
+        client = MCPClient(
+            name="test_defs_client",
+            is_stateful=False,
+            mcp_config=HttpMCPConfig(
+                type="http_mcp",
+                url=f"http://127.0.0.1:{self.port}/sse",
+            ),
+        )
+
+        mcp_tool = await client.get_tool("tool_with_model")
+
+        # 1. input_schema must preserve $defs
+        self.assertIn(
+            "$defs",
+            mcp_tool.input_schema,
+            "MCPTool.input_schema must preserve $defs from inputSchema",
+        )
+
+        # 2. get_tool_schemas() must preserve $defs and strip titles
+        toolkit = Toolkit(tools=[mcp_tool])
+        schemas = await toolkit.get_tool_schemas()
+        self.assertListEqual(schemas, self.schemas)
diff --git a/tests/mcp_streamable_http_client_test.py b/tests/mcp_streamable_http_client_test.py
new file mode 100644
index 0000000..49a25a4
--- /dev/null
+++ b/tests/mcp_streamable_http_client_test.py
@@ -0,0 +1,147 @@
+# -*- coding: utf-8 -*-
+"""The MCP client test module in agentscope."""
+import asyncio
+from multiprocessing import Process
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from mcp.server import FastMCP
+from mcp.types import EmbeddedResource, TextResourceContents
+
+from agentscope.mcp import MCPClient, HttpMCPConfig
+from agentscope.tool import ToolChunk
+
+
+async def tool_1(arg1: str, arg2: list[int]) -> str:
+    """A test tool function.
+
+    Args:
+        arg1 (`str`):
+            The first argument named arg1.
+        arg2 (`list[int]`):
+            The second argument named arg2.
+    """
+    return f"arg1: {arg1}, arg2: {arg2}"
+
+
+async def tool_2() -> list:
+    """
+    A test tool function return the EmbeddedResource type
+    """
+    return [
+        EmbeddedResource(
+            type="resource",
+            resource=TextResourceContents(
+                uri="file://tmp.txt",
+                mimeType="text/plain",
+                text="test content",
+            ),
+        ),
+    ]
+
+
+def setup_server() -> None:
+    """Set up the streamable HTTP MCP server."""
+    sse_server = FastMCP("StreamableHTTP", port=8002)
+    sse_server.tool(description="A test tool function.")(tool_1)
+    sse_server.tool(
+        description="A test tool function with embedded resource.",
+    )(tool_2)
+    sse_server.run(transport="streamable-http")
+
+
+class StreamableHttpMCPClientTest(IsolatedAsyncioTestCase):
+    """Test class for streamable HTTP MCP client."""
+
+    async def asyncTearDown(self) -> None:
+        """Tear down the test environment."""
+        while self.process.is_alive():
+            self.process.terminate()
+            await asyncio.sleep(5)
+
+    async def asyncSetUp(self) -> None:
+        """Set up the test environment."""
+        self.port = 8002
+        self.process = Process(target=setup_server)
+        self.process.start()
+        await asyncio.sleep(10)
+
+    async def test_streamable_http_stateless_client(self) -> None:
+        """Test the MCP server connection functionality."""
+
+        # Test stateless client (is_stateful=False)
+        client = MCPClient(
+            name="test_streamable_http_stateless_client",
+            is_stateful=False,
+            mcp_config=HttpMCPConfig(
+                type="http_mcp",
+                url=f"http://127.0.0.1:{self.port}/mcp",
+            ),
+        )
+
+        my_tool_1 = await client.get_tool("tool_1")
+        res_1: ToolChunk = await my_tool_1(arg1="123", arg2=[1, 2, 3])
+        self.assertEqual(
+            res_1.content[0].text,
+            "arg1: 123, arg2: [1, 2, 3]",
+        )
+
+        res_2: ToolChunk = await my_tool_1(arg1="345", arg2=[4, 5, 6])
+        self.assertEqual(
+            res_2.content[0].text,
+            "arg1: 345, arg2: [4, 5, 6]",
+        )
+
+        # Test stateful client (is_stateful=True)
+        client = MCPClient(
+            name="test_streamable_http_stateful_client",
+            is_stateful=True,
+            mcp_config=HttpMCPConfig(
+                type="http_mcp",
+                url=f"http://127.0.0.1:{self.port}/mcp",
+            ),
+        )
+
+        self.assertFalse(client.is_connected)
+        await client.connect()
+
+        self.assertTrue(client.is_connected)
+
+        my_tool_1 = await client.get_tool("tool_1")
+        res_3: ToolChunk = await my_tool_1(arg1="12", arg2=[1, 2])
+        self.assertEqual(
+            res_3.content[0].text,
+            "arg1: 12, arg2: [1, 2]",
+        )
+
+        res_4: ToolChunk = await my_tool_1(arg1="34", arg2=[4, 5])
+        self.assertEqual(
+            res_4.content[0].text,
+            "arg1: 34, arg2: [4, 5]",
+        )
+
+        await client.close()
+        self.assertFalse(client.is_connected)
+
+    async def test_embedded_content(self) -> None:
+        """Test the EmbeddedContent functionality."""
+        # Test with stateless client (is_stateful=False)
+        client = MCPClient(
+            name="test_embedded_content",
+            is_stateful=False,
+            mcp_config=HttpMCPConfig(
+                type="http_mcp",
+                url=f"http://127.0.0.1:{self.port}/mcp",
+            ),
+        )
+
+        my_tool_2 = await client.get_tool("tool_2")
+        res: ToolChunk = await my_tool_2()
+        self.assertEqual(
+            res.content[0].text,
+            """{
+  "uri": "file://tmp.txt/",
+  "mimeType": "text/plain",
+  "meta": null,
+  "text": "test content"
+}""",
+        )
diff --git a/tests/mem0_agentscope_adapter_test.py b/tests/mem0_agentscope_adapter_test.py
new file mode 100644
index 0000000..552febe
--- /dev/null
+++ b/tests/mem0_agentscope_adapter_test.py
@@ -0,0 +1,462 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=wrong-import-order
+"""Unit tests for the AgentScope ↔ mem0 adapters.
+
+Verifies that ``AgentScopeLLM`` / ``AgentScopeEmbedding`` correctly
+translate between mem0's sync OpenAI-style contract and AgentScope's
+async ``Msg`` / ``ContentBlock`` / ``EmbeddingResponse`` shapes, and
+that ``register_with_mem0`` plugs them into mem0's factories.
+"""
+import asyncio
+import json
+import unittest
+from typing import Any
+
+from agentscope.credential import DashScopeCredential
+from agentscope.embedding import EmbeddingModelBase, EmbeddingResponse
+from agentscope.message import (
+    Msg,
+    TextBlock,
+    ThinkingBlock,
+    ToolCallBlock,
+)
+from agentscope.middleware._longterm_memory._mem0._agentscope_adapter import (
+    AgentScopeEmbedding,
+    AgentScopeLLM,
+    _convert_messages_to_agentscope,
+    _parse_chat_response,
+    build_mem0_config,
+)
+from agentscope.model import ChatResponse
+from utils import MockModel
+
+
+# ----------------------------------------------------------------------
+# Pure helpers
+# ----------------------------------------------------------------------
+
+
+class TestConvertMessages(unittest.TestCase):
+    """Tests for converting mem0 dict messages into AgentScope messages."""
+
+    def test_three_roles_map_to_correct_role(self) -> None:
+        """System, user, and assistant roles should be preserved."""
+        msgs = _convert_messages_to_agentscope(
+            [
+                {"role": "system", "content": "you are helpful"},
+                {"role": "user", "content": "hi"},
+                {"role": "assistant", "content": "hello"},
+            ],
+        )
+        self.assertEqual(
+            [m.role for m in msgs],
+            ["system", "user", "assistant"],
+        )
+        self.assertTrue(all(isinstance(m, Msg) for m in msgs))
+        self.assertEqual(msgs[1].get_text_content(), "hi")
+
+    def test_unknown_role_dropped(self) -> None:
+        """Unsupported message roles should be skipped."""
+        msgs = _convert_messages_to_agentscope(
+            [
+                {"role": "tool", "content": "noise"},
+                {"role": "user", "content": "real"},
+            ],
+        )
+        self.assertEqual(len(msgs), 1)
+        self.assertEqual(msgs[0].role, "user")
+
+
+class TestParseChatResponse(unittest.TestCase):
+    """Tests for converting AgentScope chat responses into mem0 output."""
+
+    def _resp(self, blocks: list) -> ChatResponse:
+        """Build a final chat response from content blocks."""
+        return ChatResponse(content=blocks, is_last=True)
+
+    def test_text_only_returns_string(self) -> None:
+        """Plain text responses should become plain strings."""
+        resp = self._resp([TextBlock(type="text", text="answer")])
+        self.assertEqual(_parse_chat_response(resp, has_tool=False), "answer")
+
+    def test_thinking_prefixed_to_text(self) -> None:
+        """Thinking blocks should be preserved before visible text."""
+        resp = self._resp(
+            [
+                ThinkingBlock(type="thinking", thinking="hmm"),
+                TextBlock(type="text", text="final"),
+            ],
+        )
+        out = _parse_chat_response(resp, has_tool=False)
+        self.assertIn("hmm", out)
+        self.assertIn("final", out)
+        # thinking comes first to mirror v1 order
+        self.assertLess(out.index("hmm"), out.index("final"))
+
+    def test_tool_call_with_json_string_input(self) -> None:
+        """v2 stores ToolCallBlock.input as a JSON string — adapter
+        must parse it back to a dict for mem0."""
+        resp = self._resp(
+            [
+                TextBlock(type="text", text="calling tool"),
+                ToolCallBlock(
+                    type="tool_call",
+                    id="call_1",
+                    name="lookup",
+                    input=json.dumps({"q": "alice"}),
+                ),
+            ],
+        )
+        out = _parse_chat_response(resp, has_tool=True)
+        self.assertEqual(out["content"], "calling tool")
+        self.assertEqual(
+            out["tool_calls"],
+            [{"name": "lookup", "arguments": {"q": "alice"}}],
+        )
+
+    def test_tool_call_with_malformed_input_keeps_raw(self) -> None:
+        """Malformed JSON tool inputs should remain as raw strings."""
+        resp = self._resp(
+            [
+                ToolCallBlock(
+                    type="tool_call",
+                    id="call_2",
+                    name="lookup",
+                    input="not json",
+                ),
+            ],
+        )
+        out = _parse_chat_response(resp, has_tool=True)
+        self.assertEqual(out["tool_calls"][0]["arguments"], "not json")
+
+    def test_empty_content(self) -> None:
+        """Empty responses should convert to the empty mem0 shapes."""
+        resp = self._resp([])
+        self.assertEqual(_parse_chat_response(resp, has_tool=False), "")
+        self.assertEqual(
+            _parse_chat_response(resp, has_tool=True),
+            {"content": "", "tool_calls": []},
+        )
+
+
+# ----------------------------------------------------------------------
+# AgentScopeLLM end-to-end (fake AgentScope model on caller event loop)
+# ----------------------------------------------------------------------
+
+
+class _CurrentEventLoopTestCase(unittest.TestCase):
+    """Provides a current event loop for the adapter's sync bridge."""
+
+    _event_loop: asyncio.AbstractEventLoop
+    _previous_event_loop: asyncio.AbstractEventLoop | None
+
+    def setUp(self) -> None:
+        """Install a fresh event loop for each sync-bridge test."""
+        super().setUp()
+        try:
+            self._previous_event_loop = asyncio.get_event_loop()
+        except RuntimeError:
+            self._previous_event_loop = None
+        self._event_loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(self._event_loop)
+
+    def tearDown(self) -> None:
+        """Restore the previous event loop after each test."""
+        asyncio.set_event_loop(self._previous_event_loop)
+        self._event_loop.close()
+        super().tearDown()
+
+
+class _RecordingMockChatModel(MockModel):
+    """Captures the ``messages`` arg so we can assert the v2 Msg
+    objects mem0's dict messages were converted into."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        """Initialize the recording model."""
+        super().__init__(*args, **kwargs)
+        self.received_messages: list[list[Msg]] = []
+
+    async def _call_api(self, *args: Any, **kwargs: Any) -> Any:
+        """Record delivered messages before delegating to MockModel."""
+        self.received_messages.append(list(kwargs.get("messages") or []))
+        return await super()._call_api(*args, **kwargs)
+
+
+class TestAgentScopeLLM(_CurrentEventLoopTestCase):
+    """End-to-end tests for the mem0 LLM adapter."""
+
+    def test_constructor_rejects_non_chatmodel(self) -> None:
+        """The LLM adapter should reject non-AgentScope chat models."""
+        with self.assertRaises(TypeError):
+            AgentScopeLLM(config={"model": object()})
+
+    def test_constructor_requires_model(self) -> None:
+        """The LLM adapter should require a model config entry."""
+        with self.assertRaises(ValueError):
+            AgentScopeLLM(config={})
+
+    def test_generate_response_routes_through_agentscope_model(self) -> None:
+        """mem0 generation should call the wrapped AgentScope model."""
+        model = _RecordingMockChatModel()
+        model.set_responses(
+            [
+                ChatResponse(
+                    content=[TextBlock(type="text", text="from agentscope")],
+                    is_last=True,
+                ),
+            ],
+        )
+        llm = AgentScopeLLM(config={"model": model})
+
+        result = llm.generate_response(
+            [
+                {"role": "system", "content": "sys"},
+                {"role": "user", "content": "hello"},
+            ],
+        )
+        self.assertEqual(result, "from agentscope")
+        # The dict messages were converted to Msg objects with the
+        # correct roles preserved.
+        delivered = model.received_messages[0]
+        self.assertEqual([m.role for m in delivered], ["system", "user"])
+
+    def test_generate_response_with_tools(self) -> None:
+        """Tool-call responses should be converted to mem0's tool shape."""
+        model = _RecordingMockChatModel()
+        model.set_responses(
+            [
+                ChatResponse(
+                    content=[
+                        ToolCallBlock(
+                            type="tool_call",
+                            id="call_3",
+                            name="search",
+                            input=json.dumps({"q": "x"}),
+                        ),
+                    ],
+                    is_last=True,
+                ),
+            ],
+        )
+        llm = AgentScopeLLM(config={"model": model})
+
+        result = llm.generate_response(
+            [{"role": "user", "content": "find x"}],
+            tools=[{"name": "search"}],
+        )
+        self.assertIsInstance(result, dict)
+        self.assertEqual(
+            result["tool_calls"],
+            [{"name": "search", "arguments": {"q": "x"}}],
+        )
+
+    def test_streaming_response_drained_to_last_chunk(self) -> None:
+        """When the AgentScope model streams, the adapter must
+        consume all chunks and use the last (which carries the
+        complete content per AgentScope's streaming contract)."""
+        model = _RecordingMockChatModel()
+        # MockModel.set_responses with a list-of-list triggers stream mode
+        model.set_responses(
+            [
+                [
+                    ChatResponse(
+                        content=[TextBlock(type="text", text="part 1")],
+                        is_last=False,
+                    ),
+                    ChatResponse(
+                        content=[TextBlock(type="text", text="final")],
+                        is_last=True,
+                    ),
+                ],
+            ],
+        )
+        llm = AgentScopeLLM(config={"model": model})
+        result = llm.generate_response(
+            [{"role": "user", "content": "stream"}],
+        )
+        self.assertEqual(result, "final")
+
+    def test_empty_messages_raises(self) -> None:
+        """Dropping all unsupported messages should raise ValueError."""
+        llm = AgentScopeLLM(config={"model": _RecordingMockChatModel()})
+        with self.assertRaises(ValueError):
+            llm.generate_response([{"role": "tool", "content": "ignored"}])
+
+
+# ----------------------------------------------------------------------
+# AgentScopeEmbedding
+# ----------------------------------------------------------------------
+
+
+class _FakeEmbeddingModel(EmbeddingModelBase):
+    """Minimal embedding model that records requested texts."""
+
+    def __init__(self) -> None:
+        """Initialize the fake embedding model."""
+        super().__init__(
+            credential=DashScopeCredential(api_key="fake"),
+            model="fake-embed",
+            parameters=self.Parameters(),
+            context_size=8192,
+            batch_size=10,
+            max_retries=0,
+            retry_delay=0.0,
+            dimensions=3,
+        )
+        self.received: list[list[str]] = []
+
+    async def _call_api(
+        self,
+        inputs: list[str],
+        **kwargs: Any,
+    ) -> EmbeddingResponse:
+        """Return a fixed vector for every input text."""
+        self.received.append(list(inputs))
+        return EmbeddingResponse(
+            embeddings=[[0.1, 0.2, 0.3] for _ in inputs],
+            source="api",
+        )
+
+
+class TestAgentScopeEmbedding(_CurrentEventLoopTestCase):
+    """Tests for the mem0 embedding adapter."""
+
+    def test_constructor_validation(self) -> None:
+        """The embedding adapter should validate model config."""
+        with self.assertRaises(ValueError):
+            AgentScopeEmbedding(config={})
+        with self.assertRaises(TypeError):
+            AgentScopeEmbedding(config={"model": object()})
+
+    def test_embed_single_string(self) -> None:
+        """Single-string inputs should be wrapped before model calls."""
+        model = _FakeEmbeddingModel()
+        emb = AgentScopeEmbedding(config={"model": model})
+        result = emb.embed("hello")
+        self.assertEqual(result, [0.1, 0.2, 0.3])
+        # The string was wrapped into a list before reaching the model.
+        self.assertEqual(model.received, [["hello"]])
+
+    def test_embed_list_of_strings_returns_first(self) -> None:
+        """mem0's contract is that ``embed`` returns ONE vector. We
+        return the first."""
+        model = _FakeEmbeddingModel()
+        emb = AgentScopeEmbedding(config={"model": model})
+        result = emb.embed(["a", "b"])
+        self.assertEqual(result, [0.1, 0.2, 0.3])
+        self.assertEqual(model.received, [["a", "b"]])
+
+
+# ----------------------------------------------------------------------
+# Factory registration
+# ----------------------------------------------------------------------
+
+
+class TestBuildMem0Config(unittest.TestCase):
+    """``build_mem0_config`` must bypass mem0's hardcoded provider
+    whitelist and emit a config that names the AgentScope adapter."""
+
+    def test_models_only_produces_fresh_config(self) -> None:
+        """Models-only construction should create AgentScope providers."""
+        chat = MockModel()
+        emb = _FakeEmbeddingModel()
+        cfg = build_mem0_config(chat_model=chat, embedding_model=emb)
+
+        self.assertEqual(cfg.llm.provider, "agentscope")
+        self.assertEqual(cfg.embedder.provider, "agentscope")
+        self.assertIs(cfg.llm.config["model"], chat)
+        self.assertIs(cfg.embedder.config["model"], emb)
+
+    def test_models_only_requires_both(self) -> None:
+        """Models-only construction should require chat and embedding."""
+        with self.assertRaises(ValueError):
+            build_mem0_config(chat_model=MockModel())
+        with self.assertRaises(ValueError):
+            build_mem0_config(embedding_model=_FakeEmbeddingModel())
+        with self.assertRaises(ValueError):
+            build_mem0_config()
+
+    def test_base_config_with_both_models_preserves_other_fields(
+        self,
+    ) -> None:
+        """When a ``mem0_config`` base is given, vector_store /
+        history_db / etc. should survive — only .llm and .embedder
+        are rewired to the AgentScope adapters."""
+        from mem0.configs.base import MemoryConfig
+
+        base = MemoryConfig(history_db_path="/tmp/custom_history.db")
+        original_vs = base.vector_store
+
+        chat = MockModel()
+        emb = _FakeEmbeddingModel()
+        cfg = build_mem0_config(
+            chat_model=chat,
+            embedding_model=emb,
+            mem0_config=base,
+        )
+
+        self.assertEqual(cfg.llm.provider, "agentscope")
+        self.assertIs(cfg.llm.config["model"], chat)
+        self.assertEqual(cfg.embedder.provider, "agentscope")
+        self.assertIs(cfg.embedder.config["model"], emb)
+        # Non-llm/embedder fields preserved.
+        self.assertEqual(cfg.history_db_path, "/tmp/custom_history.db")
+        self.assertIs(cfg.vector_store, original_vs)
+
+    def test_base_config_with_only_chat_model_partial_override(
+        self,
+    ) -> None:
+        """Partial override: chat_model alone replaces .llm but
+        leaves .embedder untouched (whatever the base config had)."""
+        from mem0.configs.base import MemoryConfig
+
+        base = MemoryConfig()  # base has the default openai embedder
+        original_embedder = base.embedder
+
+        cfg = build_mem0_config(
+            chat_model=MockModel(),
+            mem0_config=base,
+        )
+        self.assertEqual(cfg.llm.provider, "agentscope")
+        # Embedder unchanged from base — still mem0's openai default.
+        self.assertIs(cfg.embedder, original_embedder)
+
+    def test_base_config_alone_is_pass_through(self) -> None:
+        """``mem0_config=base`` with no models is just a pass-through —
+        registration still happens (cheap) but no fields change."""
+        from mem0.configs.base import MemoryConfig
+
+        base = MemoryConfig()
+        cfg = build_mem0_config(mem0_config=base)
+        self.assertIs(cfg, base)
+
+    def test_registers_adapter_in_factory(self) -> None:
+        """The helper side-effect: mem0's factory dicts now know how
+        to resolve provider='agentscope'."""
+        from mem0.utils.factory import EmbedderFactory, LlmFactory
+
+        build_mem0_config(
+            chat_model=MockModel(),
+            embedding_model=_FakeEmbeddingModel(),
+        )
+        self.assertIn("agentscope", LlmFactory.provider_to_class)
+        self.assertIn("agentscope", EmbedderFactory.provider_to_class)
+
+    def test_naive_from_config_path_still_rejected(self) -> None:
+        """Sanity check: confirm WHY the helper exists — calling
+        ``MemoryConfig`` with ``provider='agentscope'`` directly DOES
+        raise, which is the failure ``build_mem0_config`` works around."""
+        from mem0.configs.base import MemoryConfig
+        from pydantic import ValidationError
+
+        with self.assertRaises(ValidationError):
+            MemoryConfig(
+                llm={
+                    "provider": "agentscope",
+                    "config": {"model": MockModel()},
+                },
+                embedder={
+                    "provider": "agentscope",
+                    "config": {"model": _FakeEmbeddingModel()},
+                },
+            )
diff --git a/tests/mem0_middleware_test.py b/tests/mem0_middleware_test.py
new file mode 100644
index 0000000..086de47
--- /dev/null
+++ b/tests/mem0_middleware_test.py
@@ -0,0 +1,891 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access,unused-argument
+"""Unit tests for Mem0Middleware.
+
+The mem0 client itself is mocked — we only exercise the AgentScope hook
+wiring (retrieve-before / write-after, system-prompt injection,
+list_tools exposure) and the small adapter that translates between
+AgentScope and mem0. The OSS ``Memory`` and Platform ``MemoryClient``
+share the same call shape (``search(query, filters=..., top_k=...)``
+and ``add(messages, user_id=..., agent_id=...)``) so one mock covers
+both.
+
+``protected-access`` is disabled because tests legitimately reach into
+middleware internals (``mw._client``, ``mw._async_search``, ``mw._top_k``) to
+inspect what the public API just did.
+"""
+from unittest.async_case import IsolatedAsyncioTestCase
+from unittest.mock import AsyncMock, MagicMock
+from typing import Any
+
+from utils import MockModel
+
+from agentscope.agent import Agent
+from agentscope.event import (
+    ExternalExecutionResultEvent,
+    UserConfirmResultEvent,
+)
+from agentscope.message import HintBlock, Msg, TextBlock, UserMsg
+from agentscope.middleware import Mem0Middleware
+from agentscope.middleware._longterm_memory._mem0._utils import (
+    _extract_memory_texts,
+    _extract_query_text,
+)
+from agentscope.model import ChatResponse
+from agentscope.tool import Toolkit
+
+
+# ----------------------------------------------------------------------
+# Test helpers
+# ----------------------------------------------------------------------
+
+
+class RecordingMockModel(MockModel):
+    """MockModel that captures the ``messages`` of every _call_api call."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        """Initialize the recording mock model."""
+        super().__init__(*args, **kwargs)
+        self.calls: list[list[Msg]] = []
+
+    async def _call_api(
+        self,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Any:
+        """Record messages before delegating to MockModel."""
+        messages = kwargs.get("messages")
+        if messages is None and len(args) >= 2:
+            messages = args[1]
+        self.calls.append(list(messages or []))
+        return await super()._call_api(*args, **kwargs)
+
+    @property
+    def last_call_messages(self) -> list[Msg]:
+        """Return the most recent model-call messages."""
+        return self.calls[-1]
+
+
+class _FakeAsyncMem0Client:
+    """Stands in for any of mem0's four client variants.
+
+    All four expose compatible ``search(query, filters=..., top_k=...)``
+    and ``add(messages, user_id=..., agent_id=...)`` shapes, so a single
+    fake suffices.
+    """
+
+    def __init__(self, search_return: Any = None) -> None:
+        """Initialize the fake mem0 client."""
+        self.search_return = search_return or {"results": []}
+        self.search_calls: list[dict] = []
+        self.add_calls: list[dict] = []
+
+    async def search(self, query: str, **kwargs: Any) -> Any:
+        """Record a mem0 search call and return the configured result."""
+        self.search_calls.append({"query": query, **kwargs})
+        return self.search_return
+
+    async def add(self, messages: list[dict], **kwargs: Any) -> None:
+        """Record a mem0 add call."""
+        self.add_calls.append({"messages": messages, **kwargs})
+
+
+def _single_response(text: str) -> ChatResponse:
+    """Build a final single-text chat response."""
+    return ChatResponse(
+        content=[TextBlock(type="text", text=text)],
+        is_last=True,
+    )
+
+
+def _all_tool_names(toolkit: Toolkit) -> list[str]:
+    """Flatten every registered tool's name across every group."""
+    return [t.name for g in toolkit.tool_groups for t in g.tools]
+
+
+def _find_tool(toolkit: Toolkit, name: str) -> Any:
+    """Look a tool up by name across every group on the toolkit."""
+    for g in toolkit.tool_groups:
+        for t in g.tools:
+            if t.name == name:
+                return t
+    raise LookupError(f"tool {name!r} not found in any group")
+
+
+def _find_group(toolkit: Toolkit, name: str) -> Any:
+    """Look a tool group up by name on the toolkit."""
+    for g in toolkit.tool_groups:
+        if g.name == name:
+            return g
+    raise LookupError(f"tool group {name!r} not found")
+
+
+def _chunk_text(chunk: Any) -> str:
+    """Return the first text block from a tool chunk."""
+    return chunk.content[0].text
+
+
+# ----------------------------------------------------------------------
+# Unit tests for module-level helpers
+# ----------------------------------------------------------------------
+
+
+class TestExtractQueryText(IsolatedAsyncioTestCase):
+    """Tests for extracting the query text from incoming inputs."""
+
+    def test_none_and_empty(self) -> None:
+        """None and empty inputs should not produce a query."""
+        self.assertIsNone(_extract_query_text(None))
+        self.assertIsNone(_extract_query_text([]))
+
+    def test_single_user_msg(self) -> None:
+        """A single user message should become its text content."""
+        msg = UserMsg("user", "hello world")
+        self.assertEqual(_extract_query_text(msg), "hello world")
+
+    def test_list_of_user_msgs_joined(self) -> None:
+        """Multiple user messages should be joined by newlines."""
+        msgs = [UserMsg("user", "first"), UserMsg("user", "second")]
+        self.assertEqual(_extract_query_text(msgs), "first\nsecond")
+
+    def test_resumption_events_return_none(self) -> None:
+        """HITL resumption events should not trigger memory IO."""
+        self.assertIsNone(
+            _extract_query_text(
+                UserConfirmResultEvent(
+                    reply_id="reply",
+                    confirm_results=[],
+                ),
+            ),
+        )
+        self.assertIsNone(
+            _extract_query_text(
+                ExternalExecutionResultEvent(
+                    reply_id="reply",
+                    execution_results=[],
+                ),
+            ),
+        )
+
+
+class TestExtractMemoryTexts(IsolatedAsyncioTestCase):
+    """Tests for normalizing mem0 search responses into text lists."""
+
+    def test_dict_with_results(self) -> None:
+        """Dictionary responses with result dicts should be flattened."""
+        raw = {"results": [{"memory": "a"}, {"memory": "b"}]}
+        self.assertEqual(_extract_memory_texts(raw), ["a", "b"])
+
+    def test_plain_list_of_dicts(self) -> None:
+        """Plain list responses should also be supported."""
+        self.assertEqual(
+            _extract_memory_texts([{"memory": "only"}]),
+            ["only"],
+        )
+
+    def test_plain_list_of_strings(self) -> None:
+        """String results should pass through unchanged."""
+        self.assertEqual(
+            _extract_memory_texts({"results": ["x", "y"]}),
+            ["x", "y"],
+        )
+
+    def test_none_and_garbage(self) -> None:
+        """Malformed mem0 outputs should normalize to an empty list."""
+        self.assertEqual(_extract_memory_texts(None), [])
+        self.assertEqual(_extract_memory_texts({"results": "nope"}), [])
+
+
+# ----------------------------------------------------------------------
+# Constructor validation
+# ----------------------------------------------------------------------
+
+
+class TestConstructorValidation(IsolatedAsyncioTestCase):
+    """Tests for Mem0Middleware constructor validation."""
+
+    def test_missing_user_id_raises(self) -> None:
+        """Empty user IDs should be rejected."""
+        with self.assertRaises(ValueError):
+            Mem0Middleware(client=MagicMock(), user_id="")
+        with self.assertRaises(ValueError):
+            Mem0Middleware(client=MagicMock(), user_id="   ")
+
+    def test_unknown_mode_raises(self) -> None:
+        """Unknown control modes should be rejected."""
+        with self.assertRaises(ValueError):
+            Mem0Middleware(
+                client=MagicMock(),
+                user_id="alice",
+                mode="garbage",  # type: ignore[arg-type]
+            )
+
+    def test_neither_client_nor_models_nor_config_raises(self) -> None:
+        """At least one backend construction path should be provided."""
+        with self.assertRaises(ValueError) as ctx:
+            Mem0Middleware(user_id="alice")
+        self.assertIn("client", str(ctx.exception))
+        self.assertIn("mem0_config", str(ctx.exception))
+        self.assertIn("chat_model", str(ctx.exception))
+
+    def test_client_wins_over_other_backend_kwargs_with_warning(
+        self,
+    ) -> None:
+        """``client`` is the escape hatch — when given, the other
+        backend kwargs are ignored. A warning is logged so the
+        mismatch is not invisible."""
+        fake_client = _FakeAsyncMem0Client()
+        with self.assertLogs(
+            "as",  # the project-wide logger name
+            level="WARNING",
+        ) as captured:
+            mw = Mem0Middleware(
+                user_id="alice",
+                client=fake_client,
+                chat_model=MagicMock(),  # ignored
+                embedding_model=MagicMock(),  # ignored
+                mem0_config=MagicMock(),  # ignored
+            )
+
+        # The fake client wired through unchanged — no AgentScope-
+        # adapter construction machinery ran.
+        self.assertIs(mw._client, fake_client)
+
+        # Warning mentions all three ignored kwargs.
+        joined = "\n".join(captured.output)
+        self.assertIn("chat_model", joined)
+        self.assertIn("embedding_model", joined)
+        self.assertIn("mem0_config", joined)
+
+    def test_client_alone_does_not_warn(self) -> None:
+        """Sanity: pure client-only path stays quiet."""
+        fake_client = _FakeAsyncMem0Client()
+        with self.assertNoLogs("as", level="WARNING"):
+            Mem0Middleware(user_id="alice", client=fake_client)
+
+    def test_only_one_of_chat_or_embedding_without_config_raises(
+        self,
+    ) -> None:
+        """Models-only construction requires both chat and embedding."""
+        with self.assertRaises(ValueError):
+            Mem0Middleware(user_id="alice", chat_model=MagicMock())
+        with self.assertRaises(ValueError):
+            Mem0Middleware(user_id="alice", embedding_model=MagicMock())
+
+
+# ----------------------------------------------------------------------
+# Static-control mode (default)
+# ----------------------------------------------------------------------
+
+
+class TestStaticControlMode(IsolatedAsyncioTestCase):
+    """Default mode: retrieve-before / inject / write-after, no tools."""
+
+    async def asyncSetUp(self) -> None:
+        """Create a fresh recording model and empty toolkit."""
+        self.model = RecordingMockModel(context_size=100_000)
+        self.toolkit = Toolkit()
+
+    def _agent(
+        self,
+        middleware: Mem0Middleware,
+        response_text: str = "ok",
+    ) -> Agent:
+        """Build a test agent using ``middleware`` and one response."""
+        self.model.set_responses([_single_response(response_text)])
+        return Agent(
+            name="agent_under_test",
+            system_prompt="base system prompt",
+            model=self.model,
+            toolkit=self.toolkit,
+            middlewares=[middleware],
+        )
+
+    async def test_retrieve_inject_write(self) -> None:
+        """Static control should search, inject, reply, then write."""
+        fake = _FakeAsyncMem0Client(
+            search_return={"results": [{"memory": "alice loves coffee"}]},
+        )
+        mw = Mem0Middleware(
+            client=fake,
+            user_id="alice",
+            agent_id="agent_under_test",
+            mode="static_control",
+        )
+
+        agent = self._agent(mw, response_text="hi alice")
+        reply = await agent.reply(UserMsg("user", "remind me what I like"))
+
+        # 1. search called with unified call shape (filters dict, top_k)
+        self.assertEqual(len(fake.search_calls), 1)
+        self.assertEqual(
+            fake.search_calls[0]["query"],
+            "remind me what I like",
+        )
+        self.assertEqual(
+            fake.search_calls[0]["filters"],
+            {"user_id": "alice", "agent_id": "agent_under_test"},
+        )
+        self.assertEqual(fake.search_calls[0]["top_k"], 5)
+
+        # 2. write called post-turn with user+assistant pair
+        self.assertEqual(len(fake.add_calls), 1)
+        self.assertEqual(
+            fake.add_calls[0]["messages"],
+            [
+                {"role": "user", "content": "remind me what I like"},
+                {"role": "assistant", "content": "hi alice"},
+            ],
+        )
+        self.assertEqual(fake.add_calls[0]["user_id"], "alice")
+        self.assertEqual(fake.add_calls[0]["agent_id"], "agent_under_test")
+
+        # 3. system prompt is unchanged — static_control mode does NOT
+        #    add tool instructions (those only fire in agent_control /
+        #    both modes via on_system_prompt).
+        sys_msg = self.model.last_call_messages[0]
+        self.assertEqual(sys_msg.role, "system")
+        self.assertEqual(sys_msg.get_text_content(), "base system prompt")
+
+        # 4. memory appended to the agent's persistent context as an
+        #    assistant-role hint note named "memory". Formatters convert
+        #    HintBlock content into a user message before provider calls.
+        memory_msgs = []
+        for msg in agent.state.context:
+            if getattr(msg, "name", None) == "memory":
+                memory_msgs.append(msg)
+        self.assertEqual(len(memory_msgs), 1)
+        self.assertEqual(memory_msgs[0].role, "assistant")
+        memory_hints = memory_msgs[0].get_content_blocks("hint")
+        self.assertEqual(len(memory_hints), 1)
+        self.assertIsInstance(memory_hints[0], HintBlock)
+        memory_text = memory_hints[0].hint
+        self.assertIn("Relevant memories", memory_text)
+        self.assertIn("alice loves coffee", memory_text)
+        # The model saw it on its first call as well.
+        delivered = [
+            m
+            for m in self.model.last_call_messages
+            if getattr(m, "name", None) == "memory"
+        ]
+        self.assertEqual(len(delivered), 1)
+
+        # 5. no agent-control tools registered (in any group)
+        all_names = _all_tool_names(self.toolkit)
+        self.assertNotIn("search_memory", all_names)
+        self.assertNotIn("add_memory", all_names)
+
+        self.assertEqual(reply.get_text_content(), "hi alice")
+
+    async def test_memory_message_lands_after_user_message(self) -> None:
+        """Mirroring AgentScope 1.x's ReActAgent placement: the memory
+        note is inserted right AFTER the new user input lands in the
+        agent context, not before."""
+        fake = _FakeAsyncMem0Client(
+            search_return={"results": [{"memory": "saved fact"}]},
+        )
+        mw = Mem0Middleware(
+            client=fake,
+            user_id="alice",
+            mode="static_control",
+        )
+        agent = self._agent(mw, response_text="answer")
+        await agent.reply(UserMsg("user", "tell me what you know"))
+
+        # context order should be: [...prior history..., USER_MSG,
+        # MEMORY_NOTE, ASSISTANT_REPLY (added by the agent loop)]
+        roles_and_names = [
+            (m.role, getattr(m, "name", None)) for m in agent.state.context
+        ]
+        user_idx = next(
+            i
+            for i, (r, n) in enumerate(roles_and_names)
+            if r == "user" and n != "memory"
+        )
+        memory_idx = next(
+            i for i, (_, n) in enumerate(roles_and_names) if n == "memory"
+        )
+        self.assertGreater(
+            memory_idx,
+            user_idx,
+            f"memory note at {memory_idx} should come after user msg "
+            f"at {user_idx}: {roles_and_names}",
+        )
+
+    async def test_no_memories_no_injection(self) -> None:
+        """Empty search results should not add a memory hint message."""
+        fake = _FakeAsyncMem0Client(search_return={"results": []})
+        mw = Mem0Middleware(
+            client=fake,
+            user_id="alice",
+            mode="static_control",
+        )
+
+        agent = self._agent(mw)
+        await agent.reply(UserMsg("user", "hi"))
+
+        # System prompt unchanged, no synthetic memory msg present.
+        msgs = self.model.last_call_messages
+        self.assertEqual(msgs[0].get_text_content(), "base system prompt")
+        for m in msgs:
+            self.assertNotEqual(getattr(m, "name", None), "memory")
+        self.assertEqual(len(fake.search_calls), 1)
+
+    async def test_search_failure_does_not_break_reply(self) -> None:
+        """Search errors should be logged but not block the reply."""
+        fake = _FakeAsyncMem0Client()
+        fake.search = AsyncMock(side_effect=RuntimeError("mem0 down"))
+        mw = Mem0Middleware(
+            client=fake,
+            user_id="alice",
+            mode="static_control",
+        )
+
+        agent = self._agent(mw, response_text="still works")
+        reply = await agent.reply(UserMsg("user", "ping"))
+
+        self.assertEqual(reply.get_text_content(), "still works")
+        # Write still happened — a failed search must not block writes.
+        self.assertEqual(len(fake.add_calls), 1)
+
+    async def test_scope_search_by_agent_false_drops_agent_id(
+        self,
+    ) -> None:
+        """Unscoped search should omit agent_id from mem0 filters."""
+        fake = _FakeAsyncMem0Client()
+        mw = Mem0Middleware(
+            client=fake,
+            user_id="alice",
+            agent_id="agent_under_test",
+            mode="static_control",
+            scope_search_by_agent=False,
+        )
+        agent = self._agent(mw)
+        await agent.reply(UserMsg("user", "hi"))
+
+        self.assertNotIn("agent_id", fake.search_calls[0]["filters"])
+        # Write still tags both for future scoped queries.
+        self.assertEqual(fake.add_calls[0]["agent_id"], "agent_under_test")
+
+    async def test_sync_client_rejected(self) -> None:
+        """Sync mem0 clients (``Memory`` / ``MemoryClient``) must be
+        rejected at construction time — only async clients are
+        supported."""
+
+        class SyncFake:
+            """Fake sync mem0 client used to verify rejection."""
+
+            def search(self, query: str, **kwargs: Any) -> Any:
+                """Return an empty synchronous search result."""
+                return {"results": []}
+
+            def add(self, messages: list, **kwargs: Any) -> None:
+                """No-op synchronous add method."""
+                return None
+
+        with self.assertRaises(TypeError) as ctx:
+            Mem0Middleware(client=SyncFake(), user_id="alice")
+        self.assertIn("AsyncMemory", str(ctx.exception))
+
+    async def test_async_method_wrapped_by_sync_decorator_accepted(
+        self,
+    ) -> None:
+        """mem0's hosted ``AsyncMemoryClient`` decorates its async
+        methods with ``@api_error_handler`` — a sync wrapper that
+        returns the coroutine produced by calling the underlying
+        ``async def func``. ``inspect.iscoroutinefunction(wrapper)``
+        is False, so the naive check would reject the client; we use
+        ``inspect.unwrap`` to peel through ``@functools.wraps`` and
+        find the real async function. This test simulates that
+        pattern and asserts the wrapped-but-async client is accepted.
+        """
+        from functools import wraps
+
+        def sync_wraps_async(func: Any) -> Any:
+            """Wrap an async function in a sync functools wrapper."""
+
+            @wraps(func)
+            def wrapper(*args: Any, **kwargs: Any) -> Any:
+                """Return the coroutine created by the wrapped function."""
+                return func(*args, **kwargs)
+
+            return wrapper
+
+        class WrappedFake:
+            """Fake client whose async methods are sync-wrapped."""
+
+            @sync_wraps_async
+            async def search(self, query: str, **kwargs: Any) -> Any:
+                """Return an empty async search result."""
+                return {"results": []}
+
+            @sync_wraps_async
+            async def add(self, messages: list, **kwargs: Any) -> None:
+                """No-op async add method."""
+                return None
+
+        # Should NOT raise — the unwrap+iscoroutinefunction check sees
+        # through the sync wrapper.
+        mw = Mem0Middleware(client=WrappedFake(), user_id="alice")
+        self.assertIsInstance(mw._client, WrappedFake)
+
+
+# ----------------------------------------------------------------------
+# Agent-control mode
+# ----------------------------------------------------------------------
+
+
+class TestAgentControlMode(IsolatedAsyncioTestCase):
+    """Tools are listed, but no automatic memory hook behavior."""
+
+    async def asyncSetUp(self) -> None:
+        """Create a fresh recording model and empty toolkit."""
+        self.model = RecordingMockModel(context_size=100_000)
+        self.toolkit = Toolkit()
+
+    async def _agent(
+        self,
+        middleware: Mem0Middleware,
+        *,
+        name: str = "a",
+        system_prompt: str = "p",
+        responses: list[str] | None = None,
+    ) -> Agent:
+        """Build an agent with tools explicitly listed by middleware."""
+        self.model.set_responses(
+            [_single_response(r) for r in (responses or ["ok"])],
+        )
+        self.toolkit = Toolkit(tools=await middleware.list_tools())
+        return Agent(
+            name=name,
+            system_prompt=system_prompt,
+            model=self.model,
+            toolkit=self.toolkit,
+            middlewares=[middleware],
+        )
+
+    async def test_tools_listed_and_hint_in_prompt(self) -> None:
+        """Agent-control mode should expose tools and prompt guidance."""
+        fake = _FakeAsyncMem0Client(
+            search_return={"results": [{"memory": "found"}]},
+        )
+        mw = Mem0Middleware(
+            client=fake,
+            user_id="alice",
+            mode="agent_control",
+        )
+        agent = await self._agent(
+            mw,
+            system_prompt="base prompt",
+        )
+        await agent.reply(UserMsg("user", "hello"))
+
+        # Tools are listed by the middleware and explicitly passed into
+        # the toolkit by the caller.
+        basic = _find_group(self.toolkit, "basic")
+        names = [t.name for t in basic.tools]
+        self.assertIn("search_memory", names)
+        self.assertIn("add_memory", names)
+
+        # No automatic search/add ran.
+        self.assertEqual(fake.search_calls, [])
+        self.assertEqual(fake.add_calls, [])
+
+        # System prompt got a short nudge mentioning the tools — the
+        # per-tool guidance comes via the standard tool schema, not
+        # this nudge.
+        msgs = self.model.last_call_messages
+        prompt_text = msgs[0].get_text_content()
+        self.assertIn("base prompt", prompt_text)
+        self.assertIn("Long-term memory", prompt_text)
+        self.assertIn("search_memory", prompt_text)
+        self.assertIn("add_memory", prompt_text)
+        # No synthetic memory message was injected in agent_control mode.
+        for m in msgs:
+            self.assertNotEqual(getattr(m, "name", None), "memory")
+
+    async def test_middleware_does_not_mutate_toolkit(self) -> None:
+        """Middleware should not register tools unless caller does so."""
+        fake = _FakeAsyncMem0Client()
+        mw = Mem0Middleware(
+            client=fake,
+            user_id="alice",
+            mode="agent_control",
+        )
+        self.model.set_responses([_single_response("ok")])
+        toolkit = Toolkit()
+        agent = Agent(
+            name="a",
+            system_prompt="base prompt",
+            model=self.model,
+            toolkit=toolkit,
+            middlewares=[mw],
+        )
+        await agent.reply(UserMsg("user", "hello"))
+
+        self.assertNotIn("search_memory", _all_tool_names(toolkit))
+        self.assertNotIn("add_memory", _all_tool_names(toolkit))
+
+    async def test_search_memory_tool_invokes_mem0(self) -> None:
+        """The search_memory tool should query mem0 per keyword."""
+        fake = _FakeAsyncMem0Client(
+            search_return={
+                "results": [
+                    {"memory": "first fact"},
+                    {"memory": "second fact"},
+                ],
+            },
+        )
+        mw = Mem0Middleware(
+            client=fake,
+            user_id="alice",
+            agent_id="a",
+            mode="agent_control",
+        )
+        agent = await self._agent(
+            mw,
+            system_prompt="base prompt",
+        )
+        # Trigger middleware tool registration by issuing a reply.
+        await agent.reply(UserMsg("user", "hi"))
+
+        search_tool = _find_tool(self.toolkit, "search_memory")
+
+        # Exercise the tool directly. The signature mirrors
+        # AgentScope 1.x: a LIST of keywords, each issued as an
+        # independent parallel search.
+        result = await search_tool(
+            keywords=["what does alice like?", "alice preferences"],
+            limit=3,
+        )
+        result_text = _chunk_text(result)
+        self.assertIn("first fact", result_text)
+        self.assertIn("second fact", result_text)
+
+        # Each keyword produces one mem0 call; both share user/agent
+        # filter and per-keyword limit.
+        self.assertEqual(len(fake.search_calls), 2)
+        for call in fake.search_calls:
+            self.assertEqual(
+                call["filters"],
+                {"user_id": "alice", "agent_id": "a"},
+            )
+            self.assertEqual(call["top_k"], 3)
+
+    async def test_async_search_accepts_per_call_top_k(self) -> None:
+        """Per-call search limits should not mutate middleware state."""
+        fake = _FakeAsyncMem0Client()
+        mw = Mem0Middleware(
+            client=fake,
+            user_id="alice",
+            mode="agent_control",
+            top_k=9,
+        )
+
+        await mw._async_search(
+            "q",
+            user_id="alice",
+            agent_id="a",
+            top_k=3,
+        )
+
+        self.assertEqual(fake.search_calls[0]["top_k"], 3)
+        self.assertEqual(mw._top_k, 9)
+
+    async def test_tools_auto_allow_permission(self) -> None:
+        """Memory tools should be auto-allowed by permission checks."""
+        mw = Mem0Middleware(
+            client=_FakeAsyncMem0Client(),
+            user_id="alice",
+            mode="agent_control",
+        )
+        agent = await self._agent(mw)
+        await agent.reply(UserMsg("user", "hi"))
+
+        from agentscope.permission import PermissionBehavior
+
+        search_tool = _find_tool(self.toolkit, "search_memory")
+        add_tool = _find_tool(self.toolkit, "add_memory")
+        decision_search = await search_tool.check_permissions({}, None)
+        decision_add = await add_tool.check_permissions({}, None)
+        self.assertEqual(decision_search.behavior, PermissionBehavior.ALLOW)
+        self.assertEqual(decision_add.behavior, PermissionBehavior.ALLOW)
+
+    async def test_search_memory_dedupes_across_keywords(self) -> None:
+        """When two keywords return overlapping memories, the tool
+        merges and dedupes."""
+        fake = _FakeAsyncMem0Client(
+            search_return={
+                "results": [{"memory": "shared"}, {"memory": "unique"}],
+            },
+        )
+        mw = Mem0Middleware(client=fake, user_id="alice", mode="agent_control")
+        agent = await self._agent(mw)
+        await agent.reply(UserMsg("user", "hi"))
+        search_tool = _find_tool(self.toolkit, "search_memory")
+
+        result = await search_tool(
+            keywords=["kw1", "kw2"],
+            limit=5,
+        )
+        result_text = _chunk_text(result)
+        # "shared" appears once even though both keywords returned it.
+        self.assertEqual(result_text.count("shared"), 1)
+        self.assertEqual(result_text.count("unique"), 1)
+
+    async def test_search_memory_failure_returns_error_chunk(self) -> None:
+        """mem0 raising during search produces a ToolChunk with
+        state=ERROR so the toolkit marks the call as failed."""
+        from agentscope.message import ToolResultState
+        from agentscope.tool import ToolChunk
+
+        fake = _FakeAsyncMem0Client()
+        fake.search = AsyncMock(side_effect=RuntimeError("mem0 down"))
+        mw = Mem0Middleware(client=fake, user_id="alice", mode="agent_control")
+        agent = await self._agent(mw)
+        await agent.reply(UserMsg("user", "hi"))
+        search_tool = _find_tool(self.toolkit, "search_memory")
+
+        result = await search_tool(
+            keywords=["q"],
+            limit=5,
+        )
+        self.assertIsInstance(result, ToolChunk)
+        self.assertEqual(result.state, ToolResultState.ERROR)
+        self.assertIn("mem0 down", result.content[0].text)
+
+    async def test_add_memory_two_tier_fallback(self) -> None:
+        """When mem0's extraction LLM returns no memories, the tool
+        falls back to ``infer=False`` and saves raw text so the
+        caller's ``add_memory`` invocation isn't silently dropped.
+
+        Two tiers, not three — v1's tier-2 role switch (user →
+        assistant) was a no-op against current mem0 (v2.x), which
+        picks the extraction prompt based on the filter dict, not the
+        message role. See the docstring of
+        ``Mem0Middleware._async_add_with_fallback`` for the full
+        rationale."""
+
+        class CountingFake:
+            """Fake mem0 client that triggers add fallback once."""
+
+            def __init__(self) -> None:
+                """Initialize call tracking and empty search behavior."""
+                self.add_calls: list[dict] = []
+                self.search = AsyncMock(return_value={"results": []})
+
+            async def add(
+                self,
+                messages: list[dict],
+                **kwargs: Any,
+            ) -> dict:
+                """Return empty extraction first, then a saved memory."""
+                self.add_calls.append({"messages": messages, **kwargs})
+                # First attempt: extracted nothing → triggers fallback.
+                # Second attempt (with infer=False): succeeds.
+                if len(self.add_calls) < 2:
+                    return {"results": []}
+                return {"results": [{"id": "m1", "memory": "saved"}]}
+
+        fake = CountingFake()
+        mw = Mem0Middleware(client=fake, user_id="alice", mode="agent_control")
+        agent = await self._agent(mw)
+        await agent.reply(UserMsg("user", "hi"))
+        add_tool = _find_tool(self.toolkit, "add_memory")
+
+        result = await add_tool(
+            thinking="my reasoning",
+            content=["fact one"],
+        )
+        self.assertIn("Successfully recorded", _chunk_text(result))
+
+        # Exactly 2 calls — the role-switch tier from v1 is gone.
+        self.assertEqual(len(fake.add_calls), 2)
+        # Both calls use the user role (no more switching).
+        self.assertEqual(fake.add_calls[0]["messages"][0]["role"], "user")
+        self.assertEqual(fake.add_calls[1]["messages"][0]["role"], "user")
+        # First call uses default inference; second explicitly disables it.
+        self.assertNotIn("infer", fake.add_calls[0])
+        self.assertFalse(fake.add_calls[1]["infer"])
+
+    async def test_add_memory_does_not_persist_thinking(self) -> None:
+        """``thinking`` is the agent's rationale — it appears in the
+        tool's return text (auditable in the transcript) but is NOT
+        sent to mem0, so the stored memory stays clean of agent
+        self-narration."""
+        fake = _FakeAsyncMem0Client()
+        # First attempt extracts something → no fallback.
+        fake.add = AsyncMock(
+            return_value={"results": [{"id": "m1", "memory": "saved"}]},
+        )
+        mw = Mem0Middleware(client=fake, user_id="alice", mode="agent_control")
+        agent = await self._agent(mw)
+        await agent.reply(UserMsg("user", "hi"))
+        add_tool = _find_tool(self.toolkit, "add_memory")
+
+        thinking = "user said X because Y"
+        fact = "likes coffee"
+        result = await add_tool(
+            thinking=thinking,
+            content=[fact],
+        )
+        result_text = _chunk_text(result)
+
+        # mem0 only saw the fact, NOT the rationale.
+        sent = fake.add.call_args.args[0][0]["content"]
+        self.assertIn(fact, sent)
+        self.assertNotIn(thinking, sent)
+
+        # ...but the tool return text DOES echo the rationale, so the
+        # decision is auditable in the agent transcript.
+        self.assertIn(thinking, result_text)
+
+
+# ----------------------------------------------------------------------
+# Both mode — hooks + tools together
+# ----------------------------------------------------------------------
+
+
+class TestBothMode(IsolatedAsyncioTestCase):
+    """Tests for combined static-control and agent-control behavior."""
+
+    async def test_memory_msg_and_tool_hint_both_present(self) -> None:
+        """Both mode should inject memory and expose memory tools."""
+        model = RecordingMockModel(context_size=100_000)
+        fake = _FakeAsyncMem0Client(
+            search_return={"results": [{"memory": "auto-injected"}]},
+        )
+        mw = Mem0Middleware(client=fake, user_id="alice", mode="both")
+        toolkit = Toolkit(tools=await mw.list_tools())
+        model.set_responses([_single_response("ok")])
+        agent = Agent(
+            name="a",
+            system_prompt="base",
+            model=model,
+            toolkit=toolkit,
+            middlewares=[mw],
+        )
+        await agent.reply(UserMsg("user", "hi"))
+
+        # Static hooks ran.
+        self.assertEqual(len(fake.search_calls), 1)
+        self.assertEqual(len(fake.add_calls), 1)
+
+        msgs = model.last_call_messages
+
+        # System prompt has the tool nudge (from on_system_prompt).
+        prompt_text = msgs[0].get_text_content()
+        self.assertIn("Long-term memory", prompt_text)
+        self.assertIn("search_memory", prompt_text)
+
+        # Memory injected as a synthetic HintBlock Msg.
+        memory_msgs = [m for m in msgs if getattr(m, "name", None) == "memory"]
+        self.assertEqual(len(memory_msgs), 1)
+        memory_hints = memory_msgs[0].get_content_blocks("hint")
+        self.assertEqual(len(memory_hints), 1)
+        self.assertIn("auto-injected", memory_hints[0].hint)
+
+        # Tools exposed.
+        names = _all_tool_names(toolkit)
+        self.assertIn("search_memory", names)
+        self.assertIn("add_memory", names)
diff --git a/tests/message_test.py b/tests/message_test.py
new file mode 100644
index 0000000..4ec2ee1
--- /dev/null
+++ b/tests/message_test.py
@@ -0,0 +1,271 @@
+# -*- coding: utf-8 -*-
+"""A template test case."""
+from unittest.async_case import IsolatedAsyncioTestCase
+from utils import AnyString
+
+from agentscope.message import (
+    UserMsg,
+    TextBlock,
+    DataBlock,
+    URLSource,
+    Base64Source,
+    ThinkingBlock,
+    AssistantMsg,
+    HintBlock,
+    Msg,
+    ToolCallBlock,
+    ToolResultBlock,
+    ToolResultState,
+)
+
+
+class MessageTest(IsolatedAsyncioTestCase):
+    """The template test case."""
+
+    async def test_creating_message(self) -> None:
+        """The template test."""
+        # Test string content
+        user_msg = UserMsg(name="user", content="hello world")
+        self.assertDictEqual(
+            user_msg.model_dump(),
+            {
+                "id": AnyString(),
+                "name": "user",
+                "role": "user",
+                "content": [
+                    {
+                        "id": AnyString(),
+                        "text": "hello world",
+                        "type": "text",
+                    },
+                ],
+                "metadata": {},
+                "created_at": AnyString(),
+                "finished_at": AnyString(),
+                "usage": None,
+            },
+        )
+
+        # Test list of content
+        user_msg = UserMsg(
+            name="user",
+            content=[TextBlock(text="1"), TextBlock(text="2")],
+        )
+        self.assertDictEqual(
+            user_msg.model_dump(),
+            {
+                "id": AnyString(),
+                "name": "user",
+                "role": "user",
+                "content": [
+                    {"type": "text", "text": "1", "id": AnyString()},
+                    {"type": "text", "text": "2", "id": AnyString()},
+                ],
+                "metadata": {},
+                "created_at": AnyString(),
+                "finished_at": AnyString(),
+                "usage": None,
+            },
+        )
+
+        # Test DataBlock content
+        user_msg = UserMsg(
+            name="user",
+            content=[
+                TextBlock(text="1"),
+                DataBlock(
+                    source=URLSource(
+                        url="https://example.com/image.png",
+                        media_type="image/png",
+                    ),
+                ),
+                DataBlock(
+                    source=Base64Source(
+                        data="iVBORw0KGgoAAAANSUhEUgAAAAUA",
+                        media_type="image/png",
+                    ),
+                ),
+            ],
+        )
+
+        self.assertDictEqual(
+            user_msg.model_dump(),
+            {
+                "id": AnyString(),
+                "name": "user",
+                "role": "user",
+                "content": [
+                    {"type": "text", "text": "1", "id": AnyString()},
+                    {
+                        "type": "data",
+                        "id": AnyString(),
+                        "source": {
+                            "type": "url",
+                            "url": "https://example.com/image.png",
+                            "media_type": "image/png",
+                        },
+                        "name": None,
+                    },
+                    {
+                        "type": "data",
+                        "id": AnyString(),
+                        "source": {
+                            "type": "base64",
+                            "data": "iVBORw0KGgoAAAANSUhEUgAAAAUA",
+                            "media_type": "image/png",
+                        },
+                        "name": None,
+                    },
+                ],
+                "metadata": {},
+                "created_at": AnyString(),
+                "finished_at": AnyString(),
+                "usage": None,
+            },
+        )
+
+        # Test thinking content
+        msg = AssistantMsg(
+            name="assistant",
+            content=[ThinkingBlock(thinking="thinking...")],
+        )
+        self.assertDictEqual(
+            msg.model_dump(),
+            {
+                "id": AnyString(),
+                "name": "assistant",
+                "role": "assistant",
+                "content": [
+                    {
+                        "type": "thinking",
+                        "thinking": "thinking...",
+                        "id": AnyString(),
+                    },
+                ],
+                "metadata": {},
+                "created_at": AnyString(),
+                "finished_at": None,
+                "usage": None,
+            },
+        )
+
+        # Test hint content
+        msg = AssistantMsg(
+            name="assistant",
+            content=[HintBlock(hint="hint...")],
+        )
+        self.assertDictEqual(
+            msg.model_dump(),
+            {
+                "id": AnyString(),
+                "name": "assistant",
+                "role": "assistant",
+                "content": [
+                    {
+                        "type": "hint",
+                        "hint": "hint...",
+                        "id": AnyString(),
+                        "source": None,
+                    },
+                ],
+                "metadata": {},
+                "created_at": AnyString(),
+                "finished_at": None,
+                "usage": None,
+            },
+        )
+
+    async def test_invalid_message(self) -> None:
+        """Test invalid message creation."""
+        # User message with thinking block should raise ValueError
+        with self.assertRaises(ValueError):
+            Msg(
+                name="user",
+                role="user",
+                content=[ThinkingBlock(thinking="thinking...")],
+            )
+
+        # User message with hint block should raise ValueError
+        with self.assertRaises(ValueError):
+            Msg(
+                name="user",
+                role="user",
+                content=[HintBlock(hint="hint...")],
+            )
+
+        # User message with tool call block should raise ValueError
+        with self.assertRaises(ValueError):
+            Msg(
+                name="user",
+                role="user",
+                content=[ToolCallBlock(id="1", name="tool", input="{}")],
+            )
+
+        # User message with tool result block should raise ValueError
+        with self.assertRaises(ValueError):
+            Msg(
+                name="user",
+                role="user",
+                content=[
+                    ToolResultBlock(
+                        id="1",
+                        name="tool",
+                        output="result",
+                        state=ToolResultState.SUCCESS,
+                    ),
+                ],
+            )
+
+        # System message with data block should raise ValueError
+        with self.assertRaises(ValueError):
+            Msg(
+                name="system",
+                role="system",
+                content=[
+                    DataBlock(
+                        source=URLSource(
+                            url="https://example.com/image.png",
+                            media_type="image/png",
+                        ),
+                    ),
+                ],
+            )
+
+        # System message with thinking block should raise ValueError
+        with self.assertRaises(ValueError):
+            Msg(
+                name="system",
+                role="system",
+                content=[ThinkingBlock(thinking="thinking...")],
+            )
+
+        # System message with hint block should raise ValueError
+        with self.assertRaises(ValueError):
+            Msg(
+                name="system",
+                role="system",
+                content=[HintBlock(hint="hint...")],
+            )
+
+        # System message with tool call block should raise ValueError
+        with self.assertRaises(ValueError):
+            Msg(
+                name="system",
+                role="system",
+                content=[ToolCallBlock(id="1", name="tool", input="{}")],
+            )
+
+        # System message with tool result block should raise ValueError
+        with self.assertRaises(ValueError):
+            Msg(
+                name="system",
+                role="system",
+                content=[
+                    ToolResultBlock(
+                        id="1",
+                        name="tool",
+                        output="result",
+                        state=ToolResultState.SUCCESS,
+                    ),
+                ],
+            )
diff --git a/tests/middleware_background_acting_test.py b/tests/middleware_background_acting_test.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/middleware_budget_test.py b/tests/middleware_budget_test.py
new file mode 100644
index 0000000..c6a8c54
--- /dev/null
+++ b/tests/middleware_budget_test.py
@@ -0,0 +1,476 @@
+# -*- coding: utf-8 -*-
+"""Unit tests for BudgetControlMiddleware."""
+from typing import Any
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from utils import MockModel
+from agentscope.agent import Agent
+from agentscope.message import UserMsg, TextBlock, ToolCallBlock, HintBlock
+from agentscope.middleware import ReplyBudgetControlMiddleware
+from agentscope.model import ChatResponse, ChatUsage
+from agentscope.permission import (
+    PermissionBehavior,
+    PermissionContext,
+    PermissionDecision,
+)
+from agentscope.event import UserConfirmResultEvent, ConfirmResult
+from agentscope.tool import ToolBase, Toolkit, ToolChunk
+
+
+def _response(
+    text: str,
+    input_tokens: int,
+    output_tokens: int,
+) -> ChatResponse:
+    """Build a non-streaming ChatResponse with usage."""
+    return ChatResponse(
+        content=[TextBlock(text=text)],
+        is_last=True,
+        usage=ChatUsage(
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            time=0.0,
+        ),
+    )
+
+
+class DummyTool(ToolBase):
+    """Minimal tool that always allows and returns a fixed result."""
+
+    name: str = "dummy"
+    description: str = "A dummy tool for testing"
+    input_schema: dict[str, Any] = {"type": "object", "properties": {}}
+    is_concurrency_safe: bool = True
+    is_read_only: bool = True
+    is_external_tool: bool = False
+    is_mcp: bool = False
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        """Always allow."""
+        return PermissionDecision(
+            behavior=PermissionBehavior.ALLOW,
+            decision_reason="Dummy tool always allows",
+            message="Dummy tool always allows",
+        )
+
+    async def __call__(self, **kwargs: Any) -> ToolChunk:
+        """Return a fixed result."""
+        return ToolChunk(content=[TextBlock(text="ok")])
+
+
+class ConfirmRequiredTool(ToolBase):
+    """Minimal tool that always requires user confirmation before running."""
+
+    name: str = "confirm_required"
+    description: str = "A tool that requires user confirmation"
+    input_schema: dict[str, Any] = {"type": "object", "properties": {}}
+    is_concurrency_safe: bool = False
+    is_read_only: bool = False
+    is_external_tool: bool = False
+    is_mcp: bool = False
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        """Always require user confirmation."""
+        return PermissionDecision(
+            behavior=PermissionBehavior.ASK,
+            decision_reason="Confirmation required",
+            message="Confirmation required",
+        )
+
+    async def __call__(self, **kwargs: Any) -> ToolChunk:
+        """Return a fixed result."""
+        return ToolChunk(content=[TextBlock(text="confirmed result")])
+
+
+def _has_hint_block(msg: Any, hint_message: str) -> bool:
+    """Return True if *msg* contains a HintBlock with *hint_message*."""
+    content = getattr(msg, "content", None)
+    if not isinstance(content, list):
+        return False
+    return any(
+        isinstance(b, HintBlock) and hint_message in b.hint for b in content
+    )
+
+
+class TestBudgetControlMiddleware(IsolatedAsyncioTestCase):
+    """Test cases for BudgetControlMiddleware."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up shared fixtures."""
+        self.toolkit = Toolkit()
+
+    async def test_under_budget_no_hint_injected(self) -> None:
+        """When token usage stays below the budget, no hint is injected."""
+        model = MockModel()
+        model.set_responses(
+            [_response("done", input_tokens=10, output_tokens=5)],
+        )
+
+        middleware = ReplyBudgetControlMiddleware(token_budget=1000)
+        agent = Agent(
+            name="test_agent",
+            system_prompt="you are helpful",
+            model=model,
+            toolkit=self.toolkit,
+            middlewares=[middleware],
+        )
+
+        context_before = len(agent.state.context)
+        await agent.reply(UserMsg("user", "hello"))
+
+        # No HintBlock should have been added to context
+        hint_msgs = [
+            m
+            for m in agent.state.context[context_before:]
+            if _has_hint_block(m, middleware.hint_message)
+        ]
+        self.assertEqual(len(hint_msgs), 0)
+
+    async def test_budget_exceeded_injects_hint(self) -> None:
+        """When the budget is exceeded, the hint block is injected.
+
+        Uses token_budget=0 so the budget condition fires on the very first
+        reasoning call (0 used >= 0 max).
+        """
+        model = MockModel()
+        model.set_responses(
+            [_response("wrap up", input_tokens=10, output_tokens=5)],
+        )
+
+        middleware = ReplyBudgetControlMiddleware(token_budget=0)
+        agent = Agent(
+            name="test_agent",
+            system_prompt="you are helpful",
+            model=model,
+            toolkit=self.toolkit,
+            middlewares=[middleware],
+        )
+
+        context_before = len(agent.state.context)
+        await agent.reply(UserMsg("user", "hello"))
+
+        hint_msgs = [
+            m
+            for m in agent.state.context[context_before:]
+            if _has_hint_block(m, middleware.hint_message)
+        ]
+        self.assertGreater(len(hint_msgs), 0)
+
+    async def test_budget_exceeded_forces_tool_choice_none(self) -> None:
+        """When budget is exceeded, tool_choice forwarded to model is none.
+
+        Uses token_budget=0 so the override fires on the first reasoning call.
+        """
+        received_tool_choices: list = []
+
+        class TrackingModel(MockModel):
+            """Model that records tool_choice on every call."""
+
+            async def _call_api(
+                self,
+                *args: Any,
+                **kwargs: Any,
+            ) -> ChatResponse:
+                """Record tool_choice and delegate to mock."""
+                received_tool_choices.append(kwargs.get("tool_choice"))
+                return await super()._call_api(*args, **kwargs)
+
+        model = TrackingModel()
+        model.set_responses(
+            [_response("wrap up", input_tokens=10, output_tokens=5)],
+        )
+
+        middleware = ReplyBudgetControlMiddleware(token_budget=0)
+        agent = Agent(
+            name="test_agent",
+            system_prompt="you are helpful",
+            model=model,
+            toolkit=self.toolkit,
+            middlewares=[middleware],
+        )
+
+        await agent.reply(UserMsg("user", "hello"))
+
+        # At least one call must have received tool_choice with mode="none"
+        self.assertTrue(
+            any(
+                getattr(tc, "mode", None) == "none"
+                for tc in received_tool_choices
+                if tc is not None
+            ),
+        )
+
+    async def test_token_accumulation_across_steps(self) -> None:
+        """Tokens accumulate across steps and trigger enforcement correctly.
+
+        Step 1: tool call costs 200+100=300 tokens (token_budget=300 so
+        step 2 sees used >= max and injects the hint).
+        """
+        toolkit = Toolkit(tools=[DummyTool()])
+
+        model = MockModel()
+        model.set_responses(
+            [
+                [
+                    ChatResponse(
+                        content=[
+                            ToolCallBlock(
+                                id="tc_1",
+                                name="dummy",
+                                input="{}",
+                            ),
+                        ],
+                        is_last=True,
+                        usage=ChatUsage(
+                            input_tokens=200,
+                            output_tokens=100,
+                            time=0.0,
+                        ),
+                    ),
+                ],
+                [
+                    ChatResponse(
+                        content=[TextBlock(text="done")],
+                        is_last=True,
+                        usage=ChatUsage(
+                            input_tokens=150,
+                            output_tokens=50,
+                            time=0.0,
+                        ),
+                    ),
+                ],
+            ],
+        )
+
+        middleware = ReplyBudgetControlMiddleware(token_budget=300)
+        agent = Agent(
+            name="test_agent",
+            system_prompt="you are helpful",
+            model=model,
+            toolkit=toolkit,
+            middlewares=[middleware],
+        )
+
+        context_before = len(agent.state.context)
+        await agent.reply(UserMsg("user", "hello"))
+
+        hint_msgs = [
+            m
+            for m in agent.state.context[context_before:]
+            if _has_hint_block(m, middleware.hint_message)
+        ]
+        self.assertGreater(len(hint_msgs), 0)
+
+    async def test_weighted_token_calculation(self) -> None:
+        """output_token_weight scales output tokens in the budget calculation.
+
+        With input_token_weight=1, output_token_weight=3, token_budget=200:
+        - Step 1: 50 input * 1 + 50 output * 3 = 200 → budget hit exactly
+        - Step 2: hint should be injected before the model call
+        """
+        toolkit = Toolkit(tools=[DummyTool()])
+
+        model = MockModel()
+        model.set_responses(
+            [
+                [
+                    ChatResponse(
+                        content=[
+                            ToolCallBlock(
+                                id="tc_1",
+                                name="dummy",
+                                input="{}",
+                            ),
+                        ],
+                        is_last=True,
+                        usage=ChatUsage(
+                            input_tokens=50,
+                            output_tokens=50,
+                            time=0.0,
+                        ),
+                    ),
+                ],
+                [
+                    ChatResponse(
+                        content=[TextBlock(text="done")],
+                        is_last=True,
+                        usage=ChatUsage(
+                            input_tokens=30,
+                            output_tokens=10,
+                            time=0.0,
+                        ),
+                    ),
+                ],
+            ],
+        )
+
+        # 50*1 + 50*3 = 200 == token_budget → step 2 triggers enforcement
+        middleware = ReplyBudgetControlMiddleware(
+            token_budget=200,
+            input_token_weight=1,
+            output_token_weight=3,
+        )
+        agent = Agent(
+            name="test_agent",
+            system_prompt="you are helpful",
+            model=model,
+            toolkit=toolkit,
+            middlewares=[middleware],
+        )
+
+        context_before = len(agent.state.context)
+        await agent.reply(UserMsg("user", "hello"))
+
+        hint_msgs = [
+            m
+            for m in agent.state.context[context_before:]
+            if _has_hint_block(m, middleware.hint_message)
+        ]
+        self.assertGreater(len(hint_msgs), 0)
+
+    async def test_state_cleanup_after_reply(self) -> None:
+        """middle_context entry for the reply is removed after reply ends."""
+        model = MockModel()
+        model.set_responses(
+            [_response("done", input_tokens=10, output_tokens=5)],
+        )
+
+        middleware = ReplyBudgetControlMiddleware(token_budget=1000)
+        agent = Agent(
+            name="test_agent",
+            system_prompt="you are helpful",
+            model=model,
+            toolkit=self.toolkit,
+            middlewares=[middleware],
+        )
+
+        await agent.reply(UserMsg("user", "hello"))
+
+        middleware_key = await middleware.get_middleware_key()
+        bucket = agent.state.middle_context.get(middleware_key, {})
+        # All per-reply entries must have been cleaned up
+        self.assertEqual(len(bucket), 0)
+
+    async def test_token_accumulation_persists_across_hitl(self) -> None:
+        """Token accumulation in middle_context persists across HITL boundary.
+
+        Scenario:
+        - token_budget=300, both weights default to 1.
+        - First reply_stream call: model call costs 200 input + 100 output
+          = 300 tokens, then pauses at REQUIRE_USER_CONFIRM (no ReplyEndEvent
+          is emitted). The 300-token count is stored in middle_context.
+        - Second reply_stream call with UserConfirmResultEvent: the same
+          reply_id resumes. on_reasoning reads 300 >= 300 from middle_context
+          and injects the hint + forces tool_choice=none before the final
+          model call, proving budget state survived the HITL round-trip.
+        """
+        tool_call_id = "tc_hitl"
+        tool_input = "{}"
+        toolkit = Toolkit(tools=[ConfirmRequiredTool()])
+
+        model = MockModel()
+        model.set_responses(
+            [
+                # Step 1: model produces a tool call that requires confirmation
+                [
+                    ChatResponse(
+                        content=[
+                            ToolCallBlock(
+                                id=tool_call_id,
+                                name="confirm_required",
+                                input=tool_input,
+                            ),
+                        ],
+                        is_last=True,
+                        usage=ChatUsage(
+                            input_tokens=200,
+                            output_tokens=100,
+                            time=0.0,
+                        ),
+                    ),
+                ],
+                # Step 2 (after confirmation): final wrap-up text
+                [
+                    ChatResponse(
+                        content=[TextBlock(text="wrap up")],
+                        is_last=True,
+                        usage=ChatUsage(
+                            input_tokens=50,
+                            output_tokens=20,
+                            time=0.0,
+                        ),
+                    ),
+                ],
+            ],
+        )
+
+        # 200*1 + 100*1 = 300 == token_budget → reasoning after resume
+        # injects hint
+        middleware = ReplyBudgetControlMiddleware(token_budget=300)
+        agent = Agent(
+            name="test_agent",
+            system_prompt="you are helpful",
+            model=model,
+            toolkit=toolkit,
+            middlewares=[middleware],
+        )
+
+        # --- First call: pauses at REQUIRE_USER_CONFIRM ---
+        events = []
+        async for event in agent.reply_stream(UserMsg("user", "hello")):
+            events.append(event)
+
+        event_types = [e.type for e in events]
+        self.assertIn("REQUIRE_USER_CONFIRM", event_types)
+        self.assertNotIn("REPLY_END", event_types)
+
+        reply_id = agent.state.reply_id
+
+        # Token count must be stored in middle_context (survived the pause)
+        middleware_key = await middleware.get_middleware_key()
+        stored = agent.state.middle_context.get(middleware_key, {})
+        self.assertAlmostEqual(stored.get(reply_id, 0), 300.0)
+
+        # --- Second call: resume with user confirmation ---
+        user_confirm_event = UserConfirmResultEvent(
+            reply_id=reply_id,
+            confirm_results=[
+                ConfirmResult(
+                    confirmed=True,
+                    tool_call=ToolCallBlock(
+                        id=tool_call_id,
+                        name="confirm_required",
+                        input=tool_input,
+                    ),
+                ),
+            ],
+        )
+
+        resume_events = []
+        async for event in agent.reply_stream(inputs=user_confirm_event):
+            resume_events.append(event)
+
+        resume_event_types = [e.type for e in resume_events]
+        self.assertIn("REPLY_END", resume_event_types)
+
+        # Hint is appended to the existing assistant message (which was created
+        # in the first call), so we search the full context rather than a
+        # slice.
+        hint_msgs = [
+            m
+            for m in agent.state.context
+            if _has_hint_block(m, middleware.hint_message)
+        ]
+        self.assertGreater(len(hint_msgs), 0)
+
+        # middle_context must be cleaned up after reply ends
+        bucket = agent.state.middle_context.get(middleware_key, {})
+        self.assertNotIn(reply_id, bucket)
diff --git a/tests/middleware_filesystem_memory_test.py b/tests/middleware_filesystem_memory_test.py
new file mode 100644
index 0000000..826638c
--- /dev/null
+++ b/tests/middleware_filesystem_memory_test.py
@@ -0,0 +1,772 @@
+# -*- coding: utf-8 -*-
+"""Unit tests for AgenticMemoryMiddleware with real Agent execution."""
+import os
+import shutil
+import tempfile
+from typing import Any, Type
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from pydantic import BaseModel
+from utils import AnyString, AnyValue, MockModel
+
+from agentscope.agent import Agent
+from agentscope.message import (
+    HintBlock,
+    Msg,
+    TextBlock,
+    ToolCallBlock,
+    UserMsg,
+)
+from agentscope.middleware import AgenticMemoryMiddleware
+from agentscope.model import ChatResponse, StructuredResponse
+from agentscope.permission import (
+    PermissionBehavior,
+    PermissionContext,
+    PermissionDecision,
+)
+from agentscope.tool import ToolBase, ToolChunk, Toolkit
+
+
+class _RecordingMockModel(MockModel):
+    """A ``MockModel`` that records chat and structured-output calls."""
+
+    def __init__(self, **kwargs: Any) -> None:
+        """Initialize the recording mock model.
+
+        Args:
+            **kwargs (`Any`):
+                Keyword arguments forwarded to :class:`MockModel`.
+        """
+        kwargs.setdefault("context_size", 100_000)
+        super().__init__(**kwargs)
+        self.chat_messages: list[list[Msg]] = []
+        self.structured_messages: list[list[Msg]] = []
+
+    async def _call_api(
+        self,
+        *args: Any,
+        **kwargs: Any,
+    ) -> ChatResponse:
+        """Record the chat messages and delegate to ``MockModel``.
+
+        Args:
+            *args (`Any`):
+                Positional arguments forwarded to ``MockModel``.
+            **kwargs (`Any`):
+                Keyword arguments forwarded to ``MockModel``.
+
+        Returns:
+            `ChatResponse`:
+                The configured mock chat response.
+        """
+        self.chat_messages.append(kwargs["messages"])
+        return await super()._call_api(*args, **kwargs)
+
+    async def _call_api_with_structured_output(
+        self,
+        model_name: str,
+        messages: list[Msg],
+        structured_model: Type[BaseModel] | dict,
+        **kwargs: Any,
+    ) -> StructuredResponse:
+        """Record structured-output messages and delegate to ``MockModel``.
+
+        Args:
+            model_name (`str`):
+                The model name.
+            messages (`list[Msg]`):
+                The structured-output prompt messages.
+            structured_model (`Type[BaseModel] | dict`):
+                The expected structured-output schema.
+            **kwargs (`Any`):
+                Extra keyword arguments forwarded to ``MockModel``.
+
+        Returns:
+            `StructuredResponse`:
+                The configured mock structured response.
+        """
+        self.structured_messages.append(messages)
+        return await super()._call_api_with_structured_output(
+            model_name,
+            messages,
+            structured_model,
+            **kwargs,
+        )
+
+
+class _DummyTool(ToolBase):
+    """A minimal tool that forces a second Agent reasoning iteration."""
+
+    name: str = "dummy"
+    description: str = "A dummy tool for middleware tests."
+    input_schema: dict[str, Any] = {"type": "object", "properties": {}}
+    is_concurrency_safe: bool = True
+    is_read_only: bool = True
+    is_external_tool: bool = False
+    is_mcp: bool = False
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        """Allow every dummy tool call.
+
+        Args:
+            tool_input (`dict[str, Any]`):
+                The tool input.
+            context (`PermissionContext`):
+                The permission context.
+
+        Returns:
+            `PermissionDecision`:
+                The allow decision.
+        """
+        return PermissionDecision(
+            behavior=PermissionBehavior.ALLOW,
+            decision_reason="Dummy tool always allows.",
+            message="Dummy tool always allows.",
+        )
+
+    async def __call__(self, **kwargs: Any) -> ToolChunk:
+        """Return a fixed tool result.
+
+        Args:
+            **kwargs (`Any`):
+                Ignored tool arguments.
+
+        Returns:
+            `ToolChunk`:
+                The fixed tool output.
+        """
+        return ToolChunk(content=[TextBlock(text="tool result")])
+
+
+def _text_response(text: str) -> ChatResponse:
+    """Build a text-only chat response.
+
+    Args:
+        text (`str`):
+            The response text.
+
+    Returns:
+        `ChatResponse`:
+            A complete chat response with one text block.
+    """
+    return ChatResponse(content=[TextBlock(text=text)], is_last=True)
+
+
+def _tool_response() -> ChatResponse:
+    """Build a chat response that calls the dummy tool.
+
+    Returns:
+        `ChatResponse`:
+            A complete chat response with one tool call block.
+    """
+    return ChatResponse(
+        content=[
+            ToolCallBlock(
+                id="call_dummy",
+                name="dummy",
+                input="{}",
+            ),
+        ],
+        is_last=True,
+    )
+
+
+def _structured_response(selected_files: list[str]) -> StructuredResponse:
+    """Build a structured memory-selection response.
+
+    Args:
+        selected_files (`list[str]`):
+            The selected memory filenames.
+
+    Returns:
+        `StructuredResponse`:
+            The structured response consumed by the middleware.
+    """
+    return StructuredResponse(content={"selected_files": selected_files})
+
+
+def _block_to_dict(block: Any) -> dict:
+    """Convert a message block into a stable assertion dictionary.
+
+    Args:
+        block (`Any`):
+            The message block to convert.
+
+    Returns:
+        `dict`:
+            The stable block representation.
+    """
+    if isinstance(block, TextBlock):
+        return {
+            "type": "text",
+            "text": block.text,
+            "id": AnyString(),
+        }
+    if isinstance(block, HintBlock):
+        return {
+            "type": "hint",
+            "hint": block.hint,
+            "id": AnyString(),
+            "source": block.source,
+        }
+    if isinstance(block, ToolCallBlock):
+        return {
+            "type": "tool_call",
+            "id": AnyString(),
+            "name": block.name,
+            "input": block.input,
+            "state": block.state,
+            "suggested_rules": block.suggested_rules,
+        }
+    return block.model_dump()
+
+
+def _message_to_dict(msg: Msg) -> dict:
+    """Convert a message into a stable assertion dictionary.
+
+    Args:
+        msg (`Msg`):
+            The message to convert.
+
+    Returns:
+        `dict`:
+            The stable message representation.
+    """
+    return {
+        "id": AnyString(),
+        "name": msg.name,
+        "role": msg.role,
+        "content": [_block_to_dict(block) for block in msg.content],
+        "metadata": msg.metadata,
+    }
+
+
+def _hint_texts(agent: Agent) -> list[str]:
+    """Collect hint texts from an agent context.
+
+    Args:
+        agent (`Agent`):
+            The agent whose context is inspected.
+
+    Returns:
+        `list[str]`:
+            The hint texts in context order.
+    """
+    return [
+        block.hint
+        for msg in agent.state.context
+        for block in msg.content
+        if isinstance(block, HintBlock)
+    ]
+
+
+def _write_memory_file(
+    memory_dir: str,
+    filename: str,
+    description: str,
+    memory_type: str,
+    body: str,
+) -> None:
+    """Write one Markdown memory file with frontmatter.
+
+    Args:
+        memory_dir (`str`):
+            The memory directory.
+        filename (`str`):
+            The memory filename relative to ``memory_dir``.
+        description (`str`):
+            The frontmatter description.
+        memory_type (`str`):
+            The frontmatter memory type.
+        body (`str`):
+            The Markdown body.
+    """
+    path = os.path.join(memory_dir, filename)
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path, "w", encoding="utf-8") as f:
+        f.write(
+            "---\n"
+            f"name: {filename}\n"
+            f"description: {description}\n"
+            f"type: {memory_type}\n"
+            "---\n\n"
+            f"{body}\n",
+        )
+
+
+class AgenticMemoryMiddlewareTest(IsolatedAsyncioTestCase):
+    """Agent-level tests for :class:`AgenticMemoryMiddleware`."""
+
+    async def asyncSetUp(self) -> None:
+        """Create a temporary workspace for each test."""
+        self.temp_dir = tempfile.mkdtemp()
+
+    async def asyncTearDown(self) -> None:
+        """Remove the temporary workspace after each test."""
+        shutil.rmtree(self.temp_dir, ignore_errors=True)
+
+    def _make_agent(
+        self,
+        model: _RecordingMockModel,
+        middleware: AgenticMemoryMiddleware,
+        toolkit: Toolkit | None = None,
+    ) -> Agent:
+        """Build an Agent with the filesystem memory middleware attached.
+
+        Args:
+            model (`_RecordingMockModel`):
+                The mock model used by the agent.
+            middleware (`AgenticMemoryMiddleware`):
+                The middleware under test.
+            toolkit (`Toolkit | None`, optional):
+                The toolkit for the agent. Defaults to an empty toolkit.
+
+        Returns:
+            `Agent`:
+                The configured agent.
+        """
+        return Agent(
+            name="assistant",
+            system_prompt="You are helpful.",
+            model=model,
+            toolkit=toolkit or Toolkit(),
+            middlewares=[middleware],
+        )
+
+    async def test_agent_reply_creates_layout_and_injects_memory_prompt(
+        self,
+    ) -> None:
+        """Agent reply should create layout and inject memory instructions."""
+        model = _RecordingMockModel()
+        model.set_responses([_text_response("done")])
+        middleware = AgenticMemoryMiddleware(workdir=self.temp_dir)
+        agent = self._make_agent(model, middleware)
+
+        reply = await agent.reply(UserMsg("user", "hello"))
+        memory_dir = os.path.join(self.temp_dir, "Memory")
+        system_prompt = model.chat_messages[0][0].get_text_content()
+
+        self.assertDictEqual(
+            {
+                "reply": _message_to_dict(reply),
+                "memory_dir_exists": os.path.isdir(memory_dir),
+                "memory_md_exists": os.path.isfile(
+                    os.path.join(memory_dir, "MEMORY.md"),
+                ),
+                "system_prompt": {
+                    "has_memory_dir": memory_dir in system_prompt,
+                    "has_placeholder": "{memory_dir}" in system_prompt,
+                    "has_memory_header": "## MEMORY.md" in system_prompt,
+                    "has_empty_memory_text": (
+                        "Your MEMORY.md is currently empty" in system_prompt
+                    ),
+                },
+            },
+            {
+                "reply": {
+                    "id": AnyString(),
+                    "name": "assistant",
+                    "role": "assistant",
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": "done",
+                            "id": AnyString(),
+                        },
+                    ],
+                    "metadata": {},
+                },
+                "memory_dir_exists": True,
+                "memory_md_exists": True,
+                "system_prompt": {
+                    "has_memory_dir": True,
+                    "has_placeholder": False,
+                    "has_memory_header": True,
+                    "has_empty_memory_text": True,
+                },
+            },
+        )
+
+    async def test_agent_reasoning_injects_selected_memory_hint(
+        self,
+    ) -> None:
+        """Agent reasoning should inject content selected by structured
+        output."""
+        memory_dir = os.path.join(self.temp_dir, "Memory")
+        os.makedirs(memory_dir)
+        with open(
+            os.path.join(memory_dir, "MEMORY.md"),
+            "w",
+            encoding="utf-8",
+        ) as f:
+            f.write("- [User profile](user_profile.md) — User profile.\n")
+        _write_memory_file(
+            memory_dir,
+            "user_profile.md",
+            "User profile details",
+            "user",
+            "The user prefers concise Chinese answers.",
+        )
+
+        model = _RecordingMockModel()
+        model.set_structured_response(
+            _structured_response(["user_profile.md"]),
+        )
+        model.set_responses([_tool_response(), _text_response("final answer")])
+        middleware = AgenticMemoryMiddleware(workdir=self.temp_dir)
+        agent = self._make_agent(
+            model,
+            middleware,
+            toolkit=Toolkit(tools=[_DummyTool()]),
+        )
+
+        reply = await agent.reply(UserMsg("user", "what do you remember?"))
+        hint_texts = _hint_texts(agent)
+
+        self.assertDictEqual(
+            {
+                "reply": _message_to_dict(reply),
+                "hints": [
+                    {
+                        "has_selected_content": (
+                            "The user prefers concise Chinese answers." in hint
+                        ),
+                        "has_selected_path": "user_profile.md" in hint,
+                    }
+                    for hint in hint_texts
+                ],
+                "context": [
+                    _message_to_dict(msg) for msg in agent.state.context
+                ],
+                "structured_call_count": len(model.structured_messages),
+            },
+            {
+                "reply": {
+                    "id": AnyString(),
+                    "name": "assistant",
+                    "role": "assistant",
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": "final answer",
+                            "id": AnyString(),
+                        },
+                    ],
+                    "metadata": {},
+                },
+                "hints": [
+                    {
+                        "has_selected_content": True,
+                        "has_selected_path": True,
+                    },
+                ],
+                "context": [
+                    {
+                        "id": AnyString(),
+                        "name": "user",
+                        "role": "user",
+                        "content": [
+                            {
+                                "type": "text",
+                                "text": "what do you remember?",
+                                "id": AnyString(),
+                            },
+                        ],
+                        "metadata": {},
+                    },
+                    {
+                        "id": AnyString(),
+                        "name": "assistant",
+                        "role": "assistant",
+                        "content": [
+                            {
+                                "type": "tool_call",
+                                "id": AnyString(),
+                                "name": "dummy",
+                                "input": "{}",
+                                "state": "finished",
+                                "suggested_rules": [],
+                            },
+                            AnyValue(),
+                            {
+                                "type": "hint",
+                                "hint": AnyString(),
+                                "id": AnyString(),
+                                "source": None,
+                            },
+                            {
+                                "type": "text",
+                                "text": "final answer",
+                                "id": AnyString(),
+                            },
+                        ],
+                        "metadata": {},
+                    },
+                ],
+                "structured_call_count": 1,
+            },
+        )
+
+    async def test_agent_filters_hallucinated_memory_filenames(self) -> None:
+        """Agent retrieval should ignore filenames not present in memory."""
+        memory_dir = os.path.join(self.temp_dir, "Memory")
+        os.makedirs(memory_dir)
+        with open(
+            os.path.join(memory_dir, "MEMORY.md"),
+            "w",
+            encoding="utf-8",
+        ) as f:
+            f.write("- [User profile](user_profile.md) — User profile.\n")
+        _write_memory_file(
+            memory_dir,
+            "user_profile.md",
+            "User profile details",
+            "user",
+            "Only this real memory should be injected.",
+        )
+
+        model = _RecordingMockModel()
+        model.set_structured_response(
+            _structured_response(["user_profile.md", "missing.md"]),
+        )
+        model.set_responses([_tool_response(), _text_response("filtered")])
+        middleware = AgenticMemoryMiddleware(workdir=self.temp_dir)
+        agent = self._make_agent(
+            model,
+            middleware,
+            toolkit=Toolkit(tools=[_DummyTool()]),
+        )
+
+        await agent.reply(UserMsg("user", "recall memory"))
+        hint_texts = _hint_texts(agent)
+
+        self.assertListEqual(
+            [
+                {
+                    "has_real_memory": (
+                        "Only this real memory should be injected." in hint
+                    ),
+                    "has_missing_memory": "missing.md" in hint,
+                }
+                for hint in hint_texts
+            ],
+            [
+                {
+                    "has_real_memory": True,
+                    "has_missing_memory": False,
+                },
+            ],
+        )
+
+    async def test_agent_does_not_inject_hint_when_no_file_selected(
+        self,
+    ) -> None:
+        """Agent retrieval should inject no hint when selection is empty."""
+        memory_dir = os.path.join(self.temp_dir, "Memory")
+        os.makedirs(memory_dir)
+        with open(
+            os.path.join(memory_dir, "MEMORY.md"),
+            "w",
+            encoding="utf-8",
+        ) as f:
+            f.write("- [User profile](user_profile.md) — User profile.\n")
+        _write_memory_file(
+            memory_dir,
+            "user_profile.md",
+            "User profile details",
+            "user",
+            "This memory is available but not selected.",
+        )
+
+        model = _RecordingMockModel()
+        model.set_structured_response(_structured_response([]))
+        model.set_responses([_tool_response(), _text_response("no hint")])
+        middleware = AgenticMemoryMiddleware(workdir=self.temp_dir)
+        agent = self._make_agent(
+            model,
+            middleware,
+            toolkit=Toolkit(tools=[_DummyTool()]),
+        )
+
+        reply = await agent.reply(UserMsg("user", "ignore memories"))
+
+        self.assertDictEqual(
+            {
+                "reply": _message_to_dict(reply),
+                "hints": _hint_texts(agent),
+                "structured_call_count": len(model.structured_messages),
+            },
+            {
+                "reply": {
+                    "id": AnyString(),
+                    "name": "assistant",
+                    "role": "assistant",
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": "no hint",
+                            "id": AnyString(),
+                        },
+                    ],
+                    "metadata": {},
+                },
+                "hints": [],
+                "structured_call_count": 1,
+            },
+        )
+
+    async def test_agent_does_not_retrieve_when_only_memory_index_exists(
+        self,
+    ) -> None:
+        """Agent retrieval should skip structured output without topic
+        files."""
+        model = _RecordingMockModel()
+        model.set_structured_response(_structured_response(["missing.md"]))
+        model.set_responses([_tool_response(), _text_response("index only")])
+        middleware = AgenticMemoryMiddleware(workdir=self.temp_dir)
+        agent = self._make_agent(
+            model,
+            middleware,
+            toolkit=Toolkit(tools=[_DummyTool()]),
+        )
+
+        reply = await agent.reply(UserMsg("user", "hello"))
+
+        self.assertDictEqual(
+            {
+                "reply": _message_to_dict(reply),
+                "hints": _hint_texts(agent),
+                "structured_call_count": len(model.structured_messages),
+                "memory_md_exists": os.path.isfile(
+                    os.path.join(self.temp_dir, "Memory", "MEMORY.md"),
+                ),
+            },
+            {
+                "reply": {
+                    "id": AnyString(),
+                    "name": "assistant",
+                    "role": "assistant",
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": "index only",
+                            "id": AnyString(),
+                        },
+                    ],
+                    "metadata": {},
+                },
+                "hints": [],
+                "structured_call_count": 0,
+                "memory_md_exists": True,
+            },
+        )
+
+    async def test_agent_system_prompt_contains_truncation_reminder(
+        self,
+    ) -> None:
+        """Agent system prompt should contain reminder for truncated index."""
+        memory_dir = os.path.join(self.temp_dir, "Memory")
+        os.makedirs(memory_dir)
+        with open(
+            os.path.join(memory_dir, "MEMORY.md"),
+            "w",
+            encoding="utf-8",
+        ) as f:
+            f.write("0123456789" * 80)
+
+        model = _RecordingMockModel()
+        model.set_responses([_text_response("truncated")])
+        middleware = AgenticMemoryMiddleware(
+            workdir=self.temp_dir,
+            parameters=AgenticMemoryMiddleware.Parameters(
+                memory_max_tokens=10,
+                retrieval_async=False,
+            ),
+        )
+        agent = self._make_agent(model, middleware)
+
+        await agent.reply(UserMsg("user", "hello"))
+        system_prompt = model.chat_messages[0][0].get_text_content()
+
+        self.assertDictEqual(
+            {
+                "has_truncated_marker": "<<<TRUNCATED>>>" in system_prompt,
+                "has_offset_reminder": "Use the `Read` tool with offset"
+                in system_prompt,
+                "has_memory_path": os.path.join(memory_dir, "MEMORY.md")
+                in system_prompt,
+            },
+            {
+                "has_truncated_marker": True,
+                "has_offset_reminder": True,
+                "has_memory_path": True,
+            },
+        )
+
+    async def test_agent_skips_retrieval_when_async_retrieval_disabled(
+        self,
+    ) -> None:
+        """Agent should not run retrieval when ``retrieval_async`` is false."""
+        memory_dir = os.path.join(self.temp_dir, "Memory")
+        os.makedirs(memory_dir)
+        with open(
+            os.path.join(memory_dir, "MEMORY.md"),
+            "w",
+            encoding="utf-8",
+        ) as f:
+            f.write("- [User profile](user_profile.md) — User profile.\n")
+        _write_memory_file(
+            memory_dir,
+            "user_profile.md",
+            "User profile details",
+            "user",
+            "This memory should not be retrieved.",
+        )
+
+        model = _RecordingMockModel()
+        model.set_structured_response(
+            _structured_response(["user_profile.md"]),
+        )
+        model.set_responses([_tool_response(), _text_response("disabled")])
+        middleware = AgenticMemoryMiddleware(
+            workdir=self.temp_dir,
+            parameters=AgenticMemoryMiddleware.Parameters(
+                retrieval_async=False,
+            ),
+        )
+        agent = self._make_agent(
+            model,
+            middleware,
+            toolkit=Toolkit(tools=[_DummyTool()]),
+        )
+
+        reply = await agent.reply(UserMsg("user", "remember?"))
+
+        self.assertDictEqual(
+            {
+                "reply": _message_to_dict(reply),
+                "hints": _hint_texts(agent),
+                "structured_call_count": len(model.structured_messages),
+            },
+            {
+                "reply": {
+                    "id": AnyString(),
+                    "name": "assistant",
+                    "role": "assistant",
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": "disabled",
+                            "id": AnyString(),
+                        },
+                    ],
+                    "metadata": {},
+                },
+                "hints": [],
+                "structured_call_count": 0,
+            },
+        )
diff --git a/tests/middleware_rag_test.py b/tests/middleware_rag_test.py
new file mode 100644
index 0000000..49955b6
--- /dev/null
+++ b/tests/middleware_rag_test.py
@@ -0,0 +1,550 @@
+# -*- coding: utf-8 -*-
+"""Unit tests for the :class:`RAGMiddleware` class."""
+from contextlib import AsyncExitStack
+from types import SimpleNamespace
+from typing import Any, AsyncGenerator
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from utils import AnyString
+
+from agentscope.embedding import EmbeddingResponse
+from agentscope.event import EventType, HintBlockEvent
+from agentscope.message import (
+    Base64Source,
+    DataBlock,
+    Msg,
+    TextBlock,
+    UserMsg,
+)
+from agentscope.middleware import RAGMiddleware
+from agentscope.rag import Chunk, KnowledgeBase, QdrantStore, VectorRecord
+
+
+_HINT_SOURCE = '{"label": "KnowledgeBase", "sublabel": ""}'
+
+_EXPECTED_HINT = (
+    "<system-reminder>The following content is retrieved from the "
+    "knowledge base(s) and may be helpful for the current "
+    "request:\n"
+    "<content>[1] (source: doc-1.txt)\n"
+    "Paris is in France.</content></system-reminder>"
+)
+
+
+class _StubEmbeddingModel:
+    """A stub embedding model returning a fixed vector per input."""
+
+    supports_multimodal = False
+    dimensions = 3
+
+    def __init__(self, vector: list[float]) -> None:
+        """Initialize the stub.
+
+        Args:
+            vector (`list[float]`):
+                The vector returned for every input.
+        """
+        self.vector = vector
+        self.calls: list[list] = []
+
+    async def __call__(self, inputs: list) -> EmbeddingResponse:
+        """Return the fixed vector for each input.
+
+        Args:
+            inputs (`list`):
+                The input queries.
+
+        Returns:
+            `EmbeddingResponse`:
+                The response with one fixed vector per input.
+        """
+        self.calls.append(inputs)
+        return EmbeddingResponse(embeddings=[self.vector] * len(inputs))
+
+
+def _make_record(
+    text: str,
+    vector: list[float],
+    document_id: str,
+) -> VectorRecord:
+    """Build a VectorRecord for testing.
+
+    Args:
+        text (`str`):
+            The chunk text content.
+        vector (`list[float]`):
+            The embedding vector.
+        document_id (`str`):
+            The ID of the source document the record belongs to.
+
+    Returns:
+        `VectorRecord`:
+            The constructed record.
+    """
+    return VectorRecord(
+        vector=vector,
+        document_id=document_id,
+        chunk=Chunk(
+            content=TextBlock(text=text),
+            source=f"{document_id}.txt",
+            chunk_index=0,
+            total_chunks=1,
+        ),
+    )
+
+
+def _make_agent(
+    context: list[Msg] | None = None,
+    cur_iter: int = 0,
+) -> Any:
+    """Build a minimal stand-in for an Agent.
+
+    Args:
+        context (`list[Msg] | None`, optional):
+            The initial agent context.
+        cur_iter (`int`, defaults to ``0``):
+            Value for ``state.cur_iter``; the middleware only searches
+            on the first reasoning step (``0``).
+
+    Returns:
+        `Any`:
+            An object with ``name`` and ``state.context`` /
+            ``state.reply_id`` / ``state.session_id`` /
+            ``state.cur_iter`` / ``state.append_context``.
+    """
+
+    msgs: list[Msg] = context if context is not None else []
+
+    def _append_context(name: str, blocks: list) -> None:
+        # Always append a new assistant carrier message keyed on the
+        # static reply_id used in these tests.  Mirrors the real
+        # ``AgentState.append_context`` for the purposes of the
+        # middleware's reverse-scan removal logic.
+        carrier = Msg(name=name, role="assistant", content=blocks)
+        carrier.id = "reply-1"
+        msgs.append(carrier)
+
+    state = SimpleNamespace(
+        context=msgs,
+        reply_id="reply-1",
+        session_id="session-1",
+        cur_iter=cur_iter,
+        append_context=_append_context,
+    )
+    return SimpleNamespace(name="assistant", state=state)
+
+
+async def _drain(generator: AsyncGenerator) -> list:
+    """Exhaust an async generator into a list.
+
+    Args:
+        generator (`AsyncGenerator`):
+            The generator to drain.
+
+    Returns:
+        `list`:
+            All yielded items.
+    """
+    return [item async for item in generator]
+
+
+class RAGMiddlewareTest(IsolatedAsyncioTestCase):
+    """The test cases for the :class:`RAGMiddleware` class."""
+
+    async def asyncSetUp(self) -> None:
+        """Create an in-memory store seeded with one collection +
+        one :class:`KnowledgeBase` handle wired to it."""
+        self._exit_stack = AsyncExitStack()
+        self.store = await self._exit_stack.enter_async_context(
+            QdrantStore(location=":memory:"),
+        )
+        await self.store.create_collection("kb-1", dimensions=3)
+        await self.store.insert(
+            "kb-1",
+            [
+                _make_record("Paris is in France.", [1.0, 0.0, 0.0], "doc-1"),
+                _make_record("Cats are mammals.", [0.0, 1.0, 0.0], "doc-2"),
+            ],
+        )
+        self.embedding_model = _StubEmbeddingModel([1.0, 0.0, 0.0])
+        # Build the KnowledgeBase handle once; tests share it.  The
+        # collection already exists, so ``ensure_collection`` will
+        # short-circuit on first use.
+        self.knowledge = KnowledgeBase(
+            name="paris-kb",
+            description="Trivia about Paris and cats.",
+            embedding_model=self.embedding_model,
+            vector_store=self.store,
+            collection="kb-1",
+        )
+
+    async def asyncTearDown(self) -> None:
+        """Close the store after each test."""
+        await self._exit_stack.aclose()
+
+    def _middleware(
+        self,
+        knowledges: list[KnowledgeBase] | None = None,
+        **kwargs: Any,
+    ) -> RAGMiddleware:
+        """Build a middleware bound to ``self.knowledge`` with a
+        :class:`SearchConfig` assembled from ``kwargs``.
+
+        Args:
+            knowledges (`list[KnowledgeBase] | None`, optional):
+                Override the bound knowledge bases.  Defaults to
+                ``[self.knowledge]``.
+            **kwargs (`Any`):
+                Forwarded to :class:`SearchConfig` (e.g. ``mode``,
+                ``top_k``, ``score_threshold``, ``emit_hint_event``,
+                ``persist_hint``).
+
+        Returns:
+            `RAGMiddleware`:
+                The middleware under test.
+        """
+        return RAGMiddleware(
+            knowledge_bases=knowledges
+            if knowledges is not None
+            else [
+                self.knowledge,
+            ],
+            parameters=RAGMiddleware.Parameters(**kwargs),
+        )
+
+    async def _run_with_inputs(
+        self,
+        middleware: RAGMiddleware,
+        agent: Any,
+        inputs: Msg | list[Msg] | None,
+        context_during_reasoning: list[dict] | None = None,
+    ) -> list:
+        """Drive ``on_reply`` → ``on_reasoning`` end-to-end.
+
+        Mirrors the real agent loop: ``on_reply`` captures the inputs
+        in the middleware's scratchpad, then ``on_reasoning`` runs
+        (with ``state.cur_iter == 0``) and may inject a hint.  The
+        reasoning step yields a sentinel ``"reasoning-evt"`` so callers
+        can assert event order; if ``context_during_reasoning`` is
+        provided it is filled with a dump of ``agent.state.context`` as
+        seen by the innermost reasoning callback.
+
+        Args:
+            middleware (`RAGMiddleware`):
+                The middleware under test.
+            agent (`Any`):
+                The fake agent.
+            inputs (`Msg | list[Msg] | None`):
+                The reply inputs to pass through ``on_reply``.
+            context_during_reasoning (`list[dict] | None`, optional):
+                When provided, receives a dump of the agent context as
+                seen by the wrapped (innermost) reasoning call.
+
+        Returns:
+            `list`:
+                All events yielded by the on_reply → on_reasoning chain.
+        """
+
+        async def reasoning_next(**_kwargs: Any) -> AsyncGenerator:
+            if context_during_reasoning is not None:
+                context_during_reasoning.extend(
+                    msg.model_dump() for msg in agent.state.context
+                )
+            yield "reasoning-evt"
+
+        async def reply_next(**_kwargs: Any) -> AsyncGenerator:
+            # The reply branch drives the reasoning branch — same as
+            # the real composition.
+            async for evt in middleware.on_reasoning(
+                agent=agent,
+                input_kwargs={"tool_choice": None},
+                next_handler=reasoning_next,
+            ):
+                yield evt
+
+        return await _drain(
+            middleware.on_reply(
+                agent=agent,
+                input_kwargs={"inputs": inputs},
+                next_handler=reply_next,
+            ),
+        )
+
+    # ------------------------------------------------------------------
+    # Static mode (auto-injection)
+    # ------------------------------------------------------------------
+
+    async def test_static_one_shot_injection(self) -> None:
+        """The hint participates in one reasoning step and is removed
+        afterwards (``persist_hint=False``, default)."""
+        middleware = self._middleware(
+            mode="static",
+            top_k=1,
+            emit_hint_event=False,
+        )
+        agent = _make_agent()
+        seen_context: list[dict] = []
+
+        events = await self._run_with_inputs(
+            middleware,
+            agent,
+            UserMsg(name="user", content="Where is Paris?"),
+            context_during_reasoning=seen_context,
+        )
+
+        # No HintBlockEvent (emit_hint_event=False); only downstream
+        # events.
+        self.assertEqual(events, ["reasoning-evt"])
+
+        # The reasoning callback observed exactly one carrier message
+        # holding the injected hint block.
+        self.assertEqual(len(seen_context), 1)
+        carrier = seen_context[0]
+        self.assertEqual(carrier["role"], "assistant")
+        self.assertEqual(carrier["id"], "reply-1")
+        self.assertEqual(len(carrier["content"]), 1)
+        block = carrier["content"][0]
+        self.assertEqual(block["type"], "hint")
+        self.assertEqual(block["source"], _HINT_SOURCE)
+        self.assertEqual(block["hint"], _EXPECTED_HINT)
+
+        # One-shot: after on_reasoning unwinds, the carrier is emptied.
+        post = [msg.model_dump() for msg in agent.state.context]
+        self.assertEqual(len(post), 1)
+        self.assertEqual(post[0]["content"], [])
+
+    async def test_static_persistent_injection(self) -> None:
+        """``persist_hint=True`` keeps the hint in the context."""
+        middleware = self._middleware(
+            mode="static",
+            top_k=1,
+            persist_hint=True,
+            emit_hint_event=False,
+        )
+        agent = _make_agent()
+        seen_context: list[dict] = []
+
+        await self._run_with_inputs(
+            middleware,
+            agent,
+            UserMsg(name="user", content="Where is Paris?"),
+            context_during_reasoning=seen_context,
+        )
+
+        self.assertEqual(
+            [msg.model_dump() for msg in agent.state.context],
+            seen_context,
+        )
+
+    async def test_static_event_emission(self) -> None:
+        """``emit_hint_event=True`` yields one :class:`HintBlockEvent`."""
+        middleware = self._middleware(
+            mode="static",
+            top_k=1,
+            emit_hint_event=True,
+        )
+        agent = _make_agent()
+
+        events = await self._run_with_inputs(
+            middleware,
+            agent,
+            UserMsg(name="user", content="Where is Paris?"),
+        )
+
+        self.assertEqual(len(events), 2)
+        self.assertIsInstance(events[0], HintBlockEvent)
+        self.assertEqual(
+            events[0].model_dump(),
+            {
+                "type": EventType.HINT_BLOCK,
+                "reply_id": "reply-1",
+                "block_id": AnyString(),
+                "source": _HINT_SOURCE,
+                "hint": _EXPECTED_HINT,
+                "id": AnyString(),
+                "created_at": AnyString(),
+                "metadata": {},
+            },
+        )
+        self.assertEqual(events[1], "reasoning-evt")
+
+    async def test_static_skips_event_inputs(self) -> None:
+        """Non-message inputs (resumption events / ``None``) skip the
+        search entirely."""
+        middleware = self._middleware(mode="static")
+        agent = _make_agent()
+
+        events = await self._run_with_inputs(middleware, agent, None)
+
+        self.assertEqual(events, ["reasoning-evt"])
+        self.assertEqual(self.embedding_model.calls, [])
+        self.assertEqual(agent.state.context, [])
+
+    async def test_multimodal_query_extraction(self) -> None:
+        """DataBlocks reach the embedding model when it declares
+        ``supports_multimodal``."""
+        self.embedding_model.supports_multimodal = True
+        middleware = self._middleware(
+            mode="static",
+            top_k=1,
+            emit_hint_event=False,
+        )
+        agent = _make_agent()
+        data_block = DataBlock(
+            source=Base64Source(data="aGk=", media_type="image/png"),
+        )
+
+        await self._run_with_inputs(
+            middleware,
+            agent,
+            UserMsg(
+                name="user",
+                content=[TextBlock(text="What is this?"), data_block],
+            ),
+        )
+
+        # The query path prepends ``{name}: `` to the first text
+        # block; the data block is passed through verbatim.
+        self.assertEqual(len(self.embedding_model.calls), 1)
+        query = self.embedding_model.calls[0]
+        self.assertEqual(len(query), 2)
+        self.assertEqual(query[0].text, "user: What is this?")
+        self.assertEqual(query[1], data_block)
+
+    async def test_multimodal_blocks_dropped_for_text_only_model(
+        self,
+    ) -> None:
+        """A text-only embedding model silently drops DataBlock queries
+        (no exception, no crash)."""
+        middleware = self._middleware(
+            mode="static",
+            top_k=1,
+            emit_hint_event=False,
+        )
+        agent = _make_agent()
+        data_block = DataBlock(
+            source=Base64Source(data="aGk=", media_type="image/png"),
+        )
+
+        await self._run_with_inputs(
+            middleware,
+            agent,
+            UserMsg(
+                name="user",
+                content=[TextBlock(text="What is this?"), data_block],
+            ),
+        )
+
+        # ``KnowledgeBase.search`` strips the DataBlock when the bound
+        # embedding model isn't multimodal — the model only saw text.
+        self.assertEqual(len(self.embedding_model.calls), 1)
+        for item in self.embedding_model.calls[0]:
+            self.assertNotIsInstance(item, DataBlock)
+
+    # ------------------------------------------------------------------
+    # Agentic mode (tool exposure)
+    # ------------------------------------------------------------------
+
+    async def test_agentic_list_tools(self) -> None:
+        """Agentic mode exposes the search tool; static mode none."""
+        agentic_tools = await self._middleware(mode="agentic").list_tools()
+        static_tools = await self._middleware(mode="static").list_tools()
+
+        self.assertEqual(
+            [tool.name for tool in agentic_tools],
+            ["search_knowledge"],
+        )
+        self.assertEqual(static_tools, [])
+
+    async def test_agentic_no_auto_injection(self) -> None:
+        """Agentic mode never searches or injects automatically."""
+        middleware = self._middleware(mode="agentic")
+        agent = _make_agent()
+
+        events = await self._run_with_inputs(
+            middleware,
+            agent,
+            UserMsg(name="user", content="Where is Paris?"),
+        )
+
+        self.assertEqual(events, ["reasoning-evt"])
+        self.assertEqual(self.embedding_model.calls, [])
+        self.assertEqual(agent.state.context, [])
+
+    async def test_search_knowledge_tool_call(self) -> None:
+        """The tool returns a formatted ``ToolChunk`` for a query.
+
+        ``_SearchKnowledgeTool.call`` is a regular async function (not
+        an async generator), so ``ToolBase.__call__`` awaits it and
+        returns the single ``ToolChunk`` directly.
+        """
+        middleware = self._middleware(mode="agentic", top_k=1)
+        tool = (await middleware.list_tools())[0]
+
+        chunk = await tool(query="Where is Paris?")
+
+        self.assertEqual(
+            chunk.model_dump(),
+            {
+                "content": [
+                    {
+                        "type": "text",
+                        "text": (
+                            "[1] (source: doc-1.txt)\nParis is in France."
+                        ),
+                        "id": AnyString(),
+                    },
+                ],
+                "state": "success",
+                "is_last": True,
+                "metadata": {},
+                "id": AnyString(),
+            },
+        )
+
+    async def test_search_knowledge_tool_input_schema_enum(self) -> None:
+        """The tool's ``input_schema`` narrows ``knowledge_bases.items``
+        to the equipped KB names."""
+        middleware = self._middleware(mode="agentic")
+        tool = (await middleware.list_tools())[0]
+
+        schema = tool.input_schema
+        kb_schema = schema["properties"]["knowledge_bases"]
+        # Pydantic emits Optional[list[str]] as anyOf; pick the array
+        # branch.
+        array_variant = next(
+            v for v in kb_schema["anyOf"] if v.get("type") == "array"
+        )
+        self.assertEqual(array_variant["items"]["enum"], ["paris-kb"])
+
+    async def test_search_knowledge_tool_filters_by_name(self) -> None:
+        """Passing ``knowledge_bases=[<unknown>]`` returns the
+        ``"No relevant content found."`` notice without touching the
+        embedding model."""
+        middleware = self._middleware(mode="agentic", top_k=1)
+        tool = (await middleware.list_tools())[0]
+
+        chunk = await tool(
+            query="Where is Paris?",
+            knowledge_bases=["does-not-exist"],
+        )
+
+        self.assertEqual(
+            [b["text"] for b in chunk.model_dump()["content"]],
+            ["No relevant content found."],
+        )
+        self.assertEqual(self.embedding_model.calls, [])
+
+    # ------------------------------------------------------------------
+    # Config validation
+    # ------------------------------------------------------------------
+
+    async def test_hint_template_must_have_context_placeholder(self) -> None:
+        """:class:`SearchConfig` rejects a template without exactly one
+        ``{context}``."""
+        with self.assertRaises(ValueError):
+            RAGMiddleware.Parameters(hint_template="no placeholder here")
+        with self.assertRaises(ValueError):
+            RAGMiddleware.Parameters(hint_template="{context} twice {context}")
+        # Exactly one placeholder is fine.
+        RAGMiddleware.Parameters(hint_template="wrapped: {context}.")
diff --git a/tests/middleware_test.py b/tests/middleware_test.py
new file mode 100644
index 0000000..3810612
--- /dev/null
+++ b/tests/middleware_test.py
@@ -0,0 +1,1295 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=abstract-method
+"""Unit tests for middleware system."""
+from unittest.async_case import IsolatedAsyncioTestCase
+from unittest.mock import AsyncMock, patch
+from typing import Any, AsyncGenerator, Callable, Union
+
+from utils import MockModel
+from pydantic import BaseModel
+from agentscope.event import AgentEvent
+from agentscope.agent import Agent, ContextConfig
+from agentscope.middleware import MiddlewareBase
+from agentscope.model import ChatResponse
+from agentscope.message import (
+    TextBlock,
+    HintBlock,
+    UserMsg,
+    SystemMsg,
+    Msg,
+    ToolCallBlock,
+)
+from agentscope.tool import Toolkit, ToolBase, ToolChunk
+from agentscope.permission import (
+    PermissionContext,
+    PermissionDecision,
+    PermissionBehavior,
+)
+
+
+class TestMiddleware(IsolatedAsyncioTestCase):
+    """Test cases for middleware system."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up test fixtures."""
+        self.mock_model = MockModel()
+        self.toolkit = Toolkit()
+        self.execution_log = []
+
+    async def test_on_reply_middleware_pre_post_yield(self) -> None:
+        """Test on_reply middleware pre, post and yield positions."""
+
+        class ReplyMiddleware(MiddlewareBase):
+            """Middleware for testing on_reply hook."""
+
+            def __init__(self, log: list, name: str) -> None:
+                """Initialize the reply middleware.
+
+                Args:
+                    log: The execution log list.
+                    name: The middleware name.
+                """
+                self.log = log
+                self.name = name
+
+            async def on_reply(
+                self,
+                agent: Agent,
+                input_kwargs: dict,
+                next_handler: Callable[[], AsyncGenerator],
+            ) -> AsyncGenerator:
+                """The on_reply middleware logic."""
+                self.log.append(f"{self.name}_pre")
+                async for item in next_handler():
+                    if isinstance(item, AgentEvent):
+                        self.log.append(f"{self.name}_{item.type}")
+                    elif isinstance(item, Msg):
+                        self.log.append(f"{self.name}_msg")
+                    yield item
+                self.log.append(f"{self.name}_post")
+
+        middleware1 = ReplyMiddleware(self.execution_log, "mw1")
+        middleware2 = ReplyMiddleware(self.execution_log, "mw2")
+
+        self.mock_model.set_responses(
+            [
+                ChatResponse(
+                    content=[TextBlock(text="test response")],
+                    is_last=True,
+                ),
+            ],
+        )
+
+        agent = Agent(
+            name="test_agent",
+            system_prompt="test prompt",
+            model=self.mock_model,
+            toolkit=self.toolkit,
+            middlewares=[middleware1, middleware2],
+        )
+
+        await agent.reply(UserMsg("user", "test message"))
+
+        # Verify execution order
+        expected = [
+            "mw1_pre",
+            "mw2_pre",
+            "mw2_REPLY_START",
+            "mw1_REPLY_START",
+            "mw2_MODEL_CALL_START",
+            "mw1_MODEL_CALL_START",
+            "mw2_TEXT_BLOCK_START",
+            "mw1_TEXT_BLOCK_START",
+            "mw2_TEXT_BLOCK_DELTA",
+            "mw1_TEXT_BLOCK_DELTA",
+            "mw2_TEXT_BLOCK_END",
+            "mw1_TEXT_BLOCK_END",
+            "mw2_MODEL_CALL_END",
+            "mw1_MODEL_CALL_END",
+            "mw2_msg",
+            "mw1_msg",
+            "mw2_REPLY_END",
+            "mw1_REPLY_END",
+            "mw2_post",
+            "mw1_post",
+        ]
+        self.assertListEqual(self.execution_log, expected)
+
+    async def test_on_reasoning_middleware_pre_yield(self) -> None:
+        """Test on_reasoning middleware pre and yield positions."""
+
+        class ReasoningMiddleware(MiddlewareBase):
+            """Middleware for testing on_reasoning hook."""
+
+            def __init__(self, log: list, name: str) -> None:
+                """Initialize the reasoning middleware.
+
+                Args:
+                    log: The execution log list.
+                    name: The middleware name.
+                """
+                self.log = log
+                self.name = name
+
+            async def on_reasoning(
+                self,
+                agent: Agent,
+                input_kwargs: dict,
+                next_handler: Callable[[], AsyncGenerator],
+            ) -> AsyncGenerator:
+                """The on_reasoning middleware logic."""
+                self.log.append(f"{self.name}_pre")
+                async for item in next_handler():
+                    if isinstance(item, AgentEvent):
+                        self.log.append(f"{self.name}_{item.type}")
+                    elif isinstance(item, Msg):
+                        self.log.append(f"{self.name}_msg")
+                    yield item
+                self.log.append(f"{self.name}_post")
+
+        middleware1 = ReasoningMiddleware(self.execution_log, "mw1")
+        middleware2 = ReasoningMiddleware(self.execution_log, "mw2")
+
+        self.mock_model.set_responses(
+            [
+                ChatResponse(
+                    content=[TextBlock(text="test response")],
+                    is_last=True,
+                ),
+            ],
+        )
+
+        agent = Agent(
+            name="test_agent",
+            system_prompt="test prompt",
+            model=self.mock_model,
+            toolkit=self.toolkit,
+            middlewares=[middleware1, middleware2],
+        )
+
+        await agent.reply(UserMsg("user", "test message"))
+
+        # Verify execution order
+        expected = [
+            "mw1_pre",
+            "mw2_pre",
+            "mw2_MODEL_CALL_START",
+            "mw1_MODEL_CALL_START",
+            "mw2_TEXT_BLOCK_START",
+            "mw1_TEXT_BLOCK_START",
+            "mw2_TEXT_BLOCK_DELTA",
+            "mw1_TEXT_BLOCK_DELTA",
+            "mw2_TEXT_BLOCK_END",
+            "mw1_TEXT_BLOCK_END",
+            "mw2_MODEL_CALL_END",
+            "mw1_MODEL_CALL_END",
+            "mw2_msg",
+            "mw1_msg",
+        ]
+        self.assertListEqual(self.execution_log, expected)
+
+    async def test_on_model_call_middleware_non_streaming(self) -> None:
+        """Test on_model_call middleware for non-streaming model."""
+
+        class ModelCallMiddleware(MiddlewareBase):
+            """Middleware for testing on_model_call hook."""
+
+            def __init__(self, log: list, name: str) -> None:
+                """Initialize the model call middleware.
+
+                Args:
+                    log: The execution log list.
+                    name: The middleware name.
+                """
+                self.log = log
+                self.name = name
+
+            async def on_model_call(
+                self,
+                agent: Agent,
+                input_kwargs: dict,
+                next_handler: Callable,
+            ) -> Union[ChatResponse, AsyncGenerator[ChatResponse, None]]:
+                """The on_model_call middleware logic."""
+                self.log.append(f"{self.name}_pre")
+                result = await next_handler()
+                self.log.append(f"{self.name}_post")
+                return result
+
+        middleware1 = ModelCallMiddleware(self.execution_log, "mw1")
+        middleware2 = ModelCallMiddleware(self.execution_log, "mw2")
+
+        self.mock_model.set_responses(
+            [
+                ChatResponse(
+                    content=[TextBlock(text="test response")],
+                    is_last=True,
+                ),
+            ],
+        )
+
+        agent = Agent(
+            name="test_agent",
+            system_prompt="test prompt",
+            model=self.mock_model,
+            toolkit=self.toolkit,
+            middlewares=[middleware1, middleware2],
+        )
+
+        await agent.reply(UserMsg("user", "test message"))
+
+        # Verify execution order: mw1_pre -> mw2_pre -> mw2_post -> mw1_post
+        expected = ["mw1_pre", "mw2_pre", "mw2_post", "mw1_post"]
+        self.assertListEqual(self.execution_log, expected)
+
+    async def test_on_model_call_middleware_streaming(self) -> None:
+        """Test on_model_call middleware for streaming model."""
+
+        class ModelCallMiddleware(MiddlewareBase):
+            """Middleware for testing on_model_call hook with streaming."""
+
+            def __init__(self, log: list, name: str) -> None:
+                """Initialize the model call middleware.
+
+                Args:
+                    log: The execution log list.
+                    name: The middleware name.
+                """
+                self.log = log
+                self.name = name
+
+            async def on_model_call(
+                self,
+                agent: Agent,
+                input_kwargs: dict,
+                next_handler: Callable,
+            ) -> Union[ChatResponse, AsyncGenerator[ChatResponse, None]]:
+                """The on_model_call middleware logic for streaming."""
+                self.log.append(f"{self.name}_pre")
+                result = await next_handler()
+
+                async def wrapped_generator() -> AsyncGenerator[
+                    ChatResponse,
+                    None,
+                ]:
+                    """Wrap the generator to log yields."""
+                    async for chunk in result:
+                        self.log.append(f"{self.name}_chunk")
+                        yield chunk
+                    self.log.append(f"{self.name}_post")
+
+                return wrapped_generator()
+
+        middleware1 = ModelCallMiddleware(self.execution_log, "mw1")
+        middleware2 = ModelCallMiddleware(self.execution_log, "mw2")
+
+        self.mock_model.set_responses(
+            [
+                [
+                    ChatResponse(
+                        content=[TextBlock(text="chunk1")],
+                        is_last=False,
+                    ),
+                    ChatResponse(
+                        content=[TextBlock(text="chunk2")],
+                        is_last=False,
+                    ),
+                    ChatResponse(
+                        content=[TextBlock(text="chunk3")],
+                        is_last=True,
+                    ),
+                ],
+            ],
+        )
+
+        agent = Agent(
+            name="test_agent",
+            system_prompt="test prompt",
+            model=self.mock_model,
+            toolkit=self.toolkit,
+            middlewares=[middleware1, middleware2],
+        )
+
+        await agent.reply(UserMsg("user", "test message"))
+
+        # Verify execution order
+        expected = [
+            "mw1_pre",
+            "mw2_pre",
+            "mw2_chunk",
+            "mw1_chunk",
+            "mw2_chunk",
+            "mw1_chunk",
+            "mw2_chunk",
+            "mw1_chunk",
+            "mw2_post",
+            "mw1_post",
+        ]
+        self.assertListEqual(self.execution_log, expected)
+
+    async def test_on_system_prompt_middleware(self) -> None:
+        """Test on_system_prompt middleware (transformer pattern)."""
+
+        class SystemPromptMiddleware(MiddlewareBase):
+            """Middleware for testing on_system_prompt hook."""
+
+            def __init__(self, log: list, name: str, suffix: str) -> None:
+                """Initialize the system prompt middleware.
+
+                Args:
+                    log: The execution log list.
+                    name: The middleware name.
+                    suffix: The suffix to append to the prompt.
+                """
+                self.log = log
+                self.name = name
+                self.suffix = suffix
+
+            async def on_system_prompt(
+                self,
+                agent: Agent,
+                current_prompt: str,
+            ) -> str:
+                """The on_system_prompt middleware logic."""
+                self.log.append(f"{self.name}_executed")
+                return f"{current_prompt} {self.suffix}"
+
+        middleware1 = SystemPromptMiddleware(
+            self.execution_log,
+            "mw1",
+            "[MW1]",
+        )
+        middleware2 = SystemPromptMiddleware(
+            self.execution_log,
+            "mw2",
+            "[MW2]",
+        )
+
+        self.mock_model.set_responses(
+            [
+                ChatResponse(
+                    content=[TextBlock(text="test response")],
+                    is_last=True,
+                ),
+            ],
+        )
+
+        agent = Agent(
+            name="test_agent",
+            system_prompt="test prompt",
+            model=self.mock_model,
+            toolkit=self.toolkit,
+            middlewares=[middleware1, middleware2],
+        )
+
+        await agent.reply(UserMsg("user", "test message"))
+
+        # Verify execution order: mw1 -> mw2 (sequential transformer pattern)
+        # Note: system_prompt is called twice (once for initial setup, once
+        # during reasoning)
+        expected = [
+            "mw1_executed",
+            "mw2_executed",  # First call
+            "mw1_executed",
+            "mw2_executed",  # Second call during reasoning
+        ]
+        self.assertListEqual(self.execution_log, expected)
+
+    async def test_multiple_middleware_types(self) -> None:
+        """Test multiple middleware types working together."""
+
+        class MultiMiddleware(MiddlewareBase):
+            """Middleware implementing multiple hooks."""
+
+            def __init__(self, log: list, name: str) -> None:
+                """Initialize the multi middleware.
+
+                Args:
+                    log: The execution log list.
+                    name: The middleware name.
+                """
+                self.log = log
+                self.name = name
+
+            async def on_reply(
+                self,
+                agent: Agent,
+                input_kwargs: dict,
+                next_handler: Callable[[], AsyncGenerator],
+            ) -> AsyncGenerator:
+                """The on_reply middleware logic."""
+                self.log.append(f"{self.name}_reply_pre")
+                async for item in next_handler():
+                    yield item
+                self.log.append(f"{self.name}_reply_post")
+
+            async def on_reasoning(
+                self,
+                agent: Agent,
+                input_kwargs: dict,
+                next_handler: Callable[[], AsyncGenerator],
+            ) -> AsyncGenerator:
+                """The on_reasoning middleware logic."""
+                self.log.append(f"{self.name}_reasoning_pre")
+                async for item in next_handler():
+                    yield item
+                self.log.append(f"{self.name}_reasoning_post")
+
+            async def on_model_call(
+                self,
+                agent: Agent,
+                input_kwargs: dict,
+                next_handler: Callable,
+            ) -> Union[ChatResponse, AsyncGenerator[ChatResponse, None]]:
+                """The on_model_call middleware logic."""
+                self.log.append(f"{self.name}_model_call_pre")
+                result = await next_handler()
+                self.log.append(f"{self.name}_model_call_post")
+                return result
+
+            async def on_system_prompt(
+                self,
+                agent: Agent,
+                current_prompt: str,
+            ) -> str:
+                """The on_system_prompt middleware logic."""
+                self.log.append(f"{self.name}_system_prompt")
+                return current_prompt
+
+        middleware = MultiMiddleware(self.execution_log, "multi")
+
+        self.mock_model.set_responses(
+            [
+                ChatResponse(
+                    content=[TextBlock(text="test response")],
+                    is_last=True,
+                ),
+            ],
+        )
+
+        agent = Agent(
+            name="test_agent",
+            system_prompt="test prompt",
+            model=self.mock_model,
+            toolkit=self.toolkit,
+            middlewares=[middleware],
+        )
+
+        await agent.reply(UserMsg("user", "test message"))
+
+        # Verify all middleware hooks were called
+        expected = [
+            "multi_reply_pre",
+            "multi_system_prompt",
+            "multi_reasoning_pre",
+            "multi_system_prompt",
+            "multi_model_call_pre",
+            "multi_model_call_post",
+            "multi_reply_post",
+        ]
+        self.assertListEqual(self.execution_log, expected)
+
+    async def test_on_reply_middleware_modify_input(self) -> None:
+        """Test that on_reply middleware can modify msgs input."""
+
+        class ModifyMsgsMiddleware(MiddlewareBase):
+            """Middleware that modifies the msgs input."""
+
+            async def on_reply(
+                self,
+                agent: Agent,
+                input_kwargs: dict,
+                next_handler: Callable[..., AsyncGenerator],
+            ) -> AsyncGenerator:
+                """Modify inputs before passing to next handler."""
+                # Modify the message content
+                inputs = input_kwargs["inputs"]
+                if isinstance(inputs, Msg):
+                    modified_msg = UserMsg(
+                        name=inputs.name,
+                        content="MODIFIED: " + inputs.get_text_content(),
+                    )
+                    async for item in next_handler(inputs=modified_msg):
+                        yield item
+                else:
+                    async for item in next_handler(**input_kwargs):
+                        yield item
+
+        middleware = ModifyMsgsMiddleware()
+
+        # Track what message the model receives
+        received_messages = []
+
+        class TrackingModel(MockModel):
+            """Model that tracks received messages."""
+
+            async def _call_api(
+                self,
+                *args: Any,
+                **kwargs: Any,
+            ) -> ChatResponse:
+                """Track the messages and return mock response."""
+                messages = kwargs.get("messages", [])
+                received_messages.extend(messages)
+                return await super()._call_api(*args, **kwargs)
+
+        tracking_model = TrackingModel()
+        tracking_model.set_responses(
+            [
+                ChatResponse(
+                    content=[TextBlock(text="response")],
+                    is_last=True,
+                ),
+            ],
+        )
+
+        agent_instance = Agent(
+            name="test_agent",
+            system_prompt="test prompt",
+            model=tracking_model,
+            toolkit=self.toolkit,
+            middlewares=[middleware],
+        )
+
+        await agent_instance.reply(UserMsg("user", "original message"))
+
+        # Verify the model received the modified message
+        user_messages = [m for m in received_messages if m.role == "user"]
+        self.assertTrue(len(user_messages) > 0)
+        self.assertIn(
+            "MODIFIED: original message",
+            user_messages[-1].get_text_content(),
+        )
+
+    async def test_on_reply_keeps_outer_input_when_inner_omits_kwargs(
+        self,
+    ) -> None:
+        """Argumentless next_handler() keeps outer reply input changes."""
+
+        class ModifyInputMiddleware(MiddlewareBase):
+            """Middleware that replaces the reply input."""
+
+            async def on_reply(
+                self,
+                agent: Agent,
+                input_kwargs: dict,
+                next_handler: Callable[..., AsyncGenerator],
+            ) -> AsyncGenerator:
+                inputs = input_kwargs["inputs"]
+                modified = UserMsg(
+                    name=inputs.name,
+                    content="MODIFIED by outer middleware",
+                )
+                async for item in next_handler(inputs=modified):
+                    yield item
+
+        class TransparentMiddleware(MiddlewareBase):
+            """Middleware that calls next_handler() without passing kwargs."""
+
+            async def on_reply(
+                self,
+                agent: Agent,
+                input_kwargs: dict,
+                next_handler: Callable[..., AsyncGenerator],
+            ) -> AsyncGenerator:
+                assert (
+                    "MODIFIED by outer middleware"
+                    in input_kwargs["inputs"].get_text_content()
+                )
+                async for item in next_handler():
+                    yield item
+
+        received_messages = []
+
+        class TrackingModel(MockModel):
+            """Model that tracks received messages."""
+
+            async def _call_api(
+                self,
+                *args: Any,
+                **kwargs: Any,
+            ) -> ChatResponse:
+                received_messages.extend(kwargs.get("messages", []))
+                return await super()._call_api(*args, **kwargs)
+
+        tracking_model = TrackingModel()
+        tracking_model.set_responses(
+            [ChatResponse(content=[TextBlock(text="response")], is_last=True)],
+        )
+
+        agent_instance = Agent(
+            name="test_agent",
+            system_prompt="test prompt",
+            model=tracking_model,
+            toolkit=self.toolkit,
+            middlewares=[
+                ModifyInputMiddleware(),
+                TransparentMiddleware(),
+            ],
+        )
+
+        await agent_instance.reply(UserMsg("user", "original message"))
+
+        user_messages = [m for m in received_messages if m.role == "user"]
+        self.assertIn(
+            "MODIFIED by outer middleware",
+            user_messages[-1].get_text_content(),
+        )
+
+    async def test_on_reasoning_middleware_modify_input(self) -> None:
+        """Test that on_reasoning middleware can modify tool_choice input."""
+
+        class ModifyToolChoiceMiddleware(MiddlewareBase):
+            """Middleware that modifies the tool_choice input."""
+
+            async def on_reasoning(
+                self,
+                agent: Agent,
+                input_kwargs: dict,
+                next_handler: Callable[..., AsyncGenerator],
+            ) -> AsyncGenerator:
+                """Force tool_choice to 'none' to prevent tool calls."""
+                # Override tool_choice to 'none'
+                async for item in next_handler(tool_choice="none"):
+                    yield item
+
+        middleware = ModifyToolChoiceMiddleware()
+
+        # Track what tool_choice the model receives
+        received_tool_choices = []
+
+        class TrackingModel(MockModel):
+            """Model that tracks received tool_choice."""
+
+            async def _call_api(
+                self,
+                *args: Any,
+                **kwargs: Any,
+            ) -> ChatResponse:
+                """Track the tool_choice and return mock response."""
+                tool_choice = kwargs.get("tool_choice")
+                received_tool_choices.append(tool_choice)
+                return await super()._call_api(*args, **kwargs)
+
+        tracking_model = TrackingModel()
+        tracking_model.set_responses(
+            [
+                ChatResponse(
+                    content=[TextBlock(text="response without tools")],
+                    is_last=True,
+                ),
+            ],
+        )
+
+        agent_instance = Agent(
+            name="test_agent",
+            system_prompt="test prompt",
+            model=tracking_model,
+            toolkit=self.toolkit,
+            middlewares=[middleware],
+        )
+
+        await agent_instance.reply(UserMsg("user", "test message"))
+
+        # Verify the model received tool_choice='none'
+        self.assertIn("none", received_tool_choices)
+
+    async def test_on_acting_middleware_intercepts_tool_execution(
+        self,
+    ) -> None:
+        """Test that on_acting middleware intercepts raw tool execution.
+
+        After the refactor, ``on_acting`` wraps only ``_acting_impl``
+        (i.e. ``toolkit.call_tool``).  Permission checking and context
+        writes are handled by ``_execute_tool_call`` *outside* the hook.
+        This test verifies that the middleware can observe and modify the
+        ``tool_call`` passed to the actual tool function.
+        """
+
+        # ------------------------------------------------------------------ #
+        # A minimal tool that records the raw input it receives.              #
+        # ------------------------------------------------------------------ #
+        received_inputs: list[str] = []
+
+        class _EchoParams(BaseModel):
+            value: str
+
+        class EchoTool(ToolBase):
+            """Tool that echoes its input and records it."""
+
+            name: str = "echo"
+            description: str = "Echo the value."
+            input_schema: dict = _EchoParams.model_json_schema()
+            is_concurrency_safe: bool = True
+            is_read_only: bool = True
+            is_state_injected: bool = False
+            is_external_tool: bool = False
+            is_mcp: bool = False
+            mcp_name: str | None = None
+
+            async def check_permissions(
+                self,
+                tool_input: dict[str, Any],
+                context: PermissionContext,
+            ) -> PermissionDecision:
+                """Always allow."""
+                return PermissionDecision(
+                    behavior=PermissionBehavior.ALLOW,
+                    message="allowed",
+                )
+
+            async def __call__(
+                self,
+                value: str,
+            ) -> ToolChunk:
+                """Record the value and return it."""
+                received_inputs.append(value)
+                return ToolChunk(
+                    content=[TextBlock(text=f"echo:{value}")],
+                )
+
+        toolkit_with_tool = Toolkit(tools=[EchoTool()])
+
+        # ------------------------------------------------------------------ #
+        # Middleware that renames the tool_call.input before forwarding.      #
+        # ------------------------------------------------------------------ #
+        intercepted_tool_calls: list[str] = []
+
+        class ObserveActingMiddleware(MiddlewareBase):
+            """Middleware that records the tool_call seen at acting level."""
+
+            async def on_acting(
+                self,
+                agent: Agent,
+                input_kwargs: dict,
+                next_handler: Callable[..., AsyncGenerator],
+            ) -> AsyncGenerator:
+                """Record the tool_call and forward to next handler."""
+                tool_call = input_kwargs["tool_call"]
+                intercepted_tool_calls.append(tool_call.input)
+                # Modify the input before execution
+                import json
+
+                modified = ToolCallBlock(
+                    id=tool_call.id,
+                    name=tool_call.name,
+                    input=json.dumps({"value": "MODIFIED"}),
+                    state=tool_call.state,
+                )
+                async for chunk in next_handler(tool_call=modified):
+                    yield chunk
+
+        middleware = ObserveActingMiddleware()
+        self.mock_model.set_responses(
+            [
+                ChatResponse(
+                    content=[TextBlock(text="done")],
+                    is_last=True,
+                ),
+            ],
+        )
+
+        agent_instance = Agent(
+            name="test_agent",
+            system_prompt="test prompt",
+            model=self.mock_model,
+            toolkit=toolkit_with_tool,
+            middlewares=[middleware],
+        )
+
+        # Call _execute_tool_call with a valid tool call.
+        tool_call = ToolCallBlock(
+            id="call_1",
+            name="echo",
+            input='{"value": "ORIGINAL"}',
+        )
+        events = []
+        # pylint: disable=protected-access
+        async for evt in agent_instance._execute_tool_call(tool_call):
+            events.append(evt)
+
+        # Middleware intercepted the tool call at execution level
+        self.assertEqual(len(intercepted_tool_calls), 1)
+        self.assertIn("ORIGINAL", intercepted_tool_calls[0])
+
+        # The tool actually received the MODIFIED value
+        self.assertEqual(len(received_inputs), 1)
+        self.assertEqual(received_inputs[0], "MODIFIED")
+
+    async def test_on_model_call_middleware_modify_input(self) -> None:
+        """Test that on_model_call middleware can modify messages and model."""
+
+        class ModifyMessagesMiddleware(MiddlewareBase):
+            """Middleware that modifies messages input."""
+
+            async def on_model_call(
+                self,
+                agent: Agent,
+                input_kwargs: dict,
+                next_handler: Callable[..., Any],
+            ) -> Union[ChatResponse, AsyncGenerator[ChatResponse, None]]:
+                """Prepend a system message to the messages list."""
+                messages = input_kwargs["messages"]
+                modified_messages = [
+                    SystemMsg(
+                        name="system",
+                        content="INJECTED SYSTEM MESSAGE",
+                    ),
+                ] + messages
+
+                # Pass modified messages to next handler
+                return await next_handler(
+                    current_model=input_kwargs["current_model"],
+                    messages=modified_messages,
+                    tools=input_kwargs["tools"],
+                    tool_choice=input_kwargs["tool_choice"],
+                )
+
+        middleware = ModifyMessagesMiddleware()
+
+        # Track what messages the model receives
+        received_messages = []
+
+        class TrackingModel(MockModel):
+            """Model that tracks received messages."""
+
+            async def _call_api(
+                self,
+                *args: Any,
+                **kwargs: Any,
+            ) -> ChatResponse:
+                """Track the messages and return mock response."""
+                messages = kwargs.get("messages", [])
+                received_messages.extend(messages)
+                return await super()._call_api(*args, **kwargs)
+
+        tracking_model = TrackingModel()
+        tracking_model.set_responses(
+            [
+                ChatResponse(
+                    content=[TextBlock(text="response")],
+                    is_last=True,
+                ),
+            ],
+        )
+
+        agent_instance = Agent(
+            name="test_agent",
+            system_prompt="test prompt",
+            model=tracking_model,
+            toolkit=self.toolkit,
+            middlewares=[middleware],
+        )
+
+        await agent_instance.reply(UserMsg("user", "test message"))
+
+        # Verify the injected system message is present
+        system_messages = [m for m in received_messages if m.role == "system"]
+        self.assertTrue(
+            any(
+                "INJECTED SYSTEM MESSAGE" in m.get_text_content()
+                for m in system_messages
+            ),
+        )
+
+    async def test_on_model_call_keeps_outer_messages_when_inner_omits_kwargs(
+        self,
+    ) -> None:
+        """Transparent inner model-call middleware keeps outer messages."""
+
+        class ModifyMessagesMiddleware(MiddlewareBase):
+            """Middleware that changes the messages."""
+
+            async def on_model_call(
+                self,
+                agent: Agent,
+                input_kwargs: dict,
+                next_handler: Callable[..., Any],
+            ) -> Union[ChatResponse, AsyncGenerator[ChatResponse, None]]:
+                modified_messages = [
+                    SystemMsg(
+                        name="system",
+                        content="INJECTED SYSTEM MESSAGE",
+                    ),
+                ] + input_kwargs["messages"]
+                return await next_handler(messages=modified_messages)
+
+        class TransparentMiddleware(MiddlewareBase):
+            """Middleware that calls next_handler() without passing kwargs."""
+
+            async def on_model_call(
+                self,
+                agent: Agent,
+                input_kwargs: dict,
+                next_handler: Callable[..., Any],
+            ) -> Union[ChatResponse, AsyncGenerator[ChatResponse, None]]:
+                system_messages = [
+                    m for m in input_kwargs["messages"] if m.role == "system"
+                ]
+                assert any(
+                    "INJECTED SYSTEM MESSAGE" in m.get_text_content()
+                    for m in system_messages
+                )
+                return await next_handler()
+
+        received_messages = []
+
+        class TrackingModel(MockModel):
+            """Model that tracks received messages."""
+
+            async def _call_api(
+                self,
+                *args: Any,
+                **kwargs: Any,
+            ) -> ChatResponse:
+                received_messages.extend(kwargs.get("messages", []))
+                return await super()._call_api(*args, **kwargs)
+
+        tracking_model = TrackingModel()
+        tracking_model.set_responses(
+            [ChatResponse(content=[TextBlock(text="response")], is_last=True)],
+        )
+
+        agent_instance = Agent(
+            name="test_agent",
+            system_prompt="test prompt",
+            model=tracking_model,
+            toolkit=self.toolkit,
+            middlewares=[
+                ModifyMessagesMiddleware(),
+                TransparentMiddleware(),
+            ],
+        )
+
+        await agent_instance.reply(UserMsg("user", "test message"))
+
+        system_messages = [m for m in received_messages if m.role == "system"]
+        self.assertTrue(
+            any(
+                "INJECTED SYSTEM MESSAGE" in m.get_text_content()
+                for m in system_messages
+            ),
+        )
+
+    async def test_on_model_call_keeps_outer_messages_with_partial_kwargs(
+        self,
+    ) -> None:
+        """Partial next_handler kwargs keep outer model-call changes."""
+        injected_text = "INJECTED SYSTEM MESSAGE FROM OUTER MIDDLEWARE"
+        inner_saw_injected_message = False
+
+        class ModifyMessagesMiddleware(MiddlewareBase):
+            """Middleware that changes the messages."""
+
+            async def on_model_call(
+                self,
+                agent: Agent,
+                input_kwargs: dict,
+                next_handler: Callable[..., Any],
+            ) -> Union[ChatResponse, AsyncGenerator[ChatResponse, None]]:
+                modified_messages = [
+                    SystemMsg(
+                        name="system",
+                        content=injected_text,
+                    ),
+                ] + input_kwargs["messages"]
+                return await next_handler(messages=modified_messages)
+
+        class PartialForwardMiddleware(MiddlewareBase):
+            """Middleware that forwards only one of the current kwargs."""
+
+            async def on_model_call(
+                self,
+                agent: Agent,
+                input_kwargs: dict,
+                next_handler: Callable[..., Any],
+            ) -> Union[ChatResponse, AsyncGenerator[ChatResponse, None]]:
+                nonlocal inner_saw_injected_message
+                inner_saw_injected_message = any(
+                    injected_text in m.get_text_content()
+                    for m in input_kwargs["messages"]
+                )
+                return await next_handler(
+                    tool_choice=input_kwargs["tool_choice"],
+                )
+
+        received_messages = []
+
+        class TrackingModel(MockModel):
+            """Model that tracks received messages."""
+
+            async def _call_api(
+                self,
+                *args: Any,
+                **kwargs: Any,
+            ) -> ChatResponse:
+                received_messages.extend(kwargs.get("messages", []))
+                return await super()._call_api(*args, **kwargs)
+
+        tracking_model = TrackingModel()
+        tracking_model.set_responses(
+            [ChatResponse(content=[TextBlock(text="response")], is_last=True)],
+        )
+
+        agent_instance = Agent(
+            name="test_agent",
+            system_prompt="test prompt",
+            model=tracking_model,
+            toolkit=self.toolkit,
+            middlewares=[
+                ModifyMessagesMiddleware(),
+                PartialForwardMiddleware(),
+            ],
+        )
+
+        await agent_instance.reply(UserMsg("user", "test message"))
+
+        self.assertTrue(inner_saw_injected_message)
+        self.assertTrue(
+            any(
+                injected_text in m.get_text_content()
+                for m in received_messages
+            ),
+        )
+
+    async def test_on_compress_context_middleware(self) -> None:
+        """Test on_compress_context middleware follows the onion chain pattern.
+
+        Verifies that:
+        - Multiple middlewares are chained in onion order (mw1 wraps mw2).
+        - ``input_kwargs`` carries the correct ``context_config`` and
+          ``instructions``.
+        - The ``next_handler`` ultimately calls ``_compress_context_impl``.
+        - A middleware can short-circuit and skip the actual implementation.
+        """
+        seen_instructions = []
+
+        # ------------------------------------------------------------------ #
+        # Middleware that records pre/post and forwards to next_handler.      #
+        # ------------------------------------------------------------------ #
+        class CompressContextMiddleware(MiddlewareBase):
+            """Middleware for testing on_compress_context hook."""
+
+            def __init__(self, log: list, name: str) -> None:
+                """Initialize the compress context middleware.
+
+                Args:
+                    log (`list`):
+                        The execution log list.
+                    name (`str`):
+                        The middleware name.
+                """
+                self.log = log
+                self.name = name
+
+            async def on_compress_context(
+                self,
+                agent: Agent,
+                input_kwargs: dict,
+                next_handler: Callable[..., Any],
+            ) -> None:
+                """Forward to next handler, recording pre and post."""
+                self.log.append(f"{self.name}_pre")
+                seen_instructions.append(input_kwargs.get("instructions"))
+                await next_handler(**input_kwargs)
+                self.log.append(f"{self.name}_post")
+
+        middleware1 = CompressContextMiddleware(self.execution_log, "mw1")
+        middleware2 = CompressContextMiddleware(self.execution_log, "mw2")
+
+        self.mock_model.set_responses(
+            [
+                ChatResponse(
+                    content=[TextBlock(text="test response")],
+                    is_last=True,
+                ),
+            ],
+        )
+
+        context_config = ContextConfig(trigger_ratio=0.8, reserve_ratio=0.1)
+        agent = Agent(
+            name="test_agent",
+            system_prompt="test prompt",
+            model=self.mock_model,
+            toolkit=self.toolkit,
+            middlewares=[middleware1, middleware2],
+            context_config=context_config,
+        )
+
+        # Patch _compress_context_impl to avoid real token counting.
+        instructions = HintBlock(
+            hint="Keep user requirements while compressing.",
+            source="user",
+        )
+        with patch.object(
+            agent,
+            "_compress_context_impl",
+            new_callable=AsyncMock,
+        ) as mock_impl:
+            await agent.compress_context(
+                context_config=context_config,
+                instructions=instructions,
+            )
+
+            # _compress_context_impl must have been called exactly once.
+            mock_impl.assert_awaited_once_with(
+                context_config=context_config,
+                instructions=instructions,
+            )
+
+        # Verify onion execution order: mw1_pre -> mw2_pre -> mw2_post ->
+        # mw1_post
+        expected = ["mw1_pre", "mw2_pre", "mw2_post", "mw1_post"]
+        self.assertListEqual(self.execution_log, expected)
+        self.assertListEqual(seen_instructions, [instructions, instructions])
+
+    async def test_on_compress_context_middleware_modify_instructions(
+        self,
+    ) -> None:
+        """Test that middleware can replace compress_context instructions."""
+
+        class ReplaceInstructionsMiddleware(MiddlewareBase):
+            """Middleware that replaces the compression instructions."""
+
+            def __init__(self, replacement: HintBlock) -> None:
+                """Initialize the middleware with replacement instructions."""
+                self.replacement = replacement
+
+            async def on_compress_context(
+                self,
+                agent: Agent,
+                input_kwargs: dict,
+                next_handler: Callable[..., Any],
+            ) -> None:
+                """Replace instructions before forwarding."""
+                input_kwargs["instructions"] = self.replacement
+                await next_handler(**input_kwargs)
+
+        original = HintBlock(
+            hint="Keep all requirements.",
+            source="user",
+        )
+        replacement = HintBlock(
+            hint="Keep only unresolved requirements.",
+            source="middleware",
+        )
+        context_config = ContextConfig(trigger_ratio=0.8, reserve_ratio=0.1)
+        agent = Agent(
+            name="test_agent",
+            system_prompt="test prompt",
+            model=self.mock_model,
+            toolkit=self.toolkit,
+            middlewares=[ReplaceInstructionsMiddleware(replacement)],
+            context_config=context_config,
+        )
+
+        with patch.object(
+            agent,
+            "_compress_context_impl",
+            new_callable=AsyncMock,
+        ) as mock_impl:
+            await agent.compress_context(
+                context_config=context_config,
+                instructions=original,
+            )
+
+            mock_impl.assert_awaited_once_with(
+                context_config=context_config,
+                instructions=replacement,
+            )
+
+    async def test_on_compress_context_middleware_short_circuit(
+        self,
+    ) -> None:
+        """Test that a middleware can skip _compress_context_impl entirely."""
+
+        class SkipCompressMiddleware(MiddlewareBase):
+            """Middleware that skips the actual compress_context call."""
+
+            def __init__(self, log: list) -> None:
+                """Initialize the skip compress middleware.
+
+                Args:
+                    log (`list`):
+                        The execution log list.
+                """
+                self.log = log
+
+            async def on_compress_context(
+                self,
+                agent: Agent,
+                input_kwargs: dict,
+                next_handler: Callable[..., Any],
+            ) -> None:
+                """Record the call and skip forwarding to next_handler."""
+                self.log.append("skipped")
+                # Intentionally NOT calling next_handler.
+
+        middleware = SkipCompressMiddleware(self.execution_log)
+
+        self.mock_model.set_responses(
+            [
+                ChatResponse(
+                    content=[TextBlock(text="test response")],
+                    is_last=True,
+                ),
+            ],
+        )
+
+        agent = Agent(
+            name="test_agent",
+            system_prompt="test prompt",
+            model=self.mock_model,
+            toolkit=self.toolkit,
+            middlewares=[middleware],
+        )
+
+        with patch.object(
+            agent,
+            "_compress_context_impl",
+            new_callable=AsyncMock,
+        ) as mock_impl:
+            await agent.compress_context()
+
+            # _compress_context_impl should NOT have been called.
+            mock_impl.assert_not_awaited()
+
+        self.assertListEqual(self.execution_log, ["skipped"])
+
+    async def test_on_compress_context_no_middleware(self) -> None:
+        """Test that compress_context calls _compress_context_impl directly
+        when no middleware is registered."""
+
+        self.mock_model.set_responses(
+            [
+                ChatResponse(
+                    content=[TextBlock(text="test response")],
+                    is_last=True,
+                ),
+            ],
+        )
+
+        context_config = ContextConfig(trigger_ratio=0.8, reserve_ratio=0.1)
+        agent = Agent(
+            name="test_agent",
+            system_prompt="test prompt",
+            model=self.mock_model,
+            toolkit=self.toolkit,
+            # No middlewares registered.
+            context_config=context_config,
+        )
+
+        with patch.object(
+            agent,
+            "_compress_context_impl",
+            new_callable=AsyncMock,
+        ) as mock_impl:
+            await agent.compress_context(context_config=context_config)
+            mock_impl.assert_awaited_once_with(
+                context_config=context_config,
+                instructions=None,
+            )
+
+    async def asyncTearDown(self) -> None:
+        """Clean up test fixtures."""
+        self.execution_log.clear()
diff --git a/tests/model_anthropic_test.py b/tests/model_anthropic_test.py
new file mode 100644
index 0000000..0ebde9a
--- /dev/null
+++ b/tests/model_anthropic_test.py
@@ -0,0 +1,550 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Unit tests for AnthropicChatModel with mocked API responses.
+
+Tests cover both non-streaming and streaming modes.
+Anthropic uses event-based streaming (message_start, content_block_start,
+content_block_delta, message_delta events).
+"""
+import json
+from typing import Any
+import unittest
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import AsyncMock, MagicMock, patch
+
+from utils import AnyString
+
+from agentscope.message import TextBlock, ToolCallBlock, ThinkingBlock
+from agentscope.model import AnthropicChatModel
+from agentscope.credential import AnthropicCredential
+from agentscope.tool import ToolChoice
+
+A = AnyString()
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_model(stream: bool = False) -> Any:
+    return AnthropicChatModel(
+        credential=AnthropicCredential(api_key="test"),
+        model="claude-opus-4-5",
+        stream=stream,
+        context_size=200_000,
+    )
+
+
+def _mock_completion(
+    text: Any = None,
+    tool_calls: Any = None,
+    thinking: Any = None,
+    response_id: str = "msg-1",
+) -> MagicMock:
+    """Build a mock non-streaming Anthropic Message response."""
+    blocks = []
+    if thinking:
+        b = MagicMock()
+        b.type = "thinking"
+        b.thinking = thinking
+        b.signature = "sig123"
+        blocks.append(b)
+    if text:
+        b = MagicMock()
+        b.type = "text"
+        b.text = text
+        blocks.append(b)
+    if tool_calls:
+        for tc in tool_calls:
+            b = MagicMock()
+            b.type = "tool_use"
+            b.id = tc["id"]
+            b.name = tc["name"]
+            b.input = tc["input"]
+            blocks.append(b)
+
+    resp = MagicMock()
+    resp.id = response_id
+    resp.content = blocks
+    resp.usage = MagicMock()
+    resp.usage.input_tokens = 10
+    resp.usage.output_tokens = 5
+    resp.usage.cache_creation_input_tokens = 0
+    resp.usage.cache_read_input_tokens = 0
+    return resp
+
+
+def _make_event(event_type: str, **kwargs: Any) -> MagicMock:
+    """Build a mock Anthropic streaming event."""
+    event = MagicMock()
+    event.type = event_type
+    for key, val in kwargs.items():
+        setattr(event, key, val)
+    return event
+
+
+class _MockAsyncEventStream:
+    """Mock async iterator over Anthropic events."""
+
+    def __init__(self, events: list) -> None:
+        self._events = events
+        self._index = 0
+
+    def __aiter__(self) -> "_MockAsyncEventStream":
+        return self
+
+    async def __anext__(self) -> Any:
+        if self._index >= len(self._events):
+            raise StopAsyncIteration
+        event = self._events[self._index]
+        self._index += 1
+        return event
+
+
+# ---------------------------------------------------------------------------
+# Non-streaming tests
+# ---------------------------------------------------------------------------
+
+
+class TestAnthropicNonStream(IsolatedAsyncioTestCase):
+    """Tests for AnthropicChatModel in non-streaming mode."""
+
+    def setUp(self) -> None:
+        self.model = _make_model(stream=False)
+
+    @patch("anthropic.AsyncAnthropic")
+    async def test_text_response(self, mock_client_cls: MagicMock) -> None:
+        """Non-stream text response returns a single ChatResponse."""
+        mock_create = AsyncMock(
+            return_value=_mock_completion(text="Hello!"),
+        )
+        mock_client_cls.return_value.messages.create = mock_create
+
+        result = await self.model([])
+
+        self.assertEqual(
+            (result.is_last, result.content),
+            (True, [TextBlock.model_construct(id=A, text="Hello!")]),
+        )
+        self.assertEqual(result.id, "msg-1")
+
+    @patch("anthropic.AsyncAnthropic")
+    async def test_tool_call_response(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Non-stream tool call response creates ToolCallBlocks."""
+        mock_create = AsyncMock(
+            return_value=_mock_completion(
+                tool_calls=[
+                    {
+                        "id": "toolu_1",
+                        "name": "get_weather",
+                        "input": {"city": "Beijing"},
+                    },
+                ],
+            ),
+        )
+        mock_client_cls.return_value.messages.create = mock_create
+
+        result = await self.model([])
+
+        self.assertEqual(
+            (result.is_last, result.content),
+            (
+                True,
+                [
+                    ToolCallBlock(
+                        id="toolu_1",
+                        name="get_weather",
+                        input=json.dumps({"city": "Beijing"}),
+                    ),
+                ],
+            ),
+        )
+
+    @patch("anthropic.AsyncAnthropic")
+    async def test_thinking_response(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Non-stream response with reasoning creates ThinkingBlock."""
+        mock_create = AsyncMock(
+            return_value=_mock_completion(
+                thinking="Deep thought...",
+                text="Answer",
+            ),
+        )
+        mock_client_cls.return_value.messages.create = mock_create
+
+        result = await self.model([])
+
+        self.assertEqual(
+            (result.is_last, result.content),
+            (
+                True,
+                [
+                    ThinkingBlock.model_construct(
+                        id=A,
+                        thinking="Deep thought...",
+                        signature="sig123",
+                    ),
+                    TextBlock.model_construct(id=A, text="Answer"),
+                ],
+            ),
+        )
+
+
+# ---------------------------------------------------------------------------
+# Streaming tests
+# ---------------------------------------------------------------------------
+
+
+class TestAnthropicStream(IsolatedAsyncioTestCase):
+    """Tests for AnthropicChatModel in streaming mode."""
+
+    def setUp(self) -> None:
+        self.model = _make_model(stream=True)
+
+    @patch("anthropic.AsyncAnthropic")
+    async def test_stream_text(self, mock_client_cls: MagicMock) -> None:
+        """Stream text yields n deltas + 1 final with full content."""
+        msg_usage = MagicMock()
+        msg_usage.input_tokens = 10
+        msg_usage.output_tokens = 0
+        msg_usage.cache_creation_input_tokens = 0
+        msg_usage.cache_read_input_tokens = 0
+
+        message = MagicMock()
+        message.id = "msg-1"
+        message.usage = msg_usage
+
+        delta1 = MagicMock()
+        delta1.type = "text_delta"
+        delta1.text = "Hello"
+
+        delta2 = MagicMock()
+        delta2.type = "text_delta"
+        delta2.text = " world"
+
+        msg_delta_usage = MagicMock()
+        msg_delta_usage.output_tokens = 5
+
+        events = [
+            _make_event("message_start", message=message),
+            _make_event("content_block_delta", index=0, delta=delta1),
+            _make_event("content_block_delta", index=0, delta=delta2),
+            _make_event(
+                "message_delta",
+                usage=msg_delta_usage,
+            ),
+        ]
+        mock_create = AsyncMock(
+            return_value=_MockAsyncEventStream(events),
+        )
+        mock_client_cls.return_value.messages.create = mock_create
+
+        gen = await self.model([])
+        responses = [r async for r in gen]
+
+        self.assertListEqual(
+            [(r.is_last, r.content) for r in responses],
+            [
+                (False, [TextBlock.model_construct(id=A, text="Hello")]),
+                (False, [TextBlock.model_construct(id=A, text=" world")]),
+                (True, [TextBlock.model_construct(id=A, text="Hello world")]),
+            ],
+        )
+        self.assertEqual(responses[-1].id, "msg-1")
+
+    @patch("anthropic.AsyncAnthropic")
+    async def test_stream_thinking_and_text(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Stream thinking + text yields deltas then final with signature."""
+        msg_usage = MagicMock()
+        msg_usage.input_tokens = 10
+        msg_usage.output_tokens = 0
+        msg_usage.cache_creation_input_tokens = 0
+        msg_usage.cache_read_input_tokens = 0
+
+        message = MagicMock()
+        message.id = "msg-2"
+        message.usage = msg_usage
+
+        thinking_delta = MagicMock()
+        thinking_delta.type = "thinking_delta"
+        thinking_delta.thinking = "Let me think"
+
+        sig_delta = MagicMock()
+        sig_delta.type = "signature_delta"
+        sig_delta.signature = "sig_abc"
+
+        text_delta = MagicMock()
+        text_delta.type = "text_delta"
+        text_delta.text = "Result"
+
+        events = [
+            _make_event("message_start", message=message),
+            _make_event("content_block_delta", index=0, delta=thinking_delta),
+            _make_event("content_block_delta", index=0, delta=sig_delta),
+            _make_event("content_block_delta", index=1, delta=text_delta),
+        ]
+        mock_create = AsyncMock(
+            return_value=_MockAsyncEventStream(events),
+        )
+        mock_client_cls.return_value.messages.create = mock_create
+
+        gen = await self.model([])
+        responses = [r async for r in gen]
+
+        self.assertListEqual(
+            [(r.is_last, r.content) for r in responses],
+            [
+                (
+                    False,
+                    [
+                        ThinkingBlock.model_construct(
+                            id=A,
+                            thinking="Let me think",
+                        ),
+                    ],
+                ),
+                # ``signature_delta`` is emitted as its own delta chunk
+                # carrying the signature but no additional thinking text.
+                (
+                    False,
+                    [
+                        ThinkingBlock.model_construct(
+                            id=A,
+                            thinking="",
+                            signature="sig_abc",
+                        ),
+                    ],
+                ),
+                (False, [TextBlock.model_construct(id=A, text="Result")]),
+                (
+                    True,
+                    [
+                        ThinkingBlock.model_construct(
+                            id=A,
+                            thinking="Let me think",
+                            signature="sig_abc",
+                        ),
+                        TextBlock.model_construct(id=A, text="Result"),
+                    ],
+                ),
+            ],
+        )
+
+    @patch("anthropic.AsyncAnthropic")
+    async def test_stream_tool_call(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Stream tool call yields partial deltas then full accumulated
+        input."""
+        msg_usage = MagicMock()
+        msg_usage.input_tokens = 10
+        msg_usage.output_tokens = 0
+        msg_usage.cache_creation_input_tokens = 0
+        msg_usage.cache_read_input_tokens = 0
+
+        message = MagicMock()
+        message.id = "msg-3"
+        message.usage = msg_usage
+
+        tool_block = MagicMock()
+        tool_block.type = "tool_use"
+        tool_block.id = "toolu_1"
+        tool_block.name = "get_weather"
+
+        json_delta1 = MagicMock()
+        json_delta1.type = "input_json_delta"
+        json_delta1.partial_json = '{"city":'
+
+        json_delta2 = MagicMock()
+        json_delta2.type = "input_json_delta"
+        json_delta2.partial_json = '"BJ"}'
+
+        events = [
+            _make_event("message_start", message=message),
+            _make_event(
+                "content_block_start",
+                index=0,
+                content_block=tool_block,
+            ),
+            _make_event("content_block_delta", index=0, delta=json_delta1),
+            _make_event("content_block_delta", index=0, delta=json_delta2),
+        ]
+        mock_create = AsyncMock(
+            return_value=_MockAsyncEventStream(events),
+        )
+        mock_client_cls.return_value.messages.create = mock_create
+
+        gen = await self.model([])
+        responses = [r async for r in gen]
+
+        self.assertListEqual(
+            [(r.is_last, r.content) for r in responses],
+            [
+                # Anthropic emits a ``content_block_start`` event before the
+                # first delta, which surfaces as an initial empty-input
+                # ``ToolCallBlock`` delta.
+                (
+                    False,
+                    [
+                        ToolCallBlock(
+                            id="toolu_1",
+                            name="get_weather",
+                            input="",
+                        ),
+                    ],
+                ),
+                (
+                    False,
+                    [
+                        ToolCallBlock(
+                            id="toolu_1",
+                            name="get_weather",
+                            input='{"city":',
+                        ),
+                    ],
+                ),
+                (
+                    False,
+                    [
+                        ToolCallBlock(
+                            id="toolu_1",
+                            name="get_weather",
+                            input='"BJ"}',
+                        ),
+                    ],
+                ),
+                (
+                    True,
+                    [
+                        ToolCallBlock(
+                            id="toolu_1",
+                            name="get_weather",
+                            input='{"city":"BJ"}',
+                        ),
+                    ],
+                ),
+            ],
+        )
+
+
+# ---------------------------------------------------------------------------
+# _format_tools tests
+# ---------------------------------------------------------------------------
+
+_FT_TOOLS = [
+    {
+        "type": "function",
+        "function": {
+            "name": "get_weather",
+            "description": "Get the weather",
+            "parameters": {
+                "type": "object",
+                "properties": {"city": {"type": "string"}},
+                "required": ["city"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "get_time",
+            "description": "Get the time",
+            "parameters": {
+                "type": "object",
+                "properties": {"timezone": {"type": "string"}},
+                "required": ["timezone"],
+            },
+        },
+    },
+]
+
+_FT_TOOLS_ANTHROPIC = [
+    {
+        "name": "get_weather",
+        "description": "Get the weather",
+        "input_schema": {
+            "type": "object",
+            "properties": {"city": {"type": "string"}},
+            "required": ["city"],
+        },
+    },
+    {
+        "name": "get_time",
+        "description": "Get the time",
+        "input_schema": {
+            "type": "object",
+            "properties": {"timezone": {"type": "string"}},
+            "required": ["timezone"],
+        },
+    },
+]
+
+
+class TestAnthropicFormatTools(unittest.TestCase):
+    """Tests for AnthropicChatModel._format_tools."""
+
+    def setUp(self) -> None:
+        """Set up model instance."""
+        self.model = _make_model()
+
+    def test_auto_mode(self) -> None:
+        """Auto mode returns converted tools and type=auto."""
+        fmt_tools, fmt_choice = self.model._format_tools(
+            _FT_TOOLS,
+            ToolChoice(mode="auto"),
+        )
+        self.assertEqual(fmt_tools, _FT_TOOLS_ANTHROPIC)
+        self.assertEqual(fmt_choice, {"type": "auto"})
+
+    def test_none_mode(self) -> None:
+        """None mode returns converted tools and type=none."""
+        fmt_tools, fmt_choice = self.model._format_tools(
+            _FT_TOOLS,
+            ToolChoice(mode="none"),
+        )
+        self.assertEqual(fmt_tools, _FT_TOOLS_ANTHROPIC)
+        self.assertEqual(fmt_choice, {"type": "none"})
+
+    def test_required_mode(self) -> None:
+        """Required mode maps to type=any."""
+        fmt_tools, fmt_choice = self.model._format_tools(
+            _FT_TOOLS,
+            ToolChoice(mode="required"),
+        )
+        self.assertEqual(fmt_tools, _FT_TOOLS_ANTHROPIC)
+        self.assertEqual(fmt_choice, {"type": "any"})
+
+    def test_str_mode_force_call(self) -> None:
+        """A specific tool name forces that tool call."""
+        fmt_tools, fmt_choice = self.model._format_tools(
+            _FT_TOOLS,
+            ToolChoice(mode="get_weather"),
+        )
+        self.assertEqual(fmt_tools, _FT_TOOLS_ANTHROPIC)
+        self.assertEqual(fmt_choice, {"type": "tool", "name": "get_weather"})
+
+    def test_tools_filtered(self) -> None:
+        """When tool_choice.tools is set, only those tools are included."""
+        fmt_tools, fmt_choice = self.model._format_tools(
+            _FT_TOOLS,
+            ToolChoice(mode="auto", tools=["get_weather"]),
+        )
+        self.assertEqual(len(fmt_tools), 1)
+        self.assertEqual(fmt_tools[0]["name"], "get_weather")
+        self.assertEqual(fmt_choice, {"type": "auto"})
+
+    def test_no_tool_choice(self) -> None:
+        """Without tool_choice, returns converted tools and None."""
+        fmt_tools, fmt_choice = self.model._format_tools(_FT_TOOLS, None)
+        self.assertEqual(fmt_tools, _FT_TOOLS_ANTHROPIC)
+        self.assertIsNone(fmt_choice)
diff --git a/tests/model_base_test.py b/tests/model_base_test.py
new file mode 100644
index 0000000..db93734
--- /dev/null
+++ b/tests/model_base_test.py
@@ -0,0 +1,469 @@
+# -*- coding: utf-8 -*-
+"""Unit tests for :class:`agentscope.model.ChatModelBase.__call__` — the
+retry / accumulation / interrupt wrapper around ``_call_api``."""
+import asyncio
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from utils import AnyString, MockModel
+
+from agentscope.message import TextBlock, ThinkingBlock, ToolCallBlock, UserMsg
+from agentscope.model import ChatResponse, FinishedReason
+
+
+def _dump(chat_response: ChatResponse) -> dict:
+    """Normalize a ``ChatResponse`` (a ``dict``-subclass with pydantic
+    blocks inside) into a plain dict suitable for
+    ``assertDictEqual`` / ``assertListEqual`` comparison."""
+    d = dict(chat_response)
+    d["content"] = [b.model_dump(mode="json") for b in d["content"]]
+    if d["usage"] is not None:
+        d["usage"] = dict(d["usage"])
+    return d
+
+
+def _expected(
+    content: list,
+    is_last: bool,
+    finished_reason: FinishedReason = FinishedReason.COMPLETED,
+    usage: dict | None = None,
+) -> dict:
+    """Build the expected serialized ``ChatResponse`` dict, with
+    ``AnyString`` placeholders for auto-generated fields (id,
+    created_at)."""
+    return {
+        "content": content,
+        "is_last": is_last,
+        "id": AnyString(),
+        "created_at": AnyString(),
+        "type": "chat_response",
+        "usage": usage,
+        "finished_reason": finished_reason,
+        "metadata": {},
+    }
+
+
+class ChatModelBaseCallTest(IsolatedAsyncioTestCase):
+    """Test ``ChatModelBase.__call__`` end-to-end with a ``MockModel``.
+
+    Covers the four scenarios that ``__call__`` must handle:
+
+    1. Non-stream success — the underlying ``ChatResponse`` is returned
+       verbatim.
+    2. Non-stream ``CancelledError`` raised from inside ``_call_api`` —
+       converted to a ``ChatResponse`` with
+       ``finished_reason=INTERRUPTED``.
+    3. Stream success — every delta is forwarded, followed by an
+       accumulated final ``ChatResponse`` with ``is_last=True`` and
+       ``finished_reason=COMPLETED``.
+    4. Stream ``CancelledError`` raised while consuming the underlying
+       async generator — deltas produced so far are forwarded, followed
+       by an accumulated final ``ChatResponse`` with
+       ``finished_reason=INTERRUPTED``.
+    """
+
+    async def asyncSetUp(self) -> None:
+        """The async setup method."""
+        self.model = MockModel(model="mock-model")
+        self.messages = [UserMsg(name="user", content="hi")]
+
+    # ------------------------------------------------------------------
+    # 1) non-stream success
+    # ------------------------------------------------------------------
+    async def test_non_stream_success(self) -> None:
+        """Non-stream ``_call_api`` returns a ``ChatResponse``; the base
+        class must return it unchanged."""
+        response = ChatResponse(
+            content=[TextBlock(text="hello", id="t1")],
+            is_last=True,
+        )
+        self.model.set_responses([response])
+
+        result = await self.model(messages=self.messages)
+
+        self.assertIsInstance(result, ChatResponse)
+        self.assertDictEqual(
+            _dump(result),
+            _expected(
+                content=[
+                    {"type": "text", "text": "hello", "id": "t1"},
+                ],
+                is_last=True,
+            ),
+        )
+
+    # ------------------------------------------------------------------
+    # 2) non-stream CancelledError raised from inside _call_api
+    # ------------------------------------------------------------------
+    async def test_non_stream_cancelled_error(self) -> None:
+        """``CancelledError`` raised from inside a non-stream
+        ``_call_api`` is translated into an empty ``ChatResponse`` with
+        ``finished_reason=INTERRUPTED``."""
+        self.model.set_responses([asyncio.CancelledError()])
+
+        result = await self.model(messages=self.messages)
+
+        self.assertIsInstance(result, ChatResponse)
+        self.assertDictEqual(
+            _dump(result),
+            _expected(
+                content=[],
+                is_last=True,
+                finished_reason=FinishedReason.INTERRUPTED,
+            ),
+        )
+
+    # ------------------------------------------------------------------
+    # 3) stream success
+    # ------------------------------------------------------------------
+    async def test_stream_success_with_final_accumulation(self) -> None:
+        """A well-behaved stream of deltas is forwarded chunk-by-chunk;
+        the base class appends a final accumulated ``ChatResponse``
+        with ``is_last=True``."""
+        deltas = [
+            ChatResponse(
+                content=[TextBlock(text="hello", id="t1")],
+                is_last=False,
+                id="chunk-1",
+            ),
+            ChatResponse(
+                content=[TextBlock(text=" world", id="t1")],
+                is_last=False,
+                id="chunk-2",
+            ),
+        ]
+        self.model.set_responses([deltas])
+
+        gen = await self.model(messages=self.messages)
+        collected = [_dump(c) async for c in gen]
+
+        self.assertListEqual(
+            collected,
+            [
+                # delta 1 — passed through verbatim
+                _expected(
+                    content=[
+                        {"type": "text", "text": "hello", "id": "t1"},
+                    ],
+                    is_last=False,
+                ),
+                # delta 2 — passed through verbatim
+                _expected(
+                    content=[
+                        {"type": "text", "text": " world", "id": "t1"},
+                    ],
+                    is_last=False,
+                ),
+                # accumulated final — synthesised by ChatModelBase
+                _expected(
+                    content=[
+                        {
+                            "type": "text",
+                            "text": "hello world",
+                            "id": "t1",
+                        },
+                    ],
+                    is_last=True,
+                    finished_reason=FinishedReason.COMPLETED,
+                ),
+            ],
+        )
+
+    # ------------------------------------------------------------------
+    # 4) stream CancelledError raised while consuming the generator
+    # ------------------------------------------------------------------
+    async def test_stream_cancelled_error_mid_consumption(self) -> None:
+        """``CancelledError`` raised mid-stream is caught inside the
+        base class's ``_stream`` wrapper. Deltas produced before the
+        cancellation are still forwarded, and a final accumulated
+        ``ChatResponse`` with ``finished_reason=INTERRUPTED`` is
+        appended."""
+        deltas = [
+            ChatResponse(
+                content=[TextBlock(text="hello", id="t1")],
+                is_last=False,
+                id="chunk-1",
+            ),
+            asyncio.CancelledError(),
+            # anything after the exception must not be reached
+            ChatResponse(
+                content=[TextBlock(text=" world", id="t1")],
+                is_last=False,
+                id="chunk-2",
+            ),
+        ]
+        self.model.set_responses([deltas])
+
+        gen = await self.model(messages=self.messages)
+        collected = [_dump(c) async for c in gen]
+
+        self.assertListEqual(
+            collected,
+            [
+                # the one delta yielded before the cancellation
+                _expected(
+                    content=[
+                        {"type": "text", "text": "hello", "id": "t1"},
+                    ],
+                    is_last=False,
+                ),
+                # accumulated final with INTERRUPTED — content reflects
+                # only the deltas received before the cancellation
+                _expected(
+                    content=[
+                        {"type": "text", "text": "hello", "id": "t1"},
+                    ],
+                    is_last=True,
+                    finished_reason=FinishedReason.INTERRUPTED,
+                ),
+            ],
+        )
+
+    # ------------------------------------------------------------------
+    # 5) stream CancelledError — thinking + text content interrupted
+    # ------------------------------------------------------------------
+    async def test_stream_cancelled_error_with_thinking_and_text(
+        self,
+    ) -> None:
+        """Same as (4) but the underlying stream produces multiple
+        ``ThinkingBlock`` and ``TextBlock`` deltas (across the same
+        block ids) before the cancellation. The accumulated final
+        response must merge the deltas by block id in their original
+        order."""
+        deltas = [
+            # thinking (part 1)
+            ChatResponse(
+                content=[
+                    ThinkingBlock(thinking="let me ", id="think-1"),
+                ],
+                is_last=False,
+                id="chunk-1",
+            ),
+            # thinking (part 2, same block-id, plus signature)
+            ChatResponse(
+                content=[
+                    ThinkingBlock(thinking="think...", id="think-1"),
+                ],
+                is_last=False,
+                id="chunk-2",
+            ),
+            # text (part 1, new block-id)
+            ChatResponse(
+                content=[TextBlock(text="hello", id="text-1")],
+                is_last=False,
+                id="chunk-3",
+            ),
+            asyncio.CancelledError(),
+            # unreachable
+            ChatResponse(
+                content=[TextBlock(text=" world", id="text-1")],
+                is_last=False,
+                id="chunk-4",
+            ),
+        ]
+        self.model.set_responses([deltas])
+
+        gen = await self.model(messages=self.messages)
+        collected = [_dump(c) async for c in gen]
+
+        self.assertListEqual(
+            collected,
+            [
+                _expected(
+                    content=[
+                        {
+                            "type": "thinking",
+                            "thinking": "let me ",
+                            "id": "think-1",
+                        },
+                    ],
+                    is_last=False,
+                ),
+                _expected(
+                    content=[
+                        {
+                            "type": "thinking",
+                            "thinking": "think...",
+                            "id": "think-1",
+                        },
+                    ],
+                    is_last=False,
+                ),
+                _expected(
+                    content=[
+                        {"type": "text", "text": "hello", "id": "text-1"},
+                    ],
+                    is_last=False,
+                ),
+                # accumulated final — thinking merged, text merged, no
+                # trailing " world" (it came after the cancellation)
+                _expected(
+                    content=[
+                        {
+                            "type": "thinking",
+                            "thinking": "let me think...",
+                            "id": "think-1",
+                        },
+                        {
+                            "type": "text",
+                            "text": "hello",
+                            "id": "text-1",
+                        },
+                    ],
+                    is_last=True,
+                    finished_reason=FinishedReason.INTERRUPTED,
+                ),
+            ],
+        )
+
+    # ------------------------------------------------------------------
+    # 6) stream CancelledError — thinking + text + tool_call interrupted
+    # ------------------------------------------------------------------
+    async def test_stream_cancelled_error_with_thinking_text_tool_call(
+        self,
+    ) -> None:
+        """Same as (5) but the stream also produces a
+        ``ToolCallBlock`` whose ``input`` string is streamed across
+        multiple deltas. The cancellation happens after the partial
+        tool_call input; the accumulated final response must contain
+        the tool_call with the concatenated ``input`` received so far."""
+        deltas = [
+            # thinking
+            ChatResponse(
+                content=[
+                    ThinkingBlock(thinking="planning...", id="think-1"),
+                ],
+                is_last=False,
+                id="chunk-1",
+            ),
+            # text
+            ChatResponse(
+                content=[
+                    TextBlock(text="calling tool", id="text-1"),
+                ],
+                is_last=False,
+                id="chunk-2",
+            ),
+            # tool_call (part 1: name + partial input)
+            ChatResponse(
+                content=[
+                    ToolCallBlock(
+                        id="tool-1",
+                        name="get_weather",
+                        input='{"city":"',
+                    ),
+                ],
+                is_last=False,
+                id="chunk-3",
+            ),
+            # tool_call (part 2: input continuation, same block-id)
+            ChatResponse(
+                content=[
+                    ToolCallBlock(
+                        id="tool-1",
+                        name="get_weather",
+                        input='Beijing"',
+                    ),
+                ],
+                is_last=False,
+                id="chunk-4",
+            ),
+            asyncio.CancelledError(),
+            # unreachable — the closing "}" never arrives
+            ChatResponse(
+                content=[
+                    ToolCallBlock(
+                        id="tool-1",
+                        name="get_weather",
+                        input="}",
+                    ),
+                ],
+                is_last=False,
+                id="chunk-5",
+            ),
+        ]
+        self.model.set_responses([deltas])
+
+        gen = await self.model(messages=self.messages)
+        collected = [_dump(c) async for c in gen]
+
+        self.assertListEqual(
+            collected,
+            [
+                _expected(
+                    content=[
+                        {
+                            "type": "thinking",
+                            "thinking": "planning...",
+                            "id": "think-1",
+                        },
+                    ],
+                    is_last=False,
+                ),
+                _expected(
+                    content=[
+                        {
+                            "type": "text",
+                            "text": "calling tool",
+                            "id": "text-1",
+                        },
+                    ],
+                    is_last=False,
+                ),
+                _expected(
+                    content=[
+                        {
+                            "type": "tool_call",
+                            "id": "tool-1",
+                            "name": "get_weather",
+                            "input": '{"city":"',
+                            "state": "pending",
+                            "suggested_rules": [],
+                        },
+                    ],
+                    is_last=False,
+                ),
+                _expected(
+                    content=[
+                        {
+                            "type": "tool_call",
+                            "id": "tool-1",
+                            "name": "get_weather",
+                            "input": 'Beijing"',
+                            "state": "pending",
+                            "suggested_rules": [],
+                        },
+                    ],
+                    is_last=False,
+                ),
+                # accumulated final — thinking / text preserved,
+                # tool_call.input concatenated to the partial JSON
+                # received before the cancellation (no closing "}")
+                _expected(
+                    content=[
+                        {
+                            "type": "thinking",
+                            "thinking": "planning...",
+                            "id": "think-1",
+                        },
+                        {
+                            "type": "text",
+                            "text": "calling tool",
+                            "id": "text-1",
+                        },
+                        {
+                            "type": "tool_call",
+                            "id": "tool-1",
+                            "name": "get_weather",
+                            "input": '{"city":"Beijing"',
+                            "state": "pending",
+                            "suggested_rules": [],
+                        },
+                    ],
+                    is_last=True,
+                    finished_reason=FinishedReason.INTERRUPTED,
+                ),
+            ],
+        )
+
+    async def asyncTearDown(self) -> None:
+        """The async teardown method."""
diff --git a/tests/model_count_tokens_test.py b/tests/model_count_tokens_test.py
new file mode 100644
index 0000000..c64ae67
--- /dev/null
+++ b/tests/model_count_tokens_test.py
@@ -0,0 +1,84 @@
+# -*- coding: utf-8 -*-
+"""Tests for the fallback chat model token estimation."""
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from utils import MockModel
+
+from agentscope.message import (
+    Base64Source,
+    DataBlock,
+    TextBlock,
+    URLSource,
+    UserMsg,
+)
+
+
+class ModelCountTokensTest(IsolatedAsyncioTestCase):
+    """Test the base chat model token estimation behavior."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up a mock model that uses ChatModelBase.count_tokens."""
+        self.model = MockModel()
+
+    async def test_data_blocks_use_flat_multimodal_estimate(self) -> None:
+        """Large base64 payloads are not counted as prompt text."""
+        data = "a" * 400_000
+        tokens = await self.model.count_tokens(
+            [
+                UserMsg(
+                    name="user",
+                    content=[
+                        TextBlock(text="hi"),
+                        DataBlock(
+                            source=Base64Source(
+                                data=data,
+                                media_type="image/png",
+                            ),
+                        ),
+                    ],
+                ),
+            ],
+            None,
+        )
+
+        self.assertEqual(tokens, 2001)
+
+    async def test_base64_and_url_data_blocks_have_same_estimate(self) -> None:
+        """The same data block should not differ by source representation."""
+        base64_tokens = await self.model.count_tokens(
+            [
+                UserMsg(
+                    name="user",
+                    content=[
+                        DataBlock(
+                            source=Base64Source(
+                                data="a" * 400_000,
+                                media_type="image/png",
+                            ),
+                        ),
+                    ],
+                ),
+            ],
+            None,
+        )
+        # The file does not need to exist; token estimation must not read
+        # URLSource payloads.
+        url_tokens = await self.model.count_tokens(
+            [
+                UserMsg(
+                    name="user",
+                    content=[
+                        DataBlock(
+                            source=URLSource(
+                                url="file:///tmp/image.png",
+                                media_type="image/png",
+                            ),
+                        ),
+                    ],
+                ),
+            ],
+            None,
+        )
+
+        self.assertEqual(base64_tokens, 2000)
+        self.assertEqual(url_tokens, 2000)
diff --git a/tests/model_dashscope_test.py b/tests/model_dashscope_test.py
new file mode 100644
index 0000000..f4ebc68
--- /dev/null
+++ b/tests/model_dashscope_test.py
@@ -0,0 +1,589 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Unit tests for DashScopeChatModel with mocked API responses.
+
+Tests cover both non-streaming and streaming modes.
+"""
+import base64
+import io
+import wave
+from typing import Any
+import unittest
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import AsyncMock, MagicMock, patch
+
+from utils import AnyString
+
+from agentscope.message import (
+    TextBlock,
+    ToolCallBlock,
+    ThinkingBlock,
+    DataBlock,
+)
+from agentscope.model import DashScopeChatModel
+from agentscope.credential import DashScopeCredential
+from agentscope.tool import ToolChoice
+
+A = AnyString()
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_model(stream: bool = False) -> Any:
+    return DashScopeChatModel(
+        credential=DashScopeCredential(api_key="test"),
+        model="qwen3-max",
+        stream=stream,
+        max_retries=3,
+        context_size=131_072,
+        parameters=DashScopeChatModel.Parameters(
+            max_tokens=1000,
+            thinking_enable=True,
+            thinking_budget=100,
+        ),
+    )
+
+
+def _mock_completion(
+    text: Any = None,
+    tool_calls: Any = None,
+    reasoning: Any = None,
+    response_id: str = "req-1",
+) -> MagicMock:
+    """Build a mock non-streaming ChatCompletion response."""
+    msg = MagicMock()
+    msg.content = text
+    msg.reasoning_content = reasoning
+    msg.tool_calls = None
+
+    if tool_calls:
+        tc_mocks = []
+        for tc in tool_calls:
+            m = MagicMock()
+            m.id = tc["id"]
+            m.function.name = tc["name"]
+            m.function.arguments = tc["arguments"]
+            tc_mocks.append(m)
+        msg.tool_calls = tc_mocks
+
+    choice = MagicMock()
+    choice.message = msg
+
+    resp = MagicMock()
+    resp.id = response_id
+    resp.choices = [choice]
+    resp.usage = MagicMock()
+    resp.usage.prompt_tokens = 10
+    resp.usage.completion_tokens = 5
+    resp.usage.prompt_tokens_details = None
+    return resp
+
+
+def _make_stream_chunk(
+    delta_text: str | None = None,
+    delta_reasoning: str | None = None,
+    tool_calls: list | None = None,
+    delta_audio: dict | None = None,
+    response_id: str = "req-1",
+    usage: dict | None = None,
+    has_choices: bool = True,
+) -> MagicMock:
+    """Build a single mock streaming chunk."""
+    chunk = MagicMock()
+    chunk.id = response_id
+
+    if usage:
+        chunk.usage = MagicMock()
+        chunk.usage.prompt_tokens = usage.get("prompt_tokens", 0)
+        chunk.usage.completion_tokens = usage.get("completion_tokens", 0)
+        chunk.usage.prompt_tokens_details = None
+    else:
+        chunk.usage = None
+
+    if has_choices:
+        delta = MagicMock()
+        delta.content = delta_text
+        delta.reasoning_content = delta_reasoning
+        delta.tool_calls = tool_calls
+        delta.audio = delta_audio
+        choice = MagicMock()
+        choice.delta = delta
+        chunk.choices = [choice]
+    else:
+        chunk.choices = []
+
+    return chunk
+
+
+def _make_tool_call_delta(
+    index: int,
+    tc_id: str | None = None,
+    name: str | None = None,
+    arguments: str | None = None,
+) -> MagicMock:
+    tc = MagicMock()
+    tc.index = index
+    tc.id = tc_id
+    tc.function = MagicMock()
+    tc.function.name = name
+    tc.function.arguments = arguments
+    return tc
+
+
+class _MockAsyncStream:
+    """Mock async stream (context manager + async iterator)."""
+
+    def __init__(self, chunks: list) -> None:
+        self._chunks = chunks
+        self._index = 0
+
+    async def __aenter__(self) -> "_MockAsyncStream":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        pass
+
+    def __aiter__(self) -> "_MockAsyncStream":
+        return self
+
+    async def __anext__(self) -> Any:
+        if self._index >= len(self._chunks):
+            raise StopAsyncIteration
+        chunk = self._chunks[self._index]
+        self._index += 1
+        return chunk
+
+
+# ---------------------------------------------------------------------------
+# Non-streaming tests
+# ---------------------------------------------------------------------------
+
+
+class TestDashScopeNonStream(IsolatedAsyncioTestCase):
+    """Tests for DashScopeChatModel in non-streaming mode."""
+
+    def setUp(self) -> None:
+        self.model = _make_model(stream=False)
+
+    @patch("openai.AsyncClient")
+    async def test_text_response(self, mock_client_cls: MagicMock) -> None:
+        """Non-stream text response returns a single ChatResponse."""
+        mock_create = AsyncMock(
+            return_value=_mock_completion(text="Hello!"),
+        )
+        mock_client_cls.return_value.chat.completions.create = mock_create
+
+        result = await self.model([])
+
+        self.assertEqual(
+            (result.is_last, result.content),
+            (True, [TextBlock.model_construct(id=A, text="Hello!")]),
+        )
+        self.assertEqual(result.id, "req-1")
+
+    @patch("openai.AsyncClient")
+    async def test_tool_call_response(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Non-stream tool call response creates ToolCallBlocks."""
+        mock_create = AsyncMock(
+            return_value=_mock_completion(
+                tool_calls=[
+                    {
+                        "id": "call-1",
+                        "name": "get_weather",
+                        "arguments": '{"city":"Hangzhou"}',
+                    },
+                ],
+            ),
+        )
+        mock_client_cls.return_value.chat.completions.create = mock_create
+
+        result = await self.model([])
+
+        self.assertEqual(
+            (result.is_last, result.content),
+            (
+                True,
+                [
+                    ToolCallBlock(
+                        id="call-1",
+                        name="get_weather",
+                        input='{"city":"Hangzhou"}',
+                    ),
+                ],
+            ),
+        )
+
+    @patch("openai.AsyncClient")
+    async def test_thinking_response(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Non-stream response with reasoning creates ThinkingBlock."""
+        mock_create = AsyncMock(
+            return_value=_mock_completion(
+                text="42",
+                reasoning="Reasoning step...",
+            ),
+        )
+        mock_client_cls.return_value.chat.completions.create = mock_create
+
+        result = await self.model([])
+
+        self.assertEqual(
+            (result.is_last, result.content),
+            (
+                True,
+                [
+                    ThinkingBlock.model_construct(
+                        id=A,
+                        thinking="Reasoning step...",
+                    ),
+                    TextBlock.model_construct(id=A, text="42"),
+                ],
+            ),
+        )
+
+
+# ---------------------------------------------------------------------------
+# Streaming tests
+# ---------------------------------------------------------------------------
+
+
+class TestDashScopeStream(IsolatedAsyncioTestCase):
+    """Tests for DashScopeChatModel in streaming mode."""
+
+    def setUp(self) -> None:
+        self.model = _make_model(stream=True)
+
+    @patch("openai.AsyncClient")
+    async def test_stream_text(self, mock_client_cls: MagicMock) -> None:
+        """Stream text yields n deltas + 1 final with full content."""
+        chunks = [
+            _make_stream_chunk(delta_text="Hello"),
+            _make_stream_chunk(delta_text=" world"),
+            _make_stream_chunk(
+                has_choices=False,
+                usage={"prompt_tokens": 10, "completion_tokens": 2},
+            ),
+        ]
+        mock_create = AsyncMock(return_value=_MockAsyncStream(chunks))
+        mock_client_cls.return_value.chat.completions.create = mock_create
+
+        gen = await self.model([])
+        responses = [r async for r in gen]
+
+        self.assertListEqual(
+            [(r.is_last, r.content) for r in responses],
+            [
+                (False, [TextBlock.model_construct(id=A, text="Hello")]),
+                (False, [TextBlock.model_construct(id=A, text=" world")]),
+                (True, [TextBlock.model_construct(id=A, text="Hello world")]),
+            ],
+        )
+
+    @patch("openai.AsyncClient")
+    async def test_stream_thinking_and_text(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Stream reasoning + text yields deltas then accumulated final."""
+        chunks = [
+            _make_stream_chunk(delta_reasoning="Think"),
+            _make_stream_chunk(delta_reasoning="ing"),
+            _make_stream_chunk(delta_text="Answer"),
+            _make_stream_chunk(
+                has_choices=False,
+                usage={"prompt_tokens": 10, "completion_tokens": 5},
+            ),
+        ]
+        mock_create = AsyncMock(return_value=_MockAsyncStream(chunks))
+        mock_client_cls.return_value.chat.completions.create = mock_create
+
+        gen = await self.model([])
+        responses = [r async for r in gen]
+
+        self.assertListEqual(
+            [(r.is_last, r.content) for r in responses],
+            [
+                (
+                    False,
+                    [ThinkingBlock.model_construct(id=A, thinking="Think")],
+                ),
+                (False, [ThinkingBlock.model_construct(id=A, thinking="ing")]),
+                (False, [TextBlock.model_construct(id=A, text="Answer")]),
+                (
+                    True,
+                    [
+                        ThinkingBlock.model_construct(
+                            id=A,
+                            thinking="Thinking",
+                        ),
+                        TextBlock.model_construct(id=A, text="Answer"),
+                    ],
+                ),
+            ],
+        )
+
+    @patch("openai.AsyncClient")
+    async def test_stream_tool_calls(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Stream tool call chunks accumulate into final ToolCallBlock."""
+        chunks = [
+            _make_stream_chunk(
+                tool_calls=[
+                    _make_tool_call_delta(0, "call-1", "search", '{"q":'),
+                ],
+            ),
+            _make_stream_chunk(
+                tool_calls=[
+                    _make_tool_call_delta(0, None, None, '"hello"}'),
+                ],
+            ),
+            _make_stream_chunk(
+                has_choices=False,
+                usage={"prompt_tokens": 10, "completion_tokens": 5},
+            ),
+        ]
+        mock_create = AsyncMock(return_value=_MockAsyncStream(chunks))
+        mock_client_cls.return_value.chat.completions.create = mock_create
+
+        gen = await self.model([])
+        responses = [r async for r in gen]
+
+        self.assertListEqual(
+            [(r.is_last, r.content) for r in responses],
+            [
+                (
+                    False,
+                    [
+                        ToolCallBlock(
+                            id="call-1",
+                            name="search",
+                            input='{"q":',
+                        ),
+                    ],
+                ),
+                (
+                    False,
+                    [
+                        ToolCallBlock(
+                            id="call-1",
+                            name="search",
+                            input='"hello"}',
+                        ),
+                    ],
+                ),
+                (
+                    True,
+                    [
+                        ToolCallBlock(
+                            id="call-1",
+                            name="search",
+                            input='{"q":"hello"}',
+                        ),
+                    ],
+                ),
+            ],
+        )
+
+    @patch("openai.AsyncClient")
+    async def test_stream_usage(self, mock_client_cls: MagicMock) -> None:
+        """Stream usage chunk attaches token counts to final response."""
+        chunks = [
+            _make_stream_chunk(delta_text="X"),
+            _make_stream_chunk(
+                has_choices=False,
+                usage={"prompt_tokens": 50, "completion_tokens": 10},
+            ),
+        ]
+        mock_create = AsyncMock(return_value=_MockAsyncStream(chunks))
+        mock_client_cls.return_value.chat.completions.create = mock_create
+
+        gen = await self.model([])
+        responses = [r async for r in gen]
+
+        self.assertListEqual(
+            [(r.is_last, r.content) for r in responses],
+            [
+                (False, [TextBlock.model_construct(id=A, text="X")]),
+                (True, [TextBlock.model_construct(id=A, text="X")]),
+            ],
+        )
+        self.assertEqual(responses[-1].usage.input_tokens, 50)
+        self.assertEqual(responses[-1].usage.output_tokens, 10)
+
+    @patch("openai.AsyncClient")
+    async def test_stream_audio_response(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Stream PCM deltas produce per-chunk DataBlocks (first chunk
+        prefixed with a streaming WAV header) sharing a stable id, plus a
+        final fixed-size WAV block readable by the ``wave`` module."""
+        pcm1 = bytes([1, 2, 3, 4])
+        pcm2 = bytes([5, 6, 7, 8])
+        pcm3 = bytes([9, 10, 11, 12])
+        pcm_full = pcm1 + pcm2 + pcm3
+
+        chunks = [
+            _make_stream_chunk(
+                delta_audio={"data": base64.b64encode(pcm1).decode()},
+            ),
+            _make_stream_chunk(
+                delta_audio={"data": base64.b64encode(pcm2).decode()},
+            ),
+            _make_stream_chunk(
+                delta_audio={"data": base64.b64encode(pcm3).decode()},
+            ),
+            _make_stream_chunk(
+                has_choices=False,
+                usage={"prompt_tokens": 5, "completion_tokens": 3},
+            ),
+        ]
+        mock_create = AsyncMock(return_value=_MockAsyncStream(chunks))
+        mock_client_cls.return_value.chat.completions.create = mock_create
+
+        gen = await self.model([])
+        responses = [r async for r in gen]
+        self.assertEqual(len(responses), 4)
+
+        # All four chunks (3 deltas + 1 final) must share the same audio
+        # block id so downstream consumers stitch them as one stream.
+        all_audio_ids = {
+            block.id
+            for r in responses
+            for block in r.content
+            if isinstance(block, DataBlock)
+        }
+        self.assertEqual(len(all_audio_ids), 1)
+
+        # First delta: WAV header (44 bytes, "RIFF"..."WAVE") + pcm1.
+        first_payload = base64.b64decode(responses[0].content[0].source.data)
+        self.assertEqual(len(first_payload), 44 + len(pcm1))
+        self.assertEqual(first_payload[:4], b"RIFF")
+        self.assertEqual(first_payload[8:12], b"WAVE")
+        self.assertEqual(first_payload[44:], pcm1)
+
+        # Subsequent deltas: raw PCM only, no header.
+        for resp, pcm in zip(responses[1:3], [pcm2, pcm3]):
+            payload = base64.b64decode(resp.content[0].source.data)
+            self.assertEqual(payload, pcm)
+
+        # Final ``is_last`` block: a fixed-size WAV the ``wave`` module
+        # can parse end-to-end at 24kHz / mono / 16-bit.
+        final = responses[-1]
+        self.assertTrue(final.is_last)
+        final_audio = next(
+            b for b in final.content if isinstance(b, DataBlock)
+        )
+        wav_bytes = base64.b64decode(final_audio.source.data)
+        with wave.open(io.BytesIO(wav_bytes), "rb") as wav:
+            self.assertEqual(wav.getnchannels(), 1)
+            self.assertEqual(wav.getsampwidth(), 2)
+            self.assertEqual(wav.getframerate(), 24000)
+            frames = wav.readframes(wav.getnframes())
+        self.assertEqual(frames, pcm_full)
+
+
+# ---------------------------------------------------------------------------
+# _format_tools tests
+# ---------------------------------------------------------------------------
+
+_FT_TOOLS = [
+    {
+        "type": "function",
+        "function": {
+            "name": "get_weather",
+            "description": "Get the weather",
+            "parameters": {
+                "type": "object",
+                "properties": {"city": {"type": "string"}},
+                "required": ["city"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "get_time",
+            "description": "Get the time",
+            "parameters": {
+                "type": "object",
+                "properties": {"timezone": {"type": "string"}},
+                "required": ["timezone"],
+            },
+        },
+    },
+]
+
+
+class TestDashScopeFormatTools(unittest.TestCase):
+    """Tests for DashScopeChatModel._format_tools."""
+
+    def setUp(self) -> None:
+        """Set up model instance."""
+        self.model = _make_model()
+
+    def test_auto_mode(self) -> None:
+        """Auto mode returns tools unchanged and string 'auto'."""
+        fmt_tools, fmt_choice = self.model._format_tools(
+            _FT_TOOLS,
+            ToolChoice(mode="auto"),
+        )
+        self.assertEqual(fmt_tools, _FT_TOOLS)
+        self.assertEqual(fmt_choice, "auto")
+
+    def test_none_mode(self) -> None:
+        """None mode returns tools unchanged and string 'none'."""
+        fmt_tools, fmt_choice = self.model._format_tools(
+            _FT_TOOLS,
+            ToolChoice(mode="none"),
+        )
+        self.assertEqual(fmt_tools, _FT_TOOLS)
+        self.assertEqual(fmt_choice, "none")
+
+    def test_required_mode_warns(self) -> None:
+        """Required mode emits a DeprecationWarning and falls back to auto."""
+        with self.assertWarns(DeprecationWarning):
+            fmt_tools, fmt_choice = self.model._format_tools(
+                _FT_TOOLS,
+                ToolChoice(mode="required"),
+            )
+        self.assertEqual(fmt_tools, _FT_TOOLS)
+        self.assertEqual(fmt_choice, "auto")
+
+    def test_str_mode_force_call(self) -> None:
+        """A specific tool name forces that tool call."""
+        fmt_tools, fmt_choice = self.model._format_tools(
+            _FT_TOOLS,
+            ToolChoice(mode="get_weather"),
+        )
+        self.assertEqual(fmt_tools, _FT_TOOLS)
+        self.assertEqual(
+            fmt_choice,
+            {"type": "function", "function": {"name": "get_weather"}},
+        )
+
+    def test_tools_filtered(self) -> None:
+        """When tool_choice.tools is set, only those tools are included."""
+        fmt_tools, fmt_choice = self.model._format_tools(
+            _FT_TOOLS,
+            ToolChoice(mode="auto", tools=["get_weather"]),
+        )
+        self.assertEqual(len(fmt_tools), 1)
+        self.assertEqual(fmt_tools[0]["function"]["name"], "get_weather")
+        self.assertEqual(fmt_choice, "auto")
+
+    def test_no_tool_choice(self) -> None:
+        """Without tool_choice, returns tools and None."""
+        fmt_tools, fmt_choice = self.model._format_tools(_FT_TOOLS, None)
+        self.assertEqual(fmt_tools, _FT_TOOLS)
+        self.assertIsNone(fmt_choice)
diff --git a/tests/model_deepseek_test.py b/tests/model_deepseek_test.py
new file mode 100644
index 0000000..f20006d
--- /dev/null
+++ b/tests/model_deepseek_test.py
@@ -0,0 +1,641 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Unit tests for DeepSeekChatModel with mocked API responses.
+
+Tests cover both non-streaming and streaming modes, verifying that:
+- Non-stream mode returns a single ChatResponse with is_last=True.
+- Stream mode yields n delta ChatResponses (is_last=False) followed by
+  1 final ChatResponse (is_last=True) with the full accumulated content.
+"""
+from typing import Any
+import unittest
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import AsyncMock, MagicMock, patch
+
+from utils import AnyString
+
+from agentscope.message import TextBlock, ToolCallBlock, ThinkingBlock
+from agentscope.model import DeepSeekChatModel
+from agentscope.credential import DeepSeekCredential
+from agentscope.tool import ToolChoice
+
+A = AnyString()
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_model(stream: bool = False) -> Any:
+    return DeepSeekChatModel(
+        credential=DeepSeekCredential(api_key="test"),
+        model="deepseek-v4-pro",
+        stream=stream,
+        context_size=65_536,
+    )
+
+
+def _mock_completion(
+    text: Any = None,
+    tool_calls: Any = None,
+    reasoning: Any = None,
+    response_id: str = "deepseek-1",
+) -> MagicMock:
+    """Build a mock non-streaming ChatCompletion response."""
+    msg = MagicMock()
+    msg.content = text
+    msg.reasoning_content = reasoning
+    msg.tool_calls = None
+
+    if tool_calls:
+        tc_mocks = []
+        for tc in tool_calls:
+            m = MagicMock()
+            m.id = tc["id"]
+            m.function.name = tc["name"]
+            m.function.arguments = tc["arguments"]
+            tc_mocks.append(m)
+        msg.tool_calls = tc_mocks
+
+    choice = MagicMock()
+    choice.message = msg
+
+    resp = MagicMock()
+    resp.id = response_id
+    resp.choices = [choice]
+    resp.usage.prompt_tokens = 10
+    resp.usage.completion_tokens = 5
+    resp.usage.prompt_cache_hit_tokens = 0
+    return resp
+
+
+def _make_stream_chunk(
+    delta_text: str | None = None,
+    delta_reasoning: str | None = None,
+    tool_calls: list | None = None,
+    response_id: str = "deepseek-1",
+    usage: dict | None = None,
+    has_choices: bool = True,
+) -> MagicMock:
+    """Build a single mock streaming chunk."""
+    chunk = MagicMock()
+    chunk.id = response_id
+
+    if usage:
+        chunk.usage = MagicMock()
+        chunk.usage.prompt_tokens = usage.get("prompt_tokens", 0)
+        chunk.usage.completion_tokens = usage.get("completion_tokens", 0)
+        chunk.usage.prompt_cache_hit_tokens = usage.get(
+            "prompt_cache_hit_tokens",
+            0,
+        )
+    else:
+        chunk.usage = None
+
+    if has_choices:
+        delta = MagicMock()
+        delta.content = delta_text
+        delta.reasoning_content = delta_reasoning
+        delta.tool_calls = tool_calls
+        choice = MagicMock()
+        choice.delta = delta
+        chunk.choices = [choice]
+    else:
+        chunk.choices = []
+
+    return chunk
+
+
+def _make_tool_call_delta(
+    index: int,
+    tc_id: str | None = None,
+    name: str | None = None,
+    arguments: str | None = None,
+) -> MagicMock:
+    """Build a tool_call delta item for streaming."""
+    tc = MagicMock()
+    tc.index = index
+    tc.id = tc_id
+    tc.function.name = name
+    tc.function.arguments = arguments
+    return tc
+
+
+class _MockAsyncStream:
+    """Mock async stream that acts as an async context manager + iterator."""
+
+    def __init__(self, chunks: list) -> None:
+        self._chunks = chunks
+        self._index = 0
+
+    async def __aenter__(self) -> "_MockAsyncStream":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        pass
+
+    def __aiter__(self) -> "_MockAsyncStream":
+        return self
+
+    async def __anext__(self) -> Any:
+        if self._index >= len(self._chunks):
+            raise StopAsyncIteration
+        chunk = self._chunks[self._index]
+        self._index += 1
+        return chunk
+
+
+# ---------------------------------------------------------------------------
+# Non-streaming tests
+# ---------------------------------------------------------------------------
+
+
+class TestDeepSeekNonStream(IsolatedAsyncioTestCase):
+    """Tests for DeepSeekChatModel in non-streaming mode."""
+
+    def setUp(self) -> None:
+        self.model = _make_model(stream=False)
+
+    @patch("openai.AsyncClient")
+    async def test_text_response(self, mock_client_cls: MagicMock) -> None:
+        """Non-stream text response returns a single ChatResponse."""
+        mock_create = AsyncMock(
+            return_value=_mock_completion(text="Hello world!"),
+        )
+        mock_client_cls.return_value.chat.completions.create = mock_create
+
+        result = await self.model([])
+
+        self.assertEqual(
+            (result.is_last, result.content),
+            (True, [TextBlock.model_construct(id=A, text="Hello world!")]),
+        )
+        self.assertEqual(result.id, "deepseek-1")
+
+    @patch("openai.AsyncClient")
+    async def test_tool_call_response(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Non-stream tool call response creates ToolCallBlocks."""
+        mock_create = AsyncMock(
+            return_value=_mock_completion(
+                tool_calls=[
+                    {
+                        "id": "call-1",
+                        "name": "get_weather",
+                        "arguments": '{"city":"Beijing"}',
+                    },
+                    {
+                        "id": "call-2",
+                        "name": "get_time",
+                        "arguments": '{"tz":"UTC"}',
+                    },
+                ],
+            ),
+        )
+        mock_client_cls.return_value.chat.completions.create = mock_create
+
+        result = await self.model([])
+
+        self.assertEqual(
+            (result.is_last, result.content),
+            (
+                True,
+                [
+                    ToolCallBlock(
+                        id="call-1",
+                        name="get_weather",
+                        input='{"city":"Beijing"}',
+                    ),
+                    ToolCallBlock(
+                        id="call-2",
+                        name="get_time",
+                        input='{"tz":"UTC"}',
+                    ),
+                ],
+            ),
+        )
+
+    @patch("openai.AsyncClient")
+    async def test_thinking_response(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Non-stream response with reasoning creates ThinkingBlock."""
+        mock_create = AsyncMock(
+            return_value=_mock_completion(
+                text="The answer is 42.",
+                reasoning="Let me think step by step...",
+            ),
+        )
+        mock_client_cls.return_value.chat.completions.create = mock_create
+
+        result = await self.model([])
+
+        self.assertEqual(
+            (result.is_last, result.content),
+            (
+                True,
+                [
+                    ThinkingBlock.model_construct(
+                        id=A,
+                        thinking="Let me think step by step...",
+                    ),
+                    TextBlock.model_construct(id=A, text="The answer is 42."),
+                ],
+            ),
+        )
+
+
+# ---------------------------------------------------------------------------
+# Streaming tests
+# ---------------------------------------------------------------------------
+
+
+class TestDeepSeekStream(IsolatedAsyncioTestCase):
+    """Tests for DeepSeekChatModel in streaming mode."""
+
+    def setUp(self) -> None:
+        self.model = _make_model(stream=True)
+
+    @patch("openai.AsyncClient")
+    async def test_stream_text_response(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Stream text yields n deltas (is_last=False) + 1 final
+        (is_last=True) with full content."""
+        chunks = [
+            _make_stream_chunk(delta_text="Hello"),
+            _make_stream_chunk(delta_text=" world"),
+            _make_stream_chunk(delta_text="!"),
+            _make_stream_chunk(
+                has_choices=False,
+                usage={"prompt_tokens": 10, "completion_tokens": 3},
+            ),
+        ]
+        mock_create = AsyncMock(return_value=_MockAsyncStream(chunks))
+        mock_client_cls.return_value.chat.completions.create = mock_create
+
+        gen = await self.model([])
+        responses = [r async for r in gen]
+
+        self.assertListEqual(
+            [(r.is_last, r.content) for r in responses],
+            [
+                (False, [TextBlock.model_construct(id=A, text="Hello")]),
+                (False, [TextBlock.model_construct(id=A, text=" world")]),
+                (False, [TextBlock.model_construct(id=A, text="!")]),
+                (True, [TextBlock.model_construct(id=A, text="Hello world!")]),
+            ],
+        )
+        self.assertEqual(responses[-1].id, "deepseek-1")
+
+    @patch("openai.AsyncClient")
+    async def test_stream_thinking_and_text(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Stream with thinking + text yields deltas then final with both."""
+        chunks = [
+            _make_stream_chunk(delta_reasoning="Think"),
+            _make_stream_chunk(delta_reasoning="ing..."),
+            _make_stream_chunk(delta_text="Answer"),
+            _make_stream_chunk(delta_text=" here."),
+            _make_stream_chunk(
+                has_choices=False,
+                usage={"prompt_tokens": 10, "completion_tokens": 8},
+            ),
+        ]
+        mock_create = AsyncMock(return_value=_MockAsyncStream(chunks))
+        mock_client_cls.return_value.chat.completions.create = mock_create
+
+        gen = await self.model([])
+        responses = [r async for r in gen]
+
+        self.assertListEqual(
+            [(r.is_last, r.content) for r in responses],
+            [
+                (
+                    False,
+                    [ThinkingBlock.model_construct(id=A, thinking="Think")],
+                ),
+                (
+                    False,
+                    [ThinkingBlock.model_construct(id=A, thinking="ing...")],
+                ),
+                (False, [TextBlock.model_construct(id=A, text="Answer")]),
+                (False, [TextBlock.model_construct(id=A, text=" here.")]),
+                (
+                    True,
+                    [
+                        ThinkingBlock.model_construct(
+                            id=A,
+                            thinking="Thinking...",
+                        ),
+                        TextBlock.model_construct(id=A, text="Answer here."),
+                    ],
+                ),
+            ],
+        )
+
+    @patch("openai.AsyncClient")
+    async def test_stream_tool_calls(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Stream tool calls accumulate across chunks into final response."""
+        chunks = [
+            _make_stream_chunk(
+                delta_text=None,
+                tool_calls=[
+                    _make_tool_call_delta(0, "call-1", "get_weather", '{"ci'),
+                ],
+            ),
+            _make_stream_chunk(
+                delta_text=None,
+                tool_calls=[
+                    _make_tool_call_delta(0, None, None, 'ty":"BJ"}'),
+                ],
+            ),
+            _make_stream_chunk(
+                has_choices=False,
+                usage={"prompt_tokens": 10, "completion_tokens": 5},
+            ),
+        ]
+        mock_create = AsyncMock(return_value=_MockAsyncStream(chunks))
+        mock_client_cls.return_value.chat.completions.create = mock_create
+
+        gen = await self.model([])
+        responses = [r async for r in gen]
+
+        self.assertListEqual(
+            [(r.is_last, r.content) for r in responses],
+            [
+                (
+                    False,
+                    [
+                        ToolCallBlock(
+                            id="call-1",
+                            name="get_weather",
+                            input='{"ci',
+                        ),
+                    ],
+                ),
+                (
+                    False,
+                    [
+                        ToolCallBlock(
+                            id="call-1",
+                            name="get_weather",
+                            input='ty":"BJ"}',
+                        ),
+                    ],
+                ),
+                (
+                    True,
+                    [
+                        ToolCallBlock(
+                            id="call-1",
+                            name="get_weather",
+                            input='{"city":"BJ"}',
+                        ),
+                    ],
+                ),
+            ],
+        )
+
+    @patch("openai.AsyncClient")
+    async def test_stream_text_then_tool_call(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Stream with text followed by tool call accumulates both."""
+        chunks = [
+            _make_stream_chunk(delta_reasoning="Let me check"),
+            _make_stream_chunk(delta_text="I'll look it up."),
+            _make_stream_chunk(
+                delta_text=None,
+                tool_calls=[
+                    _make_tool_call_delta(
+                        0,
+                        "call-1",
+                        "search",
+                        '{"q":"weather"}',
+                    ),
+                ],
+            ),
+            _make_stream_chunk(
+                has_choices=False,
+                usage={"prompt_tokens": 15, "completion_tokens": 10},
+            ),
+        ]
+        mock_create = AsyncMock(return_value=_MockAsyncStream(chunks))
+        mock_client_cls.return_value.chat.completions.create = mock_create
+
+        gen = await self.model([])
+        responses = [r async for r in gen]
+
+        self.assertListEqual(
+            [(r.is_last, r.content) for r in responses],
+            [
+                (
+                    False,
+                    [
+                        ThinkingBlock.model_construct(
+                            id=A,
+                            thinking="Let me check",
+                        ),
+                    ],
+                ),
+                (
+                    False,
+                    [TextBlock.model_construct(id=A, text="I'll look it up.")],
+                ),
+                (
+                    False,
+                    [
+                        ToolCallBlock(
+                            id="call-1",
+                            name="search",
+                            input='{"q":"weather"}',
+                        ),
+                    ],
+                ),
+                (
+                    True,
+                    [
+                        ThinkingBlock.model_construct(
+                            id=A,
+                            thinking="Let me check",
+                        ),
+                        TextBlock.model_construct(
+                            id=A,
+                            text="I'll look it up.",
+                        ),
+                        ToolCallBlock(
+                            id="call-1",
+                            name="search",
+                            input='{"q":"weather"}',
+                        ),
+                    ],
+                ),
+            ],
+        )
+
+    @patch("openai.AsyncClient")
+    async def test_stream_usage_in_final(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Usage information is captured and present in final response."""
+        chunks = [
+            _make_stream_chunk(delta_text="Hi"),
+            _make_stream_chunk(
+                has_choices=False,
+                usage={
+                    "prompt_tokens": 100,
+                    "completion_tokens": 20,
+                    "prompt_cache_hit_tokens": 50,
+                },
+            ),
+        ]
+        mock_create = AsyncMock(return_value=_MockAsyncStream(chunks))
+        mock_client_cls.return_value.chat.completions.create = mock_create
+
+        gen = await self.model([])
+        responses = [r async for r in gen]
+
+        self.assertListEqual(
+            [(r.is_last, r.content) for r in responses],
+            [
+                (False, [TextBlock.model_construct(id=A, text="Hi")]),
+                (True, [TextBlock.model_construct(id=A, text="Hi")]),
+            ],
+        )
+        self.assertEqual(responses[-1].usage.input_tokens, 100)
+        self.assertEqual(responses[-1].usage.output_tokens, 20)
+        self.assertEqual(responses[-1].usage.cache_input_tokens, 50)
+
+
+class TestDeepSeekModelParameters(unittest.TestCase):
+    """Tests for DeepSeekChatModel.Parameters."""
+
+    def test_thinking_enable_stored_on_model(self) -> None:
+        """thinking_enable is accessible through model.parameters."""
+        model = DeepSeekChatModel(
+            credential=DeepSeekCredential(api_key="test"),
+            model="deepseek-reasoner",
+            stream=False,
+            context_size=65_536,
+            parameters=DeepSeekChatModel.Parameters(thinking_enable=True),
+        )
+        self.assertTrue(model.parameters.thinking_enable)
+
+    def test_reasoning_effort_stored_on_model(self) -> None:
+        """reasoning_effort is accessible through model.parameters."""
+        model = DeepSeekChatModel(
+            credential=DeepSeekCredential(api_key="test"),
+            model="deepseek-reasoner",
+            stream=False,
+            context_size=65_536,
+            parameters=DeepSeekChatModel.Parameters(reasoning_effort="max"),
+        )
+        self.assertEqual(model.parameters.reasoning_effort, "max")
+
+
+# ---------------------------------------------------------------------------
+# Shared _format_tools fixtures
+# ---------------------------------------------------------------------------
+
+_FT_TOOLS = [
+    {
+        "type": "function",
+        "function": {
+            "name": "get_weather",
+            "description": "Get the weather",
+            "parameters": {
+                "type": "object",
+                "properties": {"city": {"type": "string"}},
+                "required": ["city"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "get_time",
+            "description": "Get the time",
+            "parameters": {
+                "type": "object",
+                "properties": {"timezone": {"type": "string"}},
+                "required": ["timezone"],
+            },
+        },
+    },
+]
+
+
+class TestDeepSeekFormatTools(unittest.TestCase):
+    """Tests for DeepSeekChatModel._format_tools."""
+
+    def setUp(self) -> None:
+        """Set up model instance."""
+        self.model = _make_model()
+
+    def test_auto_mode(self) -> None:
+        """Auto mode returns tools unchanged and string 'auto'."""
+        fmt_tools, fmt_choice = self.model._format_tools(
+            _FT_TOOLS,
+            ToolChoice(mode="auto"),
+        )
+        self.assertEqual(fmt_tools, _FT_TOOLS)
+        self.assertEqual(fmt_choice, "auto")
+
+    def test_none_mode(self) -> None:
+        """None mode returns tools unchanged and string 'none'."""
+        fmt_tools, fmt_choice = self.model._format_tools(
+            _FT_TOOLS,
+            ToolChoice(mode="none"),
+        )
+        self.assertEqual(fmt_tools, _FT_TOOLS)
+        self.assertEqual(fmt_choice, "none")
+
+    def test_required_mode(self) -> None:
+        """Required mode returns tools unchanged and string 'required'."""
+        fmt_tools, fmt_choice = self.model._format_tools(
+            _FT_TOOLS,
+            ToolChoice(mode="required"),
+        )
+        self.assertEqual(fmt_tools, _FT_TOOLS)
+        self.assertEqual(fmt_choice, "required")
+
+    def test_str_mode_force_call(self) -> None:
+        """A specific tool name returns a type=function dict."""
+        fmt_tools, fmt_choice = self.model._format_tools(
+            _FT_TOOLS,
+            ToolChoice(mode="get_weather"),
+        )
+        self.assertEqual(fmt_tools, _FT_TOOLS)
+        self.assertEqual(
+            fmt_choice,
+            {"type": "function", "function": {"name": "get_weather"}},
+        )
+
+    def test_tools_filtered(self) -> None:
+        """When tool_choice.tools is set, only those tools are included."""
+        fmt_tools, fmt_choice = self.model._format_tools(
+            _FT_TOOLS,
+            ToolChoice(mode="auto", tools=["get_weather"]),
+        )
+        self.assertEqual(len(fmt_tools), 1)
+        self.assertEqual(fmt_tools[0]["function"]["name"], "get_weather")
+        self.assertEqual(fmt_choice, "auto")
+
+    def test_no_tool_choice(self) -> None:
+        """Without tool_choice, returns tools and None."""
+        fmt_tools, fmt_choice = self.model._format_tools(_FT_TOOLS, None)
+        self.assertEqual(fmt_tools, _FT_TOOLS)
+        self.assertIsNone(fmt_choice)
diff --git a/tests/model_gemini_test.py b/tests/model_gemini_test.py
new file mode 100644
index 0000000..c5dd3d9
--- /dev/null
+++ b/tests/model_gemini_test.py
@@ -0,0 +1,704 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Unit tests for GeminiChatModel with mocked API responses.
+
+Tests cover both non-streaming and streaming modes.
+Gemini uses google.genai client with async iterator streaming.
+"""
+import json
+from typing import Any
+import unittest
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import AsyncMock, MagicMock, patch
+
+from utils import AnyString
+
+from agentscope.message import TextBlock, ToolCallBlock, ThinkingBlock
+from agentscope.model import GeminiChatModel
+from agentscope.model._gemini._model import _sanitize_schema_for_gemini
+from agentscope._utils._common import _flatten_json_schema
+from agentscope.credential import GeminiCredential
+from agentscope.tool import ToolChoice
+
+A = AnyString()
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_model(stream: bool = False) -> Any:
+    return GeminiChatModel(
+        credential=GeminiCredential(api_key="test"),
+        model="gemini-2.5-flash",
+        stream=stream,
+        context_size=1_048_576,
+    )
+
+
+def _make_part(
+    text: str | None = None,
+    thought: bool = False,
+    function_call: dict | None = None,
+    thought_signature: Any = None,
+) -> MagicMock:
+    """Build a mock Gemini Part."""
+    part = MagicMock()
+    part.text = text
+    part.thought = thought
+    part.thought_signature = thought_signature
+    if function_call:
+        part.function_call = MagicMock()
+        part.function_call.name = function_call["name"]
+        part.function_call.args = function_call.get("args", {})
+        part.function_call.id = function_call.get("id", "call-1")
+    else:
+        part.function_call = None
+    return part
+
+
+def _mock_completion(
+    parts: list,
+    response_id: str = "resp-gem-1",
+) -> MagicMock:
+    """Build a mock non-streaming Gemini response."""
+    resp = MagicMock()
+    resp.response_id = response_id
+    resp.candidates = [MagicMock()]
+    resp.candidates[0].content = MagicMock()
+    resp.candidates[0].content.parts = parts
+    resp.usage_metadata = MagicMock()
+    resp.usage_metadata.prompt_token_count = 10
+    resp.usage_metadata.candidates_token_count = 5
+    return resp
+
+
+def _make_stream_chunk(
+    parts: list,
+    response_id: str = "resp-gem-1",
+) -> MagicMock:
+    """Build a single mock streaming chunk."""
+    chunk = MagicMock()
+    chunk.response_id = response_id
+    chunk.candidates = [MagicMock()]
+    chunk.candidates[0].content = MagicMock()
+    chunk.candidates[0].content.parts = parts
+    chunk.usage_metadata = MagicMock()
+    chunk.usage_metadata.prompt_token_count = 10
+    chunk.usage_metadata.candidates_token_count = 5
+    return chunk
+
+
+class _MockAsyncStream:
+    """Mock async iterator for Gemini stream."""
+
+    def __init__(self, chunks: list) -> None:
+        self._chunks = chunks
+        self._index = 0
+
+    def __aiter__(self) -> "_MockAsyncStream":
+        return self
+
+    async def __anext__(self) -> Any:
+        if self._index >= len(self._chunks):
+            raise StopAsyncIteration
+        chunk = self._chunks[self._index]
+        self._index += 1
+        return chunk
+
+
+# ---------------------------------------------------------------------------
+# Non-streaming tests
+# ---------------------------------------------------------------------------
+
+
+class TestGeminiNonStream(IsolatedAsyncioTestCase):
+    """Tests for GeminiChatModel in non-streaming mode."""
+
+    def setUp(self) -> None:
+        self.model = _make_model(stream=False)
+
+    @patch("google.genai.Client")
+    async def test_text_response(self, mock_client_cls: MagicMock) -> None:
+        """Non-stream text response returns a single ChatResponse."""
+        parts = [_make_part(text="Hello!")]
+        mock_client_cls.return_value.aio.models.generate_content = AsyncMock(
+            return_value=_mock_completion(parts),
+        )
+
+        result = await self.model([])
+
+        self.assertEqual(
+            (result.is_last, result.content),
+            (True, [TextBlock.model_construct(id=A, text="Hello!")]),
+        )
+
+    @patch("google.genai.Client")
+    async def test_tool_call_response(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Non-stream tool call response creates ToolCallBlocks."""
+        parts = [
+            _make_part(
+                function_call={
+                    "name": "get_weather",
+                    "args": {"city": "Tokyo"},
+                    "id": "call-1",
+                },
+            ),
+        ]
+        mock_client_cls.return_value.aio.models.generate_content = AsyncMock(
+            return_value=_mock_completion(parts),
+        )
+
+        result = await self.model([])
+
+        self.assertEqual(
+            (result.is_last, result.content),
+            (
+                True,
+                [
+                    ToolCallBlock(
+                        id="call-1",
+                        name="get_weather",
+                        input=json.dumps(
+                            {"city": "Tokyo"},
+                            ensure_ascii=False,
+                        ),
+                    ),
+                ],
+            ),
+        )
+
+    @patch("google.genai.Client")
+    async def test_tool_call_response_without_id(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """A function call with no id gets a generated id, not a crash."""
+        parts = [
+            _make_part(
+                function_call={
+                    "name": "get_weather",
+                    "args": {"city": "Tokyo"},
+                    "id": None,
+                },
+            ),
+        ]
+        mock_client_cls.return_value.aio.models.generate_content = AsyncMock(
+            return_value=_mock_completion(parts),
+        )
+
+        result = await self.model([])
+
+        self.assertEqual(
+            (result.is_last, result.content),
+            (
+                True,
+                [
+                    ToolCallBlock.model_construct(
+                        id=A,
+                        name="get_weather",
+                        input=json.dumps(
+                            {"city": "Tokyo"},
+                            ensure_ascii=False,
+                        ),
+                    ),
+                ],
+            ),
+        )
+        self.assertIsInstance(result.content[0].id, str)
+        self.assertTrue(result.content[0].id)
+
+    @patch("google.genai.Client")
+    async def test_thinking_response(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Non-stream response with reasoning creates ThinkingBlock."""
+        parts = [
+            _make_part(text="Let me think...", thought=True),
+            _make_part(text="Answer"),
+        ]
+        mock_client_cls.return_value.aio.models.generate_content = AsyncMock(
+            return_value=_mock_completion(parts),
+        )
+
+        result = await self.model([])
+
+        self.assertEqual(
+            (result.is_last, result.content),
+            (
+                True,
+                [
+                    ThinkingBlock.model_construct(
+                        id=A,
+                        thinking="Let me think...",
+                    ),
+                    TextBlock.model_construct(id=A, text="Answer"),
+                ],
+            ),
+        )
+
+
+# ---------------------------------------------------------------------------
+# Streaming tests
+# ---------------------------------------------------------------------------
+
+
+class TestGeminiStream(IsolatedAsyncioTestCase):
+    """Tests for GeminiChatModel in streaming mode."""
+
+    def setUp(self) -> None:
+        self.model = _make_model(stream=True)
+
+    @patch("google.genai.Client")
+    async def test_stream_text(self, mock_client_cls: MagicMock) -> None:
+        """Stream text yields n deltas + 1 final with full content."""
+        chunks = [
+            _make_stream_chunk([_make_part(text="Hello")]),
+            _make_stream_chunk([_make_part(text=" world")]),
+        ]
+        mock_client_cls.return_value.aio.models.generate_content_stream = (
+            AsyncMock(return_value=_MockAsyncStream(chunks))
+        )
+
+        gen = await self.model([])
+        responses = [r async for r in gen]
+
+        self.assertListEqual(
+            [(r.is_last, r.content) for r in responses],
+            [
+                (False, [TextBlock.model_construct(id=A, text="Hello")]),
+                (False, [TextBlock.model_construct(id=A, text=" world")]),
+                (True, [TextBlock.model_construct(id=A, text="Hello world")]),
+            ],
+        )
+
+    @patch("google.genai.Client")
+    async def test_stream_thinking_and_text(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Stream thinking + text yields deltas then accumulated final."""
+        chunks = [
+            _make_stream_chunk([_make_part(text="Think", thought=True)]),
+            _make_stream_chunk([_make_part(text="Answer")]),
+        ]
+        mock_client_cls.return_value.aio.models.generate_content_stream = (
+            AsyncMock(return_value=_MockAsyncStream(chunks))
+        )
+
+        gen = await self.model([])
+        responses = [r async for r in gen]
+
+        self.assertListEqual(
+            [(r.is_last, r.content) for r in responses],
+            [
+                (
+                    False,
+                    [ThinkingBlock.model_construct(id=A, thinking="Think")],
+                ),
+                (False, [TextBlock.model_construct(id=A, text="Answer")]),
+                (
+                    True,
+                    [
+                        ThinkingBlock.model_construct(id=A, thinking="Think"),
+                        TextBlock.model_construct(id=A, text="Answer"),
+                    ],
+                ),
+            ],
+        )
+
+    @patch("google.genai.Client")
+    async def test_stream_tool_call(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Stream tool call yields delta then final with same ToolCallBlock."""
+        chunks = [
+            _make_stream_chunk(
+                [
+                    _make_part(
+                        function_call={
+                            "name": "search",
+                            "args": {"q": "test"},
+                            "id": "call-1",
+                        },
+                    ),
+                ],
+            ),
+        ]
+        mock_client_cls.return_value.aio.models.generate_content_stream = (
+            AsyncMock(return_value=_MockAsyncStream(chunks))
+        )
+
+        gen = await self.model([])
+        responses = [r async for r in gen]
+
+        tool_block = ToolCallBlock(
+            id="call-1",
+            name="search",
+            input=json.dumps({"q": "test"}, ensure_ascii=False),
+        )
+        self.assertListEqual(
+            [(r.is_last, r.content) for r in responses],
+            [
+                (False, [tool_block]),
+                (True, [tool_block]),
+            ],
+        )
+
+    @patch("google.genai.Client")
+    async def test_stream_tool_calls_without_id(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Two id-less function calls in one chunk get distinct ids."""
+        chunks = [
+            _make_stream_chunk(
+                [
+                    _make_part(
+                        function_call={
+                            "name": "search",
+                            "args": {"q": "a"},
+                            "id": None,
+                        },
+                    ),
+                    _make_part(
+                        function_call={
+                            "name": "search",
+                            "args": {"q": "b"},
+                            "id": None,
+                        },
+                    ),
+                ],
+            ),
+        ]
+        mock_client_cls.return_value.aio.models.generate_content_stream = (
+            AsyncMock(return_value=_MockAsyncStream(chunks))
+        )
+
+        gen = await self.model([])
+        responses = [r async for r in gen]
+
+        final = responses[-1]
+        self.assertTrue(final.is_last)
+        self.assertEqual(len(final.content), 2)
+        ids = [block.id for block in final.content]
+        self.assertTrue(all(isinstance(i, str) and i for i in ids))
+        self.assertNotEqual(ids[0], ids[1])
+        self.assertEqual(
+            [block.input for block in final.content],
+            [
+                json.dumps({"q": "a"}, ensure_ascii=False),
+                json.dumps({"q": "b"}, ensure_ascii=False),
+            ],
+        )
+
+
+# ---------------------------------------------------------------------------
+# _format_tools tests
+# ---------------------------------------------------------------------------
+
+_FT_TOOLS = [
+    {
+        "type": "function",
+        "function": {
+            "name": "get_weather",
+            "description": "Get the weather",
+            "parameters": {
+                "type": "object",
+                "properties": {"city": {"type": "string"}},
+                "required": ["city"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "get_time",
+            "description": "Get the time",
+            "parameters": {
+                "type": "object",
+                "properties": {"timezone": {"type": "string"}},
+                "required": ["timezone"],
+            },
+        },
+    },
+]
+
+_FT_TOOLS_GEMINI = [
+    {
+        "function_declarations": [
+            {
+                "name": "get_weather",
+                "description": "Get the weather",
+                "parameters": {
+                    "type": "object",
+                    "properties": {"city": {"type": "string"}},
+                    "required": ["city"],
+                },
+            },
+            {
+                "name": "get_time",
+                "description": "Get the time",
+                "parameters": {
+                    "type": "object",
+                    "properties": {"timezone": {"type": "string"}},
+                    "required": ["timezone"],
+                },
+            },
+        ],
+    },
+]
+
+
+class TestGeminiFormatTools(unittest.TestCase):
+    """Tests for GeminiChatModel._format_tools."""
+
+    def setUp(self) -> None:
+        """Set up model instance."""
+        self.model = _make_model()
+
+    def test_auto_mode(self) -> None:
+        """Auto mode returns function_declarations and AUTO config."""
+        fmt_tools, fmt_choice = self.model._format_tools(
+            _FT_TOOLS,
+            ToolChoice(mode="auto"),
+        )
+        self.assertEqual(fmt_tools, _FT_TOOLS_GEMINI)
+        self.assertEqual(
+            fmt_choice,
+            {"function_calling_config": {"mode": "AUTO"}},
+        )
+
+    def test_none_mode(self) -> None:
+        """None mode returns function_declarations and NONE config."""
+        fmt_tools, fmt_choice = self.model._format_tools(
+            _FT_TOOLS,
+            ToolChoice(mode="none"),
+        )
+        self.assertEqual(fmt_tools, _FT_TOOLS_GEMINI)
+        self.assertEqual(
+            fmt_choice,
+            {"function_calling_config": {"mode": "NONE"}},
+        )
+
+    def test_required_mode(self) -> None:
+        """Required mode maps to ANY config."""
+        fmt_tools, fmt_choice = self.model._format_tools(
+            _FT_TOOLS,
+            ToolChoice(mode="required"),
+        )
+        self.assertEqual(fmt_tools, _FT_TOOLS_GEMINI)
+        self.assertEqual(
+            fmt_choice,
+            {"function_calling_config": {"mode": "ANY"}},
+        )
+
+    def test_str_mode_force_call(self) -> None:
+        """A specific tool name restricts via allowed_function_names."""
+        fmt_tools, fmt_choice = self.model._format_tools(
+            _FT_TOOLS,
+            ToolChoice(mode="get_weather"),
+        )
+        self.assertEqual(fmt_tools, _FT_TOOLS_GEMINI)
+        self.assertEqual(
+            fmt_choice,
+            {
+                "function_calling_config": {
+                    "mode": "ANY",
+                    "allowed_function_names": ["get_weather"],
+                },
+            },
+        )
+
+    def test_tools_filtered(self) -> None:
+        """When tool_choice.tools is set, only those tools are included."""
+        fmt_tools, _ = self.model._format_tools(
+            _FT_TOOLS,
+            ToolChoice(mode="auto", tools=["get_weather"]),
+        )
+        self.assertEqual(len(fmt_tools[0]["function_declarations"]), 1)
+        self.assertEqual(
+            fmt_tools[0]["function_declarations"][0]["name"],
+            "get_weather",
+        )
+
+    def test_no_tool_choice(self) -> None:
+        """Without tool_choice, returns function_declarations and None."""
+        fmt_tools, fmt_choice = self.model._format_tools(_FT_TOOLS, None)
+        self.assertEqual(fmt_tools, _FT_TOOLS_GEMINI)
+        self.assertIsNone(fmt_choice)
+
+
+# ---------------------------------------------------------------------------
+# Tests for _sanitize_schema_for_gemini and _flatten_json_schema
+# ---------------------------------------------------------------------------
+
+
+class TestGeminiSchemaUtils(unittest.TestCase):
+    """Tests for _sanitize_schema_for_gemini and _flatten_json_schema."""
+
+    def test_sanitize_removes_additional_properties_and_inlines_optional(
+        self,
+    ) -> None:
+        """additionalProperties removed; anyOf[X, null] inlined to X."""
+        self.assertEqual(
+            _sanitize_schema_for_gemini(
+                {
+                    "description": "x",
+                    "anyOf": [{"type": "string"}, {"type": "null"}],
+                },
+            ),
+            {"type": "string", "description": "x"},
+        )
+        self.assertEqual(
+            _sanitize_schema_for_gemini(
+                {"type": "object", "additionalProperties": False},
+            ),
+            {"type": "object"},
+        )
+
+    def test_sanitize_pydantic_optional_list_dict(self) -> None:
+        """End-to-end: Pydantic Optional[list[dict]] schema is cleaned."""
+        result = _sanitize_schema_for_gemini(
+            {
+                "type": "object",
+                "additionalProperties": False,
+                "properties": {
+                    "actions": {
+                        "description": "List of actions",
+                        "anyOf": [
+                            {
+                                "type": "array",
+                                "items": {
+                                    "type": "object",
+                                    "additionalProperties": True,
+                                },
+                            },
+                            {"type": "null"},
+                        ],
+                    },
+                },
+            },
+        )
+        self.assertEqual(
+            result,
+            {
+                "type": "object",
+                "properties": {
+                    "actions": {
+                        "type": "array",
+                        "description": "List of actions",
+                        "items": {"type": "object"},
+                    },
+                },
+            },
+        )
+
+    def test_sanitize_converts_const_to_enum(self) -> None:
+        """`const` is converted into a single-value `enum` for Gemini."""
+        self.assertEqual(
+            _sanitize_schema_for_gemini(
+                {
+                    "type": "object",
+                    "properties": {
+                        "topic": {"type": "string", "const": "general"},
+                        "query": {
+                            "type": "string",
+                            "description": "Search query",
+                        },
+                    },
+                    "required": ["query"],
+                },
+            ),
+            {
+                "type": "object",
+                "properties": {
+                    "topic": {"type": "string", "enum": ["general"]},
+                    "query": {
+                        "type": "string",
+                        "description": "Search query",
+                    },
+                },
+                "required": ["query"],
+            },
+        )
+
+    def test_flatten_resolves_ref_and_removes_defs(self) -> None:
+        """$ref inlined with extra keys merged; $defs removed."""
+        self.assertEqual(
+            _flatten_json_schema(
+                {
+                    "$defs": {"Name": {"type": "string"}},
+                    "properties": {
+                        "name": {
+                            "$ref": "#/$defs/Name",
+                            "description": "The name",
+                        },
+                    },
+                },
+            ),
+            {
+                "properties": {
+                    "name": {"type": "string", "description": "The name"},
+                },
+            },
+        )
+
+    def test_flatten_circular_ref_returns_placeholder(self) -> None:
+        """Circular $ref produces a placeholder without infinite recursion."""
+        self.assertEqual(
+            _flatten_json_schema(
+                {
+                    "$defs": {
+                        "Node": {
+                            "type": "object",
+                            "properties": {"child": {"$ref": "#/$defs/Node"}},
+                        },
+                    },
+                    "properties": {"root": {"$ref": "#/$defs/Node"}},
+                },
+            ),
+            {
+                "properties": {
+                    "root": {
+                        "type": "object",
+                        "properties": {
+                            "child": {
+                                "type": "object",
+                                "description": "(circular: Node)",
+                            },
+                        },
+                    },
+                },
+            },
+        )
+
+    def test_flatten_legacy_definitions_ref(self) -> None:
+        """Legacy 'definitions' keyword is resolved like '$defs'."""
+        self.assertEqual(
+            _flatten_json_schema(
+                {
+                    "definitions": {"Address": {"type": "string"}},
+                    "properties": {
+                        "addr": {"$ref": "#/definitions/Address"},
+                    },
+                },
+            ),
+            {
+                "properties": {
+                    "addr": {"type": "string"},
+                },
+            },
+        )
+
+    def test_flatten_no_defs_returns_same_object(self) -> None:
+        """Schema with no $defs/definitions is returned unchanged (
+        identity)."""
+        schema = {"type": "object", "properties": {"x": {"type": "integer"}}}
+        self.assertIs(_flatten_json_schema(schema), schema)
diff --git a/tests/model_moonshot_test.py b/tests/model_moonshot_test.py
new file mode 100644
index 0000000..a13cf8b
--- /dev/null
+++ b/tests/model_moonshot_test.py
@@ -0,0 +1,491 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Unit tests for MoonshotChatModel with mocked API responses.
+
+Tests cover both non-streaming and streaming modes.
+"""
+from typing import Any
+import unittest
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import AsyncMock, MagicMock, patch
+
+from utils import AnyString
+
+from agentscope.message import TextBlock, ToolCallBlock, ThinkingBlock
+from agentscope.model import MoonshotChatModel
+from agentscope.credential import MoonshotCredential
+from agentscope.tool import ToolChoice
+
+A = AnyString()
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_model(stream: bool = False) -> Any:
+    return MoonshotChatModel(
+        credential=MoonshotCredential(api_key="test"),
+        model="kimi-k2-5",
+        stream=stream,
+        context_size=131_072,
+    )
+
+
+def _mock_completion(
+    text: Any = None,
+    tool_calls: Any = None,
+    reasoning: Any = None,
+    response_id: str = "kimi-1",
+) -> MagicMock:
+    """Build a mock non-streaming ChatCompletion response."""
+    msg = MagicMock()
+    msg.content = text
+    msg.reasoning_content = reasoning
+    msg.tool_calls = None
+
+    if tool_calls:
+        tc_mocks = []
+        for tc in tool_calls:
+            m = MagicMock()
+            m.id = tc["id"]
+            m.function.name = tc["name"]
+            m.function.arguments = tc["arguments"]
+            tc_mocks.append(m)
+        msg.tool_calls = tc_mocks
+
+    choice = MagicMock()
+    choice.message = msg
+
+    resp = MagicMock()
+    resp.id = response_id
+    resp.choices = [choice]
+    resp.usage.prompt_tokens = 10
+    resp.usage.completion_tokens = 5
+    resp.usage.cached_tokens = 0
+    return resp
+
+
+def _make_stream_chunk(
+    delta_text: str | None = None,
+    delta_reasoning: str | None = None,
+    tool_calls: list | None = None,
+    response_id: str = "kimi-1",
+    usage: dict | None = None,
+    has_choices: bool = True,
+) -> MagicMock:
+    """Build a single mock streaming chunk."""
+    chunk = MagicMock()
+    chunk.id = response_id
+
+    if usage:
+        chunk.usage = MagicMock()
+        chunk.usage.prompt_tokens = usage.get("prompt_tokens", 0)
+        chunk.usage.completion_tokens = usage.get("completion_tokens", 0)
+        chunk.usage.cached_tokens = usage.get("cached_tokens", 0)
+    else:
+        chunk.usage = None
+
+    if has_choices:
+        delta = MagicMock()
+        delta.content = delta_text
+        delta.reasoning_content = delta_reasoning
+        delta.tool_calls = tool_calls
+        choice = MagicMock()
+        choice.delta = delta
+        chunk.choices = [choice]
+    else:
+        chunk.choices = []
+
+    return chunk
+
+
+def _make_tool_call_delta(
+    index: int,
+    tc_id: str | None = None,
+    name: str | None = None,
+    arguments: str | None = None,
+) -> MagicMock:
+    tc = MagicMock()
+    tc.index = index
+    tc.id = tc_id
+    tc.function.name = name
+    tc.function.arguments = arguments
+    return tc
+
+
+class _MockAsyncStream:
+    """Mock async stream (context manager + async iterator)."""
+
+    def __init__(self, chunks: list) -> None:
+        self._chunks = chunks
+        self._index = 0
+
+    async def __aenter__(self) -> "_MockAsyncStream":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        pass
+
+    def __aiter__(self) -> "_MockAsyncStream":
+        return self
+
+    async def __anext__(self) -> Any:
+        if self._index >= len(self._chunks):
+            raise StopAsyncIteration
+        chunk = self._chunks[self._index]
+        self._index += 1
+        return chunk
+
+
+# ---------------------------------------------------------------------------
+# Non-streaming tests
+# ---------------------------------------------------------------------------
+
+
+class TestMoonshotNonStream(IsolatedAsyncioTestCase):
+    """Tests for MoonshotChatModel in non-streaming mode."""
+
+    def setUp(self) -> None:
+        self.model = _make_model(stream=False)
+
+    @patch("openai.AsyncClient")
+    async def test_text_response(self, mock_client_cls: MagicMock) -> None:
+        """Non-stream text response returns a single ChatResponse."""
+        mock_create = AsyncMock(
+            return_value=_mock_completion(text="Hello!"),
+        )
+        mock_client_cls.return_value.chat.completions.create = mock_create
+
+        result = await self.model([])
+
+        self.assertEqual(
+            (result.is_last, result.content),
+            (True, [TextBlock.model_construct(id=A, text="Hello!")]),
+        )
+        self.assertEqual(result.id, "kimi-1")
+
+    @patch("openai.AsyncClient")
+    async def test_tool_call_response(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Non-stream tool call response creates ToolCallBlocks."""
+        mock_create = AsyncMock(
+            return_value=_mock_completion(
+                tool_calls=[
+                    {
+                        "id": "call-1",
+                        "name": "get_weather",
+                        "arguments": '{"city":"Shanghai"}',
+                    },
+                ],
+            ),
+        )
+        mock_client_cls.return_value.chat.completions.create = mock_create
+
+        result = await self.model([])
+
+        self.assertEqual(
+            (result.is_last, result.content),
+            (
+                True,
+                [
+                    ToolCallBlock(
+                        id="call-1",
+                        name="get_weather",
+                        input='{"city":"Shanghai"}',
+                    ),
+                ],
+            ),
+        )
+
+    @patch("openai.AsyncClient")
+    async def test_thinking_response(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Non-stream response with reasoning creates ThinkingBlock."""
+        mock_create = AsyncMock(
+            return_value=_mock_completion(
+                text="42",
+                reasoning="Step by step...",
+            ),
+        )
+        mock_client_cls.return_value.chat.completions.create = mock_create
+
+        result = await self.model([])
+
+        self.assertEqual(
+            (result.is_last, result.content),
+            (
+                True,
+                [
+                    ThinkingBlock.model_construct(
+                        id=A,
+                        thinking="Step by step...",
+                    ),
+                    TextBlock.model_construct(id=A, text="42"),
+                ],
+            ),
+        )
+
+
+class TestKimiModelParameters(unittest.TestCase):
+    """Tests for MoonshotChatModel.Parameters."""
+
+    def test_thinking_enable_stored_on_model(self) -> None:
+        """thinking_enable is accessible through model.parameters."""
+        model = MoonshotChatModel(
+            credential=MoonshotCredential(api_key="test"),
+            model="kimi-k2-5",
+            stream=False,
+            context_size=131_072,
+            parameters=MoonshotChatModel.Parameters(thinking_enable=True),
+        )
+        self.assertTrue(model.parameters.thinking_enable)
+
+
+# ---------------------------------------------------------------------------
+# Streaming tests
+# ---------------------------------------------------------------------------
+
+
+class TestMoonshotStream(IsolatedAsyncioTestCase):
+    """Tests for MoonshotChatModel in streaming mode."""
+
+    def setUp(self) -> None:
+        self.model = _make_model(stream=True)
+
+    @patch("openai.AsyncClient")
+    async def test_stream_text(self, mock_client_cls: MagicMock) -> None:
+        """Stream text yields n deltas (is_last=False) + 1 final
+        (is_last=True) with full content."""
+        chunks = [
+            _make_stream_chunk(delta_text="Hi"),
+            _make_stream_chunk(delta_text=" there"),
+            _make_stream_chunk(
+                has_choices=False,
+                usage={"prompt_tokens": 10, "completion_tokens": 2},
+            ),
+        ]
+        mock_create = AsyncMock(return_value=_MockAsyncStream(chunks))
+        mock_client_cls.return_value.chat.completions.create = mock_create
+
+        gen = await self.model([])
+        responses = [r async for r in gen]
+
+        self.assertListEqual(
+            [(r.is_last, r.content) for r in responses],
+            [
+                (False, [TextBlock.model_construct(id=A, text="Hi")]),
+                (False, [TextBlock.model_construct(id=A, text=" there")]),
+                (True, [TextBlock.model_construct(id=A, text="Hi there")]),
+            ],
+        )
+
+    @patch("openai.AsyncClient")
+    async def test_stream_thinking_then_text(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Moonshot yields thinking chunks separately before text."""
+        chunks = [
+            _make_stream_chunk(delta_reasoning="Let me"),
+            _make_stream_chunk(delta_reasoning=" think"),
+            _make_stream_chunk(delta_text="Result"),
+            _make_stream_chunk(
+                has_choices=False,
+                usage={"prompt_tokens": 10, "completion_tokens": 5},
+            ),
+        ]
+        mock_create = AsyncMock(return_value=_MockAsyncStream(chunks))
+        mock_client_cls.return_value.chat.completions.create = mock_create
+
+        gen = await self.model([])
+        responses = [r async for r in gen]
+
+        self.assertListEqual(
+            [(r.is_last, r.content) for r in responses],
+            [
+                (
+                    False,
+                    [ThinkingBlock.model_construct(id=A, thinking="Let me")],
+                ),
+                (
+                    False,
+                    [ThinkingBlock.model_construct(id=A, thinking=" think")],
+                ),
+                (False, [TextBlock.model_construct(id=A, text="Result")]),
+                (
+                    True,
+                    [
+                        ThinkingBlock.model_construct(
+                            id=A,
+                            thinking="Let me think",
+                        ),
+                        TextBlock.model_construct(id=A, text="Result"),
+                    ],
+                ),
+            ],
+        )
+
+    @patch("openai.AsyncClient")
+    async def test_stream_tool_calls(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Stream tool calls accumulate across chunks into final response."""
+        chunks = [
+            _make_stream_chunk(
+                tool_calls=[
+                    _make_tool_call_delta(0, "call-1", "search", '{"q":'),
+                ],
+            ),
+            _make_stream_chunk(
+                tool_calls=[
+                    _make_tool_call_delta(0, None, None, '"test"}'),
+                ],
+            ),
+            _make_stream_chunk(
+                has_choices=False,
+                usage={"prompt_tokens": 10, "completion_tokens": 5},
+            ),
+        ]
+        mock_create = AsyncMock(return_value=_MockAsyncStream(chunks))
+        mock_client_cls.return_value.chat.completions.create = mock_create
+
+        gen = await self.model([])
+        responses = [r async for r in gen]
+
+        self.assertListEqual(
+            [(r.is_last, r.content) for r in responses],
+            [
+                (
+                    False,
+                    [
+                        ToolCallBlock(
+                            id="call-1",
+                            name="search",
+                            input='{"q":',
+                        ),
+                    ],
+                ),
+                (
+                    False,
+                    [
+                        ToolCallBlock(
+                            id="call-1",
+                            name="search",
+                            input='"test"}',
+                        ),
+                    ],
+                ),
+                (
+                    True,
+                    [
+                        ToolCallBlock(
+                            id="call-1",
+                            name="search",
+                            input='{"q":"test"}',
+                        ),
+                    ],
+                ),
+            ],
+        )
+
+
+# ---------------------------------------------------------------------------
+# _format_tools tests
+# ---------------------------------------------------------------------------
+
+_FT_TOOLS = [
+    {
+        "type": "function",
+        "function": {
+            "name": "get_weather",
+            "description": "Get the weather",
+            "parameters": {
+                "type": "object",
+                "properties": {"city": {"type": "string"}},
+                "required": ["city"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "get_time",
+            "description": "Get the time",
+            "parameters": {
+                "type": "object",
+                "properties": {"timezone": {"type": "string"}},
+                "required": ["timezone"],
+            },
+        },
+    },
+]
+
+
+class TestMoonshotFormatTools(unittest.TestCase):
+    """Tests for MoonshotChatModel._format_tools."""
+
+    def setUp(self) -> None:
+        """Set up model instance."""
+        self.model = _make_model()
+
+    def test_auto_mode(self) -> None:
+        """Auto mode returns tools unchanged and string 'auto'."""
+        fmt_tools, fmt_choice = self.model._format_tools(
+            _FT_TOOLS,
+            ToolChoice(mode="auto"),
+        )
+        self.assertEqual(fmt_tools, _FT_TOOLS)
+        self.assertEqual(fmt_choice, "auto")
+
+    def test_none_mode(self) -> None:
+        """None mode returns tools unchanged and string 'none'."""
+        fmt_tools, fmt_choice = self.model._format_tools(
+            _FT_TOOLS,
+            ToolChoice(mode="none"),
+        )
+        self.assertEqual(fmt_tools, _FT_TOOLS)
+        self.assertEqual(fmt_choice, "none")
+
+    def test_required_mode(self) -> None:
+        """Required mode returns tools unchanged and string 'required'."""
+        fmt_tools, fmt_choice = self.model._format_tools(
+            _FT_TOOLS,
+            ToolChoice(mode="required"),
+        )
+        self.assertEqual(fmt_tools, _FT_TOOLS)
+        self.assertEqual(fmt_choice, "required")
+
+    def test_str_mode_force_call(self) -> None:
+        """A specific tool name returns a type=function dict."""
+        fmt_tools, fmt_choice = self.model._format_tools(
+            _FT_TOOLS,
+            ToolChoice(mode="get_weather"),
+        )
+        self.assertEqual(fmt_tools, _FT_TOOLS)
+        self.assertEqual(
+            fmt_choice,
+            {"type": "function", "function": {"name": "get_weather"}},
+        )
+
+    def test_tools_filtered(self) -> None:
+        """When tool_choice.tools is set, only those tools are included."""
+        fmt_tools, fmt_choice = self.model._format_tools(
+            _FT_TOOLS,
+            ToolChoice(mode="auto", tools=["get_weather"]),
+        )
+        self.assertEqual(len(fmt_tools), 1)
+        self.assertEqual(fmt_tools[0]["function"]["name"], "get_weather")
+        self.assertEqual(fmt_choice, "auto")
+
+    def test_no_tool_choice(self) -> None:
+        """Without tool_choice, returns tools and None."""
+        fmt_tools, fmt_choice = self.model._format_tools(_FT_TOOLS, None)
+        self.assertEqual(fmt_tools, _FT_TOOLS)
+        self.assertIsNone(fmt_choice)
diff --git a/tests/model_ollama_test.py b/tests/model_ollama_test.py
new file mode 100644
index 0000000..fc7dd96
--- /dev/null
+++ b/tests/model_ollama_test.py
@@ -0,0 +1,365 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Unit tests for OllamaChatModel with mocked API responses.
+
+Tests cover both non-streaming and streaming modes.
+Ollama uses ollama.AsyncClient with async iterator streaming.
+"""
+import json
+from typing import Any
+import unittest
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import AsyncMock, MagicMock, patch
+
+from utils import AnyString
+
+from agentscope.message import TextBlock, ToolCallBlock, ThinkingBlock
+from agentscope.model import OllamaChatModel
+from agentscope.tool import ToolChoice
+
+A = AnyString()
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_model(stream: bool = False) -> Any:
+    return OllamaChatModel(
+        model="qwen3:8b",
+        stream=stream,
+        context_size=40_960,
+    )
+
+
+def _mock_completion(
+    content: str = "",
+    thinking: str | None = None,
+    tool_calls: list | None = None,
+) -> MagicMock:
+    """Build a mock non-streaming Ollama response."""
+    msg = MagicMock()
+    msg.content = content
+    msg.thinking = thinking
+
+    if tool_calls:
+        tc_mocks = []
+        for tc in tool_calls:
+            m = MagicMock()
+            m.function.name = tc["name"]
+            m.function.arguments = tc["args"]
+            tc_mocks.append(m)
+        msg.tool_calls = tc_mocks
+    else:
+        msg.tool_calls = None
+
+    resp = MagicMock()
+    resp.message = msg
+    resp.prompt_eval_count = 10
+    resp.eval_count = 5
+    resp.id = None
+    return resp
+
+
+def _make_stream_chunk(
+    content: str = "",
+    thinking: str | None = None,
+    tool_calls: list | None = None,
+) -> MagicMock:
+    """Build a single mock Ollama streaming chunk."""
+    msg = MagicMock()
+    msg.content = content
+    msg.thinking = thinking
+
+    if tool_calls:
+        tc_mocks = []
+        for tc in tool_calls:
+            m = MagicMock()
+            m.function.name = tc["name"]
+            m.function.arguments = tc["args"]
+            tc_mocks.append(m)
+        msg.tool_calls = tc_mocks
+    else:
+        msg.tool_calls = None
+
+    chunk = MagicMock()
+    chunk.message = msg
+    chunk.prompt_eval_count = 10
+    chunk.eval_count = 5
+    chunk.id = None
+    return chunk
+
+
+class _MockAsyncStream:
+    """Mock async iterator for Ollama stream."""
+
+    def __init__(self, chunks: list) -> None:
+        self._chunks = chunks
+        self._index = 0
+
+    def __aiter__(self) -> "_MockAsyncStream":
+        return self
+
+    async def __anext__(self) -> Any:
+        if self._index >= len(self._chunks):
+            raise StopAsyncIteration
+        chunk = self._chunks[self._index]
+        self._index += 1
+        return chunk
+
+
+# ---------------------------------------------------------------------------
+# Non-streaming tests
+# ---------------------------------------------------------------------------
+
+
+class TestOllamaNonStream(IsolatedAsyncioTestCase):
+    """Tests for OllamaChatModel in non-streaming mode."""
+
+    def setUp(self) -> None:
+        self.model = _make_model(stream=False)
+
+    @patch("ollama.AsyncClient")
+    async def test_text_response(self, mock_client_cls: MagicMock) -> None:
+        """Non-stream text response returns a single ChatResponse."""
+        mock_client_cls.return_value.chat = AsyncMock(
+            return_value=_mock_completion(content="Hello!"),
+        )
+
+        result = await self.model([])
+
+        self.assertEqual(
+            (result.is_last, result.content),
+            (True, [TextBlock.model_construct(id=A, text="Hello!")]),
+        )
+
+    @patch("ollama.AsyncClient")
+    async def test_tool_call_response(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Parsing a tool-call response creates a ToolCallBlock."""
+        mock_client_cls.return_value.chat = AsyncMock(
+            return_value=_mock_completion(
+                tool_calls=[
+                    {"name": "get_weather", "args": {"city": "SH"}},
+                ],
+            ),
+        )
+
+        result = await self.model([])
+
+        self.assertEqual(
+            (result.is_last, result.content),
+            (
+                True,
+                [
+                    ToolCallBlock(
+                        id="0_get_weather",
+                        name="get_weather",
+                        input=json.dumps({"city": "SH"}),
+                    ),
+                ],
+            ),
+        )
+
+    @patch("ollama.AsyncClient")
+    async def test_thinking_response(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Non-stream thinking plus text returns ThinkingBlock then
+        TextBlock."""
+        mock_client_cls.return_value.chat = AsyncMock(
+            return_value=_mock_completion(
+                content="Answer",
+                thinking="Let me think...",
+            ),
+        )
+
+        result = await self.model([])
+
+        self.assertEqual(
+            (result.is_last, result.content),
+            (
+                True,
+                [
+                    ThinkingBlock.model_construct(
+                        id=A,
+                        thinking="Let me think...",
+                    ),
+                    TextBlock.model_construct(id=A, text="Answer"),
+                ],
+            ),
+        )
+
+
+# ---------------------------------------------------------------------------
+# Streaming tests
+# ---------------------------------------------------------------------------
+
+
+class TestOllamaStream(IsolatedAsyncioTestCase):
+    """Tests for OllamaChatModel in streaming mode."""
+
+    def setUp(self) -> None:
+        self.model = _make_model(stream=True)
+
+    @patch("ollama.AsyncClient")
+    async def test_stream_text(self, mock_client_cls: MagicMock) -> None:
+        """Stream text yields deltas then final with full content."""
+        chunks = [
+            _make_stream_chunk(content="Hi"),
+            _make_stream_chunk(content=" there"),
+        ]
+        mock_client_cls.return_value.chat = AsyncMock(
+            return_value=_MockAsyncStream(chunks),
+        )
+
+        gen = await self.model([])
+        responses = [r async for r in gen]
+
+        self.assertListEqual(
+            [(r.is_last, r.content) for r in responses],
+            [
+                (False, [TextBlock.model_construct(id=A, text="Hi")]),
+                (False, [TextBlock.model_construct(id=A, text=" there")]),
+                (True, [TextBlock.model_construct(id=A, text="Hi there")]),
+            ],
+        )
+
+    @patch("ollama.AsyncClient")
+    async def test_stream_thinking_and_text(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Stream thinking and text deltas then final with accumulated
+        content."""
+        chunks = [
+            _make_stream_chunk(thinking="Think step"),
+            _make_stream_chunk(content="Result"),
+        ]
+        mock_client_cls.return_value.chat = AsyncMock(
+            return_value=_MockAsyncStream(chunks),
+        )
+
+        gen = await self.model([])
+        responses = [r async for r in gen]
+
+        self.assertListEqual(
+            [(r.is_last, r.content) for r in responses],
+            [
+                (
+                    False,
+                    [
+                        ThinkingBlock.model_construct(
+                            id=A,
+                            thinking="Think step",
+                        ),
+                    ],
+                ),
+                (False, [TextBlock.model_construct(id=A, text="Result")]),
+                (
+                    True,
+                    [
+                        ThinkingBlock.model_construct(
+                            id=A,
+                            thinking="Think step",
+                        ),
+                        TextBlock.model_construct(id=A, text="Result"),
+                    ],
+                ),
+            ],
+        )
+
+    @patch("ollama.AsyncClient")
+    async def test_stream_tool_call(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Stream tool-call chunk yields delta then final with same
+        ToolCallBlock."""
+        chunks = [
+            _make_stream_chunk(
+                tool_calls=[
+                    {"name": "search", "args": {"q": "hello"}},
+                ],
+            ),
+        ]
+        mock_client_cls.return_value.chat = AsyncMock(
+            return_value=_MockAsyncStream(chunks),
+        )
+
+        gen = await self.model([])
+        responses = [r async for r in gen]
+
+        tool_block = ToolCallBlock(
+            id="0_search",
+            name="search",
+            input=json.dumps({"q": "hello"}),
+        )
+        self.assertListEqual(
+            [(r.is_last, r.content) for r in responses],
+            [
+                (False, [tool_block]),
+                (True, [tool_block]),
+            ],
+        )
+
+
+# ---------------------------------------------------------------------------
+# _format_tools tests
+# ---------------------------------------------------------------------------
+
+_FT_TOOLS = [
+    {
+        "type": "function",
+        "function": {
+            "name": "get_weather",
+            "description": "Get the weather",
+            "parameters": {
+                "type": "object",
+                "properties": {"city": {"type": "string"}},
+                "required": ["city"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "get_time",
+            "description": "Get the time",
+            "parameters": {
+                "type": "object",
+                "properties": {"timezone": {"type": "string"}},
+                "required": ["timezone"],
+            },
+        },
+    },
+]
+
+
+class TestOllamaFormatTools(unittest.TestCase):
+    """Tests for OllamaChatModel._format_tools."""
+
+    def setUp(self) -> None:
+        self.model = _make_model()
+
+    def test_tools_forwarded_no_choice(self) -> None:
+        """Tools are forwarded unchanged when tool_choice is None."""
+        fmt_tools, fmt_choice = self.model._format_tools(_FT_TOOLS, None)
+        self.assertEqual(fmt_tools, _FT_TOOLS)
+        self.assertIsNone(fmt_choice)
+
+    def test_tools_filtered(self) -> None:
+        """ToolChoice with tools list filters to matching function names."""
+        fmt_tools, fmt_choice = self.model._format_tools(
+            _FT_TOOLS,
+            ToolChoice(mode="auto", tools=["get_weather"]),
+        )
+        self.assertIsNotNone(fmt_tools)
+        assert fmt_tools is not None
+        self.assertEqual(len(fmt_tools), 1)
+        self.assertEqual(fmt_tools[0]["function"]["name"], "get_weather")
+        self.assertIsNone(fmt_choice)
diff --git a/tests/model_openai_chat_test.py b/tests/model_openai_chat_test.py
new file mode 100644
index 0000000..1060240
--- /dev/null
+++ b/tests/model_openai_chat_test.py
@@ -0,0 +1,769 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Unit tests for OpenAIChatModel with mocked API responses.
+
+Tests cover both non-streaming and streaming modes, verifying that:
+- Non-stream mode returns a single ChatResponse with is_last=True.
+- Stream mode yields n delta ChatResponses (is_last=False) followed by
+  1 final ChatResponse (is_last=True) with the full accumulated content.
+"""
+import base64
+import io
+import wave
+from typing import Any
+import unittest
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import AsyncMock, MagicMock, patch
+
+from utils import AnyString
+
+from agentscope.message import (
+    TextBlock,
+    ToolCallBlock,
+    ThinkingBlock,
+    DataBlock,
+    Base64Source,
+)
+from agentscope.model import OpenAIChatModel
+from agentscope.credential import OpenAICredential
+from agentscope.tool import ToolChoice
+
+A = AnyString()
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_model(stream: bool = False) -> Any:
+    return OpenAIChatModel(
+        credential=OpenAICredential(api_key="test"),
+        model="gpt-4o",
+        stream=stream,
+        context_size=128_000,
+    )
+
+
+def _mock_completion(
+    text: Any = None,
+    tool_calls: Any = None,
+    reasoning: Any = None,
+    response_id: str = "resp-1",
+    audio: dict | None = None,
+) -> MagicMock:
+    """Build a mock non-streaming ChatCompletion response."""
+    msg = MagicMock()
+    msg.content = text
+    msg.reasoning_content = reasoning
+    msg.reasoning = None
+    msg.audio = audio
+    msg.tool_calls = None
+
+    if tool_calls:
+        tc_mocks = []
+        for tc in tool_calls:
+            m = MagicMock()
+            m.id = tc["id"]
+            m.function.name = tc["name"]
+            m.function.arguments = tc["arguments"]
+            tc_mocks.append(m)
+        msg.tool_calls = tc_mocks
+
+    choice = MagicMock()
+    choice.message = msg
+
+    resp = MagicMock()
+    resp.id = response_id
+    resp.choices = [choice]
+    resp.usage.prompt_tokens = 10
+    resp.usage.completion_tokens = 5
+    resp.usage.prompt_tokens_details = None
+    return resp
+
+
+def _make_stream_chunk(
+    delta_text: str | None = None,
+    delta_reasoning: str | None = None,
+    tool_calls: list | None = None,
+    response_id: str = "resp-1",
+    usage: dict | None = None,
+    has_choices: bool = True,
+    delta_audio: dict | None = None,
+) -> MagicMock:
+    """Build a single mock streaming chunk."""
+    chunk = MagicMock()
+    chunk.id = response_id
+
+    if usage:
+        chunk.usage = MagicMock()
+        chunk.usage.prompt_tokens = usage.get("prompt_tokens", 0)
+        chunk.usage.completion_tokens = usage.get("completion_tokens", 0)
+        chunk.usage.prompt_tokens_details = None
+    else:
+        chunk.usage = None
+
+    if has_choices:
+        delta = MagicMock()
+        delta.content = delta_text
+        delta.reasoning_content = delta_reasoning
+        delta.reasoning = None
+        delta.audio = delta_audio
+        delta.tool_calls = tool_calls
+        choice = MagicMock()
+        choice.delta = delta
+        chunk.choices = [choice]
+    else:
+        chunk.choices = []
+
+    return chunk
+
+
+def _make_tool_call_delta(
+    index: int,
+    tc_id: str | None = None,
+    name: str | None = None,
+    arguments: str | None = None,
+) -> MagicMock:
+    """Build a tool_call delta item for streaming."""
+    tc = MagicMock()
+    tc.index = index
+    tc.id = tc_id
+    tc.function.name = name
+    tc.function.arguments = arguments
+    return tc
+
+
+class _MockAsyncStream:
+    """Mock async stream that acts as an async context manager + iterator."""
+
+    def __init__(self, chunks: list) -> None:
+        self._chunks = chunks
+        self._index = 0
+
+    async def __aenter__(self) -> "_MockAsyncStream":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        pass
+
+    def __aiter__(self) -> "_MockAsyncStream":
+        return self
+
+    async def __anext__(self) -> Any:
+        if self._index >= len(self._chunks):
+            raise StopAsyncIteration
+        chunk = self._chunks[self._index]
+        self._index += 1
+        return chunk
+
+
+# ---------------------------------------------------------------------------
+# Non-streaming tests
+# ---------------------------------------------------------------------------
+
+
+class TestOpenAIChatNonStream(IsolatedAsyncioTestCase):
+    """Tests for OpenAIChatModel in non-streaming mode."""
+
+    def setUp(self) -> None:
+        self.model = _make_model(stream=False)
+
+    @patch("openai.AsyncClient")
+    async def test_text_response(self, mock_client_cls: MagicMock) -> None:
+        """Non-stream text response returns a single ChatResponse."""
+        mock_create = AsyncMock(
+            return_value=_mock_completion(text="Hello world!"),
+        )
+        mock_client_cls.return_value.chat.completions.create = mock_create
+
+        result = await self.model([])
+
+        self.assertEqual(
+            (result.is_last, result.content),
+            (True, [TextBlock.model_construct(id=A, text="Hello world!")]),
+        )
+        self.assertEqual(result.id, "resp-1")
+
+    @patch("openai.AsyncClient")
+    async def test_default_thinking_enable_not_forwarded(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Default parameters do not add provider-specific extra_body."""
+        mock_create = AsyncMock(
+            return_value=_mock_completion(text="Hello world!"),
+        )
+        mock_client_cls.return_value.chat.completions.create = mock_create
+
+        await self.model([])
+
+        self.assertNotIn("extra_body", mock_create.call_args.kwargs)
+
+    @patch("openai.AsyncClient")
+    async def test_constructor_extra_body_forwarded(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Custom request fields are forwarded to OpenAI-compatible APIs."""
+        model = OpenAIChatModel(
+            credential=OpenAICredential(api_key="test"),
+            model="custom-model",
+            stream=False,
+            context_size=128_000,
+            extra_body={"enable_thinking": False},
+        )
+        mock_create = AsyncMock(
+            return_value=_mock_completion(text="Hello world!"),
+        )
+        mock_client_cls.return_value.chat.completions.create = mock_create
+
+        await model([])
+
+        self.assertEqual(
+            mock_create.call_args.kwargs["extra_body"],
+            {"enable_thinking": False},
+        )
+
+    @patch("openai.AsyncClient")
+    async def test_generate_kwargs_extra_body_overrides_constructor(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Per-call extra_body overrides the constructor default."""
+        model = OpenAIChatModel(
+            credential=OpenAICredential(api_key="test"),
+            model="custom-model",
+            stream=False,
+            context_size=128_000,
+            extra_body={"enable_thinking": False},
+        )
+        mock_create = AsyncMock(
+            return_value=_mock_completion(text="Hello world!"),
+        )
+        mock_client_cls.return_value.chat.completions.create = mock_create
+
+        await model([], extra_body={"custom_option": "value"})
+
+        self.assertEqual(
+            mock_create.call_args.kwargs["extra_body"],
+            {"custom_option": "value"},
+        )
+
+    @patch("openai.AsyncClient")
+    async def test_tool_call_response(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Non-stream tool call response creates ToolCallBlocks."""
+        mock_create = AsyncMock(
+            return_value=_mock_completion(
+                tool_calls=[
+                    {
+                        "id": "call-1",
+                        "name": "get_weather",
+                        "arguments": '{"city":"Beijing"}',
+                    },
+                ],
+            ),
+        )
+        mock_client_cls.return_value.chat.completions.create = mock_create
+
+        result = await self.model([])
+
+        self.assertEqual(
+            (result.is_last, result.content),
+            (
+                True,
+                [
+                    ToolCallBlock(
+                        id="call-1",
+                        name="get_weather",
+                        input='{"city":"Beijing"}',
+                    ),
+                ],
+            ),
+        )
+
+    @patch("openai.AsyncClient")
+    async def test_audio_response(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Non-stream audio-only output yields transcript TextBlock + audio
+        DataBlock."""
+        mock_create = AsyncMock(
+            return_value=_mock_completion(
+                text=None,
+                audio={
+                    "data": "QUJDREVG",
+                    "transcript": "Hello from audio.",
+                },
+            ),
+        )
+        mock_client_cls.return_value.chat.completions.create = mock_create
+
+        result = await self.model([])
+
+        self.assertEqual(
+            (result.is_last, result.content),
+            (
+                True,
+                [
+                    TextBlock.model_construct(
+                        id=A,
+                        text="Hello from audio.",
+                    ),
+                    DataBlock.model_construct(
+                        id=A,
+                        source=Base64Source.model_construct(
+                            type="base64",
+                            media_type="audio/wav",
+                            data="QUJDREVG",
+                        ),
+                    ),
+                ],
+            ),
+        )
+
+    @patch("openai.AsyncClient")
+    async def test_thinking_response(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Non-stream response with reasoning creates ThinkingBlock."""
+        mock_create = AsyncMock(
+            return_value=_mock_completion(
+                text="The answer is 42.",
+                reasoning="Let me think step by step...",
+            ),
+        )
+        mock_client_cls.return_value.chat.completions.create = mock_create
+
+        result = await self.model([])
+
+        self.assertEqual(
+            (result.is_last, result.content),
+            (
+                True,
+                [
+                    ThinkingBlock.model_construct(
+                        id=A,
+                        thinking="Let me think step by step...",
+                    ),
+                    TextBlock.model_construct(id=A, text="The answer is 42."),
+                ],
+            ),
+        )
+
+
+# ---------------------------------------------------------------------------
+# Streaming tests
+# ---------------------------------------------------------------------------
+
+
+class TestOpenAIChatStream(IsolatedAsyncioTestCase):
+    """Tests for OpenAIChatModel in streaming mode."""
+
+    def setUp(self) -> None:
+        self.model = _make_model(stream=True)
+
+    @patch("openai.AsyncClient")
+    async def test_stream_text_response(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Stream text yields n deltas (is_last=False) + 1 final
+        (is_last=True) with full content."""
+        chunks = [
+            _make_stream_chunk(delta_text="Hello"),
+            _make_stream_chunk(delta_text=" world"),
+            _make_stream_chunk(delta_text="!"),
+            _make_stream_chunk(
+                has_choices=False,
+                usage={"prompt_tokens": 10, "completion_tokens": 3},
+            ),
+        ]
+        mock_create = AsyncMock(return_value=_MockAsyncStream(chunks))
+        mock_client_cls.return_value.chat.completions.create = mock_create
+
+        gen = await self.model([])
+        responses = [r async for r in gen]
+
+        self.assertListEqual(
+            [(r.is_last, r.content) for r in responses],
+            [
+                (False, [TextBlock.model_construct(id=A, text="Hello")]),
+                (False, [TextBlock.model_construct(id=A, text=" world")]),
+                (False, [TextBlock.model_construct(id=A, text="!")]),
+                (True, [TextBlock.model_construct(id=A, text="Hello world!")]),
+            ],
+        )
+        self.assertEqual(responses[-1].id, "resp-1")
+
+    @patch("openai.AsyncClient")
+    async def test_stream_thinking_and_text(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Stream with thinking + text yields deltas then final with both."""
+        chunks = [
+            _make_stream_chunk(delta_reasoning="Think"),
+            _make_stream_chunk(delta_reasoning="ing..."),
+            _make_stream_chunk(delta_text="Answer"),
+            _make_stream_chunk(
+                has_choices=False,
+                usage={"prompt_tokens": 10, "completion_tokens": 8},
+            ),
+        ]
+        mock_create = AsyncMock(return_value=_MockAsyncStream(chunks))
+        mock_client_cls.return_value.chat.completions.create = mock_create
+
+        gen = await self.model([])
+        responses = [r async for r in gen]
+
+        self.assertListEqual(
+            [(r.is_last, r.content) for r in responses],
+            [
+                (
+                    False,
+                    [ThinkingBlock.model_construct(id=A, thinking="Think")],
+                ),
+                (
+                    False,
+                    [ThinkingBlock.model_construct(id=A, thinking="ing...")],
+                ),
+                (False, [TextBlock.model_construct(id=A, text="Answer")]),
+                (
+                    True,
+                    [
+                        ThinkingBlock.model_construct(
+                            id=A,
+                            thinking="Thinking...",
+                        ),
+                        TextBlock.model_construct(id=A, text="Answer"),
+                    ],
+                ),
+            ],
+        )
+
+    @patch("openai.AsyncClient")
+    async def test_stream_tool_calls(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Stream tool calls accumulate across chunks into final response."""
+        chunks = [
+            _make_stream_chunk(
+                tool_calls=[
+                    _make_tool_call_delta(0, "call-1", "get_weather", '{"ci'),
+                ],
+            ),
+            _make_stream_chunk(
+                tool_calls=[
+                    _make_tool_call_delta(0, None, None, 'ty":"BJ"}'),
+                ],
+            ),
+            _make_stream_chunk(
+                has_choices=False,
+                usage={"prompt_tokens": 10, "completion_tokens": 5},
+            ),
+        ]
+        mock_create = AsyncMock(return_value=_MockAsyncStream(chunks))
+        mock_client_cls.return_value.chat.completions.create = mock_create
+
+        gen = await self.model([])
+        responses = [r async for r in gen]
+
+        self.assertListEqual(
+            [(r.is_last, r.content) for r in responses],
+            [
+                (
+                    False,
+                    [
+                        ToolCallBlock(
+                            id="call-1",
+                            name="get_weather",
+                            input='{"ci',
+                        ),
+                    ],
+                ),
+                (
+                    False,
+                    [
+                        ToolCallBlock(
+                            id="call-1",
+                            name="get_weather",
+                            input='ty":"BJ"}',
+                        ),
+                    ],
+                ),
+                (
+                    True,
+                    [
+                        ToolCallBlock(
+                            id="call-1",
+                            name="get_weather",
+                            input='{"city":"BJ"}',
+                        ),
+                    ],
+                ),
+            ],
+        )
+
+    @patch("openai.AsyncClient")
+    async def test_stream_usage_in_final(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Usage information is captured and present in final response."""
+        chunks = [
+            _make_stream_chunk(delta_text="Hi"),
+            _make_stream_chunk(
+                has_choices=False,
+                usage={"prompt_tokens": 100, "completion_tokens": 20},
+            ),
+        ]
+        mock_create = AsyncMock(return_value=_MockAsyncStream(chunks))
+        mock_client_cls.return_value.chat.completions.create = mock_create
+
+        gen = await self.model([])
+        responses = [r async for r in gen]
+
+        self.assertListEqual(
+            [(r.is_last, r.content) for r in responses],
+            [
+                (False, [TextBlock.model_construct(id=A, text="Hi")]),
+                (True, [TextBlock.model_construct(id=A, text="Hi")]),
+            ],
+        )
+        self.assertEqual(responses[-1].usage.input_tokens, 100)
+        self.assertEqual(responses[-1].usage.output_tokens, 20)
+
+    @patch("openai.AsyncClient")
+    async def test_stream_audio_response(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Stream PCM deltas produce per-chunk DataBlocks (first chunk
+        prefixed with a streaming WAV header) sharing a stable id, plus a
+        final fixed-size WAV block readable by the ``wave`` module.
+        Transcript chunks ride alongside as TextBlock deltas so the agent
+        can stream caption text live; the final block carries the full
+        accumulated transcript."""
+        pcm1 = bytes([1, 2, 3, 4])
+        pcm2 = bytes([5, 6, 7, 8])
+        pcm3 = bytes([9, 10, 11, 12])
+        pcm_full = pcm1 + pcm2 + pcm3
+
+        chunks = [
+            _make_stream_chunk(
+                delta_audio={
+                    "data": base64.b64encode(pcm1).decode(),
+                    "transcript": "Hello",
+                },
+            ),
+            _make_stream_chunk(
+                delta_audio={
+                    "data": base64.b64encode(pcm2).decode(),
+                    "transcript": " world",
+                },
+            ),
+            _make_stream_chunk(
+                delta_audio={
+                    "data": base64.b64encode(pcm3).decode(),
+                    "transcript": "!",
+                },
+            ),
+            _make_stream_chunk(
+                has_choices=False,
+                usage={"prompt_tokens": 10, "completion_tokens": 6},
+            ),
+        ]
+        mock_create = AsyncMock(return_value=_MockAsyncStream(chunks))
+        mock_client_cls.return_value.chat.completions.create = mock_create
+
+        gen = await self.model([])
+        responses = [r async for r in gen]
+        self.assertEqual(len(responses), 4)
+
+        # All four chunks (3 deltas + 1 final) must share the same audio
+        # block id so downstream consumers stitch them as one stream.
+        all_audio_ids = {
+            block.id
+            for r in responses
+            for block in r.content
+            if isinstance(block, DataBlock)
+        }
+        self.assertEqual(len(all_audio_ids), 1)
+
+        # First delta: WAV header (44 bytes, "RIFF"..."WAVE") + pcm1.
+        first_audio = next(
+            b for b in responses[0].content if isinstance(b, DataBlock)
+        )
+        first_payload = base64.b64decode(first_audio.source.data)
+        self.assertEqual(len(first_payload), 44 + len(pcm1))
+        self.assertEqual(first_payload[:4], b"RIFF")
+        self.assertEqual(first_payload[8:12], b"WAVE")
+        self.assertEqual(first_payload[44:], pcm1)
+        self.assertEqual(first_audio.source.media_type, "audio/wav")
+
+        # Subsequent deltas: raw PCM only, no header.
+        for resp, pcm in zip(responses[1:3], [pcm2, pcm3]):
+            audio_block = next(
+                b for b in resp.content if isinstance(b, DataBlock)
+            )
+            self.assertEqual(base64.b64decode(audio_block.source.data), pcm)
+            self.assertEqual(audio_block.source.media_type, "audio/wav")
+
+        # Transcript rides alongside: each delta carries a TextBlock with
+        # only that chunk's text (so the agent emits TextBlockDeltaEvents
+        # in real time).
+        for resp, expected_text in zip(
+            responses[:3],
+            ["Hello", " world", "!"],
+        ):
+            text_block = next(
+                b for b in resp.content if isinstance(b, TextBlock)
+            )
+            self.assertEqual(text_block.text, expected_text)
+
+        # Final ``is_last`` block: a fixed-size WAV the ``wave`` module
+        # can parse end-to-end at 24kHz / mono / 16-bit.
+        final = responses[-1]
+        self.assertTrue(final.is_last)
+        final_audio = next(
+            b for b in final.content if isinstance(b, DataBlock)
+        )
+        wav_bytes = base64.b64decode(final_audio.source.data)
+        with wave.open(io.BytesIO(wav_bytes), "rb") as wav:
+            self.assertEqual(wav.getnchannels(), 1)
+            self.assertEqual(wav.getsampwidth(), 2)
+            self.assertEqual(wav.getframerate(), 24000)
+            frames = wav.readframes(wav.getnframes())
+        self.assertEqual(frames, pcm_full)
+
+        # Transcript is accumulated and emitted as a TextBlock alongside.
+        final_text = next(b for b in final.content if isinstance(b, TextBlock))
+        self.assertEqual(final_text.text, "Hello world!")
+
+
+class TestOpenAIChatModelParameters(unittest.TestCase):
+    """Tests for OpenAIChatModel.Parameters."""
+
+    def test_reasoning_effort_stored_on_model(self) -> None:
+        """reasoning_effort is accessible through model.parameters."""
+        model = OpenAIChatModel(
+            credential=OpenAICredential(api_key="test"),
+            model="o3",
+            stream=False,
+            context_size=200_000,
+            parameters=OpenAIChatModel.Parameters(reasoning_effort="low"),
+        )
+        self.assertEqual(model.parameters.reasoning_effort, "low")
+
+    def test_thinking_enable_stored_on_model(self) -> None:
+        """thinking_enable is accessible through model.parameters."""
+        model = OpenAIChatModel(
+            credential=OpenAICredential(api_key="test"),
+            model="o3",
+            stream=False,
+            context_size=200_000,
+            parameters=OpenAIChatModel.Parameters(thinking_enable=True),
+        )
+        self.assertTrue(model.parameters.thinking_enable)
+
+
+# ---------------------------------------------------------------------------
+# Shared _format_tools fixtures
+# ---------------------------------------------------------------------------
+
+_FT_TOOLS = [
+    {
+        "type": "function",
+        "function": {
+            "name": "get_weather",
+            "description": "Get the weather",
+            "parameters": {
+                "type": "object",
+                "properties": {"city": {"type": "string"}},
+                "required": ["city"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "get_time",
+            "description": "Get the time",
+            "parameters": {
+                "type": "object",
+                "properties": {"timezone": {"type": "string"}},
+                "required": ["timezone"],
+            },
+        },
+    },
+]
+
+
+class TestOpenAIChatFormatTools(unittest.TestCase):
+    """Tests for OpenAIChatModel._format_tools."""
+
+    def setUp(self) -> None:
+        """Set up model instance."""
+        self.model = _make_model()
+
+    def test_auto_mode(self) -> None:
+        """Auto mode returns tools unchanged and string 'auto'."""
+        fmt_tools, fmt_choice = self.model._format_tools(
+            _FT_TOOLS,
+            ToolChoice(mode="auto"),
+        )
+        self.assertEqual(fmt_tools, _FT_TOOLS)
+        self.assertEqual(fmt_choice, "auto")
+
+    def test_none_mode(self) -> None:
+        """None mode returns tools unchanged and string 'none'."""
+        fmt_tools, fmt_choice = self.model._format_tools(
+            _FT_TOOLS,
+            ToolChoice(mode="none"),
+        )
+        self.assertEqual(fmt_tools, _FT_TOOLS)
+        self.assertEqual(fmt_choice, "none")
+
+    def test_required_mode(self) -> None:
+        """Required mode returns tools unchanged and string 'required'."""
+        fmt_tools, fmt_choice = self.model._format_tools(
+            _FT_TOOLS,
+            ToolChoice(mode="required"),
+        )
+        self.assertEqual(fmt_tools, _FT_TOOLS)
+        self.assertEqual(fmt_choice, "required")
+
+    def test_str_mode_force_call(self) -> None:
+        """A specific tool name returns a type=function dict."""
+        fmt_tools, fmt_choice = self.model._format_tools(
+            _FT_TOOLS,
+            ToolChoice(mode="get_weather"),
+        )
+        self.assertEqual(fmt_tools, _FT_TOOLS)
+        self.assertEqual(
+            fmt_choice,
+            {"type": "function", "function": {"name": "get_weather"}},
+        )
+
+    def test_tools_filtered(self) -> None:
+        """When tool_choice.tools is set, only those tools are included."""
+        fmt_tools, fmt_choice = self.model._format_tools(
+            _FT_TOOLS,
+            ToolChoice(mode="auto", tools=["get_weather"]),
+        )
+        self.assertEqual(len(fmt_tools), 1)
+        self.assertEqual(fmt_tools[0]["function"]["name"], "get_weather")
+        self.assertEqual(fmt_choice, "auto")
+
+    def test_no_tool_choice(self) -> None:
+        """Without tool_choice, returns tools and None."""
+        fmt_tools, fmt_choice = self.model._format_tools(_FT_TOOLS, None)
+        self.assertEqual(fmt_tools, _FT_TOOLS)
+        self.assertIsNone(fmt_choice)
diff --git a/tests/model_openai_response_test.py b/tests/model_openai_response_test.py
new file mode 100644
index 0000000..739f3b8
--- /dev/null
+++ b/tests/model_openai_response_test.py
@@ -0,0 +1,570 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Unit tests for OpenAIResponseModel with mocked API responses.
+
+Tests cover both non-streaming and streaming modes.
+OpenAI Responses API uses event-based streaming with response.completed.
+"""
+from typing import Any
+import unittest
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import AsyncMock, MagicMock, patch
+
+from utils import AnyString
+
+from agentscope.message import TextBlock, ToolCallBlock, ThinkingBlock
+from agentscope.model import OpenAIResponseModel
+from agentscope.credential import OpenAICredential
+from agentscope.tool import ToolChoice
+
+A = AnyString()
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_model(stream: bool = False) -> Any:
+    return OpenAIResponseModel(
+        credential=OpenAICredential(api_key="test"),
+        model="o4-mini",
+        stream=stream,
+        context_size=200_000,
+    )
+
+
+def _mock_completion(
+    text: Any = None,
+    function_calls: Any = None,
+    reasoning_summary: Any = None,
+    reasoning_id: str = "rs_test123",
+    response_id: str = "resp-openai-1",
+) -> MagicMock:
+    """Build a mock non-streaming Responses API response."""
+    output = []
+
+    if reasoning_summary:
+        reasoning_item = MagicMock()
+        reasoning_item.type = "reasoning"
+        reasoning_item.id = reasoning_id
+        summary_mock = MagicMock()
+        summary_mock.text = reasoning_summary
+        reasoning_item.summary = [summary_mock]
+        output.append(reasoning_item)
+
+    if text:
+        msg_item = MagicMock()
+        msg_item.type = "message"
+        part = MagicMock()
+        part.type = "output_text"
+        part.text = text
+        msg_item.content = [part]
+        output.append(msg_item)
+
+    if function_calls:
+        for fc in function_calls:
+            fc_item = MagicMock()
+            fc_item.type = "function_call"
+            fc_item.id = fc["id"]
+            fc_item.call_id = fc["call_id"]
+            fc_item.name = fc["name"]
+            fc_item.arguments = fc["arguments"]
+            output.append(fc_item)
+
+    resp = MagicMock()
+    resp.id = response_id
+    resp.output = output
+    resp.usage = MagicMock()
+    resp.usage.input_tokens = 10
+    resp.usage.output_tokens = 5
+    resp.usage.input_tokens_details = None
+    return resp
+
+
+def _make_event(event_type: str, **kwargs: Any) -> MagicMock:
+    """Build a mock Responses API streaming event."""
+    event = MagicMock()
+    event.type = event_type
+    for key, val in kwargs.items():
+        setattr(event, key, val)
+    # Default: no response attribute
+    if "response" not in kwargs:
+        event.response = None
+    return event
+
+
+class _MockAsyncEventStream:
+    """Mock async iterator over Response events."""
+
+    def __init__(self, events: list) -> None:
+        self._events = events
+        self._index = 0
+
+    def __aiter__(self) -> "_MockAsyncEventStream":
+        return self
+
+    async def __anext__(self) -> Any:
+        if self._index >= len(self._events):
+            raise StopAsyncIteration
+        event = self._events[self._index]
+        self._index += 1
+        return event
+
+
+# ---------------------------------------------------------------------------
+# Non-streaming tests
+# ---------------------------------------------------------------------------
+
+
+class TestOpenAIResponseNonStream(IsolatedAsyncioTestCase):
+    """Tests for OpenAIResponseModel in non-streaming mode."""
+
+    def setUp(self) -> None:
+        self.model = _make_model(stream=False)
+
+    @patch("openai.AsyncClient")
+    async def test_text_response(self, mock_client_cls: MagicMock) -> None:
+        """Non-stream text response returns a single ChatResponse."""
+        mock_create = AsyncMock(
+            return_value=_mock_completion(text="Hello!"),
+        )
+        mock_client_cls.return_value.responses.create = mock_create
+
+        result = await self.model([])
+
+        self.assertEqual(
+            (result.is_last, result.content),
+            (True, [TextBlock.model_construct(id=A, text="Hello!")]),
+        )
+        self.assertEqual(result.id, "resp-openai-1")
+
+    @patch("openai.AsyncClient")
+    async def test_tool_call_response(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Parsing a tool-call response stores call_id as ToolCallBlock.id."""
+        mock_create = AsyncMock(
+            return_value=_mock_completion(
+                function_calls=[
+                    {
+                        "id": "fc_abc",
+                        "call_id": "call-1",
+                        "name": "get_weather",
+                        "arguments": '{"city":"BJ"}',
+                    },
+                ],
+            ),
+        )
+        mock_client_cls.return_value.responses.create = mock_create
+
+        result = await self.model([])
+
+        self.assertEqual(
+            (result.is_last, result.content),
+            (
+                True,
+                [
+                    ToolCallBlock(
+                        id="call-1",
+                        name="get_weather",
+                        input='{"city":"BJ"}',
+                    ),
+                ],
+            ),
+        )
+
+    @patch("openai.AsyncClient")
+    async def test_reasoning_response(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Non-stream reasoning summary plus text returns both block types."""
+        mock_create = AsyncMock(
+            return_value=_mock_completion(
+                reasoning_summary="Thinking step...",
+                text="Answer",
+                reasoning_id="rs_abc999",
+            ),
+        )
+        mock_client_cls.return_value.responses.create = mock_create
+
+        result = await self.model([])
+
+        self.assertEqual(
+            (result.is_last, result.content),
+            (
+                True,
+                [
+                    ThinkingBlock.model_construct(
+                        id=A,
+                        thinking="Thinking step...",
+                        reasoning_item_id="rs_abc999",
+                    ),
+                    TextBlock.model_construct(id=A, text="Answer"),
+                ],
+            ),
+        )
+
+
+class TestOpenAIResponseModelParameters(unittest.TestCase):
+    """Tests for OpenAIResponseModel.Parameters."""
+
+    def test_thinking_enable_stored_on_model(self) -> None:
+        """thinking_enable is accessible through model.parameters."""
+        model = OpenAIResponseModel(
+            credential=OpenAICredential(api_key="test"),
+            model="o4-mini",
+            stream=False,
+            context_size=200_000,
+            parameters=OpenAIResponseModel.Parameters(thinking_enable=True),
+        )
+        self.assertTrue(model.parameters.thinking_enable)
+
+    def test_reasoning_effort_stored_on_model(self) -> None:
+        """reasoning_effort is accessible through model.parameters."""
+        model = OpenAIResponseModel(
+            credential=OpenAICredential(api_key="test"),
+            model="o4-mini",
+            stream=False,
+            context_size=200_000,
+            parameters=OpenAIResponseModel.Parameters(
+                reasoning_effort="high",
+            ),
+        )
+        self.assertEqual(model.parameters.reasoning_effort, "high")
+
+
+# ---------------------------------------------------------------------------
+# Streaming tests
+# ---------------------------------------------------------------------------
+
+
+class TestOpenAIResponseStream(IsolatedAsyncioTestCase):
+    """Tests for OpenAIResponseModel in streaming mode."""
+
+    def setUp(self) -> None:
+        self.model = _make_model(stream=True)
+
+    @patch("openai.AsyncClient")
+    async def test_stream_text(self, mock_client_cls: MagicMock) -> None:
+        """Stream text yields deltas then final with full content."""
+        completed_resp = MagicMock()
+        completed_resp.id = "resp-1"
+        completed_resp.output = []
+        completed_resp.usage = MagicMock()
+        completed_resp.usage.input_tokens = 10
+        completed_resp.usage.output_tokens = 5
+        completed_resp.usage.input_tokens_details = None
+
+        events = [
+            _make_event(
+                "response.output_text.delta",
+                delta="Hello",
+                response=MagicMock(id="resp-1"),
+            ),
+            _make_event(
+                "response.output_text.delta",
+                delta=" world",
+            ),
+            _make_event("response.completed", response=completed_resp),
+        ]
+        mock_create = AsyncMock(
+            return_value=_MockAsyncEventStream(events),
+        )
+        mock_client_cls.return_value.responses.create = mock_create
+
+        gen = await self.model([])
+        responses = [r async for r in gen]
+
+        self.assertListEqual(
+            [(r.is_last, r.content) for r in responses],
+            [
+                (False, [TextBlock.model_construct(id=A, text="Hello")]),
+                (False, [TextBlock.model_construct(id=A, text=" world")]),
+                (True, [TextBlock.model_construct(id=A, text="Hello world")]),
+            ],
+        )
+
+    @patch("openai.AsyncClient")
+    async def test_stream_reasoning_and_text(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Stream reasoning and text deltas then final with
+        reasoning_item_id."""
+        reasoning_item = MagicMock()
+        reasoning_item.type = "reasoning"
+        reasoning_item.id = "rs_123"
+
+        completed_resp = MagicMock()
+        completed_resp.id = "resp-2"
+        completed_resp.output = [reasoning_item]
+        completed_resp.usage = MagicMock()
+        completed_resp.usage.input_tokens = 10
+        completed_resp.usage.output_tokens = 5
+        completed_resp.usage.input_tokens_details = None
+
+        events = [
+            _make_event(
+                "response.reasoning_summary_text.delta",
+                delta="Thinking",
+                response=MagicMock(id="resp-2"),
+            ),
+            _make_event(
+                "response.output_text.delta",
+                delta="Answer",
+            ),
+            _make_event("response.completed", response=completed_resp),
+        ]
+        mock_create = AsyncMock(
+            return_value=_MockAsyncEventStream(events),
+        )
+        mock_client_cls.return_value.responses.create = mock_create
+
+        gen = await self.model([])
+        responses = [r async for r in gen]
+
+        self.assertListEqual(
+            [(r.is_last, r.content) for r in responses],
+            [
+                (
+                    False,
+                    [ThinkingBlock.model_construct(id=A, thinking="Thinking")],
+                ),
+                (False, [TextBlock.model_construct(id=A, text="Answer")]),
+                # ``reasoning_item_id`` is only known at
+                # ``response.completed``; it is emitted as a dedicated
+                # carrier delta chunk (empty thinking text) that the base
+                # accumulator merges onto the existing ``ThinkingBlock``.
+                (
+                    False,
+                    [
+                        ThinkingBlock.model_construct(
+                            id=A,
+                            thinking="",
+                            reasoning_item_id="rs_123",
+                        ),
+                    ],
+                ),
+                (
+                    True,
+                    [
+                        ThinkingBlock.model_construct(
+                            id=A,
+                            thinking="Thinking",
+                            reasoning_item_id="rs_123",
+                        ),
+                        TextBlock.model_construct(id=A, text="Answer"),
+                    ],
+                ),
+            ],
+        )
+
+    @patch("openai.AsyncClient")
+    async def test_stream_function_call(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Stream function-call events use call_id as ToolCallBlock.id."""
+        fc_item = MagicMock()
+        fc_item.type = "function_call"
+        fc_item.id = "fc_1"
+        fc_item.call_id = "call-1"
+        fc_item.name = "search"
+
+        completed_resp = MagicMock()
+        completed_resp.id = "resp-3"
+        completed_resp.output = []
+        completed_resp.usage = MagicMock()
+        completed_resp.usage.input_tokens = 10
+        completed_resp.usage.output_tokens = 5
+        completed_resp.usage.input_tokens_details = None
+
+        events = [
+            _make_event(
+                "response.output_item.added",
+                item=fc_item,
+                response=MagicMock(id="resp-3"),
+            ),
+            _make_event(
+                "response.function_call_arguments.delta",
+                item_id="fc_1",
+                delta='{"q":',
+            ),
+            _make_event(
+                "response.function_call_arguments.delta",
+                item_id="fc_1",
+                delta='"test"}',
+            ),
+            _make_event("response.completed", response=completed_resp),
+        ]
+        mock_create = AsyncMock(
+            return_value=_MockAsyncEventStream(events),
+        )
+        mock_client_cls.return_value.responses.create = mock_create
+
+        gen = await self.model([])
+        responses = [r async for r in gen]
+
+        self.assertListEqual(
+            [(r.is_last, r.content) for r in responses],
+            [
+                (
+                    False,
+                    [
+                        ToolCallBlock(
+                            id="call-1",
+                            name="search",
+                            input='{"q":',
+                        ),
+                    ],
+                ),
+                (
+                    False,
+                    [
+                        ToolCallBlock(
+                            id="call-1",
+                            name="search",
+                            input='"test"}',
+                        ),
+                    ],
+                ),
+                (
+                    True,
+                    [
+                        ToolCallBlock(
+                            id="call-1",
+                            name="search",
+                            input='{"q":"test"}',
+                        ),
+                    ],
+                ),
+            ],
+        )
+
+
+# ---------------------------------------------------------------------------
+# _format_tools tests
+# ---------------------------------------------------------------------------
+
+_FT_TOOLS = [
+    {
+        "type": "function",
+        "function": {
+            "name": "get_weather",
+            "description": "Get the weather",
+            "parameters": {
+                "type": "object",
+                "properties": {"city": {"type": "string"}},
+                "required": ["city"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "get_time",
+            "description": "Get the time",
+            "parameters": {
+                "type": "object",
+                "properties": {"timezone": {"type": "string"}},
+                "required": ["timezone"],
+            },
+        },
+    },
+]
+
+_FT_TOOLS_RESPONSE = [
+    {
+        "type": "function",
+        "name": "get_weather",
+        "description": "Get the weather",
+        "parameters": {
+            "type": "object",
+            "properties": {"city": {"type": "string"}},
+            "required": ["city"],
+        },
+    },
+    {
+        "type": "function",
+        "name": "get_time",
+        "description": "Get the time",
+        "parameters": {
+            "type": "object",
+            "properties": {"timezone": {"type": "string"}},
+            "required": ["timezone"],
+        },
+    },
+]
+
+
+class TestOpenAIResponseFormatTools(unittest.TestCase):
+    """Tests for OpenAIResponseModel._format_tools."""
+
+    def setUp(self) -> None:
+        self.model = _make_model()
+
+    def test_auto_mode(self) -> None:
+        """Auto mode converts tools and sets choice to 'auto'."""
+        fmt_tools, fmt_choice = self.model._format_tools(
+            _FT_TOOLS,
+            ToolChoice(mode="auto"),
+        )
+        self.assertEqual(fmt_tools, _FT_TOOLS_RESPONSE)
+        self.assertEqual(fmt_choice, "auto")
+
+    def test_none_mode(self) -> None:
+        """None mode converts tools and sets choice to 'none'."""
+        fmt_tools, fmt_choice = self.model._format_tools(
+            _FT_TOOLS,
+            ToolChoice(mode="none"),
+        )
+        self.assertEqual(fmt_tools, _FT_TOOLS_RESPONSE)
+        self.assertEqual(fmt_choice, "none")
+
+    def test_required_mode(self) -> None:
+        """Required mode converts tools and sets choice to 'required'."""
+        fmt_tools, fmt_choice = self.model._format_tools(
+            _FT_TOOLS,
+            ToolChoice(mode="required"),
+        )
+        self.assertEqual(fmt_tools, _FT_TOOLS_RESPONSE)
+        self.assertEqual(fmt_choice, "required")
+
+    def test_str_mode_force_call(self) -> None:
+        """String mode forces a function call for the named tool."""
+        fmt_tools, fmt_choice = self.model._format_tools(
+            _FT_TOOLS,
+            ToolChoice(mode="get_weather"),
+        )
+        self.assertEqual(fmt_tools, _FT_TOOLS_RESPONSE)
+        self.assertEqual(
+            fmt_choice,
+            {"type": "function", "name": "get_weather"},
+        )
+
+    def test_tools_filtered(self) -> None:
+        """ToolChoice with tools list keeps the full tools schema and
+        narrows the callable subset via ``allowed_tools`` to preserve
+        prompt cache hits."""
+        fmt_tools, fmt_choice = self.model._format_tools(
+            _FT_TOOLS,
+            ToolChoice(mode="auto", tools=["get_weather"]),
+        )
+        self.assertListEqual(fmt_tools, _FT_TOOLS_RESPONSE)
+        self.assertEqual(
+            fmt_choice,
+            {
+                "type": "allowed_tools",
+                "mode": "auto",
+                "tools": [{"type": "function", "name": "get_weather"}],
+            },
+        )
+
+    def test_no_tool_choice(self) -> None:
+        """Tools are converted when tool_choice is None."""
+        fmt_tools, fmt_choice = self.model._format_tools(_FT_TOOLS, None)
+        self.assertEqual(fmt_tools, _FT_TOOLS_RESPONSE)
+        self.assertIsNone(fmt_choice)
diff --git a/tests/model_response_test.py b/tests/model_response_test.py
new file mode 100644
index 0000000..9e8ab33
--- /dev/null
+++ b/tests/model_response_test.py
@@ -0,0 +1,456 @@
+# -*- coding: utf-8 -*-
+"""Unit tests for :class:`agentscope.model.ChatResponse` and its
+``append_*`` helpers."""
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from utils import AnyString
+
+from agentscope.message import TextBlock
+from agentscope.model import ChatResponse, FinishedReason, ChatUsage
+
+
+def _dump(chat_response: ChatResponse) -> dict:
+    """Convert a ``ChatResponse`` into a plain-dict form suitable for
+    ``assertDictEqual`` / ``assertListEqual`` comparison.
+
+    ``ChatResponse`` inherits from ``DictMixin`` (a ``dict`` subclass) but
+    keeps its content blocks as pydantic models, so we normalize them via
+    ``model_dump(mode="json")`` here.
+    """
+    d = dict(chat_response)
+    d["content"] = [b.model_dump(mode="json") for b in d["content"]]
+    if d["usage"] is not None:
+        d["usage"] = dict(d["usage"])
+    return d
+
+
+def _expected(
+    content: list,
+    usage: dict | None = None,
+    finished_reason: FinishedReason = FinishedReason.COMPLETED,
+    is_last: bool = True,
+) -> dict:
+    """Build the expected serialized-``ChatResponse`` dict, with
+    ``AnyString`` placeholders for auto-generated fields."""
+    return {
+        "content": content,
+        "is_last": is_last,
+        "id": AnyString(),
+        "created_at": AnyString(),
+        "type": "chat_response",
+        "usage": usage,
+        "finished_reason": finished_reason,
+        "metadata": {},
+    }
+
+
+class ChatResponseAppendTest(IsolatedAsyncioTestCase):
+    """Test the ``append_*`` methods of ``ChatResponse``."""
+
+    async def asyncSetUp(self) -> None:
+        """The async setup method."""
+
+    # ------------------------------------------------------------------
+    # append_text
+    # ------------------------------------------------------------------
+    async def test_append_text_new_block(self) -> None:
+        """A new text block is created when the list is empty."""
+        r = ChatResponse(content=[TextBlock(text="exists")], is_last=True)
+        r.append_text("hello", block_id="t1")
+
+        self.assertDictEqual(
+            _dump(r),
+            _expected(
+                content=[
+                    {"type": "text", "text": "exists", "id": AnyString()},
+                    {"type": "text", "text": "hello", "id": "t1"},
+                ],
+            ),
+        )
+
+    async def test_append_text_merge_same_id(self) -> None:
+        """Two ``append_text`` calls with the same ``block_id`` merge
+        into a single text block."""
+        r = ChatResponse(content=[], is_last=True)
+        r.append_text("hello", block_id="t1")
+        r.append_text(" world", block_id="t1")
+
+        self.assertDictEqual(
+            _dump(r),
+            _expected(
+                content=[
+                    {"type": "text", "text": "hello world", "id": "t1"},
+                ],
+            ),
+        )
+
+    async def test_append_text_different_ids_are_separate_blocks(
+        self,
+    ) -> None:
+        """``append_text`` with different ``block_id`` values creates
+        separate text blocks in order."""
+        r = ChatResponse(content=[], is_last=True)
+        r.append_text("first", block_id="t1")
+        r.append_text("second", block_id="t2")
+
+        self.assertDictEqual(
+            _dump(r),
+            _expected(
+                content=[
+                    {"type": "text", "text": "first", "id": "t1"},
+                    {"type": "text", "text": "second", "id": "t2"},
+                ],
+            ),
+        )
+
+    # ------------------------------------------------------------------
+    # append_thinking
+    # ------------------------------------------------------------------
+    async def test_append_thinking_no_signature(self) -> None:
+        """A thinking block is created without ``signature`` field when
+        the caller does not provide one."""
+        r = ChatResponse(content=[], is_last=True)
+        r.append_thinking("why", block_id="th1")
+
+        self.assertDictEqual(
+            _dump(r),
+            _expected(
+                content=[
+                    {"type": "thinking", "thinking": "why", "id": "th1"},
+                ],
+            ),
+        )
+
+    async def test_append_thinking_with_signature_on_create(self) -> None:
+        """Signature can be supplied at block-creation time."""
+        r = ChatResponse(content=[], is_last=True)
+        r.append_thinking("why", block_id="th1", signature="sig-1")
+
+        self.assertDictEqual(
+            _dump(r),
+            _expected(
+                content=[
+                    {
+                        "type": "thinking",
+                        "thinking": "why",
+                        "id": "th1",
+                        "signature": "sig-1",
+                    },
+                ],
+            ),
+        )
+
+    async def test_append_thinking_merge_multiple_deltas_no_signature(
+        self,
+    ) -> None:
+        """Multiple consecutive thinking deltas without signature merge
+        into one block. Regression test: the previous implementation
+        raised ``AttributeError`` on the second delta because
+        ``signature`` was accessed unconditionally."""
+        r = ChatResponse(content=[], is_last=True)
+        r.append_thinking("hello", block_id="th1")
+        r.append_thinking(" world", block_id="th1")
+
+        self.assertDictEqual(
+            _dump(r),
+            _expected(
+                content=[
+                    {
+                        "type": "thinking",
+                        "thinking": "hello world",
+                        "id": "th1",
+                    },
+                ],
+            ),
+        )
+
+    async def test_append_thinking_signature_after_thinking(self) -> None:
+        """The Anthropic pattern: several thinking deltas followed by a
+        signature-only delta, all sharing the same ``block_id``."""
+        r = ChatResponse(content=[], is_last=True)
+        r.append_thinking("hello", block_id="th1")
+        r.append_thinking(" world", block_id="th1")
+        r.append_thinking("", block_id="th1", signature="sig-1")
+
+        self.assertDictEqual(
+            _dump(r),
+            _expected(
+                content=[
+                    {
+                        "type": "thinking",
+                        "thinking": "hello world",
+                        "id": "th1",
+                        "signature": "sig-1",
+                    },
+                ],
+            ),
+        )
+
+    # ------------------------------------------------------------------
+    # append_tool_call
+    # ------------------------------------------------------------------
+    async def test_append_tool_call_new_block(self) -> None:
+        """A new tool call block is created on first append."""
+        r = ChatResponse(content=[], is_last=True)
+        r.append_tool_call(block_id="tc1", name="fn", input='{"x":1}')
+
+        self.assertDictEqual(
+            _dump(r),
+            _expected(
+                content=[
+                    {
+                        "type": "tool_call",
+                        "id": "tc1",
+                        "name": "fn",
+                        "input": '{"x":1}',
+                        "state": "pending",
+                        "suggested_rules": [],
+                    },
+                ],
+            ),
+        )
+
+    async def test_append_tool_call_merge_input_by_id(self) -> None:
+        """Multiple ``append_tool_call`` calls sharing the same
+        ``block_id`` concatenate their ``input`` payload."""
+        r = ChatResponse(content=[], is_last=True)
+        r.append_tool_call(block_id="tc1", name="fn", input='{"x"')
+        r.append_tool_call(block_id="tc1", name="fn", input=":1}")
+
+        self.assertDictEqual(
+            _dump(r),
+            _expected(
+                content=[
+                    {
+                        "type": "tool_call",
+                        "id": "tc1",
+                        "name": "fn",
+                        "input": '{"x":1}',
+                        "state": "pending",
+                        "suggested_rules": [],
+                    },
+                ],
+            ),
+        )
+
+    async def test_append_tool_call_multiple_calls(self) -> None:
+        """Different ``block_id`` values produce separate tool-call
+        blocks in the order they were appended."""
+        r = ChatResponse(content=[], is_last=True)
+        r.append_tool_call(block_id="tc1", name="fn_a", input='{"x":1}')
+        r.append_tool_call(block_id="tc2", name="fn_b", input='{"y":2}')
+
+        self.assertDictEqual(
+            _dump(r),
+            _expected(
+                content=[
+                    {
+                        "type": "tool_call",
+                        "id": "tc1",
+                        "name": "fn_a",
+                        "input": '{"x":1}',
+                        "state": "pending",
+                        "suggested_rules": [],
+                    },
+                    {
+                        "type": "tool_call",
+                        "id": "tc2",
+                        "name": "fn_b",
+                        "input": '{"y":2}',
+                        "state": "pending",
+                        "suggested_rules": [],
+                    },
+                ],
+            ),
+        )
+
+    # ------------------------------------------------------------------
+    # append_chat_response
+    # ------------------------------------------------------------------
+    async def test_append_chat_response_merges_matching_ids(self) -> None:
+        """Blocks with matching ids across mixed types are merged, not
+        duplicated. Verifies text / thinking / tool_call all merge in
+        one call."""
+        acc = ChatResponse(content=[], is_last=True)
+
+        # First delta contains one of each block type.
+        d1 = ChatResponse(content=[], is_last=False)
+        d1.append_text("hello", block_id="txt")
+        d1.append_thinking("why", block_id="th")
+        d1.append_tool_call(block_id="tc", name="fn", input='{"a"')
+        acc.append_chat_response(d1)
+
+        # Second delta extends each block by matching ids.
+        d2 = ChatResponse(content=[], is_last=False)
+        d2.append_text(" world", block_id="txt")
+        d2.append_thinking(" not", block_id="th")
+        d2.append_tool_call(block_id="tc", name="fn", input=":1}")
+        acc.append_chat_response(d2)
+
+        self.assertDictEqual(
+            _dump(acc),
+            _expected(
+                content=[
+                    {
+                        "type": "text",
+                        "text": "hello world",
+                        "id": "txt",
+                    },
+                    {
+                        "type": "thinking",
+                        "thinking": "why not",
+                        "id": "th",
+                    },
+                    {
+                        "type": "tool_call",
+                        "id": "tc",
+                        "name": "fn",
+                        "input": '{"a":1}',
+                        "state": "pending",
+                        "suggested_rules": [],
+                    },
+                ],
+            ),
+        )
+
+    async def test_append_chat_response_extends_new_ids(self) -> None:
+        """Delta blocks whose ids are not present in the accumulator
+        are appended as new blocks."""
+        acc = ChatResponse(content=[], is_last=True)
+        d1 = ChatResponse(content=[], is_last=False)
+        d1.append_text("hello", block_id="t1")
+        acc.append_chat_response(d1)
+
+        d2 = ChatResponse(content=[], is_last=False)
+        d2.append_text("second", block_id="t2")
+        d2.append_tool_call(block_id="tc1", name="fn", input="{}")
+        acc.append_chat_response(d2)
+
+        self.assertDictEqual(
+            _dump(acc),
+            _expected(
+                content=[
+                    {"type": "text", "text": "hello", "id": "t1"},
+                    {"type": "text", "text": "second", "id": "t2"},
+                    {
+                        "type": "tool_call",
+                        "id": "tc1",
+                        "name": "fn",
+                        "input": "{}",
+                        "state": "pending",
+                        "suggested_rules": [],
+                    },
+                ],
+            ),
+        )
+
+    async def test_append_chat_response_thinking_then_signature(
+        self,
+    ) -> None:
+        """A signature-only delta arriving after several thinking-only
+        deltas via ``append_chat_response`` correctly attaches the
+        signature to the accumulated thinking block."""
+        acc = ChatResponse(content=[], is_last=True)
+
+        d1 = ChatResponse(content=[], is_last=False)
+        d1.append_thinking("hello", block_id="th1")
+        acc.append_chat_response(d1)
+
+        d2 = ChatResponse(content=[], is_last=False)
+        d2.append_thinking(" world", block_id="th1")
+        acc.append_chat_response(d2)
+
+        d3 = ChatResponse(content=[], is_last=False)
+        d3.append_thinking("", block_id="th1", signature="sig-1")
+        acc.append_chat_response(d3)
+
+        self.assertDictEqual(
+            _dump(acc),
+            _expected(
+                content=[
+                    {
+                        "type": "thinking",
+                        "thinking": "hello world",
+                        "id": "th1",
+                        "signature": "sig-1",
+                    },
+                ],
+            ),
+        )
+
+    async def test_append_chat_response_multiple_thinking_deltas_no_signature(
+        self,
+    ) -> None:
+        """Regression test for the ``AttributeError`` that used to be
+        raised when merging two consecutive thinking deltas that never
+        carried a ``signature``."""
+        acc = ChatResponse(content=[], is_last=True)
+
+        d1 = ChatResponse(content=[], is_last=False)
+        d1.append_thinking("foo", block_id="th1")
+        acc.append_chat_response(d1)
+
+        d2 = ChatResponse(content=[], is_last=False)
+        d2.append_thinking("bar", block_id="th1")
+        acc.append_chat_response(d2)
+
+        self.assertDictEqual(
+            _dump(acc),
+            _expected(
+                content=[
+                    {
+                        "type": "thinking",
+                        "thinking": "foobar",
+                        "id": "th1",
+                    },
+                ],
+            ),
+        )
+
+    async def test_append_chat_response_usage_override(self) -> None:
+        """``usage`` from the delta overrides ``self.usage`` when
+        non-``None``; a delta with no usage leaves it untouched."""
+        acc = ChatResponse(content=[], is_last=True)
+
+        # First delta carries an early usage snapshot.
+        d1 = ChatResponse(
+            content=[],
+            is_last=False,
+            usage=ChatUsage(input_tokens=1, output_tokens=1, time=0.1),
+        )
+        d1.append_text("hi", block_id="t1")
+        acc.append_chat_response(d1)
+
+        # Second delta has no usage → previous should be preserved.
+        d2 = ChatResponse(content=[], is_last=False)
+        d2.append_text(" there", block_id="t1")
+        acc.append_chat_response(d2)
+
+        # Third delta carries the final usage → it wins.
+        d3 = ChatResponse(
+            content=[],
+            is_last=False,
+            usage=ChatUsage(input_tokens=5, output_tokens=10, time=0.5),
+        )
+        acc.append_chat_response(d3)
+
+        self.assertDictEqual(
+            _dump(acc),
+            _expected(
+                content=[
+                    {"type": "text", "text": "hi there", "id": "t1"},
+                ],
+                usage={
+                    "input_tokens": 5,
+                    "output_tokens": 10,
+                    "time": 0.5,
+                    "cache_creation_input_tokens": 0,
+                    "cache_input_tokens": 0,
+                    "type": "chat",
+                    "metadata": None,
+                },
+            ),
+        )
+
+    async def asyncTearDown(self) -> None:
+        """The async teardown method."""
diff --git a/tests/model_xai_test.py b/tests/model_xai_test.py
new file mode 100644
index 0000000..254f815
--- /dev/null
+++ b/tests/model_xai_test.py
@@ -0,0 +1,589 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Unit tests for XAIChatModel with mocked API responses.
+
+Tests cover both non-streaming and streaming modes.
+XAI uses xai_sdk with chat.stream() for streaming.
+"""
+import sys
+from typing import Any
+from types import ModuleType
+import unittest
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import AsyncMock, MagicMock, patch
+
+from utils import AnyString
+
+from agentscope.message import TextBlock, ToolCallBlock, ThinkingBlock
+from agentscope.model import XAIChatModel
+from agentscope.credential import XAICredential
+from agentscope.tool import ToolChoice
+
+A = AnyString()
+
+
+# ---------------------------------------------------------------------------
+# Build a lightweight xai_sdk stub so tests run without the real package.
+# ---------------------------------------------------------------------------
+
+
+def _build_xai_sdk_stub() -> None:
+    """Register stub modules for xai_sdk so imports don't fail."""
+    if "xai_sdk" in sys.modules:
+        return
+
+    chat_pb2 = ModuleType("xai_sdk.chat.chat_pb2")
+
+    class _EnumHelper:
+        """Helper that makes .Value() return an integer."""
+
+        _mapping = {
+            "ROLE_ASSISTANT": 2,
+            "TOOL_CALL_TYPE_CLIENT_SIDE_TOOL": 1,
+        }
+
+        def Value(self, name: str) -> int:
+            """Return the integer value for the given enum name."""
+            return self._mapping.get(name, 0)
+
+    chat_pb2.MessageRole = _EnumHelper()
+    chat_pb2.ToolCallType = _EnumHelper()
+
+    class _RepeatedField(list):
+        """Minimal repeated proto field that supports .add()."""
+
+        def __init__(self, factory: Any) -> None:
+            super().__init__()
+            self._factory = factory
+
+        def add(self) -> Any:
+            """Add a new item using the factory and return it."""
+            item = self._factory()
+            self.append(item)
+            return item
+
+    class _FunctionSpec:
+        name: str = ""
+        arguments: str = ""
+
+    class _ToolCallProto:
+        id: str = ""
+        type: int = 0
+        function = _FunctionSpec()
+
+    class _ContentPart:
+        text: str = ""
+
+    class _MessageProto:
+        def __init__(self) -> None:
+            self.role = 0
+            self.content = _RepeatedField(_ContentPart)
+            self.tool_calls = _RepeatedField(_ToolCallProto)
+
+    chat_pb2.Message = _MessageProto
+
+    xai_chat = ModuleType("xai_sdk.chat")
+    xai_chat.chat_pb2 = chat_pb2
+    xai_chat.user = lambda *args: MagicMock(role="user", args=args)
+    xai_chat.assistant = lambda *args: MagicMock(role="assistant", args=args)
+    xai_chat.system = lambda *args: MagicMock(role="system", args=args)
+    xai_chat.tool_result = lambda *args, **kw: MagicMock(
+        role="tool",
+        args=args,
+        kwargs=kw,
+    )
+    xai_chat.image = lambda url: MagicMock(type="image", url=url)
+
+    xai_sdk = ModuleType("xai_sdk")
+    xai_sdk.chat = xai_chat
+    xai_sdk.AsyncClient = MagicMock()
+
+    sys.modules["xai_sdk"] = xai_sdk
+    sys.modules["xai_sdk.chat"] = xai_chat
+    sys.modules["xai_sdk.chat.chat_pb2"] = chat_pb2
+
+
+_build_xai_sdk_stub()
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_model(stream: bool = False) -> Any:
+    return XAIChatModel(
+        credential=XAICredential(api_key="test"),
+        model="grok-3",
+        stream=stream,
+        context_size=131_072,
+    )
+
+
+def _mock_completion(
+    text: str = "",
+    reasoning: str = "",
+    tool_calls: list | None = None,
+    response_id: str = "xai-resp-1",
+) -> MagicMock:
+    """Build a mock xAI non-streaming response."""
+    resp = MagicMock()
+    resp.id = response_id
+    resp.content = text
+    resp.reasoning_content = reasoning
+    resp.tool_calls = None
+    resp.usage = None
+
+    if tool_calls:
+        tc_mocks = []
+        for tc in tool_calls:
+            m = MagicMock()
+            m.id = tc["id"]
+            m.function.name = tc["name"]
+            m.function.arguments = tc["arguments"]
+            tc_mocks.append(m)
+        resp.tool_calls = tc_mocks
+
+    return resp
+
+
+class _MockStreamChunk:
+    """A single chunk from xai chat.stream()."""
+
+    def __init__(
+        self,
+        content: str = "",
+        reasoning_content: str = "",
+    ) -> None:
+        self.content = content
+        self.reasoning_content = reasoning_content
+
+
+class _MockChatStream:
+    """Mock xai_sdk chat session with stream() and sample()."""
+
+    def __init__(
+        self,
+        stream_items: list | None = None,
+        sample_response: Any = None,
+    ) -> None:
+        self._stream_items = stream_items or []
+        self._sample_response = sample_response
+        self._appended: list = []
+
+    def append(self, msg: Any) -> None:
+        """Append a message to the conversation."""
+        self._appended.append(msg)
+
+    async def sample(self) -> Any:
+        """Return the pre-configured sample response."""
+        return self._sample_response
+
+    def stream(self) -> "_MockStreamIterator":
+        """Return an async iterator over pre-configured stream items."""
+        return _MockStreamIterator(self._stream_items)
+
+
+class _MockStreamIterator:
+    """Async iterator for (response, chunk) pairs from xai stream."""
+
+    def __init__(self, items: list) -> None:
+        self._items = items
+        self._index = 0
+
+    def __aiter__(self) -> "_MockStreamIterator":
+        return self
+
+    async def __anext__(self) -> tuple:
+        if self._index >= len(self._items):
+            raise StopAsyncIteration
+        item = self._items[self._index]
+        self._index += 1
+        return item
+
+
+# ---------------------------------------------------------------------------
+# Non-streaming tests
+# ---------------------------------------------------------------------------
+
+
+class TestXAINonStream(IsolatedAsyncioTestCase):
+    """Tests for XAIChatModel in non-streaming mode."""
+
+    def setUp(self) -> None:
+        self.model = _make_model(stream=False)
+
+    @patch("xai_sdk.AsyncClient")
+    async def test_text_response(self, mock_client_cls: MagicMock) -> None:
+        """Non-stream text response returns a single ChatResponse."""
+        mock_chat = _MockChatStream(
+            sample_response=_mock_completion(text="Hello!"),
+        )
+        mock_client_cls.return_value.chat.create.return_value = mock_chat
+        mock_client_cls.return_value.close = AsyncMock()
+
+        result = await self.model([])
+
+        self.assertEqual(
+            (result.is_last, result.content),
+            (True, [TextBlock.model_construct(id=A, text="Hello!")]),
+        )
+        self.assertEqual(result.id, "xai-resp-1")
+
+    @patch("xai_sdk.AsyncClient")
+    async def test_tool_call_response(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Parsing a tool-call response creates a ToolCallBlock."""
+        mock_chat = _MockChatStream(
+            sample_response=_mock_completion(
+                tool_calls=[
+                    {
+                        "id": "call-1",
+                        "name": "get_weather",
+                        "arguments": '{"city":"NY"}',
+                    },
+                ],
+            ),
+        )
+        mock_client_cls.return_value.chat.create.return_value = mock_chat
+        mock_client_cls.return_value.close = AsyncMock()
+
+        result = await self.model([])
+
+        self.assertEqual(
+            (result.is_last, result.content),
+            (
+                True,
+                [
+                    ToolCallBlock(
+                        id="call-1",
+                        name="get_weather",
+                        input='{"city":"NY"}',
+                    ),
+                ],
+            ),
+        )
+
+    @patch("xai_sdk.AsyncClient")
+    async def test_thinking_response(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Non-stream reasoning plus text returns ThinkingBlock then
+        TextBlock."""
+        mock_chat = _MockChatStream(
+            sample_response=_mock_completion(
+                text="Answer",
+                reasoning="Deep thinking...",
+            ),
+        )
+        mock_client_cls.return_value.chat.create.return_value = mock_chat
+        mock_client_cls.return_value.close = AsyncMock()
+
+        result = await self.model([])
+
+        self.assertEqual(
+            (result.is_last, result.content),
+            (
+                True,
+                [
+                    ThinkingBlock.model_construct(
+                        id=A,
+                        thinking="Deep thinking...",
+                    ),
+                    TextBlock.model_construct(id=A, text="Answer"),
+                ],
+            ),
+        )
+
+
+# ---------------------------------------------------------------------------
+# Streaming tests
+# ---------------------------------------------------------------------------
+
+
+class TestXAIStream(IsolatedAsyncioTestCase):
+    """Tests for XAIChatModel in streaming mode."""
+
+    def setUp(self) -> None:
+        self.model = _make_model(stream=True)
+
+    @patch("xai_sdk.AsyncClient")
+    async def test_stream_text(self, mock_client_cls: MagicMock) -> None:
+        """Stream text yields deltas then final with full content."""
+        final_response = _mock_completion(text="Hello world")
+        final_response.tool_calls = None
+        final_response.usage = MagicMock()
+        final_response.usage.prompt_tokens = 10
+        final_response.usage.completion_tokens = 5
+        final_response.usage.cached_prompt_text_tokens = 0
+
+        stream_items = [
+            (final_response, _MockStreamChunk(content="Hello")),
+            (final_response, _MockStreamChunk(content=" world")),
+        ]
+        mock_chat = _MockChatStream(stream_items=stream_items)
+        mock_client_cls.return_value.chat.create.return_value = mock_chat
+        mock_client_cls.return_value.close = AsyncMock()
+
+        gen = await self.model([])
+        responses = [r async for r in gen]
+
+        self.assertListEqual(
+            [(r.is_last, r.content) for r in responses],
+            [
+                (False, [TextBlock.model_construct(id=A, text="Hello")]),
+                (False, [TextBlock.model_construct(id=A, text=" world")]),
+                (True, [TextBlock.model_construct(id=A, text="Hello world")]),
+            ],
+        )
+
+    @patch("xai_sdk.AsyncClient")
+    async def test_stream_thinking_and_text(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Stream reasoning and text deltas then final with accumulated
+        content."""
+        final_response = _mock_completion(text="")
+        final_response.tool_calls = None
+        final_response.usage = MagicMock()
+        final_response.usage.prompt_tokens = 10
+        final_response.usage.completion_tokens = 5
+        final_response.usage.cached_prompt_text_tokens = 0
+
+        stream_items = [
+            (final_response, _MockStreamChunk(reasoning_content="Think")),
+            (final_response, _MockStreamChunk(content="Answer")),
+        ]
+        mock_chat = _MockChatStream(stream_items=stream_items)
+        mock_client_cls.return_value.chat.create.return_value = mock_chat
+        mock_client_cls.return_value.close = AsyncMock()
+
+        gen = await self.model([])
+        responses = [r async for r in gen]
+
+        self.assertListEqual(
+            [(r.is_last, r.content) for r in responses],
+            [
+                (
+                    False,
+                    [ThinkingBlock.model_construct(id=A, thinking="Think")],
+                ),
+                (False, [TextBlock.model_construct(id=A, text="Answer")]),
+                (
+                    True,
+                    [
+                        ThinkingBlock.model_construct(id=A, thinking="Think"),
+                        TextBlock.model_construct(id=A, text="Answer"),
+                    ],
+                ),
+            ],
+        )
+
+    @patch("xai_sdk.AsyncClient")
+    async def test_stream_tool_calls_in_final(
+        self,
+        mock_client_cls: MagicMock,
+    ) -> None:
+        """Stream text delta then final adds tool calls from last_response."""
+        final_response = _mock_completion(
+            tool_calls=[
+                {
+                    "id": "call-1",
+                    "name": "search",
+                    "arguments": '{"q":"test"}',
+                },
+            ],
+        )
+        final_response.usage = MagicMock()
+        final_response.usage.prompt_tokens = 10
+        final_response.usage.completion_tokens = 5
+        final_response.usage.cached_prompt_text_tokens = 0
+
+        stream_items = [
+            (final_response, _MockStreamChunk(content="I'll search")),
+        ]
+        mock_chat = _MockChatStream(stream_items=stream_items)
+        mock_client_cls.return_value.chat.create.return_value = mock_chat
+        mock_client_cls.return_value.close = AsyncMock()
+
+        gen = await self.model([])
+        responses = [r async for r in gen]
+
+        self.assertListEqual(
+            [(r.is_last, r.content) for r in responses],
+            [
+                (False, [TextBlock.model_construct(id=A, text="I'll search")]),
+                # ``xai_sdk`` does not stream tool calls — they only
+                # appear on the final accumulated response object, so
+                # the parser emits them as a dedicated trailing carrier
+                # delta that the base accumulator merges.
+                (
+                    False,
+                    [
+                        ToolCallBlock(
+                            id="call-1",
+                            name="search",
+                            input='{"q":"test"}',
+                        ),
+                    ],
+                ),
+                (
+                    True,
+                    [
+                        TextBlock.model_construct(id=A, text="I'll search"),
+                        ToolCallBlock(
+                            id="call-1",
+                            name="search",
+                            input='{"q":"test"}',
+                        ),
+                    ],
+                ),
+            ],
+        )
+
+
+class TestXAIModelParameters(unittest.TestCase):
+    """Tests for XAIChatModel.Parameters."""
+
+    def test_thinking_enable_stored_on_model(self) -> None:
+        """thinking_enable is accessible through model.parameters."""
+        model = XAIChatModel(
+            credential=XAICredential(api_key="test"),
+            model="grok-3-mini",
+            stream=False,
+            context_size=131_072,
+            parameters=XAIChatModel.Parameters(thinking_enable=True),
+        )
+        self.assertTrue(model.parameters.thinking_enable)
+
+    def test_reasoning_effort_stored_on_model(self) -> None:
+        """reasoning_effort is accessible through model.parameters."""
+        model = XAIChatModel(
+            credential=XAICredential(api_key="test"),
+            model="grok-3-mini",
+            stream=False,
+            context_size=131_072,
+            parameters=XAIChatModel.Parameters(reasoning_effort="high"),
+        )
+        self.assertEqual(model.parameters.reasoning_effort, "high")
+
+
+# ---------------------------------------------------------------------------
+# _format_tools tests
+# ---------------------------------------------------------------------------
+
+_FT_TOOLS = [
+    {
+        "type": "function",
+        "function": {
+            "name": "get_weather",
+            "description": "Get the weather",
+            "parameters": {
+                "type": "object",
+                "properties": {"city": {"type": "string"}},
+                "required": ["city"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "get_time",
+            "description": "Get the time",
+            "parameters": {
+                "type": "object",
+                "properties": {"timezone": {"type": "string"}},
+                "required": ["timezone"],
+            },
+        },
+    },
+]
+
+
+def _extend_xai_stub_for_tools() -> None:
+    """Add tool and required_tool stubs to the existing xai_sdk stub."""
+    xai_chat = sys.modules.get("xai_sdk.chat")
+    if xai_chat is None or hasattr(xai_chat, "required_tool"):
+        return
+
+    class _RequiredTool:
+        def __init__(self, tool_name: str) -> None:
+            self.tool_name = tool_name
+
+        def __eq__(self, other: object) -> bool:
+            return (
+                isinstance(other, _RequiredTool)
+                and self.tool_name == other.tool_name
+            )
+
+    def _tool_stub(
+        name: str,
+        description: str = "",
+        parameters: Any = None,
+    ) -> MagicMock:
+        m = MagicMock()
+        m.name = name
+        m.description = description
+        m.parameters = parameters or {}
+        return m
+
+    xai_chat.required_tool = _RequiredTool
+    xai_chat.tool = _tool_stub
+
+
+_extend_xai_stub_for_tools()
+
+
+class TestXAIFormatTools(unittest.TestCase):
+    """Tests for XAIChatModel._format_tools."""
+
+    def setUp(self) -> None:
+        self.model = _make_model()
+
+    def test_no_tool_choice(self) -> None:
+        """All tools are returned when tool_choice is None."""
+        fmt_tools, fmt_choice = self.model._format_tools(_FT_TOOLS, None)
+        self.assertIsNotNone(fmt_tools)
+        self.assertEqual(len(fmt_tools), 2)
+        self.assertIsNone(fmt_choice)
+
+    def test_auto_mode(self) -> None:
+        """Auto mode passes tools through with choice 'auto'."""
+        fmt_tools, fmt_choice = self.model._format_tools(
+            _FT_TOOLS,
+            ToolChoice(mode="auto"),
+        )
+        self.assertIsNotNone(fmt_tools)
+        self.assertEqual(fmt_choice, "auto")
+
+    def test_none_mode(self) -> None:
+        """None mode passes tools through with choice 'none'."""
+        fmt_tools, fmt_choice = self.model._format_tools(
+            _FT_TOOLS,
+            ToolChoice(mode="none"),
+        )
+        self.assertIsNotNone(fmt_tools)
+        self.assertEqual(fmt_choice, "none")
+
+    def test_str_mode_force_call(self) -> None:
+        """String mode forces a required_tool for the named function."""
+        fmt_tools, fmt_choice = self.model._format_tools(
+            _FT_TOOLS,
+            ToolChoice(mode="get_weather"),
+        )
+        self.assertIsNotNone(fmt_tools)
+        self.assertEqual(fmt_choice.tool_name, "get_weather")
+
+    def test_tools_filtered(self) -> None:
+        """ToolChoice with tools list filters to matching function names."""
+        fmt_tools, fmt_choice = self.model._format_tools(
+            _FT_TOOLS,
+            ToolChoice(mode="auto", tools=["get_weather"]),
+        )
+        self.assertEqual(len(fmt_tools), 1)
+        self.assertEqual(fmt_tools[0].name, "get_weather")
+        self.assertEqual(fmt_choice, "auto")
diff --git a/tests/permission_bash_parser_test.py b/tests/permission_bash_parser_test.py
new file mode 100644
index 0000000..4c20dc2
--- /dev/null
+++ b/tests/permission_bash_parser_test.py
@@ -0,0 +1,1317 @@
+# -*- coding: utf-8 -*-
+"""Test cases for BashCommandParser."""
+import sys
+import unittest
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from agentscope.tool._builtin._bash_parser import BashCommandParser
+from agentscope.tool import Bash
+
+
+@unittest.skipIf(
+    sys.platform == "win32",
+    "Bash tool is not supported on Windows",
+)
+class BashCommandParserTest(IsolatedAsyncioTestCase):
+    """Test cases for BashCommandParser."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up test fixtures."""
+        self.parser = BashCommandParser()
+
+    async def test_single_command_with_prefix(self) -> None:
+        """Test single commands that can extract prefixes."""
+        test_cases = [
+            ("git commit -m 'fix'", ["git commit"]),
+            ("npm run build", ["npm run"]),
+            ("docker compose up", ["docker compose"]),
+            ("cargo build --release", ["cargo build"]),
+            ("python -m pytest", ["python -m"]),
+        ]
+
+        for command, expected in test_cases:
+            with self.subTest(command=command):
+                result = self.parser.extract_command_prefixes(command)
+                self.assertEqual(result, expected)
+
+    async def test_single_command_without_prefix(self) -> None:
+        """Test single commands that cannot extract prefixes."""
+        test_cases = [
+            ("ls", []),
+            ("ls -la", []),
+            ("echo hello", []),
+            ("cd /tmp", []),
+            ("pwd", []),
+            ("cat file.txt", []),
+        ]
+
+        for command, expected in test_cases:
+            with self.subTest(command=command):
+                result = self.parser.extract_command_prefixes(command)
+                self.assertEqual(result, expected)
+
+    async def test_environment_variables_safe(self) -> None:
+        """Test commands with safe environment variables."""
+        test_cases = [
+            ("NODE_ENV=prod npm run build", ["npm run"]),
+            ("DEBUG=1 npm test", ["npm test"]),
+            ("PATH=/usr/bin npm run build", ["npm run"]),
+            ("CI=true npm run test", ["npm run"]),
+            ("PYTHONUNBUFFERED=1 python -m pytest", ["python -m"]),
+        ]
+
+        for command, expected in test_cases:
+            with self.subTest(command=command):
+                result = self.parser.extract_command_prefixes(command)
+                self.assertEqual(result, expected)
+
+    async def test_environment_variables_unsafe(self) -> None:
+        """Test commands with unsafe environment variables."""
+        test_cases = [
+            ("CUSTOM_VAR=value npm run build", []),
+            ("MY_SECRET=123 npm test", []),
+            ("API_KEY=abc npm run deploy", []),
+        ]
+
+        for command, expected in test_cases:
+            with self.subTest(command=command):
+                result = self.parser.extract_command_prefixes(command)
+                self.assertEqual(result, expected)
+
+    async def test_compound_command_and_operator(self) -> None:
+        """Test compound commands with && operator."""
+        test_cases = [
+            ("git add . && git commit", ["git add", "git commit"]),
+            (
+                "npm install && npm run build && npm test",
+                ["npm install", "npm run", "npm test"],
+            ),
+            ("docker build . && docker push", ["docker build", "docker push"]),
+        ]
+
+        for command, expected in test_cases:
+            with self.subTest(command=command):
+                result = self.parser.extract_command_prefixes(command)
+                self.assertEqual(result, expected)
+
+    async def test_compound_command_or_operator(self) -> None:
+        """Test compound commands with || operator."""
+        test_cases = [
+            ("npm run build || echo failed", ["npm run"]),
+            ("git commit || git status", ["git commit", "git status"]),
+        ]
+
+        for command, expected in test_cases:
+            with self.subTest(command=command):
+                result = self.parser.extract_command_prefixes(command)
+                self.assertEqual(result, expected)
+
+    async def test_compound_command_semicolon(self) -> None:
+        """Test compound commands with ; operator."""
+        test_cases = [
+            ("cd /tmp; ls -la; pwd", []),
+            ("npm install; npm run build", ["npm install", "npm run"]),
+        ]
+
+        for command, expected in test_cases:
+            with self.subTest(command=command):
+                result = self.parser.extract_command_prefixes(command)
+                self.assertEqual(result, expected)
+
+    async def test_compound_command_pipe(self) -> None:
+        """Test compound commands with | operator."""
+        test_cases = [
+            ("cat file.txt | grep error", []),
+            ("docker ps | grep nginx", ["docker ps"]),
+            ("npm run build | tee output.log", ["npm run"]),
+        ]
+
+        for command, expected in test_cases:
+            with self.subTest(command=command):
+                result = self.parser.extract_command_prefixes(command)
+                self.assertEqual(result, expected)
+
+    async def test_compound_command_mixed(self) -> None:
+        """Test compound commands with mixed operators."""
+        test_cases = [
+            (
+                "git add . && git commit -m 'fix' || echo failed",
+                ["git add", "git commit"],
+            ),
+            (
+                "npm install && npm run build | tee log.txt",
+                ["npm install", "npm run"],
+            ),
+        ]
+
+        for command, expected in test_cases:
+            with self.subTest(command=command):
+                result = self.parser.extract_command_prefixes(command)
+                self.assertEqual(result, expected)
+
+    async def test_edge_cases(self) -> None:
+        """Test edge cases."""
+        test_cases = [
+            ("", []),
+            ("   ", []),
+            ("npm", []),
+            ("   npm run build   ", ["npm run"]),
+        ]
+
+        for command, expected in test_cases:
+            with self.subTest(command=command):
+                result = self.parser.extract_command_prefixes(command)
+                self.assertEqual(result, expected)
+
+    async def test_max_prefixes_limit(self) -> None:
+        """Test that max_prefixes parameter limits the results."""
+        command = (
+            "npm install && npm run build && npm test && "
+            "npm run lint && npm run format && npm run deploy"
+        )
+
+        # Default max is 5, but with deduplication we get 3 unique prefixes
+        result = self.parser.extract_command_prefixes(command)
+        self.assertEqual(len(result), 3)
+        self.assertEqual(
+            result,
+            ["npm install", "npm run", "npm test"],
+        )
+
+        # Custom max
+        result = self.parser.extract_command_prefixes(command, max_prefixes=3)
+        self.assertEqual(len(result), 3)
+
+    async def test_deduplication(self) -> None:
+        """Test that duplicate prefixes are removed."""
+        test_cases = [
+            (
+                "npm run build && npm run test && npm run lint",
+                ["npm run"],
+            ),
+            (
+                "git add . && git commit && git push && git status",
+                ["git add", "git commit", "git push", "git status"],
+            ),
+        ]
+
+        for command, expected in test_cases:
+            with self.subTest(command=command):
+                result = self.parser.extract_command_prefixes(command)
+                self.assertEqual(result, expected)
+
+    async def asyncTearDown(self) -> None:
+        """Clean up test fixtures."""
+        self.parser = None
+
+
+@unittest.skipIf(
+    sys.platform == "win32",
+    "Bash tool is not supported on Windows",
+)
+class BashParserReadOnlyTest(IsolatedAsyncioTestCase):
+    """Test is_read_only_command() method."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up test fixtures."""
+        self.parser = BashCommandParser()
+
+    async def test_single_read_only_git_commands(self) -> None:
+        """Test single read-only git commands."""
+        read_only_commands = [
+            "git status",
+            "git log",
+            "git diff",
+            "git show",
+            "git branch",
+            "git remote -v",
+            "git log --oneline",
+        ]
+        for cmd in read_only_commands:
+            with self.subTest(cmd=cmd):
+                self.assertTrue(
+                    self.parser.is_read_only_command(cmd),
+                    f"Expected '{cmd}' to be read-only",
+                )
+
+    async def test_single_read_only_file_commands(self) -> None:
+        """Test single read-only file commands."""
+        read_only_commands = [
+            "ls",
+            "ls -la",
+            "cat file.txt",
+            "head -n 10 file.txt",
+            "tail -f log.txt",
+            "grep pattern file.txt",
+            "find . -name '*.py'",
+            "tree",
+            "pwd",
+            "which python",
+        ]
+        for cmd in read_only_commands:
+            with self.subTest(cmd=cmd):
+                self.assertTrue(
+                    self.parser.is_read_only_command(cmd),
+                    f"Expected '{cmd}' to be read-only",
+                )
+
+    async def test_single_read_only_docker_commands(self) -> None:
+        """Test single read-only docker commands."""
+        read_only_commands = [
+            "docker ps",
+            "docker images",
+            "docker inspect container_id",
+            "docker logs container_id",
+        ]
+        for cmd in read_only_commands:
+            with self.subTest(cmd=cmd):
+                self.assertTrue(
+                    self.parser.is_read_only_command(cmd),
+                    f"Expected '{cmd}' to be read-only",
+                )
+
+    async def test_single_non_read_only_commands(self) -> None:
+        """Test single non-read-only commands."""
+        non_read_only_commands = [
+            "git commit -m 'message'",
+            "git push",
+            "git pull",
+            "rm file.txt",
+            "mv file1.txt file2.txt",
+            "cp file1.txt file2.txt",
+            "chmod +x script.sh",
+            "mkdir new_dir",
+            "touch file.txt",
+        ]
+        for cmd in non_read_only_commands:
+            with self.subTest(cmd=cmd):
+                self.assertFalse(
+                    self.parser.is_read_only_command(cmd),
+                    f"Expected '{cmd}' to be non-read-only",
+                )
+
+    async def test_compound_command_all_read_only(self) -> None:
+        """Test compound commands with all read-only subcommands."""
+        compound_commands = [
+            "ls -la && cat file.txt",
+            "git status && git log",
+            "pwd && ls",
+            "cat file1.txt || cat file2.txt",
+            "ls; pwd; cat file.txt",
+            "git diff | grep pattern",
+        ]
+        for cmd in compound_commands:
+            with self.subTest(cmd=cmd):
+                self.assertTrue(
+                    self.parser.is_read_only_command(cmd),
+                    f"Expected '{cmd}' to be read-only "
+                    f"(all subcommands are read-only)",
+                )
+
+    async def test_compound_command_mixed(self) -> None:
+        """Test compound commands with mixed read-only and non-read-only."""
+        mixed_commands = [
+            "ls -la && git commit -m 'message'",
+            "cat file.txt && rm file.txt",
+            "git status && git push",
+            "pwd || mkdir new_dir",
+            "ls; touch file.txt",
+        ]
+        for cmd in mixed_commands:
+            with self.subTest(cmd=cmd):
+                self.assertFalse(
+                    self.parser.is_read_only_command(cmd),
+                    f"Expected '{cmd}' to be non-read-only "
+                    f"(contains non-read-only subcommand)",
+                )
+
+    async def test_commands_with_output_redirection(self) -> None:
+        """Test commands with output redirections are not read-only."""
+        redirect_commands = [
+            "cat file.txt > output.txt",
+            "ls -la > list.txt",
+            "git log >> history.txt",
+            "echo 'hello' > file.txt",
+            "cat file.txt 2> error.log",
+            "ls &> output.log",
+        ]
+        for cmd in redirect_commands:
+            with self.subTest(cmd=cmd):
+                self.assertFalse(
+                    self.parser.is_read_only_command(cmd),
+                    f"Expected '{cmd}' to be non-read-only "
+                    f"(contains output redirection)",
+                )
+
+    async def test_commands_with_dangerous_paths(self) -> None:
+        """Test commands with dangerous paths."""
+        # Note: dangerous path check is separate from read-only check
+        # These commands are still considered read-only if they don't
+        # modify files
+        dangerous_read_only = [
+            "cat ~/.bashrc",
+            "ls ~/.ssh",
+            "cat .git/config",
+        ]
+        for cmd in dangerous_read_only:
+            with self.subTest(cmd=cmd):
+                self.assertTrue(
+                    self.parser.is_read_only_command(cmd),
+                    f"Expected '{cmd}' to be read-only "
+                    f"(dangerous path doesn't affect read-only status)",
+                )
+
+        # These are non-read-only because they modify files
+        dangerous_non_read_only = [
+            "rm ~/.bashrc",
+            "chmod 600 ~/.ssh/config",
+            "mv file.txt ~/.ssh/",
+        ]
+        for cmd in dangerous_non_read_only:
+            with self.subTest(cmd=cmd):
+                self.assertFalse(
+                    self.parser.is_read_only_command(cmd),
+                    f"Expected '{cmd}' to be non-read-only "
+                    f"(modifies files)",
+                )
+
+    async def test_empty_and_whitespace_commands(self) -> None:
+        """Test empty and whitespace-only commands."""
+        empty_commands = [
+            "",
+            "   ",
+            "\t",
+            "\n",
+        ]
+        for cmd in empty_commands:
+            with self.subTest(cmd=repr(cmd)):
+                # Empty commands return False (not read-only, but
+                # also not executable)
+                self.assertFalse(
+                    self.parser.is_read_only_command(cmd),
+                    "Expected empty/whitespace command to return False",
+                )
+
+    async def asyncTearDown(self) -> None:
+        """Clean up test fixtures."""
+        self.parser = None
+
+
+@unittest.skipIf(
+    sys.platform == "win32",
+    "Bash tool is not supported on Windows",
+)
+class BashParserFilePathsTest(IsolatedAsyncioTestCase):
+    """Test extract_file_paths() method."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up test fixtures."""
+        self.parser = BashCommandParser()
+
+    async def test_rm_command(self) -> None:
+        """Test file path extraction from rm commands."""
+        test_cases = [
+            ("rm file.txt", [("rm", "file.txt")]),
+            ("rm -rf /tmp/test", [("rm", "/tmp/test")]),
+            (
+                "rm file1.txt file2.txt",
+                [("rm", "file1.txt"), ("rm", "file2.txt")],
+            ),
+            ("rm -f *.log", [("rm", "*.log")]),
+        ]
+        for cmd, expected in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.extract_file_paths(cmd)
+                self.assertEqual(result, expected)
+
+    async def test_mv_command(self) -> None:
+        """Test file path extraction from mv commands."""
+        test_cases = [
+            ("mv old.txt new.txt", [("mv", "old.txt"), ("mv", "new.txt")]),
+            (
+                "mv /tmp/file.txt /home/user/",
+                [("mv", "/tmp/file.txt"), ("mv", "/home/user/")],
+            ),
+            (
+                "mv -f file1.txt file2.txt",
+                [("mv", "file1.txt"), ("mv", "file2.txt")],
+            ),
+        ]
+        for cmd, expected in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.extract_file_paths(cmd)
+                self.assertEqual(result, expected)
+
+    async def test_cp_command(self) -> None:
+        """Test file path extraction from cp commands."""
+        test_cases = [
+            (
+                "cp file.txt backup.txt",
+                [("cp", "file.txt"), ("cp", "backup.txt")],
+            ),
+            ("cp -r /src /dest", [("cp", "/src"), ("cp", "/dest")]),
+            (
+                "cp file1.txt file2.txt /tmp/",
+                [("cp", "file1.txt"), ("cp", "file2.txt"), ("cp", "/tmp/")],
+            ),
+        ]
+        for cmd, expected in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.extract_file_paths(cmd)
+                self.assertEqual(result, expected)
+
+    async def test_chmod_command(self) -> None:
+        """Test file path extraction from chmod commands."""
+        test_cases = [
+            ("chmod +x script.sh", [("chmod", "+x"), ("chmod", "script.sh")]),
+            ("chmod 755 /usr/bin/tool", [("chmod", "/usr/bin/tool")]),
+            ("chmod -R 644 /tmp/files", [("chmod", "/tmp/files")]),
+        ]
+        for cmd, expected in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.extract_file_paths(cmd)
+                self.assertEqual(result, expected)
+
+    async def test_chown_command(self) -> None:
+        """Test file path extraction from chown commands."""
+        test_cases = [
+            (
+                "chown user:group file.txt",
+                [("chown", "user:group"), ("chown", "file.txt")],
+            ),
+            (
+                "chown -R user /var/www",
+                [("chown", "user"), ("chown", "/var/www")],
+            ),
+        ]
+        for cmd, expected in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.extract_file_paths(cmd)
+                self.assertEqual(result, expected)
+
+    async def test_touch_command(self) -> None:
+        """Test file path extraction from touch commands."""
+        test_cases = [
+            ("touch file.txt", [("touch", "file.txt")]),
+            (
+                "touch file1.txt file2.txt",
+                [("touch", "file1.txt"), ("touch", "file2.txt")],
+            ),
+            ("touch /tmp/newfile.log", [("touch", "/tmp/newfile.log")]),
+        ]
+        for cmd, expected in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.extract_file_paths(cmd)
+                self.assertEqual(result, expected)
+
+    async def test_ln_command(self) -> None:
+        """Test file path extraction from ln commands."""
+        test_cases = [
+            ("ln -s target link", [("ln", "target"), ("ln", "link")]),
+            (
+                "ln /src/file /dest/file",
+                [("ln", "/src/file"), ("ln", "/dest/file")],
+            ),
+        ]
+        for cmd, expected in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.extract_file_paths(cmd)
+                self.assertEqual(result, expected)
+
+    async def test_sed_command(self) -> None:
+        """Test file path extraction from sed commands."""
+        test_cases = [
+            ("sed -i 's/old/new/' file.txt", [("sed", "file.txt")]),
+            ("sed 's/pattern/replacement/' input.txt", [("sed", "input.txt")]),
+        ]
+        for cmd, expected in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.extract_file_paths(cmd)
+                self.assertEqual(result, expected)
+
+    async def test_output_redirections(self) -> None:
+        """Test file path extraction from output redirections."""
+        test_cases = [
+            (
+                "echo 'hello' > output.txt",
+                [("redirect", "output.txt")],
+            ),
+            ("cat file.txt > backup.txt", [("redirect", "backup.txt")]),
+            ("ls -la >> list.txt", [("redirect", "list.txt")]),
+        ]
+        for cmd, expected in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.extract_file_paths(cmd)
+                self.assertEqual(result, expected)
+
+    async def test_compound_commands(self) -> None:
+        """Test file path extraction from compound commands."""
+        test_cases = [
+            (
+                "rm file1.txt && rm file2.txt",
+                [("rm", "file1.txt"), ("rm", "file2.txt")],
+            ),
+            (
+                "touch new.txt && chmod +x new.txt",
+                [("touch", "new.txt"), ("chmod", "+x"), ("chmod", "new.txt")],
+            ),
+            (
+                "cp src.txt dest.txt || mv src.txt dest.txt",
+                [
+                    ("cp", "src.txt"),
+                    ("cp", "dest.txt"),
+                    ("mv", "src.txt"),
+                    ("mv", "dest.txt"),
+                ],
+            ),
+        ]
+        for cmd, expected in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.extract_file_paths(cmd)
+                self.assertEqual(result, expected)
+
+    async def test_quoted_paths(self) -> None:
+        """Test file path extraction with quoted paths."""
+        test_cases = [
+            ('rm "file with spaces.txt"', []),  # Quoted paths not extracted
+            ("rm 'file.txt'", []),  # Quoted paths not extracted
+            (
+                'mv "old file.txt" "new file.txt"',
+                [],  # Quoted paths not extracted
+            ),
+        ]
+        for cmd, expected in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.extract_file_paths(cmd)
+                self.assertEqual(result, expected)
+
+    async def test_dangerous_paths(self) -> None:
+        """Test file path extraction with dangerous paths."""
+        test_cases = [
+            ("rm ~/.bashrc", [("rm", "~/.bashrc")]),
+            ("chmod 600 ~/.ssh/config", [("chmod", "~/.ssh/config")]),
+            (
+                "mv file.txt .git/hooks/",
+                [("mv", "file.txt"), ("mv", ".git/hooks/")],
+            ),
+        ]
+        for cmd, expected in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.extract_file_paths(cmd)
+                self.assertEqual(result, expected)
+
+    async def test_commands_without_file_operations(self) -> None:
+        """Test commands that don't operate on files."""
+        test_cases = [
+            ("ls", []),
+            ("pwd", []),
+            ("echo 'hello'", []),
+            ("git status", []),
+            ("docker ps", []),
+        ]
+        for cmd, expected in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.extract_file_paths(cmd)
+                self.assertEqual(result, expected)
+
+    async def test_empty_command(self) -> None:
+        """Test empty command."""
+        result = self.parser.extract_file_paths("")
+        self.assertEqual(result, [])
+
+    async def asyncTearDown(self) -> None:
+        """Clean up test fixtures."""
+        self.parser = None
+
+
+@unittest.skipIf(
+    sys.platform == "win32",
+    "Bash tool is not supported on Windows",
+)
+class BashParserRedirectionsTest(IsolatedAsyncioTestCase):
+    """Test extract_redirections() method."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up test fixtures."""
+        self.parser = BashCommandParser()
+
+    async def test_simple_output_redirection(self) -> None:
+        """Test simple output redirection (>)."""
+        test_cases = [
+            ("echo 'hello' > output.txt", ["output.txt"]),
+            ("cat file.txt > backup.txt", ["backup.txt"]),
+            ("ls -la > list.txt", ["list.txt"]),
+            ("git log > history.txt", ["history.txt"]),
+        ]
+        for cmd, expected in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.extract_redirections(cmd)
+                self.assertEqual(result, expected)
+
+    async def test_append_redirection(self) -> None:
+        """Test append redirection (>>)."""
+        test_cases = [
+            ("echo 'line' >> log.txt", ["log.txt"]),
+            ("cat file.txt >> combined.txt", ["combined.txt"]),
+            ("ls >> list.txt", ["list.txt"]),
+        ]
+        for cmd, expected in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.extract_redirections(cmd)
+                self.assertEqual(result, expected)
+
+    async def test_error_redirection(self) -> None:
+        """Test error redirection (2>)."""
+        test_cases = [
+            ("command 2> error.log", ["error.log"]),
+            ("python script.py 2> stderr.txt", ["stderr.txt"]),
+            ("npm run build 2> build_errors.log", ["build_errors.log"]),
+        ]
+        for cmd, expected in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.extract_redirections(cmd)
+                self.assertEqual(result, expected)
+
+    async def test_combined_redirection(self) -> None:
+        """Test combined stdout/stderr redirection (&>)."""
+        test_cases = [
+            ("command &> output.log", ["output.log"]),
+            ("python script.py &> all_output.txt", ["all_output.txt"]),
+            ("npm test &> test_results.log", ["test_results.log"]),
+        ]
+        for cmd, expected in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.extract_redirections(cmd)
+                self.assertEqual(result, expected)
+
+    async def test_multiple_redirections(self) -> None:
+        """Test commands with multiple redirections."""
+        test_cases = [
+            ("command > output.txt 2> error.log", ["output.txt", "error.log"]),
+            (
+                "python script.py > stdout.txt 2> stderr.txt",
+                ["stdout.txt", "stderr.txt"],
+            ),
+        ]
+        for cmd, expected in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.extract_redirections(cmd)
+                self.assertEqual(result, expected)
+
+    async def test_compound_commands_with_redirections(self) -> None:
+        """Test compound commands with multiple redirections."""
+        test_cases = [
+            (
+                "echo 'a' > file1.txt && echo 'b' > file2.txt",
+                ["file1.txt", "file2.txt"],
+            ),
+            (
+                "cat file.txt > backup.txt || cp file.txt backup.txt",
+                ["backup.txt"],
+            ),
+            ("ls > list1.txt; pwd > list2.txt", ["list1.txt", "list2.txt"]),
+        ]
+        for cmd, expected in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.extract_redirections(cmd)
+                self.assertEqual(result, expected)
+
+    async def test_redirections_with_quoted_paths(self) -> None:
+        """Test redirections with quoted file paths."""
+        test_cases = [
+            (
+                'echo "hello" > "output file.txt"',
+                [],
+            ),  # Quoted redirections not extracted
+            (
+                "cat file.txt > 'backup.txt'",
+                [],
+            ),  # Quoted redirections not extracted
+            (
+                'ls > "file with spaces.log"',
+                [],
+            ),  # Quoted redirections not extracted
+        ]
+        for cmd, expected in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.extract_redirections(cmd)
+                self.assertEqual(result, expected)
+
+    async def test_redirections_to_dangerous_paths(self) -> None:
+        """Test redirections to dangerous paths."""
+        test_cases = [
+            ("echo 'alias' >> ~/.bashrc", ["~/.bashrc"]),
+            ("cat key > ~/.ssh/authorized_keys", ["~/.ssh/authorized_keys"]),
+            ("echo 'config' > .git/config", [".git/config"]),
+        ]
+        for cmd, expected in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.extract_redirections(cmd)
+                self.assertEqual(result, expected)
+
+    async def test_redirections_with_absolute_paths(self) -> None:
+        """Test redirections with absolute paths."""
+        test_cases = [
+            ("echo 'data' > /tmp/output.txt", ["/tmp/output.txt"]),
+            ("cat file.txt > /var/log/app.log", ["/var/log/app.log"]),
+            ("ls > /home/user/list.txt", ["/home/user/list.txt"]),
+        ]
+        for cmd, expected in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.extract_redirections(cmd)
+                self.assertEqual(result, expected)
+
+    async def test_commands_without_redirections(self) -> None:
+        """Test commands without redirections."""
+        test_cases = [
+            ("ls -la", []),
+            ("cat file.txt", []),
+            ("echo 'hello'", []),
+            ("git status", []),
+            ("rm file.txt", []),
+        ]
+        for cmd, expected in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.extract_redirections(cmd)
+                self.assertEqual(result, expected)
+
+    async def test_pipe_not_redirection(self) -> None:
+        """Test that pipes (|) are not treated as redirections."""
+        test_cases = [
+            ("cat file.txt | grep pattern", []),
+            ("ls | wc -l", []),
+            ("git log | head -n 10", []),
+        ]
+        for cmd, expected in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.extract_redirections(cmd)
+                self.assertEqual(result, expected)
+
+    async def test_empty_command(self) -> None:
+        """Test empty command."""
+        result = self.parser.extract_redirections("")
+        self.assertEqual(result, [])
+
+    async def asyncTearDown(self) -> None:
+        """Clean up test fixtures."""
+        self.parser = None
+
+
+@unittest.skipIf(
+    sys.platform == "win32",
+    "Bash tool is not supported on Windows",
+)
+class BashParserSedConstraintsTest(IsolatedAsyncioTestCase):
+    """Test check_sed_constraints() with complex allowlist/denylist."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up test fixtures."""
+        self.parser = BashCommandParser()
+        self.dangerous_files = [".env", "config.json", "secrets.yaml"]
+
+    async def test_allowlist_line_printing(self) -> None:
+        """Test allowlist Pattern 1: Line printing with -n flag."""
+        test_cases = [
+            ("sed -n '5p' file.txt", None),
+            ("sed -n '10,20p' file.txt", None),
+            ("sed -n '1p' data.log", None),
+        ]
+        for cmd, expected in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.check_sed_constraints(
+                    cmd,
+                    self.dangerous_files,
+                )
+                self.assertEqual(result, expected)
+
+    async def test_allowlist_substitution(self) -> None:
+        """Test allowlist Pattern 2: Substitution commands."""
+        test_cases = [
+            ("sed 's/old/new/' file.txt", None),
+            ("sed 's/old/new/g' file.txt", None),
+            ("sed 's|old|new|' file.txt", None),
+            ("sed 's#pattern#replacement#' file.txt", None),
+        ]
+        for cmd, expected in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.check_sed_constraints(
+                    cmd,
+                    self.dangerous_files,
+                )
+                self.assertEqual(result, expected)
+
+    async def test_denylist_write_operations(self) -> None:
+        """Test denylist: write operations (w/W)."""
+        test_cases = [
+            ("sed 's/old/new/w output.txt' file.txt", "write operation"),
+            ("sed 's/old/new/W output.txt' file.txt", "write operation"),
+        ]
+        for cmd, expected_substring in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.check_sed_constraints(
+                    cmd,
+                    self.dangerous_files,
+                )
+                self.assertIsNotNone(result)
+                self.assertIn(expected_substring, result)
+
+    async def test_denylist_execute_operations(self) -> None:
+        """Test denylist: execute operations (e/E)."""
+        test_cases = [
+            ("sed 's/old/new/e' file.txt", "execute operation"),
+            ("sed 's/old/new/E' file.txt", "execute operation"),
+        ]
+        for cmd, expected_substring in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.check_sed_constraints(
+                    cmd,
+                    self.dangerous_files,
+                )
+                self.assertIsNotNone(result)
+                self.assertIn(expected_substring, result)
+
+    async def test_denylist_dangerous_patterns(self) -> None:
+        """Test denylist: dangerous patterns (curly braces, negation)."""
+        test_cases = [
+            ("sed '{s/old/new/}' file.txt", "curly braces"),
+            ("sed '!s/old/new/' file.txt", "negation"),
+        ]
+        for cmd, expected_substring in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.check_sed_constraints(
+                    cmd,
+                    self.dangerous_files,
+                )
+                self.assertIsNotNone(result)
+                self.assertIn(expected_substring, result)
+
+    async def test_not_in_allowlist(self) -> None:
+        """Test commands not in allowlist."""
+        test_cases = [
+            ("sed 'd' file.txt", "not in allowlist"),
+            ("sed 'a\\text' file.txt", "not in allowlist"),
+            ("sed 'i\\text' file.txt", "not in allowlist"),
+        ]
+        for cmd, expected_substring in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.check_sed_constraints(
+                    cmd,
+                    self.dangerous_files,
+                )
+                self.assertIsNotNone(result)
+                self.assertIn(expected_substring, result)
+
+    async def test_inplace_with_dangerous_files(self) -> None:
+        """Test -i flag with dangerous files."""
+        test_cases = [
+            ("sed -i 's/old/new/' .env", "dangerous file"),
+            ("sed -i 's/old/new/' config.json", "dangerous file"),
+            ("sed --in-place 's/old/new/' secrets.yaml", "dangerous file"),
+        ]
+        for cmd, expected_substring in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.check_sed_constraints(
+                    cmd,
+                    self.dangerous_files,
+                )
+                self.assertIsNotNone(result)
+                self.assertIn(expected_substring, result)
+
+    async def test_invalid_flags(self) -> None:
+        """Test invalid flags."""
+        test_cases = [
+            ("sed -r 's/old/new/' file.txt", "flag -r not allowed"),
+            ("sed -u 's/old/new/' file.txt", "flag -u not allowed"),
+        ]
+        for cmd, expected_substring in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.check_sed_constraints(
+                    cmd,
+                    self.dangerous_files,
+                )
+                self.assertIsNotNone(result)
+                self.assertIn(expected_substring, result)
+
+    async def test_non_sed_commands(self) -> None:
+        """Test non-sed commands return None."""
+        test_cases = [
+            "ls -la",
+            "cat file.txt",
+            "grep pattern file.txt",
+        ]
+        for cmd in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.check_sed_constraints(
+                    cmd,
+                    self.dangerous_files,
+                )
+                self.assertIsNone(result)
+
+    async def asyncTearDown(self) -> None:
+        """Clean up test fixtures."""
+        self.parser = None
+
+
+@unittest.skipIf(
+    sys.platform == "win32",
+    "Bash tool is not supported on Windows",
+)
+class BashWildcardMatchingTest(IsolatedAsyncioTestCase):
+    """Test match_rule() with complex regex-based wildcard matching."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up test fixtures."""
+        self.bash_tool = Bash()
+
+    async def test_basic_wildcard_matching(self) -> None:
+        """Test basic wildcard matching with *."""
+        test_cases = [
+            ("git *", "git status", True),
+            ("git *", "git", True),  # Special optimization
+            ("git * push", "git origin push", True),
+            ("npm run *", "npm run build", True),
+            ("npm run *", "npm run test", True),
+            ("docker * up", "docker compose up", True),
+        ]
+        for pattern, command, expected in test_cases:
+            with self.subTest(pattern=pattern, command=command):
+                result = await self.bash_tool.match_rule(
+                    pattern,
+                    {"command": command},
+                )
+                self.assertEqual(result, expected)
+
+    async def test_wildcard_no_match(self) -> None:
+        """Test wildcard patterns that don't match."""
+        test_cases = [
+            ("git *", "github", False),
+            ("npm run *", "yarn run build", False),
+            ("docker * up", "docker ps", False),
+        ]
+        for pattern, command, expected in test_cases:
+            with self.subTest(pattern=pattern, command=command):
+                result = await self.bash_tool.match_rule(
+                    pattern,
+                    {"command": command},
+                )
+                self.assertEqual(result, expected)
+
+    async def test_escape_sequences(self) -> None:
+        """Test escape sequences \\* and \\\\."""
+        test_cases = [
+            ("file\\*.txt", "file*.txt", True),
+            ("file\\*.txt", "file123.txt", False),
+            ("path\\\\to\\\\file", "path\\to\\file", True),
+            ("path\\\\to\\\\file", "path/to/file", False),
+        ]
+        for pattern, command, expected in test_cases:
+            with self.subTest(pattern=pattern, command=command):
+                result = await self.bash_tool.match_rule(
+                    pattern,
+                    {"command": command},
+                )
+                self.assertEqual(result, expected)
+
+    async def test_prefix_pattern(self) -> None:
+        """Test prefix pattern with :* suffix."""
+        test_cases = [
+            ("git:*", "git status", True),
+            ("git:*", "git", True),
+            ("git:*", "github", False),
+            ("npm:*", "npm install", True),
+            ("npm:*", "npm", True),
+        ]
+        for pattern, command, expected in test_cases:
+            with self.subTest(pattern=pattern, command=command):
+                result = await self.bash_tool.match_rule(
+                    pattern,
+                    {"command": command},
+                )
+                self.assertEqual(result, expected)
+
+    async def test_substring_matching(self) -> None:
+        """Test substring matching (no wildcards)."""
+        test_cases = [
+            ("npm install", "npm install express", True),
+            ("npm install", "yarn install", False),
+            ("git commit", "git commit -m 'fix'", True),
+            ("git commit", "git push", False),
+        ]
+        for pattern, command, expected in test_cases:
+            with self.subTest(pattern=pattern, command=command):
+                result = await self.bash_tool.match_rule(
+                    pattern,
+                    {"command": command},
+                )
+                self.assertEqual(result, expected)
+
+    async def asyncTearDown(self) -> None:
+        """Clean up test fixtures."""
+        self.bash_tool = None
+
+
+@unittest.skipIf(
+    sys.platform == "win32",
+    "Bash tool is not supported on Windows",
+)
+class BashParserInjectionRiskTest(IsolatedAsyncioTestCase):
+    """Test check_injection_risk() method for detecting dynamic shell
+    structures."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up test fixtures."""
+        self.parser = BashCommandParser()
+
+    async def test_command_substitution_dollar_paren(self) -> None:
+        """Test detection of command substitution with $()."""
+        test_cases = [
+            "ls $(pwd)",
+            "rm $(find . -name '*.tmp')",
+            "echo $(date)",
+            "cat $(which python)",
+        ]
+        for cmd in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.check_injection_risk(cmd)
+                self.assertIsNotNone(result)
+                self.assertIn("command_substitution", result)
+
+    async def test_command_substitution_backtick(self) -> None:
+        """Test detection of command substitution with backticks."""
+        test_cases = [
+            "ls `pwd`",
+            "rm `find . -name '*.tmp'`",
+            "echo `date`",
+        ]
+        for cmd in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.check_injection_risk(cmd)
+                self.assertIsNotNone(result)
+                self.assertIn("command_substitution", result)
+
+    async def test_process_substitution(self) -> None:
+        """Test detection of process substitution <()."""
+        test_cases = [
+            "diff <(ls dir1) <(ls dir2)",
+            "cat <(echo hello)",
+            "grep pattern <(curl http://example.com)",
+        ]
+        for cmd in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.check_injection_risk(cmd)
+                self.assertIsNotNone(result)
+                self.assertIn("process_substitution", result)
+
+    async def test_subshell(self) -> None:
+        """Test detection of subshells ()."""
+        test_cases = [
+            "(cd /tmp && ls)",
+            "(export VAR=value; echo $VAR)",
+            "echo before && (cd /tmp; pwd) && echo after",
+        ]
+        for cmd in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.check_injection_risk(cmd)
+                self.assertIsNotNone(result)
+                self.assertIn("subshell", result)
+
+    async def test_for_loop(self) -> None:
+        """Test detection of for loops."""
+        test_cases = [
+            "for f in *.txt; do cat $f; done",
+            "for i in 1 2 3; do echo $i; done",
+            "for file in $(ls); do rm $file; done",
+        ]
+        for cmd in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.check_injection_risk(cmd)
+                self.assertIsNotNone(result)
+                self.assertIn("for_statement", result)
+
+    async def test_while_loop(self) -> None:
+        """Test detection of while loops."""
+        test_cases = [
+            "while read line; do echo $line; done < file.txt",
+            "while true; do sleep 1; done",
+            "while [ $i -lt 10 ]; do echo $i; i=$((i+1)); done",
+        ]
+        for cmd in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.check_injection_risk(cmd)
+                self.assertIsNotNone(result)
+                self.assertIn("while_statement", result)
+
+    async def test_if_statement(self) -> None:
+        """Test detection of if statements."""
+        test_cases = [
+            "if [ -f file.txt ]; then cat file.txt; fi",
+            "if test -d /tmp; then echo exists; fi",
+            "if [ $? -eq 0 ]; then echo success; else echo fail; fi",
+        ]
+        for cmd in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.check_injection_risk(cmd)
+                self.assertIsNotNone(result)
+                self.assertIn("if_statement", result)
+
+    async def test_case_statement(self) -> None:
+        """Test detection of case statements."""
+        test_cases = [
+            "case $1 in start) echo starting;; stop) echo stopping;; esac",
+            "case $var in a) echo A;; b) echo B;; *) echo other;; esac",
+        ]
+        for cmd in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.check_injection_risk(cmd)
+                self.assertIsNotNone(result)
+                self.assertIn("case_statement", result)
+
+    async def test_function_definition(self) -> None:
+        """Test detection of function definitions."""
+        test_cases = [
+            "function myfunc() { echo hello; }",
+            "myfunc() { ls -la; }",
+        ]
+        for cmd in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.check_injection_risk(cmd)
+                self.assertIsNotNone(result)
+                self.assertIn("function_definition", result)
+
+    async def test_safe_commands(self) -> None:
+        """Test that safe commands pass injection check."""
+        safe_commands = [
+            "ls -la",
+            "cat file.txt",
+            "git status",
+            "npm install",
+            "echo 'hello world'",
+            "grep pattern file.txt",
+            "find . -name '*.py'",
+            "docker ps",
+            "python script.py",
+        ]
+        for cmd in safe_commands:
+            with self.subTest(cmd=cmd):
+                result = self.parser.check_injection_risk(cmd)
+                self.assertIsNone(result, f"Expected '{cmd}' to be safe")
+
+    async def test_compound_commands_safe(self) -> None:
+        """Test that compound commands without dynamic structures are safe."""
+        safe_commands = [
+            "ls -la && cat file.txt",
+            "git add . && git commit -m 'fix'",
+            "npm install || echo failed",
+            "cd /tmp; ls; pwd",
+            "cat file.txt | grep pattern",
+        ]
+        for cmd in safe_commands:
+            with self.subTest(cmd=cmd):
+                result = self.parser.check_injection_risk(cmd)
+                self.assertIsNone(result, f"Expected '{cmd}' to be safe")
+
+    async def test_mixed_safe_and_unsafe(self) -> None:
+        """Test compound commands with both safe and unsafe parts."""
+        test_cases = [
+            ("ls && rm $(find . -name '*.tmp')", "command_substitution"),
+            ("git status && (cd /tmp; ls)", "subshell"),
+            (
+                "echo start && for f in *.txt; do cat $f; done",
+                "for_statement",
+            ),
+        ]
+        for cmd, expected_type in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.check_injection_risk(cmd)
+                self.assertIsNotNone(result)
+                self.assertIn(expected_type, result)
+
+    async def test_empty_command(self) -> None:
+        """Test empty command."""
+        result = self.parser.check_injection_risk("")
+        # Empty command should be safe (no dangerous nodes)
+        self.assertIsNone(result)
+
+    async def asyncTearDown(self) -> None:
+        """Clean up test fixtures."""
+        self.parser = None
+
+
+@unittest.skipIf(
+    sys.platform == "win32",
+    "Bash tool is not supported on Windows",
+)
+class BashParserDangerousCommandTest(IsolatedAsyncioTestCase):
+    """Test check_dangerous_command() method."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up test fixtures."""
+        self.parser = BashCommandParser()
+
+    async def test_rm_rf_pattern(self) -> None:
+        """Test detection of rm -rf pattern."""
+        test_cases = [
+            "rm -rf /tmp/test",
+            "rm -rf .",
+            "sudo rm -rf /var/log",
+        ]
+        for cmd in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.check_dangerous_command(cmd)
+                self.assertIsNotNone(result)
+                self.assertIn("rm -rf", result)
+
+    async def test_sudo_rm_pattern(self) -> None:
+        """Test detection of sudo rm pattern."""
+        test_cases = [
+            "sudo rm file.txt",
+            "sudo rm -f /etc/config",
+        ]
+        for cmd in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.check_dangerous_command(cmd)
+                self.assertIsNotNone(result)
+                self.assertIn("sudo rm", result)
+
+    async def test_dd_command(self) -> None:
+        """Test detection of dd command."""
+        test_cases = [
+            "dd if=/dev/zero of=/dev/sda",
+            "dd if=file.iso of=/dev/sdb",
+        ]
+        for cmd in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.check_dangerous_command(cmd)
+                self.assertIsNotNone(result)
+                self.assertEqual(result, "dd")
+
+    async def test_chmod_777_pattern(self) -> None:
+        """Test detection of chmod 777 pattern."""
+        test_cases = [
+            "chmod 777 file.txt",
+            "chmod -R 777 /var/www",
+        ]
+        for cmd in test_cases:
+            with self.subTest(cmd=cmd):
+                result = self.parser.check_dangerous_command(cmd)
+                self.assertIsNotNone(result)
+                self.assertIn("chmod", result)
+
+    async def test_safe_commands(self) -> None:
+        """Test that safe commands are not flagged."""
+        safe_commands = [
+            "rm file.txt",
+            "rm -f temp.log",
+            "chmod +x script.sh",
+            "chmod 644 file.txt",
+            "ls -la",
+            "git status",
+        ]
+        for cmd in safe_commands:
+            with self.subTest(cmd=cmd):
+                result = self.parser.check_dangerous_command(cmd)
+                self.assertIsNone(result, f"Expected '{cmd}' to be safe")
+
+    async def asyncTearDown(self) -> None:
+        """Clean up test fixtures."""
+        self.parser = None
diff --git a/tests/permission_engine_test.py b/tests/permission_engine_test.py
new file mode 100644
index 0000000..4be95dd
--- /dev/null
+++ b/tests/permission_engine_test.py
@@ -0,0 +1,813 @@
+# -*- coding: utf-8 -*-
+"""Test cases for PermissionEngine.
+
+Mode-specific tests live in :mod:`tests.permission_mode_test`. This file
+covers rule priority, rule pattern matching (Bash / file glob), dangerous
+path detection, suggestion generation, Bash read-only command analysis,
+and bypass-immune safety checks.
+"""
+import sys
+import unittest
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from agentscope.permission import (
+    PermissionEngine,
+    PermissionMode,
+    PermissionContext,
+    PermissionRule,
+    PermissionBehavior,
+    PermissionDecision,
+    AdditionalWorkingDirectory,
+)
+from agentscope.tool import (
+    Bash,
+    Write,
+    Read,
+    Edit,
+    ToolBase,
+)
+
+
+class PermissionEngineRulePriorityTest(IsolatedAsyncioTestCase):
+    """Test cases for rule priority and decision-making."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up test fixtures."""
+        self.context = PermissionContext(mode=PermissionMode.DEFAULT)
+        self.engine = PermissionEngine(self.context)
+
+    async def test_deny_rule_priority(self) -> None:
+        """Test that deny rules have the highest priority."""
+        # Add both allow and deny rules for the same tool
+        self.engine.add_rule(
+            PermissionRule(
+                tool_name="Bash",
+                rule_content="git:*",
+                behavior=PermissionBehavior.ALLOW,
+                source="test",
+            ),
+        )
+        self.engine.add_rule(
+            PermissionRule(
+                tool_name="Bash",
+                rule_content="git:*",
+                behavior=PermissionBehavior.DENY,
+                source="test",
+            ),
+        )
+
+        decision = await self.engine.check_permission(
+            Bash(),
+            {"command": "git status"},
+        )
+
+        # Deny should take precedence over allow
+        self.assertEqual(decision.behavior, PermissionBehavior.DENY)
+
+    async def test_ask_rule_priority(self) -> None:
+        """Test that ask rules have priority over allow rules."""
+        # Add both allow and ask rules for the same tool
+        self.engine.add_rule(
+            PermissionRule(
+                tool_name="Bash",
+                rule_content="npm:*",
+                behavior=PermissionBehavior.ALLOW,
+                source="test",
+            ),
+        )
+        self.engine.add_rule(
+            PermissionRule(
+                tool_name="Bash",
+                rule_content="npm:*",
+                behavior=PermissionBehavior.ASK,
+                source="test",
+            ),
+        )
+
+        decision = await self.engine.check_permission(
+            Bash(),
+            {"command": "npm install"},
+        )
+
+        # Ask should take precedence over allow
+        self.assertEqual(decision.behavior, PermissionBehavior.ASK)
+
+    async def test_rule_priority_order(self) -> None:
+        """Test complete rule priority: deny > ask > allow."""
+        # Add all three types of rules
+        self.engine.add_rule(
+            PermissionRule(
+                tool_name="Bash",
+                rule_content="test:*",
+                behavior=PermissionBehavior.ALLOW,
+                source="test",
+            ),
+        )
+        self.engine.add_rule(
+            PermissionRule(
+                tool_name="Bash",
+                rule_content="test:*",
+                behavior=PermissionBehavior.ASK,
+                source="test",
+            ),
+        )
+        self.engine.add_rule(
+            PermissionRule(
+                tool_name="Bash",
+                rule_content="test:*",
+                behavior=PermissionBehavior.DENY,
+                source="test",
+            ),
+        )
+
+        decision = await self.engine.check_permission(
+            Bash(),
+            {"command": "test command"},
+        )
+
+        # Deny should win
+        self.assertEqual(decision.behavior, PermissionBehavior.DENY)
+
+    async def asyncTearDown(self) -> None:
+        """Clean up test fixtures."""
+        self.engine = None
+        self.context = None
+
+
+@unittest.skipIf(
+    sys.platform == "win32",
+    "Bash tool is not supported on Windows",
+)
+class PermissionEngineBashRuleTest(IsolatedAsyncioTestCase):
+    """Test cases for Bash command rule matching."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up test fixtures."""
+        self.context = PermissionContext(mode=PermissionMode.DEFAULT)
+        self.engine = PermissionEngine(self.context)
+
+    async def test_bash_prefix_pattern_matching(self) -> None:
+        """Test bash command prefix pattern matching with :* wildcard."""
+        self.engine.add_rule(
+            PermissionRule(
+                tool_name="Bash",
+                rule_content="git:*",
+                behavior=PermissionBehavior.ALLOW,
+                source="test",
+            ),
+        )
+
+        # Test exact command
+        decision = await self.engine.check_permission(
+            Bash(),
+            {"command": "git"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.ALLOW)
+
+        # Test command with arguments
+        decision = await self.engine.check_permission(
+            Bash(),
+            {"command": "git status"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.ALLOW)
+
+        # Test command with multiple arguments
+        decision = await self.engine.check_permission(
+            Bash(),
+            {"command": "git add ."},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.ALLOW)
+
+        # Test non-matching command
+        decision = await self.engine.check_permission(
+            Bash(),
+            {"command": "npm install"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.ASK)
+
+    async def test_bash_substring_pattern_matching(self) -> None:
+        """Test bash command substring pattern matching."""
+        self.engine.add_rule(
+            PermissionRule(
+                tool_name="Bash",
+                rule_content="install",
+                behavior=PermissionBehavior.DENY,
+                source="test",
+            ),
+        )
+
+        # Test command containing substring
+        decision = await self.engine.check_permission(
+            Bash(),
+            {"command": "npm install package"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.DENY)
+
+        # Test command containing substring in different position
+        decision = await self.engine.check_permission(
+            Bash(),
+            {"command": "pip install requests"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.DENY)
+
+    async def test_bash_multiple_rules(self) -> None:
+        """Test bash command matching with multiple rules."""
+        self.engine.add_rule(
+            PermissionRule(
+                tool_name="Bash",
+                rule_content="rm:*",
+                behavior=PermissionBehavior.DENY,
+                source="test",
+            ),
+        )
+        self.engine.add_rule(
+            PermissionRule(
+                tool_name="Bash",
+                rule_content="git:*",
+                behavior=PermissionBehavior.ALLOW,
+                source="test",
+            ),
+        )
+
+        # Test deny rule
+        decision = await self.engine.check_permission(
+            Bash(),
+            {"command": "rm -rf /tmp"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.DENY)
+
+        # Test allow rule
+        decision = await self.engine.check_permission(
+            Bash(),
+            {"command": "git status"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.ALLOW)
+
+        # Test no matching rule
+        decision = await self.engine.check_permission(
+            Bash(),
+            {"command": "npm install"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.ASK)
+
+    async def asyncTearDown(self) -> None:
+        """Clean up test fixtures."""
+        self.engine = None
+        self.context = None
+
+
+class PermissionEngineFileRuleTest(IsolatedAsyncioTestCase):
+    """Test cases for file operation rule matching."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up test fixtures."""
+        self.context = PermissionContext(mode=PermissionMode.DEFAULT)
+        self.engine = PermissionEngine(self.context)
+
+    async def test_file_glob_pattern_matching(self) -> None:
+        """Test file path glob pattern matching."""
+        self.engine.add_rule(
+            PermissionRule(
+                tool_name="Read",
+                rule_content="*.py",
+                behavior=PermissionBehavior.ALLOW,
+                source="test",
+            ),
+        )
+
+        # Test matching file
+        decision = await self.engine.check_permission(
+            Read(),
+            {"file_path": "test.py"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.ALLOW)
+
+        # Test non-matching file
+        decision = await self.engine.check_permission(
+            Read(),
+            {"file_path": "test.txt"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.ASK)
+
+    async def test_file_directory_pattern_matching(self) -> None:
+        """Test file path directory pattern matching."""
+        self.engine.add_rule(
+            PermissionRule(
+                tool_name="Edit",
+                rule_content="/tmp/**",
+                behavior=PermissionBehavior.ALLOW,
+                source="test",
+            ),
+        )
+
+        # Test file in directory - glob pattern /tmp/** should match
+        decision = await self.engine.check_permission(
+            Edit(),
+            {"file_path": "/tmp/test.txt"},
+        )
+        # Note: The current implementation uses fnmatch/pathlib matching
+        # /tmp/** may not match /tmp/test.txt depending on implementation
+        # This test verifies the actual behavior
+        self.assertIn(
+            decision.behavior,
+            [PermissionBehavior.ALLOW, PermissionBehavior.ASK],
+        )
+
+        # Test file in subdirectory
+        decision = await self.engine.check_permission(
+            Edit(),
+            {"file_path": "/tmp/subdir/test.txt"},
+        )
+        self.assertIn(
+            decision.behavior,
+            [PermissionBehavior.ALLOW, PermissionBehavior.ASK],
+        )
+
+        # Test file outside directory
+        decision = await self.engine.check_permission(
+            Edit(),
+            {"file_path": "/home/user/test.txt"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.ASK)
+
+    async def asyncTearDown(self) -> None:
+        """Clean up test fixtures."""
+        self.engine = None
+        self.context = None
+
+
+@unittest.skipIf(
+    sys.platform == "win32",
+    "Unix-specific paths not supported on Windows",
+)
+class PermissionEngineDangerousPathTest(IsolatedAsyncioTestCase):
+    """Test cases for dangerous path detection (bypass-immune safety
+    checks)."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up test fixtures."""
+        self.context = PermissionContext(mode=PermissionMode.DEFAULT)
+        self.engine = PermissionEngine(self.context)
+
+    async def test_dangerous_file_blocks_write(self) -> None:
+        """Test that Write operations on dangerous files require
+        confirmation."""
+        # Try to write a dangerous file
+        decision = await self.engine.check_permission(
+            Write(),
+            {"file_path": "/home/user/.bashrc"},
+        )
+
+        # Should ask for confirmation (safety check)
+        self.assertEqual(decision.behavior, PermissionBehavior.ASK)
+
+    async def test_dangerous_file_blocks_edit(self) -> None:
+        """Test that Edit operations on dangerous files require
+        confirmation."""
+        # Try to edit a dangerous file
+        decision = await self.engine.check_permission(
+            Edit(),
+            {"file_path": "/home/user/.gitconfig"},
+        )
+
+        # Should ask for confirmation (safety check)
+        self.assertEqual(decision.behavior, PermissionBehavior.ASK)
+        self.assertIn("safety", decision.decision_reason.lower())
+
+    async def test_dangerous_directory_blocks_write(self) -> None:
+        """Test that Write operations in dangerous directories require
+        confirmation."""
+        # Try to write in a dangerous directory
+        decision = await self.engine.check_permission(
+            Write(),
+            {"file_path": "/home/user/.ssh/config"},
+        )
+
+        # Should ask for confirmation (safety check)
+        self.assertEqual(decision.behavior, PermissionBehavior.ASK)
+        self.assertIn("safety", decision.decision_reason.lower())
+
+    async def test_dangerous_path_in_bash_command(self) -> None:
+        """Test that Bash commands on dangerous paths require confirmation."""
+        # Try to remove a dangerous file
+        decision = await self.engine.check_permission(
+            Bash(),
+            {"command": "rm /home/user/.bashrc"},
+        )
+
+        # Should ask for confirmation (safety check)
+        self.assertEqual(decision.behavior, PermissionBehavior.ASK)
+        self.assertIn("safety", decision.decision_reason.lower())
+
+    async def test_dangerous_path_in_accept_edits_mode(self) -> None:
+        """Test that dangerous paths require confirmation even in
+        ACCEPT_EDITS mode."""
+        context = PermissionContext(
+            mode=PermissionMode.ACCEPT_EDITS,
+            working_directories={
+                "/home/user": AdditionalWorkingDirectory(
+                    path="/home/user",
+                    source="test",
+                ),
+            },
+        )
+        engine = PermissionEngine(context)
+
+        # Try to write a dangerous file in working directory
+        decision = await engine.check_permission(
+            Write(),
+            {"file_path": "/home/user/.bashrc"},
+        )
+
+        # Should ask despite being in working directory
+        self.assertEqual(decision.behavior, PermissionBehavior.ASK)
+
+    async def test_safe_file_allows_write(self) -> None:
+        """Test that Write operations on safe files work normally."""
+        # Try to write a safe file
+        decision = await self.engine.check_permission(
+            Write(),
+            {"file_path": "/home/user/test.py"},
+        )
+
+        # Should ask (no allow rule, but not blocked by safety check)
+        self.assertEqual(decision.behavior, PermissionBehavior.ASK)
+        # Should NOT be a safety check
+        self.assertNotIn("safety", decision.decision_reason.lower())
+
+    async def asyncTearDown(self) -> None:
+        """Clean up test fixtures."""
+        self.engine = None
+        self.context = None
+
+
+class PermissionEngineSuggestionTest(IsolatedAsyncioTestCase):
+    """Test cases for permission rule suggestions."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up test fixtures."""
+        self.context = PermissionContext(mode=PermissionMode.DEFAULT)
+        self.engine = PermissionEngine(self.context)
+
+    async def test_bash_suggestions(self) -> None:
+        """Test suggestion generation for bash commands."""
+        # Use a non-read-only command to test suggestions
+        decision = await self.engine.check_permission(
+            Bash(),
+            {"command": "git commit -m 'test'"},
+        )
+
+        # Should ask (not read-only)
+        self.assertEqual(decision.behavior, PermissionBehavior.ASK)
+
+        # Should have suggestions
+        self.assertIsNotNone(decision.suggested_rules)
+        self.assertGreater(len(decision.suggested_rules), 0)
+
+        # Check suggestion content - should generate two-word prefix rule
+        suggestion_contents = [
+            s.rule_content for s in decision.suggested_rules
+        ]
+        # git commit should generate "git commit:*"
+        self.assertIn("git commit:*", suggestion_contents)
+
+    async def test_file_suggestions(self) -> None:
+        """Test suggestion generation for file operations."""
+        decision = await self.engine.check_permission(
+            Read(),
+            {"file_path": "/tmp/test.py"},
+        )
+
+        # Should have suggestions
+        self.assertGreater(len(decision.suggested_rules), 0)
+
+        # Check suggestion content - should generate directory rule
+        suggestion_contents = [
+            s.rule_content for s in decision.suggested_rules
+        ]
+        self.assertIn("/tmp/**", suggestion_contents)
+
+    async def asyncTearDown(self) -> None:
+        """Clean up test fixtures."""
+        self.engine = None
+        self.context = None
+
+
+@unittest.skipIf(
+    sys.platform == "win32",
+    "Bash tool is not supported on Windows",
+)
+class PermissionEngineReadOnlyTest(IsolatedAsyncioTestCase):
+    """Test cases for read-only command auto-allow."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up test fixtures."""
+        self.context = PermissionContext(mode=PermissionMode.DEFAULT)
+        self.engine = PermissionEngine(self.context)
+
+    async def test_git_status_is_read_only(self) -> None:
+        """Test that git status is auto-allowed as read-only."""
+        decision = await self.engine.check_permission(
+            Bash(),
+            {"command": "git status"},
+        )
+
+        # Should be allowed (read-only command)
+        self.assertEqual(decision.behavior, PermissionBehavior.ALLOW)
+        self.assertIn("read-only", decision.decision_reason.lower())
+
+    async def test_ls_is_read_only(self) -> None:
+        """Test that ls is auto-allowed as read-only."""
+        decision = await self.engine.check_permission(
+            Bash(),
+            {"command": "ls -la"},
+        )
+
+        # Should be allowed (read-only command)
+        self.assertEqual(decision.behavior, PermissionBehavior.ALLOW)
+
+    async def test_cat_is_read_only(self) -> None:
+        """Test that cat is auto-allowed as read-only."""
+        decision = await self.engine.check_permission(
+            Bash(),
+            {"command": "cat file.txt"},
+        )
+
+        # Should be allowed (read-only command)
+        self.assertEqual(decision.behavior, PermissionBehavior.ALLOW)
+
+    async def test_git_commit_is_not_read_only(self) -> None:
+        """Test that git commit is not auto-allowed (not read-only)."""
+        decision = await self.engine.check_permission(
+            Bash(),
+            {"command": "git commit -m 'test'"},
+        )
+
+        # Should ask (not read-only)
+        self.assertEqual(decision.behavior, PermissionBehavior.ASK)
+
+    async def test_compound_command_with_dangerous_path(self) -> None:
+        """Test compound command with read-only and dangerous path o
+        perations."""
+        # ls is read-only, but rm ~/.bashrc is dangerous
+        decision = await self.engine.check_permission(
+            Bash(),
+            {"command": "ls -la && rm ~/.bashrc"},
+        )
+
+        # Should ask because of dangerous path (safety check is bypass-immune)
+        self.assertEqual(decision.behavior, PermissionBehavior.ASK)
+        self.assertIn("safety", decision.decision_reason.lower())
+
+    async def test_compound_command_all_read_only(self) -> None:
+        """Test compound command with all read-only operations."""
+        # Both ls and cat are read-only
+        decision = await self.engine.check_permission(
+            Bash(),
+            {"command": "ls -la && cat file.txt"},
+        )
+
+        # Should be allowed (all read-only)
+        self.assertEqual(decision.behavior, PermissionBehavior.ALLOW)
+
+    async def test_compound_command_with_write_operation(self) -> None:
+        """Test compound command with read-only and write operations."""
+        # ls is read-only, but git commit is not
+        decision = await self.engine.check_permission(
+            Bash(),
+            {"command": "ls -la && git commit -m 'test'"},
+        )
+
+        # Should ask (contains non-read-only command)
+        self.assertEqual(decision.behavior, PermissionBehavior.ASK)
+
+    async def test_output_redirection_to_dangerous_path(self) -> None:
+        """Test output redirection to dangerous path."""
+        # cat is read-only, but redirecting to ~/.bashrc is dangerous
+        decision = await self.engine.check_permission(
+            Bash(),
+            {"command": "cat file.txt > ~/.bashrc"},
+        )
+
+        # Should ask because of dangerous path in redirection
+        self.assertEqual(decision.behavior, PermissionBehavior.ASK)
+        self.assertIn("safety", decision.decision_reason.lower())
+
+    async def test_output_redirection_to_safe_path(self) -> None:
+        """Test output redirection to safe path."""
+        # cat is read-only, redirecting to safe path
+        decision = await self.engine.check_permission(
+            Bash(),
+            {"command": "cat file.txt > /tmp/output.txt"},
+        )
+
+        # Should ask (redirection is not considered read-only)
+        self.assertEqual(decision.behavior, PermissionBehavior.ASK)
+
+    async def asyncTearDown(self) -> None:
+        """Clean up test fixtures."""
+        self.engine = None
+        self.context = None
+
+
+@unittest.skipIf(
+    sys.platform == "win32",
+    "Bash tool is not supported on Windows",
+)
+class PermissionEngineSafetyCheckAllowRuleImmuneTest(
+    IsolatedAsyncioTestCase,
+):
+    """Safety checks are immune to allow rules in DEFAULT mode.
+
+    A user-configured allow rule cannot grant permission for an
+    operation that the tool has flagged as a safety concern
+    (``bypass_immune=True``). This guarantees that broad rules like
+    ``Bash:rm:*`` don't accidentally authorize ``rm -rf /``.
+
+    Note: in BYPASS mode the user has explicitly opted out of safety
+    enforcement, so these tools' safety ASKs are NOT honored — that
+    behavior is covered by
+    :class:`tests.permission_mode_test.PermissionEngineBypassModeTest`.
+    """
+
+    async def test_injection_check_not_bypassed_by_allow_rule(self) -> None:
+        """Allow rule for ``ls:*`` does not authorize ``ls $(rm -rf /)``."""
+        context = PermissionContext(mode=PermissionMode.DEFAULT)
+        engine = PermissionEngine(context)
+        engine.add_rule(
+            PermissionRule(
+                tool_name="Bash",
+                rule_content="ls:*",
+                behavior=PermissionBehavior.ALLOW,
+                source="test",
+            ),
+        )
+
+        decision = await engine.check_permission(
+            Bash(),
+            {"command": "ls $(rm -rf /)"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.ASK)
+        self.assertIn("command_substitution", decision.message)
+
+    async def test_dangerous_removal_not_bypassed_by_allow_rule(self) -> None:
+        """Allow rule for ``rm:*`` does not authorize ``rm -rf /``."""
+        context = PermissionContext(mode=PermissionMode.DEFAULT)
+        engine = PermissionEngine(context)
+        engine.add_rule(
+            PermissionRule(
+                tool_name="Bash",
+                rule_content="rm:*",
+                behavior=PermissionBehavior.ALLOW,
+                source="test",
+            ),
+        )
+
+        decision = await engine.check_permission(
+            Bash(),
+            {"command": "rm -rf /"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.ASK)
+        # Either dangerous removal path or dangerous command pattern fires
+        self.assertTrue(
+            "Dangerous removal operation" in decision.message
+            or "dangerous pattern" in decision.message,
+        )
+
+
+# ---------------------------------------------------------------------------
+# bypass_immune field mechanism
+# ---------------------------------------------------------------------------
+
+
+class _FakeToolReturningAsk(ToolBase):
+    """Minimal tool used to test the ``bypass_immune`` field mechanism.
+
+    Returns a single configurable ASK decision from ``check_permissions``
+    so we can verify the engine routes bypass-immune vs regular ASKs
+    correctly regardless of the specific safety trigger.
+    """
+
+    name = "FakeAskTool"
+    description = "Test-only tool"
+    input_schema = {"type": "object", "properties": {}}
+    is_concurrency_safe = True
+    is_read_only = False
+    is_external_tool = False
+    is_state_injected = False
+    is_mcp = False
+
+    def __init__(self, bypass_immune: bool) -> None:
+        self._bypass_immune = bypass_immune
+
+    async def check_permissions(
+        self,
+        tool_input: dict,
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        return PermissionDecision(
+            behavior=PermissionBehavior.ASK,
+            message="fake tool requires confirmation",
+            decision_reason="test-only reason without the s-word",
+            bypass_immune=self._bypass_immune,
+        )
+
+
+class PermissionEngineBypassImmuneFieldTest(IsolatedAsyncioTestCase):
+    """Tests for the :attr:`PermissionDecision.bypass_immune` field.
+
+    These tests use a minimal fake tool that returns ASK with a
+    configurable ``bypass_immune`` value — independent of any specific
+    safety trigger — to verify the engine's mechanism for honoring the
+    field. Together with
+    :class:`PermissionEngineSafetyCheckAllowRuleImmuneTest` (which tests
+    that Bash/Write/Edit's individual safety checks correctly set the
+    field), this fully covers the bypass-immune contract.
+    """
+
+    async def test_bypass_immune_ask_not_overridden_by_allow_rule(
+        self,
+    ) -> None:
+        """An ASK with ``bypass_immune=True`` survives a matching allow
+        rule that would otherwise grant the operation."""
+        context = PermissionContext(mode=PermissionMode.DEFAULT)
+        engine = PermissionEngine(context)
+        engine.add_rule(
+            PermissionRule(
+                tool_name="FakeAskTool",
+                rule_content=None,
+                behavior=PermissionBehavior.ALLOW,
+                source="test",
+            ),
+        )
+
+        decision = await engine.check_permission(
+            _FakeToolReturningAsk(bypass_immune=True),
+            {},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.ASK)
+
+    async def test_non_bypass_immune_ask_overridden_by_allow_rule(
+        self,
+    ) -> None:
+        """A regular ASK (``bypass_immune=False``) yields to a matching
+        allow rule — proving the field, not the ``decision_reason``
+        text, governs immunity."""
+        context = PermissionContext(mode=PermissionMode.DEFAULT)
+        engine = PermissionEngine(context)
+        engine.add_rule(
+            PermissionRule(
+                tool_name="FakeAskTool",
+                rule_content=None,
+                behavior=PermissionBehavior.ALLOW,
+                source="test",
+            ),
+        )
+
+        decision = await engine.check_permission(
+            _FakeToolReturningAsk(bypass_immune=False),
+            {},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.ALLOW)
+
+    async def test_bypass_mode_ignores_bypass_immune_field(self) -> None:
+        """BYPASS is intentionally permissive: even an ASK with
+        ``bypass_immune=True`` is allowed through. The user has opted
+        out of safety prompts; ``bypass_immune`` only governs allow
+        rules (in DEFAULT) and DONT_ASK conversion.
+        """
+        context = PermissionContext(mode=PermissionMode.BYPASS)
+        engine = PermissionEngine(context)
+
+        decision = await engine.check_permission(
+            _FakeToolReturningAsk(bypass_immune=True),
+            {},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.ALLOW)
+
+    async def test_bypass_mode_allows_non_bypass_immune_ask(self) -> None:
+        """For completeness: a non-bypass-immune ASK is also allowed
+        through in BYPASS — same outcome, different path."""
+        context = PermissionContext(mode=PermissionMode.BYPASS)
+        engine = PermissionEngine(context)
+
+        decision = await engine.check_permission(
+            _FakeToolReturningAsk(bypass_immune=False),
+            {},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.ALLOW)
+
+    async def test_bypass_immune_ask_converted_to_deny_in_dont_ask(
+        self,
+    ) -> None:
+        """Under DONT_ASK, even a bypass-immune ASK is converted to
+        DENY (issue #3 contract): no user is available to confirm,
+        so the only safe action is to refuse."""
+        context = PermissionContext(mode=PermissionMode.DONT_ASK)
+        engine = PermissionEngine(context)
+
+        decision = await engine.check_permission(
+            _FakeToolReturningAsk(bypass_immune=True),
+            {},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.DENY)
diff --git a/tests/permission_mode_test.py b/tests/permission_mode_test.py
new file mode 100644
index 0000000..ef57478
--- /dev/null
+++ b/tests/permission_mode_test.py
@@ -0,0 +1,895 @@
+# -*- coding: utf-8 -*-
+"""Per-mode test cases for ``PermissionEngine``.
+
+Each :class:`PermissionMode` has its own test class so the policy of
+that mode can be verified in isolation. Tests cover:
+
+- the three rule layers (deny / ask / allow) for that mode
+- the ``tool.check_permissions`` return paths (ALLOW / DENY / safety-ASK
+  / PASSTHROUGH)
+- mode-specific behavior (e.g. EXPLORE's read-only resolution,
+  ACCEPT_EDITS's working-directory auto-allow, BYPASS's safety-ASK
+  immunity, DONT_ASK's default DENY)
+- Bash dynamic read-only / non-read-only / dangerous commands where
+  relevant
+
+Specific safety-check triggers (injection, dangerous removal, sed
+constraints, dangerous config paths) are tested separately in
+``permission_engine_test.py::PermissionEngineSafetyCheckAllowRuleImmuneTest``.
+"""
+import os
+import sys
+import tempfile
+import unittest
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from agentscope.permission import (
+    PermissionEngine,
+    PermissionMode,
+    PermissionContext,
+    PermissionRule,
+    PermissionBehavior,
+    AdditionalWorkingDirectory,
+)
+from agentscope.tool import (
+    Bash,
+    Write,
+    Read,
+    Edit,
+)
+
+
+# ---------------------------------------------------------------------------
+# DEFAULT mode
+# ---------------------------------------------------------------------------
+
+
+class PermissionEngineDefaultModeTest(IsolatedAsyncioTestCase):
+    """Tests for :attr:`PermissionMode.DEFAULT`.
+
+    DEFAULT is the most restrictive non-DONT_ASK mode: every operation
+    requires explicit permission unless an allow rule matches or the
+    tool itself returns ALLOW (e.g. Bash auto-allows known read-only
+    commands).
+    """
+
+    async def asyncSetUp(self) -> None:
+        self.context = PermissionContext(mode=PermissionMode.DEFAULT)
+        self.engine = PermissionEngine(self.context)
+
+    async def test_default_write_with_no_rules_returns_ask(self) -> None:
+        """Write to a safe path with no matching rules falls to the
+        engine's default ASK."""
+        decision = await self.engine.check_permission(
+            Write(),
+            {"file_path": "/tmp/file.txt"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.ASK)
+
+    async def test_default_deny_rule_returns_deny(self) -> None:
+        """Deny rule has the highest priority."""
+        self.engine.add_rule(
+            PermissionRule(
+                tool_name="Write",
+                rule_content="*.env",
+                behavior=PermissionBehavior.DENY,
+                source="test",
+            ),
+        )
+        decision = await self.engine.check_permission(
+            Write(),
+            {"file_path": "/tmp/secret.env"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.DENY)
+
+    async def test_default_ask_rule_returns_ask_with_suggestions(
+        self,
+    ) -> None:
+        """Ask rule short-circuits before the tool's own check and
+        attaches ``suggested_rules``."""
+        self.engine.add_rule(
+            PermissionRule(
+                tool_name="Write",
+                rule_content="*.py",
+                behavior=PermissionBehavior.ASK,
+                source="test",
+            ),
+        )
+        decision = await self.engine.check_permission(
+            Write(),
+            {"file_path": "/tmp/main.py"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.ASK)
+        self.assertIsNotNone(decision.suggested_rules)
+        self.assertGreater(len(decision.suggested_rules), 0)
+
+    async def test_default_allow_rule_returns_allow(self) -> None:
+        """Allow rule grants permission when no deny/ask rule and no
+        safety ASK applies."""
+        self.engine.add_rule(
+            PermissionRule(
+                tool_name="Write",
+                rule_content="/tmp/**",
+                behavior=PermissionBehavior.ALLOW,
+                source="test",
+            ),
+        )
+        decision = await self.engine.check_permission(
+            Write(),
+            {"file_path": "/tmp/file.txt"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.ALLOW)
+
+    @unittest.skipIf(
+        sys.platform == "win32",
+        "Bash tool is not supported on Windows",
+    )
+    async def test_default_bash_read_only_command_auto_allows(self) -> None:
+        """Bash returns ALLOW for known read-only commands, which the
+        engine surfaces directly in DEFAULT mode."""
+        for command in ("ls -a", "pwd", "git status", "cat README.md"):
+            decision = await self.engine.check_permission(
+                Bash(),
+                {"command": command},
+            )
+            self.assertEqual(
+                decision.behavior,
+                PermissionBehavior.ALLOW,
+                f"Expected ALLOW for read-only bash command: {command}",
+            )
+
+    @unittest.skipIf(
+        sys.platform == "win32",
+        "Bash tool is not supported on Windows",
+    )
+    async def test_default_bash_modification_command_returns_ask(
+        self,
+    ) -> None:
+        """Bash modification commands (no matching rule) fall through to
+        the engine's default ASK."""
+        decision = await self.engine.check_permission(
+            Bash(),
+            {"command": "npm install"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.ASK)
+
+    async def test_default_dangerous_path_safety_ask(self) -> None:
+        """Write to a dangerous path produces a safety ASK from the tool
+        itself (bypass-immune)."""
+        decision = await self.engine.check_permission(
+            Write(),
+            {"file_path": "/home/user/.bashrc"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.ASK)
+        self.assertIn("safety", (decision.decision_reason or "").lower())
+
+    async def test_default_safety_ask_not_overridden_by_allow_rule(
+        self,
+    ) -> None:
+        """A user-configured allow rule must not override a tool's
+        safety ASK (bypass-immune)."""
+        self.engine.add_rule(
+            PermissionRule(
+                tool_name="Write",
+                rule_content="**",
+                behavior=PermissionBehavior.ALLOW,
+                source="test",
+            ),
+        )
+        decision = await self.engine.check_permission(
+            Write(),
+            {"file_path": "/home/user/.bashrc"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.ASK)
+
+
+# ---------------------------------------------------------------------------
+# EXPLORE mode
+# ---------------------------------------------------------------------------
+
+
+class PermissionEngineExploreModeTest(IsolatedAsyncioTestCase):
+    """Tests for :attr:`PermissionMode.EXPLORE`.
+
+    EXPLORE is the read-only mode: an invocation is ALLOWed iff
+    :meth:`ToolBase.check_read_only` returns True; everything else is
+    DENIed outright. ``tool.check_permissions`` is intentionally not
+    consulted (the read-only verdict is final), and allow rules cannot
+    grant write access — EXPLORE's read-only invariant is non-negotiable.
+    """
+
+    async def asyncSetUp(self) -> None:
+        self.context = PermissionContext(mode=PermissionMode.EXPLORE)
+        self.engine = PermissionEngine(self.context)
+
+    async def test_explore_read_tool_allows(self) -> None:
+        """Statically read-only tools (Read/Glob/Grep) → ALLOW."""
+        decision = await self.engine.check_permission(
+            Read(),
+            {"file_path": "/tmp/file.txt"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.ALLOW)
+
+    async def test_explore_write_tool_denies(self) -> None:
+        """Statically non-read-only tools (Write/Edit) → DENY."""
+        decision = await self.engine.check_permission(
+            Write(),
+            {"file_path": "/tmp/file.txt"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.DENY)
+
+    async def test_explore_deny_rule_returns_deny(self) -> None:
+        """Deny rule still has top priority in EXPLORE."""
+        self.engine.add_rule(
+            PermissionRule(
+                tool_name="Read",
+                rule_content="/secret/**",
+                behavior=PermissionBehavior.DENY,
+                source="test",
+            ),
+        )
+        decision = await self.engine.check_permission(
+            Read(),
+            {"file_path": "/secret/key.txt"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.DENY)
+
+    async def test_explore_ask_rule_on_read_only_tool_returns_ask(
+        self,
+    ) -> None:
+        """Ask rules apply before the read-only fast-path, so a read-only
+        tool with a matching ask rule still surfaces as ASK.
+
+        Documents current behavior — this is the design point tracked
+        as issue #7.
+        """
+        self.engine.add_rule(
+            PermissionRule(
+                tool_name="Read",
+                rule_content="**/*.env",
+                behavior=PermissionBehavior.ASK,
+                source="test",
+            ),
+        )
+        decision = await self.engine.check_permission(
+            Read(),
+            {"file_path": "/tmp/secret.env"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.ASK)
+
+    async def test_explore_allow_rule_does_not_override_deny(self) -> None:
+        """EXPLORE's deny on non-read-only tools is the invariant; an
+        allow rule must not be able to grant write access."""
+        self.engine.add_rule(
+            PermissionRule(
+                tool_name="Write",
+                rule_content="**",
+                behavior=PermissionBehavior.ALLOW,
+                source="test",
+            ),
+        )
+        decision = await self.engine.check_permission(
+            Write(),
+            {"file_path": "/tmp/file.txt"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.DENY)
+
+    async def test_explore_dangerous_path_returns_deny_not_safety_ask(
+        self,
+    ) -> None:
+        """EXPLORE never invokes ``tool.check_permissions``, so a dangerous
+        path on a write tool surfaces as DENY (the read-only verdict)
+        rather than a safety ASK. DENY is strictly stronger than ASK, so
+        this is consistent with EXPLORE's "no writes" guarantee.
+        """
+        decision = await self.engine.check_permission(
+            Write(),
+            {"file_path": "/home/user/.bashrc"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.DENY)
+
+    @unittest.skipIf(
+        sys.platform == "win32",
+        "Bash tool is not supported on Windows",
+    )
+    async def test_explore_bash_read_only_command_allows(self) -> None:
+        """EXPLORE allows read-only bash commands via
+        :meth:`Bash.check_read_only` (regression for issue #1)."""
+        for command in ("ls -a", "pwd", "git status", "cat README.md"):
+            decision = await self.engine.check_permission(
+                Bash(),
+                {"command": command},
+            )
+            self.assertEqual(
+                decision.behavior,
+                PermissionBehavior.ALLOW,
+                f"Expected ALLOW for read-only bash command: {command}",
+            )
+
+    @unittest.skipIf(
+        sys.platform == "win32",
+        "Bash tool is not supported on Windows",
+    )
+    async def test_explore_bash_modification_command_denies(self) -> None:
+        """EXPLORE denies bash commands that are not statically
+        recognized as read-only."""
+        for command in ("cp a b", "mv a b", "touch /tmp/x"):
+            decision = await self.engine.check_permission(
+                Bash(),
+                {"command": command},
+            )
+            self.assertEqual(
+                decision.behavior,
+                PermissionBehavior.DENY,
+                f"Expected DENY for non-read-only bash command: {command}",
+            )
+
+    @unittest.skipIf(
+        sys.platform == "win32",
+        "Bash tool is not supported on Windows",
+    )
+    async def test_explore_bash_dangerous_command_denies(self) -> None:
+        """EXPLORE denies dangerous commands directly — in DEFAULT mode
+        the same command would surface as a safety ASK, but EXPLORE is
+        stricter."""
+        decision = await self.engine.check_permission(
+            Bash(),
+            {"command": "rm -rf /"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.DENY)
+
+
+# ---------------------------------------------------------------------------
+# ACCEPT_EDITS mode
+# ---------------------------------------------------------------------------
+
+
+class PermissionEngineAcceptEditsModeTest(IsolatedAsyncioTestCase):
+    """Tests for :attr:`PermissionMode.ACCEPT_EDITS`.
+
+    ACCEPT_EDITS auto-allows file edits within configured working
+    directories; reads are auto-allowed unconditionally; other
+    operations follow the normal DEFAULT-like flow.
+    """
+
+    async def asyncSetUp(self) -> None:
+        self.context = PermissionContext(
+            mode=PermissionMode.ACCEPT_EDITS,
+            working_directories={
+                "/tmp/project": AdditionalWorkingDirectory(
+                    path="/tmp/project",
+                    source="test",
+                ),
+            },
+        )
+        self.engine = PermissionEngine(self.context)
+
+    async def test_accept_edits_within_working_directory(self) -> None:
+        """Write / Read / Edit within a working directory → ALLOW."""
+        for tool in (Write(), Read(), Edit()):
+            decision = await self.engine.check_permission(
+                tool,
+                {"file_path": "/tmp/project/file.txt"},
+            )
+            self.assertEqual(
+                decision.behavior,
+                PermissionBehavior.ALLOW,
+                f"Expected ALLOW for {tool.name} in working directory",
+            )
+
+    @unittest.skipIf(
+        os.name == "nt",
+        "os.symlink typically requires admin privileges on Windows",
+    )
+    async def test_accept_edits_resolves_symlinked_working_directory(
+        self,
+    ) -> None:
+        """Working directory comparison must use ``realpath`` so a path
+        reached through a symlink (e.g. macOS's ``/tmp`` ->
+        ``/private/tmp``) is recognized. Regression test for the
+        ``abspath`` → ``realpath`` fix in
+        :meth:`_path_in_allowed_working_path`.
+        """
+        parent = tempfile.mkdtemp()
+        try:
+            real_dir = os.path.join(parent, "real")
+            os.makedirs(real_dir)
+            link_dir = os.path.join(parent, "link")
+            os.symlink(real_dir, link_dir)
+
+            # Case 1: working_dir given as real path, file via link
+            context = PermissionContext(
+                mode=PermissionMode.ACCEPT_EDITS,
+                working_directories={
+                    real_dir: AdditionalWorkingDirectory(
+                        path=real_dir,
+                        source="test",
+                    ),
+                },
+            )
+            engine = PermissionEngine(context)
+            decision = await engine.check_permission(
+                Write(),
+                {"file_path": os.path.join(link_dir, "file.txt")},
+            )
+            self.assertEqual(decision.behavior, PermissionBehavior.ALLOW)
+
+            # Case 2: working_dir given as link, file via real path
+            context = PermissionContext(
+                mode=PermissionMode.ACCEPT_EDITS,
+                working_directories={
+                    link_dir: AdditionalWorkingDirectory(
+                        path=link_dir,
+                        source="test",
+                    ),
+                },
+            )
+            engine = PermissionEngine(context)
+            decision = await engine.check_permission(
+                Edit(),
+                {"file_path": os.path.join(real_dir, "file.txt")},
+            )
+            self.assertEqual(decision.behavior, PermissionBehavior.ALLOW)
+        finally:
+            import shutil
+
+            shutil.rmtree(parent, ignore_errors=True)
+
+    async def test_accept_edits_outside_working_directory(self) -> None:
+        """Edit outside a working directory falls to the default ASK."""
+        decision = await self.engine.check_permission(
+            Edit(),
+            {"file_path": "/home/user/file.txt"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.ASK)
+
+    async def test_accept_edits_read_operation_auto_allowed(self) -> None:
+        """Read tool is auto-allowed regardless of path (read-only fast
+        path)."""
+        decision = await self.engine.check_permission(
+            Read(),
+            {"file_path": "/anywhere/file.txt"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.ALLOW)
+
+    async def test_accept_edits_deny_rule_returns_deny(self) -> None:
+        """Deny rule overrides ACCEPT_EDITS's working-directory
+        auto-allow."""
+        self.engine.add_rule(
+            PermissionRule(
+                tool_name="Write",
+                rule_content="**/*.lock",
+                behavior=PermissionBehavior.DENY,
+                source="test",
+            ),
+        )
+        decision = await self.engine.check_permission(
+            Write(),
+            {"file_path": "/tmp/project/poetry.lock"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.DENY)
+
+    async def test_accept_edits_ask_rule_returns_ask(self) -> None:
+        """Ask rule short-circuits before the working-directory check."""
+        self.engine.add_rule(
+            PermissionRule(
+                tool_name="Edit",
+                rule_content="**/*.py",
+                behavior=PermissionBehavior.ASK,
+                source="test",
+            ),
+        )
+        decision = await self.engine.check_permission(
+            Edit(),
+            {"file_path": "/tmp/project/main.py"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.ASK)
+
+    async def test_accept_edits_dangerous_path_safety_ask(self) -> None:
+        """Safety ASK from a dangerous path is bypass-immune even when
+        the path is inside a working directory.
+        """
+        decision = await self.engine.check_permission(
+            Write(),
+            {"file_path": "/home/user/.bashrc"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.ASK)
+        self.assertIn("safety", (decision.decision_reason or "").lower())
+
+    @unittest.skipIf(
+        sys.platform == "win32",
+        "Bash tool is not supported on Windows",
+    )
+    async def test_accept_edits_bash_read_only_command_allows(self) -> None:
+        """Read-only bash commands ALLOW via the read-only fast path."""
+        decision = await self.engine.check_permission(
+            Bash(),
+            {"command": "ls -a"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.ALLOW)
+
+    @unittest.skipIf(
+        sys.platform == "win32",
+        "Bash tool is not supported on Windows",
+    )
+    async def test_accept_edits_bash_filesystem_command_inside_working_dir(
+        self,
+    ) -> None:
+        """ACCEPT_EDITS auto-allows recognized filesystem commands
+        (``mkdir``, ``touch``, ``rm``, ``cp``, ``mv``, ``sed``,
+        ``rmdir``) when **all** target paths are inside the configured
+        working directories."""
+        cases = [
+            "touch /tmp/project/new.txt",
+            "mkdir /tmp/project/newdir",
+            "rm /tmp/project/old.txt",
+            "rmdir /tmp/project/olddir",
+            "cp /tmp/project/a /tmp/project/b",
+            "mv /tmp/project/a /tmp/project/b",
+            "sed -i 's/x/y/g' /tmp/project/foo.txt",
+        ]
+        for command in cases:
+            decision = await self.engine.check_permission(
+                Bash(),
+                {"command": command},
+            )
+            self.assertEqual(
+                decision.behavior,
+                PermissionBehavior.ALLOW,
+                f"Expected ALLOW for in-working-dir command: {command}",
+            )
+
+    @unittest.skipIf(
+        sys.platform == "win32",
+        "Bash tool is not supported on Windows",
+    )
+    async def test_accept_edits_bash_filesystem_command_outside_working_dir(
+        self,
+    ) -> None:
+        """Regression for issue #4: filesystem commands whose targets
+        escape the working directory must NOT be auto-allowed.
+
+        Without this guard ``cp /etc/hosts /Users/me/other-project/x``
+        would silently succeed in ACCEPT_EDITS even though the
+        equivalent ``Write`` call is correctly denied. The asserted
+        behavior is ASK (the PASSTHROUGH from Bash + the engine's
+        default ASK in ACCEPT_EDITS).
+        """
+        cases = [
+            # Target entirely outside the working directory
+            "rm /Users/someone/other/foo",
+            "touch /Users/someone/other/foo",
+            "mkdir /Users/someone/other/newdir",
+            # cp / mv: at least one of (src, dst) outside
+            "cp /tmp/project/a /Users/someone/other/b",
+            "cp /Users/someone/other/a /tmp/project/b",
+            "mv /tmp/project/a /Users/someone/other/b",
+            # sed in-place modifying a file outside
+            "sed -i 's/x/y/g' /Users/someone/other/foo.txt",
+        ]
+        for command in cases:
+            decision = await self.engine.check_permission(
+                Bash(),
+                {"command": command},
+            )
+            self.assertEqual(
+                decision.behavior,
+                PermissionBehavior.ASK,
+                f"Expected ASK for outside-working-dir command: {command}",
+            )
+
+    @unittest.skipIf(
+        sys.platform == "win32",
+        "Bash tool is not supported on Windows",
+    )
+    async def test_accept_edits_bash_filesystem_command_no_args_not_allowed(
+        self,
+    ) -> None:
+        """Conservative behavior: if the parser extracts no target paths
+        (e.g. a bare ``mkdir`` with no arguments), we do not auto-allow.
+        The command itself will fail at execution, but it should not
+        silently pass the permission check."""
+        decision = await self.engine.check_permission(
+            Bash(),
+            {"command": "mkdir"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.ASK)
+
+
+# ---------------------------------------------------------------------------
+# BYPASS mode
+# ---------------------------------------------------------------------------
+
+
+class PermissionEngineBypassModeTest(IsolatedAsyncioTestCase):
+    """Tests for :attr:`PermissionMode.BYPASS`.
+
+    BYPASS is the "fully trusted" mode: the user has opted out of all
+    safety prompts. The only guardrails left are user-configured deny
+    / ask rules and tool-emitted DENY. Every bypass-immune safety ASK
+    (dangerous removal, dangerous paths, sed in-place on sensitive
+    files, command injection, ...) is intentionally **skipped**.
+    Use BYPASS only in sandboxed environments or when you fully trust
+    the agent.
+    """
+
+    async def asyncSetUp(self) -> None:
+        self.context = PermissionContext(mode=PermissionMode.BYPASS)
+        self.engine = PermissionEngine(self.context)
+
+    @unittest.skipIf(
+        sys.platform == "win32",
+        "Bash tool is not supported on Windows",
+    )
+    async def test_bypass_no_rules_allows(self) -> None:
+        """No rules → ALLOW (BYPASS's default fallback)."""
+        decision = await self.engine.check_permission(
+            Bash(),
+            {"command": "npm install"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.ALLOW)
+
+    @unittest.skipIf(
+        sys.platform == "win32",
+        "Bash tool is not supported on Windows",
+    )
+    async def test_bypass_deny_rule_returns_deny(self) -> None:
+        """Deny rules are bypass-immune."""
+        self.engine.add_rule(
+            PermissionRule(
+                tool_name="Bash",
+                rule_content="rm:*",
+                behavior=PermissionBehavior.DENY,
+                source="test",
+            ),
+        )
+        decision = await self.engine.check_permission(
+            Bash(),
+            {"command": "rm -rf /tmp/foo"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.DENY)
+
+    @unittest.skipIf(
+        sys.platform == "win32",
+        "Bash tool is not supported on Windows",
+    )
+    async def test_bypass_ask_rule_returns_ask(self) -> None:
+        """A user-configured ask rule represents explicit intent to be
+        prompted; BYPASS must not override it."""
+        self.engine.add_rule(
+            PermissionRule(
+                tool_name="Bash",
+                rule_content="git push:*",
+                behavior=PermissionBehavior.ASK,
+                source="test",
+            ),
+        )
+        decision = await self.engine.check_permission(
+            Bash(),
+            {"command": "git push origin main"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.ASK)
+
+    async def test_bypass_skips_dangerous_path_safety(self) -> None:
+        """BYPASS skips the Write tool's dangerous-path safety check —
+        writing to ``~/.bashrc`` is allowed through."""
+        decision = await self.engine.check_permission(
+            Write(),
+            {"file_path": "/home/user/.bashrc"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.ALLOW)
+
+    @unittest.skipIf(
+        sys.platform == "win32",
+        "Bash tool is not supported on Windows",
+    )
+    async def test_bypass_skips_dangerous_removal(self) -> None:
+        """BYPASS skips Bash's dangerous-removal safety check —
+        ``rm -rf /`` is allowed through."""
+        decision = await self.engine.check_permission(
+            Bash(),
+            {"command": "rm -rf /"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.ALLOW)
+
+    @unittest.skipIf(
+        sys.platform == "win32",
+        "Bash tool is not supported on Windows",
+    )
+    async def test_bypass_skips_command_injection(self) -> None:
+        """BYPASS skips Bash's command-injection safety check —
+        dynamic expansion is allowed through."""
+        decision = await self.engine.check_permission(
+            Bash(),
+            {"command": "ls $(date +%s)"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.ALLOW)
+
+    @unittest.skipIf(
+        sys.platform == "win32",
+        "Bash tool is not supported on Windows",
+    )
+    async def test_bypass_skips_sed_dangerous_file(self) -> None:
+        """BYPASS skips Bash's sed-on-dangerous-file safety check."""
+        decision = await self.engine.check_permission(
+            Bash(),
+            {"command": "sed 's/old/new/e' file.txt"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.ALLOW)
+
+    @unittest.skipIf(
+        sys.platform == "win32",
+        "Bash tool is not supported on Windows",
+    )
+    async def test_bypass_skips_dangerous_config_path_in_bash(self) -> None:
+        """BYPASS skips Bash's dangerous-config-path safety check —
+        operating on ``~/.bashrc`` via bash is allowed through."""
+        decision = await self.engine.check_permission(
+            Bash(),
+            {"command": "rm ~/.bashrc"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.ALLOW)
+
+    @unittest.skipIf(
+        sys.platform == "win32",
+        "Bash tool is not supported on Windows",
+    )
+    async def test_bypass_tool_allow_returns_allow(self) -> None:
+        """Tool's own ALLOW (e.g. Bash read-only command) is returned
+        as-is in BYPASS as in any mode."""
+        decision = await self.engine.check_permission(
+            Bash(),
+            {"command": "ls -a"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.ALLOW)
+
+
+# ---------------------------------------------------------------------------
+# DONT_ASK mode
+# ---------------------------------------------------------------------------
+
+
+class PermissionEngineDontAskModeTest(IsolatedAsyncioTestCase):
+    """Tests for :attr:`PermissionMode.DONT_ASK`.
+
+    DONT_ASK is used when no user is available to answer prompts
+    (scheduled tasks, background runs). The invariant is "never return
+    ASK" — every ASK-producing code path (default, ASK rule, safety
+    ASK) is converted to DENY.
+    """
+
+    async def asyncSetUp(self) -> None:
+        self.context = PermissionContext(mode=PermissionMode.DONT_ASK)
+        self.engine = PermissionEngine(self.context)
+
+    @unittest.skipIf(
+        sys.platform == "win32",
+        "Bash tool is not supported on Windows",
+    )
+    async def test_dont_ask_no_rules_returns_deny(self) -> None:
+        """No rules → DENY (DONT_ASK's default)."""
+        decision = await self.engine.check_permission(
+            Bash(),
+            {"command": "npm install"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.DENY)
+
+    @unittest.skipIf(
+        sys.platform == "win32",
+        "Bash tool is not supported on Windows",
+    )
+    async def test_dont_ask_deny_rule_returns_deny(self) -> None:
+        """Deny rules apply normally."""
+        self.engine.add_rule(
+            PermissionRule(
+                tool_name="Bash",
+                rule_content="rm:*",
+                behavior=PermissionBehavior.DENY,
+                source="test",
+            ),
+        )
+        decision = await self.engine.check_permission(
+            Bash(),
+            {"command": "rm -rf /tmp/foo"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.DENY)
+
+    async def test_dont_ask_allow_rule_returns_allow(self) -> None:
+        """An explicit allow rule still grants permission in DONT_ASK."""
+        self.engine.add_rule(
+            PermissionRule(
+                tool_name="Write",
+                rule_content="/tmp/**",
+                behavior=PermissionBehavior.ALLOW,
+                source="test",
+            ),
+        )
+        decision = await self.engine.check_permission(
+            Write(),
+            {"file_path": "/tmp/file.txt"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.ALLOW)
+
+    @unittest.skipIf(
+        sys.platform == "win32",
+        "Bash tool is not supported on Windows",
+    )
+    async def test_dont_ask_bash_read_only_command_allows(self) -> None:
+        """Tool's own ALLOW (Bash read-only command) is still ALLOW
+        under DONT_ASK — no user prompt is needed."""
+        decision = await self.engine.check_permission(
+            Bash(),
+            {"command": "ls -a"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.ALLOW)
+
+    async def test_dont_ask_ask_rule_returns_deny(self) -> None:
+        """An ASK rule hit is converted to DENY (issue #3): the user is
+        not available to answer the prompt, so the operation cannot
+        proceed."""
+        self.engine.add_rule(
+            PermissionRule(
+                tool_name="Write",
+                rule_content="**/*.py",
+                behavior=PermissionBehavior.ASK,
+                source="test",
+            ),
+        )
+        decision = await self.engine.check_permission(
+            Write(),
+            {"file_path": "/tmp/main.py"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.DENY)
+
+    async def test_dont_ask_ask_rule_conversion_preserves_suggestions(
+        self,
+    ) -> None:
+        """Converted DENY decisions keep the original ASK's
+        ``suggested_rules`` so callers can surface them to the user
+        out-of-band (e.g. in a scheduled-task failure report)."""
+        self.engine.add_rule(
+            PermissionRule(
+                tool_name="Write",
+                rule_content="**/*.py",
+                behavior=PermissionBehavior.ASK,
+                source="test",
+            ),
+        )
+        decision = await self.engine.check_permission(
+            Write(),
+            {"file_path": "/tmp/main.py"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.DENY)
+        self.assertIsNotNone(decision.suggested_rules)
+        self.assertGreater(len(decision.suggested_rules), 0)
+
+    async def test_dont_ask_safety_ask_returns_deny(self) -> None:
+        """A safety ASK from ``tool.check_permissions`` (e.g. Write to a
+        dangerous path) is converted to DENY (issue #3) — DONT_ASK
+        respects the safety verdict but cannot ask the user, so the
+        only safe action is to refuse."""
+        decision = await self.engine.check_permission(
+            Write(),
+            {"file_path": "/home/user/.bashrc"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.DENY)
+        # Conversion records both the original safety reason and the
+        # DONT_ASK conversion in the decision_reason.
+        reason = (decision.decision_reason or "").lower()
+        self.assertIn("dont_ask", reason)
+        self.assertIn("safety", reason)
+
+    @unittest.skipIf(
+        sys.platform == "win32",
+        "Bash tool is not supported on Windows",
+    )
+    async def test_dont_ask_bash_dangerous_command_returns_deny(
+        self,
+    ) -> None:
+        """``rm -rf /`` triggers a safety ASK from Bash, which DONT_ASK
+        converts to DENY (issue #3)."""
+        decision = await self.engine.check_permission(
+            Bash(),
+            {"command": "rm -rf /"},
+        )
+        self.assertEqual(decision.behavior, PermissionBehavior.DENY)
diff --git a/tests/rag_chunker_approx_token_test.py b/tests/rag_chunker_approx_token_test.py
new file mode 100644
index 0000000..db18e3e
--- /dev/null
+++ b/tests/rag_chunker_approx_token_test.py
@@ -0,0 +1,204 @@
+# -*- coding: utf-8 -*-
+"""Unit tests for the ApproxTokenChunker class."""
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from utils import AnyString
+
+from agentscope.message import Base64Source, DataBlock, TextBlock
+from agentscope.rag import ApproxTokenChunker, Chunk, Section
+
+
+def _dump_chunks(chunks: list[Chunk]) -> list[dict]:
+    """Convert chunks into plain dicts for whole-structure comparison.
+
+    Args:
+        chunks (`list[Chunk]`):
+            The chunks to convert.
+
+    Returns:
+        `list[dict]`:
+            The chunks as plain dicts.
+    """
+    return [chunk.model_dump() for chunk in chunks]
+
+
+class ApproxTokenChunkerTest(IsolatedAsyncioTestCase):
+    """The test cases for the ApproxTokenChunker class."""
+
+    async def test_short_text_single_chunk(self) -> None:
+        """Short text should produce a single chunk."""
+        chunker = ApproxTokenChunker(chunk_size=512, overlap=50)
+        sections = [
+            Section(
+                content=TextBlock(text="Hello world!"),
+                source="a.txt",
+                metadata={"page": 1},
+            ),
+        ]
+
+        chunks = await chunker.chunk(sections)
+
+        self.assertEqual(
+            _dump_chunks(chunks),
+            [
+                {
+                    "content": {
+                        "type": "text",
+                        "text": "Hello world!",
+                        "id": AnyString(),
+                    },
+                    "source": "a.txt",
+                    "chunk_index": 0,
+                    "total_chunks": 1,
+                    "metadata": {"page": 1},
+                },
+            ],
+        )
+
+    async def test_long_text_split_with_overlap(self) -> None:
+        """Long text should be split into overlapping chunks."""
+        # chunk_size=10 tokens -> 40-byte window, overlap=2 -> 8-byte step
+        # back, so for ASCII text the windows start at 0, 32, 64, ...
+        chunker = ApproxTokenChunker(chunk_size=10, overlap=2)
+        text = "abcdefghij" * 20  # 200 ASCII chars => 50 approx tokens
+        sections = [
+            Section(
+                content=TextBlock(text=text),
+                source="b.txt",
+            ),
+        ]
+
+        chunks = await chunker.chunk(sections)
+
+        self.assertEqual(
+            _dump_chunks(chunks),
+            [
+                {
+                    "content": {
+                        "type": "text",
+                        "text": text[start : start + 40],
+                        "id": AnyString(),
+                    },
+                    "source": "b.txt",
+                    "chunk_index": index,
+                    "total_chunks": 6,
+                    "metadata": {},
+                }
+                for index, start in enumerate([0, 32, 64, 96, 128, 160])
+            ],
+        )
+
+    async def test_data_block_pass_through(self) -> None:
+        """DataBlock sections should pass through unchanged."""
+        chunker = ApproxTokenChunker(chunk_size=10, overlap=2)
+        data_block = DataBlock(
+            source=Base64Source(data="aGk=", media_type="image/png"),
+        )
+        sections = [
+            Section(
+                content=TextBlock(text="x" * 100),
+                source="c.pdf",
+            ),
+            Section(
+                content=data_block,
+                source="c.pdf",
+                metadata={"page": 2},
+            ),
+        ]
+
+        chunks = await chunker.chunk(sections)
+
+        self.assertEqual(
+            _dump_chunks(chunks),
+            [
+                {
+                    "content": {
+                        "type": "text",
+                        "text": "x" * 40,
+                        "id": AnyString(),
+                    },
+                    "source": "c.pdf",
+                    "chunk_index": 0,
+                    "total_chunks": 4,
+                    "metadata": {},
+                },
+                {
+                    "content": {
+                        "type": "text",
+                        "text": "x" * 40,
+                        "id": AnyString(),
+                    },
+                    "source": "c.pdf",
+                    "chunk_index": 1,
+                    "total_chunks": 4,
+                    "metadata": {},
+                },
+                {
+                    "content": {
+                        "type": "text",
+                        "text": "x" * 36,
+                        "id": AnyString(),
+                    },
+                    "source": "c.pdf",
+                    "chunk_index": 2,
+                    "total_chunks": 4,
+                    "metadata": {},
+                },
+                {
+                    "content": {
+                        "type": "data",
+                        "id": AnyString(),
+                        "source": {
+                            "type": "base64",
+                            "data": "aGk=",
+                            "media_type": "image/png",
+                        },
+                        "name": None,
+                    },
+                    "source": "c.pdf",
+                    "chunk_index": 3,
+                    "total_chunks": 4,
+                    "metadata": {"page": 2},
+                },
+            ],
+        )
+        # The DataBlock instance itself is passed through, not copied
+        self.assertIs(chunks[-1].content, data_block)
+
+    async def test_no_cross_section_merging(self) -> None:
+        """Chunks must never combine content from two sections."""
+        chunker = ApproxTokenChunker(chunk_size=512, overlap=50)
+        sections = [
+            Section(content=TextBlock(text="first"), source="d.txt"),
+            Section(content=TextBlock(text="second"), source="d.txt"),
+        ]
+
+        chunks = await chunker.chunk(sections)
+
+        self.assertEqual(
+            _dump_chunks(chunks),
+            [
+                {
+                    "content": {
+                        "type": "text",
+                        "text": "first",
+                        "id": AnyString(),
+                    },
+                    "source": "d.txt",
+                    "chunk_index": 0,
+                    "total_chunks": 2,
+                    "metadata": {},
+                },
+                {
+                    "content": {
+                        "type": "text",
+                        "text": "second",
+                        "id": AnyString(),
+                    },
+                    "source": "d.txt",
+                    "chunk_index": 1,
+                    "total_chunks": 2,
+                    "metadata": {},
+                },
+            ],
+        )
diff --git a/tests/rag_parser_test.py b/tests/rag_parser_test.py
new file mode 100644
index 0000000..2a2232f
--- /dev/null
+++ b/tests/rag_parser_test.py
@@ -0,0 +1,1194 @@
+# -*- coding: utf-8 -*-
+"""Unit tests for the file parsers in :mod:`agentscope.rag._parser`.
+
+PDF / PPTX fixtures are produced in-memory via :mod:`reportlab` and
+:mod:`python-pptx` so the tests have no on-disk dependencies and can
+run anywhere ``agentscope[rag]`` is installed.
+"""
+import base64
+import io
+import os
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from utils import AnyString
+
+from agentscope.rag import (
+    ImageParser,
+    PDFParser,
+    PPTParser,
+    TextParser,
+    WordParser,
+    ExcelParser,
+)
+
+
+# Smallest valid PNG ever — a single transparent pixel.  Used wherever
+# a test needs "some image bytes" without depending on Pillow.
+_PNG_PIXEL: bytes = base64.b64decode(
+    "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNgAAIAAAUA"
+    "AarVyFEAAAAASUVORK5CYII=",
+)
+_PNG_PIXEL_B64: str = base64.b64encode(_PNG_PIXEL).decode("utf-8")
+
+
+def _make_pdf(pages: list[str]) -> bytes:
+    """Render the supplied page strings to a PDF in memory."""
+    from reportlab.pdfgen import canvas
+
+    buffer = io.BytesIO()
+    pdf = canvas.Canvas(buffer)
+    for page in pages:
+        pdf.drawString(72, 720, page)
+        pdf.showPage()
+    pdf.save()
+    return buffer.getvalue()
+
+
+def _make_pptx_simple(slides: list[str]) -> bytes:
+    """Build a PPTX in memory with one text shape per slide."""
+    from pptx import Presentation
+
+    prs = Presentation()
+    blank_layout = prs.slide_layouts[5]  # title-only layout
+    for text in slides:
+        slide = prs.slides.add_slide(blank_layout)
+        slide.shapes.title.text = text
+    buffer = io.BytesIO()
+    prs.save(buffer)
+    return buffer.getvalue()
+
+
+def _make_pptx_rich() -> bytes:
+    """Build a richer PPTX with text, a table, and an embedded image.
+
+    Slide 1: a single title text shape.
+    Slide 2: a title text shape, a 2x2 table, and a trailing text shape.
+    Slide 3: an embedded PNG image only (blank title).
+    """
+    from pptx import Presentation
+    from pptx.util import Inches
+
+    prs = Presentation()
+    blank_layout = prs.slide_layouts[5]
+
+    slide1 = prs.slides.add_slide(blank_layout)
+    slide1.shapes.title.text = "Hello"
+
+    slide2 = prs.slides.add_slide(blank_layout)
+    slide2.shapes.title.text = "Header"
+    table = slide2.shapes.add_table(
+        rows=2,
+        cols=2,
+        left=Inches(1),
+        top=Inches(2),
+        width=Inches(4),
+        height=Inches(1),
+    ).table
+    table.cell(0, 0).text = "A"
+    table.cell(0, 1).text = "B"
+    table.cell(1, 0).text = "1"
+    table.cell(1, 1).text = "2"
+    trailing = slide2.shapes.add_textbox(
+        Inches(1),
+        Inches(4),
+        Inches(4),
+        Inches(1),
+    )
+    trailing.text_frame.text = "Footer"
+
+    slide3 = prs.slides.add_slide(blank_layout)
+    slide3.shapes.title.text = ""  # blank title
+    slide3.shapes.add_picture(
+        io.BytesIO(_PNG_PIXEL),
+        Inches(1),
+        Inches(1),
+        Inches(1),
+        Inches(1),
+    )
+
+    buffer = io.BytesIO()
+    prs.save(buffer)
+    return buffer.getvalue()
+
+
+def _make_docx_simple(paragraphs: list[str]) -> bytes:
+    """Build a DOCX in memory with plain text paragraphs."""
+    from docx import Document as DocxDocument
+
+    doc = DocxDocument()
+    for text in paragraphs:
+        doc.add_paragraph(text)
+    buffer = io.BytesIO()
+    doc.save(buffer)
+    return buffer.getvalue()
+
+
+def _make_docx_with_table() -> bytes:
+    """Build a DOCX with a paragraph, a 2x2 table, and a trailing
+    paragraph."""
+    from docx import Document as DocxDocument
+
+    doc = DocxDocument()
+    doc.add_paragraph("Before table")
+
+    table = doc.add_table(rows=2, cols=2)
+    table.cell(0, 0).text = "A"
+    table.cell(0, 1).text = "B"
+    table.cell(1, 0).text = "1"
+    table.cell(1, 1).text = "2"
+
+    doc.add_paragraph("After table")
+
+    buffer = io.BytesIO()
+    doc.save(buffer)
+    return buffer.getvalue()
+
+
+def _make_docx_with_image() -> bytes:
+    """Build a DOCX with a paragraph and an embedded PNG image."""
+    from docx import Document as DocxDocument
+    from docx.shared import Inches
+
+    doc = DocxDocument()
+    doc.add_paragraph("Text before image")
+    doc.add_picture(io.BytesIO(_PNG_PIXEL), width=Inches(1))
+    doc.add_paragraph("Text after image")
+
+    buffer = io.BytesIO()
+    doc.save(buffer)
+    return buffer.getvalue()
+
+
+def _make_xlsx_simple(
+    sheets: dict[str, list[list[str]]],
+) -> bytes:
+    """Build an XLSX in memory from a dict of sheet_name → rows.
+
+    Each row is a list of cell strings; the first row becomes the
+    header in pandas.
+    """
+    import pandas as pd
+
+    buffer = io.BytesIO()
+    with pd.ExcelWriter(buffer, engine="openpyxl") as writer:
+        for sheet_name, rows in sheets.items():
+            if rows:
+                df = pd.DataFrame(rows[1:], columns=rows[0])
+            else:
+                df = pd.DataFrame()
+            df.to_excel(writer, sheet_name=sheet_name, index=False)
+    return buffer.getvalue()
+
+
+class TextParserTest(IsolatedAsyncioTestCase):
+    """Behavioural coverage for :class:`TextParser`."""
+
+    async def test_decode_bytes(self) -> None:
+        """Bytes are decoded with the configured encoding."""
+        parser = TextParser()
+        sections = await parser.parse(b"hello", "x.txt")
+        self.assertEqual(
+            [s.model_dump() for s in sections],
+            [
+                {
+                    "content": {
+                        "type": "text",
+                        "text": "hello",
+                        "id": AnyString(),
+                    },
+                    "source": "x.txt",
+                    "metadata": {},
+                },
+            ],
+        )
+
+    async def test_pre_decoded_string_round_trips(self) -> None:
+        """``str`` inputs skip the decode step when no such file exists."""
+        parser = TextParser()
+        sections = await parser.parse("preset", "x.md")
+        self.assertEqual(
+            [s.model_dump() for s in sections],
+            [
+                {
+                    "content": {
+                        "type": "text",
+                        "text": "preset",
+                        "id": AnyString(),
+                    },
+                    "source": "x.md",
+                    "metadata": {},
+                },
+            ],
+        )
+
+    async def test_string_input_treated_as_path(self) -> None:
+        """A ``str`` that names an existing file is read as a path."""
+        import tempfile
+
+        with tempfile.NamedTemporaryFile(
+            mode="w",
+            suffix=".txt",
+            delete=False,
+        ) as f:
+            f.write("from disk")
+            path = f.name
+        try:
+            parser = TextParser()
+            sections = await parser.parse(path, "x.txt")
+            self.assertEqual(len(sections), 1)
+            self.assertEqual(sections[0].content.text, "from disk")
+        finally:
+            os.unlink(path)
+
+    async def test_bad_encoding_raises_value_error(self) -> None:
+        """An undecodable byte sequence surfaces a clear error."""
+        parser = TextParser(encoding="ascii")
+        with self.assertRaises(ValueError):
+            await parser.parse(b"\xff\xfe", "bad.txt")
+
+
+class PDFParserTest(IsolatedAsyncioTestCase):
+    """Behavioural coverage for :class:`PDFParser`."""
+
+    async def test_one_section_per_page(self) -> None:
+        """Each page in the PDF round-trips to its own Section."""
+        pdf_bytes = _make_pdf(["First page text", "Second page text"])
+        parser = PDFParser()
+        sections = await parser.parse(pdf_bytes, "demo.pdf")
+
+        self.assertEqual(
+            [s.model_dump() for s in sections],
+            [
+                {
+                    "content": {
+                        "type": "text",
+                        "text": "First page text\n",
+                        "id": AnyString(),
+                    },
+                    "source": "demo.pdf",
+                    "metadata": {"page": 1},
+                },
+                {
+                    "content": {
+                        "type": "text",
+                        "text": "Second page text\n",
+                        "id": AnyString(),
+                    },
+                    "source": "demo.pdf",
+                    "metadata": {"page": 2},
+                },
+            ],
+        )
+
+    async def test_string_input_treated_as_path(self) -> None:
+        """``str`` is interpreted as a filesystem path to the PDF."""
+        import tempfile
+
+        pdf_bytes = _make_pdf(["Hello"])
+        with tempfile.NamedTemporaryFile(
+            suffix=".pdf",
+            delete=False,
+        ) as f:
+            f.write(pdf_bytes)
+            path = f.name
+        try:
+            parser = PDFParser()
+            sections = await parser.parse(path, "demo.pdf")
+            self.assertEqual(len(sections), 1)
+        finally:
+            os.unlink(path)
+
+    async def test_missing_path_raises_file_not_found(self) -> None:
+        """A ``str`` pointing at a missing path raises FileNotFoundError."""
+        parser = PDFParser()
+        with self.assertRaises(FileNotFoundError):
+            await parser.parse("/no/such/file.pdf", "x.pdf")
+
+    async def test_invalid_bytes_raise_value_error(self) -> None:
+        """Garbage bytes surface as :class:`ValueError`."""
+        parser = PDFParser()
+        with self.assertRaises(ValueError):
+            await parser.parse(b"not a pdf", "broken.pdf")
+
+    async def test_supported_extensions(self) -> None:
+        """``.pdf`` is the only extension exposed to the file picker."""
+        self.assertEqual(PDFParser.supported_extensions(), [".pdf"])
+
+
+class ImageParserTest(IsolatedAsyncioTestCase):
+    """Behavioural coverage for :class:`ImageParser`."""
+
+    async def test_wraps_bytes_in_data_block(self) -> None:
+        """A single Section is emitted with the image as a DataBlock."""
+        parser = ImageParser()
+        sections = await parser.parse(_PNG_PIXEL, "pixel.png")
+
+        self.assertEqual(
+            [s.model_dump() for s in sections],
+            [
+                {
+                    "content": {
+                        "type": "data",
+                        "id": AnyString(),
+                        "source": {
+                            "type": "base64",
+                            "data": _PNG_PIXEL_B64,
+                            "media_type": "image/png",
+                        },
+                        "name": "pixel.png",
+                    },
+                    "source": "pixel.png",
+                    "metadata": {"media_type": "image/png"},
+                },
+            ],
+        )
+
+    async def test_media_type_sniffed_from_jpeg(self) -> None:
+        """JPEG magic bytes yield ``image/jpeg``."""
+        jpeg_bytes = b"\xff\xd8\xff\xe0rest-of-jpeg"
+        parser = ImageParser()
+        sections = await parser.parse(jpeg_bytes, "x.jpg")
+        self.assertEqual(
+            [s.model_dump() for s in sections],
+            [
+                {
+                    "content": {
+                        "type": "data",
+                        "id": AnyString(),
+                        "source": {
+                            "type": "base64",
+                            "data": base64.b64encode(jpeg_bytes).decode(
+                                "utf-8",
+                            ),
+                            "media_type": "image/jpeg",
+                        },
+                        "name": "x.jpg",
+                    },
+                    "source": "x.jpg",
+                    "metadata": {"media_type": "image/jpeg"},
+                },
+            ],
+        )
+
+    async def test_string_input_treated_as_path(self) -> None:
+        """``str`` is interpreted as a filesystem path to the image."""
+        import tempfile
+
+        with tempfile.NamedTemporaryFile(
+            suffix=".png",
+            delete=False,
+        ) as f:
+            f.write(_PNG_PIXEL)
+            path = f.name
+        try:
+            parser = ImageParser()
+            sections = await parser.parse(path, "pixel.png")
+            self.assertEqual(len(sections), 1)
+        finally:
+            os.unlink(path)
+
+    async def test_missing_path_raises_file_not_found(self) -> None:
+        """A ``str`` pointing at a missing path raises FileNotFoundError."""
+        parser = ImageParser()
+        with self.assertRaises(FileNotFoundError):
+            await parser.parse("/no/such/file.png", "x.png")
+
+
+class PPTParserTest(IsolatedAsyncioTestCase):
+    """Behavioural coverage for :class:`PPTParser`."""
+
+    async def test_simple_deck_text_only(self) -> None:
+        """A simple text-only deck round-trips through wrapping tags."""
+        pptx_bytes = _make_pptx_simple(["Alpha", "Beta"])
+        parser = PPTParser(include_image=False)
+        sections = await parser.parse(pptx_bytes, "demo.pptx")
+
+        self.assertEqual(
+            [s.model_dump() for s in sections],
+            [
+                {
+                    "content": {
+                        "type": "text",
+                        "text": "<slide index=1>\nAlpha\n</slide>",
+                        "id": AnyString(),
+                    },
+                    "source": "demo.pptx",
+                    "metadata": {"slide": 1},
+                },
+                {
+                    "content": {
+                        "type": "text",
+                        "text": "<slide index=2>\nBeta\n</slide>",
+                        "id": AnyString(),
+                    },
+                    "source": "demo.pptx",
+                    "metadata": {"slide": 2},
+                },
+            ],
+        )
+
+    async def test_without_slide_tags(self) -> None:
+        """Disabling prefix/suffix removes the slide tags entirely."""
+        pptx_bytes = _make_pptx_simple(["Alpha"])
+        parser = PPTParser(
+            include_image=False,
+            slide_prefix=None,
+            slide_suffix=None,
+        )
+        sections = await parser.parse(pptx_bytes, "demo.pptx")
+        self.assertEqual(
+            [s.model_dump() for s in sections],
+            [
+                {
+                    "content": {
+                        "type": "text",
+                        "text": "Alpha",
+                        "id": AnyString(),
+                    },
+                    "source": "demo.pptx",
+                    "metadata": {"slide": 1},
+                },
+            ],
+        )
+
+    async def test_table_merges_with_surrounding_text_by_default(
+        self,
+    ) -> None:
+        """``separate_table=False`` merges the table into the running
+        text section."""
+        pptx_bytes = _make_pptx_rich()
+        parser = PPTParser(include_image=False, separate_table=False)
+        sections = await parser.parse(pptx_bytes, "rich.pptx")
+
+        self.assertEqual(
+            [s.model_dump() for s in sections],
+            [
+                {
+                    "content": {
+                        "type": "text",
+                        "text": "<slide index=1>\nHello\n</slide>",
+                        "id": AnyString(),
+                    },
+                    "source": "rich.pptx",
+                    "metadata": {"slide": 1},
+                },
+                {
+                    "content": {
+                        "type": "text",
+                        "text": (
+                            "<slide index=2>\n"
+                            "Header\n"
+                            "| A | B |\n"
+                            "| --- | --- |\n"
+                            "| 1 | 2 |\n\n"
+                            "Footer\n"
+                            "</slide>"
+                        ),
+                        "id": AnyString(),
+                    },
+                    "source": "rich.pptx",
+                    "metadata": {"slide": 2},
+                },
+                {
+                    "content": {
+                        "type": "text",
+                        "text": "<slide index=3>\n</slide>",
+                        "id": AnyString(),
+                    },
+                    "source": "rich.pptx",
+                    "metadata": {"slide": 3},
+                },
+            ],
+        )
+
+    async def test_table_separated_when_separate_table_true(self) -> None:
+        """``separate_table=True`` flushes the running text around the
+        table."""
+        pptx_bytes = _make_pptx_rich()
+        parser = PPTParser(include_image=False, separate_table=True)
+        sections = await parser.parse(pptx_bytes, "rich.pptx")
+
+        self.assertEqual(
+            [s.model_dump() for s in sections],
+            [
+                {
+                    "content": {
+                        "type": "text",
+                        "text": "<slide index=1>\nHello\n</slide>",
+                        "id": AnyString(),
+                    },
+                    "source": "rich.pptx",
+                    "metadata": {"slide": 1},
+                },
+                {
+                    "content": {
+                        "type": "text",
+                        "text": "<slide index=2>\nHeader",
+                        "id": AnyString(),
+                    },
+                    "source": "rich.pptx",
+                    "metadata": {"slide": 2},
+                },
+                {
+                    "content": {
+                        "type": "text",
+                        "text": (
+                            "| A | B |\n" "| --- | --- |\n" "| 1 | 2 |\n"
+                        ),
+                        "id": AnyString(),
+                    },
+                    "source": "rich.pptx",
+                    "metadata": {"slide": 2},
+                },
+                {
+                    "content": {
+                        "type": "text",
+                        "text": "Footer\n</slide>",
+                        "id": AnyString(),
+                    },
+                    "source": "rich.pptx",
+                    "metadata": {"slide": 2},
+                },
+                {
+                    "content": {
+                        "type": "text",
+                        "text": "<slide index=3>\n</slide>",
+                        "id": AnyString(),
+                    },
+                    "source": "rich.pptx",
+                    "metadata": {"slide": 3},
+                },
+            ],
+        )
+
+    async def test_image_emits_data_block(self) -> None:
+        """An embedded picture becomes its own DataBlock section."""
+        pptx_bytes = _make_pptx_rich()
+        parser = PPTParser(include_image=True, separate_table=True)
+        sections = await parser.parse(pptx_bytes, "rich.pptx")
+
+        self.assertEqual(
+            [s.model_dump() for s in sections],
+            [
+                {
+                    "content": {
+                        "type": "text",
+                        "text": "<slide index=1>\nHello\n</slide>",
+                        "id": AnyString(),
+                    },
+                    "source": "rich.pptx",
+                    "metadata": {"slide": 1},
+                },
+                {
+                    "content": {
+                        "type": "text",
+                        "text": "<slide index=2>\nHeader",
+                        "id": AnyString(),
+                    },
+                    "source": "rich.pptx",
+                    "metadata": {"slide": 2},
+                },
+                {
+                    "content": {
+                        "type": "text",
+                        "text": (
+                            "| A | B |\n" "| --- | --- |\n" "| 1 | 2 |\n"
+                        ),
+                        "id": AnyString(),
+                    },
+                    "source": "rich.pptx",
+                    "metadata": {"slide": 2},
+                },
+                {
+                    "content": {
+                        "type": "text",
+                        "text": "Footer\n</slide>",
+                        "id": AnyString(),
+                    },
+                    "source": "rich.pptx",
+                    "metadata": {"slide": 2},
+                },
+                {
+                    "content": {
+                        "type": "text",
+                        "text": "<slide index=3>",
+                        "id": AnyString(),
+                    },
+                    "source": "rich.pptx",
+                    "metadata": {"slide": 3},
+                },
+                {
+                    "content": {
+                        "type": "data",
+                        "id": AnyString(),
+                        "source": {
+                            "type": "base64",
+                            "data": _PNG_PIXEL_B64,
+                            "media_type": "image/png",
+                        },
+                        "name": "rich.pptx",
+                    },
+                    "source": "rich.pptx",
+                    "metadata": {
+                        "slide": 3,
+                        "media_type": "image/png",
+                    },
+                },
+                {
+                    "content": {
+                        "type": "text",
+                        "text": "</slide>",
+                        "id": AnyString(),
+                    },
+                    "source": "rich.pptx",
+                    "metadata": {"slide": 3},
+                },
+            ],
+        )
+
+    async def test_table_json_format(self) -> None:
+        """``table_format="json"`` emits the JSON marker payload."""
+        pptx_bytes = _make_pptx_rich()
+        parser = PPTParser(
+            include_image=False,
+            separate_table=True,
+            table_format="json",
+        )
+        sections = await parser.parse(pptx_bytes, "rich.pptx")
+
+        self.assertEqual(
+            [s.model_dump() for s in sections],
+            [
+                {
+                    "content": {
+                        "type": "text",
+                        "text": "<slide index=1>\nHello\n</slide>",
+                        "id": AnyString(),
+                    },
+                    "source": "rich.pptx",
+                    "metadata": {"slide": 1},
+                },
+                {
+                    "content": {
+                        "type": "text",
+                        "text": "<slide index=2>\nHeader",
+                        "id": AnyString(),
+                    },
+                    "source": "rich.pptx",
+                    "metadata": {"slide": 2},
+                },
+                {
+                    "content": {
+                        "type": "text",
+                        "text": (
+                            "<system-info>A table loaded as a JSON "
+                            "array:</system-info>\n"
+                            '[["A", "B"], ["1", "2"]]'
+                        ),
+                        "id": AnyString(),
+                    },
+                    "source": "rich.pptx",
+                    "metadata": {"slide": 2},
+                },
+                {
+                    "content": {
+                        "type": "text",
+                        "text": "Footer\n</slide>",
+                        "id": AnyString(),
+                    },
+                    "source": "rich.pptx",
+                    "metadata": {"slide": 2},
+                },
+                {
+                    "content": {
+                        "type": "text",
+                        "text": "<slide index=3>\n</slide>",
+                        "id": AnyString(),
+                    },
+                    "source": "rich.pptx",
+                    "metadata": {"slide": 3},
+                },
+            ],
+        )
+
+    async def test_table_format_validation(self) -> None:
+        """Unknown ``table_format`` raises :class:`ValueError`."""
+        with self.assertRaises(ValueError):
+            PPTParser(table_format="csv")  # type: ignore[arg-type]
+
+    async def test_string_input_treated_as_path(self) -> None:
+        """``str`` is interpreted as a filesystem path to the PPTX."""
+        import tempfile
+
+        pptx_bytes = _make_pptx_simple(["Alpha"])
+        with tempfile.NamedTemporaryFile(
+            suffix=".pptx",
+            delete=False,
+        ) as f:
+            f.write(pptx_bytes)
+            path = f.name
+        try:
+            parser = PPTParser(include_image=False)
+            sections = await parser.parse(path, "demo.pptx")
+            self.assertEqual(len(sections), 1)
+        finally:
+            os.unlink(path)
+
+    async def test_missing_path_raises_file_not_found(self) -> None:
+        """A ``str`` pointing at a missing path raises FileNotFoundError."""
+        parser = PPTParser()
+        with self.assertRaises(FileNotFoundError):
+            await parser.parse("/no/such/file.pptx", "x.pptx")
+
+
+class ExcelParserTest(IsolatedAsyncioTestCase):
+    """Behavioural coverage for :class:`ExcelParser`."""
+
+    async def test_single_sheet_markdown(self) -> None:
+        """A single-sheet workbook produces one text Section with
+        Markdown table."""
+        xlsx_bytes = _make_xlsx_simple(
+            {"Data": [["Name", "Age"], ["Alice", "25"]]},
+        )
+        parser = ExcelParser(table_format="markdown")
+        sections = await parser.parse(xlsx_bytes, "demo.xlsx")
+
+        self.assertEqual(
+            [s.model_dump() for s in sections],
+            [
+                {
+                    "content": {
+                        "type": "text",
+                        "text": (
+                            "Sheet: Data\n"
+                            "| Name | Age |\n"
+                            "| --- | --- |\n"
+                            "| Alice | 25 |\n"
+                        ),
+                        "id": AnyString(),
+                    },
+                    "source": "demo.xlsx",
+                    "metadata": {},
+                },
+            ],
+        )
+
+    async def test_single_sheet_json(self) -> None:
+        """``table_format="json"`` emits JSON rows."""
+        xlsx_bytes = _make_xlsx_simple(
+            {"Sheet1": [["X", "Y"], ["1", "2"]]},
+        )
+        parser = ExcelParser(table_format="json")
+        sections = await parser.parse(xlsx_bytes, "demo.xlsx")
+
+        self.assertEqual(
+            [s.model_dump() for s in sections],
+            [
+                {
+                    "content": {
+                        "type": "text",
+                        "text": (
+                            "Sheet: Sheet1\n"
+                            "<system-info>A table loaded as a JSON "
+                            "array:</system-info>\n"
+                            '["X", "Y"]\n'
+                            '["1", "2"]'
+                        ),
+                        "id": AnyString(),
+                    },
+                    "source": "demo.xlsx",
+                    "metadata": {},
+                },
+            ],
+        )
+
+    async def test_multi_sheet_merged_by_default(self) -> None:
+        """``separate_sheet=False`` (default) merges sheets into one
+        Section."""
+        xlsx_bytes = _make_xlsx_simple(
+            {
+                "Sales": [["Q", "Rev"], ["Q1", "100"]],
+                "Costs": [["Q", "Cost"], ["Q1", "50"]],
+            },
+        )
+        parser = ExcelParser()
+        sections = await parser.parse(xlsx_bytes, "multi.xlsx")
+
+        self.assertEqual(
+            [s.model_dump() for s in sections],
+            [
+                {
+                    "content": {
+                        "type": "text",
+                        "text": (
+                            "Sheet: Sales\n"
+                            "| Q | Rev |\n"
+                            "| --- | --- |\n"
+                            "| Q1 | 100 |\n\n"
+                            "Sheet: Costs\n"
+                            "| Q | Cost |\n"
+                            "| --- | --- |\n"
+                            "| Q1 | 50 |\n"
+                        ),
+                        "id": AnyString(),
+                    },
+                    "source": "multi.xlsx",
+                    "metadata": {},
+                },
+            ],
+        )
+
+    async def test_multi_sheet_separated(self) -> None:
+        """``separate_sheet=True`` keeps each sheet as its own Section."""
+        xlsx_bytes = _make_xlsx_simple(
+            {
+                "Sales": [["Q", "Rev"], ["Q1", "100"]],
+                "Costs": [["Q", "Cost"], ["Q1", "50"]],
+            },
+        )
+        parser = ExcelParser(separate_sheet=True)
+        sections = await parser.parse(xlsx_bytes, "multi.xlsx")
+
+        self.assertEqual(
+            [s.model_dump() for s in sections],
+            [
+                {
+                    "content": {
+                        "type": "text",
+                        "text": (
+                            "Sheet: Sales\n"
+                            "| Q | Rev |\n"
+                            "| --- | --- |\n"
+                            "| Q1 | 100 |\n"
+                        ),
+                        "id": AnyString(),
+                    },
+                    "source": "multi.xlsx",
+                    "metadata": {"sheet": "Sales"},
+                },
+                {
+                    "content": {
+                        "type": "text",
+                        "text": (
+                            "Sheet: Costs\n"
+                            "| Q | Cost |\n"
+                            "| --- | --- |\n"
+                            "| Q1 | 50 |\n"
+                        ),
+                        "id": AnyString(),
+                    },
+                    "source": "multi.xlsx",
+                    "metadata": {"sheet": "Costs"},
+                },
+            ],
+        )
+
+    async def test_sheet_name_in_text(self) -> None:
+        """``include_sheet_names=True`` prepends the sheet name."""
+        xlsx_bytes = _make_xlsx_simple(
+            {"MySheet": [["A"], ["1"]]},
+        )
+        parser = ExcelParser(include_sheet_names=True)
+        sections = await parser.parse(xlsx_bytes, "demo.xlsx")
+
+        self.assertEqual(
+            [s.model_dump() for s in sections],
+            [
+                {
+                    "content": {
+                        "type": "text",
+                        "text": (
+                            "Sheet: MySheet\n" "| A |\n" "| --- |\n" "| 1 |\n"
+                        ),
+                        "id": AnyString(),
+                    },
+                    "source": "demo.xlsx",
+                    "metadata": {},
+                },
+            ],
+        )
+
+    async def test_sheet_name_excluded(self) -> None:
+        """``include_sheet_names=False`` omits the sheet header."""
+        xlsx_bytes = _make_xlsx_simple(
+            {"MySheet": [["A"], ["1"]]},
+        )
+        parser = ExcelParser(include_sheet_names=False)
+        sections = await parser.parse(xlsx_bytes, "demo.xlsx")
+
+        self.assertEqual(
+            [s.model_dump() for s in sections],
+            [
+                {
+                    "content": {
+                        "type": "text",
+                        "text": ("| A |\n" "| --- |\n" "| 1 |\n"),
+                        "id": AnyString(),
+                    },
+                    "source": "demo.xlsx",
+                    "metadata": {},
+                },
+            ],
+        )
+
+    async def test_cell_coordinates(self) -> None:
+        """``include_cell_coordinates=True`` adds coordinate prefixes."""
+        xlsx_bytes = _make_xlsx_simple(
+            {"Data": [["Val"], ["X"]]},
+        )
+        parser = ExcelParser(include_cell_coordinates=True)
+        sections = await parser.parse(xlsx_bytes, "demo.xlsx")
+
+        self.assertEqual(
+            [s.model_dump() for s in sections],
+            [
+                {
+                    "content": {
+                        "type": "text",
+                        "text": (
+                            "Sheet: Data\n"
+                            "| [A1] Val |\n"
+                            "| --- |\n"
+                            "| [A2] X |\n"
+                        ),
+                        "id": AnyString(),
+                    },
+                    "source": "demo.xlsx",
+                    "metadata": {},
+                },
+            ],
+        )
+
+    async def test_string_input_treated_as_path(self) -> None:
+        """``str`` is interpreted as a filesystem path."""
+        import tempfile
+
+        xlsx_bytes = _make_xlsx_simple(
+            {"S": [["Col"], ["Val"]]},
+        )
+        with tempfile.NamedTemporaryFile(
+            suffix=".xlsx",
+            delete=False,
+        ) as f:
+            f.write(xlsx_bytes)
+            path = f.name
+        try:
+            parser = ExcelParser()
+            sections = await parser.parse(path, "demo.xlsx")
+            self.assertGreaterEqual(len(sections), 1)
+        finally:
+            os.unlink(path)
+
+    async def test_supported_extensions(self) -> None:
+        """Both ``.xls`` and ``.xlsx`` are listed."""
+        exts = ExcelParser.supported_extensions()
+        self.assertIn(".xlsx", exts)
+        self.assertIn(".xls", exts)
+
+    async def test_table_format_validation(self) -> None:
+        """Unknown ``table_format`` raises :class:`ValueError`."""
+        with self.assertRaises(ValueError):
+            ExcelParser(table_format="csv")  # type: ignore[arg-type]
+
+
+class WordParserTest(IsolatedAsyncioTestCase):
+    """Behavioural coverage for :class:`WordParser`."""
+
+    async def test_simple_paragraphs(self) -> None:
+        """Plain paragraphs are merged into a single text Section."""
+        docx_bytes = _make_docx_simple(["Hello", "World"])
+        parser = WordParser(include_image=False)
+        sections = await parser.parse(docx_bytes, "demo.docx")
+
+        self.assertEqual(
+            [s.model_dump() for s in sections],
+            [
+                {
+                    "content": {
+                        "type": "text",
+                        "text": "Hello\nWorld",
+                        "id": AnyString(),
+                    },
+                    "source": "demo.docx",
+                    "metadata": {},
+                },
+            ],
+        )
+
+    async def test_table_merges_by_default(self) -> None:
+        """``separate_table=False`` merges the table into surrounding
+        text."""
+        docx_bytes = _make_docx_with_table()
+        parser = WordParser(include_image=False, separate_table=False)
+        sections = await parser.parse(docx_bytes, "demo.docx")
+
+        self.assertEqual(
+            [s.model_dump() for s in sections],
+            [
+                {
+                    "content": {
+                        "type": "text",
+                        "text": (
+                            "Before table\n"
+                            "| A | B |\n"
+                            "| --- | --- |\n"
+                            "| 1 | 2 |\n\n"
+                            "After table"
+                        ),
+                        "id": AnyString(),
+                    },
+                    "source": "demo.docx",
+                    "metadata": {},
+                },
+            ],
+        )
+
+    async def test_table_separated(self) -> None:
+        """``separate_table=True`` isolates the table from surrounding
+        paragraphs."""
+        docx_bytes = _make_docx_with_table()
+        parser = WordParser(include_image=False, separate_table=True)
+        sections = await parser.parse(docx_bytes, "demo.docx")
+
+        self.assertEqual(
+            [s.model_dump() for s in sections],
+            [
+                {
+                    "content": {
+                        "type": "text",
+                        "text": "Before table",
+                        "id": AnyString(),
+                    },
+                    "source": "demo.docx",
+                    "metadata": {},
+                },
+                {
+                    "content": {
+                        "type": "text",
+                        "text": (
+                            "| A | B |\n" "| --- | --- |\n" "| 1 | 2 |\n"
+                        ),
+                        "id": AnyString(),
+                    },
+                    "source": "demo.docx",
+                    "metadata": {},
+                },
+                {
+                    "content": {
+                        "type": "text",
+                        "text": "After table",
+                        "id": AnyString(),
+                    },
+                    "source": "demo.docx",
+                    "metadata": {},
+                },
+            ],
+        )
+
+    async def test_table_json_format(self) -> None:
+        """``table_format="json"`` emits JSON instead of Markdown."""
+        docx_bytes = _make_docx_with_table()
+        parser = WordParser(
+            include_image=False,
+            separate_table=True,
+            table_format="json",
+        )
+        sections = await parser.parse(docx_bytes, "demo.docx")
+
+        self.assertEqual(
+            [s.model_dump() for s in sections],
+            [
+                {
+                    "content": {
+                        "type": "text",
+                        "text": "Before table",
+                        "id": AnyString(),
+                    },
+                    "source": "demo.docx",
+                    "metadata": {},
+                },
+                {
+                    "content": {
+                        "type": "text",
+                        "text": (
+                            "<system-info>A table loaded as a JSON "
+                            "array:</system-info>\n"
+                            '[["A", "B"], ["1", "2"]]'
+                        ),
+                        "id": AnyString(),
+                    },
+                    "source": "demo.docx",
+                    "metadata": {},
+                },
+                {
+                    "content": {
+                        "type": "text",
+                        "text": "After table",
+                        "id": AnyString(),
+                    },
+                    "source": "demo.docx",
+                    "metadata": {},
+                },
+            ],
+        )
+
+    async def test_image_emits_data_block(self) -> None:
+        """Embedded images become DataBlock sections."""
+        docx_bytes = _make_docx_with_image()
+        parser = WordParser(include_image=True)
+        sections = await parser.parse(docx_bytes, "rich.docx")
+
+        data_sections = [s for s in sections if s.content.type == "data"]
+        self.assertGreaterEqual(len(data_sections), 1)
+        ds = data_sections[0]
+        self.assertEqual(ds.source, "rich.docx")
+        self.assertEqual(ds.content.name, "rich.docx")
+        self.assertIn("media_type", ds.metadata)
+
+    async def test_image_excluded_when_disabled(self) -> None:
+        """``include_image=False`` keeps only text sections."""
+        docx_bytes = _make_docx_with_image()
+        parser = WordParser(include_image=False)
+        sections = await parser.parse(docx_bytes, "rich.docx")
+
+        self.assertEqual(
+            [s.model_dump() for s in sections],
+            [
+                {
+                    "content": {
+                        "type": "text",
+                        "text": "Text before image\nText after image",
+                        "id": AnyString(),
+                    },
+                    "source": "rich.docx",
+                    "metadata": {},
+                },
+            ],
+        )
+
+    async def test_string_input_treated_as_path(self) -> None:
+        """``str`` is interpreted as a filesystem path to the DOCX."""
+        import tempfile
+
+        docx_bytes = _make_docx_simple(["Alpha"])
+        with tempfile.NamedTemporaryFile(
+            suffix=".docx",
+            delete=False,
+        ) as f:
+            f.write(docx_bytes)
+            path = f.name
+        try:
+            parser = WordParser(include_image=False)
+            sections = await parser.parse(path, "demo.docx")
+            self.assertEqual(len(sections), 1)
+        finally:
+            os.unlink(path)
+
+    async def test_supported_extensions(self) -> None:
+        """``.docx`` is the only extension."""
+        self.assertEqual(WordParser.supported_extensions(), [".docx"])
+
+    async def test_table_format_validation(self) -> None:
+        """Unknown ``table_format`` raises :class:`ValueError`."""
+        with self.assertRaises(ValueError):
+            WordParser(table_format="csv")  # type: ignore[arg-type]
diff --git a/tests/rag_vdb_milvus_lite_test.py b/tests/rag_vdb_milvus_lite_test.py
new file mode 100644
index 0000000..a565d30
--- /dev/null
+++ b/tests/rag_vdb_milvus_lite_test.py
@@ -0,0 +1,358 @@
+# -*- coding: utf-8 -*-
+"""Unit tests for the MilvusLiteStore class."""
+import tempfile
+import unittest
+from contextlib import AsyncExitStack
+from importlib.util import find_spec
+from pathlib import Path
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from utils import AnyString
+
+from agentscope.message import TextBlock
+from agentscope.rag import (
+    Chunk,
+    MilvusLiteStore,
+    VectorRecord,
+    VectorSearchResult,
+)
+
+
+_MILVUS_LITE_AVAILABLE = (
+    find_spec("pymilvus") is not None and find_spec("milvus_lite") is not None
+)
+
+
+def _dump_results(results: list[VectorSearchResult]) -> list[dict]:
+    """Convert search results into plain dicts for comparison."""
+    return [result.model_dump() for result in results]
+
+
+def _make_record(
+    text: str,
+    vector: list[float],
+    document_id: str,
+    chunk_index: int = 0,
+    total_chunks: int = 1,
+) -> VectorRecord:
+    """Build a VectorRecord for testing."""
+    return VectorRecord(
+        vector=vector,
+        document_id=document_id,
+        chunk=Chunk(
+            content=TextBlock(text=text),
+            source=f"{document_id}.txt",
+            chunk_index=chunk_index,
+            total_chunks=total_chunks,
+        ),
+    )
+
+
+@unittest.skipUnless(
+    _MILVUS_LITE_AVAILABLE,
+    "pymilvus and milvus_lite are required for MilvusLiteStore tests",
+)
+class MilvusLiteStoreTest(IsolatedAsyncioTestCase):
+    """The test cases for the MilvusLiteStore class."""
+
+    async def asyncSetUp(self) -> None:
+        """Create a temporary Milvus Lite store before each test."""
+        self._exit_stack = AsyncExitStack()
+        tmpdir = self._exit_stack.enter_context(tempfile.TemporaryDirectory())
+        self._tmpdir = Path(tmpdir)
+        db_path = self._tmpdir / "test.db"
+        self.store = await self._exit_stack.enter_async_context(
+            MilvusLiteStore(uri=str(db_path)),
+        )
+
+    async def asyncTearDown(self) -> None:
+        """Close the store and remove the temporary database."""
+        await self._exit_stack.aclose()
+
+    async def test_collection_lifecycle(self) -> None:
+        """Collections can be created, checked, and deleted."""
+        self.assertEqual(await self.store.has_collection("kb_1"), False)
+
+        await self.store.create_collection("kb_1", dimensions=3)
+        self.assertEqual(await self.store.has_collection("kb_1"), True)
+
+        # Creating an existing collection is a no-op
+        await self.store.create_collection("kb_1", dimensions=3)
+        self.assertEqual(await self.store.has_collection("kb_1"), True)
+
+        await self.store.delete_collection("kb_1")
+        self.assertEqual(await self.store.has_collection("kb_1"), False)
+
+    async def test_insert_and_search(self) -> None:
+        """Inserted records are searchable, ordered by similarity."""
+        await self.store.create_collection("kb_1", dimensions=3)
+        await self.store.insert(
+            "kb_1",
+            [
+                _make_record(
+                    "Hello world!",
+                    [1.0, 0.0, 0.0],
+                    document_id="doc-1",
+                    chunk_index=0,
+                    total_chunks=2,
+                ),
+                _make_record(
+                    "Goodbye world!",
+                    [0.0, 1.0, 0.0],
+                    document_id="doc-1",
+                    chunk_index=1,
+                    total_chunks=2,
+                ),
+            ],
+        )
+
+        results = await self.store.search(
+            "kb_1",
+            query_vector=[1.0, 0.0, 0.0],
+            top_k=2,
+        )
+
+        self.assertAlmostEqual(results[0].score, 1.0)
+        self.assertAlmostEqual(results[1].score, 0.0)
+        dumped = _dump_results(results)
+        for result in dumped:
+            result["score"] = 0.0
+        self.assertEqual(
+            dumped,
+            [
+                {
+                    "score": 0.0,
+                    "document_id": "doc-1",
+                    "chunk": {
+                        "content": {
+                            "type": "text",
+                            "text": "Hello world!",
+                            "id": AnyString(),
+                        },
+                        "source": "doc-1.txt",
+                        "chunk_index": 0,
+                        "total_chunks": 2,
+                        "metadata": {},
+                    },
+                },
+                {
+                    "score": 0.0,
+                    "document_id": "doc-1",
+                    "chunk": {
+                        "content": {
+                            "type": "text",
+                            "text": "Goodbye world!",
+                            "id": AnyString(),
+                        },
+                        "source": "doc-1.txt",
+                        "chunk_index": 1,
+                        "total_chunks": 2,
+                        "metadata": {},
+                    },
+                },
+            ],
+        )
+
+    async def test_search_top_k(self) -> None:
+        """top_k limits the number of returned results."""
+        await self.store.create_collection("kb_1", dimensions=3)
+        await self.store.insert(
+            "kb_1",
+            [
+                _make_record("A", [1.0, 0.0, 0.0], document_id="doc-1"),
+                _make_record("B", [0.9, 0.1, 0.0], document_id="doc-2"),
+                _make_record("C", [0.0, 0.0, 1.0], document_id="doc-3"),
+            ],
+        )
+
+        results = await self.store.search(
+            "kb_1",
+            query_vector=[1.0, 0.0, 0.0],
+            top_k=1,
+        )
+
+        self.assertEqual(len(results), 1)
+        self.assertEqual(results[0].document_id, "doc-1")
+
+    async def test_delete_by_document_id(self) -> None:
+        """delete removes all records of one document only."""
+        await self.store.create_collection("kb_1", dimensions=3)
+        await self.store.insert(
+            "kb_1",
+            [
+                _make_record(
+                    "doc1-chunk0",
+                    [1.0, 0.0, 0.0],
+                    document_id="doc-1",
+                    chunk_index=0,
+                    total_chunks=2,
+                ),
+                _make_record(
+                    "doc1-chunk1",
+                    [0.9, 0.1, 0.0],
+                    document_id="doc-1",
+                    chunk_index=1,
+                    total_chunks=2,
+                ),
+                _make_record(
+                    "doc2-chunk0",
+                    [0.0, 1.0, 0.0],
+                    document_id="doc-2",
+                ),
+            ],
+        )
+
+        await self.store.delete("kb_1", document_id="doc-1")
+
+        results = await self.store.search(
+            "kb_1",
+            query_vector=[1.0, 0.0, 0.0],
+            top_k=5,
+        )
+
+        self.assertEqual([r.document_id for r in results], ["doc-2"])
+
+    async def test_insert_empty_records(self) -> None:
+        """Inserting an empty record list is a no-op."""
+        await self.store.create_collection("kb_1", dimensions=3)
+        await self.store.insert("kb_1", [])
+
+        results = await self.store.search(
+            "kb_1",
+            query_vector=[1.0, 0.0, 0.0],
+        )
+
+        self.assertEqual(_dump_results(results), [])
+
+    async def test_list_documents_aggregates_by_document_id(self) -> None:
+        """list_documents groups chunks by document_id."""
+        await self.store.create_collection("kb_1", dimensions=3)
+
+        def _record_with_metadata(
+            text: str,
+            document_id: str,
+            metadata: dict,
+            chunk_index: int = 0,
+            total_chunks: int = 1,
+        ) -> VectorRecord:
+            return VectorRecord(
+                vector=[1.0, 0.0, 0.0],
+                document_id=document_id,
+                chunk=Chunk(
+                    content=TextBlock(text=text),
+                    source=metadata.get("filename", f"{document_id}.txt"),
+                    chunk_index=chunk_index,
+                    total_chunks=total_chunks,
+                    metadata=metadata,
+                ),
+            )
+
+        await self.store.insert(
+            "kb_1",
+            [
+                _record_with_metadata(
+                    "A",
+                    "doc-1",
+                    {"filename": "alpha.txt", "media_type": "text/plain"},
+                    0,
+                    2,
+                ),
+                _record_with_metadata(
+                    "B",
+                    "doc-1",
+                    {"filename": "alpha.txt", "media_type": "text/plain"},
+                    1,
+                    2,
+                ),
+                _record_with_metadata(
+                    "C",
+                    "doc-2",
+                    {"filename": "beta.md", "media_type": "text/markdown"},
+                    0,
+                    1,
+                ),
+            ],
+        )
+
+        summaries = await self.store.list_documents("kb_1")
+        summaries_by_id = {s.document_id: s for s in summaries}
+
+        self.assertEqual(set(summaries_by_id), {"doc-1", "doc-2"})
+        self.assertEqual(summaries_by_id["doc-1"].chunk_count, 2)
+        self.assertEqual(summaries_by_id["doc-1"].source, "alpha.txt")
+        self.assertEqual(
+            summaries_by_id["doc-1"].metadata,
+            {"filename": "alpha.txt", "media_type": "text/plain"},
+        )
+        self.assertEqual(summaries_by_id["doc-2"].chunk_count, 1)
+        self.assertEqual(summaries_by_id["doc-2"].source, "beta.md")
+
+    async def test_search_metadata_filter(self) -> None:
+        """search applies the metadata_filter as a payload predicate."""
+        await self.store.create_collection("kb_1", dimensions=3)
+
+        def _record(
+            text: str,
+            document_id: str,
+            kb_scope: str,
+        ) -> VectorRecord:
+            return VectorRecord(
+                vector=[1.0, 0.0, 0.0],
+                document_id=document_id,
+                chunk=Chunk(
+                    content=TextBlock(text=text),
+                    source=f"{document_id}.txt",
+                    chunk_index=0,
+                    total_chunks=1,
+                    metadata={"kb_scope": kb_scope},
+                ),
+            )
+
+        await self.store.insert(
+            "kb_1",
+            [
+                _record("A", "doc-1", "kb-a"),
+                _record("B", "doc-2", "kb-b"),
+            ],
+        )
+
+        results = await self.store.search(
+            "kb_1",
+            query_vector=[1.0, 0.0, 0.0],
+            top_k=5,
+            metadata_filter={"kb_scope": "kb-a"},
+        )
+        self.assertEqual([r.document_id for r in results], ["doc-1"])
+
+        summaries = await self.store.list_documents(
+            "kb_1",
+            metadata_filter={"kb_scope": "kb-b"},
+        )
+        self.assertEqual([s.document_id for s in summaries], ["doc-2"])
+
+    async def test_persists_records_after_reopen(self) -> None:
+        """Records remain available after closing and reopening the DB."""
+        db_path = self._tmpdir / "persistent.db"
+
+        async with MilvusLiteStore(uri=str(db_path)) as first_store:
+            await first_store.create_collection("kb_persistent", dimensions=3)
+            await first_store.insert(
+                "kb_persistent",
+                [
+                    _make_record(
+                        "Persisted",
+                        [1.0, 0.0, 0.0],
+                        document_id="doc-1",
+                    ),
+                ],
+            )
+
+        async with MilvusLiteStore(uri=str(db_path)) as second_store:
+            await second_store.create_collection("kb_persistent", dimensions=3)
+            results = await second_store.search(
+                "kb_persistent",
+                query_vector=[1.0, 0.0, 0.0],
+                top_k=1,
+            )
+
+        self.assertEqual([r.document_id for r in results], ["doc-1"])
diff --git a/tests/rag_vdb_mongodb_test.py b/tests/rag_vdb_mongodb_test.py
new file mode 100644
index 0000000..b4c3ed5
--- /dev/null
+++ b/tests/rag_vdb_mongodb_test.py
@@ -0,0 +1,647 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access,missing-function-docstring
+"""Unit tests for the MongoDBStore class (mocked pymongo backend)."""
+from __future__ import annotations
+
+import math
+from contextlib import AsyncExitStack
+from typing import Any
+from unittest.async_case import IsolatedAsyncioTestCase
+from unittest.mock import patch
+
+from utils import AnyString
+
+from agentscope.message import TextBlock
+from agentscope.rag import (
+    Chunk,
+    MongoDBStore,
+    VectorRecord,
+    VectorSearchResult,
+)
+
+
+def _dump_results(results: list[VectorSearchResult]) -> list[dict]:
+    """Convert search results into plain dicts for whole-structure
+    comparison.
+
+    Args:
+        results (`list[VectorSearchResult]`):
+            The search results to convert.
+
+    Returns:
+        `list[dict]`:
+            The results as plain dicts.
+    """
+    return [result.model_dump() for result in results]
+
+
+def _make_record(
+    text: str,
+    vector: list[float],
+    document_id: str,
+    chunk_index: int = 0,
+    total_chunks: int = 1,
+) -> VectorRecord:
+    """Build a VectorRecord for testing.
+
+    Args:
+        text (`str`):
+            The chunk text content.
+        vector (`list[float]`):
+            The embedding vector.
+        document_id (`str`):
+            The ID of the source document the record belongs to.
+        chunk_index (`int`, defaults to ``0``):
+            The chunk index within the document.
+        total_chunks (`int`, defaults to ``1``):
+            The total number of chunks in the document.
+
+    Returns:
+        `VectorRecord`:
+            The constructed record.
+    """
+    return VectorRecord(
+        vector=vector,
+        document_id=document_id,
+        chunk=Chunk(
+            content=TextBlock(text=text),
+            source=f"{document_id}.txt",
+            chunk_index=chunk_index,
+            total_chunks=total_chunks,
+        ),
+    )
+
+
+def _cosine_similarity(a: list[float], b: list[float]) -> float:
+    """Cosine similarity aligned with Qdrant cosine scoring in tests."""
+    dot = sum(x * y for x, y in zip(a, b, strict=True))
+    norm_a = math.sqrt(sum(x * x for x in a))
+    norm_b = math.sqrt(sum(x * x for x in b))
+    if norm_a == 0.0 or norm_b == 0.0:
+        return 0.0
+    return dot / (norm_a * norm_b)
+
+
+class _FakeAsyncIterator:
+    """Minimal async iterator for mocked MongoDB cursors."""
+
+    def __init__(self, items: list[Any]) -> None:
+        self._items = items
+        self._index = 0
+
+    def __aiter__(self) -> "_FakeAsyncIterator":
+        return self
+
+    async def __anext__(self) -> Any:
+        if self._index >= len(self._items):
+            raise StopAsyncIteration
+        item = self._items[self._index]
+        self._index += 1
+        return item
+
+
+class _FakeMongoCollection:
+    """In-memory collection that implements the async API MongoDBStore uses."""
+
+    def __init__(self, database: "_FakeMongoDatabase", name: str) -> None:
+        self._database = database
+        self._name = name
+        self._docs: dict[str, dict[str, Any]] = {}
+        self._index_queryable = False
+
+    async def bulk_write(
+        self,
+        operations: list[Any],
+        ordered: bool = False,
+    ) -> None:
+        del ordered
+        for operation in operations:
+            self._docs[operation._doc["_id"]] = dict(operation._doc)
+
+    async def delete_many(self, filter_doc: dict[str, Any]) -> None:
+        document_id = filter_doc["document_id"]
+        to_remove = [
+            doc_id
+            for doc_id, doc in self._docs.items()
+            if doc.get("document_id") == document_id
+        ]
+        for doc_id in to_remove:
+            del self._docs[doc_id]
+
+    async def create_search_index(self, model: Any) -> None:
+        del model
+        self._index_queryable = True
+
+    async def list_search_indexes(self, name: str) -> _FakeAsyncIterator:
+        del name
+        return _FakeAsyncIterator([{"queryable": self._index_queryable}])
+
+    async def aggregate(
+        self,
+        pipeline: list[dict[str, Any]],
+    ) -> _FakeAsyncIterator:
+        return _FakeAsyncIterator(self._run_aggregate(pipeline))
+
+    async def drop(self) -> None:
+        self._database._collections.pop(self._name, None)
+
+    def _run_aggregate(
+        self,
+        pipeline: list[dict[str, Any]],
+    ) -> list[dict[str, Any]]:
+        if pipeline and "$vectorSearch" in pipeline[0]:
+            return self._vector_search(pipeline[0]["$vectorSearch"])
+        return self._list_documents(pipeline)
+
+    def _vector_search(self, stage: dict[str, Any]) -> list[dict[str, Any]]:
+        query_vector = stage["queryVector"]
+        top_k = stage["limit"]
+        metadata_filter = stage.get("filter")
+
+        scored: list[dict[str, Any]] = []
+        for doc in self._docs.values():
+            if not self._matches_metadata_filter(doc, metadata_filter):
+                continue
+            scored.append(
+                {
+                    "document_id": doc["document_id"],
+                    "chunk": doc["chunk"],
+                    "score": _cosine_similarity(query_vector, doc["vector"]),
+                },
+            )
+
+        scored.sort(key=lambda item: item["score"], reverse=True)
+        return scored[:top_k]
+
+    def _list_documents(
+        self,
+        pipeline: list[dict[str, Any]],
+    ) -> list[dict[str, Any]]:
+        docs = list(self._docs.values())
+        for stage in pipeline:
+            if "$match" in stage:
+                docs = [
+                    doc
+                    for doc in docs
+                    if self._matches_match_stage(doc, stage["$match"])
+                ]
+            elif "$group" in stage:
+                return self._group_documents(docs, stage["$group"])
+        return []
+
+    @staticmethod
+    def _matches_match_stage(
+        doc: dict[str, Any],
+        match: dict[str, Any],
+    ) -> bool:
+        for key, expected in match.items():
+            value = doc
+            for part in key.split("."):
+                value = value[part]
+            if value != expected:
+                return False
+        return True
+
+    @staticmethod
+    def _matches_metadata_filter(
+        doc: dict[str, Any],
+        metadata_filter: dict[str, Any] | None,
+    ) -> bool:
+        if not metadata_filter:
+            return True
+
+        for clause in metadata_filter.get("$and", []):
+            for key, condition in clause.items():
+                expected = condition["$eq"]
+                value = doc
+                for part in key.split("."):
+                    value = value[part]
+                if value != expected:
+                    return False
+        return True
+
+    @staticmethod
+    def _group_documents(
+        docs: list[dict[str, Any]],
+        group_stage: dict[str, Any],
+    ) -> list[dict[str, Any]]:
+        del group_stage
+        grouped: dict[str, dict[str, Any]] = {}
+        for doc in docs:
+            document_id = doc["document_id"]
+            if document_id not in grouped:
+                grouped[document_id] = {
+                    "_id": document_id,
+                    "source": doc["chunk"]["source"],
+                    "metadata": doc["chunk"].get("metadata") or {},
+                    "chunk_count": 0,
+                }
+            grouped[document_id]["chunk_count"] += 1
+        return list(grouped.values())
+
+
+class _FakeMongoDatabase:
+    """In-memory database handle."""
+
+    def __init__(self) -> None:
+        self._collections: dict[str, _FakeMongoCollection] = {}
+
+    async def list_collection_names(self) -> list[str]:
+        return list(self._collections.keys())
+
+    async def create_collection(self, name: str) -> _FakeMongoCollection:
+        collection = _FakeMongoCollection(self, name)
+        self._collections[name] = collection
+        return collection
+
+    def __getitem__(self, name: str) -> _FakeMongoCollection:
+        if name not in self._collections:
+            self._collections[name] = _FakeMongoCollection(self, name)
+        return self._collections[name]
+
+
+class _FakeMongoClient:
+    """In-memory async MongoDB client."""
+
+    def __init__(self, database_name: str) -> None:
+        self._database_name = database_name
+        self._databases: dict[str, _FakeMongoDatabase] = {}
+
+    def __getitem__(self, database_name: str) -> _FakeMongoDatabase:
+        if database_name not in self._databases:
+            self._databases[database_name] = _FakeMongoDatabase()
+        return self._databases[database_name]
+
+    async def close(self) -> None:
+        self._databases.clear()
+
+
+class MongoDBStoreTest(IsolatedAsyncioTestCase):
+    """The test cases for the MongoDBStore class."""
+
+    async def asyncSetUp(self) -> None:
+        """Create a MongoDB store with a mocked pymongo client."""
+        self._fake_client = _FakeMongoClient("test-db")
+        self._client_patcher = patch.object(
+            MongoDBStore,
+            "get_client",
+            return_value=self._fake_client,
+        )
+        self._client_patcher.start()
+
+        self._exit_stack = AsyncExitStack()
+        self.store = MongoDBStore(uri="mongodb://mock", database="test-db")
+        await self._exit_stack.enter_async_context(self.store)
+
+    async def asyncTearDown(self) -> None:
+        """Close the store and stop patches after each test."""
+        await self._exit_stack.aclose()
+        self._client_patcher.stop()
+
+    async def test_collection_lifecycle(self) -> None:
+        """Collections can be created, checked, and deleted."""
+        self.assertEqual(await self.store.has_collection("kb-1"), False)
+
+        await self.store.create_collection("kb-1", dimensions=3)
+        self.assertEqual(await self.store.has_collection("kb-1"), True)
+
+        # Creating an existing collection is a no-op
+        await self.store.create_collection("kb-1", dimensions=3)
+        self.assertEqual(await self.store.has_collection("kb-1"), True)
+
+        await self.store.delete_collection("kb-1")
+        self.assertEqual(await self.store.has_collection("kb-1"), False)
+
+    async def test_insert_and_search(self) -> None:
+        """Inserted records are searchable, ordered by similarity."""
+        await self.store.create_collection("kb-1", dimensions=3)
+        await self.store.insert(
+            "kb-1",
+            [
+                _make_record(
+                    "Hello world!",
+                    [1.0, 0.0, 0.0],
+                    document_id="doc-1",
+                    chunk_index=0,
+                    total_chunks=2,
+                ),
+                _make_record(
+                    "Goodbye world!",
+                    [0.0, 1.0, 0.0],
+                    document_id="doc-1",
+                    chunk_index=1,
+                    total_chunks=2,
+                ),
+            ],
+        )
+
+        results = await self.store.search(
+            "kb-1",
+            query_vector=[1.0, 0.0, 0.0],
+            top_k=2,
+        )
+
+        self.assertEqual(
+            _dump_results(results),
+            [
+                {
+                    "score": 1.0,
+                    "document_id": "doc-1",
+                    "chunk": {
+                        "content": {
+                            "type": "text",
+                            "text": "Hello world!",
+                            "id": AnyString(),
+                        },
+                        "source": "doc-1.txt",
+                        "chunk_index": 0,
+                        "total_chunks": 2,
+                        "metadata": {},
+                    },
+                },
+                {
+                    "score": 0.0,
+                    "document_id": "doc-1",
+                    "chunk": {
+                        "content": {
+                            "type": "text",
+                            "text": "Goodbye world!",
+                            "id": AnyString(),
+                        },
+                        "source": "doc-1.txt",
+                        "chunk_index": 1,
+                        "total_chunks": 2,
+                        "metadata": {},
+                    },
+                },
+            ],
+        )
+
+    async def test_search_top_k(self) -> None:
+        """top_k limits the number of returned results."""
+        await self.store.create_collection("kb-1", dimensions=3)
+        await self.store.insert(
+            "kb-1",
+            [
+                _make_record("A", [1.0, 0.0, 0.0], document_id="doc-1"),
+                _make_record("B", [0.9, 0.1, 0.0], document_id="doc-2"),
+                _make_record("C", [0.0, 0.0, 1.0], document_id="doc-3"),
+            ],
+        )
+
+        results = await self.store.search(
+            "kb-1",
+            query_vector=[1.0, 0.0, 0.0],
+            top_k=1,
+        )
+
+        self.assertEqual(
+            _dump_results(results),
+            [
+                {
+                    "score": 1.0,
+                    "document_id": "doc-1",
+                    "chunk": {
+                        "content": {
+                            "type": "text",
+                            "text": "A",
+                            "id": AnyString(),
+                        },
+                        "source": "doc-1.txt",
+                        "chunk_index": 0,
+                        "total_chunks": 1,
+                        "metadata": {},
+                    },
+                },
+            ],
+        )
+
+    async def test_delete_by_document_id(self) -> None:
+        """delete removes all records of one document only."""
+        await self.store.create_collection("kb-1", dimensions=3)
+        await self.store.insert(
+            "kb-1",
+            [
+                _make_record(
+                    "doc1-chunk0",
+                    [1.0, 0.0, 0.0],
+                    document_id="doc-1",
+                    chunk_index=0,
+                    total_chunks=2,
+                ),
+                _make_record(
+                    "doc1-chunk1",
+                    [0.9, 0.1, 0.0],
+                    document_id="doc-1",
+                    chunk_index=1,
+                    total_chunks=2,
+                ),
+                _make_record(
+                    "doc2-chunk0",
+                    [0.0, 1.0, 0.0],
+                    document_id="doc-2",
+                ),
+            ],
+        )
+
+        await self.store.delete("kb-1", document_id="doc-1")
+
+        results = await self.store.search(
+            "kb-1",
+            query_vector=[1.0, 0.0, 0.0],
+            top_k=5,
+        )
+
+        self.assertEqual(
+            _dump_results(results),
+            [
+                {
+                    "score": 0.0,
+                    "document_id": "doc-2",
+                    "chunk": {
+                        "content": {
+                            "type": "text",
+                            "text": "doc2-chunk0",
+                            "id": AnyString(),
+                        },
+                        "source": "doc-2.txt",
+                        "chunk_index": 0,
+                        "total_chunks": 1,
+                        "metadata": {},
+                    },
+                },
+            ],
+        )
+
+    async def test_insert_empty_records(self) -> None:
+        """Inserting an empty record list is a no-op."""
+        await self.store.create_collection("kb-1", dimensions=3)
+        await self.store.insert("kb-1", [])
+
+        results = await self.store.search(
+            "kb-1",
+            query_vector=[1.0, 0.0, 0.0],
+        )
+
+        self.assertEqual(_dump_results(results), [])
+
+    async def test_list_documents_aggregates_by_document_id(self) -> None:
+        """list_documents groups chunks by document_id."""
+        await self.store.create_collection("kb-1", dimensions=3)
+
+        def _record_with_metadata(
+            text: str,
+            document_id: str,
+            metadata: dict,
+            chunk_index: int = 0,
+            total_chunks: int = 1,
+        ) -> VectorRecord:
+            return VectorRecord(
+                vector=[1.0, 0.0, 0.0],
+                document_id=document_id,
+                chunk=Chunk(
+                    content=TextBlock(text=text),
+                    source=metadata.get("filename", f"{document_id}.txt"),
+                    chunk_index=chunk_index,
+                    total_chunks=total_chunks,
+                    metadata=metadata,
+                ),
+            )
+
+        await self.store.insert(
+            "kb-1",
+            [
+                _record_with_metadata(
+                    "A",
+                    "doc-1",
+                    {"filename": "alpha.txt", "media_type": "text/plain"},
+                    0,
+                    2,
+                ),
+                _record_with_metadata(
+                    "B",
+                    "doc-1",
+                    {"filename": "alpha.txt", "media_type": "text/plain"},
+                    1,
+                    2,
+                ),
+                _record_with_metadata(
+                    "C",
+                    "doc-2",
+                    {"filename": "beta.md", "media_type": "text/markdown"},
+                    0,
+                    1,
+                ),
+            ],
+        )
+
+        summaries = sorted(
+            await self.store.list_documents("kb-1"),
+            key=lambda summary: summary.document_id,
+        )
+        self.assertEqual(
+            [summary.model_dump() for summary in summaries],
+            [
+                {
+                    "document_id": "doc-1",
+                    "source": "alpha.txt",
+                    "chunk_count": 2,
+                    "metadata": {
+                        "filename": "alpha.txt",
+                        "media_type": "text/plain",
+                    },
+                },
+                {
+                    "document_id": "doc-2",
+                    "source": "beta.md",
+                    "chunk_count": 1,
+                    "metadata": {
+                        "filename": "beta.md",
+                        "media_type": "text/markdown",
+                    },
+                },
+            ],
+        )
+
+    async def test_search_metadata_filter(self) -> None:
+        """search applies the metadata_filter as a payload predicate."""
+        await self.store.create_collection("kb-1", dimensions=3)
+
+        def _record(
+            text: str,
+            document_id: str,
+            kb_scope: str,
+        ) -> VectorRecord:
+            return VectorRecord(
+                vector=[1.0, 0.0, 0.0],
+                document_id=document_id,
+                chunk=Chunk(
+                    content=TextBlock(text=text),
+                    source=f"{document_id}.txt",
+                    chunk_index=0,
+                    total_chunks=1,
+                    metadata={"kb_scope": kb_scope},
+                ),
+            )
+
+        await self.store.insert(
+            "kb-1",
+            [
+                _record("A", "doc-1", "kb-a"),
+                _record("B", "doc-2", "kb-b"),
+            ],
+        )
+
+        results = await self.store.search(
+            "kb-1",
+            query_vector=[1.0, 0.0, 0.0],
+            top_k=5,
+            metadata_filter={"kb_scope": "kb-a"},
+        )
+        self.assertEqual(
+            _dump_results(results),
+            [
+                {
+                    "score": 1.0,
+                    "document_id": "doc-1",
+                    "chunk": {
+                        "content": {
+                            "type": "text",
+                            "text": "A",
+                            "id": AnyString(),
+                        },
+                        "source": "doc-1.txt",
+                        "chunk_index": 0,
+                        "total_chunks": 1,
+                        "metadata": {"kb_scope": "kb-a"},
+                    },
+                },
+            ],
+        )
+
+        results = await self.store.search(
+            "kb-1",
+            query_vector=[1.0, 0.0, 0.0],
+            top_k=5,
+            metadata_filter={"kb_scope": "kb-b"},
+        )
+        self.assertEqual(
+            _dump_results(results),
+            [
+                {
+                    "score": 1.0,
+                    "document_id": "doc-2",
+                    "chunk": {
+                        "content": {
+                            "type": "text",
+                            "text": "B",
+                            "id": AnyString(),
+                        },
+                        "source": "doc-2.txt",
+                        "chunk_index": 0,
+                        "total_chunks": 1,
+                        "metadata": {"kb_scope": "kb-b"},
+                    },
+                },
+            ],
+        )
diff --git a/tests/rag_vdb_qdrant_test.py b/tests/rag_vdb_qdrant_test.py
new file mode 100644
index 0000000..54acd84
--- /dev/null
+++ b/tests/rag_vdb_qdrant_test.py
@@ -0,0 +1,376 @@
+# -*- coding: utf-8 -*-
+"""Unit tests for the QdrantStore class."""
+from contextlib import AsyncExitStack
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from utils import AnyString
+
+from agentscope.message import TextBlock
+from agentscope.rag import (
+    Chunk,
+    QdrantStore,
+    VectorRecord,
+    VectorSearchResult,
+)
+
+
+def _dump_results(results: list[VectorSearchResult]) -> list[dict]:
+    """Convert search results into plain dicts for whole-structure
+    comparison.
+
+    Args:
+        results (`list[VectorSearchResult]`):
+            The search results to convert.
+
+    Returns:
+        `list[dict]`:
+            The results as plain dicts.
+    """
+    return [result.model_dump() for result in results]
+
+
+def _make_record(
+    text: str,
+    vector: list[float],
+    document_id: str,
+    chunk_index: int = 0,
+    total_chunks: int = 1,
+) -> VectorRecord:
+    """Build a VectorRecord for testing.
+
+    Args:
+        text (`str`):
+            The chunk text content.
+        vector (`list[float]`):
+            The embedding vector.
+        document_id (`str`):
+            The ID of the source document the record belongs to.
+        chunk_index (`int`, defaults to ``0``):
+            The chunk index within the document.
+        total_chunks (`int`, defaults to ``1``):
+            The total number of chunks in the document.
+
+    Returns:
+        `VectorRecord`:
+            The constructed record.
+    """
+    return VectorRecord(
+        vector=vector,
+        document_id=document_id,
+        chunk=Chunk(
+            content=TextBlock(text=text),
+            source=f"{document_id}.txt",
+            chunk_index=chunk_index,
+            total_chunks=total_chunks,
+        ),
+    )
+
+
+class QdrantStoreTest(IsolatedAsyncioTestCase):
+    """The test cases for the QdrantStore class."""
+
+    async def asyncSetUp(self) -> None:
+        """Create an in-memory Qdrant store before each test."""
+        self._exit_stack = AsyncExitStack()
+        self.store = await self._exit_stack.enter_async_context(
+            QdrantStore(location=":memory:"),
+        )
+
+    async def asyncTearDown(self) -> None:
+        """Close the store after each test."""
+        await self._exit_stack.aclose()
+
+    async def test_collection_lifecycle(self) -> None:
+        """Collections can be created, checked, and deleted."""
+        self.assertEqual(await self.store.has_collection("kb-1"), False)
+
+        await self.store.create_collection("kb-1", dimensions=3)
+        self.assertEqual(await self.store.has_collection("kb-1"), True)
+
+        # Creating an existing collection is a no-op
+        await self.store.create_collection("kb-1", dimensions=3)
+        self.assertEqual(await self.store.has_collection("kb-1"), True)
+
+        await self.store.delete_collection("kb-1")
+        self.assertEqual(await self.store.has_collection("kb-1"), False)
+
+    async def test_insert_and_search(self) -> None:
+        """Inserted records are searchable, ordered by similarity."""
+        await self.store.create_collection("kb-1", dimensions=3)
+        await self.store.insert(
+            "kb-1",
+            [
+                _make_record(
+                    "Hello world!",
+                    [1.0, 0.0, 0.0],
+                    document_id="doc-1",
+                    chunk_index=0,
+                    total_chunks=2,
+                ),
+                _make_record(
+                    "Goodbye world!",
+                    [0.0, 1.0, 0.0],
+                    document_id="doc-1",
+                    chunk_index=1,
+                    total_chunks=2,
+                ),
+            ],
+        )
+
+        results = await self.store.search(
+            "kb-1",
+            query_vector=[1.0, 0.0, 0.0],
+            top_k=2,
+        )
+
+        self.assertEqual(
+            _dump_results(results),
+            [
+                {
+                    "score": 1.0,
+                    "document_id": "doc-1",
+                    "chunk": {
+                        "content": {
+                            "type": "text",
+                            "text": "Hello world!",
+                            "id": AnyString(),
+                        },
+                        "source": "doc-1.txt",
+                        "chunk_index": 0,
+                        "total_chunks": 2,
+                        "metadata": {},
+                    },
+                },
+                {
+                    "score": 0.0,
+                    "document_id": "doc-1",
+                    "chunk": {
+                        "content": {
+                            "type": "text",
+                            "text": "Goodbye world!",
+                            "id": AnyString(),
+                        },
+                        "source": "doc-1.txt",
+                        "chunk_index": 1,
+                        "total_chunks": 2,
+                        "metadata": {},
+                    },
+                },
+            ],
+        )
+
+    async def test_search_top_k(self) -> None:
+        """top_k limits the number of returned results."""
+        await self.store.create_collection("kb-1", dimensions=3)
+        await self.store.insert(
+            "kb-1",
+            [
+                _make_record("A", [1.0, 0.0, 0.0], document_id="doc-1"),
+                _make_record("B", [0.9, 0.1, 0.0], document_id="doc-2"),
+                _make_record("C", [0.0, 0.0, 1.0], document_id="doc-3"),
+            ],
+        )
+
+        results = await self.store.search(
+            "kb-1",
+            query_vector=[1.0, 0.0, 0.0],
+            top_k=1,
+        )
+
+        self.assertEqual(
+            _dump_results(results),
+            [
+                {
+                    "score": 1.0,
+                    "document_id": "doc-1",
+                    "chunk": {
+                        "content": {
+                            "type": "text",
+                            "text": "A",
+                            "id": AnyString(),
+                        },
+                        "source": "doc-1.txt",
+                        "chunk_index": 0,
+                        "total_chunks": 1,
+                        "metadata": {},
+                    },
+                },
+            ],
+        )
+
+    async def test_delete_by_document_id(self) -> None:
+        """delete removes all records of one document only."""
+        await self.store.create_collection("kb-1", dimensions=3)
+        await self.store.insert(
+            "kb-1",
+            [
+                _make_record(
+                    "doc1-chunk0",
+                    [1.0, 0.0, 0.0],
+                    document_id="doc-1",
+                    chunk_index=0,
+                    total_chunks=2,
+                ),
+                _make_record(
+                    "doc1-chunk1",
+                    [0.9, 0.1, 0.0],
+                    document_id="doc-1",
+                    chunk_index=1,
+                    total_chunks=2,
+                ),
+                _make_record(
+                    "doc2-chunk0",
+                    [0.0, 1.0, 0.0],
+                    document_id="doc-2",
+                ),
+            ],
+        )
+
+        await self.store.delete("kb-1", document_id="doc-1")
+
+        results = await self.store.search(
+            "kb-1",
+            query_vector=[1.0, 0.0, 0.0],
+            top_k=5,
+        )
+
+        self.assertEqual(
+            _dump_results(results),
+            [
+                {
+                    "score": 0.0,
+                    "document_id": "doc-2",
+                    "chunk": {
+                        "content": {
+                            "type": "text",
+                            "text": "doc2-chunk0",
+                            "id": AnyString(),
+                        },
+                        "source": "doc-2.txt",
+                        "chunk_index": 0,
+                        "total_chunks": 1,
+                        "metadata": {},
+                    },
+                },
+            ],
+        )
+
+    async def test_insert_empty_records(self) -> None:
+        """Inserting an empty record list is a no-op."""
+        await self.store.create_collection("kb-1", dimensions=3)
+        await self.store.insert("kb-1", [])
+
+        results = await self.store.search(
+            "kb-1",
+            query_vector=[1.0, 0.0, 0.0],
+        )
+
+        self.assertEqual(_dump_results(results), [])
+
+    async def test_list_documents_aggregates_by_document_id(self) -> None:
+        """list_documents groups chunks by document_id."""
+        await self.store.create_collection("kb-1", dimensions=3)
+
+        def _record_with_metadata(
+            text: str,
+            document_id: str,
+            metadata: dict,
+            chunk_index: int = 0,
+            total_chunks: int = 1,
+        ) -> VectorRecord:
+            return VectorRecord(
+                vector=[1.0, 0.0, 0.0],
+                document_id=document_id,
+                chunk=Chunk(
+                    content=TextBlock(text=text),
+                    source=metadata.get("filename", f"{document_id}.txt"),
+                    chunk_index=chunk_index,
+                    total_chunks=total_chunks,
+                    metadata=metadata,
+                ),
+            )
+
+        await self.store.insert(
+            "kb-1",
+            [
+                _record_with_metadata(
+                    "A",
+                    "doc-1",
+                    {"filename": "alpha.txt", "media_type": "text/plain"},
+                    0,
+                    2,
+                ),
+                _record_with_metadata(
+                    "B",
+                    "doc-1",
+                    {"filename": "alpha.txt", "media_type": "text/plain"},
+                    1,
+                    2,
+                ),
+                _record_with_metadata(
+                    "C",
+                    "doc-2",
+                    {"filename": "beta.md", "media_type": "text/markdown"},
+                    0,
+                    1,
+                ),
+            ],
+        )
+
+        summaries = await self.store.list_documents("kb-1")
+        summaries_by_id = {s.document_id: s for s in summaries}
+
+        self.assertEqual(set(summaries_by_id), {"doc-1", "doc-2"})
+        self.assertEqual(summaries_by_id["doc-1"].chunk_count, 2)
+        self.assertEqual(summaries_by_id["doc-1"].source, "alpha.txt")
+        self.assertEqual(
+            summaries_by_id["doc-1"].metadata,
+            {"filename": "alpha.txt", "media_type": "text/plain"},
+        )
+        self.assertEqual(summaries_by_id["doc-2"].chunk_count, 1)
+        self.assertEqual(summaries_by_id["doc-2"].source, "beta.md")
+
+    async def test_search_metadata_filter(self) -> None:
+        """search applies the metadata_filter as a payload predicate."""
+        await self.store.create_collection("kb-1", dimensions=3)
+
+        def _record(
+            text: str,
+            document_id: str,
+            kb_scope: str,
+        ) -> VectorRecord:
+            return VectorRecord(
+                vector=[1.0, 0.0, 0.0],
+                document_id=document_id,
+                chunk=Chunk(
+                    content=TextBlock(text=text),
+                    source=f"{document_id}.txt",
+                    chunk_index=0,
+                    total_chunks=1,
+                    metadata={"kb_scope": kb_scope},
+                ),
+            )
+
+        await self.store.insert(
+            "kb-1",
+            [
+                _record("A", "doc-1", "kb-a"),
+                _record("B", "doc-2", "kb-b"),
+            ],
+        )
+
+        results = await self.store.search(
+            "kb-1",
+            query_vector=[1.0, 0.0, 0.0],
+            top_k=5,
+            metadata_filter={"kb_scope": "kb-a"},
+        )
+        self.assertEqual([r.document_id for r in results], ["doc-1"])
+
+        results = await self.store.search(
+            "kb-1",
+            query_vector=[1.0, 0.0, 0.0],
+            top_k=5,
+            metadata_filter={"kb_scope": "kb-b"},
+        )
+        self.assertEqual([r.document_id for r in results], ["doc-2"])
diff --git a/tests/reme_middleware_test.py b/tests/reme_middleware_test.py
new file mode 100644
index 0000000..ad8044e
--- /dev/null
+++ b/tests/reme_middleware_test.py
@@ -0,0 +1,1242 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access,unused-argument
+"""Unit tests for ReMeMiddleware.
+
+The embedded ReMe app is mocked — we only exercise the AgentScope hook
+wiring (retrieve-before / write-after, system-prompt injection,
+list_tools exposure) and the small adapters that translate between
+AgentScope and ReMe. No real ReMe application is built.
+
+``protected-access`` is disabled because tests legitimately reach into
+middleware internals (``mw._app``, ``mw._search``, ``mw._session_id_of``)
+to inspect what the public API just did.
+"""
+import sys
+import types
+import asyncio
+from unittest import mock
+from unittest.async_case import IsolatedAsyncioTestCase
+from typing import Any
+
+from utils import MockModel
+
+from agentscope.agent import Agent
+from agentscope.event import (
+    ExternalExecutionResultEvent,
+    UserConfirmResultEvent,
+)
+from agentscope.message import (
+    HintBlock,
+    Msg,
+    TextBlock,
+    ToolCallBlock,
+    UserMsg,
+)
+from agentscope.embedding import EmbeddingModelBase
+from agentscope.middleware import ReMeMiddleware
+from agentscope.middleware._longterm_memory._reme._utils import (
+    _extract_memory_texts,
+    _extract_query_text,
+)
+from agentscope.model import ChatResponse
+from agentscope.permission import (
+    PermissionBehavior,
+    PermissionContext,
+    PermissionDecision,
+)
+from agentscope.tool import Toolkit, ToolBase, ToolChunk
+
+
+# ----------------------------------------------------------------------
+# Test helpers
+# ----------------------------------------------------------------------
+
+
+class RecordingMockModel(MockModel):
+    """MockModel that captures the ``messages`` of every _call_api call."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        """Initialize the recording mock model."""
+        super().__init__(*args, **kwargs)
+        self.calls: list[list[Msg]] = []
+
+    async def _call_api(
+        self,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Any:
+        """Record messages before delegating to MockModel."""
+        messages = kwargs.get("messages")
+        if messages is None and len(args) >= 2:
+            messages = args[1]
+        self.calls.append(list(messages or []))
+        return await super()._call_api(*args, **kwargs)
+
+    @property
+    def last_call_messages(self) -> list[Msg]:
+        """Return the most recent model-call messages."""
+        return self.calls[-1]
+
+
+class _FakeEmbedding(EmbeddingModelBase):
+    """Minimal ``EmbeddingModelBase`` instance for tests.
+
+    ``ReMeMiddleware.Parameters.embedding_model`` is validated by pydantic
+    (``arbitrary_types_allowed`` still isinstance-checks), so tests need a
+    real subclass rather than a bare sentinel. Its API is never called —
+    the middleware only checks presence and passes it through to ReMe.
+    """
+
+    def __init__(self) -> None:
+        """Skip the heavy base init; nothing here is exercised."""
+
+    async def _call_api(  # pragma: no cover - never invoked in tests
+        self,
+        inputs: list[Any],
+        **kwargs: Any,
+    ) -> Any:
+        """Unused: no test drives an actual embedding call."""
+        raise NotImplementedError
+
+
+class _FakeResponse:
+    """Minimal stand-in for ReMe's ``Response`` (answer/success/metadata)."""
+
+    def __init__(
+        self,
+        *,
+        answer: str = "",
+        success: bool = True,
+        metadata: dict | None = None,
+    ) -> None:
+        """Initialize the fake response."""
+        self.answer = answer
+        self.success = success
+        self.metadata = metadata or {}
+
+
+class _FakeReMeApp:
+    """Stands in for an embedded :class:`reme.ReMe` application.
+
+    Mirrors the surface :class:`ReMeMiddleware` drives directly (now that
+    there is no client wrapper): ``start`` / ``close`` lifecycle,
+    ``update_component`` (model injection), ``is_started``, and
+    ``run_job(name, **kwargs) -> Response``. Every job call is recorded;
+    ``search_calls`` / ``auto_memory_calls`` re-expose them in the
+    middleware's own terms for assertions.
+    """
+
+    def __init__(self, search_return: Any = None) -> None:
+        """Initialize the fake ReMe app."""
+        self.search_return = list(search_return) if search_return else []
+        self.run_job_calls: list[dict] = []
+        self.injected_models: list[Any] = []
+        self.injected_components: dict[str, Any] = {}
+        self.start_count = 0
+        self.closed = False
+        self.is_started = False
+        # Set to an exception to simulate a failing job.
+        self.search_error: Exception | None = None
+        self.auto_memory_error: Exception | None = None
+
+    async def start(self) -> None:
+        """Record an idempotent start."""
+        self.start_count += 1
+        self.is_started = True
+
+    async def close(self) -> None:
+        """Record a close."""
+        self.closed = True
+        self.is_started = False
+
+    async def update_component(
+        self,
+        component: str,
+        name: str,
+        **kwargs: Any,
+    ) -> None:
+        """Record a model injection into a ReMe default component."""
+        self.injected_models.append(kwargs.get("model"))
+        self.injected_components[component] = kwargs.get("model")
+
+    async def run_job(self, name: str, **kwargs: Any) -> _FakeResponse:
+        """Dispatch a ReMe job, recording the call."""
+        self.run_job_calls.append({"name": name, **kwargs})
+        if name == "search":
+            if self.search_error is not None:
+                raise self.search_error
+            results = [{"text": t} for t in self.search_return]
+            return _FakeResponse(metadata={"results": results})
+        if name == "auto_memory":
+            if self.auto_memory_error is not None:
+                raise self.auto_memory_error
+            return _FakeResponse(answer="recorded", success=True)
+        return _FakeResponse()
+
+    @property
+    def search_calls(self) -> list[dict]:
+        """Recorded search jobs in the middleware's terms."""
+        return [
+            {
+                "query": c.get("query"),
+                "limit": c.get("limit"),
+            }
+            for c in self.run_job_calls
+            if c["name"] == "search"
+        ]
+
+    @property
+    def auto_memory_calls(self) -> list[dict]:
+        """Recorded auto_memory jobs in the middleware's terms."""
+        return [
+            {
+                "messages": c.get("messages"),
+                "session_id": c.get("session_id"),
+            }
+            for c in self.run_job_calls
+            if c["name"] == "auto_memory"
+        ]
+
+    @property
+    def last_chat_model(self) -> Any:
+        """The model injected into the ``as_llm`` component, if any."""
+        return self.injected_components.get("as_llm")
+
+    @property
+    def last_embedding_model(self) -> Any:
+        """The model injected into the ``as_embedding`` component."""
+        return self.injected_components.get("as_embedding")
+
+
+def _mw(*, app: Any = None, **kwargs: Any) -> ReMeMiddleware:
+    """Build a ``ReMeMiddleware`` with a fake embedded app injected.
+
+    ``ReMeMiddleware`` owns and builds its own ``reme.ReMe`` app, so tests
+    can't pass one in. Instead we construct the middleware normally and
+    seed ``mw._app`` with a :class:`_FakeReMeApp` before it starts — the
+    lazy ``_ensure_started`` path sees a non-``None`` app and skips the
+    real build, so no ``reme-ai`` install is needed.
+
+    User-tunable kwargs (``chat_model`` / ``embedding_model`` / ``mode`` /
+    ``top_k``) are collected into a ``ReMeMiddleware.Parameters`` so tests
+    can keep passing them flat; the rest go straight to the constructor.
+    """
+    param_keys = ("chat_model", "embedding_model", "mode", "top_k")
+    param_kwargs = {k: kwargs.pop(k) for k in param_keys if k in kwargs}
+    if param_kwargs:
+        kwargs["parameters"] = ReMeMiddleware.Parameters(**param_kwargs)
+    mw = ReMeMiddleware(**kwargs)
+    mw._app = app if app is not None else _FakeReMeApp()
+    return mw
+
+
+def _single_response(text: str) -> ChatResponse:
+    """Build a final single-text chat response."""
+    return ChatResponse(
+        content=[TextBlock(type="text", text=text)],
+        is_last=True,
+    )
+
+
+def _echo_then_text(final_text: str, echo: str = "ping") -> list:
+    """Two-step response sequence: an ``echo`` tool call, then a text answer.
+
+    Auto-retrieval now runs as a background task started in ``on_reply`` and
+    injected in ``on_reasoning`` once it finishes. A single-shot reply may
+    complete before retrieval does, so tests that need to observe the
+    injected memory drive a tool call first (two reasoning steps): the task
+    finishes during step 1, so the hint is present before step 2's model
+    call — the same pattern the AgenticMemory middleware tests use.
+    """
+    return [
+        [
+            ChatResponse(
+                content=[
+                    ToolCallBlock(
+                        id="call-1",
+                        name="echo",
+                        input=f'{{"text": "{echo}"}}',
+                    ),
+                ],
+                is_last=True,
+            ),
+        ],
+        [
+            ChatResponse(
+                content=[TextBlock(text=final_text)],
+                is_last=True,
+            ),
+        ],
+    ]
+
+
+class _EchoTool(ToolBase):
+    """A trivial always-allowed tool used to force a multi-step turn."""
+
+    name: str = "echo"
+    description: str = "Echo the given text back."
+    input_schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {
+            "text": {"type": "string", "description": "Text to echo."},
+        },
+        "required": ["text"],
+    }
+    is_concurrency_safe: bool = True
+    is_read_only: bool = True
+    is_external_tool: bool = False
+    is_mcp: bool = False
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        """Always allow — this is a test fixture."""
+        return PermissionDecision(
+            behavior=PermissionBehavior.ALLOW,
+            decision_reason="test tool",
+            message="test tool",
+        )
+
+    async def __call__(self, text: str, **kwargs: Any) -> ToolChunk:
+        """Echo ``text`` back as the tool result."""
+        return ToolChunk(content=[TextBlock(text=f"echo: {text}")])
+
+
+def _all_tool_names(toolkit: Toolkit) -> list[str]:
+    """Flatten every registered tool's name across every group."""
+    return [t.name for g in toolkit.tool_groups for t in g.tools]
+
+
+def _find_tool(toolkit: Toolkit, name: str) -> Any:
+    """Look a tool up by name across every group on the toolkit."""
+    for g in toolkit.tool_groups:
+        for t in g.tools:
+            if t.name == name:
+                return t
+    raise LookupError(f"tool {name!r} not found in any group")
+
+
+def _find_group(toolkit: Toolkit, name: str) -> Any:
+    """Look a tool group up by name on the toolkit."""
+    for g in toolkit.tool_groups:
+        if g.name == name:
+            return g
+    raise LookupError(f"tool group {name!r} not found")
+
+
+def _chunk_text(chunk: Any) -> str:
+    """Return the first text block from a tool chunk."""
+    return chunk.content[0].text
+
+
+def _msg_text(m: Any) -> str:
+    """Text of a message that may be a ``Msg`` or a serialized dict.
+
+    The middleware serializes messages via ``Msg.model_dump(mode="json")``
+    before handing them to ReMe's ``auto_memory`` job, so the fake app
+    records dicts whose ``content`` is a list of typed blocks.
+    """
+    if hasattr(m, "get_text_content"):
+        return m.get_text_content() or ""
+    content = m.get("content") if isinstance(m, dict) else None
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        return "\n".join(
+            b.get("text", "")
+            for b in content
+            if isinstance(b, dict) and b.get("type") == "text"
+        )
+    return ""
+
+
+# ----------------------------------------------------------------------
+# Unit tests for module-level helpers
+# ----------------------------------------------------------------------
+
+
+class TestExtractQueryText(IsolatedAsyncioTestCase):
+    """Tests for extracting the query text from incoming inputs."""
+
+    def test_none_and_empty(self) -> None:
+        """None and empty inputs should not produce a query."""
+        self.assertIsNone(_extract_query_text(None))
+        self.assertIsNone(_extract_query_text([]))
+
+    def test_single_user_msg(self) -> None:
+        """A single user message should become its text content."""
+        msg = UserMsg("user", "hello world")
+        self.assertEqual(_extract_query_text(msg), "hello world")
+
+    def test_list_of_user_msgs_joined(self) -> None:
+        """Multiple user messages should be joined by newlines."""
+        msgs = [UserMsg("user", "first"), UserMsg("user", "second")]
+        self.assertEqual(_extract_query_text(msgs), "first\nsecond")
+
+    def test_resumption_events_return_none(self) -> None:
+        """HITL resumption events should not trigger memory IO."""
+        self.assertIsNone(
+            _extract_query_text(
+                UserConfirmResultEvent(
+                    reply_id="reply",
+                    confirm_results=[],
+                ),
+            ),
+        )
+        self.assertIsNone(
+            _extract_query_text(
+                ExternalExecutionResultEvent(
+                    reply_id="reply",
+                    execution_results=[],
+                ),
+            ),
+        )
+
+
+class TestExtractMemoryTexts(IsolatedAsyncioTestCase):
+    """Tests for normalizing ReMe search responses into text lists."""
+
+    def test_metadata_results_file_chunks(self) -> None:
+        """The standard ReMe envelope nests chunks under metadata."""
+        raw = {
+            "answer": "",
+            "success": True,
+            "metadata": {
+                "results": [
+                    {"text": "a", "path": "daily/1.md", "score": 0.9},
+                    {"text": "b", "path": "daily/2.md", "score": 0.8},
+                ],
+            },
+        }
+        self.assertEqual(_extract_memory_texts(raw), ["a", "b"])
+
+    def test_unwrapped_results(self) -> None:
+        """An already-unwrapped results list should also work."""
+        self.assertEqual(
+            _extract_memory_texts({"results": [{"text": "only"}]}),
+            ["only"],
+        )
+
+    def test_plain_list_of_dicts_and_strings(self) -> None:
+        """Plain lists of chunks or strings should be supported."""
+        self.assertEqual(
+            _extract_memory_texts([{"memory": "m"}, "raw"]),
+            ["m", "raw"],
+        )
+
+    def test_none_and_garbage(self) -> None:
+        """Malformed ReMe outputs should normalize to an empty list."""
+        self.assertEqual(_extract_memory_texts(None), [])
+        self.assertEqual(
+            _extract_memory_texts({"metadata": {"results": "nope"}}),
+            [],
+        )
+
+
+# ----------------------------------------------------------------------
+# Constructor validation
+# ----------------------------------------------------------------------
+
+
+class TestConstructorValidation(IsolatedAsyncioTestCase):
+    """Tests for ReMeMiddleware constructor validation."""
+
+    def test_unknown_mode_raises(self) -> None:
+        """Unknown control modes should be rejected by the Parameters model."""
+        from pydantic import ValidationError
+
+        with self.assertRaises(ValidationError):
+            ReMeMiddleware.Parameters(
+                mode="garbage",  # type: ignore[arg-type]
+            )
+
+    def test_session_id_not_stored_on_middleware(self) -> None:
+        """session_id is read live from the agent, never stored.
+
+        The middleware takes no ``session_id`` argument and keeps no
+        ``_session_id`` attribute, so one instance shared across agents
+        cannot leak one conversation's session into another's write-back.
+        It is read per call from ``agent.state.session_id``.
+        """
+        mw = ReMeMiddleware()
+        self.assertFalse(hasattr(mw, "_session_id"))
+
+        class _State:
+            session_id = "sess-xyz"
+
+        class _Agent:
+            state = _State()
+
+        self.assertEqual(mw._session_id_of(_Agent()), "sess-xyz")
+        self.assertIsNone(mw._session_id_of(object()))
+
+    def test_embedding_model_enables_vector_store(self) -> None:
+        """An ``embedding_model`` turns ReMe's vector store on at build."""
+        captured: dict = {}
+
+        def _fake_resolve(**kwargs: Any) -> dict:
+            captured.update(kwargs)
+            return {"_ok": True}
+
+        fake_reme = types.ModuleType("reme")
+        fake_reme.ReMe = lambda **kw: ("app", kw)  # type: ignore[attr-defined]
+        fake_cfg = types.ModuleType("reme.config")
+        setattr(fake_cfg, "resolve_app_config", _fake_resolve)
+
+        mw = ReMeMiddleware(
+            workspace_dir="/real/ws",
+            config="mycfg",
+            parameters=ReMeMiddleware.Parameters(
+                embedding_model=_FakeEmbedding(),
+            ),
+        )
+        with mock.patch.dict(
+            sys.modules,
+            {"reme": fake_reme, "reme.config": fake_cfg},
+        ):
+            mw._build_app()
+
+        self.assertEqual(
+            captured["components"],
+            {"file_store": {"default": {"embedding_store": "default"}}},
+        )
+        self.assertEqual(captured["workspace_dir"], "/real/ws")
+        self.assertEqual(captured["config"], "mycfg")
+        self.assertFalse(captured["enable_logo"])
+
+    def test_no_embedding_model_keeps_keyword_only(self) -> None:
+        """Without an ``embedding_model`` the vector store stays off."""
+        captured: dict = {}
+
+        def _fake_resolve(**kwargs: Any) -> dict:
+            captured.update(kwargs)
+            return {"_ok": True}
+
+        fake_reme = types.ModuleType("reme")
+        fake_reme.ReMe = lambda **kw: ("app", kw)  # type: ignore[attr-defined]
+        fake_cfg = types.ModuleType("reme.config")
+        setattr(fake_cfg, "resolve_app_config", _fake_resolve)
+
+        mw = ReMeMiddleware(workspace_dir="/real/ws")
+        with mock.patch.dict(
+            sys.modules,
+            {"reme": fake_reme, "reme.config": fake_cfg},
+        ):
+            mw._build_app()
+
+        self.assertNotIn("components", captured)
+
+
+# ----------------------------------------------------------------------
+# Static-control mode (default)
+# ----------------------------------------------------------------------
+
+
+class TestStaticControlMode(IsolatedAsyncioTestCase):
+    """Default mode: retrieve-before / inject / write-after, no tools."""
+
+    async def asyncSetUp(self) -> None:
+        """Create a fresh recording model and empty toolkit."""
+        self.model = RecordingMockModel(context_size=100_000)
+        self.toolkit = Toolkit()
+
+    def _agent(
+        self,
+        middleware: ReMeMiddleware,
+        response_text: str = "ok",
+    ) -> Agent:
+        """Build a test agent using ``middleware`` and one response."""
+        self.model.set_responses([_single_response(response_text)])
+        return Agent(
+            name="agent_under_test",
+            system_prompt="base system prompt",
+            model=self.model,
+            toolkit=self.toolkit,
+            middlewares=[middleware],
+        )
+
+    async def test_retrieve_inject_write(self) -> None:
+        """Static control should search, inject, reply, then write."""
+        fake = _FakeReMeApp(search_return=["alice loves coffee"])
+        mw = _mw(
+            app=fake,
+            mode="static_control",
+        )
+
+        # A tool call gives two reasoning steps, so the background retrieval
+        # finishes and its hint injects before the final model call.
+        self.model.set_responses(_echo_then_text("hi alice"))
+        toolkit = Toolkit(tools=[_EchoTool()])
+        agent = Agent(
+            name="agent_under_test",
+            system_prompt="base system prompt",
+            model=self.model,
+            toolkit=toolkit,
+            middlewares=[mw],
+        )
+        # session_id is sourced from the agent, not the middleware.
+        agent.state.session_id = "alice-001"
+        reply = await agent.reply(UserMsg("user", "remind me what I like"))
+
+        # 1. search called with the user query, configured limit/min_score
+        self.assertEqual(len(fake.search_calls), 1)
+        self.assertEqual(
+            fake.search_calls[0]["query"],
+            "remind me what I like",
+        )
+        self.assertEqual(fake.search_calls[0]["limit"], 5)
+
+        # 2. write called post-turn with the user+assistant pair, scoped
+        #    by session_id.
+        self.assertEqual(len(fake.auto_memory_calls), 1)
+        write = fake.auto_memory_calls[0]
+        self.assertEqual(write["session_id"], "alice-001")
+        written_texts = [_msg_text(m) for m in write["messages"]]
+        self.assertIn("remind me what I like", written_texts)
+        self.assertIn("hi alice", written_texts)
+
+        # 3. system prompt unchanged — static_control adds no tool nudge.
+        sys_msg = self.model.last_call_messages[0]
+        self.assertEqual(sys_msg.role, "system")
+        self.assertEqual(sys_msg.get_text_content(), "base system prompt")
+
+        # 4. memory appended to the agent's persistent context as an
+        #    assistant-role hint note named "memory".
+        memory_msgs = [
+            m
+            for m in agent.state.context
+            if getattr(m, "name", None) == "memory"
+        ]
+        self.assertEqual(len(memory_msgs), 1)
+        self.assertEqual(memory_msgs[0].role, "assistant")
+        memory_hints = memory_msgs[0].get_content_blocks("hint")
+        self.assertEqual(len(memory_hints), 1)
+        self.assertIsInstance(memory_hints[0], HintBlock)
+        memory_text = memory_hints[0].hint
+        self.assertIn("Relevant memories", memory_text)
+        self.assertIn("alice loves coffee", memory_text)
+        # The model saw it on the final call (injected before step 2).
+        delivered = [
+            m
+            for m in self.model.last_call_messages
+            if getattr(m, "name", None) == "memory"
+        ]
+        self.assertEqual(len(delivered), 1)
+
+        # 5. no agent-control tools registered (in any group)
+        all_names = _all_tool_names(toolkit)
+        self.assertNotIn("memory_search", all_names)
+        self.assertNotIn("add_memory", all_names)
+
+        self.assertEqual(reply.get_text_content(), "hi alice")
+
+    async def test_write_back_includes_full_turn_increment(self) -> None:
+        """Write-back persists the whole turn — user input, the tool-call
+        step, the tool result, and the final answer — not just the last
+        message, and never the injected memory note."""
+        fake = _FakeReMeApp(search_return=["remembered fact"])
+        mw = _mw(app=fake, mode="static_control")
+
+        # Turn 1: the model asks for a tool call; turn 2: it answers.
+        self.model.set_responses(
+            [
+                [
+                    ChatResponse(
+                        content=[
+                            ToolCallBlock(
+                                id="call-1",
+                                name="echo",
+                                input='{"text": "ping"}',
+                            ),
+                        ],
+                        is_last=True,
+                    ),
+                ],
+                [
+                    ChatResponse(
+                        content=[TextBlock(text="final answer")],
+                        is_last=True,
+                    ),
+                ],
+            ],
+        )
+        agent = Agent(
+            name="agent_under_test",
+            system_prompt="base system prompt",
+            model=self.model,
+            toolkit=Toolkit(tools=[_EchoTool()]),
+            middlewares=[mw],
+        )
+        agent.state.session_id = "s-multi"
+
+        await agent.reply(UserMsg("user", "use the echo tool then answer"))
+
+        self.assertEqual(len(fake.auto_memory_calls), 1)
+        written = fake.auto_memory_calls[0]["messages"]
+
+        # The injected memory hint is NEVER written back.
+        self.assertFalse(
+            any(m.get("name") == "memory" for m in written),
+            "the injected memory note must be excluded from write-back",
+        )
+
+        # Every step of the turn is present: user input, the assistant
+        # tool call, the tool result, and the final answer.
+        block_types = {
+            b.get("type")
+            for m in written
+            for b in (m.get("content") or [])
+            if isinstance(b, dict)
+        }
+        self.assertIn("tool_call", block_types)
+        self.assertIn("tool_result", block_types)
+
+        texts = [_msg_text(m) for m in written]
+        self.assertIn("use the echo tool then answer", texts)
+        self.assertIn("final answer", texts)
+
+    async def test_write_back_is_per_turn_increment(self) -> None:
+        """Each write-back carries ONLY that turn's new messages.
+
+        ``auto_memory`` consumes the incremental exchange, while
+        ``agent.state.context`` is the full accumulated history — so a
+        second turn must not re-send the first turn's messages.
+        """
+        fake = _FakeReMeApp(search_return=[])
+        mw = _mw(app=fake, mode="static_control")
+
+        # Two sequential turns on the SAME agent (shared, growing context).
+        self.model.set_responses(
+            [
+                _single_response("first answer"),
+                _single_response("second answer"),
+            ],
+        )
+        agent = Agent(
+            name="agent_under_test",
+            system_prompt="base system prompt",
+            model=self.model,
+            toolkit=self.toolkit,
+            middlewares=[mw],
+        )
+        agent.state.session_id = "s-seq"
+
+        await agent.reply(UserMsg("user", "first question"))
+        await agent.reply(UserMsg("user", "second question"))
+
+        self.assertEqual(len(fake.auto_memory_calls), 2)
+        first_texts = [
+            _msg_text(m) for m in fake.auto_memory_calls[0]["messages"]
+        ]
+        second_texts = [
+            _msg_text(m) for m in fake.auto_memory_calls[1]["messages"]
+        ]
+
+        # Turn 1 wrote only turn-1 content.
+        self.assertIn("first question", first_texts)
+        self.assertIn("first answer", first_texts)
+
+        # Turn 2 wrote ONLY turn-2 content — none of turn 1 leaked in,
+        # even though it is still present in agent.state.context.
+        self.assertIn("second question", second_texts)
+        self.assertIn("second answer", second_texts)
+        self.assertNotIn("first question", second_texts)
+        self.assertNotIn("first answer", second_texts)
+
+    async def test_memory_message_lands_after_user_message(self) -> None:
+        """The memory note is inserted AFTER the new user input lands in the
+        agent context (injected on a later reasoning step, not before)."""
+        fake = _FakeReMeApp(search_return=["saved fact"])
+        mw = _mw(
+            app=fake,
+            mode="static_control",
+        )
+        self.model.set_responses(_echo_then_text("answer"))
+        agent = Agent(
+            name="agent_under_test",
+            system_prompt="base system prompt",
+            model=self.model,
+            toolkit=Toolkit(tools=[_EchoTool()]),
+            middlewares=[mw],
+        )
+        await agent.reply(UserMsg("user", "tell me what you know"))
+
+        roles_and_names = [
+            (m.role, getattr(m, "name", None)) for m in agent.state.context
+        ]
+        user_idx = next(
+            i
+            for i, (r, n) in enumerate(roles_and_names)
+            if r == "user" and n != "memory"
+        )
+        memory_idx = next(
+            i for i, (_, n) in enumerate(roles_and_names) if n == "memory"
+        )
+        self.assertGreater(
+            memory_idx,
+            user_idx,
+            f"memory note at {memory_idx} should come after user msg "
+            f"at {user_idx}: {roles_and_names}",
+        )
+
+    async def test_no_memories_no_injection(self) -> None:
+        """Empty search results should not add a memory hint message."""
+        fake = _FakeReMeApp(search_return=[])
+        mw = _mw(
+            app=fake,
+            mode="static_control",
+        )
+
+        # Tool call → two reasoning steps, so retrieval completes and the
+        # injection path is exercised; with empty results it must add nothing.
+        self.model.set_responses(_echo_then_text("ok"))
+        agent = Agent(
+            name="agent_under_test",
+            system_prompt="base system prompt",
+            model=self.model,
+            toolkit=Toolkit(tools=[_EchoTool()]),
+            middlewares=[mw],
+        )
+        await agent.reply(UserMsg("user", "hi"))
+
+        msgs = self.model.last_call_messages
+        self.assertEqual(msgs[0].get_text_content(), "base system prompt")
+        for m in msgs:
+            self.assertNotEqual(getattr(m, "name", None), "memory")
+        for m in agent.state.context:
+            self.assertNotEqual(getattr(m, "name", None), "memory")
+        self.assertEqual(len(fake.search_calls), 1)
+
+    async def test_search_failure_does_not_break_reply(self) -> None:
+        """Search errors should be logged but not block the reply."""
+        fake = _FakeReMeApp()
+        fake.search_error = RuntimeError("reme down")
+        mw = _mw(
+            app=fake,
+            mode="static_control",
+        )
+
+        agent = self._agent(mw, response_text="still works")
+        reply = await agent.reply(UserMsg("user", "ping"))
+
+        self.assertEqual(reply.get_text_content(), "still works")
+        # Write still happened — a failed search must not block writes.
+        self.assertEqual(len(fake.auto_memory_calls), 1)
+
+    async def test_shared_middleware_isolates_sessions(self) -> None:
+        """One middleware shared by two agents writes each agent's own
+        session_id — no leakage from a stored session."""
+        fake = _FakeReMeApp()
+        mw = _mw(app=fake, mode="static_control")
+
+        self.model.set_responses(
+            [_single_response("r1"), _single_response("r2")],
+        )
+        agent_a = Agent(
+            name="a",
+            system_prompt="p",
+            model=self.model,
+            toolkit=Toolkit(),
+            middlewares=[mw],
+        )
+        agent_a.state.session_id = "sess-a"
+        agent_b = Agent(
+            name="b",
+            system_prompt="p",
+            model=self.model,
+            toolkit=Toolkit(),
+            middlewares=[mw],
+        )
+        agent_b.state.session_id = "sess-b"
+
+        await agent_a.reply(UserMsg("user", "hi from a"))
+        await agent_b.reply(UserMsg("user", "hi from b"))
+
+        sessions = [c["session_id"] for c in fake.auto_memory_calls]
+        self.assertEqual(sessions, ["sess-a", "sess-b"])
+
+    async def test_concurrent_sessions_isolate_retrieval_tasks(self) -> None:
+        """Retrieval tasks are keyed by session_id, so two replies running
+        concurrently on a shared middleware never clobber each other's
+        in-flight search — each session injects its own note and no task is
+        left behind."""
+        fake = _FakeReMeApp(search_return=["shared fact"])
+        mw = _mw(app=fake, mode="static_control")
+
+        def _make_agent(sid: str) -> Agent:
+            # Distinct model per agent: a shared response queue would be
+            # consumed racily by concurrent turns.
+            model = RecordingMockModel(context_size=100_000)
+            model.set_responses(_echo_then_text(f"done-{sid}"))
+            agent = Agent(
+                name=sid,
+                system_prompt="base",
+                model=model,
+                toolkit=Toolkit(tools=[_EchoTool()]),
+                middlewares=[mw],
+            )
+            agent.state.session_id = sid
+            return agent
+
+        agent_a = _make_agent("sess-a")
+        agent_b = _make_agent("sess-b")
+
+        await asyncio.gather(
+            agent_a.reply(UserMsg("user", "a asks")),
+            agent_b.reply(UserMsg("user", "b asks")),
+        )
+
+        # Each session injected its own memory note exactly once.
+        for agent in (agent_a, agent_b):
+            notes = [
+                m
+                for m in agent.state.context
+                if getattr(m, "name", None) == "memory"
+            ]
+            self.assertEqual(len(notes), 1, f"{agent.name} missing its note")
+
+        # No task left behind for either session after both turns finish.
+        self.assertEqual(mw._retrieval_tasks, {})
+
+    async def test_chat_model_injected_at_start(self) -> None:
+        """The configured chat_model is injected into ReMe at start."""
+        explicit = RecordingMockModel(context_size=100_000)
+        fake = _FakeReMeApp()
+        mw = _mw(
+            app=fake,
+            mode="static_control",
+            chat_model=explicit,
+        )
+        agent = self._agent(mw)
+        await agent.reply(UserMsg("user", "hi"))
+        self.assertIs(mw._parameters.chat_model, explicit)
+        self.assertIs(fake.last_chat_model, explicit)
+
+    async def test_no_chat_model_no_injection(self) -> None:
+        """Without a chat_model the middleware injects nothing.
+
+        The model is fixed at construction and never taken from the agent,
+        so ReMe falls back to the LLM in its own config/credentials.
+        """
+        fake = _FakeReMeApp()
+        mw = _mw(
+            app=fake,
+            mode="static_control",
+        )
+        agent = self._agent(mw)
+        await agent.reply(UserMsg("user", "hi"))
+        self.assertIsNone(mw._parameters.chat_model)
+        self.assertEqual(fake.injected_models, [])
+
+    async def test_embedding_model_injected_at_start(self) -> None:
+        """The configured embedding_model is injected into ReMe at start.
+
+        ReMe starts its ``as_embedding`` component eagerly; injecting a
+        model bypasses ReMe building its own from credentials, mirroring
+        the chat-model injection into ``as_llm``.
+        """
+        chat = RecordingMockModel(context_size=100_000)
+        embedding = _FakeEmbedding()  # only passed through to ReMe
+        fake = _FakeReMeApp()
+        mw = _mw(
+            app=fake,
+            mode="static_control",
+            chat_model=chat,
+            embedding_model=embedding,
+        )
+        agent = self._agent(mw)
+        await agent.reply(UserMsg("user", "hi"))
+        self.assertIs(mw._parameters.embedding_model, embedding)
+        self.assertIs(fake.last_embedding_model, embedding)
+        # Both components are configured independently at start.
+        self.assertIs(fake.last_chat_model, chat)
+
+    async def test_no_embedding_model_no_injection(self) -> None:
+        """Without an embedding_model, ReMe's embedding stays untouched."""
+        fake = _FakeReMeApp()
+        mw = _mw(
+            app=fake,
+            mode="static_control",
+            chat_model=RecordingMockModel(context_size=100_000),
+        )
+        agent = self._agent(mw)
+        await agent.reply(UserMsg("user", "hi"))
+        self.assertIsNone(mw._parameters.embedding_model)
+        self.assertIsNone(fake.last_embedding_model)
+
+
+# ----------------------------------------------------------------------
+# Agent-control mode
+# ----------------------------------------------------------------------
+
+
+class TestAgentControlMode(IsolatedAsyncioTestCase):
+    """Tools are listed, but no automatic memory hook behavior."""
+
+    async def asyncSetUp(self) -> None:
+        """Create a fresh recording model and empty toolkit."""
+        self.model = RecordingMockModel(context_size=100_000)
+        self.toolkit = Toolkit()
+
+    async def _agent(
+        self,
+        middleware: ReMeMiddleware,
+        *,
+        name: str = "a",
+        system_prompt: str = "p",
+        responses: list[str] | None = None,
+    ) -> Agent:
+        """Build an agent with tools explicitly listed by middleware."""
+        self.model.set_responses(
+            [_single_response(r) for r in (responses or ["ok"])],
+        )
+        self.toolkit = Toolkit(tools=await middleware.list_tools())
+        return Agent(
+            name=name,
+            system_prompt=system_prompt,
+            model=self.model,
+            toolkit=self.toolkit,
+            middlewares=[middleware],
+        )
+
+    async def test_tools_listed_and_hint_in_prompt(self) -> None:
+        """Agent-control mode should expose the search tool + prompt nudge."""
+        fake = _FakeReMeApp(search_return=["found"])
+        mw = _mw(
+            app=fake,
+            mode="agent_control",
+        )
+        agent = await self._agent(mw, system_prompt="base prompt")
+        await agent.reply(UserMsg("user", "hello"))
+
+        basic = _find_group(self.toolkit, "basic")
+        names = [t.name for t in basic.tools]
+        self.assertIn("memory_search", names)
+        # ReMe has no manual add tool — writing is automatic.
+        self.assertNotIn("add_memory", names)
+
+        # No automatic retrieval ran — agent_control leaves search to the
+        # tool...
+        self.assertEqual(fake.search_calls, [])
+        # ...but write-back is automatic in every mode (ReMe listens to
+        # the conversation via the reply hook).
+        self.assertEqual(len(fake.auto_memory_calls), 1)
+
+        # System prompt got a short nudge mentioning the tool.
+        msgs = self.model.last_call_messages
+        prompt_text = msgs[0].get_text_content()
+        self.assertIn("base prompt", prompt_text)
+        self.assertIn("Long-term memory", prompt_text)
+        self.assertIn("memory_search", prompt_text)
+        # No synthetic memory message was injected in agent_control mode.
+        for m in msgs:
+            self.assertNotEqual(getattr(m, "name", None), "memory")
+
+    async def test_middleware_does_not_mutate_toolkit(self) -> None:
+        """Middleware should not register tools unless caller does so."""
+        fake = _FakeReMeApp()
+        mw = _mw(
+            app=fake,
+            mode="agent_control",
+        )
+        self.model.set_responses([_single_response("ok")])
+        toolkit = Toolkit()
+        agent = Agent(
+            name="a",
+            system_prompt="base prompt",
+            model=self.model,
+            toolkit=toolkit,
+            middlewares=[mw],
+        )
+        await agent.reply(UserMsg("user", "hello"))
+
+        self.assertNotIn("memory_search", _all_tool_names(toolkit))
+        self.assertNotIn("add_memory", _all_tool_names(toolkit))
+
+    async def test_memory_search_tool_invokes_reme(self) -> None:
+        """The memory_search tool should query ReMe and return results."""
+        fake = _FakeReMeApp(search_return=["first fact", "second fact"])
+        mw = _mw(
+            app=fake,
+            mode="agent_control",
+        )
+        agent = await self._agent(mw, system_prompt="base prompt")
+        await agent.reply(UserMsg("user", "hi"))
+
+        search_tool = _find_tool(self.toolkit, "memory_search")
+        result = await search_tool(
+            query="what does alice like?",
+            limit=3,
+        )
+        result_text = _chunk_text(result)
+        self.assertIn("first fact", result_text)
+        self.assertIn("second fact", result_text)
+
+        # One ReMe search, using the supplied limit.
+        self.assertEqual(len(fake.search_calls), 1)
+        self.assertEqual(
+            fake.search_calls[0]["query"],
+            "what does alice like?",
+        )
+        self.assertEqual(fake.search_calls[0]["limit"], 3)
+
+    async def test_memory_search_default_limit_is_top_k(self) -> None:
+        """Omitting ``limit`` should fall back to the middleware's top_k.
+
+        The tool advertises ``top_k`` as the schema default and resolves an
+        omitted ``limit`` through it, so configuring ``top_k`` governs the
+        agent-facing tool, not just static-control retrieval.
+        """
+        fake = _FakeReMeApp(search_return=["fact"])
+        mw = _mw(
+            app=fake,
+            mode="agent_control",
+            top_k=11,
+        )
+        agent = await self._agent(mw)
+        await agent.reply(UserMsg("user", "hi"))
+
+        search_tool = _find_tool(self.toolkit, "memory_search")
+        # Schema advertises top_k as the default.
+        self.assertEqual(
+            search_tool.input_schema["properties"]["limit"]["default"],
+            11,
+        )
+
+        # Calling without a limit uses top_k.
+        await search_tool(query="what does alice like?")
+        self.assertEqual(fake.search_calls[-1]["limit"], 11)
+
+    async def test_memory_search_no_results(self) -> None:
+        """An empty workspace yields a friendly no-results message."""
+        fake = _FakeReMeApp(search_return=[])
+        mw = _mw(
+            app=fake,
+            mode="agent_control",
+        )
+        agent = await self._agent(mw)
+        await agent.reply(UserMsg("user", "hi"))
+        search_tool = _find_tool(self.toolkit, "memory_search")
+
+        result = await search_tool(query="anything", limit=5)
+        self.assertIn("no relevant memories", _chunk_text(result).lower())
+
+    async def test_memory_search_failure_returns_error_chunk(self) -> None:
+        """ReMe raising during search yields a ToolChunk state=ERROR."""
+        from agentscope.message import ToolResultState
+
+        fake = _FakeReMeApp()
+        fake.search_error = RuntimeError("reme down")
+        mw = _mw(
+            app=fake,
+            mode="agent_control",
+        )
+        agent = await self._agent(mw)
+        await agent.reply(UserMsg("user", "hi"))
+        search_tool = _find_tool(self.toolkit, "memory_search")
+
+        result = await search_tool(query="q", limit=5)
+        self.assertIsInstance(result, ToolChunk)
+        self.assertEqual(result.state, ToolResultState.ERROR)
+        self.assertIn("reme down", result.content[0].text)
+
+    async def test_tools_auto_allow_permission(self) -> None:
+        """The memory tool should be auto-allowed by permission checks."""
+        mw = _mw(
+            app=_FakeReMeApp(),
+            mode="agent_control",
+        )
+        agent = await self._agent(mw)
+        await agent.reply(UserMsg("user", "hi"))
+
+        search_tool = _find_tool(self.toolkit, "memory_search")
+        decision_search = await search_tool.check_permissions({}, None)
+        self.assertEqual(decision_search.behavior, PermissionBehavior.ALLOW)
+
+    async def test_no_add_memory_tool_exposed(self) -> None:
+        """ReMe exposes search only — there is no manual add tool."""
+        mw = _mw(
+            app=_FakeReMeApp(),
+            mode="agent_control",
+        )
+        tools = await mw.list_tools()
+        names = [t.name for t in tools]
+        self.assertEqual(names, ["memory_search"])
+
+    async def test_agent_control_writes_back_automatically(self) -> None:
+        """Even with no add tool, agent_control writes via the reply hook."""
+        fake = _FakeReMeApp()
+        mw = _mw(
+            app=fake,
+            mode="agent_control",
+        )
+        agent = await self._agent(mw, responses=["sure thing"])
+        # session_id is sourced from the agent, not the middleware.
+        agent.state.session_id = "alice-001"
+        await agent.reply(UserMsg("user", "remember I like tea"))
+
+        # No auto-retrieval in agent_control...
+        self.assertEqual(fake.search_calls, [])
+        # ...but the exchange was written back automatically.
+        self.assertEqual(len(fake.auto_memory_calls), 1)
+        write = fake.auto_memory_calls[0]
+        self.assertEqual(write["session_id"], "alice-001")
+        written_texts = [_msg_text(m) for m in write["messages"]]
+        self.assertIn("remember I like tea", written_texts)
+        self.assertIn("sure thing", written_texts)
+
+
+# ----------------------------------------------------------------------
+# Both mode — hooks + tools together
+# ----------------------------------------------------------------------
+
+
+class TestBothMode(IsolatedAsyncioTestCase):
+    """Tests for combined static-control and agent-control behavior."""
+
+    async def test_memory_msg_and_tool_hint_both_present(self) -> None:
+        """Both mode should inject memory and expose memory tools."""
+        model = RecordingMockModel(context_size=100_000)
+        fake = _FakeReMeApp(search_return=["auto-injected"])
+        mw = _mw(
+            app=fake,
+            mode="both",
+        )
+        # Echo tool forces a second reasoning step so the background
+        # auto-retrieval injects before the final model call.
+        toolkit = Toolkit(tools=[*await mw.list_tools(), _EchoTool()])
+        model.set_responses(_echo_then_text("ok"))
+        agent = Agent(
+            name="a",
+            system_prompt="base",
+            model=model,
+            toolkit=toolkit,
+            middlewares=[mw],
+        )
+        await agent.reply(UserMsg("user", "hi"))
+
+        # Static hooks ran — one background search (the echo tool call does
+        # not search), one write-back.
+        self.assertEqual(len(fake.search_calls), 1)
+        self.assertEqual(len(fake.auto_memory_calls), 1)
+
+        msgs = model.last_call_messages
+
+        # System prompt has the tool nudge (from on_system_prompt).
+        prompt_text = msgs[0].get_text_content()
+        self.assertIn("Long-term memory", prompt_text)
+        self.assertIn("memory_search", prompt_text)
+
+        # Memory injected as a synthetic HintBlock Msg.
+        memory_msgs = [m for m in msgs if getattr(m, "name", None) == "memory"]
+        self.assertEqual(len(memory_msgs), 1)
+        memory_hints = memory_msgs[0].get_content_blocks("hint")
+        self.assertEqual(len(memory_hints), 1)
+        self.assertIn("auto-injected", memory_hints[0].hint)
+
+        # Search tool exposed (and no add tool — writing is automatic).
+        names = _all_tool_names(toolkit)
+        self.assertIn("memory_search", names)
+        self.assertNotIn("add_memory", names)
diff --git a/tests/resource_access_policy_test.py b/tests/resource_access_policy_test.py
new file mode 100644
index 0000000..cc95783
--- /dev/null
+++ b/tests/resource_access_policy_test.py
@@ -0,0 +1,358 @@
+# -*- coding: utf-8 -*-
+"""Tests for resource access policy primitives."""
+
+from typing import cast
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from fastapi import HTTPException
+from utils import AnyValue
+
+from agentscope.app.access import (
+    DenyAllResourceAccessPolicy,
+    ResourceAccessPolicyBase,
+    ResourceKind,
+    ResourcePermission,
+    ResourceRef,
+)
+from agentscope.app._service import ResourceAccessService
+from agentscope.app.storage import AgentData, AgentRecord, CredentialRecord
+from agentscope.app.storage import StorageBase
+from agentscope.agent import ContextConfig, ReActConfig
+
+
+class _EditPolicy(ResourceAccessPolicyBase):
+    """Test policy that grants edit access to one cross-owner agent."""
+
+    async def list_accessible(
+        self,
+        viewer_id: str,
+        kind: ResourceKind,
+        storage: StorageBase,
+    ) -> list[ResourceRef]:
+        if viewer_id == "viewer" and kind == ResourceKind.AGENT:
+            return [
+                ResourceRef(
+                    kind=ResourceKind.AGENT,
+                    owner_id="owner",
+                    resource_id="agent-1",
+                    permission=ResourcePermission.EDIT,
+                ),
+            ]
+        return []
+
+
+class _SharingPolicy(ResourceAccessPolicyBase):
+    """Test policy that grants read access to shared resources."""
+
+    async def list_accessible(
+        self,
+        viewer_id: str,
+        kind: ResourceKind,
+        storage: StorageBase,
+    ) -> list[ResourceRef]:
+        if viewer_id != "viewer":
+            return []
+        if kind == ResourceKind.AGENT:
+            return [
+                ResourceRef(
+                    kind=ResourceKind.AGENT,
+                    owner_id="owner",
+                    resource_id="agent-1",
+                ),
+                ResourceRef(
+                    kind=ResourceKind.AGENT,
+                    owner_id="owner",
+                    resource_id="team-agent",
+                ),
+            ]
+        if kind == ResourceKind.CREDENTIAL:
+            return [
+                ResourceRef(
+                    kind=ResourceKind.CREDENTIAL,
+                    owner_id="owner",
+                    resource_id="credential-1",
+                ),
+            ]
+        return []
+
+
+class _FakeStorage:
+    """Tiny storage double for resource access tests."""
+
+    def __init__(self) -> None:
+        """Initialize in-memory records."""
+        self.credentials: dict[tuple[str, str], CredentialRecord] = {
+            ("owner", "credential-1"): CredentialRecord(
+                id="credential-1",
+                user_id="owner",
+                data={"type": "test"},
+            ),
+            ("viewer", "credential-own"): CredentialRecord(
+                id="credential-own",
+                user_id="viewer",
+                data={"type": "own"},
+            ),
+        }
+        self.agents: dict[tuple[str, str], AgentRecord] = {
+            ("owner", "agent-1"): AgentRecord(
+                id="agent-1",
+                user_id="owner",
+                data=_make_agent_data("Shared"),
+            ),
+            ("owner", "team-agent"): AgentRecord(
+                id="team-agent",
+                user_id="owner",
+                source="team",
+                data=_make_agent_data("Shared team"),
+            ),
+            ("viewer", "team-agent"): AgentRecord(
+                id="team-agent",
+                user_id="viewer",
+                source="team",
+                data=_make_agent_data("Own team"),
+            ),
+        }
+
+    async def list_credentials(
+        self,
+        user_id: str,
+    ) -> list[CredentialRecord]:
+        """List credentials owned by ``user_id``."""
+        return [
+            record
+            for (owner_id, _), record in self.credentials.items()
+            if owner_id == user_id
+        ]
+
+    async def get_credential(
+        self,
+        user_id: str,
+        credential_id: str,
+    ) -> CredentialRecord | None:
+        """Get a credential."""
+        return self.credentials.get((user_id, credential_id))
+
+    async def list_agents(self, user_id: str) -> list[AgentRecord]:
+        """List agents owned by ``user_id``."""
+        return [
+            record
+            for (owner_id, _), record in self.agents.items()
+            if owner_id == user_id
+        ]
+
+    async def get_agent(
+        self,
+        user_id: str,
+        agent_id: str,
+    ) -> AgentRecord | None:
+        """Get an agent."""
+        return self.agents.get((user_id, agent_id))
+
+
+def _make_agent_data(name: str) -> AgentData:
+    """Create valid agent data for tests."""
+    return AgentData(
+        name=name,
+        system_prompt="You are a helpful assistant.",
+        context_config=ContextConfig(),
+        react_config=ReActConfig(),
+    )
+
+
+class ResourceAccessPolicyTest(IsolatedAsyncioTestCase):
+    """Test resource access policy defaults and edit fallback."""
+
+    async def test_default_policy_denies_cross_owner_access(self) -> None:
+        """The base policy should preserve owner-isolated behavior."""
+        policy = DenyAllResourceAccessPolicy()
+        storage = cast(StorageBase, object())
+
+        result = (
+            await policy.list_accessible(
+                "viewer",
+                ResourceKind.CREDENTIAL,
+                storage,
+            ),
+            await policy.can_edit(
+                "viewer",
+                ResourceKind.CREDENTIAL,
+                "owner",
+                "credential-1",
+                storage,
+            ),
+        )
+
+        self.assertEqual(result, ([], False))
+
+    async def test_owner_can_edit_own_resource(self) -> None:
+        """Owners should not need an explicit policy ref to edit resources."""
+        policy = DenyAllResourceAccessPolicy()
+        storage = cast(StorageBase, object())
+
+        self.assertEqual(
+            await policy.can_edit(
+                "owner",
+                ResourceKind.AGENT,
+                "owner",
+                "agent-1",
+                storage,
+            ),
+            True,
+        )
+
+    async def test_edit_ref_allows_cross_owner_edit(self) -> None:
+        """A matching edit ref should grant cross-owner mutation rights."""
+        policy = _EditPolicy()
+        storage = cast(StorageBase, object())
+
+        result = (
+            await policy.can_edit(
+                "viewer",
+                ResourceKind.AGENT,
+                "owner",
+                "agent-1",
+                storage,
+            ),
+            await policy.can_edit(
+                "viewer",
+                ResourceKind.AGENT,
+                "owner",
+                "agent-2",
+                storage,
+            ),
+        )
+
+        self.assertEqual(result, (True, False))
+
+
+class ResourceAccessServiceTest(IsolatedAsyncioTestCase):
+    """Test resource access service resolution behavior."""
+
+    async def asyncSetUp(self) -> None:
+        """Create the service under test."""
+        self.storage = cast(StorageBase, _FakeStorage())
+        self.service = ResourceAccessService(
+            storage=self.storage,
+            policy=_SharingPolicy(),
+        )
+
+    async def test_get_shared_credential(self) -> None:
+        """Shared credentials should resolve through owner storage."""
+        view = await self.service.get_resource(
+            "viewer",
+            ResourceKind.CREDENTIAL,
+            "credential-1",
+        )
+
+        self.assertEqual(
+            view.model_dump(),
+            {
+                "id": "credential-1",
+                "user_id": "owner",
+                "created_at": AnyValue(),
+                "updated_at": AnyValue(),
+                # Shared credentials must be masked in the view.
+                "data": {"type": "test"},
+                "editable": False,
+            },
+        )
+
+    async def test_resolve_shared_credential_returns_raw(self) -> None:
+        """Runtime resolution should return the unmasked record."""
+        record = await self.service.resolve_credential(
+            "viewer",
+            "credential-1",
+        )
+
+        self.assertEqual(
+            record.model_dump(),
+            {
+                "id": "credential-1",
+                "user_id": "owner",
+                "created_at": AnyValue(),
+                "updated_at": AnyValue(),
+                "data": {"type": "test"},
+            },
+        )
+
+    async def test_list_credentials_includes_own_and_shared(self) -> None:
+        """Credential lists should merge own records and policy refs."""
+        views = await self.service.list_resource(
+            "viewer",
+            ResourceKind.CREDENTIAL,
+        )
+
+        self.assertEqual(
+            [v.model_dump() for v in views],
+            [
+                {
+                    "id": "credential-own",
+                    "user_id": "viewer",
+                    "created_at": AnyValue(),
+                    "updated_at": AnyValue(),
+                    "data": {"type": "own"},
+                    "editable": True,
+                },
+                {
+                    "id": "credential-1",
+                    "user_id": "owner",
+                    "created_at": AnyValue(),
+                    "updated_at": AnyValue(),
+                    # Shared entry has masked data.
+                    "data": {"type": "test"},
+                    "editable": False,
+                },
+            ],
+        )
+
+    async def test_get_own_team_agent_is_allowed(self) -> None:
+        """Runtime owner reads should still resolve team agents."""
+        agent = await self.service.resolve_agent("viewer", "team-agent")
+
+        self.assertEqual(
+            agent.model_dump(),
+            {
+                "id": "team-agent",
+                "user_id": "viewer",
+                "source": "team",
+                "created_at": AnyValue(),
+                "updated_at": AnyValue(),
+                "data": AnyValue(),
+            },
+        )
+
+    async def test_list_agents_skips_shared_team_agents(self) -> None:
+        """Cross-owner team agents should not appear in shared lists."""
+        views = await self.service.list_resource(
+            "viewer",
+            ResourceKind.AGENT,
+        )
+
+        self.assertEqual(
+            [v.model_dump() for v in views],
+            [
+                {
+                    "id": "agent-1",
+                    "user_id": "owner",
+                    "source": "user",
+                    "created_at": AnyValue(),
+                    "updated_at": AnyValue(),
+                    "data": AnyValue(),
+                    "editable": False,
+                },
+            ],
+        )
+
+    async def test_missing_resource_raises_404(self) -> None:
+        """Missing visible resources should raise a 404 HTTPException."""
+        with self.assertRaises(HTTPException) as ctx:
+            await self.service.get_resource(
+                "viewer",
+                ResourceKind.CREDENTIAL,
+                "missing",
+            )
+
+        self.assertEqual(
+            (ctx.exception.status_code, ctx.exception.detail),
+            (404, "Credential 'missing' not found."),
+        )
diff --git a/tests/service_agent_interrupt_test.py b/tests/service_agent_interrupt_test.py
new file mode 100644
index 0000000..6d1ba41
--- /dev/null
+++ b/tests/service_agent_interrupt_test.py
@@ -0,0 +1,171 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=missing-class-docstring,missing-function-docstring
+"""Service-layer integration tests for the agent interruption pipeline.
+
+Covers the plumbing that translates an external interrupt signal into a
+local ``task.cancel()``:
+
+    message bus publish
+        → ``CancelDispatcher`` (background subscriber)
+        → ``ChatRunRegistry`` lookup
+        → ``task.cancel()``
+        → agent exits with ``finished_reason='interrupted'``
+        → the next reply on the same session works normally.
+
+FastAPI is intentionally not started — the HTTP layer is a thin wrapper
+around :meth:`ChatService.interrupt`. This suite validates the
+service-level wiring using :class:`InMemoryMessageBus` so no Redis is
+required.
+"""
+import asyncio
+from typing import Any
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from agentscope.agent import Agent
+from agentscope.app._manager import (
+    CancelDispatcher,
+    ChatRunRegistry,
+    BackgroundTaskManager,
+)
+from agentscope.app.message_bus import InMemoryMessageBus, MessageBusKeys
+from agentscope.event import ReplyEndEvent
+from agentscope.message import (
+    TextBlock,
+    UserMsg,
+)
+from agentscope.model import ChatResponse
+from agentscope.tool import Toolkit
+
+
+class ServiceAgentInterruptTest(IsolatedAsyncioTestCase):
+    """Service-layer interrupt plumbing tests."""
+
+    async def test_full_interrupt_flow(self) -> None:
+        """Complete flow: user message → agent runs → interrupt published
+        → CancelDispatcher cancels task → agent exits with interrupted
+        → next message works.
+        """
+        bus = InMemoryMessageBus()
+        registry = ChatRunRegistry()
+        bg_manager = BackgroundTaskManager(message_bus=bus)
+
+        session_id = "full-e2e-session"
+
+        # ---- Build a model that streams slowly ----
+        class SlowModel:
+            """Streaming model with await points for testing."""
+
+            def __init__(self) -> None:
+                self.model = "slow-e2e"
+                self.stream = True
+                self.max_retries = 0
+                self.context_size = 1000
+
+            async def __call__(
+                self,
+                *_args: Any,
+                **_kwargs: Any,
+            ) -> Any:
+                async def _stream() -> Any:
+                    await asyncio.sleep(0.03)
+                    yield ChatResponse(
+                        content=[TextBlock(text="part1 ")],
+                        is_last=False,
+                    )
+                    await asyncio.sleep(0.03)
+                    yield ChatResponse(
+                        content=[TextBlock(text="part2")],
+                        is_last=False,
+                    )
+                    await asyncio.sleep(0.03)
+                    yield ChatResponse(
+                        content=[TextBlock(text="part1 part2 full")],
+                        is_last=True,
+                    )
+
+                return _stream()
+
+            async def count_tokens(
+                self,
+                *_args: Any,
+                **_kwargs: Any,
+            ) -> int:
+                return 100
+
+        # ---- Agent ----
+        agent = Agent(
+            name="FullE2EAgent",
+            system_prompt="You are a test agent.",
+            model=SlowModel(),
+            toolkit=Toolkit(),
+        )
+
+        # ---- Start agent in background, register in ChatRunRegistry ----
+        finished_reason_1 = None
+
+        async def _chat_run() -> None:
+            nonlocal finished_reason_1
+            async for evt in agent.reply_stream(
+                UserMsg(name="user", content="Hello"),
+            ):
+                if isinstance(evt, ReplyEndEvent):
+                    finished_reason_1 = evt.finished_reason
+
+        registry.spawn(_chat_run(), session_id=session_id)
+
+        # ---- Start CancelDispatcher ----
+        async with bus:
+            async with CancelDispatcher(
+                message_bus=bus,
+                registry=registry,
+                bg_manager=bg_manager,
+            ):
+                # Wait for agent to start streaming
+                await asyncio.sleep(0.04)
+
+                # Step 1: Publish interrupt (simulating API endpoint)
+                await bus.publish(
+                    MessageBusKeys.session_interrupt_channel(),
+                    {"session_id": session_id},
+                )
+
+                # Wait for cancellation to propagate and agent to finish
+                await asyncio.sleep(0.3)
+
+                # Step 2: Verify agent was interrupted
+                self.assertEqual(
+                    finished_reason_1,
+                    "interrupted",
+                    "Full flow: agent should exit with interrupted",
+                )
+
+                # Step 3: Verify chat-run task is done
+                task = registry.get(session_id)
+                self.assertTrue(
+                    task is None or task.done(),
+                    "Chat-run task should be cleaned up after interrupt",
+                )
+
+        # ---- Step 4: Next conversation round should work ----
+        model2 = SlowModel()
+        agent2 = Agent(
+            name="FullE2EAgent-Round2",
+            system_prompt="You are a test agent.",
+            model=model2,
+            toolkit=Toolkit(),
+        )
+        # Copy the interrupted context
+        agent2.state = agent.state
+
+        finished_reason_2 = None
+        async for evt in agent2.reply_stream(
+            UserMsg(name="user", content="Continue please"),
+        ):
+            if isinstance(evt, ReplyEndEvent):
+                finished_reason_2 = evt.finished_reason
+
+        self.assertEqual(
+            finished_reason_2,
+            "completed",
+            "Next round after full-flow interruption should complete normally",
+        )
diff --git a/tests/service_cancel_dispatcher_test.py b/tests/service_cancel_dispatcher_test.py
new file mode 100644
index 0000000..7be20a8
--- /dev/null
+++ b/tests/service_cancel_dispatcher_test.py
@@ -0,0 +1,463 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Tests for :class:`CancelDispatcher` — one-per-process consumer of the
+shared session-cancel broadcast channel.
+
+Verifies that on each incoming ``session_id`` the dispatcher:
+
+- Cancels the chat-run task in :class:`ChatRunRegistry` when it owns one
+  locally.
+- Asks :class:`BackgroundTaskManager` to cancel local BG tasks for the
+  same session.
+- Silently does nothing for sessions whose state lives on other
+  processes.
+"""
+import asyncio
+from contextlib import asynccontextmanager
+from typing import AsyncGenerator, Callable
+from unittest import IsolatedAsyncioTestCase
+
+from agentscope.app._manager import (
+    BackgroundTaskManager,
+    CancelDispatcher,
+    ChatRunRegistry,
+)
+from agentscope.app._manager._background_task_manager import ToolStop
+from agentscope.app.message_bus import MessageBus
+from agentscope.message import ToolResultState
+
+
+class _FakeBus(MessageBus):
+    """In-memory bus with just enough behaviour for the dispatcher.
+
+    Only the cancel-broadcast channel is exercised here; the other
+    primitives are stubbed.
+    """
+
+    def __init__(self) -> None:
+        self._channels: dict[str, asyncio.Queue] = {}
+        self._locks: set[str] = set()
+        self._registries: dict[str, dict[str, str]] = {}
+
+    def _channel(self, key: str) -> asyncio.Queue:
+        return self._channels.setdefault(key, asyncio.Queue())
+
+    # Mode A — queue (unused)
+    async def queue_push(
+        self,
+        key: str,
+        payload: dict,
+        *,
+        ttl_secs: int | None = None,
+    ) -> str:
+        return "n/a"
+
+    async def queue_drain(
+        self,
+        key: str,
+        max_count: int = 100,
+    ) -> list[tuple[str, dict]]:
+        return []
+
+    async def queue_delete(self, key: str) -> None:
+        return None
+
+    # Mode C — log (unused)
+    async def log_append(
+        self,
+        key: str,
+        payload: dict,
+        *,
+        max_len: int | None = None,
+        ttl_secs: int | None = None,
+    ) -> str:
+        return "n/a"
+
+    async def log_read(
+        self,
+        key: str,
+        since: str | None = None,
+        max_count: int = 100,
+    ) -> list[tuple[str, dict]]:
+        return []
+
+    async def log_trim(
+        self,
+        key: str,
+        before_id: str | None = None,
+    ) -> None:
+        return None
+
+    # Mode D — pub/sub
+    async def publish(self, key: str, payload: dict) -> None:
+        await self._channel(key).put(payload)
+
+    async def subscribe(
+        self,
+        key: str,
+        *,
+        on_ready: Callable[[], None] | None = None,
+    ) -> AsyncGenerator[dict, None]:
+        if on_ready is not None:
+            on_ready()
+        while True:
+            yield await self._channel(key).get()
+
+    # Mode E — lock (unused)
+    @asynccontextmanager
+    async def acquire_lock(
+        self,
+        key: str,
+        *,
+        ttl_secs: int = 600,
+    ) -> AsyncGenerator[None, None]:
+        self._locks.add(key)
+        try:
+            yield
+        finally:
+            self._locks.discard(key)
+
+    async def is_locked(self, key: str) -> bool:
+        return key in self._locks
+
+    # Mode F — registry (in-memory dict)
+    async def registry_set(
+        self,
+        namespace: str,
+        field: str,
+        value: str,
+        *,
+        ttl_secs: int | None = None,
+    ) -> None:
+        self._registries.setdefault(namespace, {})[field] = value
+
+    async def registry_del(self, namespace: str, field: str) -> None:
+        if namespace in self._registries:
+            self._registries[namespace].pop(field, None)
+
+    async def registry_exists(self, namespace: str, field: str) -> bool:
+        return field in self._registries.get(namespace, {})
+
+    async def registry_getall(self, namespace: str) -> dict[str, str]:
+        return dict(self._registries.get(namespace, {}))
+
+    async def registry_drop(self, namespace: str) -> None:
+        self._registries.pop(namespace, None)
+
+
+async def _yield_a_few_times(ticks: int = 8) -> None:
+    """Yield the event loop a few times so spawned tasks make progress."""
+    for _ in range(ticks):
+        await asyncio.sleep(0)
+
+
+class _NeverEndingCoro:
+    """Helper: yields a fresh coroutine that sleeps forever."""
+
+    @staticmethod
+    async def run() -> None:
+        """The fake coroutine."""
+        await asyncio.Event().wait()
+
+
+class TestCancelDispatcher(IsolatedAsyncioTestCase):
+    """Verifies the cross-process cancel fan-out."""
+
+    async def test_cancel_signal_cancels_local_chat_run(self) -> None:
+        """Broadcast for a session whose chat run is registered locally
+        cancels the registered asyncio task."""
+        bus = _FakeBus()
+        registry = ChatRunRegistry()
+        bg_manager = BackgroundTaskManager(message_bus=bus)
+
+        async with bg_manager, registry, CancelDispatcher(
+            message_bus=bus,
+            registry=registry,
+            bg_manager=bg_manager,
+        ):
+            chat_task = registry.spawn(
+                _NeverEndingCoro.run(),
+                session_id="sess-A",
+            )
+            await bus.session_publish_cancel("sess-A")
+
+            # Wait until the cancel actually propagates.
+            for _ in range(50):
+                if chat_task.cancelled() or chat_task.done():
+                    break
+                await asyncio.sleep(0.01)
+
+        self.assertTrue(chat_task.cancelled() or chat_task.done())
+
+    async def test_cancel_signal_cancels_local_bg_tasks(self) -> None:
+        """Broadcast for a session with locally-registered BG tasks
+        cancels each of them; tasks for other sessions are untouched."""
+        bus = _FakeBus()
+        registry = ChatRunRegistry()
+        bg_manager = BackgroundTaskManager(message_bus=bus)
+
+        async with bg_manager, registry, CancelDispatcher(
+            message_bus=bus,
+            registry=registry,
+            bg_manager=bg_manager,
+        ):
+            bg_task_a1 = asyncio.create_task(_NeverEndingCoro.run())
+            bg_task_a2 = asyncio.create_task(_NeverEndingCoro.run())
+            bg_task_b = asyncio.create_task(_NeverEndingCoro.run())
+
+            await bg_manager.register_task(
+                bg_task_a1,
+                session_id="sess-A",
+                agent_id="agent-A",
+                user_id="u",
+            )
+            await bg_manager.register_task(
+                bg_task_a2,
+                session_id="sess-A",
+                agent_id="agent-A",
+                user_id="u",
+            )
+            await bg_manager.register_task(
+                bg_task_b,
+                session_id="sess-B",
+                agent_id="agent-B",
+                user_id="u",
+            )
+
+            await bus.session_publish_cancel("sess-A")
+
+            for _ in range(50):
+                if bg_task_a1.cancelled() and bg_task_a2.cancelled():
+                    break
+                await asyncio.sleep(0.01)
+
+        self.assertTrue(bg_task_a1.cancelled() or bg_task_a1.done())
+        self.assertTrue(bg_task_a2.cancelled() or bg_task_a2.done())
+        # sess-B BG task is left running until shutdown cancels it.
+        self.assertFalse(bg_task_b.cancelled())
+        bg_task_b.cancel()
+
+    async def test_cancel_signal_for_remote_session_is_noop(self) -> None:
+        """Broadcast for a session held on another process is silently
+        ignored — no exception, no spurious cancel."""
+        bus = _FakeBus()
+        registry = ChatRunRegistry()
+        bg_manager = BackgroundTaskManager(message_bus=bus)
+
+        async with bg_manager, registry, CancelDispatcher(
+            message_bus=bus,
+            registry=registry,
+            bg_manager=bg_manager,
+        ):
+            # Register an unrelated chat run + unrelated BG task so we
+            # can verify the unrelated work survives the broadcast.
+            unrelated_chat = registry.spawn(
+                _NeverEndingCoro.run(),
+                session_id="other",
+            )
+            unrelated_bg = asyncio.create_task(_NeverEndingCoro.run())
+            await bg_manager.register_task(
+                unrelated_bg,
+                session_id="other",
+                agent_id="agent",
+                user_id="u",
+            )
+
+            await bus.session_publish_cancel("not-on-this-process")
+            await _yield_a_few_times()
+
+            self.assertFalse(unrelated_chat.cancelled())
+            self.assertFalse(unrelated_bg.cancelled())
+
+        # __aexit__ of ChatRunRegistry + BackgroundTaskManager cancels
+        # the unrelated tasks on shutdown.
+
+    async def test_cancel_fans_out_to_both_chat_and_bg_in_one_signal(
+        self,
+    ) -> None:
+        """A single cancel broadcast cancels both the local chat run
+        and the local BG task(s) for the session, not just one."""
+        bus = _FakeBus()
+        registry = ChatRunRegistry()
+        bg_manager = BackgroundTaskManager(message_bus=bus)
+
+        async with bg_manager, registry, CancelDispatcher(
+            message_bus=bus,
+            registry=registry,
+            bg_manager=bg_manager,
+        ):
+            chat_task = registry.spawn(
+                _NeverEndingCoro.run(),
+                session_id="sess-X",
+            )
+            bg_task = asyncio.create_task(_NeverEndingCoro.run())
+            await bg_manager.register_task(
+                bg_task,
+                session_id="sess-X",
+                agent_id="agent-X",
+                user_id="u",
+            )
+
+            await bus.session_publish_cancel("sess-X")
+
+            for _ in range(50):
+                if chat_task.cancelled() and bg_task.cancelled():
+                    break
+                await asyncio.sleep(0.01)
+
+        self.assertTrue(chat_task.cancelled() or chat_task.done())
+        self.assertTrue(bg_task.cancelled() or bg_task.done())
+
+
+class TestBackgroundTaskManagerCancelSessionTasks(IsolatedAsyncioTestCase):
+    """Verifies :meth:`BackgroundTaskManager.cancel_session_tasks`."""
+
+    async def test_cancels_only_matching_session(self) -> None:
+        """Only tasks whose ``session_id`` matches are cancelled; the
+        return value reports the local count."""
+        bg_manager = BackgroundTaskManager(message_bus=_FakeBus())
+        async with bg_manager:
+            task_a = asyncio.create_task(_NeverEndingCoro.run())
+            task_b = asyncio.create_task(_NeverEndingCoro.run())
+            await bg_manager.register_task(
+                task_a,
+                session_id="match",
+                agent_id="a",
+                user_id="u",
+            )
+            await bg_manager.register_task(
+                task_b,
+                session_id="other",
+                agent_id="b",
+                user_id="u",
+            )
+
+            count = bg_manager.cancel_session_tasks("match")
+            self.assertEqual(count, 1)
+
+            for _ in range(50):
+                if task_a.cancelled():
+                    break
+                await asyncio.sleep(0.01)
+
+            self.assertTrue(task_a.cancelled())
+            self.assertFalse(task_b.cancelled())
+
+    async def test_no_matches_returns_zero(self) -> None:
+        """A session with no locally-registered tasks returns 0 and
+        does no work."""
+        bg_manager = BackgroundTaskManager(message_bus=_FakeBus())
+        async with bg_manager:
+            task = asyncio.create_task(_NeverEndingCoro.run())
+            await bg_manager.register_task(
+                task,
+                session_id="other",
+                agent_id="a",
+                user_id="u",
+            )
+
+            self.assertEqual(
+                bg_manager.cancel_session_tasks("ghost"),
+                0,
+            )
+            self.assertFalse(task.cancelled())
+
+
+class TestToolStopRemoteCancel(IsolatedAsyncioTestCase):
+    """Verifies the cross-worker cancel path of :class:`ToolStop`.
+
+    A "worker A" registers a BG task in the shared bus registry, and a
+    "worker B" — which has the task only in the global registry, not in
+    its local cache — issues ``ToolStop``. The dispatcher on worker A
+    must receive the broadcast and cancel the task locally.
+    """
+
+    async def test_remote_cancel_via_toolstop_broadcast(self) -> None:
+        """ToolStop on a worker without the task publishes a task-level
+        cancel; the owning worker's CancelDispatcher cancels the task."""
+        bus = _FakeBus()
+
+        # Worker A — owns the task and runs CancelDispatcher.
+        bg_manager_owner = BackgroundTaskManager(message_bus=bus)
+        registry_owner = ChatRunRegistry()
+
+        # Worker B — only sees the task via the shared registry.
+        bg_manager_caller = BackgroundTaskManager(message_bus=bus)
+
+        async with bg_manager_owner, registry_owner, CancelDispatcher(
+            message_bus=bus,
+            registry=registry_owner,
+            bg_manager=bg_manager_owner,
+        ), bg_manager_caller:
+            owned_task = asyncio.create_task(_NeverEndingCoro.run())
+            task_id = await bg_manager_owner.register_task(
+                owned_task,
+                session_id="sess-shared",
+                agent_id="agent",
+                user_id="u",
+                tool_name="LongRunningTool",
+            )
+
+            # Worker B's ToolStop: task_id is in the global registry but
+            # not in worker B's local cache, so the remote-cancel path
+            # is taken.
+            tool_stop = ToolStop(
+                background_tasks=bg_manager_caller.tasks,
+                message_bus=bus,
+                session_id="sess-shared",
+            )
+            chunk = await tool_stop(task_id=task_id)
+
+            self.assertEqual(chunk.state, ToolResultState.SUCCESS)
+            self.assertIn(
+                "Cancel request sent",
+                chunk.content[0].text,
+            )
+
+            for _ in range(50):
+                if owned_task.cancelled() or owned_task.done():
+                    break
+                await asyncio.sleep(0.01)
+
+            self.assertTrue(owned_task.cancelled() or owned_task.done())
+
+    async def test_toolstop_does_not_cancel_other_session_locally(
+        self,
+    ) -> None:
+        """A ToolStop instance bound to session A must not cancel a
+        locally-tracked task that belongs to session B, even if the
+        guessed task_id is correct."""
+        bus = _FakeBus()
+        bg_manager = BackgroundTaskManager(message_bus=bus)
+
+        async with bg_manager:
+            victim_task = asyncio.create_task(_NeverEndingCoro.run())
+            victim_task_id = await bg_manager.register_task(
+                victim_task,
+                session_id="sess-victim",
+                agent_id="agent-v",
+                user_id="u",
+            )
+
+            # ToolStop is bound to a *different* session; it should not
+            # cancel ``victim_task`` directly. The shared registry is
+            # also keyed by the bound session id, so the lookup misses
+            # and we fall through to "not found".
+            tool_stop = ToolStop(
+                background_tasks=bg_manager.tasks,
+                message_bus=bus,
+                session_id="sess-attacker",
+            )
+            chunk = await tool_stop(task_id=victim_task_id)
+
+            await _yield_a_few_times()
+
+            self.assertEqual(chunk.state, ToolResultState.ERROR)
+            self.assertIn(
+                "TaskNotFoundError",
+                chunk.content[0].text,
+            )
+            self.assertFalse(victim_task.cancelled())
+            self.assertIn(victim_task_id, bg_manager.tasks)
+
+            victim_task.cancel()
diff --git a/tests/service_enqueue_index_task_test.py b/tests/service_enqueue_index_task_test.py
new file mode 100644
index 0000000..1d495c4
--- /dev/null
+++ b/tests/service_enqueue_index_task_test.py
@@ -0,0 +1,154 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Tests for :func:`agentscope.app._bus_ops.enqueue_index_task`.
+
+The helper is a three-line composition over two bus primitives —
+``queue_push`` and ``publish`` — so the tests verify only that:
+
+- the queued payload carries the three fields the
+  :class:`~agentscope.app._service.IndexTaskConsumer` reads;
+- a signal is published exactly once per call;
+- both primitives reach the production
+  :class:`~agentscope.app.message_bus.RedisMessageBus` backend
+  (proxied by ``fakeredis``), not just an in-memory mock — keeping
+  the test honest against the wire-level contract the worker side
+  relies on.
+
+If a future change adds metadata to the payload, this test is the
+contract gate: callers are expected to keep ``user_id`` /
+``knowledge_base_id`` / ``document_id`` as the primary keys.
+"""
+import asyncio
+from contextlib import AsyncExitStack
+from unittest import IsolatedAsyncioTestCase
+
+import fakeredis.aioredis
+
+from agentscope.app._bus_ops import enqueue_index_task
+from agentscope.app.message_bus import MessageBusKeys, RedisMessageBus
+
+
+def _make_bus(fr: fakeredis.aioredis.FakeRedis) -> RedisMessageBus:
+    """Construct a :class:`RedisMessageBus` bound to *fr*.
+
+    Args:
+        fr (`fakeredis.aioredis.FakeRedis`):
+            The fake Redis client to inject into the bus.
+
+    Returns:
+        `RedisMessageBus`:
+            A bus subclass whose ``__aenter__`` skips the real
+            connection setup and binds *fr* as the client.
+    """
+
+    class _B(RedisMessageBus):
+        """Test-only bus that reuses the supplied fakeredis client."""
+
+        async def __aenter__(
+            self,
+        ) -> "RedisMessageBus":  # type: ignore[override]
+            """Bind the pre-supplied fakeredis client and return self.
+
+            Returns:
+                `RedisMessageBus`:
+                    This bus, ready for the with-block body.
+            """
+            self._client = fr
+            return self
+
+        async def aclose(self) -> None:
+            """Drop the client reference without touching the network."""
+            self._client = None
+
+    return _B()
+
+
+class TestEnqueueIndexTask(IsolatedAsyncioTestCase):
+    """Verifies the queue_push + publish composition."""
+
+    async def asyncSetUp(self) -> None:
+        """Wire a fakeredis-backed bus into an async exit stack."""
+        self.fr = fakeredis.aioredis.FakeRedis(decode_responses=True)
+        self._stack = AsyncExitStack()
+        self.bus = await self._stack.enter_async_context(_make_bus(self.fr))
+
+    async def asyncTearDown(self) -> None:
+        """Tear the exit stack and the fakeredis client down."""
+        await self._stack.aclose()
+        await self.fr.aclose()
+
+    async def test_enqueue_pushes_payload_and_publishes_signal(
+        self,
+    ) -> None:
+        """One enqueue puts one structured entry on the durable queue
+        and one opaque payload on the signal channel.
+
+        Order matters: the queue push must precede the publish so a
+        worker woken by the signal is guaranteed to find the entry
+        when it drains. We do not assert order directly (would
+        require instrumenting the bus), but we assert both primitives
+        landed.
+        """
+        ready = asyncio.Event()
+        received: list[dict] = []
+
+        async def _signal_consumer() -> None:
+            """Consume one signal payload and exit."""
+            async for payload in self.bus.subscribe(
+                MessageBusKeys.index_tasks_signal(),
+                on_ready=ready.set,
+            ):
+                received.append(payload)
+                break
+
+        task = asyncio.create_task(_signal_consumer())
+        await asyncio.wait_for(ready.wait(), timeout=2.0)
+
+        await enqueue_index_task(
+            self.bus,
+            user_id="u",
+            knowledge_base_id="kb",
+            document_id="doc",
+        )
+        await asyncio.wait_for(task, timeout=2.0)
+
+        # Signal was published.
+        self.assertEqual(len(received), 1)
+
+        # Queue holds the structured entry under the well-known key.
+        entries = await self.bus.queue_drain(
+            MessageBusKeys.index_tasks_queue(),
+            max_count=10,
+        )
+        self.assertEqual(len(entries), 1)
+        _entry_id, payload = entries[0]
+        self.assertEqual(
+            payload,
+            {
+                "user_id": "u",
+                "knowledge_base_id": "kb",
+                "document_id": "doc",
+            },
+        )
+
+    async def test_double_enqueue_queues_twice(self) -> None:
+        """Two enqueues for the same document leave two entries on
+        the queue — the helper is intentionally not deduplicating,
+        the worker's lease CAS is the dedup contract."""
+        await enqueue_index_task(
+            self.bus,
+            user_id="u",
+            knowledge_base_id="kb",
+            document_id="doc",
+        )
+        await enqueue_index_task(
+            self.bus,
+            user_id="u",
+            knowledge_base_id="kb",
+            document_id="doc",
+        )
+        entries = await self.bus.queue_drain(
+            MessageBusKeys.index_tasks_queue(),
+            max_count=10,
+        )
+        self.assertEqual(len(entries), 2)
diff --git a/tests/service_inbox_middleware_test.py b/tests/service_inbox_middleware_test.py
new file mode 100644
index 0000000..93833da
--- /dev/null
+++ b/tests/service_inbox_middleware_test.py
@@ -0,0 +1,477 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=abstract-method,protected-access
+"""Tests for :class:`InboxMiddleware`.
+
+Every cross-session message delivery in the framework (team messages
+via ``TeamSay`` / ``AgentCreate``, background-tool completion results,
+scheduler fires) goes through this middleware on the consumer side, so
+the four branches below cover the whole inbox→context pipeline:
+
+- empty inbox → no injection, no event yield, downstream unchanged;
+- last context msg already an assistant msg from this agent → hints are
+  *extended* into its ``content``;
+- last context msg is something else (system / different agent) → a
+  fresh ``AssistantMsg`` is appended;
+- empty context → a fresh ``AssistantMsg`` is appended.
+
+Each non-empty drain must also yield one ``HintBlockEvent`` per hint so
+the SSE stream renders them.
+"""
+import uuid
+from contextlib import asynccontextmanager
+from types import SimpleNamespace
+from typing import Any, AsyncGenerator, Callable
+from unittest import IsolatedAsyncioTestCase
+
+from utils import AnyString
+
+from agentscope.app.message_bus import MessageBus
+from agentscope.app.middleware import InboxMiddleware
+from agentscope.message import (
+    AssistantMsg,
+    HintBlock,
+    SystemMsg,
+    TextBlock,
+)
+
+
+class _FakeBus(MessageBus):
+    """In-memory bus that only implements the inbox API needed by
+    :class:`InboxMiddleware`. All other primitives raise ``NotImplemented``
+    to make accidental dependencies obvious."""
+
+    def __init__(self) -> None:
+        self._queues: dict[str, list[tuple[str, dict]]] = {}
+        self._next_id = 0
+
+    def _alloc_id(self) -> str:
+        """Allocate a monotonically increasing entry id."""
+        self._next_id += 1
+        return f"id-{self._next_id}"
+
+    # Mode A — drain queue
+    async def queue_push(
+        self,
+        key: str,
+        payload: dict,
+        *,
+        ttl_secs: int | None = None,
+    ) -> str:
+        entry_id = self._alloc_id()
+        self._queues.setdefault(key, []).append((entry_id, payload))
+        return entry_id
+
+    async def queue_drain(
+        self,
+        key: str,
+        *,
+        max_count: int,
+    ) -> list[tuple[str, dict]]:
+        entries = self._queues.get(key, [])[:max_count]
+        self._queues[key] = self._queues.get(key, [])[max_count:]
+        return entries
+
+    async def queue_delete(self, key: str) -> None:
+        self._queues.pop(key, None)
+
+    # Mode C — log (unused)
+    async def log_append(
+        self,
+        key: str,
+        payload: dict,
+        *,
+        max_len: int | None = None,
+        ttl_secs: int | None = None,
+    ) -> str:
+        raise NotImplementedError
+
+    async def log_read(
+        self,
+        key: str,
+        since: str | None = None,
+        max_count: int = 100,
+    ) -> list[tuple[str, dict]]:
+        raise NotImplementedError
+
+    async def log_trim(
+        self,
+        key: str,
+        before_id: str | None = None,
+    ) -> None:
+        raise NotImplementedError
+
+    # Mode D — pub/sub (unused)
+    async def publish(self, key: str, payload: dict) -> None:
+        raise NotImplementedError
+
+    async def subscribe(
+        self,
+        key: str,
+        *,
+        on_ready: Callable[[], None] | None = None,
+    ) -> AsyncGenerator[dict, None]:
+        raise NotImplementedError
+        yield  # pragma: no cover  # pylint: disable=unreachable
+
+    # Mode E — lock (unused)
+    @asynccontextmanager
+    async def acquire_lock(
+        self,
+        key: str,
+        *,
+        ttl_secs: int = 600,
+    ) -> AsyncGenerator[None, None]:
+        raise NotImplementedError
+        yield  # pragma: no cover  # pylint: disable=unreachable
+
+    async def is_locked(self, key: str) -> bool:
+        raise NotImplementedError
+
+    # Mode F — registry (unused)
+    async def registry_set(
+        self,
+        namespace: str,
+        field: str,
+        value: str,
+        *,
+        ttl_secs: int | None = None,
+    ) -> None:
+        raise NotImplementedError
+
+    async def registry_del(self, namespace: str, field: str) -> None:
+        raise NotImplementedError
+
+    async def registry_exists(self, namespace: str, field: str) -> bool:
+        raise NotImplementedError
+
+    async def registry_getall(self, namespace: str) -> dict[str, str]:
+        raise NotImplementedError
+
+    async def registry_drop(self, namespace: str) -> None:
+        raise NotImplementedError
+
+
+def _make_agent(
+    *,
+    name: str,
+    session_id: str,
+    reply_id: str,
+    context: list,
+) -> Any:
+    """Build the smallest object that satisfies what
+    :class:`InboxMiddleware.on_reasoning` reads off ``agent``.
+
+    Args:
+        name: Agent display name.
+        session_id: Identifier for the inbox key.
+        reply_id: Reply id stamped onto freshly-appended AssistantMsg.
+        context: Mutable list of messages — the middleware mutates this
+            in place to inject hints.
+
+    Returns:
+        A ``SimpleNamespace`` shaped like the real :class:`Agent` for
+        the fields the middleware touches.
+    """
+    return SimpleNamespace(
+        name=name,
+        state=SimpleNamespace(
+            session_id=session_id,
+            reply_id=reply_id,
+            context=context,
+        ),
+    )
+
+
+async def _noop_next_handler(**_kwargs: Any) -> AsyncGenerator:
+    """Stand-in for the downstream reasoning chain. Yields nothing —
+    InboxMiddleware should run its inbox-drain step first, then exit
+    the iteration cleanly."""
+    return
+    yield  # pragma: no cover  # pylint: disable=unreachable
+
+
+async def _drain(gen: AsyncGenerator) -> list:
+    """Collect every value yielded by an async generator."""
+    out: list = []
+    async for item in gen:
+        out.append(item)
+    return out
+
+
+def _push_hint(
+    bus: _FakeBus,
+    sid: str,
+    hint: HintBlock,
+) -> None:
+    """Push a :class:`HintBlock` into the per-session inbox key the
+    middleware will drain."""
+    key = MessageBus._INBOX_KEY.format(sid=sid)
+    # asyncio.run on the bus would be overkill — `_queues` is a plain
+    # dict, mutate it directly.
+    bus._queues.setdefault(key, []).append(
+        (bus._alloc_id(), hint.model_dump(mode="json")),
+    )
+
+
+class TestInboxMiddlewareEmptyInbox(IsolatedAsyncioTestCase):
+    """When the inbox is empty, ``on_reasoning`` injects nothing, yields
+    nothing, and delegates straight to ``next_handler``."""
+
+    async def test_empty_inbox_is_noop(self) -> None:
+        """An empty inbox produces no events and leaves context untouched."""
+        bus = _FakeBus()
+        agent = _make_agent(
+            name="A",
+            session_id="s",
+            reply_id=uuid.uuid4().hex,
+            context=[],
+        )
+        mw = InboxMiddleware(bus)
+
+        out = await _drain(
+            mw.on_reasoning(agent, {}, _noop_next_handler),
+        )
+
+        self.assertEqual(out, [])
+        self.assertEqual(agent.state.context, [])
+
+
+class TestInboxMiddlewareInjection(IsolatedAsyncioTestCase):
+    """Branch coverage for the three injection cases."""
+
+    async def test_extends_into_last_assistant_msg_from_same_agent(
+        self,
+    ) -> None:
+        """When the last context msg is already an assistant msg from
+        this agent, hints are extended into its ``content`` and a new
+        msg is NOT appended."""
+        bus = _FakeBus()
+        existing = AssistantMsg(
+            name="A",
+            content=[TextBlock(text="hello")],
+        )
+        agent = _make_agent(
+            name="A",
+            session_id="s",
+            reply_id=uuid.uuid4().hex,
+            context=[existing],
+        )
+        hint = HintBlock(hint="poke", source="tester")
+        _push_hint(bus, "s", hint)
+        mw = InboxMiddleware(bus)
+
+        events = await _drain(
+            mw.on_reasoning(agent, {}, _noop_next_handler),
+        )
+
+        # No new message appended; hint extended into existing assistant msg.
+        self.assertEqual(len(agent.state.context), 1)
+        self.assertIs(agent.state.context[0], existing)
+        self.assertDictEqual(
+            existing.model_dump(),
+            {
+                "id": AnyString(),
+                "name": "A",
+                "role": "assistant",
+                "content": [
+                    {"type": "text", "text": "hello", "id": AnyString()},
+                    {
+                        "type": "hint",
+                        "hint": "poke",
+                        "id": hint.id,
+                        "source": "tester",
+                    },
+                ],
+                "metadata": {},
+                "created_at": AnyString(),
+                "finished_at": None,
+                "usage": None,
+            },
+        )
+        # One HintBlockEvent yielded.
+        self.assertEqual(
+            [e.model_dump(mode="json") for e in events],
+            [
+                {
+                    "type": "HINT_BLOCK",
+                    "id": AnyString(),
+                    "created_at": AnyString(),
+                    "metadata": {},
+                    "reply_id": agent.state.reply_id,
+                    "block_id": hint.id,
+                    "source": "tester",
+                    "hint": "poke",
+                },
+            ],
+        )
+
+    async def test_appends_new_msg_when_last_is_different_agent(
+        self,
+    ) -> None:
+        """When the last context msg is from a different agent (or a
+        system msg), a fresh :class:`AssistantMsg` is appended with the
+        hints as its content."""
+        bus = _FakeBus()
+        system_msg = SystemMsg(name="system", content="boot")
+        agent = _make_agent(
+            name="A",
+            session_id="s",
+            reply_id="rid-1",
+            context=[system_msg],
+        )
+        hint = HintBlock(hint="hi", source="x")
+        _push_hint(bus, "s", hint)
+        mw = InboxMiddleware(bus)
+
+        await _drain(mw.on_reasoning(agent, {}, _noop_next_handler))
+
+        self.assertEqual(len(agent.state.context), 2)
+        self.assertDictEqual(
+            agent.state.context[-1].model_dump(),
+            {
+                "id": "rid-1",
+                "name": "A",
+                "role": "assistant",
+                "content": [
+                    {
+                        "type": "hint",
+                        "hint": "hi",
+                        "id": hint.id,
+                        "source": "x",
+                    },
+                ],
+                "metadata": {},
+                "created_at": AnyString(),
+                "finished_at": None,
+                "usage": None,
+            },
+        )
+
+    async def test_appends_new_msg_when_context_empty(self) -> None:
+        """When ``agent.state.context`` is empty, a fresh
+        :class:`AssistantMsg` containing the hints is the first entry."""
+        bus = _FakeBus()
+        agent = _make_agent(
+            name="A",
+            session_id="s",
+            reply_id="rid-empty",
+            context=[],
+        )
+        hint = HintBlock(hint="hi", source="x")
+        _push_hint(bus, "s", hint)
+        mw = InboxMiddleware(bus)
+
+        await _drain(mw.on_reasoning(agent, {}, _noop_next_handler))
+
+        self.assertEqual(len(agent.state.context), 1)
+        self.assertDictEqual(
+            agent.state.context[0].model_dump(),
+            {
+                "id": "rid-empty",
+                "name": "A",
+                "role": "assistant",
+                "content": [
+                    {
+                        "type": "hint",
+                        "hint": "hi",
+                        "id": hint.id,
+                        "source": "x",
+                    },
+                ],
+                "metadata": {},
+                "created_at": AnyString(),
+                "finished_at": None,
+                "usage": None,
+            },
+        )
+
+
+class TestInboxMiddlewareYieldsHintBlockEvents(IsolatedAsyncioTestCase):
+    """One ``HintBlockEvent`` is yielded per injected hint, in order,
+    each carrying the hint's own block_id / source / content."""
+
+    async def test_event_count_and_payload(self) -> None:
+        """One HintBlockEvent is yielded per inbox hint, in arrival order."""
+        bus = _FakeBus()
+        agent = _make_agent(
+            name="A",
+            session_id="s",
+            reply_id="rid-evt",
+            context=[],
+        )
+        h1 = HintBlock(hint="a", source="alice")
+        h2 = HintBlock(hint="b", source="bob")
+        _push_hint(bus, "s", h1)
+        _push_hint(bus, "s", h2)
+        mw = InboxMiddleware(bus)
+
+        events = await _drain(
+            mw.on_reasoning(agent, {}, _noop_next_handler),
+        )
+
+        self.assertEqual(
+            [e.model_dump(mode="json") for e in events],
+            [
+                {
+                    "type": "HINT_BLOCK",
+                    "id": AnyString(),
+                    "created_at": AnyString(),
+                    "metadata": {},
+                    "reply_id": "rid-evt",
+                    "block_id": h1.id,
+                    "source": "alice",
+                    "hint": "a",
+                },
+                {
+                    "type": "HINT_BLOCK",
+                    "id": AnyString(),
+                    "created_at": AnyString(),
+                    "metadata": {},
+                    "reply_id": "rid-evt",
+                    "block_id": h2.id,
+                    "source": "bob",
+                    "hint": "b",
+                },
+            ],
+        )
+
+
+class TestInboxMiddlewareDelegatesDownstream(IsolatedAsyncioTestCase):
+    """After the inbox is drained, events from ``next_handler`` come
+    out of the middleware in order."""
+
+    async def test_downstream_events_pass_through(self) -> None:
+        """Downstream events appear after any HintBlockEvents."""
+        bus = _FakeBus()
+        agent = _make_agent(
+            name="A",
+            session_id="s",
+            reply_id="rid",
+            context=[],
+        )
+        hint = HintBlock(hint="hi", source="x")
+        _push_hint(bus, "s", hint)
+        mw = InboxMiddleware(bus)
+
+        async def downstream(**_k: Any) -> AsyncGenerator[str, None]:
+            yield "ds-1"
+            yield "ds-2"
+
+        out = await _drain(mw.on_reasoning(agent, {}, downstream))
+
+        # 1 HintBlockEvent followed by 2 downstream items.
+        self.assertEqual(len(out), 3)
+        self.assertDictEqual(
+            out[0].model_dump(mode="json"),
+            {
+                "type": "HINT_BLOCK",
+                "id": AnyString(),
+                "created_at": AnyString(),
+                "metadata": {},
+                "reply_id": "rid",
+                "block_id": hint.id,
+                "source": "x",
+                "hint": "hi",
+            },
+        )
+        self.assertEqual(out[1:], ["ds-1", "ds-2"])
diff --git a/tests/service_index_task_consumer_test.py b/tests/service_index_task_consumer_test.py
new file mode 100644
index 0000000..839d2eb
--- /dev/null
+++ b/tests/service_index_task_consumer_test.py
@@ -0,0 +1,399 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Tests for :class:`IndexTaskConsumer` — the worker-process side of
+the message-bus index dispatch flow.
+
+Verifies the four behaviours callers rely on:
+
+- Lifecycle is purely ACM: ``__aenter__`` starts the loop and performs
+  an initial drain; ``__aexit__`` cancels the loop and any in-flight
+  ``worker.process`` task cleanly.
+- A signal triggers a queue drain; each entry is dispatched as a
+  ``worker.process`` call.
+- Entries left on the queue from before ``__aenter__`` are picked up
+  on the initial drain without waiting for a fresh signal.
+- Malformed entries are logged and skipped, not raised; later valid
+  entries still dispatch.
+- An exception inside ``worker.process`` is logged but does not crash
+  the consumer loop — subsequent signals still drain.
+
+Mirrors :mod:`service_wakeup_dispatcher_test` deliberately; the
+flows are identical at the primitive level.
+"""
+import asyncio
+from contextlib import asynccontextmanager
+from typing import AsyncGenerator, Callable
+from unittest import IsolatedAsyncioTestCase
+
+from agentscope.app._service import IndexTaskConsumer
+from agentscope.app.message_bus import MessageBus, MessageBusKeys
+
+
+class _FakeBus(MessageBus):
+    """In-memory bus with just enough behaviour for the consumer.
+
+    Implements the primitives the consumer actually uses
+    (``queue_push`` / ``queue_drain`` / ``subscribe`` / ``publish``)
+    and stubs the others. The consumer reaches for the bus through
+    the well-known channel/key constants — no domain methods exist
+    on the bus.
+    """
+
+    def __init__(self) -> None:
+        self.queues: dict[str, list[tuple[str, dict]]] = {}
+        self._channels: dict[str, asyncio.Queue] = {}
+        self._next = 0
+        self._locks: set[str] = set()
+
+    def _channel(self, key: str) -> asyncio.Queue:
+        return self._channels.setdefault(key, asyncio.Queue())
+
+    # Mode A — queue
+    async def queue_push(
+        self,
+        key: str,
+        payload: dict,
+        *,
+        ttl_secs: int | None = None,
+    ) -> str:
+        self._next += 1
+        entry_id = str(self._next)
+        self.queues.setdefault(key, []).append((entry_id, payload))
+        return entry_id
+
+    async def queue_drain(
+        self,
+        key: str,
+        *,
+        max_count: int,
+    ) -> list[tuple[str, dict]]:
+        entries = self.queues.get(key, [])[:max_count]
+        self.queues[key] = self.queues.get(key, [])[max_count:]
+        return entries
+
+    async def queue_delete(self, key: str) -> None:
+        self.queues.pop(key, None)
+
+    # Mode C — log (unused)
+    async def log_append(
+        self,
+        key: str,
+        payload: dict,
+        *,
+        max_len: int | None = None,
+        ttl_secs: int | None = None,
+    ) -> str:
+        return "n/a"
+
+    async def log_read(
+        self,
+        key: str,
+        since: str | None = None,
+        max_count: int = 100,
+    ) -> list[tuple[str, dict]]:
+        return []
+
+    async def log_trim(
+        self,
+        key: str,
+        before_id: str | None = None,
+    ) -> None:
+        return None
+
+    # Mode D — pub/sub
+    async def publish(self, key: str, payload: dict) -> None:
+        await self._channel(key).put(payload)
+
+    async def subscribe(
+        self,
+        key: str,
+        *,
+        on_ready: Callable[[], None] | None = None,
+    ) -> AsyncGenerator[dict, None]:
+        if on_ready is not None:
+            on_ready()
+        while True:
+            yield await self._channel(key).get()
+
+    # Mode E — lock
+    @asynccontextmanager
+    async def acquire_lock(
+        self,
+        key: str,
+        *,
+        ttl_secs: int = 600,
+    ) -> AsyncGenerator[None, None]:
+        self._locks.add(key)
+        try:
+            yield
+        finally:
+            self._locks.discard(key)
+
+    async def is_locked(self, key: str) -> bool:
+        return key in self._locks
+
+    # Mode F — registry (unused by IndexTaskConsumer; raise so any
+    # accidental dependency surfaces immediately rather than silently
+    # passing through a stub).
+    async def registry_set(
+        self,
+        namespace: str,
+        field: str,
+        value: str,
+        *,
+        ttl_secs: int | None = None,
+    ) -> None:
+        raise NotImplementedError
+
+    async def registry_del(self, namespace: str, field: str) -> None:
+        raise NotImplementedError
+
+    async def registry_exists(self, namespace: str, field: str) -> bool:
+        raise NotImplementedError
+
+    async def registry_getall(self, namespace: str) -> dict[str, str]:
+        raise NotImplementedError
+
+    async def registry_drop(self, namespace: str) -> None:
+        raise NotImplementedError
+
+
+class _RecordingWorker:
+    """Records calls to :meth:`process` so tests can assert dispatch.
+
+    The real ``IndexWorker`` has many more methods, but the consumer
+    only ever invokes :meth:`process` — so the test surface stays
+    narrow on purpose.
+    """
+
+    def __init__(self) -> None:
+        self.calls: list[dict] = []
+        self.notify = asyncio.Event()
+        self.fail_on_doc: str | None = None
+        self.process_delay = 0.0
+
+    async def process(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+        document_id: str,
+    ) -> None:
+        """Record the call and signal the test, optionally failing or
+        sleeping first to exercise the consumer's error and timing
+        paths.
+
+        Args:
+            user_id (`str`):
+                The owning user id forwarded by the consumer.
+            knowledge_base_id (`str`):
+                The knowledge base id forwarded by the consumer.
+            document_id (`str`):
+                The document id forwarded by the consumer.
+
+        Raises:
+            `RuntimeError`:
+                When ``fail_on_doc`` matches ``document_id`` — used by
+                the consumer-resilience tests.
+        """
+        if self.process_delay:
+            await asyncio.sleep(self.process_delay)
+        self.calls.append(
+            {
+                "user_id": user_id,
+                "knowledge_base_id": knowledge_base_id,
+                "document_id": document_id,
+            },
+        )
+        self.notify.set()
+        if self.fail_on_doc and document_id == self.fail_on_doc:
+            raise RuntimeError(f"boom for {document_id}")
+
+
+async def _yield_a_few_times(ticks: int = 8) -> None:
+    """Yield the event loop a few times so spawned tasks make progress."""
+    for _ in range(ticks):
+        await asyncio.sleep(0)
+
+
+class TestIndexTaskConsumerDispatch(IsolatedAsyncioTestCase):
+    """Verifies the signal-driven dispatch path."""
+
+    async def test_signal_drives_dispatch(self) -> None:
+        """A signal causes the queue to be drained and each entry
+        dispatched as ``worker.process``."""
+        bus = _FakeBus()
+        worker = _RecordingWorker()
+        async with IndexTaskConsumer(message_bus=bus, worker=worker):
+            await bus.queue_push(
+                MessageBusKeys.index_tasks_queue(),
+                {
+                    "user_id": "u",
+                    "knowledge_base_id": "kb",
+                    "document_id": "d1",
+                },
+            )
+            await bus.publish(MessageBusKeys.index_tasks_signal(), {})
+
+            await asyncio.wait_for(worker.notify.wait(), timeout=2.0)
+
+        self.assertEqual(
+            worker.calls,
+            [
+                {
+                    "user_id": "u",
+                    "knowledge_base_id": "kb",
+                    "document_id": "d1",
+                },
+            ],
+        )
+
+    async def test_initial_drain_picks_up_pending_entries(self) -> None:
+        """Entries on the queue from before ``__aenter__`` are picked
+        up without waiting for a fresh signal."""
+        bus = _FakeBus()
+        worker = _RecordingWorker()
+        await bus.queue_push(
+            MessageBusKeys.index_tasks_queue(),
+            {
+                "user_id": "u",
+                "knowledge_base_id": "kb",
+                "document_id": "pre",
+            },
+        )
+
+        async with IndexTaskConsumer(message_bus=bus, worker=worker):
+            await asyncio.wait_for(worker.notify.wait(), timeout=2.0)
+
+        self.assertEqual(
+            worker.calls,
+            [
+                {
+                    "user_id": "u",
+                    "knowledge_base_id": "kb",
+                    "document_id": "pre",
+                },
+            ],
+        )
+
+    async def test_malformed_entry_skipped(self) -> None:
+        """A queue entry missing required fields is logged and
+        skipped, not raised; later valid entries still dispatch."""
+        bus = _FakeBus()
+        worker = _RecordingWorker()
+
+        async with IndexTaskConsumer(message_bus=bus, worker=worker):
+            await bus.queue_push(
+                MessageBusKeys.index_tasks_queue(),
+                {"oops": True},
+            )
+            await bus.queue_push(
+                MessageBusKeys.index_tasks_queue(),
+                {
+                    "user_id": "u",
+                    "knowledge_base_id": "kb",
+                    "document_id": "d2",
+                },
+            )
+            await bus.publish(MessageBusKeys.index_tasks_signal(), {})
+            await asyncio.wait_for(worker.notify.wait(), timeout=2.0)
+
+        self.assertEqual(
+            worker.calls,
+            [
+                {
+                    "user_id": "u",
+                    "knowledge_base_id": "kb",
+                    "document_id": "d2",
+                },
+            ],
+        )
+
+    async def test_worker_exception_is_isolated(self) -> None:
+        """An exception inside ``worker.process`` for one entry does
+        not stop subsequent entries from dispatching."""
+        bus = _FakeBus()
+        worker = _RecordingWorker()
+        worker.fail_on_doc = "boom"
+
+        async with IndexTaskConsumer(message_bus=bus, worker=worker):
+            await bus.queue_push(
+                MessageBusKeys.index_tasks_queue(),
+                {
+                    "user_id": "u",
+                    "knowledge_base_id": "kb",
+                    "document_id": "boom",
+                },
+            )
+            await bus.publish(MessageBusKeys.index_tasks_signal(), {})
+            # Reset notify so we can wait for the *second* dispatch.
+            await _yield_a_few_times()
+            worker.notify.clear()
+
+            await bus.queue_push(
+                MessageBusKeys.index_tasks_queue(),
+                {
+                    "user_id": "u",
+                    "knowledge_base_id": "kb",
+                    "document_id": "ok",
+                },
+            )
+            await bus.publish(MessageBusKeys.index_tasks_signal(), {})
+            await asyncio.wait_for(worker.notify.wait(), timeout=2.0)
+
+        doc_ids = [c["document_id"] for c in worker.calls]
+        self.assertEqual(doc_ids, ["boom", "ok"])
+
+
+class TestIndexTaskConsumerLifecycle(IsolatedAsyncioTestCase):
+    """Tests covering the ``__aenter__`` / ``__aexit__`` ACM behaviour."""
+
+    async def test_exit_cancels_loop_cleanly(self) -> None:
+        """``__aexit__`` cancels the consumer's loop task and returns
+        without re-raising the cancellation."""
+        bus = _FakeBus()
+        worker = _RecordingWorker()
+        consumer = IndexTaskConsumer(message_bus=bus, worker=worker)
+
+        # pylint: disable=unnecessary-dunder-call
+        await consumer.__aenter__()
+        loop_task = consumer._task
+        self.assertIsNotNone(loop_task)
+
+        await consumer.__aexit__(None, None, None)
+
+        self.assertIsNone(consumer._task)
+        self.assertTrue(loop_task.cancelled() or loop_task.done())
+
+    async def test_exit_drains_inflight_tasks(self) -> None:
+        """``__aexit__`` cancels in-flight ``worker.process`` tasks
+        and waits for them to settle so exceptions surface in logs
+        and the event loop does not close on top of running
+        coroutines."""
+        bus = _FakeBus()
+        worker = _RecordingWorker()
+        # Make worker.process slow so the consumer exits while one
+        # process call is still mid-flight.
+        worker.process_delay = 0.2
+
+        consumer = IndexTaskConsumer(message_bus=bus, worker=worker)
+        # pylint: disable=unnecessary-dunder-call
+        await consumer.__aenter__()
+
+        await bus.queue_push(
+            MessageBusKeys.index_tasks_queue(),
+            {
+                "user_id": "u",
+                "knowledge_base_id": "kb",
+                "document_id": "slow",
+            },
+        )
+        await bus.publish(MessageBusKeys.index_tasks_signal(), {})
+        # Give the loop a tick to start the worker task.
+        await asyncio.sleep(0)
+        self.assertGreaterEqual(len(consumer._inflight), 1)
+
+        await consumer.__aexit__(None, None, None)
+
+        # The in-flight set is cleared and the consumer task is gone.
+        self.assertEqual(consumer._inflight, set())
+        self.assertIsNone(consumer._task)
diff --git a/tests/service_knowledge_base_upload_test.py b/tests/service_knowledge_base_upload_test.py
new file mode 100644
index 0000000..44a410f
--- /dev/null
+++ b/tests/service_knowledge_base_upload_test.py
@@ -0,0 +1,444 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""End-to-end wiring test for the knowledge-base upload pipeline.
+
+Boots the full FastAPI app via :func:`create_app` against fakeredis +
+in-memory KB-side fakes, then drives the upload → status → list →
+delete flow through ``TestClient``.  Verifies that:
+
+* ``create_app`` wires the new ``blob_store`` / dispatcher / sweeper /
+  service into ``app.state`` correctly;
+* the upload endpoint streams bytes into the blob store, persists a
+  ``pending`` record, and dispatches the worker;
+* the in-process worker drives the record to ``ready`` through the
+  parse → chunk → index phases;
+* the status / list endpoints surface the lifecycle correctly;
+* delete tears down the vector-store and storage records together.
+"""
+import asyncio
+import tempfile
+from typing import Any
+from unittest.async_case import IsolatedAsyncioTestCase
+
+import fakeredis.aioredis
+from fastapi.testclient import TestClient
+
+from agentscope.app import create_app
+from agentscope.app.rag.blob_store import LocalBlobStore
+from agentscope.app.rag.knowledge_base_manager import (
+    KnowledgeBaseManagerBase,
+    KnowledgeBaseNotFoundError,
+)
+from agentscope.app.rag.knowledge_base_manager._dimension_policy import (
+    DimensionPolicy,
+    DimensionPolicyKind,
+)
+from agentscope.app.message_bus import RedisMessageBus
+from agentscope.app.storage import (
+    EmbeddingModelConfig,
+    KnowledgeBaseRecord,
+    RedisStorage,
+)
+from agentscope.app.workspace_manager._base import WorkspaceManagerBase
+from agentscope.rag import VectorStoreBase
+from agentscope.rag._vdb._vector_store import (
+    DocumentSummary,
+    VectorRecord,
+    VectorSearchResult,
+)
+
+
+# ----------------------------------------------------------------------
+# Test doubles
+# ----------------------------------------------------------------------
+
+
+class _FakeVectorStore(VectorStoreBase):
+    """In-memory vector store — records are kept by collection.
+
+    The worker never reads back from it, so there is no need for real
+    similarity math; we only have to honour the ``insert`` / ``delete``
+    / ``has_collection`` contract.
+    """
+
+    def __init__(self) -> None:
+        self._collections: dict[str, list[VectorRecord]] = {}
+
+    async def create_collection(self, name: str, dimensions: int) -> None:
+        self._collections.setdefault(name, [])
+
+    async def delete_collection(self, name: str) -> None:
+        self._collections.pop(name, None)
+
+    async def has_collection(self, name: str) -> bool:
+        return name in self._collections
+
+    async def insert(
+        self,
+        collection: str,
+        records: list[VectorRecord],
+    ) -> None:
+        self._collections.setdefault(collection, []).extend(records)
+
+    async def delete(self, collection: str, document_id: str) -> None:
+        bucket = self._collections.get(collection)
+        if bucket is None:
+            return
+        self._collections[collection] = [
+            r for r in bucket if r.document_id != document_id
+        ]
+
+    async def search(
+        self,
+        collection: str,
+        query_vector: list[float],
+        top_k: int = 5,
+        metadata_filter: dict[str, Any] | None = None,
+    ) -> list[VectorSearchResult]:
+        return []
+
+    async def list_documents(
+        self,
+        collection: str,
+        metadata_filter: dict[str, Any] | None = None,
+    ) -> list[DocumentSummary]:
+        return []
+
+
+class _FakeKnowledge:
+    """Minimal stand-in for :class:`KnowledgeBase` used by the worker.
+
+    Bypasses embedding-model construction — instead just funnels the
+    chunks into the bound :class:`_FakeVectorStore` with a fixed
+    zero-vector so ``insert_document`` succeeds end-to-end.
+    """
+
+    def __init__(
+        self,
+        vector_store: _FakeVectorStore,
+        collection_name: str,
+    ) -> None:
+        self._vector_store = vector_store
+        self._collection_name = collection_name
+
+    async def insert_document(
+        self,
+        chunks: list,
+        document_id: str | None = None,
+        document_metadata: dict | None = None,
+    ) -> str:
+        """Pretend to embed and insert ``chunks`` into the bound store.
+
+        The fake skips the real embedding step — it stamps a single
+        scalar vector on every record so the upload pipeline can be
+        exercised without an embedding model.
+
+        Args:
+            chunks (`list`):
+                The parsed and chunked document content.
+            document_id (`str | None`, optional):
+                Caller-supplied document id; the fake just echoes it
+                back rather than generating a UUID.
+            document_metadata (`dict | None`, optional):
+                Document-level metadata; ignored — the upload tests
+                don't assert on metadata propagation.
+
+        Returns:
+            `str`:
+                The (caller-supplied) document id, or ``""`` when
+                none was passed.
+        """
+        del document_metadata  # unused — see docstring
+        records = [
+            VectorRecord(
+                vector=[0.0],
+                document_id=document_id or "",
+                chunk=chunk,
+            )
+            for chunk in chunks
+        ]
+        await self._vector_store.insert(self._collection_name, records)
+        return document_id or ""
+
+    async def delete_document(self, document_id: str) -> None:
+        """Remove every record for ``document_id`` from the bound store.
+
+        Args:
+            document_id (`str`):
+                The document whose records should be deleted.
+        """
+        await self._vector_store.delete(self._collection_name, document_id)
+
+    async def search(self, queries: list, top_k: int = 5) -> list:
+        """Return an empty result list — search is out of scope here.
+
+        Args:
+            queries (`list`):
+                The query inputs; ignored.
+            top_k (`int`, defaults to ``5``):
+                The maximum result count; ignored.
+
+        Returns:
+            `list`:
+                Always empty — the upload tests do not exercise
+                retrieval.
+        """
+        del queries, top_k  # unused — see docstring
+        return []
+
+
+class _FakeKbManager(KnowledgeBaseManagerBase):
+    """KB manager that uses the storage + a fake vector store directly.
+
+    Skips the real ``CollectionPerKbManager`` so we don't need a live
+    embedding model — the indexing pipeline only requires
+    ``insert_document`` / ``delete_document``, which the
+    :class:`_FakeKnowledge` returned here implements directly.
+    """
+
+    async def get_dimension_policy(self) -> DimensionPolicy:
+        return DimensionPolicy(kind=DimensionPolicyKind.ANY, dimension=None)
+
+    async def create_knowledge_base(
+        self,
+        user_id: str,
+        name: str,
+        description: str,
+        embedding_model_config: EmbeddingModelConfig,
+    ) -> KnowledgeBaseRecord:
+        record = KnowledgeBaseRecord(
+            user_id=user_id,
+            name=name,
+            description=description,
+            embedding_model_config=embedding_model_config,
+            collection_name="",
+        )
+        record.collection_name = f"kb_{record.id}"
+        await self._vector_store.create_collection(
+            name=record.collection_name,
+            dimensions=embedding_model_config.dimensions,
+        )
+        return await self._storage.upsert_knowledge_base(user_id, record)
+
+    async def delete_knowledge_base(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+    ) -> bool:
+        record = await self._storage.get_knowledge_base(
+            user_id,
+            knowledge_base_id,
+        )
+        if record is None:
+            return False
+        await self._vector_store.delete_collection(record.collection_name)
+        return await self._storage.delete_knowledge_base(
+            user_id,
+            knowledge_base_id,
+        )
+
+    async def get_knowledge(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+    ) -> _FakeKnowledge:
+        record = await self._storage.get_knowledge_base(
+            user_id,
+            knowledge_base_id,
+        )
+        if record is None:
+            raise KnowledgeBaseNotFoundError(
+                f"Knowledge base {knowledge_base_id!r} not found.",
+            )
+        return _FakeKnowledge(
+            vector_store=self._vector_store,
+            collection_name=record.collection_name,
+        )
+
+
+class _NoopWorkspaceManager(WorkspaceManagerBase):
+    """Workspace manager that does nothing — the KB pipeline never
+    touches it, but ``create_app`` requires one to be wired in."""
+
+    async def get_workspace(self, *args: Any, **kwargs: Any) -> Any:
+        """Fake implementation."""
+        raise NotImplementedError
+
+    async def close(self, workspace_id: str) -> None:
+        """Fake implementation."""
+        return None
+
+    async def close_all(self) -> None:
+        """Fake implementation."""
+        return None
+
+
+def _make_storage(fr: fakeredis.aioredis.FakeRedis) -> RedisStorage:
+    """Build a RedisStorage already bound to *fr*.
+
+    Pre-populates ``_client`` so the lifespan's ``__aenter__`` no-ops on
+    the connection-pool side and just reuses our fakeredis handle.
+    """
+
+    class _FakeStorage(RedisStorage):
+        async def __aenter__(self) -> "_FakeStorage":
+            self._client = fr
+            return self
+
+        async def aclose(self) -> None:
+            self._client = None
+
+    return _FakeStorage()
+
+
+def _make_bus(fr: fakeredis.aioredis.FakeRedis) -> RedisMessageBus:
+    """Build a RedisMessageBus bound to *fr* (same trick as in the bus
+    tests)."""
+
+    class _FakeBus(RedisMessageBus):
+        async def __aenter__(self) -> "_FakeBus":
+            self._client = fr
+            return self
+
+        async def aclose(self) -> None:
+            self._client = None
+
+    return _FakeBus()
+
+
+# ----------------------------------------------------------------------
+# Tests
+# ----------------------------------------------------------------------
+
+
+class KnowledgeBaseUploadFlowTest(IsolatedAsyncioTestCase):
+    """End-to-end wiring of the upload pipeline through ``TestClient``."""
+
+    async def asyncSetUp(self) -> None:
+        self._tmp = tempfile.TemporaryDirectory()
+        self._fr = fakeredis.aioredis.FakeRedis(decode_responses=True)
+        self._vector_store = _FakeVectorStore()
+        storage = _make_storage(self._fr)
+        message_bus = _make_bus(self._fr)
+
+        self._app = create_app(
+            storage=storage,
+            message_bus=message_bus,
+            workspace_manager=_NoopWorkspaceManager(),
+            knowledge_base_manager=_FakeKbManager(
+                storage=storage,
+                vector_store=self._vector_store,
+            ),
+            blob_store=LocalBlobStore(root_dir=self._tmp.name),
+        )
+        # Seed a knowledge base directly through storage so we don't
+        # have to mock the manager's create flow over HTTP.
+        kb_record = KnowledgeBaseRecord(
+            user_id="user-1",
+            name="kb",
+            description="",
+            embedding_model_config=EmbeddingModelConfig(
+                type="openai_credential",
+                credential_id="cred-1",
+                model="text-embedding-3-small",
+                dimensions=1,
+            ),
+            collection_name="",
+        )
+        kb_record.collection_name = f"kb_{kb_record.id}"
+        await self._vector_store.create_collection(
+            kb_record.collection_name,
+            1,
+        )
+
+        # Drop the seed record into fakeredis directly — we need the KB
+        # in place before lifespan starts the sweeper.
+        storage._client = self._fr
+        await storage.upsert_knowledge_base("user-1", kb_record)
+        storage._client = None
+        self._kb_id = kb_record.id
+
+    async def asyncTearDown(self) -> None:
+        await self._fr.aclose()
+        self._tmp.cleanup()
+
+    async def test_upload_drives_document_to_ready(self) -> None:
+        """Upload a small text file and observe the lifecycle."""
+        headers = {"X-User-ID": "user-1"}
+        with TestClient(self._app) as client:
+            files = {
+                "file": (
+                    "hello.txt",
+                    b"hello world\n" * 16,
+                    "text/plain",
+                ),
+            }
+            resp = client.post(
+                f"/knowledge_bases/{self._kb_id}/documents",
+                files=files,
+                headers=headers,
+            )
+            self.assertEqual(resp.status_code, 201, resp.text)
+            body = resp.json()
+            document_id = body["document_id"]
+            self.assertEqual(body["filename"], "hello.txt")
+            self.assertIn(body["status"], ("pending", "ready"))
+
+            # Wait for the in-process worker to drive the record to
+            # ``ready``.  We poll with a generous overall timeout — the
+            # actual work is < 100 ms but CI machines can be slow.
+            deadline = 5.0
+            poll = 0.05
+            elapsed = 0.0
+            final_status = body["status"]
+            while elapsed < deadline:
+                resp = client.get(
+                    f"/knowledge_bases/{self._kb_id}/documents/status",
+                    params={"ids": document_id},
+                    headers=headers,
+                )
+                self.assertEqual(resp.status_code, 200, resp.text)
+                items = resp.json()["items"]
+                self.assertEqual(len(items), 1, items)
+                final_status = items[0]["status"]
+                if final_status in ("ready", "error"):
+                    break
+                await asyncio.sleep(poll)
+                elapsed += poll
+            self.assertEqual(final_status, "ready", items)
+
+            # Listing shows the document with the same ``ready`` state.
+            resp = client.get(
+                f"/knowledge_bases/{self._kb_id}/documents",
+                headers=headers,
+            )
+            self.assertEqual(resp.status_code, 200, resp.text)
+            documents = resp.json()["documents"]
+            self.assertEqual(len(documents), 1)
+            self.assertEqual(documents[0]["id"], document_id)
+            self.assertEqual(documents[0]["status"], "ready")
+            self.assertGreaterEqual(documents[0]["chunk_count"], 1)
+
+            # Delete and confirm the listing comes back empty.
+            resp = client.delete(
+                f"/knowledge_bases/{self._kb_id}/documents/{document_id}",
+                headers=headers,
+            )
+            self.assertEqual(resp.status_code, 204, resp.text)
+            resp = client.get(
+                f"/knowledge_bases/{self._kb_id}/documents",
+                headers=headers,
+            )
+            self.assertEqual(resp.json()["documents"], [])
+
+    async def test_status_for_unknown_id_is_silently_skipped(self) -> None:
+        """Asking for a non-existent doc returns an empty items list."""
+        headers = {"X-User-ID": "user-1"}
+        with TestClient(self._app) as client:
+            resp = client.get(
+                f"/knowledge_bases/{self._kb_id}/documents/status",
+                params={"ids": "does-not-exist"},
+                headers=headers,
+            )
+            self.assertEqual(resp.status_code, 200, resp.text)
+            self.assertEqual(resp.json()["items"], [])
diff --git a/tests/service_message_bus_test.py b/tests/service_message_bus_test.py
new file mode 100644
index 0000000..bbf6455
--- /dev/null
+++ b/tests/service_message_bus_test.py
@@ -0,0 +1,591 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Tests for :class:`RedisMessageBus` and the domain helpers on the base
+:class:`MessageBus` class.
+
+The Redis backend is exercised against ``fakeredis`` so tests cover both
+the abstract surface (queue / log / pubsub / lock) and the domain helpers
+(``session_run`` / ``session_publish_event`` / ``inbox_*`` / ``wakeup_*``)
+that are layered on top.
+"""
+import asyncio
+from contextlib import AsyncExitStack
+from unittest import IsolatedAsyncioTestCase
+
+import fakeredis.aioredis
+
+from agentscope.app.message_bus import MessageBus, RedisMessageBus
+
+
+def _make_bus(
+    fake_redis: fakeredis.aioredis.FakeRedis,
+) -> RedisMessageBus:
+    """Construct a :class:`RedisMessageBus` that uses *fake_redis*.
+
+    The bus subclass overrides ``__aenter__`` so it talks to fakeredis
+    instead of opening a real connection pool.
+
+    Args:
+        fake_redis (`fakeredis.aioredis.FakeRedis`):
+            A fakeredis client whose pubsub / streams APIs are async.
+
+    Returns:
+        `RedisMessageBus`:
+            A bus instance ready to be used as an async context manager.
+    """
+
+    class _FakeBus(RedisMessageBus):
+        """Bus subclass that returns the supplied fakeredis client on
+        context entry instead of building a real one."""
+
+        async def __aenter__(self) -> "RedisMessageBus":
+            self._client = fake_redis
+            return self
+
+        async def aclose(self) -> None:
+            # The fakeredis client is owned by the test, not the bus.
+            self._client = None
+
+    return _FakeBus()
+
+
+class TestQueuePrimitive(IsolatedAsyncioTestCase):
+    """Mode A — ``queue_push`` + ``queue_drain`` semantics."""
+
+    async def asyncSetUp(self) -> None:
+        self.fr = fakeredis.aioredis.FakeRedis(decode_responses=True)
+        self._stack = AsyncExitStack()
+        self.bus = await self._stack.enter_async_context(_make_bus(self.fr))
+
+    async def asyncTearDown(self) -> None:
+        await self._stack.aclose()
+        await self.fr.aclose()
+
+    async def test_push_drain_returns_payloads_in_order(self) -> None:
+        """Entries pushed in order come back out in order, once each."""
+        await self.bus.queue_push("k", {"i": 1})
+        await self.bus.queue_push("k", {"i": 2})
+        entries = await self.bus.queue_drain("k", max_count=10)
+        self.assertEqual([p for _id, p in entries], [{"i": 1}, {"i": 2}])
+
+    async def test_drain_is_destructive(self) -> None:
+        """A drained entry is gone; a second drain yields nothing."""
+        await self.bus.queue_push("k", {"x": 1})
+        await self.bus.queue_drain("k", max_count=10)
+        self.assertEqual(await self.bus.queue_drain("k", max_count=10), [])
+
+    async def test_drain_respects_max_count(self) -> None:
+        """``max_count`` caps the batch size; remaining entries persist."""
+        for i in range(5):
+            await self.bus.queue_push("k", {"i": i})
+        first = await self.bus.queue_drain("k", max_count=3)
+        rest = await self.bus.queue_drain("k", max_count=10)
+        self.assertEqual([p["i"] for _id, p in first], [0, 1, 2])
+        self.assertEqual([p["i"] for _id, p in rest], [3, 4])
+
+
+class TestLogPrimitive(IsolatedAsyncioTestCase):
+    """Mode C — replay log: append / read with cursor / trim."""
+
+    async def asyncSetUp(self) -> None:
+        self.fr = fakeredis.aioredis.FakeRedis(decode_responses=True)
+        self._stack = AsyncExitStack()
+        self.bus = await self._stack.enter_async_context(_make_bus(self.fr))
+
+    async def asyncTearDown(self) -> None:
+        await self._stack.aclose()
+        await self.fr.aclose()
+
+    async def test_read_returns_everything_when_no_cursor(self) -> None:
+        """Without a ``since`` cursor, the whole log comes back."""
+        await self.bus.log_append("k", {"i": 1})
+        await self.bus.log_append("k", {"i": 2})
+        entries = await self.bus.log_read("k")
+        self.assertEqual([p["i"] for _id, p in entries], [1, 2])
+
+    async def test_read_with_cursor_is_exclusive(self) -> None:
+        """``since=last_id`` skips that id and returns only newer entries."""
+        await self.bus.log_append("k", {"i": 1})
+        await self.bus.log_append("k", {"i": 2})
+        await self.bus.log_append("k", {"i": 3})
+        all_entries = await self.bus.log_read("k")
+        cursor = all_entries[1][0]  # id of entry 2
+        rest = await self.bus.log_read("k", since=cursor)
+        self.assertEqual([p["i"] for _id, p in rest], [3])
+
+    async def test_trim_without_before_drops_entire_log(self) -> None:
+        """``log_trim(key)`` empties the log; subsequent read is empty."""
+        await self.bus.log_append("k", {"i": 1})
+        await self.bus.log_append("k", {"i": 2})
+        await self.bus.log_trim("k")
+        self.assertEqual(await self.bus.log_read("k"), [])
+
+
+class TestPubSubPrimitive(IsolatedAsyncioTestCase):
+    """Mode D — transient broadcast: publish / subscribe."""
+
+    async def asyncSetUp(self) -> None:
+        self.fr = fakeredis.aioredis.FakeRedis(decode_responses=True)
+        self._stack = AsyncExitStack()
+        self.bus = await self._stack.enter_async_context(_make_bus(self.fr))
+
+    async def asyncTearDown(self) -> None:
+        await self._stack.aclose()
+        await self.fr.aclose()
+
+    async def test_subscribe_receives_messages_published_after_ready(
+        self,
+    ) -> None:
+        """Subscribers receive payloads published after the subscription
+        is established. The ``on_ready`` hook fires once before any
+        payload is yielded."""
+        ready = asyncio.Event()
+        received: list[dict] = []
+
+        async def _consumer() -> None:
+            async for payload in self.bus.subscribe(
+                "ch",
+                on_ready=ready.set,
+            ):
+                received.append(payload)
+                if len(received) == 2:
+                    break
+
+        task = asyncio.create_task(_consumer())
+        await asyncio.wait_for(ready.wait(), timeout=2.0)
+
+        await self.bus.publish("ch", {"i": 1})
+        await self.bus.publish("ch", {"i": 2})
+        await asyncio.wait_for(task, timeout=2.0)
+        self.assertEqual([p["i"] for p in received], [1, 2])
+
+
+class TestLockPrimitive(IsolatedAsyncioTestCase):
+    """Mode E — distributed mutex semantics."""
+
+    async def asyncSetUp(self) -> None:
+        self.fr = fakeredis.aioredis.FakeRedis(decode_responses=True)
+        self._stack = AsyncExitStack()
+        self.bus = await self._stack.enter_async_context(_make_bus(self.fr))
+
+    async def asyncTearDown(self) -> None:
+        await self._stack.aclose()
+        await self.fr.aclose()
+
+    async def test_is_locked_reflects_acquire_release(self) -> None:
+        """``is_locked`` flips to True while the body runs and back to
+        False once the context exits."""
+        self.assertFalse(await self.bus.is_locked("k"))
+        async with self.bus.acquire_lock("k", ttl_secs=10):
+            self.assertTrue(await self.bus.is_locked("k"))
+        self.assertFalse(await self.bus.is_locked("k"))
+
+    async def test_second_acquirer_waits_until_release(self) -> None:
+        """A second ``acquire_lock`` on the same key blocks until the
+        first releases."""
+        order: list[str] = []
+
+        async def _holder() -> None:
+            async with self.bus.acquire_lock("k", ttl_secs=10):
+                order.append("first-in")
+                await asyncio.sleep(0.05)
+                order.append("first-out")
+
+        async def _challenger() -> None:
+            # Tiny delay so the holder grabs the lock first.
+            await asyncio.sleep(0.005)
+            async with self.bus.acquire_lock("k", ttl_secs=10):
+                order.append("second-in")
+
+        await asyncio.gather(_holder(), _challenger())
+        self.assertEqual(
+            order,
+            ["first-in", "first-out", "second-in"],
+        )
+
+
+class TestSessionRunAutoTrimsLog(IsolatedAsyncioTestCase):
+    """``session_run.__aexit__`` must trim the session's replay log
+    *before* releasing the distributed lock, so any subscriber that
+    connects between two runs sees a clean slate."""
+
+    async def asyncSetUp(self) -> None:
+        self.fr = fakeredis.aioredis.FakeRedis(decode_responses=True)
+        self._stack = AsyncExitStack()
+        self.bus = await self._stack.enter_async_context(_make_bus(self.fr))
+
+    async def asyncTearDown(self) -> None:
+        await self._stack.aclose()
+        await self.fr.aclose()
+
+    async def test_log_trim_happens_on_session_run_exit(self) -> None:
+        """Events published inside a ``session_run`` block are trimmed
+        once the block exits — a fresh ``session_read_events`` returns
+        an empty list."""
+        sid = "s-trim"
+        async with self.bus.session_run(sid):
+            await self.bus.session_publish_event(sid, {"i": 1})
+            await self.bus.session_publish_event(sid, {"i": 2})
+            mid = await self.bus.session_read_events(sid)
+            self.assertEqual([p["i"] for _id, p in mid], [1, 2])
+        self.assertEqual(await self.bus.session_read_events(sid), [])
+
+    async def test_log_trim_runs_even_when_body_raises(self) -> None:
+        """If the body raises, the log is still trimmed before the lock
+        releases — the next run starts clean."""
+        sid = "s-raise"
+
+        class _Boom(RuntimeError):
+            """Marker exception raised inside the run body."""
+
+        with self.assertRaises(_Boom):
+            async with self.bus.session_run(sid):
+                await self.bus.session_publish_event(sid, {"i": 1})
+                raise _Boom()
+
+        self.assertEqual(await self.bus.session_read_events(sid), [])
+
+
+class TestSessionDomainHelpers(IsolatedAsyncioTestCase):
+    """``session_publish_event`` + ``session_subscribe_events`` +
+    ``session_is_running`` round-trip behaviour."""
+
+    async def asyncSetUp(self) -> None:
+        self.fr = fakeredis.aioredis.FakeRedis(decode_responses=True)
+        self._stack = AsyncExitStack()
+        self.bus = await self._stack.enter_async_context(_make_bus(self.fr))
+
+    async def asyncTearDown(self) -> None:
+        await self._stack.aclose()
+        await self.fr.aclose()
+
+    async def test_publish_event_writes_to_log_and_pubsub(self) -> None:
+        """``session_publish_event`` writes one entry to the replay log
+        AND fans it out on the live channel; subscribers receive the
+        payload with the ``_entry_id`` field stripped."""
+        sid = "s-pub"
+        ready = asyncio.Event()
+        received: list[dict] = []
+
+        async def _consumer() -> None:
+            async for payload in self.bus.session_subscribe_events(
+                sid,
+                on_ready=ready.set,
+            ):
+                received.append(payload)
+                break
+
+        task = asyncio.create_task(_consumer())
+        await asyncio.wait_for(ready.wait(), timeout=2.0)
+
+        await self.bus.session_publish_event(sid, {"hello": "world"})
+        await asyncio.wait_for(task, timeout=2.0)
+
+        # Replay log captured the entry too.
+        log_entries = await self.bus.session_read_events(sid)
+        self.assertEqual(len(log_entries), 1)
+        self.assertEqual(log_entries[0][1], {"hello": "world"})
+
+        # Live subscriber saw it without the internal _entry_id key.
+        self.assertEqual(received, [{"hello": "world"}])
+
+    async def test_session_is_running_reflects_session_run(self) -> None:
+        """``session_is_running`` returns True while inside
+        ``session_run`` and False after."""
+        sid = "s-isrun"
+        self.assertFalse(await self.bus.session_is_running(sid))
+        async with self.bus.session_run(sid):
+            self.assertTrue(await self.bus.session_is_running(sid))
+        self.assertFalse(await self.bus.session_is_running(sid))
+
+
+class TestInboxAndWakeupHelpers(IsolatedAsyncioTestCase):
+    """Inbox + wakeup domain helpers used by team / tool-offload /
+    scheduler to deliver work to idle sessions."""
+
+    async def asyncSetUp(self) -> None:
+        self.fr = fakeredis.aioredis.FakeRedis(decode_responses=True)
+        self._stack = AsyncExitStack()
+        self.bus = await self._stack.enter_async_context(_make_bus(self.fr))
+
+    async def asyncTearDown(self) -> None:
+        await self._stack.aclose()
+        await self.fr.aclose()
+
+    async def test_inbox_push_drain_round_trip(self) -> None:
+        """``inbox_push`` payloads are returned by ``inbox_drain`` in
+        push order, exactly once."""
+        sid = "s-inbox"
+        await self.bus.inbox_push(sid, {"hint": "a"})
+        await self.bus.inbox_push(sid, {"hint": "b"})
+        entries = await self.bus.inbox_drain(sid, max_count=10)
+        self.assertEqual(
+            [p["hint"] for _id, p in entries],
+            ["a", "b"],
+        )
+        self.assertEqual(
+            await self.bus.inbox_drain(sid, max_count=10),
+            [],
+        )
+
+    async def test_enqueue_wakeup_signals_and_queues(self) -> None:
+        """``enqueue_wakeup`` puts the payload on the durable queue and
+        fires the signal channel; a subscriber and a ``dequeue_wakeups``
+        call both see it."""
+        ready = asyncio.Event()
+        received: list[dict] = []
+
+        async def _signal_consumer() -> None:
+            async for payload in self.bus.subscribe_wakeup_signal(
+                on_ready=ready.set,
+            ):
+                received.append(payload)
+                break
+
+        task = asyncio.create_task(_signal_consumer())
+        await asyncio.wait_for(ready.wait(), timeout=2.0)
+
+        await self.bus.enqueue_wakeup(
+            user_id="u",
+            session_id="s",
+            agent_id="a",
+        )
+        await asyncio.wait_for(task, timeout=2.0)
+
+        # Signal fired.
+        self.assertEqual(len(received), 1)
+
+        # Queue holds the structured entry. ``enqueue_wakeup`` is the
+        # idle-wake shortcut, so the entry carries ``kind="wake"`` and a
+        # null input alongside the routing fields.
+        entries = await self.bus.dequeue_wakeups(max_count=10)
+        self.assertEqual(len(entries), 1)
+        self.assertEqual(
+            entries[0],
+            {
+                "user_id": "u",
+                "session_id": "s",
+                "agent_id": "a",
+                "kind": "wake",
+                "input": None,
+            },
+        )
+
+
+class TestRegistryPrimitive(IsolatedAsyncioTestCase):
+    """Mode F — ``registry_*`` hash-keyed namespace operations."""
+
+    async def asyncSetUp(self) -> None:
+        self.fr = fakeredis.aioredis.FakeRedis(decode_responses=True)
+        self._stack = AsyncExitStack()
+        self.bus = await self._stack.enter_async_context(_make_bus(self.fr))
+
+    async def asyncTearDown(self) -> None:
+        await self._stack.aclose()
+        await self.fr.aclose()
+
+    async def test_set_then_exists_and_getall(self) -> None:
+        """``registry_set`` stores a field under a namespace; ``exists``
+        is True, ``getall`` returns the full mapping."""
+        await self.bus.registry_set("ns", "f1", "v1")
+        await self.bus.registry_set("ns", "f2", "v2")
+
+        self.assertTrue(await self.bus.registry_exists("ns", "f1"))
+        self.assertTrue(await self.bus.registry_exists("ns", "f2"))
+        self.assertFalse(await self.bus.registry_exists("ns", "missing"))
+        self.assertFalse(await self.bus.registry_exists("other-ns", "f1"))
+
+        self.assertEqual(
+            await self.bus.registry_getall("ns"),
+            {"f1": "v1", "f2": "v2"},
+        )
+
+    async def test_set_overwrites_existing_field(self) -> None:
+        """A second ``registry_set`` for the same field overwrites the
+        previous value (``HSET`` semantics)."""
+        await self.bus.registry_set("ns", "f", "v1")
+        await self.bus.registry_set("ns", "f", "v2")
+        self.assertEqual(
+            await self.bus.registry_getall("ns"),
+            {"f": "v2"},
+        )
+
+    async def test_del_removes_only_the_named_field(self) -> None:
+        """``registry_del`` removes a single field; siblings survive."""
+        await self.bus.registry_set("ns", "keep", "k")
+        await self.bus.registry_set("ns", "drop", "d")
+
+        await self.bus.registry_del("ns", "drop")
+
+        self.assertFalse(await self.bus.registry_exists("ns", "drop"))
+        self.assertTrue(await self.bus.registry_exists("ns", "keep"))
+        self.assertEqual(
+            await self.bus.registry_getall("ns"),
+            {"keep": "k"},
+        )
+
+    async def test_del_missing_field_is_noop(self) -> None:
+        """Deleting a non-existent field does not raise."""
+        await self.bus.registry_del("ns", "nope")
+        await self.bus.registry_set("ns", "keep", "k")
+        await self.bus.registry_del("ns", "still-missing")
+        self.assertEqual(
+            await self.bus.registry_getall("ns"),
+            {"keep": "k"},
+        )
+
+    async def test_getall_on_missing_namespace_returns_empty_dict(
+        self,
+    ) -> None:
+        """``registry_getall`` for an unknown namespace returns ``{}``
+        rather than ``None``."""
+        self.assertEqual(await self.bus.registry_getall("ghost"), {})
+
+    async def test_drop_deletes_entire_namespace(self) -> None:
+        """``registry_drop`` removes every field under the namespace."""
+        await self.bus.registry_set("ns", "f1", "v1")
+        await self.bus.registry_set("ns", "f2", "v2")
+
+        await self.bus.registry_drop("ns")
+
+        self.assertFalse(await self.bus.registry_exists("ns", "f1"))
+        self.assertFalse(await self.bus.registry_exists("ns", "f2"))
+        self.assertEqual(await self.bus.registry_getall("ns"), {})
+
+    async def test_drop_missing_namespace_is_noop(self) -> None:
+        """Dropping a namespace that was never written does not raise."""
+        await self.bus.registry_drop("never-existed")
+
+    async def test_set_with_ttl_applies_expire_and_refreshes(self) -> None:
+        """``registry_set`` with ``ttl_secs`` sets a TTL on the hash key;
+        a subsequent set with a longer ``ttl_secs`` refreshes it."""
+        await self.bus.registry_set("ns", "f", "v", ttl_secs=60)
+        ttl_first = await self.fr.ttl("ns")
+        self.assertGreater(ttl_first, 0)
+        self.assertLessEqual(ttl_first, 60)
+
+        # Refresh with a much larger TTL — must overwrite the old one.
+        await self.bus.registry_set("ns", "f", "v", ttl_secs=3600)
+        ttl_refreshed = await self.fr.ttl("ns")
+        self.assertGreater(ttl_refreshed, 60)
+
+    async def test_set_without_ttl_leaves_namespace_persistent(
+        self,
+    ) -> None:
+        """Without ``ttl_secs`` the namespace has no expiry (TTL == -1)."""
+        await self.bus.registry_set("ns", "f", "v")
+        self.assertEqual(await self.fr.ttl("ns"), -1)
+
+
+class TestBackgroundTaskRegistryHelpers(IsolatedAsyncioTestCase):
+    """Domain helpers built on Mode F: ``bg_task_register / unregister /
+    exists / list / purge`` plus ``task_publish_cancel /
+    task_subscribe_cancel``."""
+
+    async def asyncSetUp(self) -> None:
+        self.fr = fakeredis.aioredis.FakeRedis(decode_responses=True)
+        self._stack = AsyncExitStack()
+        self.bus = await self._stack.enter_async_context(_make_bus(self.fr))
+
+    async def asyncTearDown(self) -> None:
+        await self._stack.aclose()
+        await self.fr.aclose()
+
+    async def test_register_then_exists_list_unregister(self) -> None:
+        """End-to-end registry round-trip for a single session."""
+        sid = "s-bg"
+
+        self.assertFalse(await self.bus.bg_task_exists(sid, "t1"))
+
+        await self.bus.bg_task_register(sid, "t1", '{"tool":"a"}')
+        await self.bus.bg_task_register(sid, "t2", '{"tool":"b"}')
+
+        self.assertTrue(await self.bus.bg_task_exists(sid, "t1"))
+        self.assertTrue(await self.bus.bg_task_exists(sid, "t2"))
+        self.assertEqual(
+            await self.bus.bg_task_list(sid),
+            {"t1": '{"tool":"a"}', "t2": '{"tool":"b"}'},
+        )
+
+        await self.bus.bg_task_unregister(sid, "t1")
+        self.assertFalse(await self.bus.bg_task_exists(sid, "t1"))
+        self.assertTrue(await self.bus.bg_task_exists(sid, "t2"))
+        self.assertEqual(
+            await self.bus.bg_task_list(sid),
+            {"t2": '{"tool":"b"}'},
+        )
+
+    async def test_register_isolates_sessions(self) -> None:
+        """Tasks registered under one session id are invisible to other
+        session ids."""
+        await self.bus.bg_task_register("s1", "t", "{}")
+
+        self.assertTrue(await self.bus.bg_task_exists("s1", "t"))
+        self.assertFalse(await self.bus.bg_task_exists("s2", "t"))
+        self.assertEqual(await self.bus.bg_task_list("s2"), {})
+
+    async def test_register_applies_fallback_ttl(self) -> None:
+        """``bg_task_register`` sets the per-session fallback TTL on the
+        hash key so abandoned entries can't accumulate forever."""
+        sid = "s-ttl"
+        await self.bus.bg_task_register(sid, "t", "{}")
+
+        ttl = await self.fr.ttl(self.bus._BG_TASKS_KEY.format(sid=sid))
+        self.assertGreater(ttl, 0)
+        self.assertLessEqual(ttl, self.bus._BG_TASKS_TTL_SECS)
+
+        # A second register-call refreshes the TTL back near the cap.
+        await asyncio.sleep(0)  # let any fakeredis internals settle
+        await self.bus.bg_task_register(sid, "t2", "{}")
+        ttl_refreshed = await self.fr.ttl(
+            self.bus._BG_TASKS_KEY.format(sid=sid),
+        )
+        self.assertGreater(ttl_refreshed, 0)
+
+    async def test_purge_clears_all_session_entries(self) -> None:
+        """``bg_task_purge`` deletes every task entry for a session in
+        a single call (used during session deletion)."""
+        sid = "s-purge"
+        await self.bus.bg_task_register(sid, "t1", "{}")
+        await self.bus.bg_task_register(sid, "t2", "{}")
+        # Other session must survive.
+        await self.bus.bg_task_register("s-keep", "t", "{}")
+
+        await self.bus.bg_task_purge(sid)
+
+        self.assertEqual(await self.bus.bg_task_list(sid), {})
+        self.assertFalse(await self.bus.bg_task_exists(sid, "t1"))
+        self.assertTrue(await self.bus.bg_task_exists("s-keep", "t"))
+
+    async def test_task_publish_cancel_reaches_subscriber(self) -> None:
+        """``task_publish_cancel`` fans out to every active
+        ``task_subscribe_cancel`` listener; the yielded value is the
+        ``task_id`` from the payload."""
+        ready = asyncio.Event()
+        received: list[str] = []
+
+        async def _consumer() -> None:
+            async for tid in self.bus.task_subscribe_cancel(
+                on_ready=ready.set,
+            ):
+                received.append(tid)
+                break
+
+        task = asyncio.create_task(_consumer())
+        await asyncio.wait_for(ready.wait(), timeout=2.0)
+
+        await self.bus.task_publish_cancel("task-X")
+        await asyncio.wait_for(task, timeout=2.0)
+
+        self.assertEqual(received, ["task-X"])
+
+
+class TestBaseClassIsAbstract(IsolatedAsyncioTestCase):
+    """``MessageBus`` itself cannot be instantiated."""
+
+    def test_instantiating_base_class_raises(self) -> None:
+        """The abstract methods are not implemented on the base — direct
+        instantiation must fail."""
+        with self.assertRaises(TypeError):
+            # pylint: disable=abstract-class-instantiated
+            MessageBus()  # type: ignore[abstract]
diff --git a/tests/service_scheduler_test.py b/tests/service_scheduler_test.py
new file mode 100644
index 0000000..8dc9af9
--- /dev/null
+++ b/tests/service_scheduler_test.py
@@ -0,0 +1,267 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Tests for :meth:`SchedulerManager._build_trigger`.
+
+We don't drive APScheduler here — we ask the manager to build a trigger
+coroutine for a record and invoke it directly. The trigger's contract is:
+
+- when ``ScheduleData.enabled`` is False → no side effects;
+- when enabled → resolve / create a target session, push a
+  ``<scheduled-task>``-wrapped :class:`HintBlock` to the session inbox,
+  and enqueue one wakeup pointing at that session.
+
+In stateful mode the session id is deterministic (``{record_id}_stateful``)
+and reused across fires; in non-stateful mode a fresh session id is
+created every fire.
+"""
+import json
+from contextlib import AsyncExitStack
+from datetime import datetime
+from unittest import IsolatedAsyncioTestCase
+
+import fakeredis.aioredis
+
+from utils import AnyString
+
+from agentscope.app._manager import SchedulerManager
+from agentscope.app.message_bus import RedisMessageBus
+from agentscope.app.storage import (
+    ChatModelConfig,
+    RedisStorage,
+    ScheduleData,
+    ScheduleRecord,
+    SessionSource,
+)
+from agentscope.permission import PermissionMode
+
+
+def _make_storage(
+    fr: fakeredis.aioredis.FakeRedis,
+) -> RedisStorage:
+    """Construct a :class:`RedisStorage` bound to *fr*."""
+
+    class _S(RedisStorage):
+        async def __aenter__(self) -> "RedisStorage":  # type: ignore[override]
+            self._client = fr
+            return self
+
+        async def aclose(self) -> None:
+            self._client = None
+
+    return _S()
+
+
+def _make_bus(
+    fr: fakeredis.aioredis.FakeRedis,
+) -> RedisMessageBus:
+    """Construct a :class:`RedisMessageBus` bound to *fr*."""
+
+    class _B(RedisMessageBus):
+        async def __aenter__(  # type: ignore[override]
+            self,
+        ) -> "RedisMessageBus":
+            self._client = fr
+            return self
+
+        async def aclose(self) -> None:
+            self._client = None
+
+    return _B()
+
+
+def _make_record(
+    *,
+    user_id: str = "u",
+    agent_id: str = "a",
+    enabled: bool = True,
+    stateful: bool = False,
+    description: str = "run nightly summary",
+) -> ScheduleRecord:
+    """Build a minimal :class:`ScheduleRecord` for the trigger test."""
+    return ScheduleRecord(
+        user_id=user_id,
+        agent_id=agent_id,
+        data=ScheduleData(
+            name="sched-a",
+            description=description,
+            enabled=enabled,
+            cron_expression="0 0 * * *",
+            started_at=datetime(2025, 1, 1),
+            chat_model_config=ChatModelConfig(
+                type="dashscope_credential",
+                credential_id="c",
+                model="m",
+                parameters={},
+            ),
+            stateful=stateful,
+            permission_mode=PermissionMode.DONT_ASK,
+        ),
+    )
+
+
+class _SchedulerFireTestBase(IsolatedAsyncioTestCase):
+    """Shared fakeredis + storage + bus + manager fixture."""
+
+    async def asyncSetUp(self) -> None:
+        self.fr = fakeredis.aioredis.FakeRedis(decode_responses=True)
+        self._stack = AsyncExitStack()
+        self.storage = await self._stack.enter_async_context(
+            _make_storage(self.fr),
+        )
+        self.bus = await self._stack.enter_async_context(_make_bus(self.fr))
+        # Do NOT enter the SchedulerManager context — that would start
+        # APScheduler. We only need ``_build_trigger`` from the
+        # un-started manager.
+        self.manager = SchedulerManager(
+            storage=self.storage,
+            message_bus=self.bus,
+        )
+
+    async def asyncTearDown(self) -> None:
+        await self._stack.aclose()
+        await self.fr.aclose()
+
+
+class TestSchedulerFireDelivery(_SchedulerFireTestBase):
+    """A fire delivers the prompt as a HintBlock + wakeup."""
+
+    async def test_fire_pushes_hint_and_wakeup(self) -> None:
+        """A fire creates a session, pushes the wrapped HintBlock to its
+        inbox, and enqueues one wakeup pointing at that session."""
+        record = _make_record(description="please summarise the news")
+        trigger = self.manager._build_trigger(record)
+        await trigger()
+
+        # A session was created.
+        sessions = await self.storage.list_sessions(
+            record.user_id,
+            record.agent_id,
+        )
+        self.assertEqual(len(sessions), 1)
+        session = sessions[0]
+        self.assertEqual(
+            {
+                "source": session.source,
+                "source_schedule_id": session.source_schedule_id,
+            },
+            {
+                "source": SessionSource.SCHEDULE,
+                "source_schedule_id": record.id,
+            },
+        )
+
+        # Inbox has the wrapped HintBlock.
+        inbox = await self.bus.inbox_drain(session.id, max_count=10)
+        self.assertEqual(len(inbox), 1)
+        hint = inbox[0][1]
+        self.assertDictEqual(
+            hint,
+            {
+                "type": "hint",
+                "id": AnyString(),
+                "hint": AnyString(),
+                "source": json.dumps(
+                    {"label": "schedule", "sublabel": record.data.name},
+                ),
+            },
+        )
+        self.assertIn("<scheduled-task>", hint["hint"])
+        self.assertIn("please summarise the news", hint["hint"])
+
+        # A wakeup is enqueued for that session.
+        wakeups = await self.bus.dequeue_wakeups(max_count=10)
+        self.assertEqual(len(wakeups), 1)
+        self.assertEqual(
+            wakeups[0],
+            {
+                "session_id": session.id,
+                "agent_id": record.agent_id,
+                "user_id": record.user_id,
+                "kind": "wake",
+                "input": None,
+            },
+        )
+
+
+class TestSchedulerFireDisabled(_SchedulerFireTestBase):
+    """Disabled schedules are a no-op."""
+
+    async def test_disabled_fire_does_nothing(self) -> None:
+        """A fire on a disabled schedule creates no session and no wakeup."""
+        record = _make_record(enabled=False)
+        trigger = self.manager._build_trigger(record)
+        await trigger()
+
+        # No session created, no wakeup enqueued.
+        sessions = await self.storage.list_sessions(
+            record.user_id,
+            record.agent_id,
+        )
+        self.assertEqual(sessions, [])
+        wakeups = await self.bus.dequeue_wakeups(max_count=10)
+        self.assertEqual(wakeups, [])
+
+
+class TestSchedulerFireStatefulMode(_SchedulerFireTestBase):
+    """Stateful schedules reuse the same session id across fires."""
+
+    async def test_stateful_fires_share_one_session(self) -> None:
+        """Two fires of a stateful schedule reuse the same session id."""
+        record = _make_record(stateful=True)
+        trigger = self.manager._build_trigger(record)
+        await trigger()
+        await trigger()
+
+        sessions = await self.storage.list_sessions(
+            record.user_id,
+            record.agent_id,
+        )
+        # Exactly ONE session reused.
+        self.assertEqual(len(sessions), 1)
+        self.assertEqual([s.id for s in sessions], [f"{record.id}_stateful"])
+
+        # That single session has two HintBlocks in its inbox.
+        inbox = await self.bus.inbox_drain(sessions[0].id, max_count=10)
+        self.assertEqual(len(inbox), 2)
+
+        # Two wakeups, both pointing at the same session.
+        wakeups = await self.bus.dequeue_wakeups(max_count=10)
+        self.assertEqual(
+            wakeups,
+            [
+                {
+                    "session_id": sessions[0].id,
+                    "agent_id": record.agent_id,
+                    "user_id": record.user_id,
+                    "kind": "wake",
+                    "input": None,
+                },
+                {
+                    "session_id": sessions[0].id,
+                    "agent_id": record.agent_id,
+                    "user_id": record.user_id,
+                    "kind": "wake",
+                    "input": None,
+                },
+            ],
+        )
+
+
+class TestSchedulerFireNonStatefulMode(_SchedulerFireTestBase):
+    """Non-stateful schedules create a fresh session every fire."""
+
+    async def test_non_stateful_fires_create_distinct_sessions(
+        self,
+    ) -> None:
+        """Two fires of a non-stateful schedule create distinct sessions."""
+        record = _make_record(stateful=False)
+        trigger = self.manager._build_trigger(record)
+        await trigger()
+        await trigger()
+
+        sessions = await self.storage.list_sessions(
+            record.user_id,
+            record.agent_id,
+        )
+        self.assertEqual(len(sessions), 2)
+        self.assertNotEqual(sessions[0].id, sessions[1].id)
diff --git a/tests/service_subagent_hitl_projector_test.py b/tests/service_subagent_hitl_projector_test.py
new file mode 100644
index 0000000..267b3b0
--- /dev/null
+++ b/tests/service_subagent_hitl_projector_test.py
@@ -0,0 +1,365 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Tests for :class:`SubagentHitlProjector` — the strategy that mirrors a
+team *member* (worker) session's HITL request onto its *leader* session.
+
+Covers the projection policy:
+
+- A worker ``Require*`` event upserts a pending card on the leader and
+  publishes the live ``EVT_REQUIRE`` notification.
+- A worker ``*Result`` / ``ReplyEnd`` event deletes the card and
+  publishes the ``EVT_RESULT`` clear notification.
+- No-op for non-team agents, for sessions with no ``team_id``, and for
+  the leader session itself (its own HITL reaches its client directly).
+- ``resolve`` finds the worker entry behind a leader+reply_id, and
+  returns ``None`` when none matches.
+"""
+from typing import Any
+from unittest import IsolatedAsyncioTestCase
+
+from agentscope.app._service import SubagentHitlProjector
+from agentscope.app.storage._model._agent import AgentRecord, AgentData
+from agentscope.app.storage._model._session import SessionRecord
+from agentscope.app.storage._model._team import TeamRecord
+from agentscope.event import (
+    RequireUserConfirmEvent,
+    RequireExternalExecutionEvent,
+    UserConfirmResultEvent,
+    ExternalExecutionResultEvent,
+    ReplyEndEvent,
+)
+
+
+class _FakeProjection:
+    """Records every mutation the projector makes, no Redis required.
+
+    Mimics :class:`SessionProjection`'s surface (``upsert`` / ``delete``
+    / ``publish`` / ``list``) over an in-memory ``{(sid, kind): {eid:
+    payload}}`` store so tests can assert exactly what was projected.
+    """
+
+    def __init__(self) -> None:
+        self.store: dict[tuple[str, str], dict[str, dict]] = {}
+        self.published: list[tuple[str, str, dict]] = []
+
+    async def upsert(
+        self,
+        target_sid: str,
+        kind: str,
+        entry_id: str,
+        payload: dict,
+    ) -> None:
+        """Record an upsert in the in-memory store."""
+        self.store.setdefault((target_sid, kind), {})[entry_id] = payload
+
+    async def delete(
+        self,
+        target_sid: str,
+        kind: str,
+        entry_id: str,
+    ) -> None:
+        """Remove an entry from the in-memory store."""
+        self.store.get((target_sid, kind), {}).pop(entry_id, None)
+
+    async def list(self, target_sid: str, kind: str) -> list[dict]:
+        """Return all entries for the given session and kind."""
+        return list(self.store.get((target_sid, kind), {}).values())
+
+    async def publish(
+        self,
+        target_sid: str,
+        event_name: str,
+        value: dict,
+    ) -> None:
+        """Record a published event for later assertion."""
+        self.published.append((target_sid, event_name, value))
+
+
+class _FakeStorage:
+    """Returns a fixed team for ``get_team``; ``None`` to simulate a
+    missing / non-team lookup."""
+
+    def __init__(self, team: TeamRecord | None) -> None:
+        self._team = team
+
+    async def get_team(
+        self,
+        _user_id: str,
+        _team_id: str,
+    ) -> TeamRecord | None:
+        """Return the pre-configured team record."""
+        return self._team
+
+
+_LEADER_SID = "leader-sid"
+_WORKER_SID = "worker-sid"
+_TEAM_ID = "team-1"
+
+
+def _team() -> TeamRecord:
+    """A team whose leader is ``_LEADER_SID``."""
+    return TeamRecord.model_construct(
+        id=_TEAM_ID,
+        user_id="u",
+        session_id=_LEADER_SID,
+    )
+
+
+def _session(sid: str, team_id: str | None = _TEAM_ID) -> SessionRecord:
+    """A session record with just the fields the projector reads."""
+    return SessionRecord.model_construct(
+        id=sid,
+        user_id="u",
+        agent_id="wa1",
+        team_id=team_id,
+    )
+
+
+def _agent(source: str = "team") -> AgentRecord:
+    """An agent record with just the fields the projector reads."""
+    return AgentRecord.model_construct(
+        id="wa1",
+        user_id="u",
+        source=source,
+        data=AgentData.model_construct(name="researcher"),
+    )
+
+
+def _projector(team: TeamRecord | None = None) -> SubagentHitlProjector:
+    return SubagentHitlProjector(_FakeStorage(team if team else _team()))
+
+
+def _entry_id() -> str:
+    return SubagentHitlProjector.entry_id(_WORKER_SID, "r1")
+
+
+class TestSubagentHitlProjectorRequire(IsolatedAsyncioTestCase):
+    """The require → upsert + publish path."""
+
+    async def _run_require(self, event: Any) -> _FakeProjection:
+        projection = _FakeProjection()
+        await _projector().maybe_project(
+            "u",
+            _session(_WORKER_SID),
+            _agent(),
+            event,
+            projection,
+        )
+        return projection
+
+    async def test_require_user_confirm_upserts_and_publishes(self) -> None:
+        """A worker ``RequireUserConfirmEvent`` writes a leader card and
+        fires the live require notification."""
+        event = RequireUserConfirmEvent.model_construct(
+            reply_id="r1",
+            tool_calls=[],
+        )
+        projection = await self._run_require(event)
+
+        card = projection.store[(_LEADER_SID, SubagentHitlProjector.KIND)]
+        self.assertIn(_entry_id(), card)
+        payload = card[_entry_id()]
+        self.assertEqual(payload["worker_session_id"], _WORKER_SID)
+        self.assertEqual(payload["reply_id"], "r1")
+        self.assertEqual(payload["event_type"], "require_user_confirm")
+
+        self.assertEqual(len(projection.published), 1)
+        sid, name, _ = projection.published[0]
+        self.assertEqual(sid, _LEADER_SID)
+        self.assertEqual(name, SubagentHitlProjector.EVT_REQUIRE)
+
+    async def test_require_external_execution_marks_event_type(self) -> None:
+        """A ``RequireExternalExecutionEvent`` carries the matching
+        ``event_type`` discriminator."""
+        event = RequireExternalExecutionEvent.model_construct(
+            reply_id="r1",
+            tool_calls=[],
+        )
+        projection = await self._run_require(event)
+
+        card = projection.store[(_LEADER_SID, SubagentHitlProjector.KIND)]
+        self.assertEqual(
+            card[_entry_id()]["event_type"],
+            "require_external_execution",
+        )
+
+    async def test_invited_agent_source_user_still_projects(self) -> None:
+        """An ``AgentInvite``-borrowed session runs on a
+        ``source='user'`` agent record but is still a team worker — its
+        HITL request must project onto the leader like any other
+        team-member session."""
+        projection = _FakeProjection()
+        await _projector().maybe_project(
+            "u",
+            _session(_WORKER_SID),
+            _agent(source="user"),  # invited agents keep source='user'
+            RequireUserConfirmEvent.model_construct(
+                reply_id="r1",
+                tool_calls=[],
+            ),
+            projection,
+        )
+        card = projection.store[(_LEADER_SID, SubagentHitlProjector.KIND)]
+        self.assertIn(_entry_id(), card)
+
+
+class TestSubagentHitlProjectorClear(IsolatedAsyncioTestCase):
+    """The result / reply-end → delete + publish path."""
+
+    async def _seed_then(self, clear_event: Any) -> _FakeProjection:
+        projection = _FakeProjection()
+        projector = _projector()
+        # Seed a pending card first.
+        await projector.maybe_project(
+            "u",
+            _session(_WORKER_SID),
+            _agent(),
+            RequireUserConfirmEvent.model_construct(
+                reply_id="r1",
+                tool_calls=[],
+            ),
+            projection,
+        )
+        projection.published.clear()
+        # Now clear it.
+        await projector.maybe_project(
+            "u",
+            _session(_WORKER_SID),
+            _agent(),
+            clear_event,
+            projection,
+        )
+        return projection
+
+    async def test_user_confirm_result_clears_card(self) -> None:
+        """A worker ``UserConfirmResultEvent`` deletes the leader card and
+        publishes the clear notification."""
+        projection = await self._seed_then(
+            UserConfirmResultEvent.model_construct(
+                reply_id="r1",
+                confirm_results=[],
+            ),
+        )
+        card = projection.store[(_LEADER_SID, SubagentHitlProjector.KIND)]
+        self.assertNotIn(_entry_id(), card)
+
+        self.assertEqual(len(projection.published), 1)
+        sid, name, value = projection.published[0]
+        self.assertEqual(sid, _LEADER_SID)
+        self.assertEqual(name, SubagentHitlProjector.EVT_RESULT)
+        self.assertEqual(value["worker_session_id"], _WORKER_SID)
+        self.assertEqual(value["reply_id"], "r1")
+
+    async def test_external_execution_result_clears_card(self) -> None:
+        """An ``ExternalExecutionResultEvent`` also clears the card."""
+        projection = await self._seed_then(
+            ExternalExecutionResultEvent.model_construct(
+                reply_id="r1",
+                execution_results=[],
+            ),
+        )
+        card = projection.store[(_LEADER_SID, SubagentHitlProjector.KIND)]
+        self.assertNotIn(_entry_id(), card)
+        self.assertEqual(
+            projection.published[0][1],
+            SubagentHitlProjector.EVT_RESULT,
+        )
+
+    async def test_reply_end_clears_card(self) -> None:
+        """``ReplyEndEvent`` is the primary clear signal (the resume's
+        continuation events are not republished through the stream)."""
+        projection = await self._seed_then(
+            ReplyEndEvent.model_construct(reply_id="r1"),
+        )
+        card = projection.store[(_LEADER_SID, SubagentHitlProjector.KIND)]
+        self.assertNotIn(_entry_id(), card)
+        self.assertEqual(
+            projection.published[0][1],
+            SubagentHitlProjector.EVT_RESULT,
+        )
+
+
+class TestSubagentHitlProjectorNoOp(IsolatedAsyncioTestCase):
+    """Cases where nothing should be projected."""
+
+    async def _assert_noop(
+        self,
+        *,
+        agent_source: str = "team",
+        team_id: str | None = _TEAM_ID,
+        team: TeamRecord | None = None,
+        session_id: str = _WORKER_SID,
+    ) -> None:
+        projection = _FakeProjection()
+        projector = SubagentHitlProjector(
+            _FakeStorage(team if team is not None else _team()),
+        )
+        await projector.maybe_project(
+            "u",
+            _session(session_id, team_id=team_id),
+            _agent(source=agent_source),
+            RequireUserConfirmEvent.model_construct(
+                reply_id="r1",
+                tool_calls=[],
+            ),
+            projection,
+        )
+        self.assertEqual(projection.store, {})
+        self.assertEqual(projection.published, [])
+
+    async def test_session_without_team_id_is_noop(self) -> None:
+        """A session with no ``team_id`` never projects."""
+        await self._assert_noop(team_id=None)
+
+    async def test_leader_session_is_noop(self) -> None:
+        """The leader's own HITL reaches its client directly — no
+        self-projection."""
+        await self._assert_noop(session_id=_LEADER_SID)
+
+    async def test_unrelated_event_is_noop(self) -> None:
+        """Events outside the HITL set are ignored."""
+        projection = _FakeProjection()
+        await _projector().maybe_project(
+            "u",
+            _session(_WORKER_SID),
+            _agent(),
+            ReplyEndEvent.model_construct(reply_id="r1"),
+            projection,
+        )
+        # ReplyEnd with no seeded card: delete is a no-op, but it DOES
+        # publish a (harmless, idempotent) clear. Assert no card written.
+        self.assertEqual(projection.store, {})
+
+
+class TestSubagentHitlProjectorResolve(IsolatedAsyncioTestCase):
+    """The router-side ``resolve`` helper."""
+
+    async def test_resolve_finds_and_misses(self) -> None:
+        """``resolve`` returns the worker entry for a known reply_id and
+        ``None`` for an unknown one."""
+        projection = _FakeProjection()
+        await _projector().maybe_project(
+            "u",
+            _session(_WORKER_SID),
+            _agent(),
+            RequireUserConfirmEvent.model_construct(
+                reply_id="r1",
+                tool_calls=[],
+            ),
+            projection,
+        )
+
+        hit = await SubagentHitlProjector.resolve(
+            projection,
+            _LEADER_SID,
+            "r1",
+        )
+        self.assertIsNotNone(hit)
+        self.assertEqual(hit["worker_session_id"], _WORKER_SID)
+
+        miss = await SubagentHitlProjector.resolve(
+            projection,
+            _LEADER_SID,
+            "nope",
+        )
+        self.assertIsNone(miss)
diff --git a/tests/service_team_tools_test.py b/tests/service_team_tools_test.py
new file mode 100644
index 0000000..d4c21f9
--- /dev/null
+++ b/tests/service_team_tools_test.py
@@ -0,0 +1,1697 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Tests for the four framework-builtin team tools — :class:`TeamCreate`,
+:class:`AgentCreate`, :class:`TeamSay`, :class:`TeamDelete`.
+
+Each tool's business logic now lives inline in its ``__call__`` (the
+old ``TeamService`` orchestration layer is gone), so unit tests run the
+tools directly against a real :class:`RedisStorage` + :class:`RedisMessageBus`
+backed by ``fakeredis``. They assert:
+
+- the success path: storage rows updated, inbox + wakeup pushed where
+  expected;
+- the failure paths: each precondition (not in a team / not the leader /
+  recipient missing / etc.) returns an ``ERROR`` ``ToolChunk`` instead
+  of raising.
+"""
+from contextlib import AsyncExitStack
+from unittest import IsolatedAsyncioTestCase
+
+import fakeredis.aioredis
+
+from utils import AnyString, FakeWorkspaceManager
+
+from agentscope.agent import ContextConfig, ReActConfig
+from agentscope.app._tool import (
+    AgentCreate,
+    AgentInvite,
+    DEFAULT_SUB_AGENT_TEMPLATE,
+    TeamCreate,
+    TeamDelete,
+    TeamSay,
+)
+from agentscope.app._types import SubAgentTemplate
+from agentscope.app.message_bus import RedisMessageBus
+from agentscope.app.storage import (
+    AgentData,
+    AgentRecord,
+    RedisStorage,
+    SessionConfig,
+)
+from agentscope.permission import (
+    AdditionalWorkingDirectory,
+    PermissionBehavior,
+    PermissionContext,
+    PermissionMode,
+    PermissionRule,
+)
+from agentscope.state import AgentState
+
+
+def _make_storage(
+    fr: fakeredis.aioredis.FakeRedis,
+) -> RedisStorage:
+    """Construct a :class:`RedisStorage` that talks to *fr*."""
+
+    class _S(RedisStorage):
+        async def __aenter__(self) -> "RedisStorage":  # type: ignore[override]
+            self._client = fr
+            return self
+
+        async def aclose(self) -> None:
+            self._client = None
+
+    return _S()
+
+
+def _make_bus(
+    fr: fakeredis.aioredis.FakeRedis,
+) -> RedisMessageBus:
+    """Construct a :class:`RedisMessageBus` that talks to *fr*."""
+
+    class _B(RedisMessageBus):
+        async def __aenter__(  # type: ignore[override]
+            self,
+        ) -> "RedisMessageBus":
+            self._client = fr
+            return self
+
+        async def aclose(self) -> None:
+            self._client = None
+
+    return _B()
+
+
+def _make_agent_record(
+    user_id: str,
+    name: str,
+    source: str = "user",
+) -> AgentRecord:
+    """Build a minimal :class:`AgentRecord`."""
+    return AgentRecord(
+        user_id=user_id,
+        source=source,
+        data=AgentData(
+            name=name,
+            system_prompt=f"You are {name}.",
+            context_config=ContextConfig(),
+            react_config=ReActConfig(),
+        ),
+    )
+
+
+class _TeamToolsTestBase(IsolatedAsyncioTestCase):
+    """Shared fixture: a fakeredis-backed storage + bus, a leader
+    agent record, and a leader session.
+
+    Sub-classes set up their own teams / workers on top.
+    """
+
+    user_id = "u"
+
+    async def asyncSetUp(self) -> None:
+        self.fr = fakeredis.aioredis.FakeRedis(decode_responses=True)
+        self._stack = AsyncExitStack()
+        self.storage = await self._stack.enter_async_context(
+            _make_storage(self.fr),
+        )
+        self.bus = await self._stack.enter_async_context(_make_bus(self.fr))
+        self.workspace_manager = FakeWorkspaceManager()
+
+        # Leader agent + its session.
+        self.leader_agent = _make_agent_record(self.user_id, "leader")
+        await self.storage.upsert_agent(self.user_id, self.leader_agent)
+        self.leader_session = await self.storage.upsert_session(
+            user_id=self.user_id,
+            agent_id=self.leader_agent.id,
+            config=SessionConfig(workspace_id="ws"),
+        )
+
+    async def asyncTearDown(self) -> None:
+        await self._stack.aclose()
+        await self.fr.aclose()
+
+
+class TestTeamCreate(_TeamToolsTestBase):
+    """``TeamCreate`` creates a TeamRecord and stamps ``team_id`` on
+    the calling session."""
+
+    async def test_creates_team_and_stamps_session(self) -> None:
+        """A successful ``TeamCreate`` writes a TeamRecord and stamps the
+        leader's session with the new ``team_id``."""
+        tool = TeamCreate(
+            storage=self.storage,
+            message_bus=self.bus,
+            workspace_manager=self.workspace_manager,
+            user_id=self.user_id,
+            session_id=self.leader_session.id,
+            agent_id=self.leader_agent.id,
+        )
+        chunk = await tool(name="alpha", description="t-desc")
+
+        self.assertDictEqual(
+            chunk.model_dump(),
+            {
+                "content": [
+                    {"type": "text", "text": AnyString(), "id": AnyString()},
+                ],
+                "state": "running",
+                "is_last": True,
+                "metadata": {},
+                "id": AnyString(),
+            },
+        )
+        # A team exists and the leader's session now points at it.
+        sess = await self.storage.get_session(
+            self.user_id,
+            self.leader_agent.id,
+            self.leader_session.id,
+        )
+        self.assertIsNotNone(sess.team_id)
+        team = await self.storage.get_team(self.user_id, sess.team_id)
+        self.assertIsNotNone(team)
+        self.assertDictEqual(
+            {
+                "name": team.data.name,
+                "session_id": team.session_id,
+                "member_ids": team.data.member_ids,
+            },
+            {
+                "name": "alpha",
+                "session_id": self.leader_session.id,
+                "member_ids": [],
+            },
+        )
+
+    async def test_rejects_when_session_already_in_team(self) -> None:
+        """A session can lead at most one team."""
+        tool = TeamCreate(
+            storage=self.storage,
+            message_bus=self.bus,
+            workspace_manager=self.workspace_manager,
+            user_id=self.user_id,
+            session_id=self.leader_session.id,
+            agent_id=self.leader_agent.id,
+        )
+        await tool(name="first", description="d")
+        chunk = await tool(name="second", description="d")
+        self.assertDictEqual(
+            chunk.model_dump(),
+            {
+                "content": [
+                    {"type": "text", "text": AnyString(), "id": AnyString()},
+                ],
+                "state": "error",
+                "is_last": True,
+                "metadata": {},
+                "id": AnyString(),
+            },
+        )
+
+
+class TestAgentCreate(_TeamToolsTestBase):
+    """``AgentCreate`` spawns a worker agent + session, appends it to
+    the team, and delivers the initial prompt via inbox + wakeup."""
+
+    async def asyncSetUp(self) -> None:
+        await super().asyncSetUp()
+        # Pre-create a team so the leader has one to add to.
+        await TeamCreate(
+            storage=self.storage,
+            message_bus=self.bus,
+            workspace_manager=self.workspace_manager,
+            user_id=self.user_id,
+            session_id=self.leader_session.id,
+            agent_id=self.leader_agent.id,
+        )(name="team", description="team desc")
+
+    async def test_spawns_worker_and_delivers_initial_prompt(
+        self,
+    ) -> None:
+        """A successful ``AgentCreate`` adds the worker agent + session to
+        the team and delivers the initial prompt via inbox + wakeup."""
+        tool = AgentCreate(
+            storage=self.storage,
+            message_bus=self.bus,
+            workspace_manager=self.workspace_manager,
+            user_id=self.user_id,
+            session_id=self.leader_session.id,
+            agent_id=self.leader_agent.id,
+        )
+        chunk = await tool(
+            name="worker",
+            description="does research",
+            prompt="please look up X",
+        )
+        self.assertDictEqual(
+            chunk.model_dump(),
+            {
+                "content": [
+                    {"type": "text", "text": AnyString(), "id": AnyString()},
+                ],
+                "state": "running",
+                "is_last": True,
+                "metadata": {},
+                "id": AnyString(),
+            },
+        )
+
+        # Team has one member.
+        sess = await self.storage.get_session(
+            self.user_id,
+            self.leader_agent.id,
+            self.leader_session.id,
+        )
+        team = await self.storage.get_team(self.user_id, sess.team_id)
+        self.assertEqual(len(team.data.member_ids), 1)
+        worker_agent_id = team.data.member_ids[0]
+
+        # Worker agent exists with source=team.
+        worker_agent = await self.storage.get_agent(
+            self.user_id,
+            worker_agent_id,
+        )
+        self.assertEqual(
+            {"source": worker_agent.source, "name": worker_agent.data.name},
+            {"source": "team", "name": "worker"},
+        )
+
+        # Worker has exactly one session, marked with team_id.
+        worker_sessions = await self.storage.list_sessions(
+            self.user_id,
+            worker_agent_id,
+        )
+        self.assertEqual(len(worker_sessions), 1)
+        self.assertEqual(worker_sessions[0].team_id, sess.team_id)
+
+        # The initial prompt is in the worker's inbox as a HintBlock
+        # wrapped in a <team-message> tag.
+        inbox = await self.bus.inbox_drain(
+            worker_sessions[0].id,
+            max_count=10,
+        )
+        self.assertEqual(len(inbox), 1)
+        hint_payload = inbox[0][1]
+        self.assertDictEqual(
+            hint_payload,
+            {
+                "type": "hint",
+                "id": AnyString(),
+                "hint": AnyString(),
+                "source": '{"label": "team_message", "sublabel": "leader"}',
+            },
+        )
+        self.assertIn("please look up X", hint_payload["hint"])
+        self.assertIn("<team-message", hint_payload["hint"])
+
+        # A wakeup was enqueued for the worker.
+        wakeups = await self.bus.dequeue_wakeups(max_count=10)
+        self.assertEqual(len(wakeups), 1)
+        self.assertEqual(
+            wakeups[0],
+            {
+                "session_id": worker_sessions[0].id,
+                "agent_id": worker_agent_id,
+                "user_id": self.user_id,
+                "kind": "wake",
+                "input": None,
+            },
+        )
+
+    async def _spawn_worker_with_template(
+        self,
+        leader_state: AgentState,
+        template: SubAgentTemplate,
+        worker_name: str = "worker",
+    ) -> PermissionContext:
+        """Run ``AgentCreate`` with the given template + leader state
+        and return the worker session's :class:`PermissionContext`."""
+        tool = AgentCreate(
+            storage=self.storage,
+            message_bus=self.bus,
+            workspace_manager=self.workspace_manager,
+            user_id=self.user_id,
+            session_id=self.leader_session.id,
+            agent_id=self.leader_agent.id,
+            sub_agent_templates={template.type: template},
+        )
+        chunk = await tool(
+            name=worker_name,
+            description="does work",
+            prompt="work in the repo",
+            subagent_type=template.type,
+            _agent_state=leader_state,
+        )
+        self.assertEqual(chunk.state.value, "running")
+        sess = await self.storage.get_session(
+            self.user_id,
+            self.leader_agent.id,
+            self.leader_session.id,
+        )
+        team = await self.storage.get_team(self.user_id, sess.team_id)
+        # The worker is whichever member was added last.
+        worker_agent_id = team.data.member_ids[-1]
+        worker_sessions = await self.storage.list_sessions(
+            self.user_id,
+            worker_agent_id,
+        )
+        return worker_sessions[0].state.permission_context
+
+    def _make_leader_state(self) -> AgentState:
+        """Build a leader :class:`AgentState` with one of every kind of
+        permission entry, so tests can assert which pieces leak through
+        each flag."""
+        return AgentState(
+            permission_context=PermissionContext(
+                mode=PermissionMode.ACCEPT_EDITS,
+                working_directories={
+                    "/tmp/as-workspace": AdditionalWorkingDirectory(
+                        path="/tmp/as-workspace",
+                        source="session",
+                    ),
+                },
+                allow_rules={
+                    "Bash": [
+                        PermissionRule(
+                            tool_name="Bash",
+                            rule_content="git status",
+                            behavior=PermissionBehavior.ALLOW,
+                            source="session",
+                        ),
+                    ],
+                },
+            ),
+        )
+
+    async def test_default_template_follows_leader_completely(self) -> None:
+        """The built-in default template inherits the leader's mode,
+        working directories, and rules — its own
+        :attr:`permission_context` is empty, so the worker effectively
+        mirrors the leader."""
+        leader_state = self._make_leader_state()
+        worker_context = await self._spawn_worker_with_template(
+            leader_state,
+            DEFAULT_SUB_AGENT_TEMPLATE,
+        )
+        self.assertEqual(worker_context.mode, PermissionMode.ACCEPT_EDITS)
+        self.assertIn("/tmp/as-workspace", worker_context.working_directories)
+        self.assertEqual(
+            worker_context.allow_rules["Bash"][0].rule_content,
+            "git status",
+        )
+
+    async def test_override_leader_mode_pins_template_mode(self) -> None:
+        """When ``override_leader_mode=True`` the template's mode wins."""
+        leader_state = self._make_leader_state()
+        explorer = SubAgentTemplate(
+            type="explorer",
+            description="Read-only worker.",
+            system_prompt_template=(
+                DEFAULT_SUB_AGENT_TEMPLATE.system_prompt_template
+            ),
+            permission_context=PermissionContext(
+                mode=PermissionMode.EXPLORE,
+            ),
+            override_leader_mode=True,
+        )
+        worker_context = await self._spawn_worker_with_template(
+            leader_state,
+            explorer,
+        )
+        self.assertEqual(worker_context.mode, PermissionMode.EXPLORE)
+        # Rules and dirs still inherited (defaults).
+        self.assertIn("/tmp/as-workspace", worker_context.working_directories)
+        self.assertIn("Bash", worker_context.allow_rules)
+
+    async def test_extend_flags_off_isolate_template(self) -> None:
+        """``extend_*=False`` keeps the leader's rules and dirs out of
+        the worker; the template's own entries are the worker's
+        complete set."""
+        leader_state = self._make_leader_state()
+        sandbox = SubAgentTemplate(
+            type="sandbox",
+            description="Fully isolated worker.",
+            system_prompt_template=(
+                DEFAULT_SUB_AGENT_TEMPLATE.system_prompt_template
+            ),
+            permission_context=PermissionContext(
+                mode=PermissionMode.BYPASS,
+                deny_rules={
+                    "Write": [
+                        PermissionRule(
+                            tool_name="Write",
+                            rule_content=None,
+                            behavior=PermissionBehavior.DENY,
+                            source="template",
+                        ),
+                    ],
+                },
+            ),
+            override_leader_mode=True,
+            extend_leader_permission_rules=False,
+            extend_leader_working_directories=False,
+        )
+        worker_context = await self._spawn_worker_with_template(
+            leader_state,
+            sandbox,
+        )
+        self.assertEqual(worker_context.mode, PermissionMode.BYPASS)
+        self.assertEqual(worker_context.working_directories, {})
+        self.assertNotIn("Bash", worker_context.allow_rules)
+        # Template's own deny rule is preserved.
+        self.assertEqual(
+            worker_context.deny_rules["Write"][0].source,
+            "template",
+        )
+
+    async def test_extend_rules_keeps_template_rules_first(self) -> None:
+        """When merging rules for the same tool, the template's rules
+        appear first in the list so the engine evaluates them before
+        the leader's."""
+        leader_state = AgentState(
+            permission_context=PermissionContext(
+                mode=PermissionMode.DEFAULT,
+                allow_rules={
+                    "Bash": [
+                        PermissionRule(
+                            tool_name="Bash",
+                            rule_content="git status",
+                            behavior=PermissionBehavior.ALLOW,
+                            source="session",
+                        ),
+                    ],
+                },
+            ),
+        )
+        template = SubAgentTemplate(
+            type="custom",
+            description="Custom worker.",
+            system_prompt_template=(
+                DEFAULT_SUB_AGENT_TEMPLATE.system_prompt_template
+            ),
+            permission_context=PermissionContext(
+                allow_rules={
+                    "Bash": [
+                        PermissionRule(
+                            tool_name="Bash",
+                            rule_content="ls",
+                            behavior=PermissionBehavior.ALLOW,
+                            source="template",
+                        ),
+                    ],
+                },
+            ),
+        )
+        worker_context = await self._spawn_worker_with_template(
+            leader_state,
+            template,
+        )
+        bash_rules = worker_context.allow_rules["Bash"]
+        self.assertEqual(
+            [r.source for r in bash_rules],
+            ["template", "session"],
+        )
+
+    async def test_extend_dirs_template_wins_on_collision(self) -> None:
+        """When the template and leader both declare the same working
+        directory path, the template's entry is kept."""
+        leader_state = AgentState(
+            permission_context=PermissionContext(
+                working_directories={
+                    "/tmp/shared": AdditionalWorkingDirectory(
+                        path="/tmp/shared",
+                        source="session",
+                    ),
+                },
+            ),
+        )
+        template = SubAgentTemplate(
+            type="custom",
+            description="Custom worker.",
+            system_prompt_template=(
+                DEFAULT_SUB_AGENT_TEMPLATE.system_prompt_template
+            ),
+            permission_context=PermissionContext(
+                working_directories={
+                    "/tmp/shared": AdditionalWorkingDirectory(
+                        path="/tmp/shared",
+                        source="template",
+                    ),
+                },
+            ),
+        )
+        worker_context = await self._spawn_worker_with_template(
+            leader_state,
+            template,
+        )
+        self.assertEqual(
+            worker_context.working_directories["/tmp/shared"].source,
+            "template",
+        )
+
+    async def test_rejects_when_not_in_team(self) -> None:
+        """Calling ``AgentCreate`` from a session that hasn't run
+        ``TeamCreate`` yet returns an error chunk."""
+        # Build a second leader session that is NOT in any team.
+        loner_session = await self.storage.upsert_session(
+            user_id=self.user_id,
+            agent_id=self.leader_agent.id,
+            config=SessionConfig(workspace_id="ws2"),
+        )
+        tool = AgentCreate(
+            storage=self.storage,
+            message_bus=self.bus,
+            workspace_manager=self.workspace_manager,
+            user_id=self.user_id,
+            session_id=loner_session.id,
+            agent_id=self.leader_agent.id,
+        )
+        chunk = await tool(
+            name="worker",
+            description="d",
+            prompt="p",
+        )
+        self.assertDictEqual(
+            chunk.model_dump(),
+            {
+                "content": [
+                    {"type": "text", "text": AnyString(), "id": AnyString()},
+                ],
+                "state": "error",
+                "is_last": True,
+                "metadata": {},
+                "id": AnyString(),
+            },
+        )
+
+    async def test_rejects_unknown_subagent_type(self) -> None:
+        """An unrecognised ``subagent_type`` returns an error chunk."""
+        tool = AgentCreate(
+            storage=self.storage,
+            message_bus=self.bus,
+            workspace_manager=self.workspace_manager,
+            user_id=self.user_id,
+            session_id=self.leader_session.id,
+            agent_id=self.leader_agent.id,
+        )
+        chunk = await tool(
+            name="w",
+            description="d",
+            prompt="p",
+            subagent_type="not-a-type",
+        )
+        self.assertDictEqual(
+            chunk.model_dump(),
+            {
+                "content": [
+                    {"type": "text", "text": AnyString(), "id": AnyString()},
+                ],
+                "state": "error",
+                "is_last": True,
+                "metadata": {},
+                "id": AnyString(),
+            },
+        )
+
+    async def test_rejects_duplicate_member_name(self) -> None:
+        """Two ``AgentCreate`` calls with the same ``name`` is rejected:
+        TeamSay routes by name, so duplicates would be ambiguous."""
+        tool = AgentCreate(
+            storage=self.storage,
+            message_bus=self.bus,
+            workspace_manager=self.workspace_manager,
+            user_id=self.user_id,
+            session_id=self.leader_session.id,
+            agent_id=self.leader_agent.id,
+        )
+        first = await tool(
+            name="worker",
+            description="d",
+            prompt="p",
+        )
+        self.assertEqual(first.state.value, "running")
+
+        second = await tool(
+            name="worker",
+            description="d",
+            prompt="p",
+        )
+        self.assertEqual(second.state.value, "error")
+
+        # The team still only has one member — the second call did not
+        # persist anything.
+        sess = await self.storage.get_session(
+            self.user_id,
+            self.leader_agent.id,
+            self.leader_session.id,
+        )
+        team = await self.storage.get_team(self.user_id, sess.team_id)
+        self.assertEqual(len(team.data.member_ids), 1)
+
+    async def test_rejects_member_name_colliding_with_leader(self) -> None:
+        """A worker name that matches the leader's name is rejected —
+        ``TeamSay(to=<leader name>)`` must remain unambiguous."""
+        tool = AgentCreate(
+            storage=self.storage,
+            message_bus=self.bus,
+            workspace_manager=self.workspace_manager,
+            user_id=self.user_id,
+            session_id=self.leader_session.id,
+            agent_id=self.leader_agent.id,
+        )
+        chunk = await tool(
+            name=self.leader_agent.data.name,  # "leader"
+            description="d",
+            prompt="p",
+        )
+        self.assertEqual(chunk.state.value, "error")
+
+        # No worker was added.
+        sess = await self.storage.get_session(
+            self.user_id,
+            self.leader_agent.id,
+            self.leader_session.id,
+        )
+        team = await self.storage.get_team(self.user_id, sess.team_id)
+        self.assertEqual(team.data.member_ids, [])
+
+
+class TestAgentCreateTemplates(_TeamToolsTestBase):
+    """Template-aware ``AgentCreate`` behaviour: schema dynamics,
+    template routing, and config isolation."""
+
+    _explorer_template = SubAgentTemplate(
+        type="explorer",
+        description="Read-only exploration agent.",
+        system_prompt_template=(
+            "You are {member_name}, an explorer in team "
+            "'{team_name}' led by {leader_name}.\n\n"
+            "Team purpose: {team_description}\n\n"
+            "Your role: {member_description}"
+        ),
+    )
+
+    async def asyncSetUp(self) -> None:
+        await super().asyncSetUp()
+        await TeamCreate(
+            storage=self.storage,
+            message_bus=self.bus,
+            workspace_manager=self.workspace_manager,
+            user_id=self.user_id,
+            session_id=self.leader_session.id,
+            agent_id=self.leader_agent.id,
+        )(name="team", description="team desc")
+
+    async def test_schema_omits_subagent_type_when_no_custom_templates(
+        self,
+    ) -> None:
+        """When only the built-in ``"default"`` template exists, the
+        ``input_schema`` must NOT contain a ``subagent_type`` field."""
+        tool = AgentCreate(
+            storage=self.storage,
+            message_bus=self.bus,
+            workspace_manager=self.workspace_manager,
+            user_id=self.user_id,
+            session_id=self.leader_session.id,
+            agent_id=self.leader_agent.id,
+        )
+        self.assertNotIn("subagent_type", tool.input_schema["properties"])
+
+    async def test_schema_includes_subagent_type_with_custom_templates(
+        self,
+    ) -> None:
+        """When custom templates are registered, ``subagent_type`` appears
+        in the schema with the correct enum values."""
+        templates = {"explorer": self._explorer_template}
+        tool = AgentCreate(
+            storage=self.storage,
+            message_bus=self.bus,
+            workspace_manager=self.workspace_manager,
+            user_id=self.user_id,
+            session_id=self.leader_session.id,
+            agent_id=self.leader_agent.id,
+            sub_agent_templates=templates,
+        )
+        self.assertIn("subagent_type", tool.input_schema["properties"])
+        enum_values = tool.input_schema["properties"]["subagent_type"]["enum"]
+        self.assertIn("default", enum_values)
+        self.assertIn("explorer", enum_values)
+
+    async def test_default_template_injected_when_missing(self) -> None:
+        """The built-in default template is always available even when
+        only custom templates are provided."""
+        templates = {"explorer": self._explorer_template}
+        tool = AgentCreate(
+            storage=self.storage,
+            message_bus=self.bus,
+            workspace_manager=self.workspace_manager,
+            user_id=self.user_id,
+            session_id=self.leader_session.id,
+            agent_id=self.leader_agent.id,
+            sub_agent_templates=templates,
+        )
+        self.assertIn("default", tool._sub_agent_templates)
+        self.assertIs(
+            tool._sub_agent_templates["default"],
+            DEFAULT_SUB_AGENT_TEMPLATE,
+        )
+
+    async def test_custom_template_applies_system_prompt(self) -> None:
+        """A worker created with a custom template gets the template's
+        system prompt (not the default one)."""
+        templates = {"explorer": self._explorer_template}
+        tool = AgentCreate(
+            storage=self.storage,
+            message_bus=self.bus,
+            workspace_manager=self.workspace_manager,
+            user_id=self.user_id,
+            session_id=self.leader_session.id,
+            agent_id=self.leader_agent.id,
+            sub_agent_templates=templates,
+        )
+        chunk = await tool(
+            name="scout",
+            description="explores code",
+            prompt="look around",
+            subagent_type="explorer",
+        )
+        self.assertEqual(chunk.state.value, "running")
+
+        sess = await self.storage.get_session(
+            self.user_id,
+            self.leader_agent.id,
+            self.leader_session.id,
+        )
+        team = await self.storage.get_team(self.user_id, sess.team_id)
+        worker_agent = await self.storage.get_agent(
+            self.user_id,
+            team.data.member_ids[0],
+        )
+        self.assertIn("an explorer in team", worker_agent.data.system_prompt)
+        self.assertNotIn(
+            "You communicate with the team leader",
+            worker_agent.data.system_prompt,
+        )
+
+    async def test_configs_are_deep_copied(self) -> None:
+        """Each spawned worker receives its own copy of the template's
+        config objects — mutations must not leak across agents."""
+        templates = {"explorer": self._explorer_template}
+        tool = AgentCreate(
+            storage=self.storage,
+            message_bus=self.bus,
+            workspace_manager=self.workspace_manager,
+            user_id=self.user_id,
+            session_id=self.leader_session.id,
+            agent_id=self.leader_agent.id,
+            sub_agent_templates=templates,
+        )
+        await tool(
+            name="w1",
+            description="d",
+            prompt="p",
+            subagent_type="explorer",
+        )
+        await tool(
+            name="w2",
+            description="d",
+            prompt="p",
+            subagent_type="explorer",
+        )
+
+        sess = await self.storage.get_session(
+            self.user_id,
+            self.leader_agent.id,
+            self.leader_session.id,
+        )
+        team = await self.storage.get_team(self.user_id, sess.team_id)
+        a1 = await self.storage.get_agent(
+            self.user_id,
+            team.data.member_ids[0],
+        )
+        a2 = await self.storage.get_agent(
+            self.user_id,
+            team.data.member_ids[1],
+        )
+        self.assertIsNot(
+            a1.data.context_config,
+            a2.data.context_config,
+        )
+        self.assertIsNot(
+            a1.data.react_config,
+            a2.data.react_config,
+        )
+
+
+class TestTeamSay(_TeamToolsTestBase):
+    """``TeamSay`` delivers a HintBlock + wakeup to each addressed
+    teammate."""
+
+    async def asyncSetUp(self) -> None:
+        await super().asyncSetUp()
+        await TeamCreate(
+            storage=self.storage,
+            message_bus=self.bus,
+            workspace_manager=self.workspace_manager,
+            user_id=self.user_id,
+            session_id=self.leader_session.id,
+            agent_id=self.leader_agent.id,
+        )(name="team", description="team desc")
+        # Add 2 workers.
+        agent_create = AgentCreate(
+            storage=self.storage,
+            message_bus=self.bus,
+            workspace_manager=self.workspace_manager,
+            user_id=self.user_id,
+            session_id=self.leader_session.id,
+            agent_id=self.leader_agent.id,
+        )
+        await agent_create(
+            name="w1",
+            description="d",
+            prompt="p1",
+        )
+        await agent_create(
+            name="w2",
+            description="d",
+            prompt="p2",
+        )
+        # Drain the pre-existing wakeups so subsequent assertions only
+        # see what TeamSay enqueues.
+        await self.bus.dequeue_wakeups(max_count=100)
+        # Resolve worker IDs.
+        sess = await self.storage.get_session(
+            self.user_id,
+            self.leader_agent.id,
+            self.leader_session.id,
+        )
+        team = await self.storage.get_team(self.user_id, sess.team_id)
+        self.worker_ids = team.data.member_ids
+        self.worker_sessions = {}
+        for aid in self.worker_ids:
+            ss = await self.storage.list_sessions(self.user_id, aid)
+            self.worker_sessions[aid] = ss[0].id
+            # Drain initial-prompt hints too.
+            await self.bus.inbox_drain(ss[0].id, max_count=100)
+
+    async def test_targeted_message_delivers_to_one(self) -> None:
+        """``to=<member name>`` delivers a HintBlock + wakeup to that worker
+        only; other team members see nothing."""
+        tool = TeamSay(
+            storage=self.storage,
+            message_bus=self.bus,
+            workspace_manager=self.workspace_manager,
+            user_id=self.user_id,
+            session_id=self.leader_session.id,
+            agent_id=self.leader_agent.id,
+            role="leader",
+        )
+        target_aid = self.worker_ids[0]
+        target_agent = await self.storage.get_agent(
+            self.user_id,
+            target_aid,
+        )
+        chunk = await tool(content="hi w1", to=target_agent.data.name)
+        self.assertDictEqual(
+            chunk.model_dump(),
+            {
+                "content": [
+                    {"type": "text", "text": AnyString(), "id": AnyString()},
+                ],
+                "state": "running",
+                "is_last": True,
+                "metadata": {},
+                "id": AnyString(),
+            },
+        )
+
+        # Inbox of target has the hint; the other worker's inbox stays
+        # empty.
+        target_sid = self.worker_sessions[target_aid]
+        other_sid = self.worker_sessions[self.worker_ids[1]]
+        target_inbox = await self.bus.inbox_drain(target_sid, max_count=10)
+        other_inbox = await self.bus.inbox_drain(other_sid, max_count=10)
+        self.assertEqual(len(target_inbox), 1)
+        self.assertEqual(len(other_inbox), 0)
+        self.assertDictEqual(
+            target_inbox[0][1],
+            {
+                "type": "hint",
+                "id": AnyString(),
+                "hint": AnyString(),
+                "source": AnyString(),
+            },
+        )
+        self.assertIn("hi w1", target_inbox[0][1]["hint"])
+
+        # Wakeup for the target only.
+        wakeups = await self.bus.dequeue_wakeups(max_count=10)
+        self.assertEqual(
+            wakeups,
+            [
+                {
+                    "session_id": target_sid,
+                    "agent_id": target_aid,
+                    "user_id": self.user_id,
+                    "kind": "wake",
+                    "input": None,
+                },
+            ],
+        )
+
+    async def test_broadcast_delivers_to_all_others(self) -> None:
+        """``to=None`` broadcasts to everyone in the team except the
+        sender."""
+        tool = TeamSay(
+            storage=self.storage,
+            message_bus=self.bus,
+            workspace_manager=self.workspace_manager,
+            user_id=self.user_id,
+            session_id=self.leader_session.id,
+            agent_id=self.leader_agent.id,
+            role="leader",
+        )
+        chunk = await tool(content="all hands", to=None)
+        self.assertDictEqual(
+            chunk.model_dump(),
+            {
+                "content": [
+                    {"type": "text", "text": AnyString(), "id": AnyString()},
+                ],
+                "state": "running",
+                "is_last": True,
+                "metadata": {},
+                "id": AnyString(),
+            },
+        )
+
+        # Both workers receive; leader doesn't loopback to itself.
+        for aid, sid in self.worker_sessions.items():
+            inbox = await self.bus.inbox_drain(sid, max_count=10)
+            self.assertEqual(
+                len(inbox),
+                1,
+                f"worker {aid} missed broadcast",
+            )
+        leader_inbox = await self.bus.inbox_drain(
+            self.leader_session.id,
+            max_count=10,
+        )
+        self.assertEqual(leader_inbox, [])
+
+        wakeups = await self.bus.dequeue_wakeups(max_count=10)
+        self.assertEqual(len(wakeups), 2)
+
+    async def test_rejects_when_session_not_in_team(self) -> None:
+        """A session without a team can't TeamSay."""
+        loner_session = await self.storage.upsert_session(
+            user_id=self.user_id,
+            agent_id=self.leader_agent.id,
+            config=SessionConfig(workspace_id="ws-lone"),
+        )
+        tool = TeamSay(
+            storage=self.storage,
+            message_bus=self.bus,
+            workspace_manager=self.workspace_manager,
+            user_id=self.user_id,
+            session_id=loner_session.id,
+            agent_id=self.leader_agent.id,
+            role="leader",
+        )
+        chunk = await tool(content="hi", to=None)
+        self.assertDictEqual(
+            chunk.model_dump(),
+            {
+                "content": [
+                    {"type": "text", "text": AnyString(), "id": AnyString()},
+                ],
+                "state": "error",
+                "is_last": True,
+                "metadata": {},
+                "id": AnyString(),
+            },
+        )
+
+    async def test_rejects_unknown_recipient(self) -> None:
+        """A ``to=`` that doesn't resolve to a team member name returns
+        an error chunk."""
+        tool = TeamSay(
+            storage=self.storage,
+            message_bus=self.bus,
+            workspace_manager=self.workspace_manager,
+            user_id=self.user_id,
+            session_id=self.leader_session.id,
+            agent_id=self.leader_agent.id,
+            role="leader",
+        )
+        chunk = await tool(content="hi", to="ghost-name-not-in-team")
+        self.assertDictEqual(
+            chunk.model_dump(),
+            {
+                "content": [
+                    {"type": "text", "text": AnyString(), "id": AnyString()},
+                ],
+                "state": "error",
+                "is_last": True,
+                "metadata": {},
+                "id": AnyString(),
+            },
+        )
+
+    async def test_rejects_self_target(self) -> None:
+        """``to=<own name>`` is rejected — talk to yourself in
+        reasoning, not via TeamSay."""
+        tool = TeamSay(
+            storage=self.storage,
+            message_bus=self.bus,
+            workspace_manager=self.workspace_manager,
+            user_id=self.user_id,
+            session_id=self.leader_session.id,
+            agent_id=self.leader_agent.id,
+            role="leader",
+        )
+        chunk = await tool(content="hi", to=self.leader_agent.data.name)
+        self.assertDictEqual(
+            chunk.model_dump(),
+            {
+                "content": [
+                    {"type": "text", "text": AnyString(), "id": AnyString()},
+                ],
+                "state": "error",
+                "is_last": True,
+                "metadata": {},
+                "id": AnyString(),
+            },
+        )
+
+    async def test_worker_can_address_leader_by_name(self) -> None:
+        """A worker constructed with ``role="worker"`` can address the
+        leader using the leader's name — the only identifier a worker
+        ever has for the leader (received via the ``from=`` attribute
+        of the initial ``<team-message>`` hint)."""
+        worker_aid = self.worker_ids[0]
+        worker_sid = self.worker_sessions[worker_aid]
+
+        tool = TeamSay(
+            storage=self.storage,
+            message_bus=self.bus,
+            workspace_manager=self.workspace_manager,
+            user_id=self.user_id,
+            session_id=worker_sid,
+            agent_id=worker_aid,
+            role="worker",
+        )
+        chunk = await tool(
+            content="task done",
+            to=self.leader_agent.data.name,
+        )
+        self.assertEqual(chunk.state.value, "running")
+
+        # Leader's inbox received the worker's reply.
+        leader_inbox = await self.bus.inbox_drain(
+            self.leader_session.id,
+            max_count=10,
+        )
+        self.assertEqual(len(leader_inbox), 1)
+        self.assertIn("task done", leader_inbox[0][1]["hint"])
+
+        # Wakeup was enqueued for the leader.
+        wakeups = await self.bus.dequeue_wakeups(max_count=10)
+        self.assertEqual(
+            wakeups,
+            [
+                {
+                    "session_id": self.leader_session.id,
+                    "agent_id": self.leader_agent.id,
+                    "user_id": self.user_id,
+                    "kind": "wake",
+                    "input": None,
+                },
+            ],
+        )
+
+
+class TestTeamDelete(_TeamToolsTestBase):
+    """``TeamDelete`` dissolves the team and clears the leader's
+    ``team_id``."""
+
+    async def asyncSetUp(self) -> None:
+        await super().asyncSetUp()
+        await TeamCreate(
+            storage=self.storage,
+            message_bus=self.bus,
+            workspace_manager=self.workspace_manager,
+            user_id=self.user_id,
+            session_id=self.leader_session.id,
+            agent_id=self.leader_agent.id,
+        )(name="team", description="d")
+
+    async def test_dissolves_team_from_leader(self) -> None:
+        """``TeamDelete`` removes the team and clears the leader's
+        ``team_id``."""
+        tool = TeamDelete(
+            storage=self.storage,
+            message_bus=self.bus,
+            workspace_manager=self.workspace_manager,
+            user_id=self.user_id,
+            session_id=self.leader_session.id,
+            agent_id=self.leader_agent.id,
+        )
+        chunk = await tool()
+        self.assertDictEqual(
+            chunk.model_dump(),
+            {
+                "content": [
+                    {"type": "text", "text": AnyString(), "id": AnyString()},
+                ],
+                "state": "running",
+                "is_last": True,
+                "metadata": {},
+                "id": AnyString(),
+            },
+        )
+
+        sess = await self.storage.get_session(
+            self.user_id,
+            self.leader_agent.id,
+            self.leader_session.id,
+        )
+        self.assertIsNone(sess.team_id)
+
+    async def test_rejects_when_not_in_team(self) -> None:
+        """Calling ``TeamDelete`` from a session that isn't in any team
+        returns an error chunk."""
+        loner_session = await self.storage.upsert_session(
+            user_id=self.user_id,
+            agent_id=self.leader_agent.id,
+            config=SessionConfig(workspace_id="ws-lone"),
+        )
+        tool = TeamDelete(
+            storage=self.storage,
+            message_bus=self.bus,
+            workspace_manager=self.workspace_manager,
+            user_id=self.user_id,
+            session_id=loner_session.id,
+            agent_id=self.leader_agent.id,
+        )
+        chunk = await tool()
+        self.assertDictEqual(
+            chunk.model_dump(),
+            {
+                "content": [
+                    {"type": "text", "text": AnyString(), "id": AnyString()},
+                ],
+                "state": "error",
+                "is_last": True,
+                "metadata": {},
+                "id": AnyString(),
+            },
+        )
+
+
+# ----------------------------------------------------------------------
+# AgentInvite tests
+# ----------------------------------------------------------------------
+
+
+class TestAgentDataInvitableValidator(IsolatedAsyncioTestCase):
+    """:class:`InviteConfig`'s cross-field validator rejects
+    ``invitable=True`` without a non-empty ``invite_description`` at
+    model boundary so PATCH / POST return HTTP 422 automatically."""
+
+    async def test_invitable_requires_description(self) -> None:
+        """``invitable=True`` with empty description fails validation."""
+        from pydantic import ValidationError
+        from agentscope.app.storage._model._agent import InviteConfig
+
+        with self.assertRaises(ValidationError):
+            AgentData(
+                name="x",
+                context_config=ContextConfig(),
+                react_config=ReActConfig(),
+                invite_config=InviteConfig(
+                    invitable=True,
+                    invite_description=None,
+                ),
+            )
+        with self.assertRaises(ValidationError):
+            AgentData(
+                name="x",
+                context_config=ContextConfig(),
+                react_config=ReActConfig(),
+                invite_config=InviteConfig(
+                    invitable=True,
+                    invite_description="   ",
+                ),
+            )
+
+    async def test_invitable_off_keeps_description(self) -> None:
+        """Draft description is preserved when ``invitable=False``."""
+        from agentscope.app.storage._model._agent import InviteConfig
+
+        data = AgentData(
+            name="x",
+            context_config=ContextConfig(),
+            react_config=ReActConfig(),
+            invite_config=InviteConfig(
+                invitable=False,
+                invite_description="draft",
+            ),
+        )
+        self.assertEqual(data.invite_config.invite_description, "draft")
+        self.assertFalse(data.invite_config.invitable)
+
+
+class _AgentInviteTestBase(_TeamToolsTestBase):
+    """Fixture: leader in a team + one invitable "Monday" agent with
+    a primary session so ``AgentInvite`` has something to borrow."""
+
+    async def asyncSetUp(self) -> None:
+        await super().asyncSetUp()
+        # Leader creates a team.
+        await TeamCreate(
+            storage=self.storage,
+            message_bus=self.bus,
+            workspace_manager=self.workspace_manager,
+            user_id=self.user_id,
+            session_id=self.leader_session.id,
+            agent_id=self.leader_agent.id,
+        )(name="team", description="d")
+
+        # A pre-existing invitable user-owned agent.
+        from agentscope.app.storage._model._agent import InviteConfig
+
+        self.monday_agent = AgentRecord(
+            user_id=self.user_id,
+            source="user",
+            data=AgentData(
+                name="Monday",
+                system_prompt="I am Monday.",
+                context_config=ContextConfig(),
+                react_config=ReActConfig(),
+                invite_config=InviteConfig(
+                    invitable=True,
+                    invite_description="Expert on X.",
+                ),
+            ),
+        )
+        await self.storage.upsert_agent(self.user_id, self.monday_agent)
+        self.monday_session = await self.storage.upsert_session(
+            user_id=self.user_id,
+            agent_id=self.monday_agent.id,
+            config=SessionConfig(workspace_id="ws-monday"),
+        )
+
+
+class TestAgentInviteSuccess(_AgentInviteTestBase):
+    """Happy-path: leader borrows Monday; borrowed session is minted
+    on top of Monday's existing AgentRecord and joins the team as an
+    invited member."""
+
+    async def test_invites_existing_agent(self) -> None:
+        """A successful ``AgentInvite`` mints a fresh session on the
+        invited agent, tags it invited in the team roster, and delivers
+        the initial prompt via inbox + wakeup."""
+        pool = [self.monday_agent]
+        tool = AgentInvite(
+            storage=self.storage,
+            message_bus=self.bus,
+            workspace_manager=self.workspace_manager,
+            user_id=self.user_id,
+            session_id=self.leader_session.id,
+            agent_id=self.leader_agent.id,
+            invitable_pool=pool,
+        )
+        target = f"Monday@{self.monday_agent.id[:8]}"
+        chunk = await tool(target=target, prompt="please look up X")
+        self.assertDictEqual(
+            chunk.model_dump(),
+            {
+                "content": [
+                    {"type": "text", "text": AnyString(), "id": AnyString()},
+                ],
+                "state": "running",
+                "is_last": True,
+                "metadata": {},
+                "id": AnyString(),
+            },
+        )
+
+        # No new AgentRecord — the invited agent's id is reused.
+        agents = await self.storage.list_agents(self.user_id)
+        agent_ids = {a.id for a in agents}
+        self.assertIn(self.monday_agent.id, agent_ids)
+        # Only leader + Monday exist (no team-spawned worker record).
+        self.assertEqual(len(agents), 2)
+
+        # Team now has exactly one invited member pointing at Monday.
+        sess = await self.storage.get_session(
+            self.user_id,
+            self.leader_agent.id,
+            self.leader_session.id,
+        )
+        team = await self.storage.get_team(self.user_id, sess.team_id)
+        self.assertEqual(len(team.data.members), 1)
+        member = team.data.members[0]
+        self.assertEqual(member.role, "invited")
+        self.assertEqual(member.agent_id, self.monday_agent.id)
+        self.assertEqual(member.owner_id, self.user_id)
+
+        # The borrowed session is distinct from Monday's primary
+        # session but inherits its workspace_id.
+        self.assertNotEqual(member.session_id, self.monday_session.id)
+        borrowed = await self.storage.get_session(
+            self.user_id,
+            self.monday_agent.id,
+            member.session_id,
+        )
+        self.assertEqual(borrowed.config.workspace_id, "ws-monday")
+        self.assertEqual(borrowed.team_id, team.id)
+
+        # Borrowed session starts with a fresh PermissionContext —
+        # no leader / Monday state carried over.
+        self.assertEqual(
+            borrowed.state.permission_context,
+            PermissionContext(),
+        )
+
+        # Initial prompt was delivered to the borrowed session only.
+        inbox = await self.bus.inbox_drain(member.session_id, max_count=10)
+        self.assertEqual(len(inbox), 1)
+        self.assertIn("please look up X", inbox[0][1]["hint"])
+        # Monday's primary session inbox is untouched.
+        primary_inbox = await self.bus.inbox_drain(
+            self.monday_session.id,
+            max_count=10,
+        )
+        self.assertEqual(primary_inbox, [])
+
+
+class TestAgentInviteRejections(_AgentInviteTestBase):
+    """``AgentInvite`` rejects the obvious bad inputs / states."""
+
+    _EXPECTED_ERROR_CHUNK = {
+        "content": [
+            {"type": "text", "text": AnyString(), "id": AnyString()},
+        ],
+        "state": "error",
+        "is_last": True,
+        "metadata": {},
+        "id": AnyString(),
+    }
+
+    def _tool(self, pool: list | None = None) -> AgentInvite:
+        """Build an :class:`AgentInvite` bound to the leader session."""
+        return AgentInvite(
+            storage=self.storage,
+            message_bus=self.bus,
+            workspace_manager=self.workspace_manager,
+            user_id=self.user_id,
+            session_id=self.leader_session.id,
+            agent_id=self.leader_agent.id,
+            invitable_pool=pool or [self.monday_agent],
+        )
+
+    async def test_rejects_malformed_target(self) -> None:
+        """A ``target`` without an ``@`` separator is rejected."""
+        chunk = await self._tool()(target="just-a-name", prompt="hi")
+        self.assertDictEqual(chunk.model_dump(), self._EXPECTED_ERROR_CHUNK)
+
+    async def test_rejects_unknown_handle(self) -> None:
+        """A syntactically-valid ``target`` whose handle prefix does
+        not match any agent in the pool is rejected."""
+        chunk = await self._tool()(
+            target="Monday@deadbeef",
+            prompt="hi",
+        )
+        self.assertDictEqual(chunk.model_dump(), self._EXPECTED_ERROR_CHUNK)
+
+    async def test_rejects_when_no_longer_invitable(self) -> None:
+        """Snapshot said invitable but fresh read shows the toggle off."""
+        # Flip the toggle off in storage while pool snapshot still has it.
+        stale = self.monday_agent
+        stale.data.invite_config.invitable = False
+        stale.data.invite_config.invite_description = None
+        await self.storage.upsert_agent(self.user_id, stale)
+
+        chunk = await self._tool(pool=[stale])(
+            target=f"Monday@{stale.id[:8]}",
+            prompt="hi",
+        )
+        self.assertDictEqual(chunk.model_dump(), self._EXPECTED_ERROR_CHUNK)
+
+    async def test_rejects_when_not_leader(self) -> None:
+        """A session that has no team can't invite."""
+        loner = await self.storage.upsert_session(
+            user_id=self.user_id,
+            agent_id=self.leader_agent.id,
+            config=SessionConfig(workspace_id="ws-lone"),
+        )
+        tool = AgentInvite(
+            storage=self.storage,
+            message_bus=self.bus,
+            workspace_manager=self.workspace_manager,
+            user_id=self.user_id,
+            session_id=loner.id,
+            agent_id=self.leader_agent.id,
+            invitable_pool=[self.monday_agent],
+        )
+        chunk = await tool(
+            target=f"Monday@{self.monday_agent.id[:8]}",
+            prompt="hi",
+        )
+        self.assertDictEqual(chunk.model_dump(), self._EXPECTED_ERROR_CHUNK)
+
+    async def test_rejects_duplicate_borrow(self) -> None:
+        """One team, one borrow per agent."""
+        tool = self._tool()
+        await tool(
+            target=f"Monday@{self.monday_agent.id[:8]}",
+            prompt="task 1",
+        )
+        chunk = await tool(
+            target=f"Monday@{self.monday_agent.id[:8]}",
+            prompt="task 2",
+        )
+        self.assertDictEqual(chunk.model_dump(), self._EXPECTED_ERROR_CHUNK)
+
+
+class TestTeamSayInvitedRouting(_AgentInviteTestBase):
+    """``TeamSay`` reaches the borrowed session using the ``@handle``
+    display string, and the invited agent can reply back."""
+
+    async def asyncSetUp(self) -> None:
+        await super().asyncSetUp()
+        # Borrow Monday.
+        await AgentInvite(
+            storage=self.storage,
+            message_bus=self.bus,
+            workspace_manager=self.workspace_manager,
+            user_id=self.user_id,
+            session_id=self.leader_session.id,
+            agent_id=self.leader_agent.id,
+            invitable_pool=[self.monday_agent],
+        )(target=f"Monday@{self.monday_agent.id[:8]}", prompt="join")
+
+        sess = await self.storage.get_session(
+            self.user_id,
+            self.leader_agent.id,
+            self.leader_session.id,
+        )
+        team = await self.storage.get_team(self.user_id, sess.team_id)
+        self.borrowed_sid = next(
+            m.session_id for m in team.data.members if m.role == "invited"
+        )
+        # Drain the initial "join" prompt so later inbox checks see
+        # only the subsequent TeamSay delivery.
+        await self.bus.inbox_drain(self.borrowed_sid, max_count=10)
+        await self.bus.dequeue_wakeups(max_count=10)
+
+    async def test_leader_addresses_invited_by_display(self) -> None:
+        """Leader's ``TeamSay(to="Monday@<prefix>")`` reaches the
+        borrowed session — not Monday's primary session."""
+        display = f"Monday@{self.monday_agent.id[:8]}"
+        tool = TeamSay(
+            storage=self.storage,
+            message_bus=self.bus,
+            workspace_manager=self.workspace_manager,
+            user_id=self.user_id,
+            session_id=self.leader_session.id,
+            agent_id=self.leader_agent.id,
+            role="leader",
+        )
+        chunk = await tool(content="hey", to=display)
+        self.assertEqual(chunk.state.value, "running")
+
+        borrowed_inbox = await self.bus.inbox_drain(
+            self.borrowed_sid,
+            max_count=10,
+        )
+        self.assertEqual(len(borrowed_inbox), 1)
+        primary_inbox = await self.bus.inbox_drain(
+            self.monday_session.id,
+            max_count=10,
+        )
+        self.assertEqual(primary_inbox, [])
+
+
+class TestTeamDeletePreservesInvited(_AgentInviteTestBase):
+    """``TeamDelete`` removes the borrowed session but preserves the
+    invited agent's :class:`AgentRecord` and other sessions."""
+
+    async def test_borrowed_session_dies_agent_survives(self) -> None:
+        """After ``TeamDelete``, the invited agent's ``AgentRecord``
+        and primary session survive; only the team-scoped borrowed
+        session is removed."""
+        await AgentInvite(
+            storage=self.storage,
+            message_bus=self.bus,
+            workspace_manager=self.workspace_manager,
+            user_id=self.user_id,
+            session_id=self.leader_session.id,
+            agent_id=self.leader_agent.id,
+            invitable_pool=[self.monday_agent],
+        )(target=f"Monday@{self.monday_agent.id[:8]}", prompt="join")
+
+        sess = await self.storage.get_session(
+            self.user_id,
+            self.leader_agent.id,
+            self.leader_session.id,
+        )
+        team = await self.storage.get_team(self.user_id, sess.team_id)
+        borrowed_sid = next(
+            m.session_id for m in team.data.members if m.role == "invited"
+        )
+
+        await TeamDelete(
+            storage=self.storage,
+            message_bus=self.bus,
+            workspace_manager=self.workspace_manager,
+            user_id=self.user_id,
+            session_id=self.leader_session.id,
+            agent_id=self.leader_agent.id,
+        )()
+
+        # Monday's AgentRecord survives.
+        monday = await self.storage.get_agent(
+            self.user_id,
+            self.monday_agent.id,
+        )
+        self.assertIsNotNone(monday)
+        # Monday's primary session survives.
+        primary = await self.storage.get_session(
+            self.user_id,
+            self.monday_agent.id,
+            self.monday_session.id,
+        )
+        self.assertIsNotNone(primary)
+        # Borrowed session is gone.
+        gone = await self.storage.get_session(
+            self.user_id,
+            self.monday_agent.id,
+            borrowed_sid,
+        )
+        self.assertIsNone(gone)
+
+
+class TestDeleteInvitedAgentReverseCascade(_AgentInviteTestBase):
+    """Deleting an invited agent while it is borrowed extracts the
+    stale entry from the borrowing team's roster."""
+
+    async def test_reverse_cascade(self) -> None:
+        """Deleting an invited agent while it is borrowed also strips
+        the stale entry from the borrowing team's ``members`` /
+        ``member_ids`` — the leader's later ``TeamSay`` will hit a
+        clean "no such member" instead of dangling routing."""
+        from agentscope.app._service import SessionService
+
+        await AgentInvite(
+            storage=self.storage,
+            message_bus=self.bus,
+            workspace_manager=self.workspace_manager,
+            user_id=self.user_id,
+            session_id=self.leader_session.id,
+            agent_id=self.leader_agent.id,
+            invitable_pool=[self.monday_agent],
+        )(target=f"Monday@{self.monday_agent.id[:8]}", prompt="join")
+
+        service = SessionService(
+            storage=self.storage,
+            message_bus=self.bus,
+        )
+        await service.delete_agent(self.user_id, self.monday_agent.id)
+
+        sess = await self.storage.get_session(
+            self.user_id,
+            self.leader_agent.id,
+            self.leader_session.id,
+        )
+        team = await self.storage.get_team(self.user_id, sess.team_id)
+        # No stale invited entry remains.
+        self.assertEqual(
+            [
+                m
+                for m in team.data.members
+                if m.agent_id == self.monday_agent.id
+            ],
+            [],
+        )
+        # Legacy member_ids scrubbed too.
+        self.assertNotIn(self.monday_agent.id, team.data.member_ids)
+
+
+class TestEnsureTeamMembersMigration(_TeamToolsTestBase):
+    """Legacy ``TeamRecord`` with only ``member_ids`` populated is
+    migrated to the new ``members`` shape on first read via
+    ``ensure_team_members``."""
+
+    async def test_legacy_member_ids_migrate_to_created_role(self) -> None:
+        """A ``TeamRecord`` whose stored shape only carries the legacy
+        ``member_ids`` list is migrated in place on first read via
+        ``ensure_team_members``: each id becomes a
+        ``TeamMember(role="created", ...)`` entry, and the writeback
+        means later reads hit the fast path."""
+        from agentscope.app.storage._model import TeamData, TeamRecord
+        from agentscope.app.storage._utils import _ensure_team_members
+
+        # Fabricate a legacy worker agent + session (no ``members``
+        # entry on the team, just ``member_ids``).
+        worker = _make_agent_record(
+            self.user_id,
+            "legacy-worker",
+            source="team",
+        )
+        await self.storage.upsert_agent(self.user_id, worker)
+        worker_sess = await self.storage.upsert_session(
+            user_id=self.user_id,
+            agent_id=worker.id,
+            config=SessionConfig(workspace_id="ws-w"),
+        )
+
+        team = TeamRecord(
+            user_id=self.user_id,
+            session_id=self.leader_session.id,
+            data=TeamData(
+                name="legacy",
+                description="",
+                member_ids=[worker.id],
+                # members deliberately left empty
+            ),
+        )
+        await self.storage.upsert_team(self.user_id, team)
+
+        members = await _ensure_team_members(
+            self.storage,
+            self.user_id,
+            team,
+        )
+        self.assertEqual(len(members), 1)
+        self.assertEqual(members[0].role, "created")
+        self.assertEqual(members[0].agent_id, worker.id)
+        self.assertEqual(members[0].session_id, worker_sess.id)
+        self.assertEqual(members[0].owner_id, self.user_id)
+
+        # And the writeback happened — subsequent reads take the fast
+        # path.
+        stored = await self.storage.get_team(self.user_id, team.id)
+        self.assertEqual(len(stored.data.members), 1)
diff --git a/tests/service_toolkit_test.py b/tests/service_toolkit_test.py
new file mode 100644
index 0000000..87e07c5
--- /dev/null
+++ b/tests/service_toolkit_test.py
@@ -0,0 +1,414 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Tests for :func:`get_toolkit` — the single entry point that assembles
+the per-chat-turn :class:`Toolkit` from every tool source the framework
+manages.
+
+Verifies the assembly rules:
+
+- workspace builtins are always included;
+- the four ``Task*`` planning tools are always included;
+- :class:`ToolStop` (from ``BackgroundTaskManager``) is always included;
+- the four ``Schedule*`` tools only when ``session.config.chat_model_config``
+  is set (they need a model to fire new runs with);
+- team tools are role-gated by ``agent_record.source``: ``"team"`` →
+  one ``TeamSay`` (worker variant); anything else → the full
+  leader-side toolset of four;
+- caller-supplied ``extra_factory`` results land at the end.
+"""
+from typing import Any
+from unittest import IsolatedAsyncioTestCase
+
+from utils import FakeWorkspaceManager
+from agentscope.agent import ContextConfig, ReActConfig
+from agentscope.app._manager import (
+    BackgroundTaskManager,
+    SchedulerManager,
+)
+from agentscope.app._service import ResourceAccessService, get_toolkit
+from agentscope.app.access import DenyAllResourceAccessPolicy
+from agentscope.app.storage import (
+    AgentData,
+    AgentRecord,
+    ChatModelConfig,
+    SessionConfig,
+    SessionRecord,
+    TeamData,
+    TeamRecord,
+)
+from agentscope.tool import ToolBase
+
+
+class _FakeWorkspace:
+    """Stand-in for a resolved :class:`WorkspaceBase` — only the three
+    methods :func:`get_toolkit` calls are implemented."""
+
+    def __init__(
+        self,
+        tools: list[ToolBase] | None = None,
+        skills: list | None = None,
+        mcps: list | None = None,
+    ) -> None:
+        self._tools = tools or []
+        self._skills = skills or []
+        self._mcps = mcps or []
+
+    async def list_tools(self) -> list[ToolBase]:
+        """Return the configured workspace tools."""
+        return list(self._tools)
+
+    async def list_skills(self) -> list:
+        """Return the configured workspace skills."""
+        return list(self._skills)
+
+    async def list_mcps(self) -> list:
+        """Return the configured workspace MCP descriptors."""
+        return list(self._mcps)
+
+
+class _NullBus:
+    """``MessageBus`` placeholder. Team tools only carry the reference;
+    nothing in :func:`get_toolkit` actually awaits it."""
+
+
+def _make_agent(*, source: str = "user", name: str = "A") -> AgentRecord:
+    """Build a minimal :class:`AgentRecord`."""
+    return AgentRecord(
+        user_id="u",
+        source=source,
+        data=AgentData(
+            name=name,
+            system_prompt=f"You are {name}.",
+            context_config=ContextConfig(),
+            react_config=ReActConfig(),
+        ),
+    )
+
+
+def _make_session(
+    *,
+    user_id: str,
+    agent_id: str,
+    with_model: bool,
+    team_id: str | None = None,
+) -> SessionRecord:
+    """Build a minimal :class:`SessionRecord`, optionally with a chat
+    model config."""
+    cfg = SessionConfig(
+        workspace_id="ws",
+        chat_model_config=(
+            ChatModelConfig(
+                type="dashscope_credential",
+                credential_id="c",
+                model="m",
+                parameters={},
+            )
+            if with_model
+            else None
+        ),
+    )
+    return SessionRecord(
+        user_id=user_id,
+        agent_id=agent_id,
+        config=cfg,
+        team_id=team_id,
+    )
+
+
+class _NoOpStorage:
+    """Storage placeholder. ``get_toolkit`` itself does not call any
+    storage method — the team tools bind a reference for later use.
+
+    Exceptions: since :class:`AgentInvite` landed, ``get_toolkit`` calls
+    ``ResourceAccessService.list_resource`` at assembly time to build
+    the invitable pool, which fans out to
+    :meth:`StorageBase.list_agents` under the hood. Return an empty
+    list — the toolkit tests care about which team tools are attached,
+    not about the pool contents; the non-empty case is covered by the
+    ``AgentInvite`` tests in ``service_team_tools_test.py``.
+    Additionally, when the session has a ``team_id`` set, ``get_toolkit``
+    calls ``get_team`` to decide leader-vs-worker; the ``team_id_map``
+    constructor arg lets a test inject a lookup so the worker branch
+    can be exercised.
+    """
+
+    def __init__(
+        self,
+        team_id_map: dict[str, TeamRecord] | None = None,
+    ) -> None:
+        """Initialize the storage placeholder."""
+        self._teams = team_id_map or {}
+
+    async def list_agents(self, _user_id: str) -> list:
+        """List agents for a team."""
+        return []
+
+    async def get_team(
+        self,
+        _user_id: str,
+        team_id: str,
+    ) -> TeamRecord | None:
+        """Return the team record for ``team_id``."""
+        return self._teams.get(team_id)
+
+
+def _make_access(storage: Any) -> ResourceAccessService:
+    """Build a :class:`ResourceAccessService` bound to ``storage`` with a
+    deny-all policy for ``get_toolkit`` tests.
+
+    ``list_resource(AGENT)`` therefore fans out to
+    ``storage.list_agents(user_id)`` alone — matching the pre-share
+    behaviour the toolkit tests were written against.
+    """
+    return ResourceAccessService(
+        storage=storage,
+        policy=DenyAllResourceAccessPolicy(),
+    )
+
+
+def _tool_names(toolkit: Any) -> list[str]:
+    """Extract every registered tool name from a :class:`Toolkit`,
+    walking its tool groups."""
+    return [t.name for group in toolkit.tool_groups for t in group.tools]
+
+
+class _StubTool(ToolBase):
+    """Minimal :class:`ToolBase` subclass that satisfies the abstract
+    methods so :func:`get_toolkit` can register the instance.
+
+    Sub-classes override ``name`` and ``description``; nothing in the
+    tests actually calls the tool, so the implementations are no-ops.
+    """
+
+    name: str = "stub"
+    description: str = "stub tool"
+    input_schema: dict = {}
+    is_concurrency_safe: bool = True
+    is_read_only: bool = False
+    is_state_injected: bool = False
+    is_external_tool: bool = False
+    is_mcp: bool = False
+    mcp_name: str | None = None
+
+    async def check_permissions(self, *args: Any, **kwargs: Any) -> None:
+        """No-op permission check — the tests do not exercise it."""
+
+    async def __call__(self, *args: Any, **kwargs: Any) -> None:
+        """No-op invocation — the tests never execute the tool."""
+
+
+class TestGetToolkitBaseAssembly(IsolatedAsyncioTestCase):
+    """User-owned agent (``source="user"``) gets the full set."""
+
+    async def test_user_agent_gets_all_sources(self) -> None:
+        """A user-owned agent receives workspace, planning, scheduling,
+        ToolStop, and the four leader-side team tools."""
+        agent = _make_agent(source="user")
+        session = _make_session(
+            user_id="u",
+            agent_id=agent.id,
+            with_model=True,
+        )
+
+        class _WsTool(_StubTool):
+            """Stub workspace tool registered through ``_FakeWorkspace``."""
+
+            name: str = "ws-bash"
+            description: str = "stub workspace tool"
+
+        ws_tool = _WsTool()
+        workspace = _FakeWorkspace(tools=[ws_tool])
+
+        toolkit = await get_toolkit(
+            storage=_NoOpStorage(),  # type: ignore[arg-type]
+            workspace=workspace,  # type: ignore[arg-type]
+            workspace_manager=FakeWorkspaceManager(),
+            scheduler_manager=SchedulerManager(
+                storage=_NoOpStorage(),  # type: ignore[arg-type]
+                message_bus=_NullBus(),  # type: ignore[arg-type]
+            ),
+            background_task_manager=BackgroundTaskManager(
+                message_bus=_NullBus(),  # type: ignore[arg-type]
+            ),
+            message_bus=_NullBus(),  # type: ignore[arg-type]
+            user_id="u",
+            agent_record=agent,
+            session_record=session,
+            extra_factory=None,
+            middlewares=[],
+            resource_access_service=_make_access(_NoOpStorage()),
+        )
+
+        names = set(_tool_names(toolkit))
+        # Workspace tool present.
+        self.assertIn("ws-bash", names)
+        # Planning tools present.
+        self.assertTrue(
+            {"TaskCreate", "TaskList", "TaskGet", "TaskUpdate"} <= names,
+        )
+        # Background task control present.
+        self.assertIn("ToolStop", names)
+        # Schedule control present (model_config is set).
+        self.assertTrue(
+            {
+                "ScheduleCreate",
+                "ScheduleView",
+                "ScheduleDelete",
+                "ScheduleList",
+            }
+            <= names,
+        )
+        # Leader-side team tools (4 of them).
+        self.assertTrue(
+            {"TeamCreate", "AgentCreate", "TeamSay", "TeamDelete"} <= names,
+        )
+
+
+class TestGetToolkitWorkerVariant(IsolatedAsyncioTestCase):
+    """A session whose team role is worker only gets ``TeamSay``.
+
+    The worker/leader distinction is now session-level: a session with
+    ``team_id`` set and ``team.session_id != session.id`` is a worker
+    regardless of the agent record's ``source`` (an ``AgentInvite``
+    borrowed session runs on ``source='user'`` but is still a worker)."""
+
+    async def test_worker_only_gets_team_say(self) -> None:
+        """A worker session receives only ``TeamSay`` from the team
+        toolset."""
+        agent = _make_agent(source="team", name="worker")
+        session = _make_session(
+            user_id="u",
+            agent_id=agent.id,
+            with_model=True,
+            team_id="t1",
+        )
+        # Team exists and its leader session is NOT this one → worker.
+        team = TeamRecord(
+            user_id="u",
+            session_id="leader-sid",
+            data=TeamData(name="team", description="d"),
+        )
+        toolkit = await get_toolkit(
+            storage=_NoOpStorage(
+                team_id_map={"t1": team},
+            ),  # type: ignore[arg-type]
+            workspace=_FakeWorkspace(),  # type: ignore[arg-type]
+            workspace_manager=FakeWorkspaceManager(),
+            scheduler_manager=SchedulerManager(
+                storage=_NoOpStorage(),  # type: ignore[arg-type]
+                message_bus=_NullBus(),  # type: ignore[arg-type]
+            ),
+            background_task_manager=BackgroundTaskManager(
+                message_bus=_NullBus(),  # type: ignore[arg-type]
+            ),
+            message_bus=_NullBus(),  # type: ignore[arg-type]
+            user_id="u",
+            agent_record=agent,
+            session_record=session,
+            extra_factory=None,
+            middlewares=[],
+            resource_access_service=_make_access(_NoOpStorage()),
+        )
+        names = set(_tool_names(toolkit))
+        # Only TeamSay from the team toolset.
+        self.assertIn("TeamSay", names)
+        for missing in (
+            "TeamCreate",
+            "AgentCreate",
+            "TeamDelete",
+            "AgentInvite",
+        ):
+            self.assertNotIn(missing, names)
+
+
+class TestGetToolkitSchedulingGuard(IsolatedAsyncioTestCase):
+    """``Schedule*`` tools are only attached when the session has a
+    model configured."""
+
+    async def test_no_schedule_tools_without_model_config(self) -> None:
+        """Without a ``chat_model_config`` on the session, the four
+        ``Schedule*`` tools are omitted from the toolkit."""
+        agent = _make_agent(source="user")
+        session = _make_session(
+            user_id="u",
+            agent_id=agent.id,
+            with_model=False,
+        )
+        toolkit = await get_toolkit(
+            storage=_NoOpStorage(),  # type: ignore[arg-type]
+            workspace=_FakeWorkspace(),  # type: ignore[arg-type]
+            workspace_manager=FakeWorkspaceManager(),
+            scheduler_manager=SchedulerManager(
+                storage=_NoOpStorage(),  # type: ignore[arg-type]
+                message_bus=_NullBus(),  # type: ignore[arg-type]
+            ),
+            background_task_manager=BackgroundTaskManager(
+                message_bus=_NullBus(),  # type: ignore[arg-type]
+            ),
+            message_bus=_NullBus(),  # type: ignore[arg-type]
+            user_id="u",
+            agent_record=agent,
+            session_record=session,
+            extra_factory=None,
+            middlewares=[],
+            resource_access_service=_make_access(_NoOpStorage()),
+        )
+        names = set(_tool_names(toolkit))
+        for missing in (
+            "ScheduleCreate",
+            "ScheduleView",
+            "ScheduleDelete",
+            "ScheduleList",
+        ):
+            self.assertNotIn(missing, names)
+
+
+class TestGetToolkitExtraFactory(IsolatedAsyncioTestCase):
+    """Tools returned by ``extra_factory`` end up in the final toolkit."""
+
+    async def test_extra_factory_tools_are_attached(self) -> None:
+        """Tools returned by ``extra_factory`` end up in the final
+        toolkit alongside the framework-builtin ones."""
+
+        class _ExtraTool(_StubTool):
+            """Stub tool emitted by the ``extra_factory`` callback."""
+
+            name: str = "my-extra"
+            description: str = "stub extra tool"
+
+        extra_tool = _ExtraTool()
+
+        async def factory(
+            _user_id: str,
+            _agent_id: str,
+            _session_id: str,
+        ) -> list[ToolBase]:
+            """Stub extra-factory that always returns ``extra_tool``."""
+            return [extra_tool]
+
+        agent = _make_agent()
+        session = _make_session(
+            user_id="u",
+            agent_id=agent.id,
+            with_model=True,
+        )
+        toolkit = await get_toolkit(
+            storage=_NoOpStorage(),  # type: ignore[arg-type]
+            workspace=_FakeWorkspace(),  # type: ignore[arg-type]
+            workspace_manager=FakeWorkspaceManager(),
+            scheduler_manager=SchedulerManager(
+                storage=_NoOpStorage(),  # type: ignore[arg-type]
+                message_bus=_NullBus(),  # type: ignore[arg-type]
+            ),
+            background_task_manager=BackgroundTaskManager(
+                message_bus=_NullBus(),  # type: ignore[arg-type]
+            ),
+            message_bus=_NullBus(),  # type: ignore[arg-type]
+            user_id="u",
+            agent_record=agent,
+            session_record=session,
+            extra_factory=factory,
+            middlewares=[],
+            resource_access_service=_make_access(_NoOpStorage()),
+        )
+        self.assertIn("my-extra", _tool_names(toolkit))
diff --git a/tests/service_wakeup_dispatcher_test.py b/tests/service_wakeup_dispatcher_test.py
new file mode 100644
index 0000000..66291af
--- /dev/null
+++ b/tests/service_wakeup_dispatcher_test.py
@@ -0,0 +1,479 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Tests for :class:`WakeupDispatcher` — one-per-process consumer of the
+shared wake-up queue + signal channel.
+
+Verifies the four behaviours that callers rely on:
+
+- Lifecycle is purely ACM: ``__aenter__`` starts the loop and performs
+  an initial drain; ``__aexit__`` cancels the loop cleanly.
+- A wake-up signal triggers a queue drain; each entry is dispatched as
+  a fire-and-forget ``ChatService.run`` call.
+- Entries left on the queue from before startup are picked up on
+  ``__aenter__`` without waiting for a fresh signal.
+- Sessions that are already running are skipped (no duplicate run).
+- Malformed entries are logged and skipped, not raised.
+"""
+import asyncio
+from contextlib import asynccontextmanager
+from typing import Any, AsyncGenerator, Callable
+from unittest import IsolatedAsyncioTestCase
+
+from agentscope.app._manager import ChatRunRegistry, WakeupDispatcher
+from agentscope.app.message_bus import MessageBus, MessageBusKeys
+
+
+class _FakeStorage:
+    """Minimal storage stand-in for the dispatcher's orphan-guard check.
+
+    ``get_session`` returns a truthy sentinel for every session id by
+    default; tests that exercise the orphan path mutate
+    ``missing_session_ids``.
+    """
+
+    def __init__(self) -> None:
+        self.missing_session_ids: set[str] = set()
+
+    async def get_session(
+        self,
+        _user_id: str,
+        _agent_id: str,
+        session_id: str,
+    ) -> object | None:
+        """Get a session id from the orphan guard."""
+        if session_id in self.missing_session_ids:
+            return None
+        return object()
+
+
+class _FakeBus(MessageBus):
+    """In-memory bus with just enough behaviour for the dispatcher.
+
+    Implements the four primitives the dispatcher uses
+    (``queue_push`` / ``dequeue_wakeups`` indirectly via the parent's
+    domain helper / ``subscribe_wakeup_signal`` / ``is_locked`` /
+    ``publish``) and stubs the others.
+    """
+
+    def __init__(self) -> None:
+        self.queues: dict[str, list[tuple[str, dict]]] = {}
+        self._channels: dict[str, asyncio.Queue] = {}
+        self._next = 0
+        self._locks: set[str] = set()
+
+    def _channel(self, key: str) -> asyncio.Queue:
+        return self._channels.setdefault(key, asyncio.Queue())
+
+    # Mode A — queue
+    async def queue_push(
+        self,
+        key: str,
+        payload: dict,
+        *,
+        ttl_secs: int | None = None,
+    ) -> str:
+        self._next += 1
+        entry_id = str(self._next)
+        self.queues.setdefault(key, []).append((entry_id, payload))
+        return entry_id
+
+    async def queue_drain(
+        self,
+        key: str,
+        *,
+        max_count: int,
+    ) -> list[tuple[str, dict]]:
+        entries = self.queues.get(key, [])[:max_count]
+        self.queues[key] = self.queues.get(key, [])[max_count:]
+        return entries
+
+    async def queue_delete(self, key: str) -> None:
+        self.queues.pop(key, None)
+
+    # Mode C — log (unused here)
+    async def log_append(
+        self,
+        key: str,
+        payload: dict,
+        *,
+        max_len: int | None = None,
+        ttl_secs: int | None = None,
+    ) -> str:
+        return "n/a"
+
+    async def log_read(
+        self,
+        key: str,
+        since: str | None = None,
+        max_count: int = 100,
+    ) -> list[tuple[str, dict]]:
+        return []
+
+    async def log_trim(
+        self,
+        key: str,
+        before_id: str | None = None,
+    ) -> None:
+        return None
+
+    # Mode D — pub/sub
+    async def publish(self, key: str, payload: dict) -> None:
+        await self._channel(key).put(payload)
+
+    async def subscribe(
+        self,
+        key: str,
+        *,
+        on_ready: Callable[[], None] | None = None,
+    ) -> AsyncGenerator[dict, None]:
+        if on_ready is not None:
+            on_ready()
+        while True:
+            yield await self._channel(key).get()
+
+    # Mode E — lock
+    @asynccontextmanager
+    async def acquire_lock(
+        self,
+        key: str,
+        *,
+        ttl_secs: int = 600,
+    ) -> AsyncGenerator[None, None]:
+        self._locks.add(key)
+        try:
+            yield
+        finally:
+            self._locks.discard(key)
+
+    async def is_locked(self, key: str) -> bool:
+        return key in self._locks
+
+    # Mode F — registry (unused by WakeupDispatcher; raise so any
+    # accidental dependency surfaces immediately rather than silently
+    # passing through a stub).
+    async def registry_set(
+        self,
+        namespace: str,
+        field: str,
+        value: str,
+        *,
+        ttl_secs: int | None = None,
+    ) -> None:
+        raise NotImplementedError
+
+    async def registry_del(self, namespace: str, field: str) -> None:
+        raise NotImplementedError
+
+    async def registry_exists(self, namespace: str, field: str) -> bool:
+        raise NotImplementedError
+
+    async def registry_getall(self, namespace: str) -> dict[str, str]:
+        raise NotImplementedError
+
+    async def registry_drop(self, namespace: str) -> None:
+        raise NotImplementedError
+
+
+class _FakeChatService:
+    """Records calls to :meth:`run` so tests can assert dispatch."""
+
+    def __init__(self) -> None:
+        self.calls: list[dict] = []
+        self.notify = asyncio.Event()
+
+    async def run(
+        self,
+        user_id: str,
+        session_id: str,
+        agent_id: str,
+        input_msg: Any = None,
+    ) -> None:
+        """Record the call and signal a waiter."""
+        self.calls.append(
+            {
+                "user_id": user_id,
+                "session_id": session_id,
+                "agent_id": agent_id,
+                "input_msg": input_msg,
+            },
+        )
+        self.notify.set()
+
+
+async def _yield_a_few_times(ticks: int = 8) -> None:
+    """Yield the event loop a few times so spawned tasks make progress."""
+    for _ in range(ticks):
+        await asyncio.sleep(0)
+
+
+class TestWakeupDispatcherDispatch(IsolatedAsyncioTestCase):
+    """Verifies the signal-driven dispatch path."""
+
+    async def test_signal_drives_dispatch(self) -> None:
+        """A wake-up signal causes the queue to be drained and each
+        entry dispatched as a chat run."""
+        bus = _FakeBus()
+        chat = _FakeChatService()
+        async with WakeupDispatcher(
+            message_bus=bus,
+            storage=_FakeStorage(),
+            chat_service=chat,
+            chat_run_registry=ChatRunRegistry(),
+        ):
+            await bus.queue_push(
+                MessageBusKeys.wakeup_queue(),
+                {"user_id": "u", "session_id": "s1", "agent_id": "a1"},
+            )
+            await bus.publish(MessageBusKeys.wakeup_signal(), {})
+
+            await asyncio.wait_for(chat.notify.wait(), timeout=2.0)
+
+        self.assertEqual(
+            chat.calls,
+            [
+                {
+                    "user_id": "u",
+                    "session_id": "s1",
+                    "agent_id": "a1",
+                    "input_msg": None,
+                },
+            ],
+        )
+
+    async def test_initial_drain_picks_up_pending_entries(self) -> None:
+        """Entries on the queue from before ``__aenter__`` are picked up
+        without waiting for a fresh signal."""
+        bus = _FakeBus()
+        chat = _FakeChatService()
+        await bus.queue_push(
+            MessageBusKeys.wakeup_queue(),
+            {"user_id": "u", "session_id": "pre", "agent_id": "a"},
+        )
+
+        async with WakeupDispatcher(
+            message_bus=bus,
+            storage=_FakeStorage(),
+            chat_service=chat,
+            chat_run_registry=ChatRunRegistry(),
+        ):
+            await _yield_a_few_times()
+
+        self.assertEqual(
+            chat.calls,
+            [
+                {
+                    "user_id": "u",
+                    "session_id": "pre",
+                    "agent_id": "a",
+                    "input_msg": None,
+                },
+            ],
+        )
+
+    async def test_active_session_skipped(self) -> None:
+        """If the target session is already running, no chat run is
+        spawned for it."""
+        bus = _FakeBus()
+        chat = _FakeChatService()
+        bus._locks.add(MessageBus._SESSION_LOCK_KEY.format(sid="busy"))
+
+        async with WakeupDispatcher(
+            message_bus=bus,
+            storage=_FakeStorage(),
+            chat_service=chat,
+            chat_run_registry=ChatRunRegistry(),
+        ):
+            await bus.queue_push(
+                MessageBusKeys.wakeup_queue(),
+                {"user_id": "u", "session_id": "busy", "agent_id": "a"},
+            )
+            await bus.publish(MessageBusKeys.wakeup_signal(), {})
+            await asyncio.sleep(0.05)
+
+        self.assertEqual(chat.calls, [])
+
+    async def test_malformed_entry_skipped(self) -> None:
+        """A wake-up entry missing required fields is logged and skipped,
+        not raised; later valid entries still dispatch."""
+        bus = _FakeBus()
+        chat = _FakeChatService()
+
+        async with WakeupDispatcher(
+            message_bus=bus,
+            storage=_FakeStorage(),
+            chat_service=chat,
+            chat_run_registry=ChatRunRegistry(),
+        ):
+            await bus.queue_push(
+                MessageBusKeys.wakeup_queue(),
+                {"oops": True},
+            )
+            await bus.queue_push(
+                MessageBusKeys.wakeup_queue(),
+                {"user_id": "u", "session_id": "s2", "agent_id": "a"},
+            )
+            await bus.publish(MessageBusKeys.wakeup_signal(), {})
+            await asyncio.wait_for(chat.notify.wait(), timeout=2.0)
+
+        # Only the valid entry made it through.
+        self.assertEqual(
+            chat.calls,
+            [
+                {
+                    "user_id": "u",
+                    "session_id": "s2",
+                    "agent_id": "a",
+                    "input_msg": None,
+                },
+            ],
+        )
+
+    async def test_deleted_session_skipped(self) -> None:
+        """A wake-up whose target session no longer exists in storage
+        is dropped without spawning a chat run; later wake-ups for live
+        sessions still dispatch."""
+        bus = _FakeBus()
+        chat = _FakeChatService()
+        storage = _FakeStorage()
+        storage.missing_session_ids.add("ghost")
+
+        async with WakeupDispatcher(
+            message_bus=bus,
+            storage=storage,
+            chat_service=chat,
+            chat_run_registry=ChatRunRegistry(),
+        ):
+            await bus.queue_push(
+                MessageBusKeys.wakeup_queue(),
+                {"user_id": "u", "session_id": "ghost", "agent_id": "a"},
+            )
+            await bus.queue_push(
+                MessageBusKeys.wakeup_queue(),
+                {"user_id": "u", "session_id": "live", "agent_id": "a"},
+            )
+            await bus.publish(MessageBusKeys.wakeup_signal(), {})
+            await asyncio.wait_for(chat.notify.wait(), timeout=2.0)
+
+        self.assertEqual(
+            chat.calls,
+            [
+                {
+                    "user_id": "u",
+                    "session_id": "live",
+                    "agent_id": "a",
+                    "input_msg": None,
+                },
+            ],
+        )
+
+    async def test_resume_idle_spawns_with_parsed_event(self) -> None:
+        """A ``resume`` trigger for an idle session spawns a run whose
+        ``input_msg`` is the carried HITL event, rebuilt from its dump."""
+        from agentscope.event import UserConfirmResultEvent
+
+        bus = _FakeBus()
+        chat = _FakeChatService()
+        event = UserConfirmResultEvent.model_construct(
+            reply_id="r1",
+            confirm_results=[],
+        )
+
+        async with WakeupDispatcher(
+            message_bus=bus,
+            storage=_FakeStorage(),
+            chat_service=chat,
+            chat_run_registry=ChatRunRegistry(),
+        ):
+            await bus.queue_push(
+                MessageBusKeys.wakeup_queue(),
+                {
+                    "user_id": "u",
+                    "session_id": "w1",
+                    "agent_id": "wa1",
+                    "kind": MessageBusKeys.WAKEUP_KIND_RESUME,
+                    "input": event.model_dump(mode="json"),
+                },
+            )
+            await bus.publish(MessageBusKeys.wakeup_signal(), {})
+            await asyncio.wait_for(chat.notify.wait(), timeout=2.0)
+
+        self.assertEqual(len(chat.calls), 1)
+        call = chat.calls[0]
+        self.assertEqual(call["session_id"], "w1")
+        self.assertIsInstance(call["input_msg"], UserConfirmResultEvent)
+        self.assertEqual(call["input_msg"].reply_id, "r1")
+
+    async def test_resume_running_session_requeues_until_free(self) -> None:
+        """A ``resume`` whose target is still running is NOT dropped: it
+        is re-queued (with backoff) and dispatched once the session lock
+        releases. This is the structural fix for the parked-run 409 race.
+        """
+        from agentscope.event import UserConfirmResultEvent
+
+        bus = _FakeBus()
+        chat = _FakeChatService()
+        lock_key = MessageBus._SESSION_LOCK_KEY.format(sid="w1")
+        bus._locks.add(lock_key)  # session is busy finishing its park tail
+        event = UserConfirmResultEvent.model_construct(
+            reply_id="r1",
+            confirm_results=[],
+        )
+
+        async with WakeupDispatcher(
+            message_bus=bus,
+            storage=_FakeStorage(),
+            chat_service=chat,
+            chat_run_registry=ChatRunRegistry(),
+        ):
+            await bus.queue_push(
+                MessageBusKeys.wakeup_queue(),
+                {
+                    "user_id": "u",
+                    "session_id": "w1",
+                    "agent_id": "wa1",
+                    "kind": MessageBusKeys.WAKEUP_KIND_RESUME,
+                    "input": event.model_dump(mode="json"),
+                },
+            )
+            await bus.publish(MessageBusKeys.wakeup_signal(), {})
+
+            # While locked, the resume must keep deferring — no run yet.
+            await asyncio.sleep(0.25)
+            self.assertEqual(chat.calls, [])
+
+            # Release the lock; the re-queued resume now lands.
+            bus._locks.discard(lock_key)
+            await asyncio.wait_for(chat.notify.wait(), timeout=2.0)
+
+        self.assertEqual(len(chat.calls), 1)
+        self.assertEqual(chat.calls[0]["session_id"], "w1")
+        self.assertIsInstance(
+            chat.calls[0]["input_msg"],
+            UserConfirmResultEvent,
+        )
+
+
+class TestWakeupDispatcherLifecycle(IsolatedAsyncioTestCase):
+    """Tests covering the ``__aenter__`` / ``__aexit__`` ACM behaviour."""
+
+    async def test_exit_cancels_loop_cleanly(self) -> None:
+        """``__aexit__`` cancels the dispatcher's loop task and returns
+        without re-raising the cancellation."""
+        bus = _FakeBus()
+        chat = _FakeChatService()
+        dispatcher = WakeupDispatcher(
+            message_bus=bus,
+            storage=_FakeStorage(),
+            chat_service=chat,
+            chat_run_registry=ChatRunRegistry(),
+        )
+
+        # pylint: disable=unnecessary-dunder-call
+        await dispatcher.__aenter__()
+        loop_task = dispatcher._task
+        self.assertIsNotNone(loop_task)
+
+        await dispatcher.__aexit__(None, None, None)
+
+        self.assertIsNone(dispatcher._task)
+        self.assertTrue(loop_task.cancelled() or loop_task.done())
diff --git a/tests/skill_loader_test.py b/tests/skill_loader_test.py
new file mode 100644
index 0000000..101be4a
--- /dev/null
+++ b/tests/skill_loader_test.py
@@ -0,0 +1,212 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Test cases for LocalSkillLoader."""
+import os
+import tempfile
+import shutil
+import time
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from agentscope.skill import LocalSkillLoader
+
+
+class SkillLoaderTest(IsolatedAsyncioTestCase):
+    """Test cases for LocalSkillLoader."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up test fixtures."""
+        # Create a temporary directory for testing
+        self.test_dir = tempfile.mkdtemp()
+
+        # Create test SKILL.md files
+        # 1. Root level skill
+        self.root_skill_content = """---
+name: root_skill
+description: A skill in the root directory
+---
+
+This is the root skill content.
+"""
+        with open(
+            os.path.join(self.test_dir, "SKILL.md"),
+            "w",
+            encoding="utf-8",
+        ) as f:
+            f.write(self.root_skill_content)
+
+        # 2. Subdirectory skill
+        self.subdir1 = os.path.join(self.test_dir, "subdir1")
+        os.makedirs(self.subdir1)
+        self.subdir1_skill_content = """---
+name: subdir1_skill
+description: A skill in subdirectory 1
+---
+
+This is the subdir1 skill content.
+"""
+        with open(
+            os.path.join(self.subdir1, "SKILL.md"),
+            "w",
+            encoding="utf-8",
+        ) as f:
+            f.write(self.subdir1_skill_content)
+
+        # 3. Nested subdirectory skill
+        self.subdir2 = os.path.join(self.test_dir, "subdir1", "subdir2")
+        os.makedirs(self.subdir2)
+        self.subdir2_skill_content = """---
+name: subdir2_skill
+description: A skill in nested subdirectory 2
+---
+
+This is the subdir2 skill content.
+"""
+        with open(
+            os.path.join(self.subdir2, "SKILL.md"),
+            "w",
+            encoding="utf-8",
+        ) as f:
+            f.write(self.subdir2_skill_content)
+
+    async def asyncTearDown(self) -> None:
+        """Clean up test fixtures."""
+        # Remove the temporary directory
+        if os.path.exists(self.test_dir):
+            shutil.rmtree(self.test_dir)
+
+    async def test_nonexistent_skill(self) -> None:
+        """Test loading from a directory without SKILL.md."""
+        # Create a directory without SKILL.md
+        empty_dir = tempfile.mkdtemp()
+        try:
+            loader = LocalSkillLoader(empty_dir, scan_subdir=False)
+            skills = await loader.list_skills()
+            self.assertEqual(len(skills), 0)
+        finally:
+            shutil.rmtree(empty_dir)
+
+    async def test_scan_subdir_flag_controls_subdirectory_scanning(
+        self,
+    ) -> None:
+        """Test that scan_subdir only controls subdirectory scanning.
+
+        The root directory is always scanned regardless of scan_subdir.
+        When scan_subdir=False, only root SKILL.md is loaded.
+        When scan_subdir=True, root + all subdirectory SKILL.md files
+        are loaded.
+        """
+        loader_no_scan = LocalSkillLoader(self.test_dir, scan_subdir=False)
+        skills_no_scan = await loader_no_scan.list_skills()
+
+        loader_with_scan = LocalSkillLoader(self.test_dir, scan_subdir=True)
+        skills_with_scan = await loader_with_scan.list_skills()
+
+        # scan_subdir=False: only root skill
+        self.assertEqual(len(skills_no_scan), 1)
+        self.assertEqual(skills_no_scan[0].name, "root_skill")
+
+        # scan_subdir=True: root skill + both subdirectory skills
+        self.assertEqual(len(skills_with_scan), 3)
+        skill_names = {s.name for s in skills_with_scan}
+        self.assertIn("root_skill", skill_names)
+        self.assertIn("subdir1_skill", skill_names)
+        self.assertIn("subdir2_skill", skill_names)
+
+    async def test_load_skill_without_scan_subdir(self) -> None:
+        """Test loading skill from root directory only (scan_subdir=False)."""
+        loader = LocalSkillLoader(self.test_dir, scan_subdir=False)
+        skills = await loader.list_skills()
+
+        # Should only load the root skill
+        self.assertEqual(len(skills), 1)
+        self.assertEqual(skills[0].name, "root_skill")
+        self.assertEqual(
+            skills[0].description,
+            "A skill in the root directory",
+        )
+        self.assertEqual(skills[0].dir, self.test_dir)
+        self.assertIn("This is the root skill content.", skills[0].markdown)
+        self.assertIsInstance(skills[0].updated_at, float)
+        self.assertGreater(skills[0].updated_at, 0)
+
+    async def test_load_skill_with_scan_subdir(self) -> None:
+        """Test loading skills from subdirectories (scan_subdir=True)."""
+        loader = LocalSkillLoader(self.test_dir, scan_subdir=True)
+        skills = await loader.list_skills()
+
+        # Should load all three skills
+        self.assertEqual(len(skills), 3)
+
+        # Check skill names
+        skill_names = {skill.name for skill in skills}
+        self.assertEqual(
+            skill_names,
+            {"root_skill", "subdir1_skill", "subdir2_skill"},
+        )
+
+        # Verify each skill has correct attributes
+        for skill in skills:
+            self.assertIsInstance(skill.name, str)
+            self.assertIsInstance(skill.description, str)
+            self.assertIsInstance(skill.dir, str)
+            self.assertIsInstance(skill.markdown, str)
+            self.assertIsInstance(skill.updated_at, float)
+            self.assertGreater(skill.updated_at, 0)
+
+    async def test_cache_mechanism(self) -> None:
+        """Test that cache is used when file is not modified."""
+        loader = LocalSkillLoader(self.test_dir, scan_subdir=False)
+
+        # First load - should read from file
+        skills_first = await loader.list_skills()
+        self.assertEqual(len(skills_first), 1)
+        first_skill = skills_first[0]
+
+        # Verify cache is populated
+        self.assertIn(self.test_dir, loader._cache)
+        cached_skill = loader._cache[self.test_dir]
+        self.assertEqual(cached_skill.name, first_skill.name)
+        self.assertEqual(cached_skill.updated_at, first_skill.updated_at)
+
+        # Second load - should use cache (file not modified)
+        skills_second = await loader.list_skills()
+        self.assertEqual(len(skills_second), 1)
+        second_skill = skills_second[0]
+
+        # Should return the same cached object
+        self.assertIs(second_skill, cached_skill)
+        self.assertEqual(second_skill.updated_at, first_skill.updated_at)
+
+        # Modify the file
+        time.sleep(0.01)  # Ensure different mtime
+        modified_content = """---
+name: modified_root_skill
+description: Modified skill description
+---
+
+This is the modified content.
+"""
+        with open(
+            os.path.join(self.test_dir, "SKILL.md"),
+            "w",
+            encoding="utf-8",
+        ) as f:
+            f.write(modified_content)
+
+        # Third load - should detect change and reload
+        skills_third = await loader.list_skills()
+        self.assertEqual(len(skills_third), 1)
+        third_skill = skills_third[0]
+
+        # Should have new content
+        self.assertEqual(third_skill.name, "modified_root_skill")
+        self.assertEqual(third_skill.description, "Modified skill description")
+        self.assertIn("This is the modified content.", third_skill.markdown)
+        self.assertNotEqual(third_skill.updated_at, first_skill.updated_at)
+
+        # Cache should be updated
+        self.assertIn(self.test_dir, loader._cache)
+        self.assertEqual(
+            loader._cache[self.test_dir].name,
+            "modified_root_skill",
+        )
diff --git a/tests/storage_redis_knowledge_base_test.py b/tests/storage_redis_knowledge_base_test.py
new file mode 100644
index 0000000..f828c73
--- /dev/null
+++ b/tests/storage_redis_knowledge_base_test.py
@@ -0,0 +1,110 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Unit tests for the knowledge base persistence layer of RedisStorage."""
+from unittest.async_case import IsolatedAsyncioTestCase
+
+import fakeredis.aioredis
+
+from agentscope.app.storage import (
+    EmbeddingModelConfig,
+    KnowledgeBaseRecord,
+    RedisStorage,
+)
+
+
+def make_storage() -> RedisStorage:
+    """Create a RedisStorage instance backed by fakeredis."""
+    storage = RedisStorage.__new__(RedisStorage)
+    storage._client = fakeredis.aioredis.FakeRedis(decode_responses=True)
+    storage.key_ttl = None
+    storage.key_config = RedisStorage.KeyConfig()
+    return storage
+
+
+def make_record(user_id: str, name: str = "kb") -> KnowledgeBaseRecord:
+    """Build a KnowledgeBaseRecord with a default embedding config."""
+    return KnowledgeBaseRecord(
+        user_id=user_id,
+        name=name,
+        description="desc",
+        embedding_model_config=EmbeddingModelConfig(
+            type="openai_credential",
+            credential_id="cred-1",
+            model="text-embedding-3-small",
+            dimensions=1536,
+        ),
+        collection_name="kb_abc",
+    )
+
+
+class KnowledgeBaseStorageTest(IsolatedAsyncioTestCase):
+    """Tests for the KnowledgeBaseRecord CRUD methods on RedisStorage."""
+
+    async def test_upsert_get_list_delete(self) -> None:
+        """Round-trip and isolation across users."""
+        storage = make_storage()
+
+        rec_a = make_record("user-1", "first")
+        rec_b = make_record("user-1", "second")
+        rec_c = make_record("user-2", "other")
+
+        stored_a = await storage.upsert_knowledge_base("user-1", rec_a)
+        stored_b = await storage.upsert_knowledge_base("user-1", rec_b)
+        stored_c = await storage.upsert_knowledge_base("user-2", rec_c)
+
+        # get returns the persisted record for the right owner
+        fetched = await storage.get_knowledge_base("user-1", stored_a.id)
+        self.assertEqual(fetched.id, stored_a.id)
+        self.assertEqual(fetched.name, "first")
+
+        # cross-user lookups return None
+        self.assertIsNone(
+            await storage.get_knowledge_base("user-2", stored_a.id),
+        )
+
+        # list scoped to user-1 returns only its records
+        listed = await storage.list_knowledge_bases("user-1")
+        self.assertEqual(
+            sorted(r.id for r in listed),
+            sorted([stored_a.id, stored_b.id]),
+        )
+
+        # delete only the requested record; other users are untouched
+        deleted = await storage.delete_knowledge_base("user-1", stored_a.id)
+        self.assertTrue(deleted)
+        self.assertIsNone(
+            await storage.get_knowledge_base("user-1", stored_a.id),
+        )
+        self.assertEqual(
+            [r.id for r in await storage.list_knowledge_bases("user-1")],
+            [stored_b.id],
+        )
+        self.assertEqual(
+            [r.id for r in await storage.list_knowledge_bases("user-2")],
+            [stored_c.id],
+        )
+
+        # double-delete returns False
+        self.assertFalse(
+            await storage.delete_knowledge_base("user-1", stored_a.id),
+        )
+
+    async def test_upsert_rejects_user_id_mismatch(self) -> None:
+        """upsert refuses records whose user_id does not match arg."""
+        storage = make_storage()
+        rec = make_record("user-1")
+        with self.assertRaises(ValueError):
+            await storage.upsert_knowledge_base("user-2", rec)
+
+    async def test_upsert_overwrites_and_preserves_created_at(self) -> None:
+        """Re-upsert with same id keeps created_at, refreshes updated_at."""
+        storage = make_storage()
+        rec = make_record("user-1")
+        first = await storage.upsert_knowledge_base("user-1", rec)
+
+        rec.name = "renamed"
+        second = await storage.upsert_knowledge_base("user-1", rec)
+
+        self.assertEqual(second.id, first.id)
+        self.assertEqual(second.created_at, first.created_at)
+        self.assertEqual(second.name, "renamed")
diff --git a/tests/storage_redis_test.py b/tests/storage_redis_test.py
new file mode 100644
index 0000000..fc748c3
--- /dev/null
+++ b/tests/storage_redis_test.py
@@ -0,0 +1,1110 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Unit tests for RedisStorage using fakeredis."""
+
+from unittest.async_case import IsolatedAsyncioTestCase
+
+import fakeredis.aioredis
+
+from agentscope.app.storage import (
+    RedisStorage,
+    AgentRecord,
+    SessionConfig,
+    SessionRecord,
+    ChatModelConfig,
+    ScheduleRecord,
+    ScheduleData,
+    SessionSource,
+    TeamData,
+    TeamRecord,
+)
+from agentscope.credential import OllamaCredential
+from agentscope.app.storage import AgentData
+from agentscope.agent import ContextConfig, ReActConfig
+from agentscope.message import UserMsg, AssistantMsg, TextBlock
+from agentscope.state import AgentState
+
+
+def make_storage() -> RedisStorage:
+    """Create a RedisStorage instance backed by fakeredis."""
+    storage = RedisStorage.__new__(RedisStorage)
+    # pylint: disable=protected-access
+    storage._client = fakeredis.aioredis.FakeRedis(decode_responses=True)
+    storage.key_ttl = None
+    storage.key_config = RedisStorage.KeyConfig()
+    return storage
+
+
+def make_agent_record(user_id: str) -> AgentRecord:
+    """Create a test AgentRecord with all-default sub-configs."""
+    return AgentRecord(
+        user_id=user_id,
+        data=AgentData(
+            id="agent-data-id",
+            name="test-agent",
+            system_prompt="You are a helpful assistant.",
+            context_config=ContextConfig(),
+            react_config=ReActConfig(),
+        ),
+    )
+
+
+def make_session_config(workspace_id: str = "ws-1") -> SessionConfig:
+    """Create a test SessionConfig with a chat model config."""
+    return SessionConfig(
+        workspace_id=workspace_id,
+        chat_model_config=ChatModelConfig(
+            type="openai",
+            credential_id="cred-1",
+            model="gpt-4",
+            parameters={},
+        ),
+    )
+
+
+class TestCredential(IsolatedAsyncioTestCase):
+    """Tests for credential CRUD and cascading operations."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up test fixtures."""
+        self.storage = make_storage()
+        self.user_id = "user-1"
+
+    async def test_create(self) -> None:
+        """Create a credential and verify it is retrievable via list."""
+        cred_id = await self.storage.upsert_credential(
+            self.user_id,
+            OllamaCredential(host="http://localhost:11434"),
+        )
+        records = await self.storage.list_credentials(self.user_id)
+        self.assertEqual(len(records), 1)
+        self.assertEqual(records[0].id, cred_id)
+        self.assertEqual(records[0].data.get("type"), "ollama_credential")
+        self.assertEqual(
+            records[0].data.get("host"),
+            "http://localhost:11434",
+        )
+
+    async def test_list_empty(self) -> None:
+        """Verify list returns empty when no records exist."""
+        records = await self.storage.list_credentials(self.user_id)
+        self.assertEqual(records, [])
+
+    async def test_update_in_place(self) -> None:
+        """Update a credential and verify data changed without adding
+        a new record."""
+        cred_id = await self.storage.upsert_credential(
+            self.user_id,
+            OllamaCredential(host="http://old-host:11434"),
+        )
+        await self.storage.upsert_credential(
+            self.user_id,
+            OllamaCredential(id=cred_id, host="http://new-host:11434"),
+        )
+        records = await self.storage.list_credentials(self.user_id)
+        self.assertEqual(len(records), 1)
+        self.assertEqual(records[0].data.get("host"), "http://new-host:11434")
+
+    async def test_delete(self) -> None:
+        """Delete a credential and verify it is gone from Redis."""
+        cred_id = await self.storage.upsert_credential(
+            self.user_id,
+            OllamaCredential(host="http://localhost:11434"),
+        )
+        result = await self.storage.delete_credential(self.user_id, cred_id)
+        self.assertTrue(result)
+        records = await self.storage.list_credentials(self.user_id)
+        self.assertEqual(records, [])
+
+    async def test_delete_nonexistent(self) -> None:
+        """Verify delete returns False for non-existent record."""
+        result = await self.storage.delete_credential(
+            self.user_id,
+            "no-such-id",
+        )
+        self.assertFalse(result)
+
+    async def test_user_isolation(self) -> None:
+        """Verify different users cannot see each other's records."""
+        await self.storage.upsert_credential(
+            "user-A",
+            OllamaCredential(host="http://localhost:11434"),
+        )
+        records = await self.storage.list_credentials("user-B")
+        self.assertEqual(records, [])
+
+
+class TestAgent(IsolatedAsyncioTestCase):
+    """Tests for agent CRUD and cascading operations."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up test fixtures."""
+        self.storage = make_storage()
+        self.user_id = "user-1"
+
+    async def test_create(self) -> None:
+        """Create an agent and verify it is retrievable via list."""
+        record = make_agent_record(self.user_id)
+        agent_id = await self.storage.upsert_agent(self.user_id, record)
+        records = await self.storage.list_agents(self.user_id)
+        self.assertEqual(len(records), 1)
+        self.assertEqual(records[0].id, agent_id)
+        self.assertEqual(records[0].data.name, "test-agent")
+
+    async def test_list_empty(self) -> None:
+        """Verify list returns empty when no records exist."""
+        records = await self.storage.list_agents(self.user_id)
+        self.assertEqual(records, [])
+
+    async def test_delete(self) -> None:
+        """Delete an agent and verify it is gone from Redis."""
+        record = make_agent_record(self.user_id)
+        await self.storage.upsert_agent(self.user_id, record)
+        result = await self.storage.delete_agent(self.user_id, record.id)
+        self.assertTrue(result)
+        records = await self.storage.list_agents(self.user_id)
+        self.assertEqual(records, [])
+
+    async def test_delete_nonexistent(self) -> None:
+        """Verify delete returns False for non-existent record."""
+        result = await self.storage.delete_agent(self.user_id, "no-such-id")
+        self.assertFalse(result)
+
+    async def test_user_isolation(self) -> None:
+        """Verify different users cannot see each other's records."""
+        await self.storage.upsert_agent("user-A", make_agent_record("user-A"))
+        records = await self.storage.list_agents("user-B")
+        self.assertEqual(records, [])
+
+
+class TestSession(IsolatedAsyncioTestCase):
+    """Tests for session CRUD and cascading operations."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up test fixtures."""
+        self.storage = make_storage()
+        self.user_id = "user-1"
+        self.agent_id = "agent-1"
+        self.workspace_id = "ws-1"
+
+    async def test_create(self) -> None:
+        """Create a session and verify it is retrievable via list."""
+        await self.storage.upsert_session(
+            self.user_id,
+            self.agent_id,
+            make_session_config(self.workspace_id),
+        )
+        records = await self.storage.list_sessions(self.user_id, self.agent_id)
+        self.assertEqual(len(records), 1)
+        self.assertEqual(records[0].config.workspace_id, self.workspace_id)
+        self.assertEqual(records[0].agent_id, self.agent_id)
+
+    async def test_list_empty(self) -> None:
+        """Verify list returns empty when no records exist."""
+        records = await self.storage.list_sessions(self.user_id, self.agent_id)
+        self.assertEqual(records, [])
+
+    async def test_upsert_same_triple_updates_in_place(self) -> None:
+        """Second upsert with the same session_id must update the existing
+        record, not create a second one."""
+        session = await self.storage.upsert_session(
+            self.user_id,
+            self.agent_id,
+            make_session_config(self.workspace_id),
+        )
+        first_id = session.id
+
+        await self.storage.upsert_session(
+            self.user_id,
+            self.agent_id,
+            make_session_config(self.workspace_id),
+            session_id=first_id,
+        )
+        records_after = await self.storage.list_sessions(
+            self.user_id,
+            self.agent_id,
+        )
+        self.assertEqual(len(records_after), 1)
+        self.assertEqual(records_after[0].id, first_id)
+
+    async def test_create_with_explicit_session_id_uses_that_key(self) -> None:
+        """A caller-provided session_id should be the stored record id."""
+        session_id = "session-from-router"
+
+        session = await self.storage.upsert_session(
+            self.user_id,
+            self.agent_id,
+            make_session_config(self.workspace_id),
+            session_id=session_id,
+        )
+
+        self.assertEqual(session.id, session_id)
+        fetched = await self.storage.get_session(
+            self.user_id,
+            self.agent_id,
+            session_id,
+        )
+        self.assertIsNotNone(fetched)
+        self.assertEqual(fetched.id, session_id)
+
+        await self.storage.update_session_state(
+            self.user_id,
+            self.agent_id,
+            session_id,
+            AgentState(),
+        )
+        records = await self.storage.list_sessions(self.user_id, self.agent_id)
+        self.assertEqual([record.id for record in records], [session_id])
+
+    async def test_delete(self) -> None:
+        """Delete a session and verify it is gone from Redis."""
+        await self.storage.upsert_session(
+            self.user_id,
+            self.agent_id,
+            make_session_config(self.workspace_id),
+        )
+        records = await self.storage.list_sessions(self.user_id, self.agent_id)
+        result = await self.storage.delete_session(
+            self.user_id,
+            self.agent_id,
+            records[0].id,
+        )
+        self.assertTrue(result)
+        remaining = await self.storage.list_sessions(
+            self.user_id,
+            self.agent_id,
+        )
+        self.assertEqual(remaining, [])
+
+    async def test_delete_cascades_lookup_key(self) -> None:
+        """Deleting a session must remove the lookup key so a subsequent upsert
+        for the same (user, agent) pair creates a fresh session with a new
+        id."""
+        await self.storage.upsert_session(
+            self.user_id,
+            self.agent_id,
+            make_session_config(self.workspace_id),
+        )
+        records = await self.storage.list_sessions(self.user_id, self.agent_id)
+        old_id = records[0].id
+
+        await self.storage.delete_session(self.user_id, self.agent_id, old_id)
+
+        await self.storage.upsert_session(
+            self.user_id,
+            self.agent_id,
+            make_session_config(self.workspace_id),
+        )
+        new_records = await self.storage.list_sessions(
+            self.user_id,
+            self.agent_id,
+        )
+        self.assertEqual(len(new_records), 1)
+        self.assertNotEqual(new_records[0].id, old_id)
+
+    async def test_delete_nonexistent(self) -> None:
+        """Verify delete returns False for non-existent record."""
+        result = await self.storage.delete_session(
+            self.user_id,
+            self.agent_id,
+            "no-such-id",
+        )
+        self.assertFalse(result)
+
+    async def test_agent_isolation(self) -> None:
+        """Verify different agents cannot see each other's sessions."""
+        await self.storage.upsert_session(
+            self.user_id,
+            "agent-A",
+            make_session_config(self.workspace_id),
+        )
+        records = await self.storage.list_sessions(self.user_id, "agent-B")
+        self.assertEqual(records, [])
+
+
+class TestMessage(IsolatedAsyncioTestCase):
+    """Tests for message persistence: upsert_message, get_message and
+    list_messages."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up test fixtures."""
+        self.storage = make_storage()
+        self.user_id = "user-1"
+        self.session_id = "session-1"
+
+    async def test_upsert_appends_new_message(self) -> None:
+        """Upserting a new message appends it to the session list."""
+        msg = UserMsg(name="alice", content="hello")
+        await self.storage.upsert_message(self.user_id, self.session_id, msg)
+        messages = await self.storage.list_messages(
+            self.user_id,
+            self.session_id,
+        )
+        self.assertListEqual(
+            [m.model_dump() for m in messages],
+            [msg.model_dump()],
+        )
+
+    async def test_upsert_refreshes_message_list_ttl(self) -> None:
+        """Message list keys expire with the session storage TTL."""
+        self.storage.key_ttl = 60
+        msg = UserMsg(name="alice", content="hello")
+
+        await self.storage.upsert_message(self.user_id, self.session_id, msg)
+
+        ttl = await self.storage._client.ttl(
+            self.storage._message_key(self.user_id, self.session_id),
+        )
+        self.assertGreater(ttl, 0)
+
+    async def test_upsert_replaces_last_message_with_same_id(self) -> None:
+        """Upserting a message whose id matches the last entry replaces it
+        in-place (streaming overwrite), rather than creating a duplicate."""
+        msg = AssistantMsg(name="bot", content="v1")
+        await self.storage.upsert_message(self.user_id, self.session_id, msg)
+
+        # Keep the same id but replace content — simulates a streaming update.
+        updated = msg.model_copy(
+            update={"content": [TextBlock(text="v2")]},
+        )
+        await self.storage.upsert_message(
+            self.user_id,
+            self.session_id,
+            updated,
+        )
+
+        messages = await self.storage.list_messages(
+            self.user_id,
+            self.session_id,
+        )
+        self.assertListEqual(
+            [m.model_dump() for m in messages],
+            [updated.model_dump()],
+            "Duplicate must not be created; existing entry must be replaced.",
+        )
+
+    async def test_replace_refreshes_message_list_ttl(self) -> None:
+        """Streaming message replacement keeps the message key expiring."""
+        self.storage.key_ttl = 60
+        msg = AssistantMsg(name="bot", content="v1")
+        await self.storage.upsert_message(self.user_id, self.session_id, msg)
+        await self.storage._client.persist(
+            self.storage._message_key(self.user_id, self.session_id),
+        )
+        updated = msg.model_copy(
+            update={"content": [TextBlock(text="v2")]},
+        )
+
+        await self.storage.upsert_message(
+            self.user_id,
+            self.session_id,
+            updated,
+        )
+
+        ttl = await self.storage._client.ttl(
+            self.storage._message_key(self.user_id, self.session_id),
+        )
+        self.assertGreater(ttl, 0)
+
+    async def test_upsert_appends_when_id_differs_from_last(self) -> None:
+        """Upserting a message with a different id than the last always
+        appends, even if an earlier message shares the same id."""
+        msg1 = UserMsg(name="alice", content="first")
+        msg2 = UserMsg(name="alice", content="second")
+        await self.storage.upsert_message(self.user_id, self.session_id, msg1)
+        await self.storage.upsert_message(self.user_id, self.session_id, msg2)
+        messages = await self.storage.list_messages(
+            self.user_id,
+            self.session_id,
+        )
+        self.assertListEqual(
+            [m.model_dump() for m in messages],
+            [msg1.model_dump(), msg2.model_dump()],
+        )
+
+    async def test_get_message_returns_correct_message(self) -> None:
+        """get_message fetches the message matching the given id."""
+        msg1 = UserMsg(name="alice", content="first")
+        msg2 = UserMsg(name="alice", content="second")
+        await self.storage.upsert_message(self.user_id, self.session_id, msg1)
+        await self.storage.upsert_message(self.user_id, self.session_id, msg2)
+
+        fetched = await self.storage.get_message(
+            self.user_id,
+            self.session_id,
+            msg1.id,
+        )
+        self.assertIsNotNone(fetched)
+        self.assertDictEqual(fetched.model_dump(), msg1.model_dump())
+
+    async def test_get_message_nonexistent_returns_none(self) -> None:
+        """get_message returns None when the message id does not exist."""
+        result = await self.storage.get_message(
+            self.user_id,
+            self.session_id,
+            "no-such-id",
+        )
+        self.assertIsNone(result)
+
+    async def test_list_messages_empty_session(self) -> None:
+        """list_messages returns an empty list for a session with no
+        messages."""
+        messages = await self.storage.list_messages(
+            self.user_id,
+            self.session_id,
+        )
+        self.assertListEqual(messages, [])
+
+    async def test_list_messages_pagination(self) -> None:
+        """list_messages respects offset and limit parameters."""
+        msgs = [UserMsg(name="alice", content=f"msg-{i}") for i in range(5)]
+        for m in msgs:
+            await self.storage.upsert_message(
+                self.user_id,
+                self.session_id,
+                m,
+            )
+
+        # Fetch the middle slice: offset=1, limit=3 → msgs[1], msgs[2], msgs[3]
+        page = await self.storage.list_messages(
+            self.user_id,
+            self.session_id,
+            offset=1,
+            limit=3,
+        )
+        self.assertListEqual(
+            [m.model_dump() for m in page],
+            [m.model_dump() for m in msgs[1:4]],
+        )
+
+    async def test_list_messages_order_preserved(self) -> None:
+        """Messages are returned in the insertion order (chronological)."""
+        msgs = [
+            UserMsg(name="alice", content=text)
+            for text in ["alpha", "beta", "gamma"]
+        ]
+        for m in msgs:
+            await self.storage.upsert_message(
+                self.user_id,
+                self.session_id,
+                m,
+            )
+        messages = await self.storage.list_messages(
+            self.user_id,
+            self.session_id,
+        )
+        self.assertListEqual(
+            [m.model_dump() for m in messages],
+            [m.model_dump() for m in msgs],
+        )
+
+    async def test_session_isolation(self) -> None:
+        """Messages belonging to different sessions do not interfere."""
+        await self.storage.upsert_message(
+            self.user_id,
+            "session-A",
+            UserMsg(name="alice", content="in A"),
+        )
+        messages = await self.storage.list_messages(
+            self.user_id,
+            "session-B",
+        )
+        self.assertListEqual(messages, [])
+
+
+def make_schedule_record(user_id: str, agent_id: str) -> ScheduleRecord:
+    """Create a test ScheduleRecord."""
+    return ScheduleRecord(
+        user_id=user_id,
+        agent_id=agent_id,
+        data=ScheduleData(
+            name="test-schedule",
+            cron_expression="0 9 * * *",
+            started_at="2026-01-01T00:00:00",
+            chat_model_config=ChatModelConfig(
+                type="openai",
+                credential_id="cred-1",
+                model="gpt-4",
+                parameters={},
+            ),
+        ),
+    )
+
+
+class TestScheduleSession(IsolatedAsyncioTestCase):
+    """Tests for schedule-session index and cascade deletion."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up test fixtures."""
+        self.storage = make_storage()
+        self.user_id = "user-1"
+        self.agent_id = "agent-1"
+
+    async def test_list_sessions_by_schedule(self) -> None:
+        """Sessions created with source_schedule_id are queryable by
+        schedule."""
+        schedule = make_schedule_record(self.user_id, self.agent_id)
+        await self.storage.upsert_schedule(self.user_id, schedule)
+
+        session = await self.storage.upsert_session(
+            self.user_id,
+            self.agent_id,
+            make_session_config(),
+            source=SessionSource.SCHEDULE,
+            source_schedule_id=schedule.id,
+        )
+
+        results = await self.storage.list_sessions_by_schedule(
+            self.user_id,
+            schedule.id,
+        )
+        self.assertEqual(len(results), 1)
+        self.assertEqual(results[0].id, session.id)
+        self.assertEqual(results[0].source_schedule_id, schedule.id)
+
+    async def test_list_sessions_by_schedule_empty(self) -> None:
+        """Returns empty list when no sessions exist for a schedule."""
+        results = await self.storage.list_sessions_by_schedule(
+            self.user_id,
+            "nonexistent-schedule",
+        )
+        self.assertEqual(results, [])
+
+    async def test_schedule_session_also_in_agent_index(self) -> None:
+        """A schedule-created session appears in both the schedule and agent
+        session indexes."""
+        schedule = make_schedule_record(self.user_id, self.agent_id)
+        await self.storage.upsert_schedule(self.user_id, schedule)
+
+        session = await self.storage.upsert_session(
+            self.user_id,
+            self.agent_id,
+            make_session_config(),
+            source=SessionSource.SCHEDULE,
+            source_schedule_id=schedule.id,
+        )
+
+        agent_sessions = await self.storage.list_sessions(
+            self.user_id,
+            self.agent_id,
+        )
+        self.assertEqual(len(agent_sessions), 1)
+        self.assertEqual(agent_sessions[0].id, session.id)
+
+    async def test_delete_schedule_cascades_sessions(self) -> None:
+        """Deleting a schedule removes all its execution sessions."""
+        schedule = make_schedule_record(self.user_id, self.agent_id)
+        await self.storage.upsert_schedule(self.user_id, schedule)
+
+        await self.storage.upsert_session(
+            self.user_id,
+            self.agent_id,
+            make_session_config(),
+            source=SessionSource.SCHEDULE,
+            source_schedule_id=schedule.id,
+        )
+        await self.storage.upsert_session(
+            self.user_id,
+            self.agent_id,
+            make_session_config(),
+            source=SessionSource.SCHEDULE,
+            source_schedule_id=schedule.id,
+        )
+
+        await self.storage.delete_schedule(self.user_id, schedule.id)
+
+        schedule_sessions = await self.storage.list_sessions_by_schedule(
+            self.user_id,
+            schedule.id,
+        )
+        self.assertEqual(schedule_sessions, [])
+
+        agent_sessions = await self.storage.list_sessions(
+            self.user_id,
+            self.agent_id,
+        )
+        self.assertEqual(agent_sessions, [])
+
+    async def test_delete_session_cleans_schedule_index(self) -> None:
+        """Deleting a session removes it from the schedule session index."""
+        schedule = make_schedule_record(self.user_id, self.agent_id)
+        await self.storage.upsert_schedule(self.user_id, schedule)
+
+        session = await self.storage.upsert_session(
+            self.user_id,
+            self.agent_id,
+            make_session_config(),
+            source=SessionSource.SCHEDULE,
+            source_schedule_id=schedule.id,
+        )
+
+        await self.storage.delete_session(
+            self.user_id,
+            self.agent_id,
+            session.id,
+        )
+
+        results = await self.storage.list_sessions_by_schedule(
+            self.user_id,
+            schedule.id,
+        )
+        self.assertEqual(results, [])
+
+
+def make_team_record(
+    user_id: str,
+    session_id: str = "leader-session-1",
+    name: str = "test-team",
+    member_ids: list[str] | None = None,
+) -> TeamRecord:
+    """Create a test TeamRecord."""
+    return TeamRecord(
+        user_id=user_id,
+        session_id=session_id,
+        data=TeamData(
+            name=name,
+            member_ids=member_ids if member_ids is not None else [],
+        ),
+    )
+
+
+class TestAgentSource(IsolatedAsyncioTestCase):
+    """Tests for the ``source`` field on AgentRecord."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up test fixtures."""
+        self.storage = make_storage()
+        self.user_id = "user-1"
+
+    async def test_default_source_is_user(self) -> None:
+        """An AgentRecord built without ``source`` defaults to ``"user"``."""
+        record = make_agent_record(self.user_id)
+        self.assertEqual(record.source, "user")
+        await self.storage.upsert_agent(self.user_id, record)
+        loaded = await self.storage.get_agent(self.user_id, record.id)
+        self.assertIsNotNone(loaded)
+        self.assertEqual(loaded.source, "user")
+
+    async def test_team_source_round_trips(self) -> None:
+        """A worker AgentRecord persists ``source='team'`` through Redis."""
+        record = AgentRecord(
+            user_id=self.user_id,
+            source="team",
+            data=AgentData(
+                id="worker-1",
+                name="worker",
+                system_prompt="You are a team worker.",
+                context_config=ContextConfig(),
+                react_config=ReActConfig(),
+            ),
+        )
+        await self.storage.upsert_agent(self.user_id, record)
+        loaded = await self.storage.get_agent(self.user_id, record.id)
+        self.assertIsNotNone(loaded)
+        self.assertEqual(loaded.source, "team")
+
+    async def test_list_agents_filters_out_team_workers(self) -> None:
+        """``storage.list_agents`` returns only ``source='user'`` agents.
+        Workers (``source='team'``) are scoped to a team and addressable
+        only via direct id lookup."""
+        user_agent = make_agent_record(self.user_id)
+        worker = AgentRecord(
+            id="worker-1",
+            user_id=self.user_id,
+            source="team",
+            data=AgentData(
+                id="data-w",
+                name="worker",
+                system_prompt="",
+                context_config=ContextConfig(),
+                react_config=ReActConfig(),
+            ),
+        )
+        await self.storage.upsert_agent(self.user_id, user_agent)
+        await self.storage.upsert_agent(self.user_id, worker)
+
+        listed = await self.storage.list_agents(self.user_id)
+        listed_ids = {a.id for a in listed}
+        self.assertIn(user_agent.id, listed_ids)
+        self.assertNotIn(worker.id, listed_ids)
+
+        # But direct lookup still works for the worker.
+        loaded_worker = await self.storage.get_agent(
+            self.user_id,
+            worker.id,
+        )
+        self.assertIsNotNone(loaded_worker)
+        self.assertEqual(loaded_worker.source, "team")
+
+    async def test_legacy_record_without_source_deserializes(self) -> None:
+        """JSON written before the ``source`` field was added still loads
+        and falls back to the default ``"user"``."""
+        legacy_record = make_agent_record(self.user_id)
+        legacy_json = legacy_record.model_dump_json()
+        # Strip the new field to simulate pre-migration data.
+        import json
+
+        payload = json.loads(legacy_json)
+        payload.pop("source", None)
+        # pylint: disable=protected-access
+        key = self.storage._key(
+            self.storage.key_config.agent,
+            user_id=self.user_id,
+            agent_id=legacy_record.id,
+        )
+        await self.storage._client.set(key, json.dumps(payload))
+        await self.storage._client.sadd(
+            self.storage._key(
+                self.storage.key_config.agent_index,
+                user_id=self.user_id,
+            ),
+            legacy_record.id,
+        )
+
+        loaded = await self.storage.get_agent(self.user_id, legacy_record.id)
+        self.assertIsNotNone(loaded)
+        self.assertEqual(loaded.source, "user")
+
+
+class TestSessionTeamId(IsolatedAsyncioTestCase):
+    """Tests for the ``team_id`` field on SessionRecord."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up test fixtures."""
+        self.storage = make_storage()
+        self.user_id = "user-1"
+        self.agent_id = "agent-1"
+
+    async def test_default_team_id_is_none(self) -> None:
+        """A SessionRecord built without ``team_id`` defaults to ``None``."""
+        session = await self.storage.upsert_session(
+            self.user_id,
+            self.agent_id,
+            make_session_config(),
+        )
+        self.assertIsNone(session.team_id)
+
+        loaded = await self.storage.get_session(
+            self.user_id,
+            self.agent_id,
+            session.id,
+        )
+        self.assertIsNotNone(loaded)
+        self.assertIsNone(loaded.team_id)
+
+    async def test_legacy_session_without_team_id_deserializes(self) -> None:
+        """JSON written before ``team_id`` existed still loads with default
+        ``None``."""
+        session = await self.storage.upsert_session(
+            self.user_id,
+            self.agent_id,
+            make_session_config(),
+        )
+
+        # Strip the new field from the persisted JSON to simulate pre-migration
+        # data, then write it back at the same key.
+        import json
+
+        # pylint: disable=protected-access
+        key = self.storage._key(
+            self.storage.key_config.session,
+            user_id=self.user_id,
+            session_id=session.id,
+        )
+        raw = await self.storage._client.get(key)
+        payload = json.loads(raw)
+        payload.pop("team_id", None)
+        await self.storage._client.set(key, json.dumps(payload))
+
+        loaded = await self.storage.get_session(
+            self.user_id,
+            self.agent_id,
+            session.id,
+        )
+        self.assertIsNotNone(loaded)
+        self.assertIsNone(loaded.team_id)
+
+
+class TestTeam(IsolatedAsyncioTestCase):
+    """Tests for team CRUD."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up test fixtures."""
+        self.storage = make_storage()
+        self.user_id = "user-1"
+
+    async def test_create(self) -> None:
+        """Create a team and verify it is retrievable via list."""
+        record = make_team_record(self.user_id)
+        stored = await self.storage.upsert_team(self.user_id, record)
+        records = await self.storage.list_teams(self.user_id)
+        self.assertEqual(len(records), 1)
+        self.assertEqual(records[0].id, stored.id)
+        self.assertEqual(records[0].session_id, "leader-session-1")
+        self.assertEqual(records[0].data.name, "test-team")
+        self.assertEqual(records[0].data.member_ids, [])
+
+    async def test_list_empty(self) -> None:
+        """Verify list returns empty when no teams exist."""
+        records = await self.storage.list_teams(self.user_id)
+        self.assertEqual(records, [])
+
+    async def test_get_returns_record(self) -> None:
+        """get_team returns the persisted record by id."""
+        record = make_team_record(
+            self.user_id,
+            member_ids=["worker-a", "worker-b"],
+        )
+        await self.storage.upsert_team(self.user_id, record)
+        loaded = await self.storage.get_team(self.user_id, record.id)
+        self.assertIsNotNone(loaded)
+        self.assertEqual(loaded.id, record.id)
+        self.assertEqual(loaded.data.member_ids, ["worker-a", "worker-b"])
+
+    async def test_get_nonexistent_returns_none(self) -> None:
+        """get_team returns None when the id does not exist."""
+        loaded = await self.storage.get_team(self.user_id, "no-such-id")
+        self.assertIsNone(loaded)
+
+    async def test_update_in_place(self) -> None:
+        """Upsert with the same id overwrites the existing record."""
+        record = make_team_record(self.user_id, name="original")
+        await self.storage.upsert_team(self.user_id, record)
+
+        record.data.name = "renamed"
+        record.data.member_ids = ["new-worker"]
+        await self.storage.upsert_team(self.user_id, record)
+
+        records = await self.storage.list_teams(self.user_id)
+        self.assertEqual(len(records), 1)
+        self.assertEqual(records[0].data.name, "renamed")
+        self.assertEqual(records[0].data.member_ids, ["new-worker"])
+
+    async def test_upsert_refreshes_updated_at(self) -> None:
+        """upsert_team bumps ``updated_at`` on each write."""
+        record = make_team_record(self.user_id)
+        first = await self.storage.upsert_team(self.user_id, record)
+        first_updated = first.updated_at
+
+        # Second write must have a strictly non-decreasing updated_at.
+        second = await self.storage.upsert_team(self.user_id, record)
+        self.assertGreaterEqual(second.updated_at, first_updated)
+
+    async def test_delete(self) -> None:
+        """Delete a team and verify it is gone from Redis and the index."""
+        record = make_team_record(self.user_id)
+        await self.storage.upsert_team(self.user_id, record)
+
+        result = await self.storage.delete_team(self.user_id, record.id)
+        self.assertTrue(result)
+
+        loaded = await self.storage.get_team(self.user_id, record.id)
+        self.assertIsNone(loaded)
+        self.assertEqual(await self.storage.list_teams(self.user_id), [])
+
+    async def test_delete_nonexistent(self) -> None:
+        """delete_team returns False for an unknown id."""
+        result = await self.storage.delete_team(self.user_id, "no-such-id")
+        self.assertFalse(result)
+
+    async def test_user_isolation(self) -> None:
+        """Teams from one user are invisible to another."""
+        await self.storage.upsert_team(
+            "user-A",
+            make_team_record("user-A"),
+        )
+        records = await self.storage.list_teams("user-B")
+        self.assertEqual(records, [])
+
+
+def make_worker_agent(user_id: str, agent_id: str) -> AgentRecord:
+    """Create a source='team' worker AgentRecord."""
+    return AgentRecord(
+        id=agent_id,
+        user_id=user_id,
+        source="team",
+        data=AgentData(
+            id=f"data-{agent_id}",
+            name=f"name-{agent_id}",
+            system_prompt="worker",
+            context_config=ContextConfig(),
+            react_config=ReActConfig(),
+        ),
+    )
+
+
+class TestTeamCascade(IsolatedAsyncioTestCase):
+    """End-to-end cascade tests for the team relationship graph."""
+
+    async def asyncSetUp(self) -> None:
+        """Build a small team fixture: 1 leader user-agent + 2 workers."""
+        self.storage = make_storage()
+        self.user_id = "user-1"
+
+        # Leader agent (user-created) and its session
+        self.leader_agent = make_agent_record(self.user_id)
+        await self.storage.upsert_agent(self.user_id, self.leader_agent)
+        leader_session = await self.storage.upsert_session(
+            self.user_id,
+            self.leader_agent.id,
+            make_session_config(),
+        )
+        self.leader_session_id = leader_session.id
+
+        # Two worker agents and their sessions
+        self.worker_a = make_worker_agent(self.user_id, "worker-a")
+        self.worker_b = make_worker_agent(self.user_id, "worker-b")
+        await self.storage.upsert_agent(self.user_id, self.worker_a)
+        await self.storage.upsert_agent(self.user_id, self.worker_b)
+        worker_a_session = await self.storage.upsert_session(
+            self.user_id,
+            self.worker_a.id,
+            make_session_config(),
+        )
+        worker_b_session = await self.storage.upsert_session(
+            self.user_id,
+            self.worker_b.id,
+            make_session_config(),
+        )
+        self.worker_a_session_id = worker_a_session.id
+        self.worker_b_session_id = worker_b_session.id
+
+        # The team itself + leader's team_id back-reference
+        self.team = make_team_record(
+            self.user_id,
+            session_id=self.leader_session_id,
+            member_ids=[self.worker_a.id, self.worker_b.id],
+        )
+        await self.storage.upsert_team(self.user_id, self.team)
+
+        # Stamp team_id on every team-participating session
+        # pylint: disable=protected-access
+        for sid in [
+            self.leader_session_id,
+            self.worker_a_session_id,
+            self.worker_b_session_id,
+        ]:
+            session_key = self.storage._key(
+                self.storage.key_config.session,
+                user_id=self.user_id,
+                session_id=sid,
+            )
+            raw = await self.storage._client.get(session_key)
+            rec = SessionRecord.model_validate_json(raw)
+            rec.team_id = self.team.id
+            await self.storage._client.set(session_key, rec.model_dump_json())
+
+    async def test_delete_team_cascades_workers_and_clears_leader(
+        self,
+    ) -> None:
+        """delete_team removes all workers + sessions + clears leader."""
+        result = await self.storage.delete_team(self.user_id, self.team.id)
+        self.assertTrue(result)
+
+        # Team record gone
+        self.assertIsNone(
+            await self.storage.get_team(self.user_id, self.team.id),
+        )
+        # Worker agents gone
+        self.assertIsNone(
+            await self.storage.get_agent(self.user_id, self.worker_a.id),
+        )
+        self.assertIsNone(
+            await self.storage.get_agent(self.user_id, self.worker_b.id),
+        )
+        # Worker sessions gone
+        self.assertIsNone(
+            await self.storage.get_session(
+                self.user_id,
+                self.worker_a.id,
+                self.worker_a_session_id,
+            ),
+        )
+        # Leader session still exists, team_id cleared
+        leader = await self.storage.get_session(
+            self.user_id,
+            self.leader_agent.id,
+            self.leader_session_id,
+        )
+        self.assertIsNotNone(leader)
+        self.assertIsNone(leader.team_id)
+
+    async def test_delete_leader_session_dissolves_team(self) -> None:
+        """Deleting a leader session auto-dissolves its team."""
+        await self.storage.delete_session(
+            self.user_id,
+            self.leader_agent.id,
+            self.leader_session_id,
+        )
+
+        # Team gone
+        self.assertIsNone(
+            await self.storage.get_team(self.user_id, self.team.id),
+        )
+        # Workers gone
+        self.assertIsNone(
+            await self.storage.get_agent(self.user_id, self.worker_a.id),
+        )
+        # Leader agent itself still exists (only the session was deleted)
+        self.assertIsNotNone(
+            await self.storage.get_agent(self.user_id, self.leader_agent.id),
+        )
+
+    async def test_delete_leader_agent_dissolves_all_its_teams(self) -> None:
+        """Deleting the leader agent dissolves every team it leads."""
+        await self.storage.delete_agent(self.user_id, self.leader_agent.id)
+
+        self.assertIsNone(
+            await self.storage.get_team(self.user_id, self.team.id),
+        )
+        self.assertIsNone(
+            await self.storage.get_agent(self.user_id, self.worker_a.id),
+        )
+        self.assertIsNone(
+            await self.storage.get_agent(self.user_id, self.leader_agent.id),
+        )
+
+    async def test_direct_delete_worker_agent_scrubs_member_ids(self) -> None:
+        """Bypassing delete_team still keeps team.member_ids consistent."""
+        await self.storage.delete_agent(self.user_id, self.worker_a.id)
+
+        team = await self.storage.get_team(self.user_id, self.team.id)
+        self.assertIsNotNone(team)
+        self.assertEqual(team.data.member_ids, [self.worker_b.id])
+        # The other worker is untouched
+        self.assertIsNotNone(
+            await self.storage.get_agent(self.user_id, self.worker_b.id),
+        )
+
+    async def test_direct_delete_worker_session_does_not_dissolve_team(
+        self,
+    ) -> None:
+        """Deleting a worker's session leaves the team intact (asymmetric
+        with leader-session deletion — there's no FK from session to its
+        owning agent)."""
+        await self.storage.delete_session(
+            self.user_id,
+            self.worker_a.id,
+            self.worker_a_session_id,
+        )
+
+        # Team and worker agent still exist
+        self.assertIsNotNone(
+            await self.storage.get_team(self.user_id, self.team.id),
+        )
+        self.assertIsNotNone(
+            await self.storage.get_agent(self.user_id, self.worker_a.id),
+        )
+        # The session is gone though
+        self.assertIsNone(
+            await self.storage.get_session(
+                self.user_id,
+                self.worker_a.id,
+                self.worker_a_session_id,
+            ),
+        )
+
+    async def test_delete_team_idempotent_on_nonexistent(self) -> None:
+        """delete_team on a missing team returns False without crashing."""
+        result = await self.storage.delete_team(self.user_id, "no-such-id")
+        self.assertFalse(result)
diff --git a/tests/task_tool_test.py b/tests/task_tool_test.py
new file mode 100644
index 0000000..3c498cb
--- /dev/null
+++ b/tests/task_tool_test.py
@@ -0,0 +1,960 @@
+# -*- coding: utf-8 -*-
+"""Unit tests for task tools."""
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from utils import AnyString
+
+from agentscope.state import AgentState
+from agentscope.tool import TaskCreate, TaskGet, TaskList, TaskUpdate
+
+
+class TestTaskCreate(IsolatedAsyncioTestCase):
+    """Test cases for TaskCreate tool."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up test fixtures."""
+        self.agent_state = AgentState()
+        self.task_create = TaskCreate()
+
+    async def test_create_single_task(self) -> None:
+        """Test creating a single task."""
+        result = await self.task_create(
+            subject="Test Task 1",
+            description="This is a test task",
+            _agent_state=self.agent_state,
+        )
+
+        # Check result using model_dump
+        task_id = self.agent_state.tasks_context.tasks[0].id
+        result_dump = result.model_dump(mode="json")
+        expected_result = {
+            "content": [
+                {
+                    "text": f"Task (id={task_id}) created successfully: "
+                    f"Test Task 1",
+                    "type": "text",
+                    "id": AnyString(),
+                },
+            ],
+            "state": "running",
+            "is_last": True,
+            "metadata": {},
+            "id": AnyString(),
+        }
+        self.assertDictEqual(result_dump, expected_result)
+
+        # Check task was added to agent state using model_dump
+        tasks_dump = [
+            task.model_dump() for task in self.agent_state.tasks_context.tasks
+        ]
+        expected = [
+            {
+                "subject": "Test Task 1",
+                "description": "This is a test task",
+                "metadata": {},
+                "created_at": AnyString(),
+                "state": "pending",
+                "id": task_id,
+                "owner": None,
+                "blocks": [],
+                "blocked_by": [],
+            },
+        ]
+        self.assertEqual(tasks_dump, expected)
+
+    async def test_create_multiple_tasks(self) -> None:
+        """Test creating multiple tasks."""
+        # Create first task
+        result1 = await self.task_create(
+            subject="Task 1",
+            description="First task",
+            _agent_state=self.agent_state,
+        )
+        task1_id = self.agent_state.tasks_context.tasks[0].id
+        expected_result1 = {
+            "content": [
+                {
+                    "text": f"Task (id={task1_id}) created successfully: "
+                    f"Task 1",
+                    "type": "text",
+                    "id": AnyString(),
+                },
+            ],
+            "state": "running",
+            "is_last": True,
+            "metadata": {},
+            "id": AnyString(),
+        }
+        self.assertDictEqual(result1.model_dump(mode="json"), expected_result1)
+
+        # Create second task
+        result2 = await self.task_create(
+            subject="Task 2",
+            description="Second task",
+            _agent_state=self.agent_state,
+        )
+        task2_id = self.agent_state.tasks_context.tasks[1].id
+        expected_result2 = {
+            "content": [
+                {
+                    "text": f"Task (id={task2_id}) created successfully: "
+                    f"Task 2",
+                    "type": "text",
+                    "id": AnyString(),
+                },
+            ],
+            "state": "running",
+            "is_last": True,
+            "metadata": {},
+            "id": AnyString(),
+        }
+        self.assertDictEqual(result2.model_dump(mode="json"), expected_result2)
+
+        # Create third task with metadata
+        result3 = await self.task_create(
+            subject="Task 3",
+            description="Third task",
+            metadata={"priority": "high"},
+            _agent_state=self.agent_state,
+        )
+        task3_id = self.agent_state.tasks_context.tasks[2].id
+        expected_result3 = {
+            "content": [
+                {
+                    "text": f"Task (id={task3_id}) created successfully: "
+                    f"Task 3",
+                    "type": "text",
+                    "id": AnyString(),
+                },
+            ],
+            "state": "running",
+            "is_last": True,
+            "metadata": {},
+            "id": AnyString(),
+        }
+        self.assertDictEqual(result3.model_dump(mode="json"), expected_result3)
+
+        # Check all tasks using model_dump
+        tasks_dump = [
+            task.model_dump() for task in self.agent_state.tasks_context.tasks
+        ]
+        expected = [
+            {
+                "subject": "Task 1",
+                "description": "First task",
+                "metadata": {},
+                "created_at": AnyString(),
+                "state": "pending",
+                "id": AnyString(),
+                "owner": None,
+                "blocks": [],
+                "blocked_by": [],
+            },
+            {
+                "subject": "Task 2",
+                "description": "Second task",
+                "metadata": {},
+                "created_at": AnyString(),
+                "state": "pending",
+                "id": AnyString(),
+                "owner": None,
+                "blocks": [],
+                "blocked_by": [],
+            },
+            {
+                "subject": "Task 3",
+                "description": "Third task",
+                "metadata": {"priority": "high"},
+                "created_at": AnyString(),
+                "state": "pending",
+                "id": AnyString(),
+                "owner": None,
+                "blocks": [],
+                "blocked_by": [],
+            },
+        ]
+        self.assertEqual(tasks_dump, expected)
+
+    async def test_create_task_with_metadata(self) -> None:
+        """Test creating a task with metadata."""
+        metadata = {"priority": "high", "tags": ["urgent", "bug"]}
+        result = await self.task_create(
+            subject="Bug Fix",
+            description="Fix critical bug",
+            metadata=metadata,
+            _agent_state=self.agent_state,
+        )
+
+        # Check result using model_dump
+        task_id = self.agent_state.tasks_context.tasks[0].id
+        result_dump = result.model_dump(mode="json")
+        expected_result = {
+            "content": [
+                {
+                    "text": f"Task (id={task_id}) created successfully: "
+                    f"Bug Fix",
+                    "type": "text",
+                    "id": AnyString(),
+                },
+            ],
+            "state": "running",
+            "is_last": True,
+            "metadata": {},
+            "id": AnyString(),
+        }
+        self.assertDictEqual(result_dump, expected_result)
+
+        # Check task using model_dump
+        tasks_dump = [
+            task.model_dump() for task in self.agent_state.tasks_context.tasks
+        ]
+        expected = [
+            {
+                "subject": "Bug Fix",
+                "description": "Fix critical bug",
+                "metadata": {"priority": "high", "tags": ["urgent", "bug"]},
+                "created_at": AnyString(),
+                "state": "pending",
+                "id": AnyString(),
+                "owner": None,
+                "blocks": [],
+                "blocked_by": [],
+            },
+        ]
+        self.assertEqual(tasks_dump, expected)
+
+
+class TestTaskList(IsolatedAsyncioTestCase):
+    """Test cases for TaskList tool."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up test fixtures."""
+        self.agent_state = AgentState()
+        self.task_list = TaskList()
+        self.task_create = TaskCreate()
+
+    async def test_list_no_tasks(self) -> None:
+        """Test listing when there are no tasks."""
+        result = await self.task_list(_agent_state=self.agent_state)
+
+        self.assertEqual(len(result.content), 1)
+        self.assertEqual(result.content[0].text, "No tasks available.")
+
+    async def test_list_with_tasks(self) -> None:
+        """Test listing when there are tasks."""
+        # Create multiple tasks
+        await self.task_create(
+            subject="Task 1",
+            description="First task",
+            _agent_state=self.agent_state,
+        )
+        await self.task_create(
+            subject="Task 2",
+            description="Second task",
+            _agent_state=self.agent_state,
+        )
+        await self.task_create(
+            subject="Task 3",
+            description="Third task",
+            _agent_state=self.agent_state,
+        )
+
+        task1_id = self.agent_state.tasks_context.tasks[0].id
+        task2_id = self.agent_state.tasks_context.tasks[1].id
+        task3_id = self.agent_state.tasks_context.tasks[2].id
+
+        # List tasks
+        result = await self.task_list(_agent_state=self.agent_state)
+
+        # Check result using model_dump
+        result_dump = result.model_dump(mode="json")
+        expected_result = {
+            "content": [
+                {
+                    "text": f"{task1_id} [pending] Task 1\n"
+                    f"{task2_id} [pending] Task 2\n"
+                    f"{task3_id} [pending] Task 3",
+                    "type": "text",
+                    "id": AnyString(),
+                },
+            ],
+            "state": "running",
+            "is_last": True,
+            "metadata": {},
+            "id": AnyString(),
+        }
+        self.assertDictEqual(result_dump, expected_result)
+
+
+class TestTaskGet(IsolatedAsyncioTestCase):
+    """Test cases for TaskGet tool."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up test fixtures."""
+        self.agent_state = AgentState()
+        self.task_get = TaskGet()
+        self.task_create = TaskCreate()
+
+    async def test_get_existing_task(self) -> None:
+        """Test getting an existing task."""
+        # Create a task
+        await self.task_create(
+            subject="Test Task",
+            description="This is a test task with details",
+            metadata={"priority": "high"},
+            _agent_state=self.agent_state,
+        )
+
+        task_id = self.agent_state.tasks_context.tasks[0].id
+
+        # Get the task
+        result = await self.task_get(
+            task_id=task_id,
+            _agent_state=self.agent_state,
+        )
+
+        # Check result using model_dump
+        result_dump = result.model_dump(mode="json")
+        expected_result = {
+            "content": [
+                {
+                    "text": f"Task (id={task_id}): Test Task\n"
+                    f"Status: pending\n"
+                    f"Description: This is a test task with details\n"
+                    f"Metadata: {{'priority': 'high'}}",
+                    "type": "text",
+                    "id": AnyString(),
+                },
+            ],
+            "state": "running",
+            "is_last": True,
+            "metadata": {},
+            "id": AnyString(),
+        }
+        self.assertDictEqual(result_dump, expected_result)
+
+    async def test_get_nonexistent_task(self) -> None:
+        """Test getting a task that doesn't exist."""
+        result = await self.task_get(
+            task_id="nonexistent-id",
+            _agent_state=self.agent_state,
+        )
+
+        # Check result using model_dump
+        result_dump = result.model_dump(mode="json")
+        expected_result = {
+            "content": [
+                {
+                    "text": "Task not found",
+                    "type": "text",
+                    "id": AnyString(),
+                },
+            ],
+            "state": "error",
+            "is_last": True,
+            "metadata": {},
+            "id": AnyString(),
+        }
+        self.assertDictEqual(result_dump, expected_result)
+
+
+class TestTaskUpdate(IsolatedAsyncioTestCase):
+    """Test cases for TaskUpdate tool."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up test fixtures."""
+        self.agent_state = AgentState()
+        self.task_update = TaskUpdate()
+        self.task_create = TaskCreate()
+
+    async def test_update_subject(self) -> None:
+        """Test updating task subject."""
+        # Create a task
+        await self.task_create(
+            subject="Original Subject",
+            description="Test description",
+            _agent_state=self.agent_state,
+        )
+        task_id = self.agent_state.tasks_context.tasks[0].id
+
+        # Update subject
+        result = await self.task_update(
+            task_id=task_id,
+            subject="Updated Subject",
+            _agent_state=self.agent_state,
+        )
+
+        # Check result using model_dump
+        result_dump = result.model_dump(mode="json")
+        expected_result = {
+            "content": [
+                {
+                    "text": f"Update task (id={task_id}) subject.",
+                    "type": "text",
+                    "id": AnyString(),
+                },
+            ],
+            "state": "running",
+            "is_last": True,
+            "metadata": {},
+            "id": AnyString(),
+        }
+        self.assertDictEqual(result_dump, expected_result)
+
+        # Check task using model_dump
+        tasks_dump = [
+            task.model_dump() for task in self.agent_state.tasks_context.tasks
+        ]
+        expected = [
+            {
+                "subject": "Updated Subject",
+                "description": "Test description",
+                "metadata": {},
+                "created_at": AnyString(),
+                "state": "pending",
+                "id": task_id,
+                "owner": None,
+                "blocks": [],
+                "blocked_by": [],
+            },
+        ]
+        self.assertEqual(tasks_dump, expected)
+
+    async def test_update_description(self) -> None:
+        """Test updating task description."""
+        # Create a task
+        await self.task_create(
+            subject="Test Task",
+            description="Original description",
+            _agent_state=self.agent_state,
+        )
+        task_id = self.agent_state.tasks_context.tasks[0].id
+
+        # Update description
+        result = await self.task_update(
+            task_id=task_id,
+            description="Updated description",
+            _agent_state=self.agent_state,
+        )
+
+        # Check result using model_dump
+        result_dump = result.model_dump(mode="json")
+        expected_result = {
+            "content": [
+                {
+                    "text": f"Update task (id={task_id}) description.",
+                    "type": "text",
+                    "id": AnyString(),
+                },
+            ],
+            "state": "running",
+            "is_last": True,
+            "metadata": {},
+            "id": AnyString(),
+        }
+        self.assertDictEqual(result_dump, expected_result)
+
+        # Check task using model_dump
+        tasks_dump = [
+            task.model_dump() for task in self.agent_state.tasks_context.tasks
+        ]
+        expected = [
+            {
+                "subject": "Test Task",
+                "description": "Updated description",
+                "metadata": {},
+                "created_at": AnyString(),
+                "state": "pending",
+                "id": task_id,
+                "owner": None,
+                "blocks": [],
+                "blocked_by": [],
+            },
+        ]
+        self.assertEqual(tasks_dump, expected)
+
+    async def test_update_status(self) -> None:
+        """Test updating task status."""
+        # Create a task
+        await self.task_create(
+            subject="Test Task",
+            description="Test description",
+            _agent_state=self.agent_state,
+        )
+        task_id = self.agent_state.tasks_context.tasks[0].id
+
+        # Update status to in_progress
+        result = await self.task_update(
+            task_id=task_id,
+            status="in_progress",
+            _agent_state=self.agent_state,
+        )
+
+        # Check result using model_dump
+        result_dump = result.model_dump(mode="json")
+        expected_result = {
+            "content": [
+                {
+                    "text": f"Update task (id={task_id}) status.",
+                    "type": "text",
+                    "id": AnyString(),
+                },
+            ],
+            "state": "running",
+            "is_last": True,
+            "metadata": {},
+            "id": AnyString(),
+        }
+        self.assertDictEqual(result_dump, expected_result)
+
+        # Check task using model_dump
+        tasks_dump = [
+            task.model_dump() for task in self.agent_state.tasks_context.tasks
+        ]
+        expected = [
+            {
+                "subject": "Test Task",
+                "description": "Test description",
+                "metadata": {},
+                "created_at": AnyString(),
+                "state": "in_progress",
+                "id": task_id,
+                "owner": None,
+                "blocks": [],
+                "blocked_by": [],
+            },
+        ]
+        self.assertEqual(tasks_dump, expected)
+
+        # Update status to completed
+        result = await self.task_update(
+            task_id=task_id,
+            status="completed",
+            _agent_state=self.agent_state,
+        )
+
+        # Check result using model_dump
+        result_dump = result.model_dump(mode="json")
+        expected_result = {
+            "content": [
+                {
+                    "text": f"Update task (id={task_id}) status.\n\n"
+                    f"Task completed. "
+                    f"Call TaskList now to find your next available "
+                    f"task or see if your work unblocked others.",
+                    "type": "text",
+                    "id": AnyString(),
+                },
+            ],
+            "state": "running",
+            "is_last": True,
+            "metadata": {},
+            "id": AnyString(),
+        }
+        self.assertDictEqual(result_dump, expected_result)
+
+        # Check task using model_dump
+        tasks_dump = [
+            task.model_dump() for task in self.agent_state.tasks_context.tasks
+        ]
+        expected[0]["state"] = "completed"
+        self.assertEqual(tasks_dump, expected)
+
+        # Test deleted status - create a new task first
+        await self.task_create(
+            subject="Task to Delete",
+            description="This task will be deleted",
+            _agent_state=self.agent_state,
+        )
+        task_to_delete_id = self.agent_state.tasks_context.tasks[1].id
+
+        # Update status to deleted
+        result = await self.task_update(
+            task_id=task_to_delete_id,
+            status="deleted",
+            _agent_state=self.agent_state,
+        )
+
+        # Check result using model_dump
+        result_dump = result.model_dump(mode="json")
+        expected_result = {
+            "content": [
+                {
+                    "text": f"Task (id={task_to_delete_id}) has been deleted.",
+                    "type": "text",
+                    "id": AnyString(),
+                },
+            ],
+            "state": "running",
+            "is_last": True,
+            "metadata": {},
+            "id": AnyString(),
+        }
+        self.assertDictEqual(result_dump, expected_result)
+
+        # Check that only the first task remains
+        self.assertEqual(len(self.agent_state.tasks_context.tasks), 1)
+        self.assertEqual(self.agent_state.tasks_context.tasks[0].id, task_id)
+
+    async def test_update_owner(self) -> None:
+        """Test updating task owner."""
+        # Create a task
+        await self.task_create(
+            subject="Test Task",
+            description="Test description",
+            _agent_state=self.agent_state,
+        )
+        task_id = self.agent_state.tasks_context.tasks[0].id
+
+        # Update owner
+        result = await self.task_update(
+            task_id=task_id,
+            owner="agent-1",
+            _agent_state=self.agent_state,
+        )
+
+        # Check result using model_dump
+        result_dump = result.model_dump(mode="json")
+        expected_result = {
+            "content": [
+                {
+                    "text": f"Update task (id={task_id}) owner.",
+                    "type": "text",
+                    "id": AnyString(),
+                },
+            ],
+            "state": "running",
+            "is_last": True,
+            "metadata": {},
+            "id": AnyString(),
+        }
+        self.assertDictEqual(result_dump, expected_result)
+
+        # Check task using model_dump
+        tasks_dump = [
+            task.model_dump() for task in self.agent_state.tasks_context.tasks
+        ]
+        expected = [
+            {
+                "subject": "Test Task",
+                "description": "Test description",
+                "metadata": {},
+                "created_at": AnyString(),
+                "state": "pending",
+                "id": task_id,
+                "owner": "agent-1",
+                "blocks": [],
+                "blocked_by": [],
+            },
+        ]
+        self.assertEqual(tasks_dump, expected)
+
+    async def test_update_metadata(self) -> None:
+        """Test updating task metadata."""
+        # Create a task with initial metadata
+        await self.task_create(
+            subject="Test Task",
+            description="Test description",
+            metadata={"priority": "low", "tags": ["test"]},
+            _agent_state=self.agent_state,
+        )
+        task_id = self.agent_state.tasks_context.tasks[0].id
+
+        # Update metadata
+        result = await self.task_update(
+            task_id=task_id,
+            metadata={"priority": "high", "new_field": "value"},
+            _agent_state=self.agent_state,
+        )
+
+        # Check result using model_dump
+        result_dump = result.model_dump(mode="json")
+        expected_result = {
+            "content": [
+                {
+                    "text": f"Update task (id={task_id}) metadata.",
+                    "type": "text",
+                    "id": AnyString(),
+                },
+            ],
+            "state": "running",
+            "is_last": True,
+            "metadata": {},
+            "id": AnyString(),
+        }
+        self.assertDictEqual(result_dump, expected_result)
+
+        # Check task using model_dump
+        tasks_dump = [
+            task.model_dump() for task in self.agent_state.tasks_context.tasks
+        ]
+        expected = [
+            {
+                "subject": "Test Task",
+                "description": "Test description",
+                "metadata": {
+                    "priority": "high",
+                    "tags": ["test"],
+                    "new_field": "value",
+                },
+                "created_at": AnyString(),
+                "state": "pending",
+                "id": task_id,
+                "owner": None,
+                "blocks": [],
+                "blocked_by": [],
+            },
+        ]
+        self.assertEqual(tasks_dump, expected)
+
+    async def test_update_add_blocks(self) -> None:
+        """Test updating task blocks relationship."""
+        # Create two tasks
+        await self.task_create(
+            subject="Task 1",
+            description="First task",
+            _agent_state=self.agent_state,
+        )
+        await self.task_create(
+            subject="Task 2",
+            description="Second task",
+            _agent_state=self.agent_state,
+        )
+
+        task1_id = self.agent_state.tasks_context.tasks[0].id
+        task2_id = self.agent_state.tasks_context.tasks[1].id
+
+        # Update task1 to block task2
+        result = await self.task_update(
+            task_id=task1_id,
+            add_blocks=[task2_id],
+            _agent_state=self.agent_state,
+        )
+
+        # Check result using model_dump
+        result_dump = result.model_dump(mode="json")
+        expected_result = {
+            "content": [
+                {
+                    "text": f"Update task (id={task1_id}) add_blocks.",
+                    "type": "text",
+                    "id": AnyString(),
+                },
+            ],
+            "state": "running",
+            "is_last": True,
+            "metadata": {},
+            "id": AnyString(),
+        }
+        self.assertDictEqual(result_dump, expected_result)
+
+        # Check tasks using model_dump
+        tasks_dump = [
+            task.model_dump() for task in self.agent_state.tasks_context.tasks
+        ]
+        expected = [
+            {
+                "subject": "Task 1",
+                "description": "First task",
+                "metadata": {},
+                "created_at": AnyString(),
+                "state": "pending",
+                "id": task1_id,
+                "owner": None,
+                "blocks": [task2_id],
+                "blocked_by": [],
+            },
+            {
+                "subject": "Task 2",
+                "description": "Second task",
+                "metadata": {},
+                "created_at": AnyString(),
+                "state": "pending",
+                "id": task2_id,
+                "owner": None,
+                "blocks": [],
+                "blocked_by": [task1_id],
+            },
+        ]
+        self.assertEqual(tasks_dump, expected)
+
+    async def test_update_add_blocked_by(self) -> None:
+        """Test updating task blockedBy relationship."""
+        # Create two tasks
+        await self.task_create(
+            subject="Task 1",
+            description="First task",
+            _agent_state=self.agent_state,
+        )
+        await self.task_create(
+            subject="Task 2",
+            description="Second task",
+            _agent_state=self.agent_state,
+        )
+
+        task1_id = self.agent_state.tasks_context.tasks[0].id
+        task2_id = self.agent_state.tasks_context.tasks[1].id
+
+        # Update task2 to be blocked by task1
+        result = await self.task_update(
+            task_id=task2_id,
+            add_blocked_by=[task1_id],
+            _agent_state=self.agent_state,
+        )
+
+        # Check result using model_dump
+        result_dump = result.model_dump(mode="json")
+        expected_result = {
+            "content": [
+                {
+                    "text": f"Update task (id={task2_id}) add_blocked_by.",
+                    "type": "text",
+                    "id": AnyString(),
+                },
+            ],
+            "state": "running",
+            "is_last": True,
+            "metadata": {},
+            "id": AnyString(),
+        }
+        self.assertDictEqual(result_dump, expected_result)
+
+        # Check tasks using model_dump
+        tasks_dump = [
+            task.model_dump() for task in self.agent_state.tasks_context.tasks
+        ]
+        expected = [
+            {
+                "subject": "Task 1",
+                "description": "First task",
+                "metadata": {},
+                "created_at": AnyString(),
+                "state": "pending",
+                "id": task1_id,
+                "owner": None,
+                "blocks": [task2_id],
+                "blocked_by": [],
+            },
+            {
+                "subject": "Task 2",
+                "description": "Second task",
+                "metadata": {},
+                "created_at": AnyString(),
+                "state": "pending",
+                "id": task2_id,
+                "owner": None,
+                "blocks": [],
+                "blocked_by": [task1_id],
+            },
+        ]
+        self.assertEqual(tasks_dump, expected)
+
+    async def test_update_delete_task(self) -> None:
+        """Test deleting a task and removing it from blocks/blocked_by."""
+        # Create three tasks with dependencies
+        await self.task_create(
+            subject="Task 1",
+            description="First task",
+            _agent_state=self.agent_state,
+        )
+        await self.task_create(
+            subject="Task 2",
+            description="Second task",
+            _agent_state=self.agent_state,
+        )
+        await self.task_create(
+            subject="Task 3",
+            description="Third task",
+            _agent_state=self.agent_state,
+        )
+
+        task1_id = self.agent_state.tasks_context.tasks[0].id
+        task2_id = self.agent_state.tasks_context.tasks[1].id
+        task3_id = self.agent_state.tasks_context.tasks[2].id
+
+        # Set up dependencies: Task 1 blocks Task 2, Task 2 blocks Task 3
+        await self.task_update(
+            task_id=task1_id,
+            add_blocks=[task2_id],
+            _agent_state=self.agent_state,
+        )
+        await self.task_update(
+            task_id=task2_id,
+            add_blocks=[task3_id],
+            _agent_state=self.agent_state,
+        )
+
+        # Verify dependencies are set up correctly
+        tasks_before = [
+            task.model_dump() for task in self.agent_state.tasks_context.tasks
+        ]
+        self.assertEqual(tasks_before[0]["blocks"], [task2_id])
+        self.assertEqual(tasks_before[1]["blocked_by"], [task1_id])
+        self.assertEqual(tasks_before[1]["blocks"], [task3_id])
+        self.assertEqual(tasks_before[2]["blocked_by"], [task2_id])
+
+        # Delete task 2 (which is in the middle of the dependency chain)
+        result = await self.task_update(
+            task_id=task2_id,
+            status="deleted",
+            _agent_state=self.agent_state,
+        )
+
+        # Check result using model_dump
+        result_dump = result.model_dump(mode="json")
+        expected_result = {
+            "content": [
+                {
+                    "text": f"Task (id={task2_id}) has been deleted.",
+                    "type": "text",
+                    "id": AnyString(),
+                },
+            ],
+            "state": "running",
+            "is_last": True,
+            "metadata": {},
+            "id": AnyString(),
+        }
+        self.assertDictEqual(result_dump, expected_result)
+
+        # Check task was removed and task2_id was removed from
+        # blocks/blocked_by
+        self.assertEqual(len(self.agent_state.tasks_context.tasks), 2)
+
+        tasks_after = [
+            task.model_dump() for task in self.agent_state.tasks_context.tasks
+        ]
+        # Task 1 should no longer have task2_id in blocks
+        self.assertEqual(tasks_after[0]["id"], task1_id)
+        self.assertEqual(tasks_after[0]["blocks"], [])
+
+        # Task 3 should no longer have task2_id in blocked_by
+        self.assertEqual(tasks_after[1]["id"], task3_id)
+        self.assertEqual(tasks_after[1]["blocked_by"], [])
+
+    async def test_update_nonexistent_task(self) -> None:
+        """Test updating a task that doesn't exist."""
+        result = await self.task_update(
+            task_id="nonexistent-id",
+            subject="New Subject",
+            description=None,
+            _agent_state=self.agent_state,
+        )
+
+        # Check result using model_dump
+        result_dump = result.model_dump(mode="json")
+        expected_result = {
+            "content": [
+                {
+                    "text": "TaskNotFoundError: "
+                    "The task (id=nonexistent-id) does not exist.",
+                    "type": "text",
+                    "id": AnyString(),
+                },
+            ],
+            "state": "error",
+            "is_last": True,
+            "metadata": {},
+            "id": AnyString(),
+        }
+        self.assertDictEqual(result_dump, expected_result)
diff --git a/tests/test_template.py b/tests/test_template.py
new file mode 100644
index 0000000..b7260e9
--- /dev/null
+++ b/tests/test_template.py
@@ -0,0 +1,16 @@
+# -*- coding: utf-8 -*-
+"""A template test case."""
+from unittest.async_case import IsolatedAsyncioTestCase
+
+
+class TemplateTest(IsolatedAsyncioTestCase):
+    """The template test case."""
+
+    async def asyncSetUp(self) -> None:
+        """The async setup method."""
+
+    async def test_template(self) -> None:
+        """The template test."""
+
+    async def asyncTearDown(self) -> None:
+        """The async teardown method."""
diff --git a/tests/tool_middleware_test.py b/tests/tool_middleware_test.py
new file mode 100644
index 0000000..c9e83fa
--- /dev/null
+++ b/tests/tool_middleware_test.py
@@ -0,0 +1,344 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=unused-argument
+"""Test cases for the tool-level onion middleware mechanism."""
+from typing import Any, AsyncGenerator
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from utils import AnyString
+
+from agentscope.tool import (
+    ToolBase,
+    ToolMiddlewareBase,
+    ToolChunk,
+)
+from agentscope.message import TextBlock, ToolResultState
+from agentscope.permission import (
+    PermissionDecision,
+    PermissionBehavior,
+)
+
+
+def _expected_chunk(text: str) -> dict:
+    """Build the full expected ``ToolChunk.model_dump()`` dict for the given
+    text, with random ``id`` fields matched by :class:`AnyString`."""
+    return {
+        "content": [{"type": "text", "text": text, "id": AnyString()}],
+        "state": ToolResultState.RUNNING,
+        "is_last": True,
+        "metadata": {},
+        "id": AnyString(),
+    }
+
+
+class _NonStreamingTool(ToolBase):
+    """A tool whose ``call`` returns a single ToolChunk (coroutine)."""
+
+    name: str = "non_streaming_tool"
+    description: str = "A tool that returns a single chunk."
+    input_schema: dict = {"type": "object", "properties": {}}
+    is_concurrency_safe: bool = True
+    is_read_only: bool = True
+    is_mcp: bool = False
+
+    async def check_permissions(
+        self,
+        *args: Any,
+        **kwargs: Any,
+    ) -> PermissionDecision:
+        """Check permissions for the tool."""
+        return PermissionDecision(
+            behavior=PermissionBehavior.ALLOW,
+            message="allowed",
+        )
+
+    async def call(self, **kwargs: Any) -> ToolChunk:
+        """Run the tool, echoing back the received kwargs."""
+        return ToolChunk(
+            content=[TextBlock(text=f"call() kwargs={kwargs}")],
+        )
+
+
+class _StreamingTool(ToolBase):
+    """A tool whose ``call`` is an async generator function."""
+
+    name: str = "streaming_tool"
+    description: str = "A tool that yields several chunks."
+    input_schema: dict = {"type": "object", "properties": {}}
+    is_concurrency_safe: bool = True
+    is_read_only: bool = True
+    is_mcp: bool = False
+
+    async def check_permissions(
+        self,
+        *args: Any,
+        **kwargs: Any,
+    ) -> PermissionDecision:
+        """Check permissions for the tool."""
+        return PermissionDecision(
+            behavior=PermissionBehavior.ALLOW,
+            message="allowed",
+        )
+
+    async def call(
+        self,
+        n: int = 2,
+        **kwargs: Any,
+    ) -> AsyncGenerator[ToolChunk, None]:
+        """Yield ``n`` chunks."""
+        for i in range(n):
+            yield ToolChunk(content=[TextBlock(text=f"chunk-{i}")])
+
+
+class _NoSuperInitTool(ToolBase):
+    """A tool that overrides ``__init__`` without calling ``super().__init__``.
+
+    Used to verify the no-middleware path still works (via the ``getattr``
+    fallback for ``_middlewares``).
+    """
+
+    name: str = "no_super_init_tool"
+    description: str = "A tool that skips super().__init__()."
+    input_schema: dict = {"type": "object", "properties": {}}
+    is_concurrency_safe: bool = True
+    is_read_only: bool = True
+    is_mcp: bool = False
+
+    def __init__(self) -> None:  # pylint: disable=super-init-not-called
+        """Intentionally does not call ``super().__init__()``."""
+        self.marker = "initialized"
+
+    async def check_permissions(
+        self,
+        *args: Any,
+        **kwargs: Any,
+    ) -> PermissionDecision:
+        """Check permissions for the tool."""
+        return PermissionDecision(
+            behavior=PermissionBehavior.ALLOW,
+            message="allowed",
+        )
+
+    async def call(self, **kwargs: Any) -> ToolChunk:
+        """Run the tool."""
+        return ToolChunk(content=[TextBlock(text="no super init")])
+
+
+def _make_recording_middleware(
+    label: str,
+    execution_order: list[str],
+) -> ToolMiddlewareBase:
+    """Build a middleware that records pre/post markers in ``execution_order``
+    and transparently forwards the chunks."""
+
+    class _Middleware(ToolMiddlewareBase):
+        async def on_tool_call(
+            self,
+            tool: Any,
+            input_kwargs: dict,
+            next_handler: Any,
+        ) -> AsyncGenerator:
+            execution_order.append(f"{label}-pre")
+            async for chunk in next_handler(**input_kwargs):
+                yield chunk
+            execution_order.append(f"{label}-post")
+
+    return _Middleware()
+
+
+class ToolMiddlewareTest(IsolatedAsyncioTestCase):
+    """Tests for the tool-level onion middleware mechanism."""
+
+    async def _drain(self, result: Any) -> list[dict]:
+        """Collect all chunks from a middleware-wrapped ``__call__`` result,
+        returning their full ``model_dump()`` dicts for whole-object asserts.
+        """
+        chunks = []
+        async for chunk in result:
+            chunks.append(chunk.model_dump())
+        return chunks
+
+    async def test_no_middleware_non_streaming(self) -> None:
+        """A non-streaming tool with no middleware returns a single chunk."""
+        tool = _NonStreamingTool()
+        result = await tool()
+        self.assertIsInstance(result, ToolChunk)
+        self.assertEqual(
+            result.model_dump(),
+            _expected_chunk("call() kwargs={}"),
+        )
+
+    async def test_no_middleware_streaming(self) -> None:
+        """A streaming tool with no middleware yields its chunks directly."""
+        tool = _StreamingTool()
+        result = await tool(n=3)
+        chunks = await self._drain(result)
+        self.assertEqual(
+            chunks,
+            [
+                _expected_chunk("chunk-0"),
+                _expected_chunk("chunk-1"),
+                _expected_chunk("chunk-2"),
+            ],
+        )
+
+    async def test_middleware_wraps_call_in_onion_order(self) -> None:
+        """Two middlewares wrap call() in the correct onion order.
+
+        Execution order must be:
+        outer-pre -> inner-pre -> call() -> inner-post -> outer-post.
+        """
+        execution_order: list[str] = []
+        tool = _NonStreamingTool(
+            middlewares=[
+                _make_recording_middleware("outer", execution_order),
+                _make_recording_middleware("inner", execution_order),
+            ],
+        )
+
+        chunks = await self._drain(await tool())
+
+        self.assertEqual(chunks, [_expected_chunk("call() kwargs={}")])
+        self.assertEqual(
+            execution_order,
+            ["outer-pre", "inner-pre", "inner-post", "outer-post"],
+        )
+
+    async def test_single_middleware(self) -> None:
+        """A single middleware fires pre and post around call()."""
+        execution_order: list[str] = []
+        tool = _NonStreamingTool(
+            middlewares=[_make_recording_middleware("only", execution_order)],
+        )
+
+        chunks = await self._drain(await tool())
+
+        self.assertEqual(chunks, [_expected_chunk("call() kwargs={}")])
+        self.assertEqual(execution_order, ["only-pre", "only-post"])
+
+    async def test_middleware_with_streaming_tool(self) -> None:
+        """Middleware transparently forwards each chunk of a streaming tool."""
+        execution_order: list[str] = []
+        tool = _StreamingTool(
+            middlewares=[_make_recording_middleware("mw", execution_order)],
+        )
+
+        chunks = await self._drain(await tool(n=3))
+
+        self.assertEqual(
+            chunks,
+            [
+                _expected_chunk("chunk-0"),
+                _expected_chunk("chunk-1"),
+                _expected_chunk("chunk-2"),
+            ],
+        )
+        self.assertEqual(execution_order, ["mw-pre", "mw-post"])
+
+    async def test_middleware_can_rewrite_input_kwargs(self) -> None:
+        """A middleware can mutate input_kwargs so the tool sees new args."""
+
+        class _RewriteMiddleware(ToolMiddlewareBase):
+            async def on_tool_call(
+                self,
+                tool: Any,
+                input_kwargs: dict,
+                next_handler: Any,
+            ) -> AsyncGenerator:
+                input_kwargs["injected"] = "value"
+                async for chunk in next_handler(**input_kwargs):
+                    yield chunk
+
+        tool = _NonStreamingTool(middlewares=[_RewriteMiddleware()])
+        chunks = await self._drain(await tool(original="x"))
+
+        self.assertEqual(
+            chunks,
+            [
+                _expected_chunk(
+                    "call() kwargs={'original': 'x', 'injected': 'value'}",
+                ),
+            ],
+        )
+
+    async def test_middleware_can_transform_chunks(self) -> None:
+        """A middleware can transform the chunks yielded by the tool."""
+
+        class _UppercaseMiddleware(ToolMiddlewareBase):
+            async def on_tool_call(
+                self,
+                tool: Any,
+                input_kwargs: dict,
+                next_handler: Any,
+            ) -> AsyncGenerator:
+                async for chunk in next_handler(**input_kwargs):
+                    yield ToolChunk(
+                        content=[
+                            TextBlock(text=chunk.content[0].text.upper()),
+                        ],
+                    )
+
+        tool = _StreamingTool(middlewares=[_UppercaseMiddleware()])
+        chunks = await self._drain(await tool(n=2))
+
+        self.assertEqual(
+            chunks,
+            [_expected_chunk("CHUNK-0"), _expected_chunk("CHUNK-1")],
+        )
+
+    async def test_middleware_can_short_circuit(self) -> None:
+        """A middleware that never calls next_handler skips the tool."""
+        called = {"value": False}
+
+        class _ShortCircuitTool(_NonStreamingTool):
+            async def call(self, **kwargs: Any) -> ToolChunk:
+                called["value"] = True
+                return await super().call(**kwargs)
+
+        class _ShortCircuitMiddleware(ToolMiddlewareBase):
+            async def on_tool_call(
+                self,
+                tool: Any,
+                input_kwargs: dict,
+                next_handler: Any,
+            ) -> AsyncGenerator:
+                yield ToolChunk(content=[TextBlock(text="short-circuited")])
+
+        tool = _ShortCircuitTool(middlewares=[_ShortCircuitMiddleware()])
+        chunks = await self._drain(await tool())
+
+        self.assertFalse(called["value"])
+        self.assertEqual(chunks, [_expected_chunk("short-circuited")])
+
+    async def test_middleware_exception_propagates(self) -> None:
+        """An exception raised in a middleware propagates to the caller."""
+
+        class _BoomMiddleware(ToolMiddlewareBase):
+            async def on_tool_call(
+                self,
+                tool: Any,
+                input_kwargs: dict,
+                next_handler: Any,
+            ) -> AsyncGenerator:
+                raise ValueError("boom")
+                yield  # pylint: disable=unreachable
+
+        tool = _NonStreamingTool(middlewares=[_BoomMiddleware()])
+
+        with self.assertRaises(ValueError):
+            await self._drain(await tool())
+
+    async def test_positional_args_rejected(self) -> None:
+        """Calling a tool with positional args raises TypeError instead of
+        silently dropping them."""
+        tool = _NonStreamingTool()
+        with self.assertRaises(TypeError):
+            await tool("positional")  # type: ignore[call-arg]
+
+    async def test_missing_super_init_no_middleware(self) -> None:
+        """A tool that skips super().__init__() still works on the
+        no-middleware path via the getattr fallback for _middlewares."""
+        tool = _NoSuperInitTool()
+        self.assertFalse(hasattr(tool, "_middlewares"))
+        result = await tool()
+        self.assertIsInstance(result, ToolChunk)
+        self.assertEqual(result.model_dump(), _expected_chunk("no super init"))
diff --git a/tests/tool_offload_middleware_test.py b/tests/tool_offload_middleware_test.py
new file mode 100644
index 0000000..6b82bb5
--- /dev/null
+++ b/tests/tool_offload_middleware_test.py
@@ -0,0 +1,400 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Unit tests for ToolOffloadMiddleware."""
+import asyncio
+import json
+from typing import Any
+from unittest.async_case import IsolatedAsyncioTestCase
+from unittest.mock import MagicMock
+
+from pydantic import BaseModel
+
+
+from utils import AnyString, MockModel
+
+from agentscope.agent import Agent
+from agentscope.app.message_bus import MessageBus, MessageBusKeys
+from agentscope.app.middleware import ToolOffloadMiddleware
+from agentscope.app._manager import BackgroundTaskManager
+from agentscope.message import TextBlock, ToolCallBlock
+from agentscope.permission import (
+    PermissionContext,
+    PermissionDecision,
+    PermissionBehavior,
+)
+from agentscope.tool import ToolBase, ToolChunk, Toolkit, ToolResponse
+
+
+class _SlowToolParams(BaseModel):
+    """Parameters for the slow test tool."""
+
+    delay: float
+
+
+class SlowTool(ToolBase):
+    """A tool that sleeps for ``delay`` seconds before returning."""
+
+    name: str = "slow_tool"
+    description: str = "A slow tool for testing background offload."
+    input_schema: dict = _SlowToolParams.model_json_schema()
+    is_concurrency_safe: bool = True
+    is_read_only: bool = True
+    is_state_injected: bool = False
+    is_external_tool: bool = False
+    is_mcp: bool = False
+    mcp_name: str | None = None
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        """Always allow.
+
+        Args:
+            tool_input (`dict[str, Any]`):
+                The tool input parameters.
+            context (`PermissionContext`):
+                The permission context.
+
+        Returns:
+            `PermissionDecision`:
+                Always ALLOW.
+        """
+        return PermissionDecision(
+            behavior=PermissionBehavior.ALLOW,
+            message="allowed",
+        )
+
+    async def __call__(  # type: ignore[override]
+        self,
+        delay: float,
+    ) -> ToolChunk:
+        """Sleep for *delay* seconds then return a result.
+
+        Args:
+            delay (`float`):
+                Seconds to sleep.
+
+        Returns:
+            `ToolChunk`:
+                A chunk containing the result text.
+        """
+        await asyncio.sleep(delay)
+        return ToolChunk(
+            content=[TextBlock(text=f"SlowTool finished after {delay}s")],
+        )
+
+
+class _FastToolParams(BaseModel):
+    """Parameters for the fast test tool."""
+
+    value: str
+
+
+class FastTool(ToolBase):
+    """A tool that returns immediately."""
+
+    name: str = "fast_tool"
+    description: str = "A fast tool for testing normal execution."
+    input_schema: dict = _FastToolParams.model_json_schema()
+    is_concurrency_safe: bool = True
+    is_read_only: bool = True
+    is_state_injected: bool = False
+    is_external_tool: bool = False
+    is_mcp: bool = False
+    mcp_name: str | None = None
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        """Always allow.
+
+        Args:
+            tool_input (`dict[str, Any]`):
+                The tool input parameters.
+            context (`PermissionContext`):
+                The permission context.
+
+        Returns:
+            `PermissionDecision`:
+                Always ALLOW.
+        """
+        return PermissionDecision(
+            behavior=PermissionBehavior.ALLOW,
+            message="allowed",
+        )
+
+    async def __call__(  # type: ignore[override]
+        self,
+        value: str,
+    ) -> ToolChunk:
+        """Return a chunk with *value*.
+
+        Args:
+            value (`str`):
+                The value to echo.
+
+        Returns:
+            `ToolChunk`:
+                A chunk containing the value.
+        """
+        return ToolChunk(
+            content=[TextBlock(text=f"FastTool: {value}")],
+        )
+
+
+class ToolOffloadMiddlewareTest(IsolatedAsyncioTestCase):
+    """Test cases for the ToolOffloadMiddleware."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up test fixtures."""
+        self.mock_model = MockModel()
+        self.bg_manager = BackgroundTaskManager(
+            message_bus=MagicMock(spec=MessageBus),
+        )
+
+    # ------------------------------------------------------------------
+    # Helper
+    # ------------------------------------------------------------------
+
+    def _make_agent(
+        self,
+        toolkit: Toolkit,
+        timeout_secs: float,
+    ) -> tuple[Agent, ToolOffloadMiddleware]:
+        """Create an agent with ToolOffloadMiddleware attached.
+
+        Args:
+            toolkit (`Toolkit`):
+                The toolkit to attach to the agent.
+            timeout_secs (`float`):
+                The middleware timeout.
+
+        Returns:
+            `tuple[Agent, ToolOffloadMiddleware]`:
+                The configured agent and the middleware instance.
+        """
+        middleware = ToolOffloadMiddleware(
+            bg_manager=self.bg_manager,
+            message_bus=MagicMock(spec=MessageBus),
+            user_id="u",
+            agent_id="a",
+            timeout_secs=timeout_secs,
+        )
+        agent = Agent(
+            name="test_agent",
+            system_prompt="test prompt",
+            model=self.mock_model,
+            toolkit=toolkit,
+            middlewares=[middleware],
+        )
+        return agent, middleware
+
+    # ------------------------------------------------------------------
+    # Tests
+    # ------------------------------------------------------------------
+
+    async def test_fast_tool_completes_normally(self) -> None:
+        """A tool that finishes within the timeout yields its real result."""
+
+        toolkit = Toolkit(tools=[FastTool()])
+        agent, _ = self._make_agent(toolkit, timeout_secs=5.0)
+
+        tool_call = ToolCallBlock(
+            id="call_fast",
+            name="fast_tool",
+            input=json.dumps({"value": "hello"}),
+        )
+
+        results: list = []
+        # pylint: disable=protected-access
+        async for item in agent._acting(tool_call):
+            results.append(item)
+
+        # Should yield real ToolResponse (not synthetic)
+        responses = [r for r in results if isinstance(r, ToolResponse)]
+        self.assertEqual(len(responses), 1)
+        text = responses[0].content[0].text  # type: ignore[union-attr]
+        self.assertIn("FastTool: hello", text)
+        # No background tasks registered
+        self.assertEqual(len(self.bg_manager.tasks), 0)
+
+    async def test_slow_tool_offloaded_to_background(self) -> None:
+        """A tool that exceeds timeout returns a synthetic result."""
+
+        toolkit = Toolkit(tools=[SlowTool()])
+        # Set a very short timeout so the 0.5s tool is always offloaded
+        agent, _ = self._make_agent(toolkit, timeout_secs=0.05)
+
+        tool_call = ToolCallBlock(
+            id="call_slow",
+            name="slow_tool",
+            input=json.dumps({"delay": 0.5}),
+        )
+
+        results: list = []
+        # pylint: disable=protected-access
+        async for item in agent._acting(tool_call):
+            results.append(item)
+
+        # Should yield a synthetic ToolResponse immediately
+        responses = [r for r in results if isinstance(r, ToolResponse)]
+        self.assertEqual(len(responses), 1)
+        self.assertDictEqual(
+            responses[0].model_dump(),
+            {
+                "content": [
+                    {
+                        "type": "text",
+                        "text": AnyString(),
+                        "id": AnyString(),
+                    },
+                ],
+                "state": "success",
+                "metadata": {},
+                "id": "call_slow",
+            },
+        )
+        text = responses[0].content[0].text  # type: ignore[union-attr]
+        self.assertIn("background", text)
+        self.assertIn("id=", text)
+
+        # Background task should be registered
+        self.assertEqual(len(self.bg_manager.tasks), 1)
+
+    async def test_background_task_result_injected_into_context(
+        self,
+    ) -> None:
+        """After the background tool finishes, the result is pushed to the
+        session inbox on the message bus as a serialised HintBlock."""
+
+        toolkit = Toolkit(tools=[SlowTool()])
+        agent, middleware = self._make_agent(toolkit, timeout_secs=0.05)
+
+        tool_call = ToolCallBlock(
+            id="call_bg",
+            name="slow_tool",
+            input=json.dumps({"delay": 0.2}),
+        )
+
+        # Trigger offload
+        # pylint: disable=protected-access
+        async for _ in agent._acting(tool_call):
+            pass
+
+        # Wait long enough for the background tool (0.2s) to finish
+        await asyncio.sleep(0.4)
+
+        # The completed result should now have been pushed to the message bus
+        # inbox as a model-dumped HintBlock.
+        mock_bus = middleware._message_bus
+        # The middleware uses queue_push(inbox_key, payload) rather
+        # than the deprecated inbox_push(session_id, payload).
+        inbox_calls = [
+            c
+            for c in mock_bus.queue_push.call_args_list
+            if c.args[0] == MessageBusKeys.inbox(agent.state.session_id)
+        ]
+        self.assertEqual(len(inbox_calls), 1)
+        _, hint_dict = inbox_calls[0].args
+        session_id_called = agent.state.session_id
+        self.assertEqual(session_id_called, agent.state.session_id)
+        self.maxDiff = None
+        self.assertDictEqual(
+            hint_dict,
+            {
+                "type": "hint",
+                "id": AnyString(),
+                "source": '{"label": "tool_output", "sublabel": "slow_tool · '
+                'call_bg"}',
+                "hint": [
+                    {
+                        "type": "text",
+                        "text": AnyString(),
+                        "id": AnyString(),
+                    },
+                ],
+            },
+        )
+        hint_text = hint_dict["hint"][0]["text"]
+        self.assertIn("SlowTool finished", hint_text)
+        self.assertIn("<system-notification>", hint_text)
+
+    async def test_background_task_triggers_wakeup_on_completion(
+        self,
+    ) -> None:
+        """After a background tool finishes, a wakeup is enqueued on the
+        message bus so that an idle session can be restarted automatically."""
+
+        toolkit = Toolkit(tools=[SlowTool()])
+        agent, middleware = self._make_agent(toolkit, timeout_secs=0.05)
+
+        tool_call = ToolCallBlock(
+            id="call_wakeup",
+            name="slow_tool",
+            input=json.dumps({"delay": 0.2}),
+        )
+
+        # Trigger offload
+        # pylint: disable=protected-access
+        async for _ in agent._acting(tool_call):
+            pass
+
+        # Wait long enough for the background tool (0.2s) to finish
+        await asyncio.sleep(0.4)
+
+        # enqueue_wakeup must be called exactly once with the correct ids so
+        # WakeupDispatcher can re-invoke ChatService.run for this session.
+        mock_bus = middleware._message_bus
+        # enqueue_run_trigger is a standalone function that calls
+        # bus.queue_push + bus.publish under the hood.
+        wakeup_calls = [
+            c
+            for c in mock_bus.queue_push.call_args_list
+            if c.args[0] == MessageBusKeys.wakeup_queue()
+        ]
+        self.assertEqual(len(wakeup_calls), 1)
+        payload = wakeup_calls[0].args[1]
+        self.assertEqual(payload["user_id"], "u")
+        self.assertEqual(payload["session_id"], agent.state.session_id)
+        self.assertEqual(payload["agent_id"], "a")
+
+    async def test_tool_stop_cancels_background_task(self) -> None:
+        """ToolStop tool cancels the running background asyncio task."""
+
+        toolkit = Toolkit(tools=[SlowTool()])
+        agent, _ = self._make_agent(toolkit, timeout_secs=0.05)
+
+        tool_call = ToolCallBlock(
+            id="call_cancel",
+            name="slow_tool",
+            input=json.dumps({"delay": 10.0}),
+        )
+
+        # Offload the slow tool
+        # pylint: disable=protected-access
+        async for _ in agent._acting(tool_call):
+            pass
+
+        self.assertEqual(len(self.bg_manager.tasks), 1)
+        task_id = next(iter(self.bg_manager.tasks))
+        bg_task = self.bg_manager.tasks[task_id]
+        asyncio_task = bg_task.asyncio_task
+
+        # Call ToolStop bound to the same session as the registered
+        # background task, so the local cancel path matches.
+        tool_stop_tools = await self.bg_manager.list_tools(
+            session_id=bg_task.session_id,
+        )
+        tool_stop = tool_stop_tools[0]
+        result = await tool_stop(task_id=task_id)
+        text = result.content[0].text  # type: ignore[union-attr]
+        self.assertIn("stopped successfully", text)
+
+        # The asyncio task should be cancelling
+        self.assertTrue(asyncio_task.cancelled() or asyncio_task.cancelling())
+        # Removed from manager
+        self.assertEqual(len(self.bg_manager.tasks), 0)
diff --git a/tests/toolkit_skill_test.py b/tests/toolkit_skill_test.py
new file mode 100644
index 0000000..5194352
--- /dev/null
+++ b/tests/toolkit_skill_test.py
@@ -0,0 +1,408 @@
+# -*- coding: utf-8 -*-
+"""Test cases for Toolkit skill-related functionality."""
+import json
+import os
+import tempfile
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from utils import AnyString
+
+from agentscope.skill import SkillLoaderBase, Skill
+from agentscope.tool import Toolkit, ToolChunk, ToolResponse, ToolGroup
+from agentscope.message import ToolCallBlock
+from agentscope.state import AgentState
+
+
+def _make_skill(
+    name: str,
+    description: str = "desc",
+    dir_: str = "/tmp",
+) -> Skill:
+    """Helper function to create a Skill object for testing."""
+    return Skill(
+        name=name,
+        description=description,
+        dir=dir_,
+        markdown="",
+        updated_at=0.0,
+    )
+
+
+class MockSkillLoader(SkillLoaderBase):
+    """A mock skill loader for testing."""
+
+    def __init__(self, skills: list[Skill]) -> None:
+        self._skills = skills
+
+    async def list_skills(self) -> list[Skill]:
+        """Return a list of all skills."""
+        return self._skills
+
+
+class ToolkitSkillTest(IsolatedAsyncioTestCase):
+    """Test cases for Toolkit skill functionality."""
+
+    async def test_init_with_various_types(self) -> None:
+        """Test Toolkit initialization with str path, SkillLoaderBase, and
+        direct Skill objects, then assert get_skill_instructions output."""
+        with tempfile.TemporaryDirectory() as skill_dir:
+            # Create a minimal SKILL.md so LocalSkillLoader can load it
+            skill_md_path = os.path.join(skill_dir, "SKILL.md")
+            with open(skill_md_path, "w", encoding="utf-8") as f:
+                f.write(
+                    "---\n"
+                    "name: path_skill\n"
+                    "description: A skill loaded from a path\n"
+                    "---\n\n"
+                    "# Path Skill\n",
+                )
+
+            loader_skill = _make_skill(
+                "loader_skill",
+                description="A skill from loader",
+                dir_="/loader/dir",
+            )
+            direct_skill = _make_skill(
+                "direct_skill",
+                description="A directly provided skill",
+                dir_="/direct/dir",
+            )
+
+            toolkit = Toolkit(
+                skills_or_loaders=[
+                    skill_dir,  # str -> LocalSkillLoader
+                    MockSkillLoader([loader_skill]),  # SkillLoaderBase
+                    direct_skill,  # Skill directly
+                ],
+            )
+
+            result = await toolkit.get_skill_instructions()
+
+            self.assertEqual(
+                result,
+                # pylint: disable=line-too-long
+                f"""<agent-skills>
+Skills are a collection of instructions, scripts, and resources to extend your capabilities.
+
+**IMPORTANT**: Skills are NOT tools, and you cannot call a skill directly. To use a skill, you MUST use the `Skill` tool to read the skill's full instructions, and then follow those instructions to use the tools and resources provided by the skill.
+
+# Available Skills:
+<skill>
+<name>path_skill</name>
+<description>A skill loaded from a path</description>
+<dir>{skill_dir}</dir>
+</skill>
+<skill>
+<name>loader_skill</name>
+<description>A skill from loader</description>
+<dir>/loader/dir</dir>
+</skill>
+<skill>
+<name>direct_skill</name>
+<description>A directly provided skill</description>
+<dir>/direct/dir</dir>
+</skill>
+</agent-skills>""",  # noqa: E501
+            )
+
+    async def test_get_skill_instructions_no_skills(self) -> None:
+        """Test that get_skill_instructions returns None when no skills
+        registered."""
+        toolkit = Toolkit()
+        result = await toolkit.get_skill_instructions()
+        self.assertIsNone(result)
+
+    async def test_get_skill_instructions_multiple_loaders(self) -> None:
+        """Test that get_skill_instructions aggregates skills from multiple
+        loaders."""
+        loader1 = MockSkillLoader([_make_skill("skill_x")])
+        loader2 = MockSkillLoader([_make_skill("skill_y")])
+        toolkit = Toolkit(skills_or_loaders=[loader1, loader2])
+
+        result = await toolkit.get_skill_instructions()
+
+        self.assertEqual(
+            result,
+            # pylint: disable=line-too-long
+            """<agent-skills>
+Skills are a collection of instructions, scripts, and resources to extend your capabilities.
+
+**IMPORTANT**: Skills are NOT tools, and you cannot call a skill directly. To use a skill, you MUST use the `Skill` tool to read the skill's full instructions, and then follow those instructions to use the tools and resources provided by the skill.
+
+# Available Skills:
+<skill>
+<name>skill_x</name>
+<description>desc</description>
+<dir>/tmp</dir>
+</skill>
+<skill>
+<name>skill_y</name>
+<description>desc</description>
+<dir>/tmp</dir>
+</skill>
+</agent-skills>""",  # noqa: E501
+        )
+
+    async def test_get_skill_instructions_empty_loader(self) -> None:
+        """Test that an empty loader contributes no skills."""
+        loader = MockSkillLoader([])
+        toolkit = Toolkit(skills_or_loaders=[loader])
+
+        result = await toolkit.get_skill_instructions()
+        self.assertIsNone(result)
+
+    async def test_get_skill_instructions_includes_tool_group_skills(
+        self,
+    ) -> None:
+        """Test that skill instructions include skills from custom groups."""
+        toolkit = Toolkit(
+            tool_groups=[
+                ToolGroup(
+                    name="repair",
+                    description="Repair tools",
+                    skills_or_loaders=[
+                        MockSkillLoader([_make_skill("repair_skill")]),
+                    ],
+                ),
+            ],
+        )
+
+        result = await toolkit.get_skill_instructions()
+
+        self.assertIsNotNone(result)
+        assert result is not None
+        self.assertIn("<name>repair_skill</name>", result)
+
+    async def test_get_skill_instructions_filters_inactive_group_skills(
+        self,
+    ) -> None:
+        """Test that inactive group skills are hidden from the prompt."""
+        toolkit = Toolkit(
+            skills_or_loaders=[MockSkillLoader([_make_skill("basic_skill")])],
+            tool_groups=[
+                ToolGroup(
+                    name="repair",
+                    description="Repair tools",
+                    skills_or_loaders=[
+                        MockSkillLoader([_make_skill("repair_skill")]),
+                    ],
+                ),
+            ],
+        )
+
+        inactive_result = await toolkit.get_skill_instructions(
+            activated_groups=[],
+        )
+        active_result = await toolkit.get_skill_instructions(
+            activated_groups=["repair"],
+        )
+
+        self.assertIsNotNone(inactive_result)
+        self.assertIsNotNone(active_result)
+        assert inactive_result is not None
+        assert active_result is not None
+        self.assertIn("<name>basic_skill</name>", inactive_result)
+        self.assertNotIn("<name>repair_skill</name>", inactive_result)
+        self.assertIn("<name>basic_skill</name>", active_result)
+        self.assertIn("<name>repair_skill</name>", active_result)
+
+
+class ToolkitSkillViewerTest(IsolatedAsyncioTestCase):
+    """Test cases for Toolkit SkillViewer functionality."""
+
+    async def test_register_skill_and_get_function_schemas(self) -> None:
+        """Test that registering skills makes SkillViewer available in
+        function schemas."""
+        skill = _make_skill("test_skill", description="A test skill")
+        loader = MockSkillLoader([skill])
+        toolkit = Toolkit(skills_or_loaders=[loader])
+
+        schemas = await toolkit.get_tool_schemas()
+
+        self.assertListEqual(
+            schemas,
+            [
+                {
+                    "type": "function",
+                    "function": {
+                        "name": "Skill",
+                        "description": (
+                            "Retrieve a skill within the conversation. "
+                            "When users asks you to perform tasks, check if "
+                            "any of the available skills match. "
+                            "Skills provide specialized capabilities and "
+                            "domain knowledge."
+                        ),
+                        "parameters": {
+                            "type": "object",
+                            "properties": {
+                                "skill": {
+                                    "type": "string",
+                                    "description": "The exact name of the "
+                                    "skill to view. ",
+                                },
+                            },
+                            "required": ["skill"],
+                        },
+                    },
+                },
+            ],
+        )
+
+    async def test_call_skill_viewer_success(self) -> None:
+        """Test calling SkillViewer with an existing skill."""
+        skill = _make_skill(
+            "my_skill",
+            description="My test skill",
+            dir_="/test/dir",
+        )
+        skill.markdown = "# My Skill\nThis is the skill content."
+        loader = MockSkillLoader([skill])
+        toolkit = Toolkit(skills_or_loaders=[loader])
+
+        tool_call = ToolCallBlock(
+            id="test_call_1",
+            name="Skill",
+            input=json.dumps({"skill": "my_skill"}),
+        )
+        state = AgentState()
+
+        chunks = []
+        response = None
+        async for result in toolkit.call_tool(tool_call, state):
+            if isinstance(result, ToolChunk):
+                chunks.append(result)
+            elif isinstance(result, ToolResponse):
+                response = result
+
+        self.assertEqual(len(chunks), 1)
+        self.assertDictEqual(
+            chunks[0].model_dump(),
+            {
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": "# My Skill\nThis is the skill content.",
+                    },
+                ],
+                "state": "running",
+                "is_last": True,
+                "metadata": {},
+                "id": AnyString(),
+            },
+        )
+
+        self.assertIsNotNone(response)
+        self.assertDictEqual(
+            response.model_dump(),
+            {
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": "# My Skill\nThis is the skill content.",
+                    },
+                ],
+                "state": "success",
+                "metadata": {},
+                "id": "test_call_1",
+            },
+        )
+
+    async def test_call_skill_viewer_not_found(self) -> None:
+        """Test calling SkillViewer with a non-existent skill."""
+        skill = _make_skill("existing_skill")
+        loader = MockSkillLoader([skill])
+        toolkit = Toolkit(skills_or_loaders=[loader])
+
+        tool_call = ToolCallBlock(
+            id="test_call_2",
+            name="Skill",
+            input=json.dumps({"skill": "non_existent_skill"}),
+        )
+        state = AgentState()
+
+        chunks = []
+        response = None
+        async for result in toolkit.call_tool(tool_call, state):
+            if isinstance(result, ToolChunk):
+                chunks.append(result)
+            elif isinstance(result, ToolResponse):
+                response = result
+
+        self.assertEqual(len(chunks), 1)
+        self.assertDictEqual(
+            chunks[0].model_dump(),
+            {
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": "SkillNotFoundError: "
+                        "Skill 'non_existent_skill' not found.",
+                    },
+                ],
+                "state": "error",
+                "is_last": True,
+                "metadata": {},
+                "id": AnyString(),
+            },
+        )
+
+        self.assertIsNotNone(response)
+        self.assertDictEqual(
+            response.model_dump(),
+            {
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": "SkillNotFoundError: "
+                        "Skill 'non_existent_skill' not found.",
+                    },
+                ],
+                "state": "error",
+                "metadata": {},
+                "id": "test_call_2",
+            },
+        )
+
+    async def test_skill_viewer_uses_active_tool_group_skills(self) -> None:
+        """Test that activated custom-group skills expose SkillViewer."""
+        skill = _make_skill("repair_skill")
+        skill.markdown = "# Repair Skill\nUse this for repair tasks."
+        toolkit = Toolkit(
+            tool_groups=[
+                ToolGroup(
+                    name="repair",
+                    description="Repair tools",
+                    skills_or_loaders=[MockSkillLoader([skill])],
+                ),
+            ],
+        )
+
+        schema_names = [
+            schema["function"]["name"]
+            for schema in await toolkit.get_tool_schemas(groups=["repair"])
+        ]
+        self.assertIn("Skill", schema_names)
+
+        tool_call = ToolCallBlock(
+            id="test_call_group_skill",
+            name="Skill",
+            input=json.dumps({"skill": "repair_skill"}),
+        )
+        state = AgentState()
+        state.tool_context.activated_groups.append("repair")
+
+        chunks = []
+        async for result in toolkit.call_tool(tool_call, state):
+            if isinstance(result, ToolChunk):
+                chunks.append(result)
+
+        self.assertEqual(len(chunks), 1)
+        self.assertEqual(
+            chunks[0].content[0].text,
+            "# Repair Skill\nUse this for repair tasks.",
+        )
diff --git a/tests/toolkit_task_test.py b/tests/toolkit_task_test.py
new file mode 100644
index 0000000..280e67f
--- /dev/null
+++ b/tests/toolkit_task_test.py
@@ -0,0 +1,1187 @@
+# -*- coding: utf-8 -*-
+"""Unit tests for task tools executed through toolkit."""
+import json
+from typing import Any
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from utils import AnyString
+
+from agentscope.message import ToolCallBlock
+from agentscope.state import AgentState
+from agentscope.tool import (
+    Toolkit,
+    ToolResponse,
+    TaskCreate,
+    TaskGet,
+    TaskList,
+    TaskUpdate,
+)
+
+
+class _ToolkitTaskTestBase(IsolatedAsyncioTestCase):
+    """Shared helpers for toolkit task tool tests."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up shared test fixtures."""
+        self.agent_state = AgentState()
+        self.toolkit = Toolkit(
+            tools=[
+                TaskCreate(),
+                TaskList(),
+                TaskGet(),
+                TaskUpdate(),
+            ],
+        )
+
+    async def _call_tool(
+        self,
+        name: str,
+        tool_input: dict[str, Any],
+        tool_call_id: str,
+    ) -> ToolResponse:
+        """Call a task tool through toolkit and return the final response."""
+        response = None
+        async for result in self.toolkit.call_tool(
+            ToolCallBlock(
+                id=tool_call_id,
+                name=name,
+                input=json.dumps(tool_input),
+            ),
+            self.agent_state,
+        ):
+            if isinstance(result, ToolResponse):
+                response = result
+
+        self.assertIsNotNone(response)
+        return response
+
+    def _dump_tasks(self) -> list[dict[str, Any]]:
+        """Dump all tasks from the agent state for assertions."""
+        return [
+            task.model_dump() for task in self.agent_state.tasks_context.tasks
+        ]
+
+
+class TestToolkitTaskCreate(_ToolkitTaskTestBase):
+    """Test cases for TaskCreate through toolkit."""
+
+    async def test_create_single_task(self) -> None:
+        """Test creating a single task."""
+        response = await self._call_tool(
+            name="TaskCreate",
+            tool_input={
+                "subject": "Test Task 1",
+                "description": "This is a test task",
+            },
+            tool_call_id="task-create-single",
+        )
+
+        task_id = self.agent_state.tasks_context.tasks[0].id
+        self.assertDictEqual(
+            response.model_dump(),
+            {
+                "content": [
+                    {
+                        "text": f"Task (id={task_id}) created successfully: "
+                        "Test Task 1",
+                        "type": "text",
+                        "id": AnyString(),
+                    },
+                ],
+                "state": "success",
+                "metadata": {},
+                "id": "task-create-single",
+            },
+        )
+
+        self.assertEqual(
+            self._dump_tasks(),
+            [
+                {
+                    "subject": "Test Task 1",
+                    "description": "This is a test task",
+                    "metadata": {},
+                    "created_at": AnyString(),
+                    "state": "pending",
+                    "id": task_id,
+                    "owner": None,
+                    "blocks": [],
+                    "blocked_by": [],
+                },
+            ],
+        )
+
+    async def test_create_multiple_tasks(self) -> None:
+        """Test creating multiple tasks."""
+        response_1 = await self._call_tool(
+            name="TaskCreate",
+            tool_input={
+                "subject": "Task 1",
+                "description": "First task",
+            },
+            tool_call_id="task-create-1",
+        )
+        task_1_id = self.agent_state.tasks_context.tasks[0].id
+        self.assertDictEqual(
+            response_1.model_dump(),
+            {
+                "content": [
+                    {
+                        "text": f"Task (id={task_1_id}) created successfully: "
+                        f"Task 1",
+                        "type": "text",
+                        "id": AnyString(),
+                    },
+                ],
+                "state": "success",
+                "metadata": {},
+                "id": "task-create-1",
+            },
+        )
+
+        response_2 = await self._call_tool(
+            name="TaskCreate",
+            tool_input={
+                "subject": "Task 2",
+                "description": "Second task",
+            },
+            tool_call_id="task-create-2",
+        )
+        task_2_id = self.agent_state.tasks_context.tasks[1].id
+        self.assertDictEqual(
+            response_2.model_dump(),
+            {
+                "content": [
+                    {
+                        "text": f"Task (id={task_2_id}) created successfully: "
+                        f"Task 2",
+                        "type": "text",
+                        "id": AnyString(),
+                    },
+                ],
+                "state": "success",
+                "metadata": {},
+                "id": "task-create-2",
+            },
+        )
+
+        response_3 = await self._call_tool(
+            name="TaskCreate",
+            tool_input={
+                "subject": "Task 3",
+                "description": "Third task",
+                "metadata": {"priority": "high"},
+            },
+            tool_call_id="task-create-3",
+        )
+        task_3_id = self.agent_state.tasks_context.tasks[2].id
+        self.assertDictEqual(
+            response_3.model_dump(),
+            {
+                "content": [
+                    {
+                        "text": f"Task (id={task_3_id}) created successfully: "
+                        f"Task 3",
+                        "type": "text",
+                        "id": AnyString(),
+                    },
+                ],
+                "state": "success",
+                "metadata": {},
+                "id": "task-create-3",
+            },
+        )
+
+        self.assertEqual(
+            self._dump_tasks(),
+            [
+                {
+                    "subject": "Task 1",
+                    "description": "First task",
+                    "metadata": {},
+                    "created_at": AnyString(),
+                    "state": "pending",
+                    "id": task_1_id,
+                    "owner": None,
+                    "blocks": [],
+                    "blocked_by": [],
+                },
+                {
+                    "subject": "Task 2",
+                    "description": "Second task",
+                    "metadata": {},
+                    "created_at": AnyString(),
+                    "state": "pending",
+                    "id": task_2_id,
+                    "owner": None,
+                    "blocks": [],
+                    "blocked_by": [],
+                },
+                {
+                    "subject": "Task 3",
+                    "description": "Third task",
+                    "metadata": {"priority": "high"},
+                    "created_at": AnyString(),
+                    "state": "pending",
+                    "id": task_3_id,
+                    "owner": None,
+                    "blocks": [],
+                    "blocked_by": [],
+                },
+            ],
+        )
+
+    async def test_create_task_with_metadata(self) -> None:
+        """Test creating a task with metadata."""
+        response = await self._call_tool(
+            name="TaskCreate",
+            tool_input={
+                "subject": "Bug Fix",
+                "description": "Fix critical bug",
+                "metadata": {
+                    "priority": "high",
+                    "tags": ["urgent", "bug"],
+                },
+            },
+            tool_call_id="task-create-metadata",
+        )
+
+        task_id = self.agent_state.tasks_context.tasks[0].id
+        self.assertDictEqual(
+            response.model_dump(),
+            {
+                "content": [
+                    {
+                        "text": f"Task (id={task_id}) created successfully: "
+                        f"Bug Fix",
+                        "type": "text",
+                        "id": AnyString(),
+                    },
+                ],
+                "state": "success",
+                "metadata": {},
+                "id": "task-create-metadata",
+            },
+        )
+
+        self.assertEqual(
+            self._dump_tasks(),
+            [
+                {
+                    "subject": "Bug Fix",
+                    "description": "Fix critical bug",
+                    "metadata": {
+                        "priority": "high",
+                        "tags": ["urgent", "bug"],
+                    },
+                    "created_at": AnyString(),
+                    "state": "pending",
+                    "id": task_id,
+                    "owner": None,
+                    "blocks": [],
+                    "blocked_by": [],
+                },
+            ],
+        )
+
+
+class TestToolkitTaskList(_ToolkitTaskTestBase):
+    """Test cases for TaskList through toolkit."""
+
+    async def test_list_no_tasks(self) -> None:
+        """Test listing when there are no tasks."""
+        response = await self._call_tool(
+            name="TaskList",
+            tool_input={},
+            tool_call_id="task-list-empty",
+        )
+
+        self.assertDictEqual(
+            response.model_dump(),
+            {
+                "content": [
+                    {
+                        "text": "No tasks available.",
+                        "type": "text",
+                        "id": AnyString(),
+                    },
+                ],
+                "state": "success",
+                "metadata": {},
+                "id": "task-list-empty",
+            },
+        )
+        self.assertEqual(self._dump_tasks(), [])
+
+    async def test_list_with_tasks(self) -> None:
+        """Test listing when there are tasks."""
+        await self._call_tool(
+            name="TaskCreate",
+            tool_input={
+                "subject": "Task 1",
+                "description": "First task",
+            },
+            tool_call_id="task-list-create-1",
+        )
+        await self._call_tool(
+            name="TaskCreate",
+            tool_input={
+                "subject": "Task 2",
+                "description": "Second task",
+            },
+            tool_call_id="task-list-create-2",
+        )
+        await self._call_tool(
+            name="TaskCreate",
+            tool_input={
+                "subject": "Task 3",
+                "description": "Third task",
+            },
+            tool_call_id="task-list-create-3",
+        )
+
+        task_1_id = self.agent_state.tasks_context.tasks[0].id
+        task_2_id = self.agent_state.tasks_context.tasks[1].id
+        task_3_id = self.agent_state.tasks_context.tasks[2].id
+
+        response = await self._call_tool(
+            name="TaskList",
+            tool_input={},
+            tool_call_id="task-list-with-tasks",
+        )
+
+        self.assertDictEqual(
+            response.model_dump(),
+            {
+                "content": [
+                    {
+                        "text": f"{task_1_id} [pending] Task 1\n"
+                        f"{task_2_id} [pending] Task 2\n"
+                        f"{task_3_id} [pending] Task 3",
+                        "type": "text",
+                        "id": AnyString(),
+                    },
+                ],
+                "state": "success",
+                "metadata": {},
+                "id": "task-list-with-tasks",
+            },
+        )
+
+        self.assertEqual(
+            self._dump_tasks(),
+            [
+                {
+                    "subject": "Task 1",
+                    "description": "First task",
+                    "metadata": {},
+                    "created_at": AnyString(),
+                    "state": "pending",
+                    "id": task_1_id,
+                    "owner": None,
+                    "blocks": [],
+                    "blocked_by": [],
+                },
+                {
+                    "subject": "Task 2",
+                    "description": "Second task",
+                    "metadata": {},
+                    "created_at": AnyString(),
+                    "state": "pending",
+                    "id": task_2_id,
+                    "owner": None,
+                    "blocks": [],
+                    "blocked_by": [],
+                },
+                {
+                    "subject": "Task 3",
+                    "description": "Third task",
+                    "metadata": {},
+                    "created_at": AnyString(),
+                    "state": "pending",
+                    "id": task_3_id,
+                    "owner": None,
+                    "blocks": [],
+                    "blocked_by": [],
+                },
+            ],
+        )
+
+
+class TestToolkitTaskGet(_ToolkitTaskTestBase):
+    """Test cases for TaskGet through toolkit."""
+
+    async def test_get_existing_task(self) -> None:
+        """Test getting an existing task."""
+        await self._call_tool(
+            name="TaskCreate",
+            tool_input={
+                "subject": "Test Task",
+                "description": "This is a test task with details",
+                "metadata": {"priority": "high"},
+            },
+            tool_call_id="task-get-create",
+        )
+
+        task_id = self.agent_state.tasks_context.tasks[0].id
+        response = await self._call_tool(
+            name="TaskGet",
+            tool_input={"task_id": task_id},
+            tool_call_id="task-get-existing",
+        )
+
+        self.assertDictEqual(
+            response.model_dump(mode="json"),
+            {
+                "content": [
+                    {
+                        "text": f"Task (id={task_id}): Test Task\n"
+                        "Status: pending\n"
+                        "Description: This is a test task with details\n"
+                        "Metadata: {'priority': 'high'}",
+                        "type": "text",
+                        "id": AnyString(),
+                    },
+                ],
+                "state": "success",
+                "metadata": {},
+                "id": "task-get-existing",
+            },
+        )
+
+        self.assertEqual(
+            self._dump_tasks(),
+            [
+                {
+                    "subject": "Test Task",
+                    "description": "This is a test task with details",
+                    "metadata": {"priority": "high"},
+                    "created_at": AnyString(),
+                    "state": "pending",
+                    "id": task_id,
+                    "owner": None,
+                    "blocks": [],
+                    "blocked_by": [],
+                },
+            ],
+        )
+
+    async def test_get_nonexistent_task(self) -> None:
+        """Test getting a task that does not exist."""
+        response = await self._call_tool(
+            name="TaskGet",
+            tool_input={"task_id": "nonexistent-id"},
+            tool_call_id="task-get-missing",
+        )
+
+        self.assertDictEqual(
+            response.model_dump(),
+            {
+                "content": [
+                    {
+                        "text": "Task not found",
+                        "type": "text",
+                        "id": AnyString(),
+                    },
+                ],
+                "state": "error",
+                "metadata": {},
+                "id": "task-get-missing",
+            },
+        )
+        self.assertEqual(self._dump_tasks(), [])
+
+
+class TestToolkitTaskUpdate(_ToolkitTaskTestBase):
+    """Test cases for TaskUpdate through toolkit."""
+
+    async def test_update_subject(self) -> None:
+        """Test updating task subject."""
+        await self._call_tool(
+            name="TaskCreate",
+            tool_input={
+                "subject": "Original Subject",
+                "description": "Test description",
+            },
+            tool_call_id="task-update-subject-create",
+        )
+        task_id = self.agent_state.tasks_context.tasks[0].id
+
+        response = await self._call_tool(
+            name="TaskUpdate",
+            tool_input={
+                "task_id": task_id,
+                "subject": "Updated Subject",
+            },
+            tool_call_id="task-update-subject",
+        )
+
+        self.assertDictEqual(
+            response.model_dump(),
+            {
+                "content": [
+                    {
+                        "text": f"Update task (id={task_id}) subject.",
+                        "type": "text",
+                        "id": AnyString(),
+                    },
+                ],
+                "state": "success",
+                "metadata": {},
+                "id": "task-update-subject",
+            },
+        )
+
+        self.assertEqual(
+            self._dump_tasks(),
+            [
+                {
+                    "subject": "Updated Subject",
+                    "description": "Test description",
+                    "metadata": {},
+                    "created_at": AnyString(),
+                    "state": "pending",
+                    "id": task_id,
+                    "owner": None,
+                    "blocks": [],
+                    "blocked_by": [],
+                },
+            ],
+        )
+
+    async def test_update_description(self) -> None:
+        """Test updating task description."""
+        await self._call_tool(
+            name="TaskCreate",
+            tool_input={
+                "subject": "Test Task",
+                "description": "Original description",
+            },
+            tool_call_id="task-update-description-create",
+        )
+        task_id = self.agent_state.tasks_context.tasks[0].id
+
+        response = await self._call_tool(
+            name="TaskUpdate",
+            tool_input={
+                "task_id": task_id,
+                "description": "Updated description",
+            },
+            tool_call_id="task-update-description",
+        )
+
+        self.assertDictEqual(
+            response.model_dump(),
+            {
+                "content": [
+                    {
+                        "text": f"Update task (id={task_id}) description.",
+                        "type": "text",
+                        "id": AnyString(),
+                    },
+                ],
+                "state": "success",
+                "metadata": {},
+                "id": "task-update-description",
+            },
+        )
+
+        self.assertEqual(
+            self._dump_tasks(),
+            [
+                {
+                    "subject": "Test Task",
+                    "description": "Updated description",
+                    "metadata": {},
+                    "created_at": AnyString(),
+                    "state": "pending",
+                    "id": task_id,
+                    "owner": None,
+                    "blocks": [],
+                    "blocked_by": [],
+                },
+            ],
+        )
+
+    async def test_update_status(self) -> None:
+        """Test updating task status."""
+        await self._call_tool(
+            name="TaskCreate",
+            tool_input={
+                "subject": "Test Task",
+                "description": "Test description",
+            },
+            tool_call_id="task-update-status-create",
+        )
+        task_id = self.agent_state.tasks_context.tasks[0].id
+
+        response = await self._call_tool(
+            name="TaskUpdate",
+            tool_input={
+                "task_id": task_id,
+                "status": "in_progress",
+            },
+            tool_call_id="task-update-status-in-progress",
+        )
+        self.assertDictEqual(
+            response.model_dump(),
+            {
+                "content": [
+                    {
+                        "text": f"Update task (id={task_id}) status.",
+                        "type": "text",
+                        "id": AnyString(),
+                    },
+                ],
+                "state": "success",
+                "metadata": {},
+                "id": "task-update-status-in-progress",
+            },
+        )
+        self.assertEqual(
+            self._dump_tasks(),
+            [
+                {
+                    "subject": "Test Task",
+                    "description": "Test description",
+                    "metadata": {},
+                    "created_at": AnyString(),
+                    "state": "in_progress",
+                    "id": task_id,
+                    "owner": None,
+                    "blocks": [],
+                    "blocked_by": [],
+                },
+            ],
+        )
+
+        response = await self._call_tool(
+            name="TaskUpdate",
+            tool_input={
+                "task_id": task_id,
+                "status": "completed",
+            },
+            tool_call_id="task-update-status-completed",
+        )
+        self.assertDictEqual(
+            response.model_dump(),
+            {
+                "content": [
+                    {
+                        "text": f"Update task (id={task_id}) status.\n\n"
+                        "Task completed. Call TaskList now to find your "
+                        "next available task or see if your work "
+                        "unblocked others.",
+                        "type": "text",
+                        "id": AnyString(),
+                    },
+                ],
+                "state": "success",
+                "metadata": {},
+                "id": "task-update-status-completed",
+            },
+        )
+        self.assertEqual(
+            self._dump_tasks(),
+            [
+                {
+                    "subject": "Test Task",
+                    "description": "Test description",
+                    "metadata": {},
+                    "created_at": AnyString(),
+                    "state": "completed",
+                    "id": task_id,
+                    "owner": None,
+                    "blocks": [],
+                    "blocked_by": [],
+                },
+            ],
+        )
+
+        await self._call_tool(
+            name="TaskCreate",
+            tool_input={
+                "subject": "Task to Delete",
+                "description": "This task will be deleted",
+            },
+            tool_call_id="task-update-status-create-delete",
+        )
+        task_to_delete_id = self.agent_state.tasks_context.tasks[1].id
+
+        response = await self._call_tool(
+            name="TaskUpdate",
+            tool_input={
+                "task_id": task_to_delete_id,
+                "status": "deleted",
+            },
+            tool_call_id="task-update-status-deleted",
+        )
+        self.assertDictEqual(
+            response.model_dump(),
+            {
+                "content": [
+                    {
+                        "text": f"Task (id={task_to_delete_id}) has been "
+                        f"deleted.",
+                        "type": "text",
+                        "id": AnyString(),
+                    },
+                ],
+                "state": "success",
+                "metadata": {},
+                "id": "task-update-status-deleted",
+            },
+        )
+        self.assertEqual(
+            self._dump_tasks(),
+            [
+                {
+                    "subject": "Test Task",
+                    "description": "Test description",
+                    "metadata": {},
+                    "created_at": AnyString(),
+                    "state": "completed",
+                    "id": task_id,
+                    "owner": None,
+                    "blocks": [],
+                    "blocked_by": [],
+                },
+            ],
+        )
+
+    async def test_update_owner(self) -> None:
+        """Test updating task owner."""
+        await self._call_tool(
+            name="TaskCreate",
+            tool_input={
+                "subject": "Test Task",
+                "description": "Test description",
+            },
+            tool_call_id="task-update-owner-create",
+        )
+        task_id = self.agent_state.tasks_context.tasks[0].id
+
+        response = await self._call_tool(
+            name="TaskUpdate",
+            tool_input={
+                "task_id": task_id,
+                "owner": "agent-1",
+            },
+            tool_call_id="task-update-owner",
+        )
+
+        self.assertDictEqual(
+            response.model_dump(),
+            {
+                "content": [
+                    {
+                        "text": f"Update task (id={task_id}) owner.",
+                        "type": "text",
+                        "id": AnyString(),
+                    },
+                ],
+                "state": "success",
+                "metadata": {},
+                "id": "task-update-owner",
+            },
+        )
+
+        self.assertEqual(
+            self._dump_tasks(),
+            [
+                {
+                    "subject": "Test Task",
+                    "description": "Test description",
+                    "metadata": {},
+                    "created_at": AnyString(),
+                    "state": "pending",
+                    "id": task_id,
+                    "owner": "agent-1",
+                    "blocks": [],
+                    "blocked_by": [],
+                },
+            ],
+        )
+
+    async def test_update_metadata(self) -> None:
+        """Test updating task metadata."""
+        await self._call_tool(
+            name="TaskCreate",
+            tool_input={
+                "subject": "Test Task",
+                "description": "Test description",
+                "metadata": {
+                    "priority": "low",
+                    "tags": ["test"],
+                },
+            },
+            tool_call_id="task-update-metadata-create",
+        )
+        task_id = self.agent_state.tasks_context.tasks[0].id
+
+        response = await self._call_tool(
+            name="TaskUpdate",
+            tool_input={
+                "task_id": task_id,
+                "metadata": {
+                    "priority": "high",
+                    "new_field": "value",
+                },
+            },
+            tool_call_id="task-update-metadata",
+        )
+
+        self.assertDictEqual(
+            response.model_dump(),
+            {
+                "content": [
+                    {
+                        "text": f"Update task (id={task_id}) metadata.",
+                        "type": "text",
+                        "id": AnyString(),
+                    },
+                ],
+                "state": "success",
+                "metadata": {},
+                "id": "task-update-metadata",
+            },
+        )
+
+        self.assertEqual(
+            self._dump_tasks(),
+            [
+                {
+                    "subject": "Test Task",
+                    "description": "Test description",
+                    "metadata": {
+                        "priority": "high",
+                        "tags": ["test"],
+                        "new_field": "value",
+                    },
+                    "created_at": AnyString(),
+                    "state": "pending",
+                    "id": task_id,
+                    "owner": None,
+                    "blocks": [],
+                    "blocked_by": [],
+                },
+            ],
+        )
+
+    async def test_update_add_blocks(self) -> None:
+        """Test updating task blocks relationship."""
+        await self._call_tool(
+            name="TaskCreate",
+            tool_input={
+                "subject": "Task 1",
+                "description": "First task",
+            },
+            tool_call_id="task-update-add-blocks-create-1",
+        )
+        await self._call_tool(
+            name="TaskCreate",
+            tool_input={
+                "subject": "Task 2",
+                "description": "Second task",
+            },
+            tool_call_id="task-update-add-blocks-create-2",
+        )
+
+        task_1_id = self.agent_state.tasks_context.tasks[0].id
+        task_2_id = self.agent_state.tasks_context.tasks[1].id
+        response = await self._call_tool(
+            name="TaskUpdate",
+            tool_input={
+                "task_id": task_1_id,
+                "add_blocks": [task_2_id],
+            },
+            tool_call_id="task-update-add-blocks",
+        )
+
+        self.assertDictEqual(
+            response.model_dump(),
+            {
+                "content": [
+                    {
+                        "text": f"Update task (id={task_1_id}) add_blocks.",
+                        "type": "text",
+                        "id": AnyString(),
+                    },
+                ],
+                "state": "success",
+                "metadata": {},
+                "id": "task-update-add-blocks",
+            },
+        )
+
+        self.assertEqual(
+            self._dump_tasks(),
+            [
+                {
+                    "subject": "Task 1",
+                    "description": "First task",
+                    "metadata": {},
+                    "created_at": AnyString(),
+                    "state": "pending",
+                    "id": task_1_id,
+                    "owner": None,
+                    "blocks": [task_2_id],
+                    "blocked_by": [],
+                },
+                {
+                    "subject": "Task 2",
+                    "description": "Second task",
+                    "metadata": {},
+                    "created_at": AnyString(),
+                    "state": "pending",
+                    "id": task_2_id,
+                    "owner": None,
+                    "blocks": [],
+                    "blocked_by": [task_1_id],
+                },
+            ],
+        )
+
+    async def test_update_add_blocked_by(self) -> None:
+        """Test updating task blocked_by relationship."""
+        await self._call_tool(
+            name="TaskCreate",
+            tool_input={
+                "subject": "Task 1",
+                "description": "First task",
+            },
+            tool_call_id="task-update-add-blocked-by-create-1",
+        )
+        await self._call_tool(
+            name="TaskCreate",
+            tool_input={
+                "subject": "Task 2",
+                "description": "Second task",
+            },
+            tool_call_id="task-update-add-blocked-by-create-2",
+        )
+
+        task_1_id = self.agent_state.tasks_context.tasks[0].id
+        task_2_id = self.agent_state.tasks_context.tasks[1].id
+        response = await self._call_tool(
+            name="TaskUpdate",
+            tool_input={
+                "task_id": task_2_id,
+                "add_blocked_by": [task_1_id],
+            },
+            tool_call_id="task-update-add-blocked-by",
+        )
+
+        self.assertDictEqual(
+            response.model_dump(),
+            {
+                "content": [
+                    {
+                        "text": f"Update task (id={task_2_id}) "
+                        f"add_blocked_by.",
+                        "type": "text",
+                        "id": AnyString(),
+                    },
+                ],
+                "state": "success",
+                "metadata": {},
+                "id": "task-update-add-blocked-by",
+            },
+        )
+
+        self.assertEqual(
+            self._dump_tasks(),
+            [
+                {
+                    "subject": "Task 1",
+                    "description": "First task",
+                    "metadata": {},
+                    "created_at": AnyString(),
+                    "state": "pending",
+                    "id": task_1_id,
+                    "owner": None,
+                    "blocks": [task_2_id],
+                    "blocked_by": [],
+                },
+                {
+                    "subject": "Task 2",
+                    "description": "Second task",
+                    "metadata": {},
+                    "created_at": AnyString(),
+                    "state": "pending",
+                    "id": task_2_id,
+                    "owner": None,
+                    "blocks": [],
+                    "blocked_by": [task_1_id],
+                },
+            ],
+        )
+
+    async def test_update_delete_task(self) -> None:
+        """Test deleting a task and cleaning dependency relations."""
+        await self._call_tool(
+            name="TaskCreate",
+            tool_input={
+                "subject": "Task 1",
+                "description": "First task",
+            },
+            tool_call_id="task-update-delete-create-1",
+        )
+        await self._call_tool(
+            name="TaskCreate",
+            tool_input={
+                "subject": "Task 2",
+                "description": "Second task",
+            },
+            tool_call_id="task-update-delete-create-2",
+        )
+        await self._call_tool(
+            name="TaskCreate",
+            tool_input={
+                "subject": "Task 3",
+                "description": "Third task",
+            },
+            tool_call_id="task-update-delete-create-3",
+        )
+
+        task_1_id = self.agent_state.tasks_context.tasks[0].id
+        task_2_id = self.agent_state.tasks_context.tasks[1].id
+        task_3_id = self.agent_state.tasks_context.tasks[2].id
+
+        await self._call_tool(
+            name="TaskUpdate",
+            tool_input={
+                "task_id": task_1_id,
+                "add_blocks": [task_2_id],
+            },
+            tool_call_id="task-update-delete-link-1",
+        )
+        await self._call_tool(
+            name="TaskUpdate",
+            tool_input={
+                "task_id": task_2_id,
+                "add_blocks": [task_3_id],
+            },
+            tool_call_id="task-update-delete-link-2",
+        )
+
+        self.assertEqual(
+            self._dump_tasks(),
+            [
+                {
+                    "subject": "Task 1",
+                    "description": "First task",
+                    "metadata": {},
+                    "created_at": AnyString(),
+                    "state": "pending",
+                    "id": task_1_id,
+                    "owner": None,
+                    "blocks": [task_2_id],
+                    "blocked_by": [],
+                },
+                {
+                    "subject": "Task 2",
+                    "description": "Second task",
+                    "metadata": {},
+                    "created_at": AnyString(),
+                    "state": "pending",
+                    "id": task_2_id,
+                    "owner": None,
+                    "blocks": [task_3_id],
+                    "blocked_by": [task_1_id],
+                },
+                {
+                    "subject": "Task 3",
+                    "description": "Third task",
+                    "metadata": {},
+                    "created_at": AnyString(),
+                    "state": "pending",
+                    "id": task_3_id,
+                    "owner": None,
+                    "blocks": [],
+                    "blocked_by": [task_2_id],
+                },
+            ],
+        )
+
+        response = await self._call_tool(
+            name="TaskUpdate",
+            tool_input={
+                "task_id": task_2_id,
+                "status": "deleted",
+            },
+            tool_call_id="task-update-delete",
+        )
+
+        self.assertDictEqual(
+            response.model_dump(),
+            {
+                "content": [
+                    {
+                        "text": f"Task (id={task_2_id}) has been deleted.",
+                        "type": "text",
+                        "id": AnyString(),
+                    },
+                ],
+                "state": "success",
+                "metadata": {},
+                "id": "task-update-delete",
+            },
+        )
+        self.assertEqual(
+            self._dump_tasks(),
+            [
+                {
+                    "subject": "Task 1",
+                    "description": "First task",
+                    "metadata": {},
+                    "created_at": AnyString(),
+                    "state": "pending",
+                    "id": task_1_id,
+                    "owner": None,
+                    "blocks": [],
+                    "blocked_by": [],
+                },
+                {
+                    "subject": "Task 3",
+                    "description": "Third task",
+                    "metadata": {},
+                    "created_at": AnyString(),
+                    "state": "pending",
+                    "id": task_3_id,
+                    "owner": None,
+                    "blocks": [],
+                    "blocked_by": [],
+                },
+            ],
+        )
+
+    async def test_update_nonexistent_task(self) -> None:
+        """Test updating a task that does not exist."""
+        response = await self._call_tool(
+            name="TaskUpdate",
+            tool_input={
+                "task_id": "nonexistent-id",
+                "subject": "New Subject",
+                "description": None,
+            },
+            tool_call_id="task-update-missing",
+        )
+
+        self.assertDictEqual(
+            response.model_dump(),
+            {
+                "content": [
+                    {
+                        "text": "TaskNotFoundError: "
+                        "The task (id=nonexistent-id) does not exist.",
+                        "type": "text",
+                        "id": AnyString(),
+                    },
+                ],
+                "state": "error",
+                "metadata": {},
+                "id": "task-update-missing",
+            },
+        )
+        self.assertEqual(self._dump_tasks(), [])
diff --git a/tests/toolkit_test.py b/tests/toolkit_test.py
new file mode 100644
index 0000000..3be91d1
--- /dev/null
+++ b/tests/toolkit_test.py
@@ -0,0 +1,1387 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=unused-argument
+"""Toolkit test case."""
+import base64
+import json
+from typing import Any, AsyncGenerator, Generator
+from unittest import TestCase
+from unittest.async_case import IsolatedAsyncioTestCase
+
+
+from utils import AnyString
+
+from agentscope.state import AgentState
+from agentscope.message import (
+    TextBlock,
+    ToolCallBlock,
+    DataBlock,
+    Base64Source,
+)
+from agentscope.tool import (
+    Toolkit,
+    ToolBase,
+    ToolChunk,
+    ToolResponse,
+    ToolGroup,
+    FunctionTool,
+)
+from agentscope.permission import (
+    PermissionDecision,
+    PermissionBehavior,
+)
+
+
+class Tool1(ToolBase):
+    """A simple tool for testing."""
+
+    name: str = "tool_1"
+    description: str = "A simple tool for testing."
+    input_schema: dict = {
+        "type": "object",
+        "properties": {},
+    }
+    is_concurrency_safe: bool = True
+    is_read_only: bool = True
+    is_mcp: bool = False
+
+    async def check_permissions(
+        self,
+        *args: Any,
+        **kwargs: Any,
+    ) -> PermissionDecision:
+        """Check permissions for the tool."""
+        return PermissionDecision(
+            behavior=PermissionBehavior.ASK,
+            message="Do you want to use my_tool?",
+        )
+
+    async def call(self, **kwargs: Any) -> ToolChunk:
+        """Run the tool."""
+        return ToolChunk(
+            content=[TextBlock(text="Hello, world!")],
+        )
+
+
+class Tool2(ToolBase):
+    """Test tool 2"""
+
+    name: str = "tool_2"
+    description: str = "Test tool 2."
+    input_schema: dict = {
+        "type": "object",
+        "properties": {},
+    }
+    is_concurrency_safe: bool = True
+    is_read_only: bool = True
+    is_mcp: bool = False
+
+    async def check_permissions(
+        self,
+        *args: Any,
+        **kwargs: Any,
+    ) -> PermissionDecision:
+        """Check permissions for the tool."""
+        return PermissionDecision(
+            behavior=PermissionBehavior.ASK,
+            message="Do you want to use my_tool?",
+        )
+
+    async def call(self, **kwargs: Any) -> AsyncGenerator[ToolChunk, None]:
+        """Run the tool."""
+        yield ToolChunk(
+            content=[TextBlock(text="123", id="a")],
+        )
+        yield ToolChunk(
+            content=[TextBlock(text="456", id="b")],
+        )
+        yield ToolChunk(
+            content=[TextBlock(text="789", id="b")],
+        )
+        yield ToolChunk(
+            content=[
+                DataBlock(
+                    id="1",
+                    source=Base64Source(
+                        data="abc",
+                        media_type="image/jpeg",
+                    ),
+                ),
+            ],
+        )
+        yield ToolChunk(
+            content=[
+                DataBlock(
+                    id="2",
+                    source=Base64Source(
+                        data="***",
+                        media_type="image/jpeg",
+                    ),
+                ),
+            ],
+        )
+        yield ToolChunk(
+            content=[
+                DataBlock(
+                    id="1",
+                    source=Base64Source(
+                        data="def",
+                        media_type="image/jpeg",
+                    ),
+                ),
+            ],
+        )
+
+
+class ToolkitTest(IsolatedAsyncioTestCase):
+    """The toolkit test case."""
+
+    async def asyncSetUp(self) -> None:
+        """The async setup method."""
+
+    async def test_initialize(self) -> None:
+        """The template test."""
+
+        # Initialize the toolkit
+        toolkit = Toolkit()
+
+        # No tools
+        schemas = await toolkit.get_tool_schemas()
+        self.assertEqual(len(schemas), 0)
+
+        # Initialize the toolkit with tools
+        toolkit = Toolkit(tools=[Tool1(), Tool2()])
+        schemas = await toolkit.get_tool_schemas()
+        self.assertListEqual(
+            schemas,
+            [
+                {
+                    "type": "function",
+                    "function": {
+                        "name": "tool_1",
+                        "description": "A simple tool for testing.",
+                        "parameters": {
+                            "type": "object",
+                            "properties": {},
+                        },
+                    },
+                },
+                {
+                    "type": "function",
+                    "function": {
+                        "name": "tool_2",
+                        "description": "Test tool 2.",
+                        "parameters": {
+                            "type": "object",
+                            "properties": {},
+                        },
+                    },
+                },
+            ],
+        )
+
+    async def test_tool(self) -> None:
+        """Test executing a tool."""
+        toolkit = Toolkit(tools=[Tool1(), Tool2()])
+        state = AgentState()
+
+        # Test Tool1 (returns single ToolChunk)
+        tool_call_1 = ToolCallBlock(
+            id="test_1",
+            name="tool_1",
+            input=json.dumps({}),
+        )
+
+        chunks_1 = []
+        response_1 = None
+        async for result in toolkit.call_tool(tool_call_1, state):
+            if isinstance(result, ToolChunk):
+                chunks_1.append(result)
+            elif isinstance(result, ToolResponse):
+                response_1 = result
+
+        # Verify Tool1 chunks
+        self.assertEqual(len(chunks_1), 1)
+        self.assertDictEqual(
+            chunks_1[0].model_dump(),
+            {
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": "Hello, world!",
+                    },
+                ],
+                "state": "running",
+                "is_last": True,
+                "metadata": {},
+                "id": AnyString(),
+            },
+        )
+
+        # Verify Tool1 response
+        self.assertIsNotNone(response_1)
+        self.assertDictEqual(
+            response_1.model_dump(),
+            {
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": "Hello, world!",
+                    },
+                ],
+                "state": "success",
+                "metadata": {},
+                "id": "test_1",
+            },
+        )
+
+        # Test Tool2 (returns async generator of ToolChunks)
+        tool_call_2 = ToolCallBlock(
+            id="test_2",
+            name="tool_2",
+            input=json.dumps({}),
+        )
+
+        chunks_2 = []
+        response_2 = None
+        async for result in toolkit.call_tool(tool_call_2, state):
+            if isinstance(result, ToolChunk):
+                chunks_2.append(result)
+            elif isinstance(result, ToolResponse):
+                response_2 = result
+
+        # Verify Tool2 chunks
+        self.assertEqual(len(chunks_2), 6)
+
+        # First chunk - TextBlock id="a"
+        self.assertDictEqual(
+            chunks_2[0].model_dump(),
+            {
+                "content": [
+                    {
+                        "type": "text",
+                        "id": "a",
+                        "text": "123",
+                    },
+                ],
+                "state": "running",
+                "is_last": True,
+                "metadata": {},
+                "id": AnyString(),
+            },
+        )
+
+        # Second chunk - TextBlock id="b"
+        self.assertDictEqual(
+            chunks_2[1].model_dump(),
+            {
+                "content": [
+                    {
+                        "type": "text",
+                        "id": "b",
+                        "text": "456",
+                    },
+                ],
+                "state": "running",
+                "is_last": True,
+                "metadata": {},
+                "id": AnyString(),
+            },
+        )
+
+        # Third chunk - TextBlock id="b" (same id as second)
+        self.assertDictEqual(
+            chunks_2[2].model_dump(),
+            {
+                "content": [
+                    {
+                        "type": "text",
+                        "id": "b",
+                        "text": "789",
+                    },
+                ],
+                "state": "running",
+                "is_last": True,
+                "metadata": {},
+                "id": AnyString(),
+            },
+        )
+
+        # Fourth chunk - DataBlock id="1"
+        self.assertDictEqual(
+            chunks_2[3].model_dump(),
+            {
+                "content": [
+                    {
+                        "type": "data",
+                        "id": "1",
+                        "name": None,
+                        "source": {
+                            "type": "base64",
+                            "media_type": "image/jpeg",
+                            "data": "abc",
+                        },
+                    },
+                ],
+                "state": "running",
+                "is_last": True,
+                "metadata": {},
+                "id": AnyString(),
+            },
+        )
+
+        # Fifth chunk - DataBlock id="2"
+        self.assertDictEqual(
+            chunks_2[4].model_dump(),
+            {
+                "content": [
+                    {
+                        "type": "data",
+                        "id": "2",
+                        "name": None,
+                        "source": {
+                            "type": "base64",
+                            "media_type": "image/jpeg",
+                            "data": "***",
+                        },
+                    },
+                ],
+                "state": "running",
+                "is_last": True,
+                "metadata": {},
+                "id": AnyString(),
+            },
+        )
+
+        # Sixth chunk - DataBlock id="1" (same id as fourth)
+        self.assertDictEqual(
+            chunks_2[5].model_dump(),
+            {
+                "content": [
+                    {
+                        "type": "data",
+                        "id": "1",
+                        "name": None,
+                        "source": {
+                            "type": "base64",
+                            "media_type": "image/jpeg",
+                            "data": "def",
+                        },
+                    },
+                ],
+                "state": "running",
+                "is_last": True,
+                "metadata": {},
+                "id": AnyString(),
+            },
+        )
+
+        # Verify Tool2 response - blocks with same id are merged,
+        # and consecutive TextBlocks are also merged
+        # TextBlock id="a" (123) + id="b" (456) + id="b" (789) -> merged to
+        # "123456789" with id="a"
+        # DataBlock id="1" appears twice, should be merged to "abcdef"
+        self.assertIsNotNone(response_2)
+        self.assertDictEqual(
+            response_2.model_dump(),
+            {
+                "content": [
+                    {
+                        "type": "text",
+                        "id": "a",
+                        # All consecutive TextBlocks merged
+                        "text": "123456789",
+                    },
+                    {
+                        "type": "data",
+                        "id": "1",
+                        "name": None,
+                        "source": {
+                            "type": "base64",
+                            "media_type": "image/jpeg",
+                            "data": "abcdef",  # Merged: "abc" + "def"
+                        },
+                    },
+                    {
+                        "type": "data",
+                        "id": "2",
+                        "name": None,
+                        "source": {
+                            "type": "base64",
+                            "media_type": "image/jpeg",
+                            "data": "***",
+                        },
+                    },
+                ],
+                "state": "success",
+                "metadata": {},
+                "id": "test_2",
+            },
+        )
+
+    async def test_tool_response_merges_base64_chunks_by_bytes(self) -> None:
+        """Base64 chunks with padding should merge as bytes, not strings."""
+        response = ToolResponse()
+        first = base64.b64encode(b"hello").decode("ascii")
+        second = base64.b64encode(b"world").decode("ascii")
+
+        response.append_chunk(
+            ToolChunk(
+                content=[
+                    DataBlock(
+                        id="image",
+                        source=Base64Source(
+                            data=first,
+                            media_type="image/png",
+                        ),
+                    ),
+                ],
+            ),
+        )
+        response.append_chunk(
+            ToolChunk(
+                content=[
+                    DataBlock(
+                        id="image",
+                        source=Base64Source(
+                            data=second,
+                            media_type="image/png",
+                        ),
+                    ),
+                ],
+            ),
+        )
+
+        self.assertEqual(len(response.content), 1)
+        merged = response.content[0]
+        self.assertIsInstance(merged, DataBlock)
+        self.assertEqual(
+            base64.b64decode(merged.source.data),
+            b"helloworld",
+        )
+
+
+class RegisterFunctionTest(IsolatedAsyncioTestCase):
+    """Test registering different functions in the toolkit."""
+
+    async def test_sync_non_streaming_function(self) -> None:
+        """Test registering a synchronous non-streaming function."""
+
+        def add_numbers(a: int, b: int) -> ToolChunk:
+            """Add two numbers together.
+
+            Args:
+                a: The first number
+                b: The second number
+            """
+            result = a + b
+            return ToolChunk(
+                content=[TextBlock(text=f"Result: {result}")],
+            )
+
+        toolkit = Toolkit(
+            tools=[FunctionTool(add_numbers)],
+        )
+
+        # Test schema
+        schemas = await toolkit.get_tool_schemas()
+        self.assertEqual(len(schemas), 1)
+        self.assertDictEqual(
+            schemas[0],
+            {
+                "type": "function",
+                "function": {
+                    "name": "add_numbers",
+                    "description": "Add two numbers together.",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {
+                            "a": {
+                                "type": "integer",
+                                "description": "The first number",
+                            },
+                            "b": {
+                                "type": "integer",
+                                "description": "The second number",
+                            },
+                        },
+                        "required": ["a", "b"],
+                    },
+                },
+            },
+        )
+
+        # Test execution
+        state = AgentState()
+        tool_call = ToolCallBlock(
+            id="test_add",
+            name="add_numbers",
+            input=json.dumps({"a": 3, "b": 5}),
+        )
+
+        chunks = []
+        response = None
+        async for result in toolkit.call_tool(tool_call, state):
+            if isinstance(result, ToolChunk):
+                chunks.append(result)
+            elif isinstance(result, ToolResponse):
+                response = result
+
+        # Verify chunks
+        self.assertEqual(len(chunks), 1)
+        self.assertDictEqual(
+            chunks[0].model_dump(),
+            {
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": "Result: 8",
+                    },
+                ],
+                "state": "running",
+                "is_last": True,
+                "metadata": {},
+                "id": AnyString(),
+            },
+        )
+
+        # Verify response
+        self.assertIsNotNone(response)
+        self.assertDictEqual(
+            response.model_dump(),
+            {
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": "Result: 8",
+                    },
+                ],
+                "state": "success",
+                "metadata": {},
+                "id": "test_add",
+            },
+        )
+
+    async def test_sync_function_returning_plain_string(self) -> None:
+        """Test wrapping a sync function that returns a plain string."""
+
+        def get_weather(location: str) -> str:
+            """Get weather information.
+
+            Args:
+                location: The location to get weather for
+            """
+            return f"The weather in {location} is sunny."
+
+        toolkit = Toolkit(
+            tools=[FunctionTool(get_weather)],
+        )
+
+        state = AgentState()
+        tool_call = ToolCallBlock(
+            id="test_weather",
+            name="get_weather",
+            input=json.dumps({"location": "Chengdu"}),
+        )
+
+        chunks = []
+        response = None
+        async for result in toolkit.call_tool(tool_call, state):
+            if isinstance(result, ToolChunk):
+                chunks.append(result)
+            elif isinstance(result, ToolResponse):
+                response = result
+
+        self.assertEqual(len(chunks), 1)
+        self.assertDictEqual(
+            chunks[0].model_dump(),
+            {
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": "The weather in Chengdu is sunny.",
+                    },
+                ],
+                "state": "running",
+                "is_last": True,
+                "metadata": {},
+                "id": AnyString(),
+            },
+        )
+
+        self.assertIsNotNone(response)
+        self.assertDictEqual(
+            response.model_dump(),
+            {
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": "The weather in Chengdu is sunny.",
+                    },
+                ],
+                "state": "success",
+                "metadata": {},
+                "id": "test_weather",
+            },
+        )
+
+    async def test_async_function_returning_json_serializable_value(
+        self,
+    ) -> None:
+        """Test wrapping an async function that returns a JSON value."""
+
+        async def get_weather(location: str) -> dict:
+            """Get weather information.
+
+            Args:
+                location: The location to get weather for
+            """
+            return {
+                "location": location,
+                "weather": {
+                    "condition": "sunny",
+                    "temperature": 22,
+                },
+            }
+
+        toolkit = Toolkit(
+            tools=[FunctionTool(get_weather)],
+        )
+
+        state = AgentState()
+        tool_call = ToolCallBlock(
+            id="test_weather_json",
+            name="get_weather",
+            input=json.dumps({"location": "成都"}),
+        )
+        expected_text = json.dumps(
+            {
+                "location": "成都",
+                "weather": {
+                    "condition": "sunny",
+                    "temperature": 22,
+                },
+            },
+            ensure_ascii=False,
+        )
+
+        chunks = []
+        response = None
+        async for result in toolkit.call_tool(tool_call, state):
+            if isinstance(result, ToolChunk):
+                chunks.append(result)
+            elif isinstance(result, ToolResponse):
+                response = result
+
+        self.assertEqual(len(chunks), 1)
+        self.assertEqual(chunks[0].content[0].text, expected_text)
+
+        self.assertIsNotNone(response)
+        self.assertEqual(response.content[0].text, expected_text)
+
+    async def test_sync_streaming_function(self) -> None:
+        """Test registering a synchronous streaming function."""
+
+        def count_to_n(n: int) -> Generator[ToolChunk, None, None]:
+            """Count from 1 to n.
+
+            Args:
+                n: The number to count to
+            """
+            for i in range(1, n + 1):
+                yield ToolChunk(
+                    content=[TextBlock(text=str(i))],
+                )
+
+        toolkit = Toolkit(
+            tools=[
+                FunctionTool(
+                    func=count_to_n,
+                ),
+            ],
+        )
+
+        # Test schema
+        schemas = await toolkit.get_tool_schemas()
+        self.assertEqual(len(schemas), 1)
+        self.assertDictEqual(
+            schemas[0],
+            {
+                "type": "function",
+                "function": {
+                    "name": "count_to_n",
+                    "description": "Count from 1 to n.",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {
+                            "n": {
+                                "type": "integer",
+                                "description": "The number to count to",
+                            },
+                        },
+                        "required": ["n"],
+                    },
+                },
+            },
+        )
+
+        # Test execution
+        state = AgentState()
+        tool_call = ToolCallBlock(
+            id="test_count",
+            name="count_to_n",
+            input=json.dumps({"n": 3}),
+        )
+
+        chunks = []
+        response = None
+        async for result in toolkit.call_tool(tool_call, state):
+            if isinstance(result, ToolChunk):
+                chunks.append(result)
+            elif isinstance(result, ToolResponse):
+                response = result
+
+        # Verify chunks
+        self.assertEqual(len(chunks), 3)
+        for i, chunk in enumerate(chunks, 1):
+            self.assertDictEqual(
+                chunk.model_dump(),
+                {
+                    "content": [
+                        {
+                            "type": "text",
+                            "id": AnyString(),
+                            "text": str(i),
+                        },
+                    ],
+                    "state": "running",
+                    "is_last": True,
+                    "metadata": {},
+                    "id": AnyString(),
+                },
+            )
+
+        # Verify response - consecutive TextBlocks are merged
+        self.assertIsNotNone(response)
+        self.assertDictEqual(
+            response.model_dump(),
+            {
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": "123",  # All consecutive TextBlocks merged
+                    },
+                ],
+                "state": "success",
+                "metadata": {},
+                "id": "test_count",
+            },
+        )
+
+    async def test_sync_streaming_function_returning_plain_values(
+        self,
+    ) -> None:
+        """Test wrapping a sync generator that yields plain values."""
+
+        def stream_weather() -> Generator[Any, None, None]:
+            """Stream weather information."""
+            yield "checking"
+            yield {
+                "condition": "sunny",
+                "temperature": 22,
+            }
+
+        toolkit = Toolkit(
+            tools=[FunctionTool(stream_weather)],
+        )
+
+        state = AgentState()
+        tool_call = ToolCallBlock(
+            id="test_weather_stream",
+            name="stream_weather",
+            input=json.dumps({}),
+        )
+        expected_dict_text = json.dumps(
+            {
+                "condition": "sunny",
+                "temperature": 22,
+            },
+            ensure_ascii=False,
+        )
+
+        chunks = []
+        response = None
+        async for result in toolkit.call_tool(tool_call, state):
+            if isinstance(result, ToolChunk):
+                chunks.append(result)
+            elif isinstance(result, ToolResponse):
+                response = result
+
+        self.assertEqual(
+            [chunk.content[0].text for chunk in chunks],
+            ["checking", expected_dict_text],
+        )
+
+        self.assertIsNotNone(response)
+        self.assertEqual(
+            response.content[0].text,
+            f"checking{expected_dict_text}",
+        )
+
+    async def test_async_non_streaming_function(self) -> None:
+        """Test registering an asynchronous non-streaming function."""
+
+        async def multiply_numbers(x: float, y: float) -> ToolChunk:
+            """Multiply two numbers.
+
+            Args:
+                x: The first number
+                y: The second number
+            """
+            result = x * y
+            return ToolChunk(
+                content=[TextBlock(text=f"Product: {result}")],
+            )
+
+        toolkit = Toolkit(
+            tools=[FunctionTool(multiply_numbers)],
+        )
+
+        # Test schema
+        schemas = await toolkit.get_tool_schemas()
+        self.assertEqual(len(schemas), 1)
+        self.assertDictEqual(
+            schemas[0],
+            {
+                "type": "function",
+                "function": {
+                    "name": "multiply_numbers",
+                    "description": "Multiply two numbers.",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {
+                            "x": {
+                                "type": "number",
+                                "description": "The first number",
+                            },
+                            "y": {
+                                "type": "number",
+                                "description": "The second number",
+                            },
+                        },
+                        "required": ["x", "y"],
+                    },
+                },
+            },
+        )
+
+        # Test execution
+        state = AgentState()
+        tool_call = ToolCallBlock(
+            id="test_multiply",
+            name="multiply_numbers",
+            input=json.dumps({"x": 2.5, "y": 4.0}),
+        )
+
+        chunks = []
+        response = None
+        async for result in toolkit.call_tool(tool_call, state):
+            if isinstance(result, ToolChunk):
+                chunks.append(result)
+            elif isinstance(result, ToolResponse):
+                response = result
+
+        # Verify chunks
+        self.assertEqual(len(chunks), 1)
+        self.assertDictEqual(
+            chunks[0].model_dump(),
+            {
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": "Product: 10.0",
+                    },
+                ],
+                "state": "running",
+                "is_last": True,
+                "metadata": {},
+                "id": AnyString(),
+            },
+        )
+
+        # Verify response
+        self.assertIsNotNone(response)
+        self.assertDictEqual(
+            response.model_dump(),
+            {
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": "Product: 10.0",
+                    },
+                ],
+                "state": "success",
+                "metadata": {},
+                "id": "test_multiply",
+            },
+        )
+
+    async def test_async_streaming_function(self) -> None:
+        """Test registering an asynchronous streaming function."""
+
+        async def generate_sequence(
+            start: int,
+            end: int,
+        ) -> AsyncGenerator[ToolChunk, None]:
+            """Generate a sequence of numbers.
+
+            Args:
+                start: The starting number
+                end: The ending number
+            """
+            for i in range(start, end + 1):
+                yield ToolChunk(
+                    content=[TextBlock(text=f"Number: {i}")],
+                )
+
+        toolkit = Toolkit(
+            tools=[FunctionTool(generate_sequence)],
+        )
+
+        # Test schema
+        schemas = await toolkit.get_tool_schemas()
+        self.assertEqual(len(schemas), 1)
+        self.assertDictEqual(
+            schemas[0],
+            {
+                "type": "function",
+                "function": {
+                    "name": "generate_sequence",
+                    "description": "Generate a sequence of numbers.",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {
+                            "start": {
+                                "type": "integer",
+                                "description": "The starting number",
+                            },
+                            "end": {
+                                "type": "integer",
+                                "description": "The ending number",
+                            },
+                        },
+                        "required": ["start", "end"],
+                    },
+                },
+            },
+        )
+
+        # Test execution
+        state = AgentState()
+        tool_call = ToolCallBlock(
+            id="test_sequence",
+            name="generate_sequence",
+            input=json.dumps({"start": 5, "end": 7}),
+        )
+
+        chunks = []
+        response = None
+        async for result in toolkit.call_tool(tool_call, state):
+            if isinstance(result, ToolChunk):
+                chunks.append(result)
+            elif isinstance(result, ToolResponse):
+                response = result
+
+        # Verify chunks
+        self.assertEqual(len(chunks), 3)
+        for chunk, num in zip(chunks, [5, 6, 7]):
+            self.assertDictEqual(
+                chunk.model_dump(),
+                {
+                    "content": [
+                        {
+                            "type": "text",
+                            "id": AnyString(),
+                            "text": f"Number: {num}",
+                        },
+                    ],
+                    "state": "running",
+                    "is_last": True,
+                    "metadata": {},
+                    "id": AnyString(),
+                },
+            )
+
+        # Verify response - consecutive TextBlocks are merged
+        self.assertIsNotNone(response)
+        self.assertDictEqual(
+            response.model_dump(),
+            {
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        # All consecutive TextBlocks merged
+                        "text": "Number: 5Number: 6Number: 7",
+                    },
+                ],
+                "state": "success",
+                "metadata": {},
+                "id": "test_sequence",
+            },
+        )
+
+    async def test_async_streaming_function_returning_plain_values(
+        self,
+    ) -> None:
+        """Test wrapping an async generator that yields plain values."""
+
+        async def stream_status() -> AsyncGenerator[Any, None]:
+            """Stream status information."""
+            yield "started"
+            yield {
+                "done": True,
+            }
+
+        toolkit = Toolkit(
+            tools=[FunctionTool(stream_status)],
+        )
+
+        state = AgentState()
+        tool_call = ToolCallBlock(
+            id="test_status_stream",
+            name="stream_status",
+            input=json.dumps({}),
+        )
+        expected_dict_text = json.dumps(
+            {
+                "done": True,
+            },
+            ensure_ascii=False,
+        )
+
+        chunks = []
+        response = None
+        async for result in toolkit.call_tool(tool_call, state):
+            if isinstance(result, ToolChunk):
+                chunks.append(result)
+            elif isinstance(result, ToolResponse):
+                response = result
+
+        self.assertEqual(
+            [chunk.content[0].text for chunk in chunks],
+            ["started", expected_dict_text],
+        )
+
+        self.assertIsNotNone(response)
+        self.assertEqual(
+            response.content[0].text,
+            f"started{expected_dict_text}",
+        )
+
+
+class ToolGroupTest(IsolatedAsyncioTestCase):
+    """The tool group test case."""
+
+    async def asyncSetUp(self) -> None:
+        """The async setup method."""
+        self.meta_tool_description = (
+            "This tool allows you to reset your equipped tools based on your "
+            "current task requirements. These tools are organized into "
+            "different groups, and you can activate/deactivate them "
+            "by specifying the boolean values for each group in the input.\n\n"
+            "**Important: The input booleans are the final state of their "
+            "corresponding tool groups, not incremental changes.** Any "
+            "group not explicitly set to True will be deactivated, "
+            "regardless of its previous state.\n\n"
+            "**Best practice**: Actively manage your tool groups——activate "
+            "only what you need for the current task, and promptly "
+            "deactivate groups as soon as they are no longer needed to"
+            " conserve context space.\n\n"
+            "This tool will return the usage instructions for the activated "
+            "tool groups, which you **MUST pay attention to and follow**. "
+            "You can also reuse this tool to re-check the instructions."
+        )
+
+    async def test_meta_tool(self) -> None:
+        """Test creating a tool group."""
+        toolkit = Toolkit()
+
+        # Test meta tool when no groups exist
+        schemas = await toolkit.get_tool_schemas()
+        self.assertEqual(len(schemas), 0)
+
+        toolkit = Toolkit(
+            tool_groups=[
+                ToolGroup(
+                    name="group_1",
+                    description="Group 1",
+                ),
+            ],
+        )
+
+        # The group is created successfully
+        self.assertEqual(len(toolkit.tool_groups), 2)
+        # The builtin meta tool is activated
+        schemas = await toolkit.get_tool_schemas()
+
+        self.assertListEqual(
+            schemas,
+            [
+                {
+                    "type": "function",
+                    "function": {
+                        "name": "reset_tools",
+                        "description": self.meta_tool_description,
+                        "parameters": {
+                            "properties": {
+                                "group_1": {
+                                    "default": False,
+                                    "description": "Group 1",
+                                    "type": "boolean",
+                                },
+                            },
+                            "type": "object",
+                        },
+                    },
+                },
+            ],
+        )
+
+        # Name conflict
+        with self.assertRaises(ValueError):
+            Toolkit(
+                tool_groups=[
+                    ToolGroup(
+                        name="group_2",
+                        description="Group 2",
+                    ),
+                    ToolGroup(
+                        name="group_2",
+                        description="Group 2",
+                    ),
+                ],
+            )
+
+        # A new group with tools
+        toolkit = Toolkit(
+            tool_groups=[
+                ToolGroup(
+                    name="group_1",
+                    description="Group 1",
+                ),
+                ToolGroup(
+                    name="group_2",
+                    description="Group 2",
+                    tools=[Tool1(), Tool2()],
+                    instructions="This is group 2.",
+                ),
+            ],
+        )
+
+        self.assertEqual(len(toolkit.tool_groups), 3)
+        schemas = await toolkit.get_tool_schemas()
+        self.assertListEqual(
+            schemas,
+            [
+                {
+                    "type": "function",
+                    "function": {
+                        "name": "reset_tools",
+                        "description": self.meta_tool_description,
+                        "parameters": {
+                            "properties": {
+                                "group_1": {
+                                    "default": False,
+                                    "description": "Group 1",
+                                    "type": "boolean",
+                                },
+                                "group_2": {
+                                    "default": False,
+                                    "description": "Group 2",
+                                    "type": "boolean",
+                                },
+                            },
+                            "type": "object",
+                        },
+                    },
+                },
+            ],
+        )
+
+        # Active one group
+        state = AgentState()
+        res = toolkit.call_tool(
+            ToolCallBlock(
+                id="xxx",
+                name="reset_tools",
+                input=json.dumps({"group_2": True}),
+            ),
+            state,
+        )
+
+        chunk = await anext(res)
+        self.assertIsInstance(chunk, ToolChunk)
+
+        chunk = await anext(res)
+        self.assertIsInstance(chunk, ToolResponse)
+        self.assertDictEqual(
+            chunk.model_dump(),
+            {
+                "id": AnyString(),
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": """The currently activated tool group(s): group_2.
+<tool-instructions>
+The tool instructions are a collection of suggestions, rules and notifications about how to use the tools in the activated groups.
+<group name="group_2">This is group 2.</group>
+</tool-instructions>""",  # noqa: E501
+                    },
+                ],
+                "metadata": {},
+                "state": "success",
+            },
+        )
+
+        # Activate both groups
+        res = toolkit.call_tool(
+            ToolCallBlock(
+                id="xxx",
+                name="reset_tools",
+                input=json.dumps({"group_2": True, "group_1": True}),
+            ),
+            state,
+        )
+
+        last_chunk = None
+        async for chunk in res:
+            last_chunk = chunk
+
+        self.assertDictEqual(
+            last_chunk.model_dump(),
+            {
+                "id": AnyString(),
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": """The currently activated tool group(s): group_1, group_2.
+<tool-instructions>
+The tool instructions are a collection of suggestions, rules and notifications about how to use the tools in the activated groups.
+<group name="group_2">This is group 2.</group>
+</tool-instructions>""",  # noqa: E501
+                    },
+                ],
+                "metadata": {},
+                "state": "success",
+            },
+        )
+
+        # deactivate all groups
+        res = toolkit.call_tool(
+            ToolCallBlock(
+                id="xxx",
+                name="reset_tools",
+                input=json.dumps({}),
+            ),
+            state,
+        )
+
+        last_chunk = None
+        async for chunk in res:
+            last_chunk = chunk
+
+        self.assertDictEqual(
+            last_chunk.model_dump(),
+            {
+                "id": AnyString(),
+                "content": [
+                    {
+                        "type": "text",
+                        "id": AnyString(),
+                        "text": "All tool groups are currently deactivated.",
+                    },
+                ],
+                "metadata": {},
+                "state": "success",
+            },
+        )
+
+
+class RemoveTitleFieldTest(TestCase):
+    """Unit tests for _remove_title_field."""
+
+    def setUp(self) -> None:
+        from agentscope.tool._utils import _remove_title_field
+
+        self.fn = _remove_title_field
+
+    def test_removes_top_level_title(self) -> None:
+        """The top level title field must be removed."""
+        schema = {"title": "Root", "type": "object", "properties": {}}
+        self.fn(schema)
+        self.assertNotIn("title", schema)
+
+    def test_removes_property_titles(self) -> None:
+        """Titles inside properties must be removed."""
+        schema: dict[str, Any] = {
+            "type": "object",
+            "properties": {
+                "name": {"title": "Name", "type": "string"},
+            },
+        }
+        self.fn(schema)
+        self.assertNotIn("title", schema["properties"]["name"])
+
+    def test_removes_defs_titles(self) -> None:
+        """Titles inside $defs must be recursively stripped."""
+        schema: dict[str, Any] = {
+            "type": "object",
+            "properties": {"x": {"$ref": "#/$defs/MyModel"}},
+            "$defs": {
+                "MyModel": {
+                    "title": "MyModel",
+                    "type": "object",
+                    "properties": {
+                        "val": {"title": "Val", "type": "string"},
+                    },
+                },
+            },
+        }
+        self.fn(schema)
+
+        self.assertDictEqual(
+            schema,
+            {
+                "type": "object",
+                "properties": {"x": {"$ref": "#/$defs/MyModel"}},
+                "$defs": {
+                    "MyModel": {
+                        "type": "object",
+                        "properties": {
+                            "val": {"type": "string"},
+                        },
+                    },
+                },
+            },
+        )
+
+    def test_does_not_mutate_non_dict_defs(self) -> None:
+        """Boolean schema values inside $defs should not raise."""
+        schema: dict[str, Any] = {
+            "type": "object",
+            "properties": {},
+            "$defs": {"AlwaysTrue": True},
+        }
+        self.fn(schema)
+        self.assertEqual(schema["$defs"]["AlwaysTrue"], True)
diff --git a/tests/tracing_test.py b/tests/tracing_test.py
new file mode 100644
index 0000000..762df42
--- /dev/null
+++ b/tests/tracing_test.py
@@ -0,0 +1,846 @@
+# -*- coding: utf-8 -*-
+"""Unit tests for the tracing module using an in-memory OTel exporter."""
+import json
+from typing import Any
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from opentelemetry import trace as otel_trace
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import (
+    InMemorySpanExporter,
+)
+
+from utils import MockModel
+
+from agentscope.agent import Agent
+from agentscope.event import (
+    ConfirmResult,
+    ExternalExecutionResultEvent,
+    RequireExternalExecutionEvent,
+    RequireUserConfirmEvent,
+    UserConfirmResultEvent,
+)
+from agentscope.message import (
+    TextBlock,
+    ToolCallBlock,
+    ToolResultBlock,
+    ToolResultState,
+    UserMsg,
+)
+from agentscope.model import ChatResponse, ChatUsage
+from agentscope.permission import (
+    PermissionContext,
+    PermissionDecision,
+    PermissionBehavior,
+)
+from agentscope.tool import Toolkit, ToolBase
+from agentscope.middleware import TracingMiddleware
+
+
+# ---------------------------------------------------------------------------
+# Shared test fixtures
+# ---------------------------------------------------------------------------
+
+
+class WeatherTool(ToolBase):
+    """Stub weather tool for tracing tests."""
+
+    name: str = "get_weather"
+    description: str = "Return stub weather for a city."
+    input_schema: dict = {
+        "type": "object",
+        "properties": {"city": {"type": "string"}},
+        "required": ["city"],
+    }
+    is_concurrency_safe: bool = True
+    is_read_only: bool = True
+    is_external_tool: bool = False
+    is_mcp: bool = False
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        return PermissionDecision(
+            behavior=PermissionBehavior.ALLOW,
+            message="always allowed",
+        )
+
+    async def execute(self, city: str) -> str:
+        """Stub weather tool for tracing tests."""
+        return f"{city}: sunny, 25°C."
+
+
+class HitlWeatherTool(ToolBase):
+    """Weather tool that always asks user for confirmation (HITL)."""
+
+    name: str = "get_weather"
+    description: str = "Return weather for a city, requires user confirmation."
+    input_schema: dict = {
+        "type": "object",
+        "properties": {"city": {"type": "string"}},
+        "required": ["city"],
+    }
+    is_concurrency_safe: bool = True
+    is_read_only: bool = True
+    is_external_tool: bool = False
+    is_mcp: bool = False
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        return PermissionDecision(
+            behavior=PermissionBehavior.ASK,
+            message="user must confirm this tool call",
+        )
+
+    async def execute(self, city: str) -> str:
+        """Stub weather tool for tracing tests."""
+        return f"{city}: sunny, 25°C."
+
+
+class ExternalWeatherTool(ToolBase):
+    """Weather tool that is always executed externally."""
+
+    name: str = "get_weather"
+    description: str = "Return weather for a city via external execution."
+    input_schema: dict = {
+        "type": "object",
+        "properties": {"city": {"type": "string"}},
+        "required": ["city"],
+    }
+    is_concurrency_safe: bool = True
+    is_read_only: bool = True
+    is_external_tool: bool = True  # Mark as external
+    is_mcp: bool = False
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        return PermissionDecision(
+            behavior=PermissionBehavior.ALLOW,
+            message="always allowed",
+        )
+
+    async def execute(self, city: str) -> str:
+        """Stub weather tool for tracing tests."""
+        return f"{city}: sunny, 25°C."
+
+
+def _make_tool_call_response(tool_id: str, city: str) -> ChatResponse:
+    return ChatResponse(
+        content=[
+            ToolCallBlock(
+                id=tool_id,
+                name="get_weather",
+                input=json.dumps({"city": city}),
+            ),
+        ],
+        is_last=True,
+        usage=ChatUsage(input_tokens=10, output_tokens=5, time=0.05),
+    )
+
+
+def _make_text_response(text: str) -> ChatResponse:
+    return ChatResponse(
+        content=[TextBlock(text=text)],
+        is_last=True,
+        usage=ChatUsage(input_tokens=15, output_tokens=8, time=0.05),
+    )
+
+
+class TracingTest(IsolatedAsyncioTestCase):
+    """Tests that OTel spans are emitted with correct attributes.
+
+    The in-memory exporter is set up once per class (setUpClass) because
+    the OTel global TracerProvider cannot be replaced once installed.
+    setUp only creates fresh model/agent and clears the exporter.
+    """
+
+    exporter: InMemorySpanExporter
+
+    @classmethod
+    def setUpClass(cls) -> None:
+        """Configure an in-memory OTel provider once for the whole class."""
+        cls.exporter = InMemorySpanExporter()
+        provider = TracerProvider()
+        provider.add_span_processor(SimpleSpanProcessor(cls.exporter))
+        otel_trace.set_tracer_provider(provider)
+
+    def setUp(self) -> None:
+        """Create a fresh agent and clear accumulated spans before each
+        test."""
+        self.exporter.clear()
+        self.model = MockModel()
+        self.agent = Agent(
+            name="test-agent",
+            system_prompt="You are a test assistant.",
+            model=self.model,
+            toolkit=Toolkit(tools=[WeatherTool()]),
+            middlewares=[TracingMiddleware()],
+        )
+
+    # -----------------------------------------------------------------------
+    # Helpers
+    # -----------------------------------------------------------------------
+
+    def _spans_by_name(self, fragment: str) -> list:
+        return [
+            s
+            for s in self.exporter.get_finished_spans()
+            if fragment in (s.name or "")
+        ]
+
+    def _all_conv_ids(self) -> set:
+        return {
+            dict(s.attributes or {}).get("gen_ai.conversation.id")
+            for s in self.exporter.get_finished_spans()
+            if "gen_ai.conversation.id" in (s.attributes or {})
+        }
+
+    # -----------------------------------------------------------------------
+    # Tests: Agent.reply
+    # -----------------------------------------------------------------------
+
+    async def test_reply_spans_share_conversation_id(self) -> None:
+        """All spans from a single reply must share the same
+        conversation_id."""
+        self.model.set_responses(
+            [
+                _make_tool_call_response("c3", "Guangzhou"),
+                _make_text_response("Guangzhou is sunny."),
+            ],
+        )
+        msg = UserMsg(name="user", content="Weather in Guangzhou?")
+        await self.agent.reply(msg)
+
+        conv_ids = self._all_conv_ids()
+        self.assertEqual(
+            len(conv_ids),
+            1,
+            f"All spans must share exactly one conversation_id, "
+            f"got: {conv_ids}",
+        )
+
+    async def test_invoke_agent_span_has_response_attributes(self) -> None:
+        """invoke_agent span must carry gen_ai.output.messages attribute."""
+        self.model.set_responses(
+            [
+                _make_tool_call_response("c4", "Wuhan"),
+                _make_text_response("Wuhan weather: clear sky."),
+            ],
+        )
+        msg = UserMsg(name="user", content="Weather in Wuhan?")
+        await self.agent.reply(msg)
+
+        agent_spans = self._spans_by_name("invoke_agent")
+        self.assertEqual(
+            len(agent_spans),
+            1,
+            "Expected exactly one invoke_agent span",
+        )
+        span_attrs = dict(agent_spans[0].attributes or {})
+        output_raw = span_attrs.get("gen_ai.output.messages")
+        assert isinstance(
+            output_raw,
+            str,
+        ), "invoke_agent span gen_ai.output.messages should be a string"
+        output = json.loads(output_raw)
+        self.assertEqual(
+            output,
+            [
+                {
+                    "role": "assistant",
+                    "parts": [
+                        {
+                            "type": "text",
+                            "content": "Wuhan weather: clear sky.",
+                        },
+                    ],
+                    "name": "test-agent",
+                    "finish_reason": "stop",
+                },
+            ],
+        )
+
+    async def test_invoke_agent_span_has_input_attributes(self) -> None:
+        """invoke_agent span must carry gen_ai.input.messages attribute."""
+        self.model.set_responses(
+            [
+                _make_text_response("Simple answer."),
+            ],
+        )
+        msg = UserMsg(name="user", content="Simple question?")
+        await self.agent.reply(msg)
+
+        agent_spans = self._spans_by_name("invoke_agent")
+        self.assertEqual(
+            len(agent_spans),
+            1,
+            "Expected exactly one invoke_agent span",
+        )
+        span_attrs = dict(agent_spans[0].attributes or {})
+        input_raw = span_attrs.get("gen_ai.input.messages")
+        assert isinstance(
+            input_raw,
+            str,
+        ), "invoke_agent span gen_ai.input.messages should be a string"
+        input_msgs = json.loads(input_raw)
+        self.assertEqual(
+            input_msgs,
+            [
+                {
+                    "role": "user",
+                    "parts": [
+                        {"type": "text", "content": "Simple question?"},
+                    ],
+                    "name": "user",
+                    "finish_reason": "stop",
+                },
+            ],
+        )
+
+    async def test_execute_tool_span_has_tool_name_attribute(self) -> None:
+        """execute_tool span must have the correct gen_ai.tool.name
+        attribute."""
+        self.model.set_responses(
+            [
+                _make_tool_call_response("c8", "Nanjing"),
+                _make_text_response("Nanjing result."),
+            ],
+        )
+        msg = UserMsg(name="user", content="Weather in Nanjing?")
+        await self.agent.reply(msg)
+
+        tool_spans = self._spans_by_name("execute_tool")
+        self.assertEqual(
+            len(tool_spans),
+            1,
+            "Expected exactly one execute_tool span",
+        )
+        span_attrs = dict(tool_spans[0].attributes or {})
+        self.assertEqual(
+            span_attrs.get("gen_ai.tool.name"),
+            "get_weather",
+            "execute_tool span should have gen_ai.tool.name = get_weather",
+        )
+
+    # -----------------------------------------------------------------------
+    # Tests: chat (LLM) span
+    # -----------------------------------------------------------------------
+
+    async def test_chat_span_has_model_and_provider(self) -> None:
+        """chat span must carry gen_ai.request.model and
+        gen_ai.provider.name."""
+        self.model.set_responses(
+            [_make_text_response("Hello from model.")],
+        )
+        msg = UserMsg(name="user", content="Hello?")
+        await self.agent.reply(msg)
+
+        chat_spans = self._spans_by_name("chat")
+        self.assertEqual(len(chat_spans), 1, "Expected exactly one chat span")
+        span_attrs = dict(chat_spans[0].attributes or {})
+        self.assertEqual(
+            span_attrs.get("gen_ai.request.model"),
+            "mock-model",
+            "chat span gen_ai.request.model should equal mock-model",
+        )
+        self.assertEqual(
+            span_attrs.get("gen_ai.operation.name"),
+            "chat",
+            "chat span gen_ai.operation.name should equal chat",
+        )
+
+    async def test_chat_span_has_output_messages(self) -> None:
+        """chat span must carry gen_ai.output.messages with response
+        content."""
+        self.model.set_responses(
+            [_make_text_response("Weather is fine.")],
+        )
+        msg = UserMsg(name="user", content="How is the weather?")
+        await self.agent.reply(msg)
+
+        chat_spans = self._spans_by_name("chat")
+        self.assertEqual(len(chat_spans), 1, "Expected exactly one chat span")
+        span_attrs = dict(chat_spans[0].attributes or {})
+        output_raw = span_attrs.get("gen_ai.output.messages")
+        assert isinstance(
+            output_raw,
+            str,
+        ), "chat span gen_ai.output.messages should be a string"
+        output = json.loads(output_raw)
+        self.assertEqual(
+            output,
+            [
+                {
+                    "role": "assistant",
+                    "parts": [
+                        {"type": "text", "content": "Weather is fine."},
+                    ],
+                    "finish_reason": "stop",
+                },
+            ],
+        )
+
+    async def test_chat_span_has_usage_tokens(self) -> None:
+        """chat span must carry input/output token counts from usage."""
+        self.model.set_responses(
+            [_make_text_response("Token test.")],
+        )
+        msg = UserMsg(name="user", content="Count tokens?")
+        await self.agent.reply(msg)
+
+        chat_spans = self._spans_by_name("chat")
+        self.assertEqual(len(chat_spans), 1, "Expected exactly one chat span")
+        span_attrs = dict(chat_spans[0].attributes or {})
+        self.assertEqual(
+            span_attrs.get("gen_ai.usage.input_tokens"),
+            15,
+            "chat span gen_ai.usage.input_tokens should equal 15",
+        )
+        self.assertEqual(
+            span_attrs.get("gen_ai.usage.output_tokens"),
+            8,
+            "chat span gen_ai.usage.output_tokens should equal 8",
+        )
+
+    # -----------------------------------------------------------------------
+    # Tests: reply_id attribute
+    # -----------------------------------------------------------------------
+
+    async def test_invoke_agent_span_has_reply_id(self) -> None:
+        """invoke_agent span from a normal reply must carry reply_id.
+
+        reply() delegates to _reply(), which is the only decorated entry
+        point, so there is exactly one invoke_agent span.  We search by
+        attribute rather than relying on list order for robustness.
+        """
+        self.model.set_responses(
+            [
+                _make_tool_call_response("r1", "Wuhan"),
+                _make_text_response("Wuhan: clear sky."),
+            ],
+        )
+        msg = UserMsg(name="user", content="Weather in Wuhan?")
+        await self.agent.reply(msg)
+
+        agent_spans = self._spans_by_name("invoke_agent")
+        self.assertEqual(
+            len(agent_spans),
+            1,
+            "Expected exactly one invoke_agent span",
+        )
+        span_attrs = dict(agent_spans[0].attributes or {})
+        self.assertIn(
+            "agentscope.agent.reply_id",
+            span_attrs,
+            "invoke_agent span should have agentscope.agent.reply_id",
+        )
+
+    # -----------------------------------------------------------------------
+    # Tests: HITL (Human-in-the-loop)
+    # -----------------------------------------------------------------------
+
+    async def test_hitl_first_call_has_hitl_pending_attribute(self) -> None:
+        """First call in HITL flow must have
+        agentscope.agent.hitl_pending_tools."""
+        hitl_agent = Agent(
+            name="hitl-agent",
+            system_prompt="You are a test assistant.",
+            model=self.model,
+            toolkit=Toolkit(tools=[HitlWeatherTool()]),
+            middlewares=[TracingMiddleware()],
+        )
+        # The HITL tool returns ASK;
+        # first call ends with RequireUserConfirmEvent
+        self.model.set_responses(
+            [_make_tool_call_response("h1", "Beijing")],
+        )
+        self.exporter.clear()
+
+        msg = UserMsg(name="user", content="Weather in Beijing?")
+        async for _ in hitl_agent.reply_stream(msg):
+            pass
+
+        first_spans = self._spans_by_name("invoke_agent")
+        self.assertEqual(
+            len(first_spans),
+            1,
+            "Expected exactly one invoke_agent span from first HITL call",
+        )
+        span_attrs = dict(first_spans[0].attributes or {})
+        self.assertIn(
+            "agentscope.agent.hitl_pending_tools",
+            span_attrs,
+            "First HITL span should carry agentscope.agent.hitl_pending_tools",
+        )
+        pending = json.loads(span_attrs["agentscope.agent.hitl_pending_tools"])
+        self.assertEqual(pending, ["get_weather"])
+
+    async def test_hitl_spans_share_reply_id(self) -> None:
+        """Both HITL calls must share the same agentscope.agent.reply_id."""
+        hitl_agent = Agent(
+            name="hitl-agent2",
+            system_prompt="You are a test assistant.",
+            model=self.model,
+            toolkit=Toolkit(tools=[HitlWeatherTool()]),
+            middlewares=[TracingMiddleware()],
+        )
+
+        # First call: agent asks for confirmation
+        self.model.set_responses(
+            [_make_tool_call_response("h2", "Shanghai")],
+        )
+        self.exporter.clear()
+
+        require_confirm_event = None
+        async for evt in hitl_agent.reply_stream(
+            UserMsg(name="user", content="Weather in Shanghai?"),
+        ):
+            if isinstance(evt, RequireUserConfirmEvent):
+                require_confirm_event = evt
+
+        self.assertIsNotNone(
+            require_confirm_event,
+            "Expected RequireUserConfirmEvent",
+        )
+
+        first_spans = self._spans_by_name("invoke_agent")
+        first_reply_ids = {
+            dict(s.attributes or {}).get("agentscope.agent.reply_id")
+            for s in first_spans
+            if "agentscope.agent.reply_id" in (s.attributes or {})
+        }
+        self.assertEqual(len(first_reply_ids), 1)
+        reply_id_first = next(iter(first_reply_ids))
+
+        # Second call: user confirms
+        self.model.set_responses(
+            [_make_text_response("Shanghai: 18°C, raining.")],
+        )
+        self.exporter.clear()
+
+        confirm_event = UserConfirmResultEvent(
+            reply_id=require_confirm_event.reply_id,
+            confirm_results=[
+                ConfirmResult(
+                    confirmed=True,
+                    tool_call=require_confirm_event.tool_calls[0],
+                ),
+            ],
+        )
+        await hitl_agent.reply(inputs=confirm_event)
+
+        second_spans = self._spans_by_name("invoke_agent")
+        second_reply_ids = {
+            dict(s.attributes or {}).get("agentscope.agent.reply_id")
+            for s in second_spans
+            if "agentscope.agent.reply_id" in (s.attributes or {})
+        }
+        self.assertEqual(len(second_reply_ids), 1)
+        reply_id_second = next(iter(second_reply_ids))
+
+        self.assertEqual(
+            reply_id_first,
+            reply_id_second,
+            "Both HITL calls must share the same reply_id",
+        )
+
+    async def test_hitl_second_call_has_incoming_event_type(self) -> None:
+        """Second call in HITL flow must carry
+        incoming_event_type=user_confirm_result."""
+        hitl_agent = Agent(
+            name="hitl-agent3",
+            system_prompt="You are a test assistant.",
+            model=self.model,
+            toolkit=Toolkit(tools=[HitlWeatherTool()]),
+            middlewares=[TracingMiddleware()],
+        )
+
+        # First call: agent asks for confirmation
+        self.model.set_responses(
+            [_make_tool_call_response("h3", "Tianjin")],
+        )
+        self.exporter.clear()
+
+        require_confirm_event = None
+        async for evt in hitl_agent.reply_stream(
+            UserMsg(name="user", content="Weather in Tianjin?"),
+        ):
+            if isinstance(evt, RequireUserConfirmEvent):
+                require_confirm_event = evt
+
+        self.assertIsNotNone(
+            require_confirm_event,
+            "Expected RequireUserConfirmEvent",
+        )
+
+        # Second call: user confirms
+        self.model.set_responses(
+            [_make_text_response("Tianjin: windy, 12°C.")],
+        )
+        self.exporter.clear()
+
+        confirm_event = UserConfirmResultEvent(
+            reply_id=require_confirm_event.reply_id,
+            confirm_results=[
+                ConfirmResult(
+                    confirmed=True,
+                    tool_call=require_confirm_event.tool_calls[0],
+                ),
+            ],
+        )
+        await hitl_agent.reply(inputs=confirm_event)
+
+        agent_spans = self._spans_by_name("invoke_agent")
+        self.assertEqual(
+            len(agent_spans),
+            1,
+            "Expected exactly one invoke_agent span from second HITL call",
+        )
+        span_attrs = dict(agent_spans[0].attributes or {})
+        self.assertEqual(
+            span_attrs.get("agentscope.agent.incoming_event_type"),
+            "user_confirm_result",
+            "Second HITL invoke_agent span should have "
+            "incoming_event_type=user_confirm_result",
+        )
+
+    # -----------------------------------------------------------------------
+    # Tests: External execution
+    # -----------------------------------------------------------------------
+
+    async def test_external_execution_first_call_has_pending_attribute(
+        self,
+    ) -> None:
+        """First call must have
+        agentscope.agent.external_execution_pending_tools."""
+        ext_agent = Agent(
+            name="ext-agent",
+            system_prompt="You are a test assistant.",
+            model=self.model,
+            toolkit=Toolkit(tools=[ExternalWeatherTool()]),
+            middlewares=[TracingMiddleware()],
+        )
+        self.model.set_responses(
+            [_make_tool_call_response("e1", "Guangzhou")],
+        )
+        self.exporter.clear()
+
+        async for _ in ext_agent.reply_stream(
+            UserMsg(name="user", content="Weather in Guangzhou?"),
+        ):
+            pass
+
+        first_spans = self._spans_by_name("invoke_agent")
+        self.assertEqual(
+            len(first_spans),
+            1,
+            "Expected exactly one invoke_agent span",
+        )
+        span_attrs = dict(first_spans[0].attributes or {})
+        self.assertIn(
+            "agentscope.agent.external_execution_pending_tools",
+            span_attrs,
+            "First external-execution span should carry "
+            "agentscope.agent.external_execution_pending_tools",
+        )
+        pending = json.loads(
+            span_attrs["agentscope.agent.external_execution_pending_tools"],
+        )
+        self.assertEqual(pending, ["get_weather"])
+
+    async def test_external_execution_spans_share_reply_id(self) -> None:
+        """Both external-execution calls must share the same reply_id."""
+        ext_agent = Agent(
+            name="ext-agent-rid",
+            system_prompt="You are a test assistant.",
+            model=self.model,
+            toolkit=Toolkit(tools=[ExternalWeatherTool()]),
+            middlewares=[TracingMiddleware()],
+        )
+
+        # First call: agent requires external execution
+        self.model.set_responses(
+            [_make_tool_call_response("ex-r1", "Nanjing")],
+        )
+        self.exporter.clear()
+
+        require_ext_event = None
+        async for evt in ext_agent.reply_stream(
+            UserMsg(name="user", content="Weather in Nanjing?"),
+        ):
+            if isinstance(evt, RequireExternalExecutionEvent):
+                require_ext_event = evt
+
+        self.assertIsNotNone(
+            require_ext_event,
+            "Expected RequireExternalExecutionEvent",
+        )
+
+        first_spans = self._spans_by_name("invoke_agent")
+        first_reply_ids = {
+            dict(s.attributes or {}).get("agentscope.agent.reply_id")
+            for s in first_spans
+            if "agentscope.agent.reply_id" in (s.attributes or {})
+        }
+        self.assertEqual(len(first_reply_ids), 1)
+        reply_id_first = next(iter(first_reply_ids))
+
+        # Second call: inject external result
+        self.model.set_responses(
+            [_make_text_response("Nanjing: clear, 18°C.")],
+        )
+        self.exporter.clear()
+
+        ext_result = ExternalExecutionResultEvent(
+            reply_id=require_ext_event.reply_id,
+            execution_results=[
+                ToolResultBlock(
+                    id=require_ext_event.tool_calls[0].id,
+                    name="get_weather",
+                    output="Nanjing: clear, 18°C.",
+                    state=ToolResultState.SUCCESS,
+                ),
+            ],
+        )
+        await ext_agent.reply(inputs=ext_result)
+
+        second_spans = self._spans_by_name("invoke_agent")
+        second_reply_ids = {
+            dict(s.attributes or {}).get("agentscope.agent.reply_id")
+            for s in second_spans
+            if "agentscope.agent.reply_id" in (s.attributes or {})
+        }
+        self.assertEqual(len(second_reply_ids), 1)
+        reply_id_second = next(iter(second_reply_ids))
+
+        self.assertEqual(
+            reply_id_first,
+            reply_id_second,
+            "Both external-execution calls must share the same reply_id",
+        )
+
+    async def test_external_execution_second_call_has_synthetic_tool_span(
+        self,
+    ) -> None:
+        """Second call with ExternalExecutionResultEvent must produce
+        execute_tool span."""
+        ext_agent = Agent(
+            name="ext-agent2",
+            system_prompt="You are a test assistant.",
+            model=self.model,
+            toolkit=Toolkit(tools=[ExternalWeatherTool()]),
+            middlewares=[TracingMiddleware()],
+        )
+
+        # First call
+        self.model.set_responses(
+            [_make_tool_call_response("e2", "Shenzhen")],
+        )
+        self.exporter.clear()
+
+        require_ext_event = None
+        async for evt in ext_agent.reply_stream(
+            UserMsg(name="user", content="Weather in Shenzhen?"),
+        ):
+            if isinstance(evt, RequireExternalExecutionEvent):
+                require_ext_event = evt
+
+        self.assertIsNotNone(require_ext_event)
+
+        # Second call: inject external result
+        self.model.set_responses(
+            [_make_text_response("Shenzhen: warm, 28°C.")],
+        )
+        self.exporter.clear()
+
+        ext_result = ExternalExecutionResultEvent(
+            reply_id=require_ext_event.reply_id,
+            execution_results=[
+                ToolResultBlock(
+                    id=require_ext_event.tool_calls[0].id,
+                    name="get_weather",
+                    output="Shenzhen: warm, 28°C.",
+                    state=ToolResultState.SUCCESS,
+                ),
+            ],
+        )
+        await ext_agent.reply(inputs=ext_result)
+
+        tool_spans = self._spans_by_name("execute_tool")
+        self.assertEqual(
+            len(tool_spans),
+            1,
+            "Expected exactly one synthetic execute_tool span",
+        )
+        span_attrs = dict(tool_spans[0].attributes or {})
+        self.assertEqual(
+            span_attrs.get("agentscope.agent.is_external_execution"),
+            True,
+            "Synthetic execute_tool span should have "
+            "is_external_execution=True",
+        )
+        self.assertEqual(span_attrs.get("gen_ai.tool.name"), "get_weather")
+
+    async def test_external_execution_second_call_has_incoming_event_type(
+        self,
+    ) -> None:
+        """Second call span must have
+        incoming_event_type=external_execution_result."""
+        ext_agent = Agent(
+            name="ext-agent3",
+            system_prompt="You are a test assistant.",
+            model=self.model,
+            toolkit=Toolkit(tools=[ExternalWeatherTool()]),
+            middlewares=[TracingMiddleware()],
+        )
+
+        # First call
+        self.model.set_responses(
+            [_make_tool_call_response("e3", "Chengdu")],
+        )
+        self.exporter.clear()
+
+        require_ext_event = None
+        async for evt in ext_agent.reply_stream(
+            UserMsg(name="user", content="Weather in Chengdu?"),
+        ):
+            if isinstance(evt, RequireExternalExecutionEvent):
+                require_ext_event = evt
+
+        # Second call
+        self.model.set_responses([_make_text_response("Chengdu: cloudy.")])
+        self.exporter.clear()
+
+        ext_result = ExternalExecutionResultEvent(
+            reply_id=require_ext_event.reply_id,
+            execution_results=[
+                ToolResultBlock(
+                    id=require_ext_event.tool_calls[0].id,
+                    name="get_weather",
+                    output="Chengdu: cloudy, 15°C.",
+                    state=ToolResultState.SUCCESS,
+                ),
+            ],
+        )
+        await ext_agent.reply(inputs=ext_result)
+
+        agent_spans = self._spans_by_name("invoke_agent")
+        self.assertEqual(
+            len(agent_spans),
+            1,
+            "Expected exactly one invoke_agent span",
+        )
+        span_attrs = dict(agent_spans[0].attributes or {})
+        self.assertEqual(
+            span_attrs.get("agentscope.agent.incoming_event_type"),
+            "external_execution_result",
+        )
diff --git a/tests/tts_dashscope_test.py b/tests/tts_dashscope_test.py
new file mode 100644
index 0000000..6c3fc2b
--- /dev/null
+++ b/tests/tts_dashscope_test.py
@@ -0,0 +1,1440 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Unit tests for the TTS module.
+
+Covers:
+  * ``TTSModelBase`` default no-op behaviour for ``connect`` / ``close`` /
+    ``push`` (so non-realtime subclasses needn't override them).
+  * ``DashScopeTTSModel`` non-streaming aggregation.
+  * ``DashScopeTTSModel`` streaming: incremental deltas and ``is_last``
+    placement at the final chunk only.
+  * ``DashScopeCosyVoiceTTSModel`` WebSocket TTS streaming and non-streaming
+    output over a mocked SDK.
+  * ``DashScopeRealtimeTTSModel`` connect / close / push / synthesize
+    lifecycle over a mocked WebSocket.
+  * ``DashScopeCosyVoiceTTSModel`` realtime connect / close / push /
+    synthesize lifecycle over a mocked SpeechSynthesizer.
+"""
+import base64
+import io
+import wave
+from typing import Any, AsyncGenerator
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import MagicMock, Mock, patch
+
+from agentscope.app._service._tts_model import _resolve_tts_class
+from agentscope.credential import DashScopeCredential
+from agentscope.tts import (
+    DashScopeCosyVoiceTTSModel,
+    DashScopeTTSModel,
+    DashScopeRealtimeTTSModel,
+    TTSModelBase,
+    TTSResponse,
+)
+
+
+_MEDIA_TYPE = "audio/wav"
+# DashScope TTS emits 24kHz / mono / 16-bit PCM; the WAV wrapping in the
+# model layer uses the same parameters.
+_TTS_SAMPLE_RATE = 24000
+_TTS_CHANNELS = 1
+_TTS_SAMPLE_WIDTH = 2  # bytes (= 16 bit)
+_WAV_HEADER_LEN = 44
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_api_chunk(
+    data_bytes: bytes | None,
+    usage: Any = None,
+) -> MagicMock:
+    """Build a chunk shaped like what dashscope.MultiModalConversation
+    yields. ``data_bytes=None`` represents a chunk with no output."""
+    chunk = MagicMock()
+    chunk.usage = usage
+    if data_bytes is None:
+        chunk.output = None
+        return chunk
+    chunk.output = MagicMock()
+    chunk.output.audio = MagicMock()
+    chunk.output.audio.data = base64.b64encode(data_bytes).decode("ascii")
+    return chunk
+
+
+def _make_usage(
+    input_tokens: int = 0,
+    output_tokens: int = 0,
+    characters: int = 0,
+) -> MagicMock:
+    """Build a usage object shaped like what the DashScope API returns."""
+    usage = MagicMock()
+    usage.input_tokens = input_tokens
+    usage.output_tokens = output_tokens
+    usage.characters = characters
+    return usage
+
+
+def _make_api_generator(chunks: list[bytes | None]) -> Any:
+    """Build a sync generator like ``MultiModalConversation.call`` returns.
+    The last chunk carries a usage object."""
+
+    def _gen() -> Any:
+        for i, data in enumerate(chunks):
+            is_last = i == len(chunks) - 1
+            usage = _make_usage(characters=10) if is_last else None
+            yield _make_api_chunk(data, usage=usage)
+
+    return _gen()
+
+
+# ---------------------------------------------------------------------------
+# TTSModelBase — default no-op surface for non-realtime subclasses
+# ---------------------------------------------------------------------------
+
+
+class _DummyTTS(TTSModelBase):
+    """Minimal subclass that implements only ``synthesize`` — exercises the
+    base class's no-op ``connect`` / ``close`` / ``push`` defaults."""
+
+    async def synthesize(
+        self,
+        text: str | None = None,
+        **kwargs: Any,
+    ) -> TTSResponse | AsyncGenerator[TTSResponse, None]:
+        del text, kwargs
+        return TTSResponse(content=None)
+
+
+class _RealtimeDummyTTS(_DummyTTS):
+    """Realtime-flavoured dummy to assert ``__aenter__`` drives the lifecycle
+    hooks when ``realtime`` is True."""
+
+    realtime = True
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.connect_calls = 0
+        self.close_calls = 0
+
+    async def connect(self) -> None:
+        self.connect_calls += 1
+
+    async def close(self) -> None:
+        self.close_calls += 1
+
+
+def _make_dummy(cls: type = _DummyTTS) -> TTSModelBase:
+    return cls(
+        credential=DashScopeCredential(api_key="test"),
+        model="x",
+        stream=False,
+    )
+
+
+class TestTTSModelBaseDefaults(IsolatedAsyncioTestCase):
+    """The base class supplies safe no-op defaults so non-realtime subclasses
+    don't need to implement realtime-only hooks."""
+
+    async def test_default_connect_close_noop(self) -> None:
+        """Default connect/close return without raising."""
+        model = _make_dummy()
+        await model.connect()
+        await model.close()
+
+    async def test_default_push_returns_empty(self) -> None:
+        """Default push returns an empty TTSResponse rather than raising,
+        so a misuse on a non-realtime model degrades gracefully."""
+        model = _make_dummy()
+        resp = await model.push("ignored")
+        self.assertIsNone(resp.content)
+
+    async def test_aenter_skips_hooks_for_non_realtime(self) -> None:
+        """``async with`` on a non-realtime model must not invoke connect/
+        close (gated by ``realtime``)."""
+        model = _make_dummy(_DummyTTS)
+        async with model as m:
+            self.assertIs(m, model)
+
+    async def test_aenter_invokes_hooks_for_realtime(self) -> None:
+        """For ``realtime=True`` subclasses, connect/close fire on
+        enter/exit exactly once."""
+        model = _make_dummy(_RealtimeDummyTTS)
+        async with model:
+            self.assertEqual(model.connect_calls, 1)
+            self.assertEqual(model.close_calls, 0)
+        self.assertEqual(model.close_calls, 1)
+
+
+# ---------------------------------------------------------------------------
+# DashScopeTTSModel — non-streaming and streaming
+# ---------------------------------------------------------------------------
+
+
+def _parse_wav_payload(wav_bytes: bytes) -> bytes:
+    """Decode a full WAV file and return its raw PCM frames."""
+    with wave.open(io.BytesIO(wav_bytes), "rb") as wav:
+        return wav.readframes(wav.getnframes())
+
+
+class TestDashScopeTTSModel(IsolatedAsyncioTestCase):
+    """The unittests for DashScope TTS model (non-realtime)."""
+
+    def setUp(self) -> None:
+        """Set up the test case."""
+        self.patcher = patch("dashscope.MultiModalConversation")
+        self.mock_mmc = self.patcher.start()
+
+    def tearDown(self) -> None:
+        """Tear down the test case."""
+        self.patcher.stop()
+
+    def _make_model(self, stream: bool = False) -> DashScopeTTSModel:
+        """Create a DashScopeTTSModel with test credentials."""
+        return DashScopeTTSModel(
+            credential=DashScopeCredential(api_key="test"),
+            model="qwen3-tts-flash",
+            parameters=DashScopeTTSModel.Parameters(voice="Cherry"),
+            stream=stream,
+        )
+
+    # -- non-streaming --
+
+    async def test_aggregates_chunks(self) -> None:
+        """All API chunks are aggregated into one self-contained WAV."""
+        self.mock_mmc.call.return_value = _make_api_generator(
+            [b"AAAA", b"BBBB", b"CCCC"],
+        )
+        model = self._make_model(stream=False)
+
+        result = await model.synthesize("Hello world")
+
+        self.assertIsInstance(result, TTSResponse)
+        self.assertEqual(result.content.source.media_type, _MEDIA_TYPE)
+        wav_bytes = base64.b64decode(result.content.source.data)
+        with wave.open(io.BytesIO(wav_bytes), "rb") as wav:
+            self.assertEqual(
+                {
+                    "framerate": wav.getframerate(),
+                    "channels": wav.getnchannels(),
+                    "sampwidth": wav.getsampwidth(),
+                    "frames": wav.readframes(wav.getnframes()),
+                },
+                {
+                    "framerate": _TTS_SAMPLE_RATE,
+                    "channels": _TTS_CHANNELS,
+                    "sampwidth": _TTS_SAMPLE_WIDTH,
+                    "frames": b"AAAABBBBCCCC",
+                },
+            )
+        self.assertTrue(result.is_last)
+
+    async def test_none_short_circuits(self) -> None:
+        """``synthesize(None)`` returns an empty response without touching
+        the API."""
+        model = self._make_model(stream=False)
+
+        result = await model.synthesize(None)
+
+        self.assertIsNone(result.content)
+        self.mock_mmc.call.assert_not_called()
+
+    async def test_empty_string_short_circuits(self) -> None:
+        """``synthesize("")`` returns an empty response without touching
+        the API."""
+        model = self._make_model(stream=False)
+
+        result = await model.synthesize("")
+
+        self.assertIsNone(result.content)
+        self.mock_mmc.call.assert_not_called()
+
+    async def test_skips_empty_chunks(self) -> None:
+        """Chunks without ``output`` are ignored during aggregation."""
+        self.mock_mmc.call.return_value = _make_api_generator(
+            [None, b"AAAA", None, b"BBBB"],
+        )
+        model = self._make_model(stream=False)
+
+        result = await model.synthesize("Hello world")
+
+        wav_bytes = base64.b64decode(result.content.source.data)
+        self.assertEqual(_parse_wav_payload(wav_bytes), b"AAAABBBB")
+
+    # -- streaming --
+
+    async def test_incremental_deltas(self) -> None:
+        """Each API chunk yields one TTSResponse with incremental PCM."""
+        self.mock_mmc.call.return_value = _make_api_generator(
+            [b"AAAA", b"BBBB", b"CCCC"],
+        )
+        model = self._make_model(stream=True)
+
+        gen = await model.synthesize("Hello world")
+        chunks = [c async for c in gen]
+
+        payloads = [base64.b64decode(c.content.source.data) for c in chunks]
+
+        self.assertTrue(payloads[0].startswith(b"RIFF"))
+        self.assertEqual(payloads[0][8:12], b"WAVE")
+        self.assertEqual(payloads[0][_WAV_HEADER_LEN:], b"AAAA")
+        self.assertEqual(payloads[1], b"BBBB")
+        self.assertEqual(payloads[2], b"CCCC")
+
+        self.assertEqual(
+            [c.is_last for c in chunks],
+            [False, False, True],
+        )
+        self.assertEqual(
+            [c.content.source.media_type for c in chunks],
+            [_MEDIA_TYPE, _MEDIA_TYPE, _MEDIA_TYPE],
+        )
+
+    async def test_single_chunk_marked_last(self) -> None:
+        """A lone audio chunk is flagged ``is_last=True`` with a streaming
+        WAV header."""
+        self.mock_mmc.call.return_value = _make_api_generator([b"ONLYCHUNK"])
+        model = self._make_model(stream=True)
+
+        gen = await model.synthesize("Hello world")
+        chunks = [c async for c in gen]
+
+        self.assertEqual(len(chunks), 1)
+        self.assertTrue(chunks[0].is_last)
+        payload = base64.b64decode(chunks[0].content.source.data)
+        self.assertTrue(payload.startswith(b"RIFF"))
+        self.assertEqual(payload[_WAV_HEADER_LEN:], b"ONLYCHUNK")
+
+    async def test_empty_stream_yields_terminal(self) -> None:
+        """When the API yields no audio, the generator emits a terminal
+        sentinel so consumers can detect EOS."""
+        self.mock_mmc.call.return_value = _make_api_generator([None, None])
+        model = self._make_model(stream=True)
+
+        gen = await model.synthesize("Hello world")
+        chunks = [c async for c in gen]
+
+        self.assertEqual(len(chunks), 1)
+        self.assertIsNone(chunks[0].content)
+        self.assertTrue(chunks[0].is_last)
+
+
+# ---------------------------------------------------------------------------
+# DashScopeCosyVoiceTTSModel — WebSocket TTS streaming and aggregation
+# ---------------------------------------------------------------------------
+
+
+class TestDashScopeCosyVoiceTTSModel(IsolatedAsyncioTestCase):
+    """The unittests for DashScope CosyVoice TTS model."""
+
+    def setUp(self) -> None:
+        """Set up the test case."""
+        self.patcher = patch(
+            "dashscope.audio.tts_v2.SpeechSynthesizer",
+        )
+        self.mock_synthesizer_class = self.patcher.start()
+        self.synthesizer_instances: list[Mock] = []
+        self.next_audio = b"FULL_AUDIO"
+        self.next_chunks = [b"CHUNK"]
+        self.mock_synthesizer_class.side_effect = self._make_synthesizer
+
+    def tearDown(self) -> None:
+        """Tear down the test case."""
+        self.patcher.stop()
+
+    def _make_synthesizer(self, **init_kwargs: Any) -> Mock:
+        """Create a mocked tts_v2 SpeechSynthesizer instance."""
+        synth = Mock()
+        synth.init_kwargs = init_kwargs
+        callback = init_kwargs.get("callback")
+
+        if callback is None:
+            synth.call = Mock(return_value=self.next_audio)
+        else:
+
+            def _call(text: str, **kwargs: Any) -> None:
+                del text, kwargs
+                for chunk in self.next_chunks:
+                    callback.on_data(chunk)
+                callback.on_complete()
+                callback.on_close()
+
+            synth.call = Mock(side_effect=_call)
+
+        self.synthesizer_instances.append(synth)
+        return synth
+
+    def _make_model(
+        self,
+        stream: bool = False,
+    ) -> DashScopeCosyVoiceTTSModel:
+        """Create a DashScopeCosyVoiceTTSModel with test credentials."""
+        return DashScopeCosyVoiceTTSModel(
+            credential=DashScopeCredential(api_key="test"),
+            model="cosyvoice-v3-flash",
+            parameters=DashScopeCosyVoiceTTSModel.Parameters(
+                voice="longanhuan",
+            ),
+            stream=stream,
+        )
+
+    async def test_empty_string_short_circuits(self) -> None:
+        """``synthesize("")`` returns empty without touching the SDK."""
+        model = self._make_model(stream=False)
+
+        result = await model.synthesize("")
+
+        self.assertIsNone(result.content)
+        self.mock_synthesizer_class.assert_not_called()
+
+    async def test_non_stream_returns_full_audio(
+        self,
+    ) -> None:
+        """stream=False returns one full audio payload from the SDK."""
+        self.next_audio = b"AAAABBBB"
+        model = self._make_model(stream=False)
+
+        result = await model.synthesize("Hello")
+
+        self.assertIsInstance(result, TTSResponse)
+        self.assertEqual(result.content.source.media_type, _MEDIA_TYPE)
+        wav_payload = base64.b64decode(result.content.source.data)
+        with wave.open(io.BytesIO(wav_payload), "rb") as wav:
+            self.assertEqual(wav.getnchannels(), 1)
+            self.assertEqual(wav.getframerate(), 24000)
+            self.assertEqual(wav.readframes(wav.getnframes()), b"AAAABBBB")
+
+        synth = self.synthesizer_instances[-1]
+        init_kwargs = synth.init_kwargs
+        self.assertEqual(init_kwargs["model"], "cosyvoice-v3-flash")
+        self.assertEqual(init_kwargs["voice"], "longanhuan")
+        self.assertEqual(init_kwargs["format"].format, "pcm")
+        self.assertEqual(init_kwargs["format"].sample_rate, 24000)
+        synth.call.assert_called_once_with(text="Hello")
+
+    async def test_streaming_returns_callback_audio_chunks(
+        self,
+    ) -> None:
+        """stream=True returns callback audio chunks."""
+        self.next_chunks = [b"AAAA", b"BBBB"]
+        model = self._make_model(stream=True)
+
+        gen = await model.synthesize("Hello")
+        chunks = [c async for c in gen]
+
+        self.assertEqual(len(chunks), 1)
+        payload = base64.b64decode(chunks[0].content.source.data)
+        self.assertTrue(payload.startswith(b"RIFF"))
+        self.assertTrue(payload.endswith(b"AAAABBBB"))
+        self.assertEqual([c.is_last for c in chunks], [True])
+
+        synth = self.synthesizer_instances[-1]
+        self.assertIsNotNone(synth.init_kwargs["callback"])
+        synth.call.assert_called_once_with(text="Hello")
+
+    async def test_model_cards_and_credential_wiring(self) -> None:
+        """CosyVoice model cards are discovered only by the CosyVoice class,
+        and DashScope credentials expose the class."""
+        cosyvoice_cards = DashScopeCosyVoiceTTSModel.list_models()
+        cosyvoice_names = {card.name for card in cosyvoice_cards}
+        self.assertEqual(len(cosyvoice_cards), 2)
+        self.assertIn("cosyvoice-v3-flash", cosyvoice_names)
+        self.assertIn("cosyvoice-v3-plus", cosyvoice_names)
+        self.assertTrue(all(not card.realtime for card in cosyvoice_cards))
+        for card in cosyvoice_cards:
+            properties = card.parameter_schema["properties"]
+            self.assertIn("voice", properties)
+            self.assertIn("realtime", properties)
+        plus_card = next(
+            card
+            for card in cosyvoice_cards
+            if card.name == "cosyvoice-v3-plus"
+        )
+        self.assertIn(
+            "longanhuan",
+            plus_card.parameter_schema["properties"]["voice"]["enum"],
+        )
+
+        qwen_names = {card.name for card in DashScopeTTSModel.list_models()}
+        self.assertNotIn("cosyvoice-v3-flash", qwen_names)
+        self.assertNotIn("cosyvoice-v3-plus", qwen_names)
+
+        credential_classes = DashScopeCredential.get_tts_model_classes()
+        self.assertIn(DashScopeCosyVoiceTTSModel, credential_classes)
+        credential_names = {
+            card.name for card in DashScopeCredential.list_tts_models()
+        }
+        self.assertIn("cosyvoice-v3-flash", credential_names)
+        self.assertIn("cosyvoice-v3-plus", credential_names)
+
+        resolved_without_realtime = _resolve_tts_class(
+            credential_classes,
+            "cosyvoice-v3-plus",
+        )
+        self.assertIs(
+            resolved_without_realtime,
+            DashScopeCosyVoiceTTSModel,
+        )
+
+
+# ---------------------------------------------------------------------------
+# DashScopeRealtimeTTSModel — realtime push / synthesize lifecycle
+# ---------------------------------------------------------------------------
+
+
+class TestDashScopeRealtimeTTSModel(  # pylint: disable=too-many-public-methods
+    IsolatedAsyncioTestCase,
+):
+    """The unittests for DashScope Realtime TTS model."""
+
+    def setUp(self) -> None:
+        self.mock_modules = self._create_mock_dashscope_modules()
+        self.mock_client = self._create_mock_tts_client()
+        mock_tts_class = Mock(return_value=self.mock_client)
+        self.mock_modules[
+            "dashscope.audio.qwen_tts_realtime"
+        ].QwenTtsRealtime = mock_tts_class
+
+    @staticmethod
+    def _create_mock_dashscope_modules() -> dict:
+        mock_qwen_tts_realtime = MagicMock()
+        mock_qwen_tts_realtime.QwenTtsRealtime = Mock
+        mock_qwen_tts_realtime.QwenTtsRealtimeCallback = Mock
+
+        mock_audio = MagicMock()
+        mock_audio.qwen_tts_realtime = mock_qwen_tts_realtime
+
+        mock_dashscope = MagicMock()
+        mock_dashscope.api_key = None
+        mock_dashscope.audio = mock_audio
+
+        return {
+            "dashscope": mock_dashscope,
+            "dashscope.audio": mock_audio,
+            "dashscope.audio.qwen_tts_realtime": mock_qwen_tts_realtime,
+        }
+
+    @staticmethod
+    def _create_mock_tts_client() -> Mock:
+        client = Mock()
+        client.connect = Mock()
+        client.close = Mock()
+        client.finish = Mock()
+        client.commit = Mock()
+        client.update_session = Mock()
+        client.append_text = Mock()
+        return client
+
+    def _make_model(self, **kwargs: Any) -> DashScopeRealtimeTTSModel:
+        defaults: dict[str, Any] = {
+            "credential": DashScopeCredential(api_key="test"),
+            "model": "qwen3-tts-flash-realtime",
+            "stream": True,
+            "max_retries": 1,
+            "retry_delay": 0.0,
+        }
+        defaults.update(kwargs)
+        return DashScopeRealtimeTTSModel(**defaults)
+
+    def _mock_synthesize_callback(self, model: Any) -> None:
+        """Set up callback mocks so ``synthesize()`` doesn't block."""
+        model._callback.finish_event = Mock()
+        model._callback.finish_event.wait = Mock()
+        model._callback.has_audio_data = Mock(return_value=True)
+        model._callback.get_audio_response = Mock(
+            return_value=TTSResponse(content=None),
+        )
+
+    # -- connect / close --
+
+    async def test_async_context_manager(self) -> None:
+        """``async with`` triggers connect on enter and close on exit."""
+        with patch.dict("sys.modules", self.mock_modules):
+            model = self._make_model()
+            async with model:
+                self.assertTrue(model._connected)
+            self.assertFalse(model._connected)
+
+    # -- push --
+
+    async def test_push_incremental_deltas(self) -> None:
+        """Consecutive deltas are each forwarded verbatim."""
+        with patch.dict("sys.modules", self.mock_modules):
+            async with self._make_model() as model:
+                await model.push("Hello")
+                await model.push(" world")
+
+                self.assertEqual(
+                    self.mock_client.append_text.call_count,
+                    2,
+                )
+                self.mock_client.append_text.assert_any_call("Hello")
+                self.mock_client.append_text.assert_any_call(" world")
+                self.assertEqual(model._accumulated_text, "Hello world")
+
+    async def test_push_returns_audio_when_available(self) -> None:
+        """push() returns audio data from the callback when available."""
+        mock_audio_data = base64.b64encode(b"PCMDATA").decode("ascii")
+
+        with patch.dict("sys.modules", self.mock_modules):
+            async with self._make_model() as model:
+                model._callback.get_audio_response = Mock(
+                    return_value=TTSResponse(
+                        content=MagicMock(
+                            source=MagicMock(
+                                data=mock_audio_data,
+                                media_type=_MEDIA_TYPE,
+                            ),
+                        ),
+                    ),
+                )
+                res = await model.push("Hello")
+
+                self.assertIsNotNone(res.content)
+                self.assertEqual(res.content.source.data, mock_audio_data)
+
+    async def test_push_cold_start_buffers_across_deltas(self) -> None:
+        """Multiple small deltas are buffered until cold_start_length is
+        met, then flushed as a single ``append_text`` call."""
+        with patch.dict("sys.modules", self.mock_modules):
+            async with self._make_model(cold_start_length=10) as model:
+                await model.push("Hi")
+                await model.push(" there")
+                self.mock_client.append_text.assert_not_called()
+                self.assertFalse(model._cold_start_done)
+
+                await model.push(" friend!")
+                self.mock_client.append_text.assert_called_once_with(
+                    "Hi there friend!",
+                )
+                self.assertTrue(model._cold_start_done)
+
+    async def test_push_after_cold_start_forwards_directly(self) -> None:
+        """Once cold start is done, subsequent deltas bypass the buffer."""
+        with patch.dict("sys.modules", self.mock_modules):
+            async with self._make_model(cold_start_length=3) as model:
+                await model.push("Hello")
+                self.mock_client.append_text.assert_called_with("Hello")
+
+                await model.push(" world")
+                self.mock_client.append_text.assert_called_with(" world")
+                self.assertEqual(
+                    self.mock_client.append_text.call_count,
+                    2,
+                )
+
+    async def test_push_cold_start_words_buffers(self) -> None:
+        """Deltas below cold_start_words are buffered."""
+        with patch.dict("sys.modules", self.mock_modules):
+            async with self._make_model(cold_start_words=3) as model:
+                await model.push("Hello")
+                await model.push(" world")
+
+                self.mock_client.append_text.assert_not_called()
+                self.assertFalse(model._cold_start_done)
+
+    # -- synthesize --
+
+    async def test_synthesize_commits_and_finishes(self) -> None:
+        """synthesize(text=...) appends text, commits, and finishes."""
+        with patch.dict("sys.modules", self.mock_modules):
+            async with self._make_model() as model:
+                self._mock_synthesize_callback(model)
+
+                await model.synthesize(text="Hello")
+
+                self.mock_client.append_text.assert_called_once_with("Hello")
+                self.mock_client.commit.assert_called_once()
+                self.mock_client.finish.assert_called_once()
+
+    async def test_synthesize_appends_extra_text(self) -> None:
+        """synthesize(text=...) after push appends the extra text."""
+        with patch.dict("sys.modules", self.mock_modules):
+            async with self._make_model() as model:
+                model._callback.get_audio_response = Mock(
+                    return_value=TTSResponse(content=None),
+                )
+                await model.push("Hello")
+                self.mock_client.append_text.reset_mock()
+
+                self._mock_synthesize_callback(model)
+                await model.synthesize(text=" world")
+
+                self.mock_client.append_text.assert_called_once_with(
+                    " world",
+                )
+                self.mock_client.commit.assert_called_once()
+
+    async def test_synthesize_no_text_drain(self) -> None:
+        """synthesize(None) after push commits without extra append."""
+        with patch.dict("sys.modules", self.mock_modules):
+            async with self._make_model() as model:
+                model._callback.get_audio_response = Mock(
+                    return_value=TTSResponse(content=None),
+                )
+                await model.push("Hello")
+                self.mock_client.append_text.reset_mock()
+
+                self._mock_synthesize_callback(model)
+                await model.synthesize()
+
+                self.mock_client.append_text.assert_not_called()
+                self.mock_client.commit.assert_called_once()
+
+    async def test_synthesize_stream_returns_generator(self) -> None:
+        """stream=True returns an async generator with is_last."""
+        with patch.dict("sys.modules", self.mock_modules):
+            async with self._make_model(stream=True) as model:
+                self._mock_synthesize_callback(model)
+
+                async def mock_chunks() -> AsyncGenerator[TTSResponse, None]:
+                    yield TTSResponse(content=None, is_last=True)
+
+                model._callback.get_audio_chunks = mock_chunks
+
+                gen = await model.synthesize(text="Hello")
+                chunks = [c async for c in gen]
+
+                self.assertTrue(len(chunks) >= 1)
+                self.assertTrue(chunks[-1].is_last)
+
+    async def test_synthesize_flushes_cold_start_buffer(self) -> None:
+        """If cold start was never met during push, synthesize flushes the
+        buffered text before committing."""
+        with patch.dict("sys.modules", self.mock_modules):
+            async with self._make_model(cold_start_length=100) as model:
+                await model.push("Hi")
+                await model.push(" there")
+                self.mock_client.append_text.assert_not_called()
+
+                self._mock_synthesize_callback(model)
+                await model.synthesize()
+
+                self.mock_client.append_text.assert_called_once_with(
+                    "Hi there",
+                )
+                self.mock_client.commit.assert_called_once()
+
+    async def test_synthesize_no_audio_raises_after_retries(self) -> None:
+        """RuntimeError after max_retries with no audio received."""
+        with patch.dict("sys.modules", self.mock_modules):
+            async with self._make_model(
+                max_retries=1,
+                retry_delay=0.0,
+            ) as model:
+                model._callback.finish_event = Mock()
+                model._callback.finish_event.wait = Mock()
+                model._callback.has_audio_data = Mock(return_value=False)
+
+                with self.assertRaises(RuntimeError):
+                    await model.synthesize(text="Hello")
+
+    # -- callback --
+
+    async def test_get_audio_chunks_prepends_header_without_prior_push(
+        self,
+    ) -> None:
+        """get_audio_chunks() prepends a WAV header when push() has not
+        yet consumed any bytes (_consumed == 0)."""
+        with patch.dict("sys.modules", self.mock_modules):
+            from agentscope.tts._dashscope._realtime_model import (
+                _make_callback_class,
+            )
+
+            callback_cls = _make_callback_class()
+            cb = callback_cls()
+
+            audio_b64 = base64.b64encode(b"ALLPCM").decode()
+            cb.on_event({"type": "response.audio.delta", "delta": audio_b64})
+            cb.on_event({"type": "session.finished"})
+
+            chunks = [c async for c in cb.get_audio_chunks()]
+            raw_payloads = [
+                base64.b64decode(c.content.source.data)
+                for c in chunks
+                if c.content is not None
+            ]
+
+            self.assertTrue(len(raw_payloads) > 0)
+            self.assertTrue(raw_payloads[0].startswith(b"RIFF"))
+            self.assertTrue(raw_payloads[0].endswith(b"ALLPCM"))
+
+    async def test_get_audio_chunks_skips_header_after_partial_push(
+        self,
+    ) -> None:
+        """get_audio_chunks() does NOT prepend a second WAV header when
+        push() already consumed and sent the first chunk with a header
+        (_consumed > 0)."""
+        with patch.dict("sys.modules", self.mock_modules):
+            from agentscope.tts._dashscope._realtime_model import (
+                _make_callback_class,
+            )
+
+            callback_cls = _make_callback_class()
+            cb = callback_cls()
+
+            # Simulate push() consuming the first chunk (with WAV header)
+            first_b64 = base64.b64encode(b"FIRSTPCM").decode()
+            cb.on_event(
+                {"type": "response.audio.delta", "delta": first_b64},
+            )
+            first_resp = cb.get_audio_response(block=False)
+            self.assertIsNotNone(first_resp.content)
+            self.assertGreater(cb._consumed, 0)
+
+            # More data arrives and session finishes
+            more_b64 = base64.b64encode(b"MOREPCM").decode()
+            cb.on_event(
+                {"type": "response.audio.delta", "delta": more_b64},
+            )
+            cb.on_event({"type": "session.finished"})
+
+            chunks = [c async for c in cb.get_audio_chunks()]
+            raw_payloads = [
+                base64.b64decode(c.content.source.data)
+                for c in chunks
+                if c.content is not None
+            ]
+
+            self.assertTrue(len(raw_payloads) > 0)
+            # No second RIFF header should appear mid-stream
+            self.assertFalse(raw_payloads[0].startswith(b"RIFF"))
+            self.assertEqual(raw_payloads[0], b"MOREPCM")
+
+    async def test_get_audio_response_includes_header_without_prior_push(
+        self,
+    ) -> None:
+        """get_audio_response() prepends a WAV header when no data has been
+        consumed yet (_consumed == 0)."""
+        with patch.dict("sys.modules", self.mock_modules):
+            from agentscope.tts._dashscope._realtime_model import (
+                _make_callback_class,
+            )
+
+            callback_cls = _make_callback_class()
+            cb = callback_cls()
+
+            audio_b64 = base64.b64encode(b"ALLPCM").decode()
+            cb.on_event({"type": "response.audio.delta", "delta": audio_b64})
+            cb.on_event({"type": "session.finished"})
+
+            resp = cb.get_audio_response(block=True)
+            raw = base64.b64decode(resp.content.source.data)
+
+            self.assertTrue(raw.startswith(b"RIFF"))
+            self.assertTrue(raw.endswith(b"ALLPCM"))
+
+    async def test_get_audio_response_skips_header_after_partial_push(
+        self,
+    ) -> None:
+        """get_audio_response() does NOT prepend a second WAV header when
+        push() already consumed and sent the first chunk with a header
+        (_consumed > 0)."""
+        with patch.dict("sys.modules", self.mock_modules):
+            from agentscope.tts._dashscope._realtime_model import (
+                _make_callback_class,
+            )
+
+            callback_cls = _make_callback_class()
+            cb = callback_cls()
+
+            first_b64 = base64.b64encode(b"FIRSTPCM").decode()
+            cb.on_event(
+                {"type": "response.audio.delta", "delta": first_b64},
+            )
+            first_resp = cb.get_audio_response(block=False)
+            self.assertIsNotNone(first_resp.content)
+            self.assertGreater(cb._consumed, 0)
+
+            more_b64 = base64.b64encode(b"MOREPCM").decode()
+            cb.on_event(
+                {"type": "response.audio.delta", "delta": more_b64},
+            )
+            cb.on_event({"type": "session.finished"})
+
+            resp = cb.get_audio_response(block=True)
+            raw = base64.b64decode(resp.content.source.data)
+
+            self.assertFalse(raw.startswith(b"RIFF"))
+            self.assertEqual(raw, b"MOREPCM")
+
+
+# ---------------------------------------------------------------------------
+# DashScopeCosyVoiceTTSModel — realtime push / synthesize lifecycle
+# ---------------------------------------------------------------------------
+
+
+# pylint: disable=too-many-public-methods
+class TestDashScopeCosyVoiceRealtimeMode(
+    IsolatedAsyncioTestCase,
+):
+    """Unit tests for CosyVoice realtime mode."""
+
+    def setUp(self) -> None:
+        self.mock_modules = self._create_mock_cosyvoice_modules()
+        self.mock_synthesizer = self._create_mock_synthesizer()
+        self.mock_modules["dashscope.audio.tts_v2"].SpeechSynthesizer = Mock(
+            return_value=self.mock_synthesizer,
+        )
+
+    @staticmethod
+    def _create_mock_cosyvoice_modules() -> dict:
+        mock_result_callback = Mock
+        mock_audio_format = MagicMock()
+        mock_audio_format.PCM_24000HZ_MONO_16BIT = "pcm_24000hz_mono_16bit"
+
+        mock_tts_v2 = MagicMock()
+        mock_tts_v2.ResultCallback = mock_result_callback
+        mock_tts_v2.AudioFormat = mock_audio_format
+        mock_tts_v2.SpeechSynthesizer = Mock
+
+        mock_audio = MagicMock()
+        mock_audio.tts_v2 = mock_tts_v2
+
+        mock_dashscope = MagicMock()
+        mock_dashscope.api_key = None
+        mock_dashscope.audio = mock_audio
+
+        return {
+            "dashscope": mock_dashscope,
+            "dashscope.audio": mock_audio,
+            "dashscope.audio.tts_v2": mock_tts_v2,
+        }
+
+    @staticmethod
+    def _create_mock_synthesizer() -> Mock:
+        synth = Mock()
+        synth.streaming_call = Mock()
+        synth.streaming_complete = Mock()
+        synth.close = Mock()
+        return synth
+
+    def _make_model(
+        self,
+        **kwargs: Any,
+    ) -> DashScopeCosyVoiceTTSModel:
+        defaults: dict[str, Any] = {
+            "credential": DashScopeCredential(api_key="test"),
+            "model": "cosyvoice-v3-plus",
+            "parameters": DashScopeCosyVoiceTTSModel.Parameters(
+                voice="longanhuan",
+                realtime=True,
+            ),
+            "stream": True,
+            "max_retries": 1,
+            "retry_delay": 0.0,
+        }
+        defaults.update(kwargs)
+        return DashScopeCosyVoiceTTSModel(**defaults)
+
+    def _mock_synthesize_callback(self, model: Any) -> None:
+        """Set up callback mocks so synthesize() doesn't block."""
+        model._callback.finish_event = Mock()
+        model._callback.finish_event.wait = Mock(return_value=True)
+        model._callback.has_audio_data = Mock(return_value=True)
+        model._callback.get_audio_response = Mock(
+            return_value=TTSResponse(content=None),
+        )
+
+    # -- connect / close --
+
+    async def test_async_context_manager(self) -> None:
+        """async with triggers connect on enter and close on exit."""
+        with patch.dict("sys.modules", self.mock_modules):
+            model = self._make_model()
+            async with model:
+                self.assertTrue(model._connected)
+            self.assertFalse(model._connected)
+
+    async def test_async_context_skips_connect_when_not_realtime(self) -> None:
+        """async with does not connect when the realtime parameter is off."""
+        with patch.dict("sys.modules", self.mock_modules):
+            model = self._make_model(
+                parameters=DashScopeCosyVoiceTTSModel.Parameters(
+                    voice="longanhuan",
+                    realtime=False,
+                ),
+            )
+            async with model:
+                self.assertFalse(model._connected)
+            self.mock_modules[
+                "dashscope.audio.tts_v2"
+            ].SpeechSynthesizer.assert_not_called()
+
+    # -- push --
+
+    async def test_push_incremental_deltas(self) -> None:
+        """Consecutive deltas are each forwarded via streaming_call."""
+        with patch.dict("sys.modules", self.mock_modules):
+            async with self._make_model() as model:
+                model._callback.get_audio_response = Mock(
+                    return_value=TTSResponse(content=None),
+                )
+                await model.push("Hello")
+                await model.push(" world")
+
+                self.assertEqual(
+                    self.mock_synthesizer.streaming_call.call_count,
+                    2,
+                )
+                self.mock_synthesizer.streaming_call.assert_any_call("Hello")
+                self.mock_synthesizer.streaming_call.assert_any_call(" world")
+
+    async def test_push_returns_audio_when_available(self) -> None:
+        """push() returns audio data from the callback when available."""
+        mock_audio_data = base64.b64encode(b"PCMDATA").decode("ascii")
+
+        with patch.dict("sys.modules", self.mock_modules):
+            async with self._make_model() as model:
+                model._callback.get_audio_response = Mock(
+                    return_value=TTSResponse(
+                        content=MagicMock(
+                            source=MagicMock(
+                                data=mock_audio_data,
+                                media_type=_MEDIA_TYPE,
+                            ),
+                        ),
+                    ),
+                )
+                res = await model.push("Hello")
+
+                self.assertIsNotNone(res.content)
+                self.assertEqual(res.content.source.data, mock_audio_data)
+
+    async def test_push_cold_start_buffers_across_deltas(self) -> None:
+        """Multiple small deltas are buffered until cold_start_length is
+        met, then flushed as a single streaming_call."""
+        with patch.dict("sys.modules", self.mock_modules):
+            async with self._make_model(cold_start_length=10) as model:
+                model._callback.get_audio_response = Mock(
+                    return_value=TTSResponse(content=None),
+                )
+                await model.push("Hi")
+                await model.push(" there")
+                self.mock_synthesizer.streaming_call.assert_not_called()
+                self.assertFalse(model._cold_start_done)
+
+                await model.push(" friend!")
+                self.mock_synthesizer.streaming_call.assert_called_once_with(
+                    "Hi there friend!",
+                )
+                self.assertTrue(model._cold_start_done)
+
+    async def test_push_after_cold_start_forwards_directly(self) -> None:
+        """Once cold start is done, subsequent deltas bypass the buffer."""
+        with patch.dict("sys.modules", self.mock_modules):
+            async with self._make_model(cold_start_length=3) as model:
+                model._callback.get_audio_response = Mock(
+                    return_value=TTSResponse(content=None),
+                )
+                await model.push("Hello")
+                self.mock_synthesizer.streaming_call.assert_called_with(
+                    "Hello",
+                )
+
+                await model.push(" world")
+                self.mock_synthesizer.streaming_call.assert_called_with(
+                    " world",
+                )
+                self.assertEqual(
+                    self.mock_synthesizer.streaming_call.call_count,
+                    2,
+                )
+
+    async def test_push_cold_start_words_buffers(self) -> None:
+        """Deltas below cold_start_words are buffered."""
+        with patch.dict("sys.modules", self.mock_modules):
+            async with self._make_model(cold_start_words=3) as model:
+                model._callback.get_audio_response = Mock(
+                    return_value=TTSResponse(content=None),
+                )
+                await model.push("Hello")
+                await model.push(" world")
+
+                self.mock_synthesizer.streaming_call.assert_not_called()
+                self.assertFalse(model._cold_start_done)
+
+    async def test_push_exception_returns_empty(self) -> None:
+        """push() returns empty response if streaming_call raises."""
+        with patch.dict("sys.modules", self.mock_modules):
+            async with self._make_model() as model:
+                self.mock_synthesizer.streaming_call.side_effect = Exception(
+                    "connection error",
+                )
+                res = await model.push("Hello")
+
+                self.assertIsNone(res.content)
+
+    # -- synthesize --
+
+    async def test_synthesize_calls_streaming_complete(self) -> None:
+        """synthesize() calls streaming_call and streaming_complete."""
+        with patch.dict("sys.modules", self.mock_modules):
+            async with self._make_model() as model:
+                self._mock_synthesize_callback(model)
+
+                await model.synthesize(text="Hello")
+
+                self.mock_synthesizer.streaming_call.assert_called_once_with(
+                    "Hello",
+                )
+                self.mock_synthesizer.streaming_complete.assert_called_once()
+
+    async def test_synthesize_appends_extra_text(self) -> None:
+        """synthesize(text=...) after push appends the extra text."""
+        with patch.dict("sys.modules", self.mock_modules):
+            async with self._make_model() as model:
+                model._callback.get_audio_response = Mock(
+                    return_value=TTSResponse(content=None),
+                )
+                await model.push("Hello")
+                self.mock_synthesizer.streaming_call.reset_mock()
+
+                self._mock_synthesize_callback(model)
+                await model.synthesize(text=" world")
+
+                self.mock_synthesizer.streaming_call.assert_called_once_with(
+                    " world",
+                )
+                self.mock_synthesizer.streaming_complete.assert_called_once()
+
+    async def test_synthesize_no_text_drain(self) -> None:
+        """synthesize(None) after push calls streaming_complete without
+        extra streaming_call."""
+        with patch.dict("sys.modules", self.mock_modules):
+            async with self._make_model() as model:
+                model._callback.get_audio_response = Mock(
+                    return_value=TTSResponse(content=None),
+                )
+                await model.push("Hello")
+                self.mock_synthesizer.streaming_call.reset_mock()
+
+                self._mock_synthesize_callback(model)
+                await model.synthesize()
+
+                self.mock_synthesizer.streaming_call.assert_not_called()
+                self.mock_synthesizer.streaming_complete.assert_called_once()
+
+    async def test_synthesize_stream_returns_generator(self) -> None:
+        """stream=True returns an async generator with is_last."""
+        with patch.dict("sys.modules", self.mock_modules):
+            async with self._make_model(stream=True) as model:
+                self._mock_synthesize_callback(model)
+
+                async def mock_chunks() -> AsyncGenerator[TTSResponse, None]:
+                    yield TTSResponse(content=None, is_last=True)
+
+                model._callback.get_audio_chunks = mock_chunks
+
+                gen = await model.synthesize(text="Hello")
+                chunks = [c async for c in gen]
+
+                self.assertTrue(len(chunks) >= 1)
+                self.assertTrue(chunks[-1].is_last)
+
+    async def test_synthesize_non_stream_returns_single(self) -> None:
+        """stream=False returns a single TTSResponse."""
+        mock_audio_data = base64.b64encode(b"PCMDATA").decode("ascii")
+
+        with patch.dict("sys.modules", self.mock_modules):
+            async with self._make_model(stream=False) as model:
+                self._mock_synthesize_callback(model)
+                model._callback.get_audio_response = Mock(
+                    return_value=TTSResponse(
+                        content=MagicMock(
+                            source=MagicMock(
+                                data=mock_audio_data,
+                                media_type=_MEDIA_TYPE,
+                            ),
+                        ),
+                    ),
+                )
+
+                res = await model.synthesize(text="Hello")
+
+                self.assertIsInstance(res, TTSResponse)
+                self.assertIsNotNone(res.content)
+
+    async def test_synthesize_flushes_cold_start_buffer(self) -> None:
+        """If cold start was never met during push, synthesize flushes the
+        buffered text before calling streaming_complete."""
+        with patch.dict("sys.modules", self.mock_modules):
+            async with self._make_model(cold_start_length=100) as model:
+                model._callback.get_audio_response = Mock(
+                    return_value=TTSResponse(content=None),
+                )
+                await model.push("Hi")
+                await model.push(" there")
+                self.mock_synthesizer.streaming_call.assert_not_called()
+
+                self._mock_synthesize_callback(model)
+                await model.synthesize()
+
+                self.mock_synthesizer.streaming_call.assert_called_once_with(
+                    "Hi there",
+                )
+                self.mock_synthesizer.streaming_complete.assert_called_once()
+
+    async def test_synthesize_empty_text_short_circuits(self) -> None:
+        """synthesize() with no accumulated text returns empty."""
+        with patch.dict("sys.modules", self.mock_modules):
+            async with self._make_model(stream=True) as model:
+                gen = await model.synthesize()
+                chunks = [c async for c in gen]
+
+                self.assertEqual(len(chunks), 1)
+                self.assertIsNone(chunks[0].content)
+                self.assertTrue(chunks[0].is_last)
+                self.mock_synthesizer.streaming_complete.assert_not_called()
+
+    async def test_synthesize_no_audio_raises_after_retries(self) -> None:
+        """RuntimeError after max_retries with no audio received."""
+        with patch.dict("sys.modules", self.mock_modules):
+            async with self._make_model(
+                max_retries=1,
+                retry_delay=0.0,
+            ) as model:
+                model._callback.finish_event = Mock()
+                model._callback.finish_event.wait = Mock(return_value=True)
+                model._callback.has_audio_data = Mock(return_value=False)
+
+                with self.assertRaises(RuntimeError):
+                    await model.synthesize(text="Hello")
+
+    async def test_synthesize_timeout_raises(self) -> None:
+        """RuntimeError when finish_event.wait times out."""
+        with patch.dict("sys.modules", self.mock_modules):
+            async with self._make_model(
+                max_retries=1,
+                retry_delay=0.0,
+            ) as model:
+                model._callback.finish_event = Mock()
+                model._callback.finish_event.wait = Mock(return_value=False)
+
+                with self.assertRaises(RuntimeError) as ctx:
+                    await model.synthesize(text="Hello")
+
+                self.assertIn("timed out", str(ctx.exception))
+
+    # -- callback --
+
+    async def test_callback_on_complete_sets_finish_event(self) -> None:
+        """on_complete() correctly sets finish_event and chunk_event."""
+        with patch.dict("sys.modules", self.mock_modules):
+            from agentscope.tts._dashscope._cosyvoice_utils import (
+                _make_cosyvoice_callback_class,
+            )
+
+            callback_cls = _make_cosyvoice_callback_class()
+            cb = callback_cls()
+
+            self.assertFalse(cb.finish_event.is_set())
+            self.assertFalse(cb.chunk_event.is_set())
+
+            cb.on_complete()
+
+            self.assertTrue(cb.finish_event.is_set())
+            self.assertTrue(cb.chunk_event.is_set())
+
+    async def test_callback_on_data_accumulates(self) -> None:
+        """on_data() accumulates PCM bytes and signals chunk_event."""
+        with patch.dict("sys.modules", self.mock_modules):
+            from agentscope.tts._dashscope._cosyvoice_utils import (
+                _make_cosyvoice_callback_class,
+            )
+
+            callback_cls = _make_cosyvoice_callback_class()
+            cb = callback_cls()
+
+            cb.on_data(b"AAAA")
+            cb.on_data(b"BBBB")
+
+            self.assertEqual(bytes(cb._pcm_bytes), b"AAAABBBB")
+            self.assertTrue(cb.chunk_event.is_set())
+
+    async def test_callback_take_delta_incremental(self) -> None:
+        """_take_delta() returns only new bytes since last call."""
+        with patch.dict("sys.modules", self.mock_modules):
+            from agentscope.tts._dashscope._cosyvoice_utils import (
+                _make_cosyvoice_callback_class,
+            )
+
+            callback_cls = _make_cosyvoice_callback_class()
+            cb = callback_cls()
+
+            cb.on_data(b"AAAA")
+            delta1 = cb._take_delta(header=False)
+            self.assertEqual(delta1, b"AAAA")
+
+            cb.on_data(b"BBBB")
+            delta2 = cb._take_delta(header=False)
+            self.assertEqual(delta2, b"BBBB")
+
+            delta3 = cb._take_delta(header=False)
+            self.assertIsNone(delta3)
+
+    async def test_callback_take_delta_with_header(self) -> None:
+        """_take_delta(header=True) prepends WAV header to first chunk."""
+        with patch.dict("sys.modules", self.mock_modules):
+            from agentscope.tts._dashscope._cosyvoice_utils import (
+                _make_cosyvoice_callback_class,
+            )
+
+            callback_cls = _make_cosyvoice_callback_class()
+            cb = callback_cls()
+
+            cb.on_data(b"PCMPCM")
+            delta = cb._take_delta(header=True)
+
+            self.assertTrue(delta.startswith(b"RIFF"))
+            self.assertIn(b"WAVE", delta[:12])
+            self.assertTrue(delta.endswith(b"PCMPCM"))
+
+    async def test_get_audio_chunks_prepends_header_without_prior_push(
+        self,
+    ) -> None:
+        """get_audio_chunks() prepends a WAV header when push() has not
+        yet consumed any bytes (_consumed == 0)."""
+        with patch.dict("sys.modules", self.mock_modules):
+            from agentscope.tts._dashscope._cosyvoice_utils import (
+                _make_cosyvoice_callback_class,
+            )
+
+            callback_cls = _make_cosyvoice_callback_class()
+            cb = callback_cls()
+
+            cb.on_data(b"ALLPCM")
+            cb.on_complete()
+
+            chunks = [c async for c in cb.get_audio_chunks()]
+            raw_payloads = [
+                base64.b64decode(c.content.source.data)
+                for c in chunks
+                if c.content is not None
+            ]
+
+            self.assertTrue(len(raw_payloads) > 0)
+            self.assertTrue(raw_payloads[0].startswith(b"RIFF"))
+            self.assertTrue(raw_payloads[0].endswith(b"ALLPCM"))
+
+    async def test_get_audio_chunks_skips_header_after_partial_push(
+        self,
+    ) -> None:
+        """get_audio_chunks() does NOT prepend a second WAV header when
+        push() already consumed and sent the first chunk with a header
+        (_consumed > 0)."""
+        with patch.dict("sys.modules", self.mock_modules):
+            from agentscope.tts._dashscope._cosyvoice_utils import (
+                _make_cosyvoice_callback_class,
+            )
+
+            callback_cls = _make_cosyvoice_callback_class()
+            cb = callback_cls()
+
+            # Simulate push() consuming the first chunk (with WAV header)
+            cb.on_data(b"FIRSTPCM")
+            first_resp = cb.get_audio_response(block=False)
+            self.assertIsNotNone(first_resp.content)
+            self.assertGreater(cb._consumed, 0)
+
+            # More data arrives and synthesis completes
+            cb.on_data(b"MOREPCM")
+            cb.on_complete()
+
+            chunks = [c async for c in cb.get_audio_chunks()]
+            raw_payloads = [
+                base64.b64decode(c.content.source.data)
+                for c in chunks
+                if c.content is not None
+            ]
+
+            self.assertTrue(len(raw_payloads) > 0)
+            # No second RIFF header should appear mid-stream
+            self.assertFalse(raw_payloads[0].startswith(b"RIFF"))
+            self.assertEqual(raw_payloads[0], b"MOREPCM")
+
+    async def test_get_audio_response_includes_header_without_prior_push(
+        self,
+    ) -> None:
+        """get_audio_response() prepends a WAV header when no data has been
+        consumed yet (_consumed == 0)."""
+        with patch.dict("sys.modules", self.mock_modules):
+            from agentscope.tts._dashscope._cosyvoice_utils import (
+                _make_cosyvoice_callback_class,
+            )
+
+            callback_cls = _make_cosyvoice_callback_class()
+            cb = callback_cls()
+
+            cb.on_data(b"ALLPCM")
+            cb.on_complete()
+
+            resp = cb.get_audio_response(block=True)
+            raw = base64.b64decode(resp.content.source.data)
+
+            self.assertTrue(raw.startswith(b"RIFF"))
+            self.assertTrue(raw.endswith(b"ALLPCM"))
+
+    async def test_get_audio_response_skips_header_after_partial_push(
+        self,
+    ) -> None:
+        """get_audio_response() does NOT prepend a second WAV header when
+        push() already consumed and sent the first chunk with a header
+        (_consumed > 0)."""
+        with patch.dict("sys.modules", self.mock_modules):
+            from agentscope.tts._dashscope._cosyvoice_utils import (
+                _make_cosyvoice_callback_class,
+            )
+
+            callback_cls = _make_cosyvoice_callback_class()
+            cb = callback_cls()
+
+            cb.on_data(b"FIRSTPCM")
+            first_resp = cb.get_audio_response(block=False)
+            self.assertIsNotNone(first_resp.content)
+            self.assertGreater(cb._consumed, 0)
+
+            cb.on_data(b"MOREPCM")
+            cb.on_complete()
+
+            resp = cb.get_audio_response(block=True)
+            raw = base64.b64decode(resp.content.source.data)
+
+            self.assertFalse(raw.startswith(b"RIFF"))
+            self.assertEqual(raw, b"MOREPCM")
+
+    async def test_callback_reset(self) -> None:
+        """reset() clears all state."""
+        with patch.dict("sys.modules", self.mock_modules):
+            from agentscope.tts._dashscope._cosyvoice_utils import (
+                _make_cosyvoice_callback_class,
+            )
+
+            callback_cls = _make_cosyvoice_callback_class()
+            cb = callback_cls()
+
+            cb.on_data(b"AAAA")
+            cb.on_complete()
+            cb.reset()
+
+            self.assertFalse(cb.finish_event.is_set())
+            self.assertFalse(cb.chunk_event.is_set())
+            self.assertEqual(bytes(cb._pcm_bytes), b"")
+            self.assertEqual(cb._consumed, 0)
+
+    # -- reconnect --
+
+    async def test_reconnect_recreates_synthesizer(self) -> None:
+        """_reconnect() closes old synthesizer and creates a new one."""
+        with patch.dict("sys.modules", self.mock_modules):
+            model = self._make_model()
+            await model.connect()
+            old_callback = model._callback
+
+            await model._reconnect()
+
+            self.mock_synthesizer.close.assert_called_once()
+            self.assertTrue(model._connected)
+            self.assertIsNot(model._callback, old_callback)
diff --git a/tests/tts_middleware_test.py b/tests/tts_middleware_test.py
new file mode 100644
index 0000000..0b94be3
--- /dev/null
+++ b/tests/tts_middleware_test.py
@@ -0,0 +1,426 @@
+# -*- coding: utf-8 -*-
+"""Unit tests for TTSMiddleware."""
+import base64
+from typing import Any, AsyncGenerator
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import AsyncMock, MagicMock
+
+from agentscope import set_id_factory
+from agentscope.event import (
+    DataBlockDeltaEvent,
+    DataBlockEndEvent,
+    DataBlockStartEvent,
+    TextBlockDeltaEvent,
+    TextBlockEndEvent,
+)
+from agentscope.message import Base64Source, DataBlock
+from agentscope.middleware import TTSMiddleware
+from agentscope.tts import TTSModelBase, TTSResponse
+
+_EXCLUDE = {"id", "created_at", "metadata"}
+
+
+def _dump(evt: Any) -> dict:
+    """Dump an event to a dict excluding auto-generated fields."""
+    return evt.model_dump(exclude=_EXCLUDE)
+
+
+def _make_tts_response(
+    data: str,
+    media_type: str = "audio/wav",
+) -> TTSResponse:
+    return TTSResponse(
+        content=DataBlock(
+            source=Base64Source(data=data, media_type=media_type),
+        ),
+    )
+
+
+def _make_agent_stub(
+    reply_id: str = "reply-1",
+    name: str = "agent",
+) -> MagicMock:
+    agent = MagicMock()
+    agent.name = name
+    agent.state.reply_id = reply_id
+    return agent
+
+
+class TestTTSMiddlewareNonRealtime(IsolatedAsyncioTestCase):
+    """Tests for non-realtime (non-streaming-input) TTS path."""
+
+    async def test_synthesize_on_text_block_end(self) -> None:
+        """After TextBlockEnd, synthesize() is called with accumulated text
+        and DATA_BLOCK_START + DATA_BLOCK_DELTA + DATA_BLOCK_END are emitted.
+        """
+        audio_b64 = base64.b64encode(b"\x00\x01\x02").decode()
+
+        tts = MagicMock(spec=TTSModelBase)
+        tts.realtime = False
+        tts.__aenter__ = AsyncMock(return_value=tts)
+        tts.__aexit__ = AsyncMock(return_value=None)
+        tts.synthesize = AsyncMock(
+            return_value=_make_tts_response(audio_b64),
+        )
+
+        middleware = TTSMiddleware(tts_model=tts)
+        agent = _make_agent_stub()
+
+        upstream_events = [
+            TextBlockDeltaEvent(
+                reply_id="reply-1",
+                block_id="blk-1",
+                delta="Hello ",
+            ),
+            TextBlockDeltaEvent(
+                reply_id="reply-1",
+                block_id="blk-1",
+                delta="world",
+            ),
+            TextBlockEndEvent(reply_id="reply-1", block_id="blk-1"),
+        ]
+
+        async def next_handler(**_kwargs: Any) -> AsyncGenerator:
+            for evt in upstream_events:
+                yield evt
+
+        emitted = []
+        async for evt in middleware.on_reply(agent, {}, next_handler):
+            emitted.append(evt)
+
+        # Upstream events are passed through
+        self.assertEqual(
+            [_dump(e) for e in emitted[:3]],
+            [_dump(e) for e in upstream_events],
+        )
+
+        # After TextBlockEnd: START + DELTA + END
+        block_id = emitted[3].block_id
+        self.assertEqual(
+            [_dump(e) for e in emitted[3:]],
+            [
+                {
+                    "type": "DATA_BLOCK_START",
+                    "reply_id": "reply-1",
+                    "block_id": block_id,
+                    "media_type": "audio/wav",
+                },
+                {
+                    "type": "DATA_BLOCK_DELTA",
+                    "reply_id": "reply-1",
+                    "block_id": block_id,
+                    "data": audio_b64,
+                    "media_type": "audio/wav",
+                },
+                {
+                    "type": "DATA_BLOCK_END",
+                    "reply_id": "reply-1",
+                    "block_id": block_id,
+                },
+            ],
+        )
+
+        # synthesize was called with the full text
+        tts.synthesize.assert_called_once_with("Hello world")
+
+    async def test_empty_text_skips_synthesize(self) -> None:
+        """When accumulated text is whitespace-only, synthesize is not called
+        and no DATA_BLOCK events are emitted."""
+        tts = MagicMock(spec=TTSModelBase)
+        tts.realtime = False
+        tts.__aenter__ = AsyncMock(return_value=tts)
+        tts.__aexit__ = AsyncMock(return_value=None)
+        tts.synthesize = AsyncMock()
+
+        middleware = TTSMiddleware(tts_model=tts)
+        agent = _make_agent_stub()
+
+        upstream_events = [
+            TextBlockDeltaEvent(
+                reply_id="reply-1",
+                block_id="blk-1",
+                delta="   ",
+            ),
+            TextBlockEndEvent(reply_id="reply-1", block_id="blk-1"),
+        ]
+
+        async def next_handler(**_kwargs: Any) -> AsyncGenerator:
+            for evt in upstream_events:
+                yield evt
+
+        emitted = []
+        async for evt in middleware.on_reply(agent, {}, next_handler):
+            emitted.append(evt)
+
+        # Only the upstream events are passed through
+        self.assertEqual(
+            [_dump(e) for e in emitted],
+            [_dump(e) for e in upstream_events],
+        )
+        tts.synthesize.assert_not_called()
+
+    async def test_audio_block_id_uses_configured_id_factory(self) -> None:
+        """TTS audio DATA_BLOCK events use the configured ID factory."""
+        import agentscope._utils._common as common
+
+        # pylint: disable=protected-access
+        saved_factory = common._id_factory
+        self.addCleanup(setattr, common, "_id_factory", saved_factory)
+        set_id_factory(lambda: "custom-audio-id")
+
+        tts = MagicMock(spec=TTSModelBase)
+        tts.realtime = False
+        tts.__aenter__ = AsyncMock(return_value=tts)
+        tts.__aexit__ = AsyncMock(return_value=None)
+        tts.synthesize = AsyncMock(
+            return_value=_make_tts_response("AAAA"),
+        )
+
+        middleware = TTSMiddleware(tts_model=tts)
+        agent = _make_agent_stub()
+
+        async def next_handler(**_kwargs: Any) -> AsyncGenerator:
+            yield TextBlockDeltaEvent(
+                reply_id="reply-1",
+                block_id="blk-1",
+                delta="hi",
+            )
+            yield TextBlockEndEvent(reply_id="reply-1", block_id="blk-1")
+
+        emitted = [
+            evt async for evt in middleware.on_reply(agent, {}, next_handler)
+        ]
+
+        self.assertEqual(
+            [evt.block_id for evt in emitted[2:]],
+            ["custom-audio-id"] * 3,
+        )
+
+    async def test_streaming_output_multiple_chunks(self) -> None:
+        """When synthesize() returns an async generator, each chunk produces
+        a DATA_BLOCK_DELTA under the same block_id."""
+        chunk1 = _make_tts_response("AAAA")
+        chunk2 = _make_tts_response("BBBB")
+
+        async def synth_gen(*_args: Any, **_kwargs: Any) -> AsyncGenerator:
+            yield chunk1
+            yield chunk2
+
+        tts = MagicMock(spec=TTSModelBase)
+        tts.realtime = False
+        tts.__aenter__ = AsyncMock(return_value=tts)
+        tts.__aexit__ = AsyncMock(return_value=None)
+        tts.synthesize = AsyncMock(return_value=synth_gen())
+
+        middleware = TTSMiddleware(tts_model=tts)
+        agent = _make_agent_stub()
+
+        upstream_events = [
+            TextBlockDeltaEvent(
+                reply_id="reply-1",
+                block_id="blk-1",
+                delta="hi",
+            ),
+            TextBlockEndEvent(reply_id="reply-1", block_id="blk-1"),
+        ]
+
+        async def next_handler(**_kwargs: Any) -> AsyncGenerator:
+            for evt in upstream_events:
+                yield evt
+
+        emitted = []
+        async for evt in middleware.on_reply(agent, {}, next_handler):
+            emitted.append(evt)
+
+        # Upstream pass-through + START + 2x DELTA + END
+        data_events = emitted[2:]
+        block_id = data_events[0].block_id
+        self.assertEqual(
+            [_dump(e) for e in data_events],
+            [
+                {
+                    "type": "DATA_BLOCK_START",
+                    "reply_id": "reply-1",
+                    "block_id": block_id,
+                    "media_type": "audio/wav",
+                },
+                {
+                    "type": "DATA_BLOCK_DELTA",
+                    "reply_id": "reply-1",
+                    "block_id": block_id,
+                    "data": "AAAA",
+                    "media_type": "audio/wav",
+                },
+                {
+                    "type": "DATA_BLOCK_DELTA",
+                    "reply_id": "reply-1",
+                    "block_id": block_id,
+                    "data": "BBBB",
+                    "media_type": "audio/wav",
+                },
+                {
+                    "type": "DATA_BLOCK_END",
+                    "reply_id": "reply-1",
+                    "block_id": block_id,
+                },
+            ],
+        )
+
+
+class TestTTSMiddlewareRealtime(IsolatedAsyncioTestCase):
+    """Tests for realtime (streaming-input) TTS path."""
+
+    async def test_push_on_delta_and_drain_on_end(self) -> None:
+        """In realtime mode, push() is called on each TextBlockDelta and
+        synthesize() drains on TextBlockEnd."""
+        push_audio = _make_tts_response("PUSH1")
+        drain_audio = _make_tts_response("DRAIN")
+
+        tts = MagicMock(spec=TTSModelBase)
+        tts.realtime = True
+        tts.__aenter__ = AsyncMock(return_value=tts)
+        tts.__aexit__ = AsyncMock(return_value=None)
+        tts.push = AsyncMock(return_value=push_audio)
+        tts.synthesize = AsyncMock(return_value=drain_audio)
+
+        middleware = TTSMiddleware(tts_model=tts)
+        agent = _make_agent_stub()
+
+        upstream_events = [
+            TextBlockDeltaEvent(
+                reply_id="reply-1",
+                block_id="blk-1",
+                delta="Hello",
+            ),
+            TextBlockEndEvent(reply_id="reply-1", block_id="blk-1"),
+        ]
+
+        async def next_handler(**_kwargs: Any) -> AsyncGenerator:
+            for evt in upstream_events:
+                yield evt
+
+        emitted = []
+        async for evt in middleware.on_reply(agent, {}, next_handler):
+            emitted.append(evt)
+
+        # push() called with the delta text
+        tts.push.assert_called_once_with("Hello")
+
+        # synthesize() called to drain
+        tts.synthesize.assert_called_once()
+
+        data_events = [
+            e
+            for e in emitted
+            if isinstance(
+                e,
+                (DataBlockStartEvent, DataBlockDeltaEvent, DataBlockEndEvent),
+            )
+        ]
+        # START + DELTA(push) + DELTA(drain) + END
+        block_id = data_events[0].block_id
+        self.assertEqual(
+            [_dump(e) for e in data_events],
+            [
+                {
+                    "type": "DATA_BLOCK_START",
+                    "reply_id": "reply-1",
+                    "block_id": block_id,
+                    "media_type": "audio/wav",
+                },
+                {
+                    "type": "DATA_BLOCK_DELTA",
+                    "reply_id": "reply-1",
+                    "block_id": block_id,
+                    "data": "PUSH1",
+                    "media_type": "audio/wav",
+                },
+                {
+                    "type": "DATA_BLOCK_DELTA",
+                    "reply_id": "reply-1",
+                    "block_id": block_id,
+                    "data": "DRAIN",
+                    "media_type": "audio/wav",
+                },
+                {
+                    "type": "DATA_BLOCK_END",
+                    "reply_id": "reply-1",
+                    "block_id": block_id,
+                },
+            ],
+        )
+
+    async def test_push_returns_none_no_audio_emitted(self) -> None:
+        """When push() returns empty content, no DATA_BLOCK events are emitted
+        until synthesize() drains."""
+        empty_response = TTSResponse(content=None)
+        drain_audio = _make_tts_response("FINAL")
+
+        tts = MagicMock(spec=TTSModelBase)
+        tts.realtime = True
+        tts.__aenter__ = AsyncMock(return_value=tts)
+        tts.__aexit__ = AsyncMock(return_value=None)
+        tts.push = AsyncMock(return_value=empty_response)
+        tts.synthesize = AsyncMock(return_value=drain_audio)
+
+        middleware = TTSMiddleware(tts_model=tts)
+        agent = _make_agent_stub()
+
+        upstream_events = [
+            TextBlockDeltaEvent(
+                reply_id="reply-1",
+                block_id="blk-1",
+                delta="Hi",
+            ),
+            TextBlockDeltaEvent(
+                reply_id="reply-1",
+                block_id="blk-1",
+                delta=" there",
+            ),
+            TextBlockEndEvent(reply_id="reply-1", block_id="blk-1"),
+        ]
+
+        async def next_handler(**_kwargs: Any) -> AsyncGenerator:
+            for evt in upstream_events:
+                yield evt
+
+        emitted = []
+        async for evt in middleware.on_reply(agent, {}, next_handler):
+            emitted.append(evt)
+
+        # push called twice but produced no audio
+        self.assertEqual(tts.push.call_count, 2)
+
+        data_events = [
+            e
+            for e in emitted
+            if isinstance(
+                e,
+                (DataBlockStartEvent, DataBlockDeltaEvent, DataBlockEndEvent),
+            )
+        ]
+        # Only drain produces: START + DELTA + END
+        block_id = data_events[0].block_id
+        self.assertEqual(
+            [_dump(e) for e in data_events],
+            [
+                {
+                    "type": "DATA_BLOCK_START",
+                    "reply_id": "reply-1",
+                    "block_id": block_id,
+                    "media_type": "audio/wav",
+                },
+                {
+                    "type": "DATA_BLOCK_DELTA",
+                    "reply_id": "reply-1",
+                    "block_id": block_id,
+                    "data": "FINAL",
+                    "media_type": "audio/wav",
+                },
+                {
+                    "type": "DATA_BLOCK_END",
+                    "reply_id": "reply-1",
+                    "block_id": block_id,
+                },
+            ],
+        )
diff --git a/tests/tts_openai_test.py b/tests/tts_openai_test.py
new file mode 100644
index 0000000..a181fbb
--- /dev/null
+++ b/tests/tts_openai_test.py
@@ -0,0 +1,167 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Unit tests for the OpenAI TTS model.
+
+Covers:
+  * ``OpenAITTSModel`` non-streaming aggregation.
+  * ``OpenAITTSModel`` streaming: incremental chunks and ``is_last``
+    placement at the final chunk only.
+  * Edge cases: empty/None input short-circuits without calling the API.
+"""
+import base64
+from typing import Any
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import AsyncMock, MagicMock, patch
+
+from agentscope.credential import OpenAICredential
+from agentscope.tts import OpenAITTSModel, TTSResponse
+
+
+_MEDIA_TYPE_MP3 = "audio/mpeg"
+_MEDIA_TYPE_WAV = "audio/wav"
+
+
+def _make_mock_client(audio_bytes: bytes, chunks: list[bytes]) -> MagicMock:
+    """Build a mock ``openai.AsyncClient`` shaped like what
+    ``audio.speech.create`` / ``with_streaming_response.create`` return."""
+    client = MagicMock()
+
+    # Non-streaming: client.audio.speech.create(...) -> response with
+    # .content bytes.
+    create_response = MagicMock()
+    create_response.content = audio_bytes
+    client.audio.speech.create = AsyncMock(return_value=create_response)
+
+    # Streaming: client.audio.speech.with_streaming_response.create(...)
+    # is an async context manager whose value exposes .iter_bytes().
+    stream_response = MagicMock()
+
+    async def _iter_bytes() -> Any:
+        for chunk in chunks:
+            yield chunk
+
+    stream_response.iter_bytes = _iter_bytes
+
+    stream_ctx = MagicMock()
+    stream_ctx.__aenter__ = AsyncMock(return_value=stream_response)
+    stream_ctx.__aexit__ = AsyncMock(return_value=None)
+
+    client.audio.speech.with_streaming_response.create = MagicMock(
+        return_value=stream_ctx,
+    )
+
+    return client
+
+
+class TestOpenAITTSModel(IsolatedAsyncioTestCase):
+    """The unittests for the OpenAI TTS model (non-realtime)."""
+
+    def _make_model(self, stream: bool = False, **kwargs: Any) -> Any:
+        """Create an OpenAITTSModel with test credentials."""
+        return OpenAITTSModel(
+            credential=OpenAICredential(api_key="test"),
+            model="tts-1",
+            stream=stream,
+            **kwargs,
+        )
+
+    async def test_aggregates_response(self) -> None:
+        """Non-streaming returns a single TTSResponse with the full audio."""
+        client = _make_mock_client(b"AAAABBBBCCCC", [])
+        model = self._make_model(stream=False)
+
+        with patch("openai.AsyncClient", return_value=client):
+            result = await model.synthesize("Hello world")
+
+        self.assertIsInstance(result, TTSResponse)
+        self.assertEqual(result.content.source.media_type, _MEDIA_TYPE_MP3)
+        self.assertEqual(
+            base64.b64decode(result.content.source.data),
+            b"AAAABBBBCCCC",
+        )
+        self.assertTrue(result.is_last)
+
+    async def test_none_short_circuits(self) -> None:
+        """``synthesize(None)`` returns an empty response without touching
+        the API."""
+        model = self._make_model(stream=False)
+
+        with patch("openai.AsyncClient") as mock_client_cls:
+            result = await model.synthesize(None)
+
+        self.assertIsNone(result.content)
+        mock_client_cls.assert_not_called()
+
+    async def test_empty_string_short_circuits(self) -> None:
+        """``synthesize("")`` returns an empty response without touching
+        the API."""
+        model = self._make_model(stream=False)
+
+        with patch("openai.AsyncClient") as mock_client_cls:
+            result = await model.synthesize("")
+
+        self.assertIsNone(result.content)
+        mock_client_cls.assert_not_called()
+
+    async def test_wav_media_type(self) -> None:
+        """The media type follows the ``response_format`` parameter."""
+        client = _make_mock_client(b"AAAA", [])
+        model = self._make_model(
+            stream=False,
+            parameters=OpenAITTSModel.Parameters(response_format="wav"),
+        )
+
+        with patch("openai.AsyncClient", return_value=client):
+            result = await model.synthesize("Hello world")
+
+        self.assertEqual(result.content.source.media_type, _MEDIA_TYPE_WAV)
+
+    async def test_incremental_chunks(self) -> None:
+        """Each streamed byte chunk yields one TTSResponse."""
+        client = _make_mock_client(b"", [b"AAAA", b"BBBB", b"CCCC"])
+        model = self._make_model(stream=True)
+
+        with patch("openai.AsyncClient", return_value=client):
+            gen = await model.synthesize("Hello world")
+            chunks = [c async for c in gen]
+
+        payloads = [base64.b64decode(c.content.source.data) for c in chunks]
+        self.assertEqual(payloads, [b"AAAA", b"BBBB", b"CCCC"])
+        self.assertEqual(
+            [c.is_last for c in chunks],
+            [False, False, True],
+        )
+        self.assertEqual(
+            [c.content.source.media_type for c in chunks],
+            [_MEDIA_TYPE_MP3] * 3,
+        )
+
+    async def test_single_chunk_marked_last(self) -> None:
+        """A lone audio chunk is flagged ``is_last=True``."""
+        client = _make_mock_client(b"", [b"ONLYCHUNK"])
+        model = self._make_model(stream=True)
+
+        with patch("openai.AsyncClient", return_value=client):
+            gen = await model.synthesize("Hello world")
+            chunks = [c async for c in gen]
+
+        self.assertEqual(len(chunks), 1)
+        self.assertTrue(chunks[0].is_last)
+        self.assertEqual(
+            base64.b64decode(chunks[0].content.source.data),
+            b"ONLYCHUNK",
+        )
+
+    async def test_empty_stream_yields_terminal(self) -> None:
+        """When the API yields no audio, the generator emits a terminal
+        sentinel so consumers can detect EOS."""
+        client = _make_mock_client(b"", [])
+        model = self._make_model(stream=True)
+
+        with patch("openai.AsyncClient", return_value=client):
+            gen = await model.synthesize("Hello world")
+            chunks = [c async for c in gen]
+
+        self.assertEqual(len(chunks), 1)
+        self.assertIsNone(chunks[0].content)
+        self.assertTrue(chunks[0].is_last)
diff --git a/tests/utils.py b/tests/utils.py
new file mode 100644
index 0000000..9eba25c
--- /dev/null
+++ b/tests/utils.py
@@ -0,0 +1,187 @@
+# -*- coding: utf-8 -*-
+"""The utility module for unit tests in agentscope."""
+import json
+from typing import Any, AsyncGenerator, Type
+
+from pydantic import BaseModel
+
+from agentscope.app.workspace_manager import WorkspaceManagerBase
+from agentscope.credential import CredentialBase
+from agentscope.message import Msg
+from agentscope.model import ChatModelBase, ChatResponse, StructuredResponse
+from agentscope.workspace import WorkspaceBase
+
+
+class AnyString(str):
+    """A helper class for asserting any string value in unit tests."""
+
+    def __eq__(self, other: object) -> bool:
+        """Override equality check to match any string."""
+        return isinstance(other, str)
+
+    def __repr__(self) -> str:
+        """Return a string representation for debugging purposes."""
+        return "<AnyString>"
+
+
+class AnyValue:
+    """A helper class for asserting any value (str, int, float, etc.)
+    in unit tests.  Useful for dynamic fields like timestamps, tokens,
+    or durations where the exact value is unpredictable."""
+
+    def __eq__(self, other: object) -> bool:
+        """Override equality check to match any value."""
+        return True
+
+    def __repr__(self) -> str:
+        """Return a string representation for debugging purposes."""
+        return "<AnyValue>"
+
+
+class MockCredential(CredentialBase):
+    """The mock credential class."""
+
+    @classmethod
+    def get_chat_model_class(cls) -> Type["ChatModelBase"]:
+        """Return the mock model class."""
+        return MockModel
+
+
+class MockModel(ChatModelBase):
+    """A mock model for testing."""
+
+    class Parameters(BaseModel):
+        """The parameters."""
+
+    def __init__(
+        self,
+        model: str = "mock-model",
+        stream: bool = True,
+        context_size: int = 1000,
+        mock_chat_responses: list | None = None,
+        mock_structured_response: Any = None,
+    ) -> None:
+        """Initialize the mock model."""
+        super().__init__(
+            credential=MockCredential(),
+            model=model,
+            stream=stream,
+            parameters=MockModel.Parameters(),
+            context_size=context_size,
+        )
+        self.mock_chat_responses = mock_chat_responses or []
+        self.mock_structured_response = mock_structured_response
+        self.cnt = 0
+
+    def set_responses(
+        self,
+        mock_responses: list[
+            ChatResponse | BaseException | list[ChatResponse | BaseException]
+        ],
+    ) -> None:
+        """Set the mock responses.
+
+        Each item in ``mock_responses`` may be:
+
+        - ``ChatResponse`` — returned directly by the next non-stream call.
+        - ``BaseException`` — raised from inside the next non-stream call
+          (use e.g. ``asyncio.CancelledError()`` to simulate an
+          interrupted API call).
+        - ``list[ChatResponse | BaseException]`` — returned as an async
+          generator by the next stream call, where each element is
+          either yielded (``ChatResponse``) or raised (``BaseException``)
+          at that position in the stream.
+        """
+        self.mock_chat_responses = mock_responses
+        if all(
+            isinstance(_, (ChatResponse, BaseException))
+            for _ in mock_responses
+        ):
+            self.stream = False
+        else:
+            self.stream = True
+        self.cnt = 0
+
+    async def _call_api(
+        self,  # pylint: disable=unused-argument
+        *args: Any,
+        **kwargs: Any,
+    ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:
+        """Mock the API call."""
+        mock_responses = self.mock_chat_responses[self.cnt]
+        self.cnt += 1
+
+        if isinstance(mock_responses, BaseException):
+            raise mock_responses
+
+        if isinstance(mock_responses, list):
+
+            async def _stream() -> AsyncGenerator[ChatResponse, None]:
+                for response in mock_responses:
+                    if isinstance(response, BaseException):
+                        raise response
+                    yield response
+
+            return _stream()
+
+        if isinstance(mock_responses, ChatResponse):
+            return mock_responses
+
+        raise AssertionError
+
+    def set_structured_response(
+        self,
+        mock_response: StructuredResponse,
+    ) -> None:
+        """Set the mock structured responses."""
+        self.mock_structured_response = mock_response
+
+    async def _call_api_with_structured_output(
+        self,
+        model_name: str,
+        messages: list[Msg],
+        structured_model: Type[BaseModel] | dict,
+        **kwargs: Any,
+    ) -> StructuredResponse:
+        """Mock the API call with structured output."""
+        return self.mock_structured_response
+
+
+def compare_by_printing(a: Any, b: Any) -> None:
+    """Compare the expected output with the actual output by printing them."""
+    print(json.dumps(a, indent=4))
+    print(json.dumps(b, indent=4))
+
+
+class FakeWorkspaceManager(WorkspaceManagerBase):
+    """Minimal :class:`WorkspaceManagerBase` for tests.
+
+    Inherits the real :meth:`assign_workspace_id` (drives the
+    isolation policy under test) and stubs the abstract async
+    methods with no-ops. Not backed by any real workspace.
+    """
+
+    async def get_workspace(
+        self,
+        user_id: str,
+        agent_id: str,
+        session_id: str,
+        workspace_id: str | None = None,
+    ) -> WorkspaceBase:
+        """Not implemented — team-tool tests never touch this."""
+        raise NotImplementedError
+
+    async def create_workspace(
+        self,
+        user_id: str,
+        agent_id: str,
+        session_id: str,
+    ) -> WorkspaceBase:
+        """Not implemented — team-tool tests never touch this."""
+        raise NotImplementedError
+
+    async def close(self, workspace_id: str) -> None:
+        """No-op."""
+
+    async def close_all(self) -> None:
+        """No-op."""
diff --git a/tests/workspace_docker_test.py b/tests/workspace_docker_test.py
new file mode 100644
index 0000000..016f3e4
--- /dev/null
+++ b/tests/workspace_docker_test.py
@@ -0,0 +1,821 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Test cases for DockerWorkspace.
+
+Mirrors the structure of ``workspace_local_test.py`` so that the two
+backends are validated against the same surface contract:
+
+* offload_context (text + DataBlock + dedup)
+* offload_tool_result (string + multimodal blocks)
+* skill seeding / listing
+* lifecycle (initialize idempotent, close, workspace_id stability)
+
+Two practical differences vs. the local tests:
+
+1. Paths *returned* by DockerWorkspace are container-side
+   (``/workspace/sessions/...``).  Host-side file checks therefore
+   compose paths against ``self.temp_dir.name``, which is bind-mounted
+   to ``CONTAINER_WORKDIR`` inside the container.
+
+2. ``DataBlock`` URLs persisted by DockerWorkspace use the container
+   path (``file:///workspace/data/<hash>.png``).  We assert the URL
+   string against the container path and verify the file's *bytes* via
+   the corresponding host-side path.
+
+The whole module is skipped when no Docker daemon is reachable.
+"""
+
+import base64
+import hashlib
+import os
+import re
+import shutil
+import subprocess
+import tempfile
+import unittest
+import uuid
+from typing import Any
+from unittest.async_case import IsolatedAsyncioTestCase
+from urllib.parse import urlparse
+
+import aiofiles
+
+from agentscope.message import (
+    AssistantMsg,
+    Base64Source,
+    DataBlock,
+    Msg,
+    TextBlock,
+    ToolResultBlock,
+    ToolResultState,
+    URLSource,
+    UserMsg,
+)
+from agentscope.permission import PermissionBehavior, PermissionDecision
+from agentscope.tool import ToolBase, ToolChunk
+from agentscope.workspace import DockerWorkspace
+from agentscope.workspace._docker._make_dockerfile import CONTAINER_WORKDIR
+
+CONTAINER_SKILLS_DIR = f"{CONTAINER_WORKDIR}/skills"
+CONTAINER_SESSIONS_DIR = f"{CONTAINER_WORKDIR}/sessions"
+
+# ── docker daemon detection ────────────────────────────────────────
+
+
+def _docker_available() -> bool:
+    """Return ``True`` iff the Docker daemon is reachable.
+
+    Probes via the ``docker`` CLI rather than the aiodocker async client
+    so the check is cheap and synchronous (runs at module import time).
+    """
+    if shutil.which("docker") is None:
+        return False
+    try:
+        result = subprocess.run(
+            ["docker", "info"],
+            capture_output=True,
+            timeout=5,
+            check=False,
+        )
+        return result.returncode == 0
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        return False
+
+
+_DOCKER_OK = _docker_available()
+_SKIP_REASON = "Docker daemon not available"
+
+
+# ── helper tool for agent-integration test ────────────────────────
+
+
+class _LongResultTool(ToolBase):
+    """Mock tool that returns a long string + base64 DataBlock."""
+
+    name: str = "long_result_tool"
+    description: str = "A tool that returns a long string."
+    input_schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {},
+        "required": [],
+    }
+    is_concurrency_safe: bool = True
+    is_read_only: bool = True
+    is_external_tool: bool = False
+    is_mcp: bool = False
+
+    async def check_permissions(
+        self,
+        *_args: Any,
+        **_kwargs: Any,
+    ) -> PermissionDecision:
+        """Always allow."""
+        return PermissionDecision(
+            behavior=PermissionBehavior.ALLOW,
+            decision_reason="Mock tool always allows",
+            message="Mock tool always allows",
+        )
+
+    async def __call__(self, **_kwargs: Any) -> ToolChunk:
+        """Long text + base64 DataBlock so we exercise both offload paths."""
+        return ToolChunk(
+            content=[
+                TextBlock(text="0" * 30000),
+                DataBlock(
+                    name="fake_image.png",
+                    source=Base64Source(
+                        data="AAECAwQF",
+                        media_type="image/png",
+                    ),
+                ),
+            ],
+            state=ToolResultState.SUCCESS,
+        )
+
+
+# ── offload tests ─────────────────────────────────────────────────
+
+
+@unittest.skipUnless(_DOCKER_OK, _SKIP_REASON)
+class TestDockerWorkspaceOffload(IsolatedAsyncioTestCase):
+    """Test cases for DockerWorkspace offload functionality."""
+
+    async def asyncSetUp(self) -> None:
+        """Build a fresh workspace bound to a temp host dir.
+
+        The workspace_id is randomised so test runs do not collide on
+        the deterministic ``as_ws_<workspace_id>`` container name.
+        """
+        # pylint: disable=consider-using-with
+        self.temp_dir = tempfile.TemporaryDirectory()
+        self.workspace = DockerWorkspace(
+            workspace_id=f"test-{uuid.uuid4().hex[:8]}",
+            host_workdir=self.temp_dir.name,
+        )
+        await self.workspace.initialize()
+
+    async def asyncTearDown(self) -> None:
+        """Stop the container and clean up the temp host dir."""
+        try:
+            await self.workspace.close()
+        finally:
+            self.temp_dir.cleanup()
+
+    async def test_offload_context_pure_text(self) -> None:
+        """Text-only offload: returned path is container-side, lines match.
+
+        Verifies:
+        1. The returned path is the *container-side* JSONL path.
+        2. The host-mirror file (under the bind-mounted workdir) contains
+           one ``model_dump_json()`` line per input message.
+        """
+        session_id = "test_session_pure_text"
+        msgs = [
+            UserMsg(name="user", content="Hello, world!"),
+            AssistantMsg(name="assistant", content="Hi there!"),
+        ]
+
+        file_path = await self.workspace.offload_context(session_id, msgs)
+
+        # Returned path is container-side (/workspace/sessions/...).
+        expected_container_path = (
+            f"{CONTAINER_SESSIONS_DIR}/{session_id}/context.jsonl"
+        )
+        self.assertEqual(file_path, expected_container_path)
+
+        # Host-side mirror of that path (bind mount).
+        host_path = os.path.join(
+            self.temp_dir.name,
+            "sessions",
+            session_id,
+            "context.jsonl",
+        )
+        self.assertTrue(os.path.exists(host_path))
+
+        async with aiofiles.open(host_path, "r") as f:
+            content = await f.read()
+        lines = content.strip().split("\n")
+        self.assertEqual(len(lines), 2)
+        self.assertListEqual(lines, [m.model_dump_json() for m in msgs])
+
+    async def test_offload_context_multiple_calls(self) -> None:
+        """Repeated calls append to the same file (proper JSONL).
+
+        Verifies:
+        1. Both calls return the same container-side path.
+        2. The host-mirror file ends up with one line per message,
+           preserving order.
+        """
+        session_id = "test_session_multiple"
+        msgs1 = [
+            UserMsg(name="user", content="First message"),
+            AssistantMsg(name="assistant", content="First response"),
+        ]
+        msgs2 = [
+            UserMsg(name="user", content="Second message"),
+            AssistantMsg(name="assistant", content="Second response"),
+        ]
+
+        path1 = await self.workspace.offload_context(session_id, msgs1)
+        path2 = await self.workspace.offload_context(session_id, msgs2)
+        self.assertEqual(path1, path2)
+
+        host_path = os.path.join(
+            self.temp_dir.name,
+            "sessions",
+            session_id,
+            "context.jsonl",
+        )
+        async with aiofiles.open(host_path, "r") as f:
+            content = await f.read()
+        lines = content.strip().split("\n")
+        self.assertEqual(len(lines), 4)
+        self.assertListEqual(
+            lines,
+            [m.model_dump_json() for m in msgs1 + msgs2],
+        )
+        for line in lines:
+            self.assertIsNotNone(Msg.model_validate_json(line))
+
+    async def test_offload_context_with_datablock(self) -> None:
+        """DataBlock(Base64Source) is rewritten to URLSource on a
+        separate file.
+
+        Verifies:
+        1. The decoded payload lands on disk under ``<workdir>/data/``
+           (container-side ``/workspace/data/``).
+        2. The offloaded JSONL line carries a ``URLSource`` whose URL is
+           the *container* path (``file:///workspace/data/<hash>.<ext>``).
+        3. Decoded bytes match the original.
+        """
+        session_id = "test_session_datablock"
+        b64_data = base64.b64encode(
+            b"\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\x01"
+            b"\x00\x00\x00\x01\x08\x02\x00\x00\x00\x90wS\xde",
+        ).decode()
+        data_block = DataBlock(
+            source=Base64Source(data=b64_data, media_type="image/png"),
+            name="test_image",
+        )
+        msgs = [
+            UserMsg(
+                name="user",
+                content=[TextBlock(text="Check this image:"), data_block],
+            ),
+        ]
+
+        file_path = await self.workspace.offload_context(session_id, msgs)
+        host_path = os.path.join(
+            self.temp_dir.name,
+            "sessions",
+            session_id,
+            "context.jsonl",
+        )
+        self.assertTrue(os.path.exists(host_path))
+
+        async with aiofiles.open(host_path, "r") as f:
+            content = await f.read()
+        loaded_msg = Msg.model_validate_json(content.strip())
+
+        # The DataBlock's source should now be URLSource pointing to a
+        # container-side file://...
+        self.assertEqual(len(loaded_msg.content), 2)
+        data_url = str(loaded_msg.content[1].source.url)
+        self.assertTrue(data_url.startswith("file:///workspace/data/"))
+
+        # Verify the bytes via the host-side mirror.
+        container_path = urlparse(data_url).path  # /workspace/data/<hash>.png
+        rel = os.path.relpath(container_path, "/workspace")
+        host_data_path = os.path.join(self.temp_dir.name, rel)
+        self.assertTrue(os.path.exists(host_data_path))
+        async with aiofiles.open(host_data_path, "rb") as f:
+            saved = await f.read()
+        self.assertEqual(saved, base64.b64decode(b64_data))
+
+        # Sanity-check the returned (container) JSONL path too.
+        self.assertEqual(
+            file_path,
+            f"{CONTAINER_SESSIONS_DIR}/{session_id}/context.jsonl",
+        )
+
+    async def test_offload_data_block_deduplication(self) -> None:
+        """Two identical DataBlocks share a single persisted file.
+
+        Verifies:
+        1. Both ``_offload_data_block`` calls return DataBlocks pointing
+           at the same URL.
+        2. Only one file ends up in ``<workdir>/data/``.
+        """
+        b64_data = base64.b64encode(b"test content").decode()
+        block1 = DataBlock(
+            source=Base64Source(data=b64_data, media_type="text/plain"),
+            name="file1",
+        )
+        block2 = DataBlock(
+            source=Base64Source(data=b64_data, media_type="text/plain"),
+            name="file2",
+        )
+
+        result1 = await self.workspace._offload_data_block(block1)
+        result2 = await self.workspace._offload_data_block(block2)
+        self.assertEqual(str(result1.source.url), str(result2.source.url))
+
+        # Check the host-mirror data dir has exactly one file.
+        host_data_dir = os.path.join(self.temp_dir.name, "data")
+        self.assertTrue(os.path.isdir(host_data_dir))
+        files = os.listdir(host_data_dir)
+        self.assertEqual(len(files), 1)
+
+        # Hash key is sha256 of the *base64 string* (matches LocalWorkspace).
+        expected_name = hashlib.sha256(b64_data.encode()).hexdigest() + ".txt"
+        self.assertIn(expected_name, files)
+
+    async def test_offload_data_block_url_source(self) -> None:
+        """A DataBlock that already has a URLSource is returned unchanged.
+
+        Verifies:
+        1. ``_offload_data_block`` is a no-op for URL-sourced blocks.
+        2. No file lands in ``<workdir>/data/``.
+        """
+        from pydantic import AnyUrl
+
+        block = DataBlock(
+            source=URLSource(
+                url=AnyUrl("https://example.com/image.png"),
+                media_type="image/png",
+            ),
+            name="remote_image",
+        )
+
+        result = await self.workspace._offload_data_block(block)
+        self.assertDictEqual(result.model_dump(), block.model_dump())
+
+        host_data_dir = os.path.join(self.temp_dir.name, "data")
+        if os.path.isdir(host_data_dir):
+            self.assertEqual(len(os.listdir(host_data_dir)), 0)
+
+    async def test_offload_tool_result_string(self) -> None:
+        """String-output tool result writes the raw string to disk.
+
+        Verifies:
+        1. The returned path is the container-side ``tool_result-<id>.txt``.
+        2. The host-mirror file contains exactly the output string.
+        """
+        session_id = "test_session_tool_result"
+        tool_result = ToolResultBlock(
+            id="tool_123",
+            name="test_tool",
+            output="Tool execution successful!",
+            state=ToolResultState.SUCCESS,
+        )
+
+        file_path = await self.workspace.offload_tool_result(
+            session_id,
+            tool_result,
+        )
+        self.assertEqual(
+            file_path,
+            f"{CONTAINER_SESSIONS_DIR}/{session_id}/"
+            f"tool_result-{tool_result.id}.txt",
+        )
+
+        host_path = os.path.join(
+            self.temp_dir.name,
+            "sessions",
+            session_id,
+            f"tool_result-{tool_result.id}.txt",
+        )
+        self.assertTrue(os.path.exists(host_path))
+        async with aiofiles.open(host_path, "r") as f:
+            self.assertEqual(await f.read(), "Tool execution successful!")
+
+    async def test_offload_tool_result_with_blocks(self) -> None:
+        """Multimodal tool result: text concatenated, DataBlock placeholder.
+
+        Verifies:
+        1. The text portion is preserved verbatim.
+        2. The DataBlock is rendered as
+           ``<data url='…' name='…' media_type='…'/>`` with a
+           container-side URL.
+        3. The decoded payload is reachable via the host mirror.
+        """
+        session_id = "test_session_tool_result_blocks"
+        b64_data = base64.b64encode(b"test file content").decode()
+        data_block = DataBlock(
+            source=Base64Source(data=b64_data, media_type="text/plain"),
+            name="output.txt",
+        )
+        tool_result = ToolResultBlock(
+            id="tool_456",
+            name="file_tool",
+            output=[
+                TextBlock(text="File created successfully: "),
+                data_block,
+            ],
+            state=ToolResultState.SUCCESS,
+        )
+
+        file_path = await self.workspace.offload_tool_result(
+            session_id,
+            tool_result,
+        )
+        host_path = os.path.join(
+            self.temp_dir.name,
+            "sessions",
+            session_id,
+            f"tool_result-{tool_result.id}.txt",
+        )
+        self.assertTrue(os.path.exists(host_path))
+        async with aiofiles.open(host_path, "r") as f:
+            content = await f.read()
+
+        self.assertTrue(content.startswith("File created successfully: "))
+        self.assertIn("<data url='file:///workspace/data/", content)
+        self.assertIn("name='output.txt'", content)
+        self.assertIn("media_type='text/plain'", content)
+        self.assertTrue(content.endswith("/>"))
+
+        # The data file is reachable via the host mirror.
+        match = re.search(r"url='([^']+)'", content)
+        self.assertIsNotNone(match)
+        container_path = urlparse(match.group(1)).path
+        rel = os.path.relpath(container_path, "/workspace")
+        host_data_path = os.path.join(self.temp_dir.name, rel)
+        self.assertTrue(os.path.exists(host_data_path))
+
+        # And the returned path is container-side.
+        self.assertEqual(
+            file_path,
+            f"{CONTAINER_SESSIONS_DIR}/{session_id}/"
+            f"tool_result-{tool_result.id}.txt",
+        )
+
+
+# ── skill tests ────────────────────────────────────────────────────
+
+
+@unittest.skipUnless(_DOCKER_OK, _SKIP_REASON)
+class TestDockerWorkspaceSkills(IsolatedAsyncioTestCase):
+    """Test cases for DockerWorkspace skill management."""
+
+    async def asyncSetUp(self) -> None:
+        """Build separate temp dirs for the workspace and the skill source."""
+        # pylint: disable=consider-using-with
+        self.temp_dir = tempfile.TemporaryDirectory()
+        self.test_skills_dir = tempfile.TemporaryDirectory()
+        self.workspace: DockerWorkspace | None = None
+
+    async def asyncTearDown(self) -> None:
+        """Stop the workspace if started, then drop both temp dirs."""
+        try:
+            if self.workspace is not None:
+                await self.workspace.close()
+        finally:
+            self.temp_dir.cleanup()
+            self.test_skills_dir.cleanup()
+
+    def _create_test_skill(
+        self,
+        skill_name: str,
+        description: str,
+        additional_files: dict[str, str] | None = None,
+    ) -> str:
+        """Create a host-side skill directory containing SKILL.md.
+
+        Args:
+            skill_name: Name written to the SKILL.md front matter and
+                used as the directory basename.
+            description: ``description`` field for the front matter.
+            additional_files: Optional ``{filename: content}`` map of
+                supplementary files written alongside SKILL.md.
+
+        Returns:
+            Absolute path to the created directory.
+        """
+        skill_dir = os.path.join(self.test_skills_dir.name, skill_name)
+        os.makedirs(skill_dir, exist_ok=True)
+        skill_md = (
+            f"---\nname: {skill_name}\ndescription: {description}\n---\n\n"
+            f"# {skill_name}\n\n{description}\n"
+        )
+        with open(
+            os.path.join(skill_dir, "SKILL.md"),
+            "w",
+            encoding="utf-8",
+        ) as f:
+            f.write(skill_md)
+        if additional_files:
+            for filename, content in additional_files.items():
+                with open(
+                    os.path.join(skill_dir, filename),
+                    "w",
+                    encoding="utf-8",
+                ) as f:
+                    f.write(content)
+        return skill_dir
+
+    async def test_initialize_copy_skills(self) -> None:
+        """``skill_paths`` are copied into the container's ``skills/``.
+
+        Verifies:
+        1. Both seed skills appear under ``<workdir>/skills/`` (host
+           mirror) — directory + SKILL.md + supplementary files.
+        """
+        skill1 = self._create_test_skill(
+            "test_skill_1",
+            "First test skill",
+            {"tool.py": "def t():\n    pass\n"},
+        )
+        skill2 = self._create_test_skill(
+            "test_skill_2",
+            "Second test skill",
+            {"helper.py": "def h():\n    return 42\n"},
+        )
+
+        self.workspace = DockerWorkspace(
+            workspace_id=f"test-{uuid.uuid4().hex[:8]}",
+            host_workdir=self.temp_dir.name,
+            skill_paths=[skill1, skill2],
+        )
+        await self.workspace.initialize()
+
+        skills_host = os.path.join(self.temp_dir.name, "skills")
+        self.assertTrue(os.path.isdir(skills_host))
+        for name, extra in (
+            ("test_skill_1", "tool.py"),
+            ("test_skill_2", "helper.py"),
+        ):
+            target = os.path.join(skills_host, name)
+            self.assertTrue(os.path.isdir(target))
+            self.assertTrue(
+                os.path.isfile(os.path.join(target, "SKILL.md")),
+            )
+            self.assertTrue(os.path.isfile(os.path.join(target, extra)))
+
+    async def test_list_skills(self) -> None:
+        """``list_skills`` enumerates skills via in-container ``find``.
+
+        Verifies:
+        1. Every seeded skill is returned with the right name + dir.
+        2. The dir field uses the *container-side* path.
+        """
+        skill1 = self._create_test_skill(
+            "list_skill_1",
+            "First skill for listing",
+        )
+        skill2 = self._create_test_skill(
+            "list_skill_2",
+            "Second skill for listing",
+        )
+
+        self.workspace = DockerWorkspace(
+            workspace_id=f"test-{uuid.uuid4().hex[:8]}",
+            host_workdir=self.temp_dir.name,
+            skill_paths=[skill1, skill2],
+        )
+        await self.workspace.initialize()
+
+        skills = await self.workspace.list_skills()
+        self.assertEqual(len(skills), 2)
+        skills_sorted = sorted(skills, key=lambda s: s.name)
+
+        self.assertEqual(skills_sorted[0].name, "list_skill_1")
+        self.assertEqual(
+            skills_sorted[0].description,
+            "First skill for listing",
+        )
+        self.assertEqual(
+            skills_sorted[0].dir,
+            f"{CONTAINER_SKILLS_DIR}/list_skill_1",
+        )
+
+        self.assertEqual(skills_sorted[1].name, "list_skill_2")
+        self.assertEqual(
+            skills_sorted[1].description,
+            "Second skill for listing",
+        )
+        self.assertEqual(
+            skills_sorted[1].dir,
+            f"{CONTAINER_SKILLS_DIR}/list_skill_2",
+        )
+
+    async def test_list_skills_empty(self) -> None:
+        """Empty workspace → empty skill list (no errors)."""
+        self.workspace = DockerWorkspace(
+            workspace_id=f"test-{uuid.uuid4().hex[:8]}",
+            host_workdir=self.temp_dir.name,
+        )
+        await self.workspace.initialize()
+        skills = await self.workspace.list_skills()
+        self.assertListEqual(skills, [])
+
+    async def test_add_skill_then_list(self) -> None:
+        """``add_skill`` after init shows up in subsequent ``list_skills``."""
+        self.workspace = DockerWorkspace(
+            workspace_id=f"test-{uuid.uuid4().hex[:8]}",
+            host_workdir=self.temp_dir.name,
+        )
+        await self.workspace.initialize()
+        self.assertListEqual(await self.workspace.list_skills(), [])
+
+        new_skill = self._create_test_skill(
+            "added_skill",
+            "Added at runtime",
+        )
+        await self.workspace.add_skill(new_skill)
+
+        skills = await self.workspace.list_skills()
+        self.assertEqual(len(skills), 1)
+        self.assertEqual(skills[0].name, "added_skill")
+        self.assertEqual(skills[0].description, "Added at runtime")
+
+    async def test_add_skill_invalid_no_md(self) -> None:
+        """``add_skill`` rejects directories without SKILL.md."""
+        self.workspace = DockerWorkspace(
+            workspace_id=f"test-{uuid.uuid4().hex[:8]}",
+            host_workdir=self.temp_dir.name,
+        )
+        await self.workspace.initialize()
+
+        invalid = os.path.join(self.test_skills_dir.name, "no_md")
+        os.makedirs(invalid, exist_ok=True)
+        with open(
+            os.path.join(invalid, "tool.py"),
+            "w",
+            encoding="utf-8",
+        ) as f:
+            f.write("def t():\n    pass\n")
+
+        with self.assertRaises(ValueError):
+            await self.workspace.add_skill(invalid)
+
+
+# ── lifecycle tests ───────────────────────────────────────────────
+
+
+@unittest.skipUnless(_DOCKER_OK, _SKIP_REASON)
+class TestDockerWorkspaceLifecycle(IsolatedAsyncioTestCase):
+    """Test cases for DockerWorkspace lifecycle (init / close / restart)."""
+
+    async def asyncSetUp(self) -> None:
+        """Per-test temp workdir; workspace built lazily inside each test."""
+        # pylint: disable=consider-using-with
+        self.temp_dir = tempfile.TemporaryDirectory()
+        self.workspace_id = f"test-{uuid.uuid4().hex[:8]}"
+
+    async def asyncTearDown(self) -> None:
+        """Best-effort cleanup of the temp workdir."""
+        self.temp_dir.cleanup()
+
+    async def test_initialize_idempotent(self) -> None:
+        """Calling ``initialize`` on a live workspace is a no-op."""
+        ws = DockerWorkspace(
+            workspace_id=self.workspace_id,
+            host_workdir=self.temp_dir.name,
+        )
+        try:
+            await ws.initialize()
+            self.assertTrue(ws.is_alive)
+            container = ws._container
+
+            await ws.initialize()  # second call — must be a no-op
+            self.assertTrue(ws.is_alive)
+            self.assertIs(ws._container, container)
+        finally:
+            await ws.close()
+
+    async def test_close_marks_inactive(self) -> None:
+        """``close`` flips ``is_alive`` and tears the container down."""
+        ws = DockerWorkspace(
+            workspace_id=self.workspace_id,
+            host_workdir=self.temp_dir.name,
+        )
+        await ws.initialize()
+        self.assertTrue(ws.is_alive)
+        await ws.close()
+        self.assertFalse(ws.is_alive)
+        self.assertIsNone(ws._container)
+        self.assertIsNone(ws._client)
+
+    async def test_list_mcps_empty(self) -> None:
+        """No MCPs registered → ``list_mcps`` returns an empty list."""
+        ws = DockerWorkspace(
+            workspace_id=self.workspace_id,
+            host_workdir=self.temp_dir.name,
+        )
+        try:
+            await ws.initialize()
+            self.assertListEqual(await ws.list_mcps(), [])
+        finally:
+            await ws.close()
+
+    async def test_list_tools_builtin(self) -> None:
+        """returns the six builtin tools backed by DockerBackend."""
+        from agentscope.tool._builtin import (
+            Bash,
+            Edit,
+            Glob,
+            Grep,
+            Read,
+            Write,
+        )
+        from agentscope.workspace._docker._docker_backend import DockerBackend
+
+        ws = DockerWorkspace(
+            workspace_id=self.workspace_id,
+            host_workdir=self.temp_dir.name,
+        )
+        try:
+            await ws.initialize()
+            tools = await ws.list_tools()
+            self.assertEqual(len(tools), 6)
+
+            expected_types = {Bash, Edit, Glob, Grep, Read, Write}
+            actual_types = {type(t) for t in tools}
+            self.assertSetEqual(actual_types, expected_types)
+
+            for tool in tools:
+                self.assertIsInstance(tool._backend, DockerBackend)
+        finally:
+            await ws.close()
+
+    async def test_workdir_persistence_across_restart(self) -> None:
+        """Same ``workspace_id`` + same ``workdir`` → state survives close.
+
+        Specifically: an offloaded session file written before ``close``
+        is still readable from the host mirror after a fresh
+        ``initialize`` (the new container re-bind-mounts the same host
+        workdir).
+        """
+        session_id = "persisted_session"
+        msg = UserMsg(name="user", content="durable line")
+
+        ws1 = DockerWorkspace(
+            workspace_id=self.workspace_id,
+            host_workdir=self.temp_dir.name,
+        )
+        await ws1.initialize()
+        await ws1.offload_context(session_id, [msg])
+        await ws1.close()
+
+        host_path = os.path.join(
+            self.temp_dir.name,
+            "sessions",
+            session_id,
+            "context.jsonl",
+        )
+        self.assertTrue(os.path.exists(host_path))
+
+        ws2 = DockerWorkspace(
+            workspace_id=self.workspace_id,
+            host_workdir=self.temp_dir.name,
+        )
+        try:
+            await ws2.initialize()
+            # The container mounts the same host dir; the file should
+            # still be visible via the host mirror.
+            self.assertTrue(os.path.exists(host_path))
+            async with aiofiles.open(host_path, "r") as f:
+                content = await f.read()
+            self.assertEqual(content.strip(), msg.model_dump_json())
+        finally:
+            await ws2.close()
+
+    async def test_reset_clears_sessions_and_data(self) -> None:
+        """``reset`` removes ``sessions/`` and ``data/`` (host-visible)."""
+        ws = DockerWorkspace(
+            workspace_id=self.workspace_id,
+            host_workdir=self.temp_dir.name,
+        )
+        try:
+            await ws.initialize()
+
+            # Seed both directories via offload_*.
+            session_id = "reset_session"
+            await ws.offload_context(
+                session_id,
+                [UserMsg(name="user", content="hi")],
+            )
+            await ws._offload_data_block(
+                DataBlock(
+                    source=Base64Source(
+                        data=base64.b64encode(b"x").decode(),
+                        media_type="text/plain",
+                    ),
+                    name="x",
+                ),
+            )
+            sessions_host = os.path.join(self.temp_dir.name, "sessions")
+            data_host = os.path.join(self.temp_dir.name, "data")
+            self.assertTrue(os.path.isdir(sessions_host))
+            self.assertTrue(os.path.isdir(data_host))
+
+            await ws.reset()
+            self.assertFalse(os.path.exists(sessions_host))
+            self.assertFalse(os.path.exists(data_host))
+        finally:
+            await ws.close()
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/workspace_e2b_test.py b/tests/workspace_e2b_test.py
new file mode 100644
index 0000000..2a5a8a7
--- /dev/null
+++ b/tests/workspace_e2b_test.py
@@ -0,0 +1,72 @@
+# -*- coding: utf-8 -*-
+"""Test cases for E2BWorkspace.
+
+The whole module is skipped when the ``E2B_API_KEY`` environment variable is
+not set, because every test requires a live E2B cloud sandbox.
+"""
+import os
+import unittest
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from agentscope.mcp import MCPClient, StdioMCPConfig
+from agentscope.workspace import E2BWorkspace
+
+
+# ── E2B availability check ─────────────────────────────────────────
+
+_E2B_API_KEY = os.getenv("E2B_API_KEY", "")
+_SKIP_REASON = "E2B_API_KEY environment variable is not set"
+
+
+# ── lifecycle tests ────────────────────────────────────────────────
+
+
+@unittest.skipUnless(_E2B_API_KEY, _SKIP_REASON)
+class TestE2BWorkspaceLifecycle(IsolatedAsyncioTestCase):
+    """Test cases for E2BWorkspace lifecycle and MCP integration.
+
+    Each test creates a real E2B cloud sandbox and tears it down
+    (``pause``) afterward.  The suite is skipped entirely when
+    ``E2B_API_KEY`` is absent so that CI runs without E2B credentials
+    are unaffected.
+    """
+
+    async def asyncSetUp(self) -> None:
+        """No shared setup — each test manages its own workspace."""
+
+    async def asyncTearDown(self) -> None:
+        """No shared teardown — each test closes its own workspace."""
+
+    async def test_initialize_and_list_mcps(self) -> None:
+        """``initialize`` starts the sandbox and ``list_mcps`` enumerates MCPs.
+
+        Verifies:
+        1. The workspace initializes without raising.
+        2. ``list_mcps`` returns at least the seeded MCP (browser-use).
+        3. Each MCP exposes at least one tool via ``list_raw_tools``.
+        4. ``close`` (sandbox pause) completes without raising.
+        """
+        workspace = E2BWorkspace(
+            api_key=_E2B_API_KEY,
+            default_mcps=[
+                MCPClient(
+                    name="browser-use",
+                    mcp_config=StdioMCPConfig(
+                        command="npx",
+                        args=["@playwright/mcp@latest"],
+                    ),
+                    is_stateful=True,
+                ),
+            ],
+        )
+
+        await workspace.initialize()
+
+        mcps = await workspace.list_mcps()
+        self.assertGreater(len(mcps), 0)
+
+        for mcp in mcps:
+            tools = await mcp.list_raw_tools()
+            self.assertGreater(len(tools), 0)
+
+        await workspace.close()
diff --git a/tests/workspace_k8s_test.py b/tests/workspace_k8s_test.py
new file mode 100644
index 0000000..8dac2ca
--- /dev/null
+++ b/tests/workspace_k8s_test.py
@@ -0,0 +1,420 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Integration tests for :class:`K8sWorkspace`.
+
+These tests exercise a real Kubernetes cluster (kind is used in CI).
+The whole module is skipped when either:
+
+* the current platform is not Linux, or
+* ``K8S_TEST_IMAGE`` is not set (the pre-baked test image name), or
+* ``kubectl`` is not on ``PATH`` (kind cluster not provisioned).
+
+Each test uses a fresh ``workspace_id`` so PVCs/Pods never collide, and
+``delete_pvc_on_close=True`` so no residue is left in the cluster.
+
+The pre-baked image (see ``tests/docker/k8s_workspace_test.Dockerfile``)
+ships the gateway script at ``GATEWAY_HOME``, so ``initialize()`` skips
+bootstrap and each test finishes in ~15 s.
+"""
+import os
+import shutil
+import sys
+import tempfile
+import unittest
+import uuid
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from agentscope.mcp import MCPClient, StdioMCPConfig
+from agentscope.workspace import K8sWorkspace
+from agentscope.workspace._k8s._constants import (
+    GATEWAY_HOME,
+    POD_WORKDIR,
+)
+
+# ── cluster availability check ────────────────────────────────────
+
+_TEST_IMAGE = os.getenv("K8S_TEST_IMAGE", "")
+_TEST_NAMESPACE = os.getenv("K8S_TEST_NAMESPACE", "agentscope")
+_KIND_AVAILABLE = (
+    sys.platform.startswith("linux")
+    and bool(_TEST_IMAGE)
+    and shutil.which("kubectl") is not None
+)
+_SKIP_REASON = (
+    "requires linux + K8S_TEST_IMAGE + kubectl (kind cluster). "
+    "See tests/docker/k8s_workspace_test.Dockerfile and the "
+    "``k8s-workspace-tests`` CI job."
+)
+
+
+def _new_workspace(**overrides: object) -> K8sWorkspace:
+    """Construct a K8sWorkspace pinned to the pre-baked test image.
+
+    Args:
+        **overrides:
+            Additional/replacement kwargs forwarded to
+            :class:`K8sWorkspace`.
+
+    Returns:
+        `K8sWorkspace`:
+            A workspace with a unique ``workspace_id``, tiny PVC, and
+            ``delete_pvc_on_close=True`` so tests never leak state.
+    """
+    kwargs: dict[str, object] = {
+        "workspace_id": f"test-{uuid.uuid4().hex[:8]}",
+        "image": _TEST_IMAGE,
+        "image_pull_policy": "Never",  # image is `kind load`-ed
+        "namespace": _TEST_NAMESPACE,
+        "storage_size": "100Mi",
+        "delete_pvc_on_close": True,
+    }
+    kwargs.update(overrides)
+    return K8sWorkspace(**kwargs)  # type: ignore[arg-type]
+
+
+def _write_skill_dir(root: str, name: str, description: str) -> str:
+    """Create a minimal, valid skill directory on the host.
+
+    Args:
+        root (`str`):
+            Parent directory for the new skill.
+        name (`str`):
+            Skill name; also used as directory basename and written
+            into the ``SKILL.md`` front matter.
+        description (`str`):
+            Skill description for the front matter.
+
+    Returns:
+        `str`:
+            Absolute path to the created skill directory.
+    """
+    skill_dir = os.path.join(root, name)
+    os.makedirs(skill_dir, exist_ok=True)
+    with open(
+        os.path.join(skill_dir, "SKILL.md"),
+        "w",
+        encoding="utf-8",
+    ) as f:
+        f.write(
+            f"---\nname: {name}\ndescription: {description}\n---\n\n"
+            f"# {name}\n\n{description}\n",
+        )
+    return skill_dir
+
+
+# ── happy-path: bootstrap + skills + mcps + backend all share ────
+# a single Pod to minimise total CI time. Each section below cleans
+# up whatever it added so subsequent sections start from a known
+# state. Destructive scenarios (reset, close) get their own class /
+# workspace further down.
+
+
+@unittest.skipUnless(_KIND_AVAILABLE, _SKIP_REASON)
+class TestK8sWorkspaceHappyPath(IsolatedAsyncioTestCase):
+    """Scenarios 1 + 2 + 3 + 7 exercised against a single Pod.
+
+    Every section restores the workspace to a clean state before the
+    next section runs, so ordering is not fragile — but ``unittest``
+    runs test methods alphabetically anyway and there is only one
+    test method here on purpose.
+    """
+
+    async def asyncSetUp(self) -> None:
+        """Start a single workspace + host-side scratch dir."""
+        # pylint: disable=consider-using-with
+        self._skills_src = tempfile.TemporaryDirectory()
+        self._ws = _new_workspace()
+        await self._ws.initialize()
+        self._backend = self._ws.get_backend()
+
+    async def asyncTearDown(self) -> None:
+        """Tear the workspace down and drop the scratch dir."""
+        try:
+            await self._ws.close()
+        finally:
+            self._skills_src.cleanup()
+
+    async def test_workspace_end_to_end(self) -> None:
+        """Cover bootstrap artefacts, skills CRUD, MCP CRUD + call, and
+        every public backend API against one Pod.
+
+        Sections:
+
+        1. **Bootstrap** — verify every workdir / gateway artefact.
+        2. **Skills**    — ``add_skill`` → ``list_skills`` → ``remove_skill``.
+        3. **MCPs**      — register a pure-Python MCP (``uvx
+           mcp-server-time``), list it, call ``list_raw_tools`` on
+           it, deregister.
+        4. **Backend**   — exec_shell (success / nonzero / cwd),
+           write_file + read_file roundtrip (binary, nested path),
+           file_exists, delete_path, join_path.
+        """
+        backend = self._backend
+        ws = self._ws
+
+        # ── 1. Bootstrap artefacts ───────────────────────────────
+        artefact_paths = [
+            f"{POD_WORKDIR}/data",
+            f"{POD_WORKDIR}/skills",
+            f"{POD_WORKDIR}/sessions",
+            f"{POD_WORKDIR}/.mcp",
+            f"{GATEWAY_HOME}/_mcp_gateway_app.py",
+            f"{GATEWAY_HOME}/_glob_helper.py",
+            f"{GATEWAY_HOME}/.venv/bin/python",
+        ]
+        artefact_state = {
+            p: await backend.file_exists(p) for p in artefact_paths
+        }
+        self.assertDictEqual(
+            artefact_state,
+            {p: True for p in artefact_paths},
+        )
+
+        # ── 2. Skills CRUD ───────────────────────────────────────
+        skill_path = _write_skill_dir(
+            self._skills_src.name,
+            "greeter",
+            "Says hi.",
+        )
+        self.assertListEqual(await ws.list_skills(), [])
+
+        await ws.add_skill(skill_path)
+        skills = await ws.list_skills()
+        self.assertEqual(len(skills), 1)
+        self.assertEqual(
+            (skills[0].name, skills[0].description, skills[0].dir),
+            ("greeter", "Says hi.", f"{POD_WORKDIR}/skills/greeter"),
+        )
+
+        await ws.remove_skill("greeter")
+        self.assertListEqual(await ws.list_skills(), [])
+
+        # ── 3. MCP CRUD + call (pure Python stdio MCP) ──────────
+        mcp_client = MCPClient(
+            name="time",
+            is_stateful=True,
+            mcp_config=StdioMCPConfig(
+                command="uvx",
+                args=["mcp-server-time"],
+            ),
+        )
+        self.assertListEqual(await ws.list_mcps(), [])
+
+        await ws.add_mcp(mcp_client)
+        mcps = await ws.list_mcps()
+        self.assertEqual(len(mcps), 1)
+        self.assertEqual(mcps[0].name, "time")
+
+        tools = await mcps[0].list_raw_tools()
+        self.assertGreater(len(tools), 0)
+
+        await ws.remove_mcp("time")
+        self.assertListEqual(await ws.list_mcps(), [])
+
+        # ── 4. Backend public API ───────────────────────────────
+        # 4a. exec_shell success
+        r_ok = await backend.exec_shell(["echo", "hello"])
+        self.assertEqual(
+            (r_ok.exit_code, r_ok.stdout.strip(), r_ok.ok()),
+            (0, b"hello", True),
+        )
+
+        # 4b. exec_shell non-zero exit + stderr
+        r_bad = await backend.exec_shell(
+            ["sh", "-c", "echo boom >&2; exit 3"],
+        )
+        self.assertEqual(
+            (r_bad.exit_code, r_bad.ok(), b"boom" in r_bad.stderr),
+            (3, False, True),
+        )
+
+        # 4c. exec_shell honours cwd
+        r_cwd = await backend.exec_shell(["pwd"], cwd=POD_WORKDIR)
+        self.assertEqual(
+            (r_cwd.exit_code, r_cwd.stdout.strip()),
+            (0, POD_WORKDIR.encode()),
+        )
+
+        # 4d. write_file → read_file roundtrip, binary safe
+        blob_path = f"{POD_WORKDIR}/data/blob.bin"
+        blob = bytes(range(256)) * 16  # 4 KiB, all byte values
+        await backend.write_file(blob_path, blob)
+        self.assertEqual(await backend.read_file(blob_path), blob)
+
+        # 4e. write_file mkdir -p
+        nested = f"{POD_WORKDIR}/data/nested/deeper/note.txt"
+        await backend.write_file(nested, b"nested")
+        self.assertEqual(await backend.read_file(nested), b"nested")
+
+        # 4f. read_file on missing path
+        with self.assertRaises(FileNotFoundError):
+            await backend.read_file(f"{POD_WORKDIR}/does_not_exist")
+
+        # 4g. file_exists reflects delete_path (files + directories)
+        tree_dir = f"{POD_WORKDIR}/data/tree"
+        tree_child = f"{tree_dir}/child.txt"
+        await backend.write_file(tree_child, b"child")
+        await backend.delete_path(blob_path)
+        await backend.delete_path(tree_dir)
+        self.assertDictEqual(
+            {
+                blob_path: await backend.file_exists(blob_path),
+                tree_dir: await backend.file_exists(tree_dir),
+            },
+            {blob_path: False, tree_dir: False},
+        )
+
+        # 4h. join_path is a pure string op
+        self.assertEqual(
+            backend.join_path("/workspace", "data", "x.txt"),
+            "/workspace/data/x.txt",
+        )
+
+
+# ── destructive: reset ───────────────────────────────────────────
+
+
+@unittest.skipUnless(_KIND_AVAILABLE, _SKIP_REASON)
+class TestK8sWorkspaceReset(IsolatedAsyncioTestCase):
+    """Scenario 5: ``reset`` wipes workspace state without killing the
+    Pod or the gateway. Isolated because it is destructive."""
+
+    async def asyncSetUp(self) -> None:
+        """Host-side temp dir for a seed skill."""
+        # pylint: disable=consider-using-with
+        self._skills_src = tempfile.TemporaryDirectory()
+
+    async def asyncTearDown(self) -> None:
+        """Drop the staging dir."""
+        self._skills_src.cleanup()
+
+    async def test_reset_clears_dirs_mcps_skills_but_keeps_gateway(
+        self,
+    ) -> None:
+        """After ``reset``: dirs empty, MCPs gone, skills gone,
+        gateway still alive.
+
+        Verifies:
+
+        1. Seed a skill file under ``skills/`` and a file under
+           ``sessions/``.
+        2. After ``reset``:
+           - ``list_skills`` and ``list_mcps`` return empty lists,
+           - ``sessions/`` and ``data/`` directories no longer exist,
+           - the gateway script under ``GATEWAY_HOME`` is untouched
+             (proves the Pod / gateway are still alive).
+        """
+        skill_path = _write_skill_dir(
+            self._skills_src.name,
+            "sample",
+            "sample skill",
+        )
+        ws = _new_workspace()
+        try:
+            await ws.initialize()
+            backend = ws.get_backend()
+
+            # Seed state.
+            await ws.add_skill(skill_path)
+            await backend.write_file(
+                f"{POD_WORKDIR}/sessions/s1/context.jsonl",
+                b'{"msg": "hi"}\n',
+            )
+            self.assertEqual(len(await ws.list_skills()), 1)
+
+            await ws.reset()
+
+            state_after = {
+                "skills": await ws.list_skills(),
+                "mcps": await ws.list_mcps(),
+                "sessions_exists": await backend.file_exists(
+                    f"{POD_WORKDIR}/sessions",
+                ),
+                "data_exists": await backend.file_exists(
+                    f"{POD_WORKDIR}/data",
+                ),
+                "gateway_alive": await backend.file_exists(
+                    f"{GATEWAY_HOME}/_mcp_gateway_app.py",
+                ),
+            }
+            self.assertDictEqual(
+                state_after,
+                {
+                    "skills": [],
+                    "mcps": [],
+                    "sessions_exists": False,
+                    "data_exists": False,
+                    "gateway_alive": True,
+                },
+            )
+        finally:
+            await ws.close()
+
+
+# ── destructive: close ───────────────────────────────────────────
+
+
+@unittest.skipUnless(_KIND_AVAILABLE, _SKIP_REASON)
+class TestK8sWorkspaceClose(IsolatedAsyncioTestCase):
+    """Scenario 4: ``close`` tears down cleanly and is idempotent.
+    Isolated because it terminates the workspace."""
+
+    async def test_close_is_idempotent_and_releases_backend(self) -> None:
+        """Two consecutive ``close`` calls succeed; backend is released.
+
+        Verifies:
+
+        1. After initialize, ``get_backend`` returns a backend.
+        2. First ``close`` succeeds.
+        3. Second ``close`` on the same workspace is a no-op (no
+           exception raised) — matches the docstring contract
+           "errors are swallowed so close is always safe to call".
+        """
+        ws = _new_workspace()
+        await ws.initialize()
+        self.assertIsNotNone(ws.get_backend())
+
+        await ws.close()
+        # Second close must not raise.
+        await ws.close()
+
+
+# ── local-only: get_instructions text ─────────────────────────────
+
+
+class TestK8sWorkspaceInstructions(IsolatedAsyncioTestCase):
+    """Scenario 6: ``get_instructions`` renders the workspace prompt.
+
+    Pure local check — no cluster needed, so *not* skip-guarded.
+    """
+
+    async def test_get_instructions_substitutes_workdir_in_template(
+        self,
+    ) -> None:
+        """Custom ``instructions`` template has ``{workdir}`` filled in."""
+        ws = K8sWorkspace(
+            workspace_id="prompt-only",
+            instructions="Workdir is {workdir}; nothing else.",
+        )
+        self.assertEqual(
+            await ws.get_instructions(),
+            f"Workdir is {POD_WORKDIR}; nothing else.",
+        )
+
+    async def test_get_instructions_default_template_mentions_workdir(
+        self,
+    ) -> None:
+        """Default template renders and mentions the Pod workdir."""
+        ws = K8sWorkspace(workspace_id="prompt-default")
+        text = await ws.get_instructions()
+        # Assert on the full rendered string as a golden of the default
+        # template — reviewers see intent at a glance.
+        self.assertIn(POD_WORKDIR, text)
+        self.assertIn("Kubernetes-based workspace", text)
+        self.assertIn("data/", text)
+        self.assertIn("skills/", text)
+        self.assertIn("sessions/", text)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/workspace_local_test.py b/tests/workspace_local_test.py
new file mode 100644
index 0000000..198a7dc
--- /dev/null
+++ b/tests/workspace_local_test.py
@@ -0,0 +1,1300 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Test cases for LocalWorkspace."""
+import os
+import json
+import base64
+import hashlib
+import tempfile
+from pathlib import Path
+from typing import Any
+from unittest.async_case import IsolatedAsyncioTestCase
+from dataclasses import asdict
+from urllib.parse import urlparse
+from urllib.request import url2pathname
+
+import aiofiles
+from utils import AnyString, MockModel
+from agentscope.agent import Agent, ContextConfig
+from agentscope.model import ChatResponse, StructuredResponse
+from agentscope.state import AgentState
+from agentscope.tool import Toolkit, ToolBase, ToolChunk
+from agentscope.permission import PermissionDecision, PermissionBehavior
+from agentscope.workspace import LocalWorkspace
+from agentscope.mcp import MCPClient, StdioMCPConfig
+from agentscope.message import (
+    Msg,
+    UserMsg,
+    AssistantMsg,
+    DataBlock,
+    Base64Source,
+    URLSource,
+    TextBlock,
+    ToolResultBlock,
+    ToolResultState,
+    ToolCallBlock,
+)
+
+
+class _LongResultTool(ToolBase):
+    """A mock tool that returns a long string result for offload testing."""
+
+    name: str = "long_result_tool"
+    description: str = "A tool that returns a long string."
+    input_schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {},
+        "required": [],
+    }
+    is_concurrency_safe: bool = True
+    is_read_only: bool = True
+    is_external_tool: bool = False
+    is_mcp: bool = False
+
+    async def check_permissions(
+        self,
+        *_args: Any,
+        **_kwargs: Any,
+    ) -> PermissionDecision:
+        """Always allow."""
+        return PermissionDecision(
+            behavior=PermissionBehavior.ALLOW,
+            decision_reason="Mock tool always allows",
+            message="Mock tool always allows",
+        )
+
+    async def __call__(self, **_kwargs: Any) -> ToolChunk:
+        """Return a long string result followed by a base64 data block, so we
+        can also verify base64 data offloading."""
+        return ToolChunk(
+            content=[
+                TextBlock(text="0" * 30000),
+                DataBlock(
+                    name="fake_image.png",
+                    source=Base64Source(
+                        data="AAECAwQF",
+                        media_type="image/png",
+                    ),
+                ),
+            ],
+            state=ToolResultState.SUCCESS,
+        )
+
+
+class TestLocalWorkspaceOffload(IsolatedAsyncioTestCase):
+    """Test cases for LocalWorkspace offload functionality."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up test fixtures."""
+        # pylint: disable=consider-using-with
+        self.temp_dir = tempfile.TemporaryDirectory()
+        self.workspace = LocalWorkspace(workdir=self.temp_dir.name)
+
+    async def asyncTearDown(self) -> None:
+        """Clean up test fixtures."""
+        self.temp_dir.cleanup()
+
+    async def test_offload_context_pure_text(self) -> None:
+        """Test offloading messages with pure text content.
+
+        This test verifies that:
+        1. Messages with string content are correctly offloaded
+        2. The offloaded file is created at the expected path
+        3. The file contains valid JSONL with all message fields preserved
+        """
+        session_id = "test_session_pure_text"
+        msgs = [
+            UserMsg(name="user", content="Hello, world!"),
+            AssistantMsg(name="assistant", content="Hi there!"),
+        ]
+
+        # Offload the messages
+        file_path = await self.workspace.offload_context(session_id, msgs)
+
+        # Verify the file was created at the expected path
+        expected_path = os.path.join(
+            self.temp_dir.name,
+            "sessions",
+            session_id,
+            "context.jsonl",
+        )
+        self.assertEqual(file_path, expected_path)
+        self.assertTrue(os.path.exists(file_path))
+
+        # Read and verify the offloaded messages
+        async with aiofiles.open(file_path, "r") as f:
+            content = await f.read()
+
+        lines = content.strip().split("\n")
+        self.assertEqual(len(lines), 2)
+
+        # Compare with expected JSON strings
+        expected_lines = [msg.model_dump_json() for msg in msgs]
+        self.assertListEqual(lines, expected_lines)
+
+    async def test_offload_context_multiple_calls(self) -> None:
+        """Test multiple calls to offload_context for the same session.
+
+        This test verifies that:
+        1. Multiple calls to offload_context append correctly to the file
+        2. Each message is on its own line (proper JSONL format)
+        3. No lines are concatenated together
+        """
+        session_id = "test_session_multiple"
+
+        # First batch of messages
+        msgs1 = [
+            UserMsg(name="user", content="First message"),
+            AssistantMsg(name="assistant", content="First response"),
+        ]
+
+        # Second batch of messages
+        msgs2 = [
+            UserMsg(name="user", content="Second message"),
+            AssistantMsg(name="assistant", content="Second response"),
+        ]
+
+        # Offload first batch
+        file_path = await self.workspace.offload_context(session_id, msgs1)
+
+        # Offload second batch
+        file_path2 = await self.workspace.offload_context(session_id, msgs2)
+
+        # Verify both calls return the same path
+        self.assertEqual(file_path, file_path2)
+
+        # Read and verify the offloaded messages
+        async with aiofiles.open(file_path, "r") as f:
+            content = await f.read()
+
+        lines = content.strip().split("\n")
+        self.assertEqual(len(lines), 4)
+
+        # Compare with expected JSON strings
+        expected_lines = [msg.model_dump_json() for msg in msgs1 + msgs2]
+        self.assertListEqual(lines, expected_lines)
+
+        # Verify each line is valid JSON
+        for line in lines:
+            msg = Msg.model_validate_json(line)
+            self.assertIsNotNone(msg)
+
+    async def test_offload_context_with_datablock(self) -> None:
+        """Test offloading messages with DataBlock content.
+
+        This test verifies that:
+        1. Messages with DataBlock (Base64Source) are correctly offloaded
+        2. DataBlock data is persisted to separate files
+        3. DataBlock source is converted from Base64Source to URLSource
+        4. The offloaded message file contains the updated DataBlock
+        """
+        session_id = "test_session_datablock"
+
+        # Create a test image data (1x1 red pixel PNG)
+        test_data = base64.b64encode(
+            b"\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\x01"
+            b"\x00\x00\x00\x01\x08\x02\x00\x00\x00\x90wS\xde",
+        ).decode()
+
+        data_block = DataBlock(
+            source=Base64Source(data=test_data, media_type="image/png"),
+            name="test_image",
+        )
+
+        msgs = [
+            UserMsg(
+                name="user",
+                content=[TextBlock(text="Check this image:"), data_block],
+            ),
+        ]
+
+        # Offload the messages
+        file_path = await self.workspace.offload_context(session_id, msgs)
+
+        # Verify the message file was created
+        self.assertTrue(os.path.exists(file_path))
+
+        # Read and verify the offloaded message
+        async with aiofiles.open(file_path, "r") as f:
+            content = await f.read()
+
+        loaded_msg = Msg.model_validate_json(content.strip())
+
+        # Verify the data file was created and extract the URL
+        self.assertIsInstance(loaded_msg.content, list)
+        self.assertEqual(len(loaded_msg.content), 2)
+        data_url = str(loaded_msg.content[1].source.url)
+        self.assertTrue(data_url.startswith("file://"))
+        # Convert file URL to local path (works on both Windows and Unix)
+        data_file_path = url2pathname(urlparse(data_url).path)
+        self.assertTrue(os.path.exists(data_file_path))
+
+        # Verify the data file contains the correct content
+        async with aiofiles.open(data_file_path, "rb") as f:
+            saved_data = await f.read()
+        self.assertEqual(saved_data, base64.b64decode(test_data))
+
+        # Build expected message with URLSource for comparison
+        # Use the actual IDs from loaded message to avoid UUID mismatch
+        expected_msg = UserMsg(
+            name="user",
+            content=[
+                TextBlock(
+                    text="Check this image:",
+                    id=loaded_msg.content[0].id,
+                ),
+                DataBlock(
+                    id=loaded_msg.content[1].id,
+                    source=loaded_msg.content[1].source,
+                    name="test_image",
+                ),
+            ],
+            id=loaded_msg.id,
+            created_at=loaded_msg.created_at,
+        )
+        self.assertEqual(
+            loaded_msg.model_dump_json(),
+            expected_msg.model_dump_json(),
+        )
+
+    async def test_offload_data_block_deduplication(self) -> None:
+        """Test that duplicate DataBlocks are deduplicated.
+
+        This test verifies that:
+        1. Multiple DataBlocks with the same content share the same file
+        2. Only one file is created for duplicate data
+        3. Both DataBlocks point to the same file path
+        """
+        # Create two DataBlocks with identical data
+        test_data = base64.b64encode(b"test content").decode()
+
+        data_block1 = DataBlock(
+            source=Base64Source(data=test_data, media_type="text/plain"),
+            name="file1",
+        )
+        data_block2 = DataBlock(
+            source=Base64Source(data=test_data, media_type="text/plain"),
+            name="file2",
+        )
+
+        # Offload both data blocks
+        result1 = await self.workspace._offload_data_block(data_block1)
+        result2 = await self.workspace._offload_data_block(data_block2)
+
+        # Verify both point to the same file by comparing source URLs
+        self.assertEqual(str(result1.source.url), str(result2.source.url))
+
+        # Verify the file exists
+        data_url = str(result1.source.url)
+        # Convert file URL to local path (works on both Windows and Unix)
+        data_file_path = url2pathname(urlparse(data_url).path)
+        self.assertTrue(os.path.exists(data_file_path))
+
+        # Verify only one file was created in the data directory
+        data_dir = os.path.join(self.temp_dir.name, "data")
+        files = os.listdir(data_dir)
+        self.assertEqual(len(files), 1)
+
+    async def test_offload_data_block_url_source(self) -> None:
+        """Test offloading DataBlock with URLSource.
+
+        This test verifies that:
+        1. DataBlock with URLSource is returned as-is
+        2. No file is created for URLSource DataBlocks
+        """
+        from pydantic import AnyUrl
+
+        data_block = DataBlock(
+            source=URLSource(
+                url=AnyUrl("https://example.com/image.png"),
+                media_type="image/png",
+            ),
+            name="remote_image",
+        )
+
+        # Offload the data block
+        result = await self.workspace._offload_data_block(data_block)
+
+        # Verify the data block is returned as-is by comparing full objects
+        self.assertDictEqual(result.model_dump(), data_block.model_dump())
+
+        # Verify no file was created in the data directory
+        data_dir = os.path.join(self.temp_dir.name, "data")
+        if os.path.exists(data_dir):
+            files = os.listdir(data_dir)
+            self.assertEqual(len(files), 0)
+
+    async def test_offload_tool_result_string(self) -> None:
+        """Test offloading tool result with string output.
+
+        This test verifies that:
+        1. Tool result with string output is correctly offloaded
+        2. The offloaded file is created at the expected path
+        3. The file contains the correct string content
+        """
+        session_id = "test_session_tool_result"
+        tool_result = ToolResultBlock(
+            id="tool_123",
+            name="test_tool",
+            output="Tool execution successful!",
+            state=ToolResultState.SUCCESS,
+        )
+
+        # Offload the tool result
+        file_path = await self.workspace.offload_tool_result(
+            session_id,
+            tool_result,
+        )
+
+        # Verify the file was created at the expected path
+        expected_path = os.path.join(
+            self.temp_dir.name,
+            "sessions",
+            session_id,
+            f"tool_result-{tool_result.id}.txt",
+        )
+        self.assertEqual(file_path, expected_path)
+        self.assertTrue(os.path.exists(file_path))
+
+        # Read and verify the content
+        async with aiofiles.open(file_path, "r") as f:
+            content = await f.read()
+
+        expected_content = "Tool execution successful!"
+        self.assertEqual(content, expected_content)
+
+    async def test_offload_tool_result_with_blocks(self) -> None:
+        """Test offloading tool result with TextBlock and DataBlock output.
+
+        This test verifies that:
+        1. Tool result with list of blocks is correctly offloaded
+        2. TextBlock content is extracted and written to file
+        3. DataBlock is offloaded and referenced in the output file
+        4. The output file contains the correct format
+        """
+        session_id = "test_session_tool_result_blocks"
+
+        # Create test data
+        test_data = base64.b64encode(b"test file content").decode()
+        data_block = DataBlock(
+            source=Base64Source(data=test_data, media_type="text/plain"),
+            name="output.txt",
+        )
+
+        tool_result = ToolResultBlock(
+            id="tool_456",
+            name="file_tool",
+            output=[
+                TextBlock(text="File created successfully: "),
+                data_block,
+            ],
+            state=ToolResultState.SUCCESS,
+        )
+
+        # Offload the tool result
+        file_path = await self.workspace.offload_tool_result(
+            session_id,
+            tool_result,
+        )
+
+        # Verify the file was created
+        self.assertTrue(os.path.exists(file_path))
+
+        # Read and verify the content
+        async with aiofiles.open(file_path, "r") as f:
+            content = await f.read()
+
+        # Verify the content structure (URL format varies by platform)
+        self.assertTrue(content.startswith("File created successfully: "))
+        self.assertIn("<data url='file://", content)
+        self.assertIn("name='output.txt'", content)
+        self.assertIn("media_type='text/plain'", content)
+        self.assertTrue(content.endswith("/>"))
+
+        # Extract and verify the data file exists
+        # Parse the URL from the content
+        import re
+
+        url_match = re.search(r"url='([^']+)'", content)
+        self.assertIsNotNone(url_match)
+        data_url = url_match.group(1)
+        # Convert file URL to local path (works on both Windows and Unix)
+        data_file_path = url2pathname(urlparse(data_url).path)
+        self.assertTrue(os.path.exists(data_file_path))
+
+
+class TestLocalWorkspaceSkills(IsolatedAsyncioTestCase):
+    """Test cases for LocalWorkspace skill management functionality."""
+
+    async def asyncSetUp(self) -> None:
+        """Set up test fixtures."""
+        # pylint: disable=consider-using-with
+        self.temp_dir = tempfile.TemporaryDirectory()
+        # pylint: disable=consider-using-with
+        self.test_skills_dir = tempfile.TemporaryDirectory()
+
+    async def asyncTearDown(self) -> None:
+        """Clean up test fixtures."""
+        self.temp_dir.cleanup()
+        self.test_skills_dir.cleanup()
+
+    def _create_test_skill(
+        self,
+        skill_name: str,
+        description: str,
+        additional_files: dict[str, str] | None = None,
+    ) -> str:
+        """Create a test skill directory with SKILL.md.
+
+        Args:
+            skill_name (`str`):
+                The name of the skill.
+            description (`str`):
+                The description of the skill.
+            additional_files (`dict[str, str] | None`, optional):
+                Additional files to create in the skill directory.
+                Keys are file names, values are file contents.
+
+        Returns:
+            `str`:
+                The path to the created skill directory.
+        """
+        skill_dir = os.path.join(self.test_skills_dir.name, skill_name)
+        os.makedirs(skill_dir, exist_ok=True)
+
+        # Create SKILL.md with frontmatter
+        skill_md_content = f"""---
+name: {skill_name}
+description: {description}
+---
+
+# {skill_name}
+
+{description}
+"""
+        with open(
+            os.path.join(skill_dir, "SKILL.md"),
+            "w",
+            encoding="utf-8",
+        ) as f:
+            f.write(skill_md_content)
+
+        # Create additional files if provided
+        if additional_files:
+            for filename, content in additional_files.items():
+                with open(
+                    os.path.join(skill_dir, filename),
+                    "w",
+                    encoding="utf-8",
+                ) as f:
+                    f.write(content)
+
+        return skill_dir
+
+    async def test_initialize_copy_skills(self) -> None:
+        """Test copying skills to workspace.
+
+        This test verifies that:
+        1. Skills are correctly copied from source paths to workspace
+        2. The .skills file is created with correct hash mappings
+        3. All skill files are preserved during copying
+        """
+        # Create test skills
+        skill1_dir = self._create_test_skill(
+            "test_skill_1",
+            "A test skill for testing",
+            {"tool.py": "def test_tool():\n    pass\n"},
+        )
+        skill2_dir = self._create_test_skill(
+            "test_skill_2",
+            "Another test skill",
+            {"helper.py": "def helper():\n    return 42\n"},
+        )
+
+        # Create workspace with skill paths
+        workspace = LocalWorkspace(
+            workdir=self.temp_dir.name,
+            skill_paths=[skill1_dir, skill2_dir],
+        )
+
+        # Initialize the workspace
+        await workspace.initialize()
+
+        # Verify skills were copied
+        skills_dir = os.path.join(self.temp_dir.name, "skills")
+        self.assertTrue(os.path.exists(skills_dir))
+
+        # Verify skill directories exist
+        skill1_target = os.path.join(skills_dir, "test_skill_1")
+        skill2_target = os.path.join(skills_dir, "test_skill_2")
+        self.assertTrue(os.path.exists(skill1_target))
+        self.assertTrue(os.path.exists(skill2_target))
+
+        # Verify SKILL.md files exist
+        self.assertTrue(
+            os.path.exists(os.path.join(skill1_target, "SKILL.md")),
+        )
+        self.assertTrue(
+            os.path.exists(os.path.join(skill2_target, "SKILL.md")),
+        )
+
+        # Verify additional files were copied
+        self.assertTrue(os.path.exists(os.path.join(skill1_target, "tool.py")))
+        self.assertTrue(
+            os.path.exists(os.path.join(skill2_target, "helper.py")),
+        )
+
+        # Verify .skills file was created with correct new structure
+        skills_hash_file = os.path.join(skills_dir, ".skills")
+        self.assertTrue(os.path.exists(skills_hash_file))
+
+        async with aiofiles.open(skills_hash_file, "r") as f:
+            skills_data = json.loads(await f.read())
+
+        # Verify top-level structure
+        self.assertIn("skills_dir_mtime", skills_data)
+        self.assertIn("skills", skills_data)
+
+        skills_index = skills_data["skills"]
+        self.assertEqual(len(skills_index), 2)
+
+        # Verify each entry has the correct structure
+        self.assertIn("test_skill_1", skills_index)
+        self.assertIn("test_skill_2", skills_index)
+        self.assertDictEqual(
+            {k: v["skill_name"] for k, v in skills_index.items()},
+            {"test_skill_1": "test_skill_1", "test_skill_2": "test_skill_2"},
+        )
+
+    async def test_initialize_skip_duplicate_skills(self) -> None:
+        """Test that duplicate skills are not copied again.
+
+        This test verifies that:
+        1. Skills are copied on first initialization
+        2. Running initialize again does not copy duplicate skills
+        3. The .skills file is not modified on second initialization
+        """
+        # Create test skill
+        skill_dir = self._create_test_skill(
+            "test_skill_dup",
+            "A test skill for duplication testing",
+        )
+
+        # Create workspace and initialize
+        workspace = LocalWorkspace(
+            workdir=self.temp_dir.name,
+            skill_paths=[skill_dir],
+        )
+        await workspace.initialize()
+
+        # Get the .skills file content after first initialization
+        skills_hash_file = os.path.join(
+            self.temp_dir.name,
+            "skills",
+            ".skills",
+        )
+        async with aiofiles.open(skills_hash_file, "r") as f:
+            hash_data_first = await f.read()
+
+        # Get modification time of the skill directory
+        skill_target = os.path.join(
+            self.temp_dir.name,
+            "skills",
+            "test_skill_dup",
+        )
+        mtime_first = os.path.getmtime(skill_target)
+
+        # Initialize again
+        await workspace.initialize()
+
+        # Verify .skills file is unchanged
+        async with aiofiles.open(skills_hash_file, "r") as f:
+            hash_data_second = await f.read()
+        self.assertEqual(hash_data_first, hash_data_second)
+
+        # Verify skill directory was not modified
+        mtime_second = os.path.getmtime(skill_target)
+        self.assertEqual(mtime_first, mtime_second)
+
+    async def test_initialize_deduplicate_skills(self) -> None:
+        """Test that duplicate skills in skill_paths are deduplicated.
+
+        This test verifies that:
+        1. When skill_paths contains duplicates (same hash), only one is copied
+        2. No concurrent copy conflicts occur
+        3. The .skills file contains only one entry for the duplicated skill
+        """
+        # Create a test skill
+        skill_dir = self._create_test_skill(
+            "test_skill_dedup",
+            "A test skill for deduplication testing",
+        )
+
+        # Create workspace with the same skill path listed multiple times
+        workspace = LocalWorkspace(
+            workdir=self.temp_dir.name,
+            skill_paths=[skill_dir, skill_dir, skill_dir],  # Same path 3 times
+        )
+
+        # Initialize the workspace
+        await workspace.initialize()
+
+        # Verify only one skill was copied
+        skills_dir = os.path.join(self.temp_dir.name, "skills")
+        skill_target = os.path.join(skills_dir, "test_skill_dedup")
+        self.assertTrue(os.path.exists(skill_target))
+
+        # Verify .skills file contains only one entry
+        skills_hash_file = os.path.join(skills_dir, ".skills")
+        self.assertTrue(os.path.exists(skills_hash_file))
+
+        async with aiofiles.open(skills_hash_file, "r") as f:
+            skills_data = json.loads(await f.read())
+
+        # Should have exactly one entry in the skills index
+        skills_index = skills_data["skills"]
+        self.assertEqual(len(skills_index), 1)
+        self.assertIn("test_skill_dedup", skills_index)
+        self.assertEqual(
+            skills_index["test_skill_dedup"]["skill_name"],
+            "test_skill_dedup",
+        )
+
+    async def test_initialize_invalid_skill(self) -> None:
+        """Test handling of invalid skills.
+
+        This test verifies that:
+        1. Skills without SKILL.md are not copied
+        2. Skills with invalid frontmatter are not copied
+        3. Valid skills are still copied correctly
+        """
+        # Create a valid skill
+        valid_skill_dir = self._create_test_skill(
+            "valid_skill",
+            "A valid test skill",
+        )
+
+        # Create an invalid skill without SKILL.md
+        invalid_skill_no_md = os.path.join(
+            self.test_skills_dir.name,
+            "invalid_no_md",
+        )
+        os.makedirs(invalid_skill_no_md, exist_ok=True)
+        with open(
+            os.path.join(invalid_skill_no_md, "tool.py"),
+            "w",
+            encoding="utf-8",
+        ) as f:
+            f.write("def tool():\n    pass\n")
+
+        # Create an invalid skill with malformed frontmatter
+        invalid_skill_bad_fm = os.path.join(
+            self.test_skills_dir.name,
+            "invalid_bad_fm",
+        )
+        os.makedirs(invalid_skill_bad_fm, exist_ok=True)
+        with open(
+            os.path.join(invalid_skill_bad_fm, "SKILL.md"),
+            "w",
+            encoding="utf-8",
+        ) as f:
+            f.write(
+                "---\nname: missing_description\n---\n\nNo description field!",
+            )
+
+        # Create workspace with all skill paths
+        workspace = LocalWorkspace(
+            workdir=self.temp_dir.name,
+            skill_paths=[
+                valid_skill_dir,
+                invalid_skill_no_md,
+                invalid_skill_bad_fm,
+            ],
+        )
+
+        # Initialize the workspace
+        await workspace.initialize()
+
+        # Verify only the valid skill was copied
+        skills_dir = os.path.join(self.temp_dir.name, "skills")
+        self.assertTrue(os.path.exists(skills_dir))
+
+        # Verify valid skill exists
+        valid_target = os.path.join(skills_dir, "valid_skill")
+        self.assertTrue(os.path.exists(valid_target))
+
+        # Verify invalid skills do not exist
+        invalid_target_no_md = os.path.join(skills_dir, "invalid_no_md")
+        invalid_target_bad_fm = os.path.join(skills_dir, "invalid_bad_fm")
+        self.assertFalse(os.path.exists(invalid_target_no_md))
+        self.assertFalse(os.path.exists(invalid_target_bad_fm))
+
+    async def test_list_skills(self) -> None:
+        """Test listing skills from workspace.
+
+        This test verifies that:
+        1. All skills in the workspace are correctly listed
+        2. Each skill has the correct name, description, and directory
+        3. The returned list matches the expected skills
+        """
+        # Create test skills
+        skill1_dir = self._create_test_skill(
+            "list_skill_1",
+            "First skill for listing",
+        )
+        skill2_dir = self._create_test_skill(
+            "list_skill_2",
+            "Second skill for listing",
+        )
+
+        # Create workspace and initialize
+        workspace = LocalWorkspace(
+            workdir=self.temp_dir.name,
+            skill_paths=[skill1_dir, skill2_dir],
+        )
+        await workspace.initialize()
+
+        # List skills
+        skills = await workspace.list_skills()
+
+        # Verify the number of skills
+        self.assertEqual(len(skills), 2)
+
+        # Sort skills by name for consistent comparison
+        skills_sorted = sorted(skills, key=lambda s: s.name)
+
+        # Build expected skills for comparison
+        expected_skills = [
+            {
+                "name": "list_skill_1",
+                "description": "First skill for listing",
+                "dir": skills_sorted[0].dir,  # Use actual dir path
+                "markdown": skills_sorted[0].markdown,  # Use actual markdown
+                "updated_at": skills_sorted[
+                    0
+                ].updated_at,  # Use actual timestamp
+            },
+            {
+                "name": "list_skill_2",
+                "description": "Second skill for listing",
+                "dir": skills_sorted[1].dir,  # Use actual dir path
+                "markdown": skills_sorted[1].markdown,  # Use actual markdown
+                "updated_at": skills_sorted[
+                    1
+                ].updated_at,  # Use actual timestamp
+            },
+        ]
+
+        # Compare full skill objects using dataclasses.asdict
+        actual_skills = [asdict(skill) for skill in skills_sorted]
+        self.assertListEqual(actual_skills, expected_skills)
+
+    async def test_list_skills_empty(self) -> None:
+        """Test listing skills when no skills exist.
+
+        This test verifies that:
+        1. An empty list is returned when no skills are in the workspace
+        2. No errors are raised when the skills directory doesn't exist
+        """
+        # Create workspace without initializing
+        workspace = LocalWorkspace(workdir=self.temp_dir.name)
+
+        # List skills (should return empty list)
+        skills = await workspace.list_skills()
+
+        # Verify empty list is returned
+        self.assertListEqual(skills, [])
+
+
+class TestLocalWorkspaceWithAgent(IsolatedAsyncioTestCase):
+    """Test the local workspace class offloading with the agent."""
+
+    async def test_offload_tool_result(self) -> None:
+        """Test integration with the agent when offloading tool result.
+
+        This test verifies that:
+        1. A long tool result is split into a reserved part (kept in context)
+           and an offloaded part (written to disk).
+        2. The reserved tool result block in the context is truncated and
+           contains a system reminder pointing to the offload file.
+        3. The offloaded file contains the truncated remainder.
+        4. A second reply with a fresh tool call produces a new offload file.
+        """
+        with tempfile.TemporaryDirectory() as workdir:
+            session_id = "test_session"
+            model = MockModel(stream=False)
+            agent = Agent(
+                name="Friday",
+                system_prompt="You're a helpful assistant named Friday.",
+                model=model,
+                toolkit=Toolkit(
+                    tools=[_LongResultTool()],
+                ),
+                context_config=ContextConfig(
+                    tool_result_limit=50,
+                ),
+                offloader=LocalWorkspace(
+                    workdir=workdir,
+                ),
+                state=AgentState(session_id=session_id),
+            )
+
+            model.set_responses(
+                mock_responses=[
+                    [
+                        ChatResponse(
+                            content=[
+                                ToolCallBlock(
+                                    id="1",
+                                    name="long_result_tool",
+                                    input="{}",
+                                ),
+                            ],
+                            is_last=True,
+                        ),
+                    ],
+                    [
+                        ChatResponse(
+                            content=[
+                                TextBlock(text="End_1."),
+                            ],
+                            is_last=True,
+                        ),
+                    ],
+                ],
+            )
+
+            await agent.reply()
+
+            # === Assert offload file content ===
+            offload_path_1 = os.path.join(
+                workdir,
+                "sessions",
+                session_id,
+                "tool_result-1.txt",
+            )
+            self.assertTrue(os.path.exists(offload_path_1))
+            async with aiofiles.open(offload_path_1, "r") as f:
+                offload_content = await f.read()
+
+            # The base64 payload is hashed with sha256 and persisted under
+            # `{workdir}/data/{hash}.{ext}` with the decoded bytes.
+            b64_data = "AAECAwQF"
+            data_hash = hashlib.sha256(b64_data.encode()).hexdigest()
+            data_file_path = os.path.join(
+                workdir,
+                "data",
+                f"{data_hash}.png",
+            )
+            self.assertTrue(os.path.exists(data_file_path))
+            async with aiofiles.open(data_file_path, "rb") as f:
+                self.assertEqual(await f.read(), base64.b64decode(b64_data))
+
+            # The full text is "0" * 30000 followed by a base64 DataBlock;
+            # tool_result_limit=50 reserves ~200 chars of text in context, the
+            # remaining 29800 chars + the DataBlock placeholder are offloaded.
+            data_url = Path(data_file_path).as_uri()
+            expected_offload_content = (
+                "0" * 29800 + f"<data url='{data_url}' name='fake_image.png' "
+                f"media_type='image/png'/>"
+            )
+            self.assertEqual(offload_content, expected_offload_content)
+
+            # === Assert context content ===
+            reminder_1 = (
+                "\n<<<TRUNCATED>>>\n<system-reminder>The remaining content "
+                "has been omitted for limited context. You can refer to the "
+                f"file in '{offload_path_1}' for the truncated content if "
+                "needed.</system-reminder>"
+            )
+            expected_first_msg = {
+                "id": AnyString(),
+                "name": "Friday",
+                "role": "assistant",
+                "content": [
+                    {
+                        "type": "tool_call",
+                        "id": "1",
+                        "name": "long_result_tool",
+                        "input": "{}",
+                        "state": "finished",
+                        "suggested_rules": [],
+                    },
+                    {
+                        "type": "tool_result",
+                        "id": "1",
+                        "name": "long_result_tool",
+                        "output": [
+                            {
+                                "type": "text",
+                                "text": "0" * 200 + reminder_1,
+                                "id": AnyString(),
+                            },
+                        ],
+                        "state": "success",
+                        "metadata": {},
+                    },
+                    {
+                        "type": "text",
+                        "text": "End_1.",
+                        "id": AnyString(),
+                    },
+                ],
+                "metadata": {},
+                "created_at": AnyString(),
+                "finished_at": None,
+                "usage": None,
+            }
+            self.assertListEqual(
+                [_.model_dump() for _ in agent.state.context],
+                [expected_first_msg],
+            )
+
+    async def test_offload_context(self) -> None:
+        """Test integration with the agent when offloading context.
+
+        This test triggers context compression twice in the same session and
+        verifies that:
+        1. The offload file ``context.jsonl`` is appended to (not
+           overwritten) across the two compressions.
+        2. When the compressed context contains a base64-encoded
+           ``DataBlock``, the binary payload is persisted to a separate
+           data file and the offloaded JSON line references that file via a
+           ``URLSource`` instead of embedding the base64 inline.
+        3. ``agent.state.summary`` is rewritten on every compression and
+           ends with a system-reminder pointing to the offload file.
+        4. ``agent.state.context`` only retains the latest assistant reply.
+
+        Note: compression triggers based on ``model.context_size`` together
+        with the default ``ContextConfig.trigger_ratio`` (0.8) — we set
+        ``context_size=100`` here so the threshold is just 80 tokens, and a
+        ~500-byte user message (~125 tokens) is enough to trigger
+        compression on each reply. The default ``ContextConfig`` is used.
+        """
+        with tempfile.TemporaryDirectory() as workdir:
+            session_id = "test_session_ctx"
+            model = MockModel(stream=False, context_size=100)
+            agent = Agent(
+                name="Friday",
+                system_prompt="You're Friday.",
+                model=model,
+                toolkit=Toolkit(),
+                offloader=LocalWorkspace(workdir=workdir),
+                state=AgentState(session_id=session_id),
+            )
+
+            # The mock structured response is reused across both compression
+            # calls (same summary fields each time).
+            model.set_structured_response(
+                StructuredResponse(
+                    content={
+                        "task_overview": "TASK",
+                        "current_state": "STATE",
+                        "important_discoveries": "DISCOVERIES",
+                        "next_steps": "NEXT",
+                        "context_to_preserve": "PRESERVE",
+                    },
+                ),
+            )
+
+            # Each reply yields a single final-text response (no tool calls).
+            model.set_responses(
+                mock_responses=[
+                    ChatResponse(
+                        content=[TextBlock(text="End_1.")],
+                        is_last=True,
+                    ),
+                    ChatResponse(
+                        content=[TextBlock(text="End_2.")],
+                        is_last=True,
+                    ),
+                ],
+            )
+
+            offload_path = os.path.join(
+                workdir,
+                "sessions",
+                session_id,
+                "context.jsonl",
+            )
+
+            # ===== First reply =====
+            # Build user_msg_a with **fixed** random fields (msg id, the
+            # content-block ids, timestamps) so the offloaded JSONL is a
+            # fully deterministic string we can assert against literally.
+            #
+            # Putting the DataBlock FIRST (before the long TextBlock) makes
+            # the boundary split include both blocks on the compress side,
+            # so the very first compression offloads a multimodal message —
+            # the DataBlock is rewritten to a URLSource alongside the
+            # original TextBlock, exercising the multimodal offload path.
+            b64_data = "AAECAwQF"
+            user_msg_a = UserMsg(
+                name="user",
+                content=[
+                    DataBlock(
+                        id="data_block_a",
+                        name="fake_image_a.png",
+                        source=Base64Source(
+                            data=b64_data,
+                            media_type="image/png",
+                        ),
+                    ),
+                    TextBlock(id="text_block_a", text="A" * 500),
+                ],
+                id="msg_a",
+                created_at="2026-01-01T00:00:00",
+                finished_at="2026-01-01T00:00:00",
+            )
+            await agent.reply(user_msg_a)
+
+            self.assertTrue(os.path.exists(offload_path))
+            async with aiofiles.open(offload_path, "r") as f:
+                content_after_first = await f.read()
+
+            # The DataBlock is persisted to ``{workdir}/data/`` as soon as
+            # it is included in an offloaded line — this happens during the
+            # first compression because both blocks land on the compress
+            # side of the boundary split.
+            data_hash = hashlib.sha256(b64_data.encode()).hexdigest()
+            data_file_path = os.path.join(
+                workdir,
+                "data",
+                f"{data_hash}.png",
+            )
+            self.assertTrue(os.path.exists(data_file_path))
+            async with aiofiles.open(data_file_path, "rb") as f:
+                self.assertEqual(await f.read(), base64.b64decode(b64_data))
+
+            # The single offloaded line carries user_msg_a with the
+            # DataBlock's source rewritten from ``Base64Source`` to
+            # ``URLSource`` (pointing at the persisted data file) while the
+            # TextBlock is preserved as-is. The expected JSONL is written
+            # literally so a developer can read off exactly what gets
+            # persisted; only the temp-dir-dependent file URL is
+            # interpolated via ``data_url``.
+            data_url = Path(data_file_path).as_uri()
+            expected_user_msg_a_offloaded_json = (
+                '{"name":"user","content":['
+                '{"type":"data","id":"data_block_a","source":'
+                '{"type":"url","url":"' + data_url + '",'
+                '"media_type":"image/png"},"name":"fake_image_a.png"},'
+                '{"type":"text","text":"' + "A" * 500 + '",'
+                '"id":"text_block_a"}'
+                '],"role":"user","id":"msg_a","metadata":{},'
+                '"created_at":"2026-01-01T00:00:00",'
+                '"finished_at":"2026-01-01T00:00:00","usage":null}'
+            )
+            self.assertEqual(
+                content_after_first,
+                expected_user_msg_a_offloaded_json + "\n",
+            )
+
+            # ``state.context`` after the first compression is empty
+            # (msgs_to_reserve is empty since both content blocks of
+            # user_msg_a went to the compress side). After reasoning,
+            # ``state.context[0]`` is the assistant's "End_1." reply. The
+            # assistant fields (msg id, text-block id, timestamps) are
+            # generated by the agent — we capture them here and substitute
+            # them into the expected string.
+            assistant_1 = agent.state.context[0]
+
+            # ===== Second reply =====
+            user_msg_b = UserMsg(
+                name="user",
+                content=[
+                    TextBlock(id="text_block_b", text="B" * 500),
+                ],
+                id="msg_b",
+                created_at="2026-01-02T00:00:00",
+                finished_at="2026-01-02T00:00:00",
+            )
+            await agent.reply(user_msg_b)
+
+            async with aiofiles.open(offload_path, "r") as f:
+                content_after_second = await f.read()
+
+            # The second compression offloads ``assistant_1`` and
+            # ``user_msg_b``. The file is appended to (mode="a"), so it
+            # now contains 3 lines: the multimodal user_msg_a from the
+            # first compression, plus assistant_1 and user_msg_b from the
+            # second.
+            expected_assistant_1_json = (
+                '{"name":"Friday","content":['
+                '{"type":"text","text":"End_1.","id":"'
+                + assistant_1.content[0].id
+                + '"}'
+                '],"role":"assistant","id":"' + assistant_1.id + '",'
+                '"metadata":{},"created_at":"' + assistant_1.created_at + '",'
+                '"finished_at":null,"usage":null}'
+            )
+            expected_user_msg_b_json = (
+                '{"name":"user","content":['
+                '{"type":"text","text":"' + "B" * 500 + '",'
+                '"id":"text_block_b"}'
+                '],"role":"user","id":"msg_b","metadata":{},'
+                '"created_at":"2026-01-02T00:00:00",'
+                '"finished_at":"2026-01-02T00:00:00","usage":null}'
+            )
+            self.assertEqual(
+                content_after_second,
+                expected_user_msg_a_offloaded_json
+                + "\n"
+                + expected_assistant_1_json
+                + "\n"
+                + expected_user_msg_b_json
+                + "\n",
+            )
+
+            # ``state.summary`` is rewritten on every compression, so the
+            # final value is just one rendering of the summary template plus
+            # one offload pointer (both compressions wrote to the same file).
+            expected_summary = (
+                "<system-info>Here is a summary of your previous work\n"
+                "# Task Overview\n"
+                "TASK\n\n"
+                "# Current State\n"
+                "STATE\n\n"
+                "# Important Discoveries\n"
+                "DISCOVERIES\n\n"
+                "# Next Steps\n"
+                "NEXT\n\n"
+                "# Context to Preserve\n"
+                "PRESERVE</system-info>\n"
+                f"<system-reminder>The compressed context is offloaded "
+                f"to '{offload_path}', you can refer to it when needed."
+                f"</system-reminder>"
+            )
+            self.assertEqual(agent.state.summary, expected_summary)
+
+            # ``state.context`` only retains the latest assistant text;
+            # everything else has been offloaded.
+            expected_second_assistant = {
+                "id": AnyString(),
+                "name": "Friday",
+                "role": "assistant",
+                "content": [
+                    {
+                        "type": "text",
+                        "text": "End_2.",
+                        "id": AnyString(),
+                    },
+                ],
+                "metadata": {},
+                "created_at": AnyString(),
+                "finished_at": None,
+                "usage": None,
+            }
+            self.assertListEqual(
+                [_.model_dump() for _ in agent.state.context],
+                [expected_second_assistant],
+            )
+
+
+class TestLocalWorkspaceMCPInit(IsolatedAsyncioTestCase):
+    """Test MCP loading error handling in LocalWorkspace.initialize().
+
+    Covers:
+    - Invalid entries in persisted .mcp are skipped (not crashing)
+    - Stateful MCP connection failures are skipped (not crashing)
+    - Valid MCPs still load despite invalid neighbours
+    """
+
+    async def asyncSetUp(self) -> None:
+        """Set up test fixtures."""
+        # pylint: disable=consider-using-with
+        self.temp_dir = tempfile.TemporaryDirectory()
+
+    async def asyncTearDown(self) -> None:
+        """Clean up test fixtures."""
+        self.temp_dir.cleanup()
+
+    async def _write_mcp_file(self, entries: list[dict]) -> str:
+        """Write a list of MCP config dicts to ``<workdir>/.mcp``.
+
+        Args:
+            entries: List of raw MCP config dicts.
+
+        Returns:
+            The path to the written file.
+        """
+        mcp_file = os.path.join(self.temp_dir.name, ".mcp")
+        async with aiofiles.open(mcp_file, "w", encoding="utf-8") as f:
+            await f.write(json.dumps(entries, indent=2, ensure_ascii=False))
+        return mcp_file
+
+    @staticmethod
+    def _make_http_mcp(name: str) -> dict:
+        """Return a valid stateless HTTP MCP entry."""
+        return {
+            "name": name,
+            "is_stateful": False,
+            "mcp_config": {
+                "type": "http_mcp",
+                "url": "http://localhost:19999/nonexistent",
+            },
+            "enable_tools": None,
+            "disable_tools": None,
+            "execution_timeout": None,
+        }
+
+    @staticmethod
+    def _make_bad_stdio_mcp(name: str) -> dict:
+        """Return an invalid STDIO MCP entry (is_stateful=False)."""
+        return {
+            "name": name,
+            "is_stateful": False,
+            "mcp_config": {
+                "type": "stdio_mcp",
+                "command": "nonexistent_cmd",
+            },
+            "enable_tools": None,
+            "disable_tools": None,
+            "execution_timeout": None,
+        }
+
+    # -----------------------------------------------------------------
+    #  persisted .mcp
+    # -----------------------------------------------------------------
+
+    async def test_initialize_skips_bad_entry_keeps_good(self) -> None:
+        """A persisted .mcp with one bad entry should skip it and still
+        load the valid entry."""
+        await self._write_mcp_file(
+            [
+                self._make_bad_stdio_mcp("bad_one"),
+                self._make_http_mcp("good_one"),
+            ],
+        )
+
+        ws = LocalWorkspace(workdir=self.temp_dir.name)
+        await ws.initialize()
+
+        mcps = await ws.list_mcps()
+        names = [m.name for m in mcps]
+        self.assertIn("good_one", names)
+        self.assertNotIn("bad_one", names)
+
+    # -----------------------------------------------------------------
+    #  default_mcps + connect failure
+    # -----------------------------------------------------------------
+
+    async def test_initialize_connect_failure_removes_mcp(self) -> (None):
+        """A stateful MCP whose connect() raises should not crash
+        initialize() and should be removed from the MCP list."""
+        ws = LocalWorkspace(
+            workdir=self.temp_dir.name,
+            default_mcps=[
+                MCPClient(
+                    name="will_fail_connect",
+                    is_stateful=True,
+                    mcp_config=StdioMCPConfig(
+                        command="nonexistent_command_xyz",
+                    ),
+                ),
+            ],
+        )
+        await ws.initialize()
+        self.assertTrue(ws.is_alive)
+        names = [m.name for m in await ws.list_mcps()]
+        self.assertNotIn("will_fail_connect", names)
diff --git a/tests/workspace_opensandbox_test.py b/tests/workspace_opensandbox_test.py
new file mode 100644
index 0000000..893c6df
--- /dev/null
+++ b/tests/workspace_opensandbox_test.py
@@ -0,0 +1,73 @@
+# -*- coding: utf-8 -*-
+"""Test cases for OpenSandboxWorkspace.
+
+The whole module is skipped when the ``OPENSANDBOX_DOMAIN`` environment
+variable is not set, because every test requires a live OpenSandbox
+service.
+"""
+import os
+import unittest
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from agentscope.mcp import MCPClient, StdioMCPConfig
+from agentscope.workspace import OpenSandboxWorkspace
+
+
+# ── OpenSandbox availability check ─────────────────────────────────
+
+_DOMAIN = os.getenv("OPENSANDBOX_DOMAIN", "")
+_API_KEY = os.getenv("OPENSANDBOX_API_KEY", "")
+_SKIP_REASON = "OPENSANDBOX_DOMAIN environment variable is not set"
+
+
+# ── lifecycle tests ────────────────────────────────────────────────
+
+
+@unittest.skipUnless(_DOMAIN, _SKIP_REASON)
+class TestOpenSandboxWorkspaceLifecycle(IsolatedAsyncioTestCase):
+    """Test cases for OpenSandboxWorkspace lifecycle and MCP integration.
+
+    Each test creates a real OpenSandbox sandbox and tears it down
+    (``pause``) afterward. The suite is skipped entirely when
+    ``OPENSANDBOX_DOMAIN`` is absent so that CI runs without OpenSandbox
+    access are unaffected.
+    """
+
+    async def test_initialize_and_list_mcps(self) -> None:
+        """``initialize`` starts the sandbox and ``list_mcps`` enumerates MCPs.
+
+        Verifies:
+        1. The workspace initializes without raising.
+        2. ``list_mcps`` returns at least the seeded MCP (browser-use).
+        3. Each MCP exposes at least one tool via ``list_raw_tools``.
+        4. ``close`` (sandbox pause) completes without raising.
+        """
+        workspace = OpenSandboxWorkspace(
+            domain=_DOMAIN,
+            api_key=_API_KEY,
+            default_mcps=[
+                MCPClient(
+                    name="browser-use",
+                    mcp_config=StdioMCPConfig(
+                        command="npx",
+                        args=["@playwright/mcp@latest"],
+                    ),
+                    is_stateful=True,
+                ),
+            ],
+        )
+
+        await workspace.initialize()
+
+        mcps = await workspace.list_mcps()
+        self.assertGreater(len(mcps), 0)
+
+        for mcp in mcps:
+            tools = await mcp.list_raw_tools()
+            self.assertGreater(len(tools), 0)
+
+        await workspace.close()
+
+
+if __name__ == "__main__":
+    unittest.main()