@zleap-ai/dsh-sag 0.1.0

package/lib/tools/search.js

@@ -0,0 +1,107 @@
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { presentSearchCall } from '../presentation.js';
+import { localInputError, localOperation, requireToolCapability } from './local.js';
+import { SEARCH_OUTPUT_SCHEMA, renderSearch } from './output.js';
+const LOCAL_SEARCH_OUTPUT_SCHEMA = {
+    type: 'object', additionalProperties: false, properties: {
+        query: { type: 'string', required: true },
+        evidences: { type: 'array', required: true, items: {
+                type: 'object', additionalProperties: false, properties: {
+                    evidenceRef: { type: 'string', required: true }, sourceId: { type: 'string', required: true },
+                    sourceName: { oneOf: [{ type: 'string' }, { type: 'null' }], required: true },
+                    chunkId: { type: 'string', required: true }, title: { type: 'string', required: true },
+                    excerpt: { type: 'string', required: true }, score: { type: 'number', required: true }, rank: { type: 'integer', required: true },
+                },
+            } },
+    },
+};
+function renderLocalSearch(value) {
+    const result = value;
+    if (result.evidences.length === 0)
+        return 'No SAG evidence matched the query.';
+    return result.evidences.map((evidence, index) => `${index + 1}. [${evidence.sourceName ?? evidence.sourceId}] ${evidence.title} (score ${evidence.score.toFixed(3)})\n   ${evidence.excerpt}\n   evidence_ref: ${evidence.evidenceRef}`).join('\n\n');
+}
+function searchResult(value) {
+    if (value === null || typeof value !== 'object' || !('evidences' in value))
+        throw new Error('SAG runtime returned the wrong search result type');
+    return value;
+}
+function createEmbeddedSearchTool(client, config) {
+    const allowed = new Set(config.namespaces.map(namespace => namespace.id));
+    const labels = new Map(config.namespaces.map(namespace => [namespace.id, namespace.label]));
+    return defineTool({
+        name: 'sag_search',
+        description: 'Search configured embedded SAG namespaces and return evidence_ref values for follow-up sag_read calls.',
+        parameters: {
+            query: { type: 'string', required: true, description: 'Natural-language or identifier search query.' },
+            namespaces: { type: 'array', items: { type: 'string' }, description: 'Optional configured namespace ids.' },
+            mode: { type: 'string', enum: ['fast', 'precise'], description: 'Embedded retrieval expansion mode.' },
+            limit: { type: 'integer', description: 'Maximum evidence items requested.' },
+        },
+        output: { schema: SEARCH_OUTPUT_SCHEMA, render: (_args, value) => [{ type: 'text', text: renderSearch(value, labels) }] },
+        timeoutMs: config.requestTimeoutMs,
+        isConcurrencySafe: () => true,
+        async execute(args, exec) {
+            const query = args.query.trim();
+            if (!query)
+                throw new Error('sag_search query must not be empty');
+            const namespaces = args.namespaces ?? config.namespaces.map(namespace => namespace.id);
+            if (namespaces.length === 0 || namespaces.some(namespace => !allowed.has(namespace)))
+                throw new Error('sag_search namespaces must be configured');
+            const requestedLimit = args.limit ?? config.maxResults;
+            if (!Number.isInteger(requestedLimit) || requestedLimit < 1)
+                throw new Error('sag_search limit must be positive');
+            return searchResult(await client.request('search', {
+                query, namespaces: [...new Set(namespaces)], mode: args.mode ?? config.defaultMode,
+                limit: Math.min(requestedLimit, config.maxResults),
+            }, exec.signal));
+        },
+        presentCall: args => presentSearchCall(args),
+    });
+}
+function createLocalSearchTool(manager, config) {
+    return defineTool({
+        name: 'sag_search',
+        description: 'Search one or more local SAG knowledge bases and return opaque evidence_ref values for sag_read.',
+        parameters: {
+            query: { type: 'string', required: true, description: 'Natural-language or identifier search query.' },
+            source_ids: { type: 'array', items: { type: 'string' }, description: 'Optional local SAG knowledge-base ids.' },
+            strategy: { type: 'string', enum: ['vector', 'multi', 'multi_es_fast'], description: 'SAG search strategy.' },
+            limit: { type: 'integer', description: 'Maximum evidence items, from 1 through 50.' },
+        },
+        output: { schema: LOCAL_SEARCH_OUTPUT_SCHEMA, render: (_args, value) => [{ type: 'text', text: renderLocalSearch(value) }] },
+        timeoutMs: config.requestTimeoutMs,
+        isConcurrencySafe: () => true,
+        execute(args, exec) {
+            return localOperation(manager, exec.signal, async (connection) => {
+                requireToolCapability(connection, 'sag_search');
+                const query = args.query.trim();
+                if (!query)
+                    localInputError('sag_search query must not be empty');
+                if (args.limit !== undefined && (!Number.isInteger(args.limit) || args.limit < 1 || args.limit > 50))
+                    localInputError('sag_search limit must be an integer from 1 to 50');
+                const sourceIds = args.source_ids?.map(value => value.trim()).filter(Boolean);
+                if (args.source_ids !== undefined && sourceIds?.length === 0)
+                    localInputError('sag_search source_ids must contain a knowledge-base id');
+                const result = await connection.gateway.search({
+                    query,
+                    ...(sourceIds === undefined ? {} : { sourceIds: [...new Set(sourceIds)] }),
+                    ...(args.limit === undefined ? {} : { topK: args.limit }),
+                    ...(args.strategy === undefined ? {} : { strategy: args.strategy }),
+                }, exec.signal);
+                return { query: result.query, evidences: result.evidences.map(evidence => ({
+                        evidenceRef: evidence.evidenceRef, sourceId: evidence.sourceId, sourceName: evidence.sourceName, chunkId: evidence.chunkId,
+                        title: evidence.heading || evidence.sourceName || evidence.chunkId, excerpt: evidence.content, score: evidence.score, rank: evidence.rank,
+                    })) };
+            });
+        },
+        presentCall: args => presentSearchCall(args),
+    });
+}
+/** Build the mode-specific model-facing SAG search tool. */
+export function createSearchTool(client, config) {
+    return config.mode === 'embedded'
+        ? createEmbeddedSearchTool(client, config)
+        : createLocalSearchTool(client, config);
+}
+//# sourceMappingURL=search.js.map

package/lib/tools/sources.d.ts

@@ -0,0 +1,5 @@
+import type { ResolvedLocalConfig } from '../config.js';
+import { type ConnectionManager } from './local.js';
+/** Build source-list and source-creation tools for local SAG. */
+export declare function createSourceTools(manager: ConnectionManager, config: ResolvedLocalConfig): readonly [import("@deepseek-ai/dsh-tools").ToolDefinition, import("@deepseek-ai/dsh-tools").ToolDefinition];
+//# sourceMappingURL=sources.d.ts.map

package/lib/tools/sources.js

@@ -0,0 +1,61 @@
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { jsonRender, localInputError, localOperation, requireToolCapability } from './local.js';
+const SOURCE = {
+    type: 'object', additionalProperties: false, properties: {
+        id: { type: 'string', required: true }, name: { type: 'string', required: true },
+        description: { type: 'string' }, status: { type: 'string' },
+        documentCount: { type: 'integer' }, chunkCount: { type: 'integer' },
+    },
+};
+function sourceValue(source) {
+    return {
+        id: source.id, name: source.name,
+        ...(typeof source.description === 'string' ? { description: source.description } : {}),
+        ...(typeof source.status === 'string' ? { status: source.status } : {}),
+        ...(typeof source.documentCount === 'number' ? { documentCount: source.documentCount } : {}),
+        ...(typeof source.chunkCount === 'number' ? { chunkCount: source.chunkCount } : {}),
+    };
+}
+/** Build source-list and source-creation tools for local SAG. */
+export function createSourceTools(manager, config) {
+    const list = defineTool({
+        name: 'sag_list_sources',
+        description: 'List local SAG knowledge bases with stable ids for search, upload, and document operations.',
+        parameters: {},
+        output: {
+            schema: { type: 'object', additionalProperties: false, properties: { sources: { type: 'array', required: true, items: SOURCE } } },
+            render: (_args, value) => jsonRender(value),
+        },
+        timeoutMs: config.requestTimeoutMs,
+        isConcurrencySafe: () => true,
+        async execute(_args, exec) {
+            return localOperation(manager, exec.signal, async (connection) => {
+                requireToolCapability(connection, 'sag_list_sources');
+                return { sources: (await connection.gateway.listSources(exec.signal)).map(sourceValue) };
+            });
+        },
+        presentCall: () => ({ card: 'generic', title: 'List SAG knowledge bases', kind: 'read' }),
+    });
+    const create = defineTool({
+        name: 'sag_create_source',
+        description: 'Create a local SAG knowledge base that can receive uploaded files or directly ingested text.',
+        parameters: {
+            name: { type: 'string', required: true, description: 'Knowledge-base name.' },
+            description: { type: 'string', description: 'Optional description.' },
+        },
+        output: { schema: SOURCE, render: (_args, value) => jsonRender(value) },
+        timeoutMs: config.requestTimeoutMs,
+        async execute(args, exec) {
+            return localOperation(manager, exec.signal, async (connection) => {
+                requireToolCapability(connection, 'sag_create_source');
+                const name = args.name.trim();
+                if (!name)
+                    localInputError('sag_create_source name must not be empty');
+                return sourceValue(await connection.gateway.createSource({ name, ...(args.description === undefined ? {} : { description: args.description }) }, exec.signal));
+            });
+        },
+        presentCall: args => ({ card: 'generic', title: 'Create SAG knowledge base', kind: 'edit', rawInput: args.name }),
+    });
+    return [list, create];
+}
+//# sourceMappingURL=sources.js.map

package/lib/tools/status.d.ts

@@ -0,0 +1,5 @@
+import type { ResolvedLocalConfig } from '../config.js';
+import { type ConnectionManager } from './local.js';
+/** Build a read-only summary of the current local SAG connection. */
+export declare function createStatusTool(manager: ConnectionManager, config: ResolvedLocalConfig): import("@deepseek-ai/dsh-tools").ToolDefinition;
+//# sourceMappingURL=status.d.ts.map

package/lib/tools/status.js

@@ -0,0 +1,28 @@
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { jsonRender, localOperation } from './local.js';
+const STATUS_OUTPUT = {
+    type: 'object', additionalProperties: false, properties: {
+        status: { type: 'string', required: true },
+        name: { type: 'string', required: true },
+        sourceCount: { type: 'integer', required: true },
+        capabilities: { type: 'array', required: true, items: { type: 'string' } },
+    },
+};
+/** Build a read-only summary of the current local SAG connection. */
+export function createStatusTool(manager, config) {
+    return defineTool({
+        name: 'sag_status',
+        description: 'Check the local SAG connection and report its public capabilities without exposing credentials.',
+        parameters: {},
+        output: { schema: STATUS_OUTPUT, render: (_args, value) => jsonRender(value) },
+        timeoutMs: config.requestTimeoutMs,
+        isConcurrencySafe: () => true,
+        async execute(_args, exec) {
+            return localOperation(manager, exec.signal, async (connection) => {
+                return { status: 'ready', name: connection.descriptor.name, sourceCount: connection.sourceCount, capabilities: [...connection.capabilities.capabilities] };
+            });
+        },
+        presentCall: () => ({ card: 'generic', title: 'Check SAG status', kind: 'fetch' }),
+    });
+}
+//# sourceMappingURL=status.js.map

package/lib/tools/upload.d.ts

@@ -0,0 +1,6 @@
+import type { FileSystem } from '@deepseek-ai/dsh-fs';
+import type { ResolvedLocalConfig } from '../config.js';
+import { type ConnectionManager } from './local.js';
+/** Build a bounded file-upload tool that reads exclusively through dsh FS. */
+export declare function createUploadTool(manager: ConnectionManager, config: ResolvedLocalConfig, fs: FileSystem): import("@deepseek-ai/dsh-tools").ToolDefinition;
+//# sourceMappingURL=upload.d.ts.map

package/lib/tools/upload.js

@@ -0,0 +1,68 @@
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { jsonRender, localInputError, localOperation, requireToolCapability, selectSource } from './local.js';
+const ACCEPTED_OUTPUT = {
+    type: 'object', additionalProperties: false, properties: {
+        accepted: { type: 'boolean', required: true }, documentId: { type: 'string', required: true },
+        sourceId: { type: 'string', required: true }, status: { type: 'string', required: true },
+    },
+};
+function basename(path) {
+    return path.split(/[\\/]/).at(-1) ?? path;
+}
+function extension(filename) {
+    const index = filename.lastIndexOf('.');
+    return index < 0 ? '' : filename.slice(index + 1).toLowerCase();
+}
+function contentType(ext) {
+    if (ext === 'md' || ext === 'markdown')
+        return 'text/markdown';
+    if (ext === 'txt')
+        return 'text/plain';
+    if (ext === 'json')
+        return 'application/json';
+    if (ext === 'pdf')
+        return 'application/pdf';
+    return 'application/octet-stream';
+}
+/** Build a bounded file-upload tool that reads exclusively through dsh FS. */
+export function createUploadTool(manager, config, fs) {
+    return defineTool({
+        name: 'sag_upload_file',
+        description: 'Upload one admitted local file to a SAG knowledge base and return its asynchronous processing status.',
+        parameters: {
+            path: { type: 'string', required: true, description: 'File path resolved through the dsh filesystem.' },
+            source_id: { type: 'string', description: 'Target knowledge-base id; omitted only when a default or single source exists.' },
+        },
+        output: { schema: ACCEPTED_OUTPUT, render: (_args, value) => jsonRender(value) },
+        timeoutMs: config.requestTimeoutMs,
+        async execute(args, exec) {
+            return localOperation(manager, exec.signal, async (connection) => {
+                requireToolCapability(connection, 'sag_upload_file');
+                const upload = connection.capabilities.upload;
+                if (upload === undefined)
+                    localInputError('This SAG version does not provide documents.upload limits. Upgrade SAG and retry.');
+                const sourceId = await selectSource(connection, args.source_id, exec.signal);
+                const target = await fs.resolve(args.path, { signal: exec.signal });
+                const info = await fs.stat(target, exec.signal);
+                if (info?.type !== 'file')
+                    localInputError('sag_upload_file 只能上传普通文件。');
+                const filename = basename(target.displayPath);
+                const ext = extension(filename);
+                const allowed = upload.extensions.map(value => value.toLowerCase());
+                if (!allowed.includes(ext))
+                    localInputError(`SAG 不允许 .${ext || '(无扩展名)'} 文件；可用扩展名：${allowed.join('、')}`);
+                const sagLimit = upload.maxMb * 1024 * 1024;
+                const limit = Math.min(sagLimit, config.maxUploadBytes);
+                if (info.size !== undefined && info.size > limit)
+                    localInputError(`文件超过上传上限 ${Math.floor(limit / 1024 / 1024)} MiB。`);
+                const bytes = await fs.readBytes(target, exec.signal, limit);
+                if (bytes.length > limit)
+                    localInputError(`文件超过上传上限 ${Math.floor(limit / 1024 / 1024)} MiB。`);
+                const document = await connection.gateway.uploadFile({ sourceId, filename, contentType: contentType(ext), bytes }, exec.signal);
+                return { accepted: true, documentId: document.id, sourceId, status: document.status ?? 'pending' };
+            });
+        },
+        presentCall: args => ({ card: 'generic', title: 'Upload file to SAG', kind: 'edit', rawInput: args.path, locations: [{ path: args.path }] }),
+    });
+}
+//# sourceMappingURL=upload.js.map

package/package.json

@@ -0,0 +1,96 @@
+{
+  "name": "@zleap-ai/dsh-sag",
+  "description": "Local SAG personal knowledge base plugin for DeepSeek Harness",
+  "version": "0.1.0",
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "dsh-plugin",
+    "sag",
+    "knowledge-base"
+  ],
+  "homepage": "https://github.com/Zleap-AI/dsh-sag#readme",
+  "bugs": {
+    "url": "https://github.com/Zleap-AI/dsh-sag/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Zleap-AI/dsh-sag.git"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "bin": {
+    "dsh-sag": "./lib/dsh-sag-cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/**/*.js",
+    "lib/**/*.d.ts",
+    "cordis.patch.yml",
+    "runtime",
+    "scripts/setup-runtime.mjs",
+    "docs/embedded.md",
+    "THIRD_PARTY_NOTICES",
+    "CHANGELOG.md",
+    "README.md",
+    "README.zh.md",
+    "LICENSE"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "3.18.1",
+    "@modelcontextprotocol/sdk": "^1.12.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-credentials": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-credentials-local": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-fs": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-llm": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-session": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-settings": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-settings-file": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-subprocess": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-subprocess-local": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-tools": "0.1.1-rc.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.1",
+    "@deepseek-ai/dsh-credentials": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-credentials-local": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-fs": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-llm": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-session": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-settings": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-settings-file": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-subprocess": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-subprocess-local": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-tools": "0.1.1-rc.2",
+    "@types/node": "^24.3.0",
+    "typescript": "^5.9.2"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node ../../scripts/build-cli.mjs && node ../../scripts/sync-runtime.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/runtime/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling>=1.27,<2"]
+build-backend = "hatchling.build"
+
+[project]
+name = "dsh-sag-runtime"
+version = "0.1.0"
+description = "Managed zleap-sag sidecar for the dsh-sag plugin"
+requires-python = ">=3.11"
+dependencies = [
+  "pydantic>=2.5,<3",
+  "zleap-sag==0.10.0",
+]
+
+[project.scripts]
+dsh-sag-runtime = "dsh_sag_runtime.__main__:main"
+
+[dependency-groups]
+dev = [
+  "pytest>=8.4,<9",
+  "pytest-asyncio>=1.1,<2",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/dsh_sag_runtime"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

package/runtime/src/dsh_sag_runtime/__init__.py

@@ -0,0 +1,3 @@
+"""Managed zleap-sag runtime for the dsh-sag plugin."""
+
+__version__ = "0.1.0"

package/runtime/src/dsh_sag_runtime/__main__.py

@@ -0,0 +1,80 @@
+"""stdio entrypoint for the managed dsh-sag runtime."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import importlib.metadata
+import sys
+from typing import BinaryIO, TextIO
+
+from zleap.sag import EngineConfig
+
+from .engines import EnginePool
+from .evidence import EvidenceRefCodec
+from .protocol import REQUIRED_ENGINE_VERSION, decode_request, encode_response
+from .read import ReadAdapter
+from .search import SearchAdapter
+from .server import RuntimeServer
+
+
+async def run_stdio(server: RuntimeServer, reader: BinaryIO, writer: BinaryIO, diagnostics: TextIO) -> None:
+    """Serve requests until stdin closes, keeping stdout protocol-only."""
+    write_lock = asyncio.Lock()
+    tasks: set[asyncio.Task[None]] = set()
+
+    async def process(frame: bytes) -> None:
+        try:
+            request = decode_request(frame.rstrip(b"\r\n"))
+            response = await server.accept(request)
+            if response is not None:
+                encoded = encode_response(response)
+                async with write_lock:
+                    writer.write(encoded)
+                    writer.flush()
+        except Exception as error:
+            print(f"dsh-sag-runtime rejected a frame: {type(error).__name__}", file=diagnostics, flush=True)
+
+    try:
+        while frame := await asyncio.to_thread(reader.readline):
+            task = asyncio.create_task(process(frame))
+            tasks.add(task)
+            task.add_done_callback(tasks.discard)
+        if tasks:
+            await asyncio.gather(*tasks, return_exceptions=True)
+    finally:
+        await server.aclose()
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(prog="dsh-sag-runtime")
+    parser.add_argument("--env-file", required=True)
+    parser.add_argument("--namespace", action="append", required=True)
+    parser.add_argument("--max-read-engines", type=int, default=4)
+    parser.add_argument("--max-results", type=int, default=20)
+    parser.add_argument("--max-excerpt-chars", type=int, default=1200)
+    parser.add_argument("--max-read-chars", type=int, default=40_000)
+    return parser.parse_args(argv)
+
+
+async def async_main(argv: list[str] | None = None) -> None:
+    args = parse_args(argv)
+    engine_version = importlib.metadata.version("zleap-sag")
+    if engine_version != REQUIRED_ENGINE_VERSION:
+        raise RuntimeError(f"zleap-sag {REQUIRED_ENGINE_VERSION} is required")
+    namespaces = tuple(dict.fromkeys(args.namespace))
+    config = EngineConfig.from_env(args.env_file)
+    pool = EnginePool(config, set(namespaces), max_read_engines=args.max_read_engines)
+    codec = EvidenceRefCodec(set(namespaces))
+    search = SearchAdapter(pool, codec, set(namespaces), max_results=args.max_results, max_excerpt_chars=args.max_excerpt_chars)
+    read = ReadAdapter(pool, codec, max_read_chars=args.max_read_chars, max_events=20)
+    server = RuntimeServer(pool, search, read, namespaces, engine_version=engine_version)
+    await run_stdio(server, sys.stdin.buffer, sys.stdout.buffer, sys.stderr)
+
+
+def main() -> None:
+    asyncio.run(async_main())
+
+
+if __name__ == "__main__":
+    main()

package/runtime/src/dsh_sag_runtime/engines.py

@@ -0,0 +1,139 @@
+"""Owned zleap-sag engine lifecycle with a bounded read-engine LRU."""
+
+from __future__ import annotations
+
+import asyncio
+from collections import OrderedDict
+from collections.abc import AsyncIterator, Callable
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+
+class Engine(Protocol):
+    async def start(self) -> None: ...
+    async def aclose(self) -> None: ...
+    async def health(self) -> Any: ...
+
+
+EngineFactory = Callable[[object, str | None], Engine]
+
+
+def _default_factory(config: object, namespace: str | None) -> Engine:
+    from zleap.sag import DataEngine
+
+    return DataEngine(config, data_source_id=namespace)  # type: ignore[arg-type]
+
+
+@dataclass(slots=True)
+class _ReadEntry:
+    engine: Engine
+    active: int = 0
+
+
+class EnginePool:
+    """Own one search engine and at most `max_read_engines` namespace engines."""
+
+    def __init__(
+        self,
+        config: object,
+        namespaces: set[str] | frozenset[str],
+        *,
+        max_read_engines: int,
+        factory: EngineFactory = _default_factory,
+    ) -> None:
+        if max_read_engines < 1:
+            raise ValueError("max_read_engines must be positive")
+        self._config = config
+        self._namespaces = frozenset(namespaces)
+        self._max_read_engines = max_read_engines
+        self._factory = factory
+        self._condition = asyncio.Condition()
+        self._search: Engine | None = None
+        self._reads: OrderedDict[str, _ReadEntry] = OrderedDict()
+        self._closed = False
+
+    async def start(self) -> None:
+        async with self._condition:
+            if self._closed:
+                raise RuntimeError("engine pool is closed")
+            if self._search is not None:
+                return
+            engine = self._factory(self._config, None)
+            try:
+                await engine.start()
+            except BaseException:
+                await engine.aclose()
+                raise
+            self._search = engine
+
+    async def search_engine(self) -> Engine:
+        async with self._condition:
+            if self._closed:
+                raise RuntimeError("engine pool is closed")
+            if self._search is None:
+                raise RuntimeError("engine pool is not started")
+            return self._search
+
+    @asynccontextmanager
+    async def read_engine(self, namespace_id: str) -> AsyncIterator[Engine]:
+        if namespace_id not in self._namespaces:
+            raise ValueError("namespace is not configured")
+        entry: _ReadEntry
+        async with self._condition:
+            while True:
+                if self._closed:
+                    raise RuntimeError("engine pool is closed")
+                existing = self._reads.get(namespace_id)
+                if existing is not None:
+                    entry = existing
+                    entry.active += 1
+                    self._reads.move_to_end(namespace_id)
+                    break
+                if len(self._reads) >= self._max_read_engines:
+                    idle_namespace = next((name for name, candidate in self._reads.items() if candidate.active == 0), None)
+                    if idle_namespace is None:
+                        await self._condition.wait()
+                        continue
+                    idle = self._reads.pop(idle_namespace)
+                    await idle.engine.aclose()
+                engine = self._factory(self._config, namespace_id)
+                try:
+                    await engine.start()
+                except BaseException:
+                    await engine.aclose()
+                    raise
+                entry = _ReadEntry(engine=engine, active=1)
+                self._reads[namespace_id] = entry
+                break
+        try:
+            yield entry.engine
+        finally:
+            async with self._condition:
+                entry.active -= 1
+                self._condition.notify_all()
+
+    async def health(self) -> Any:
+        return await (await self.search_engine()).health()
+
+    async def capabilities(self) -> Any:
+        engine = await self.search_engine()
+        return engine.capabilities()  # type: ignore[attr-defined]
+
+    async def aclose(self) -> None:
+        async with self._condition:
+            if self._closed:
+                return
+            self._closed = True
+            self._condition.notify_all()
+            while any(entry.active for entry in self._reads.values()):
+                await self._condition.wait()
+            engines = [entry.engine for entry in self._reads.values()]
+            if self._search is not None:
+                engines.insert(0, self._search)
+            self._reads.clear()
+            self._search = None
+        results = await asyncio.gather(*(engine.aclose() for engine in engines), return_exceptions=True)
+        failures = [result for result in results if isinstance(result, BaseException)]
+        if failures:
+            raise ExceptionGroup("failed to close SAG engines", failures)