perf(agent-runner): improve session registry and orchestrator efficiency

- Add pre-computed _authorized_ids (frozenset) at session registration for O(1) lookup
- Refactor is_resource_allowed() from linear search to set membership check
- Add thread-safe locking to get_session_registry() singleton
- Cache _session_registry and _state_store references in orchestrator __init__
- Add asyncio.gather() for parallel resource building in AgentResourceBuilder
- Create shared test fixtures in tests/unit_tests/agent/conftest.py
- Update test files to import from shared conftest.py

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

src/langbot/pkg/agent/runner/__init__.py

@@ -16,6 +16,7 @@ from .resource_builder import AgentResourceBuilder
 from .result_normalizer import AgentResultNormalizer
 from .orchestrator import AgentRunOrchestrator
 from .config_migration import ConfigMigration
+from .session_registry import AgentRunSessionRegistry, AgentRunSession, get_session_registry
 
 __all__ = [
     'AgentRunnerDescriptor',
@@ -33,4 +34,7 @@ __all__ = [
     'AgentResultNormalizer',
     'AgentRunOrchestrator',
     'ConfigMigration',
+    'AgentRunSessionRegistry',
+    'AgentRunSession',
+    'get_session_registry',
 ]

src/langbot/pkg/agent/runner/config_migration.py

@@ -72,7 +72,7 @@ class ConfigMigration:
         pipeline_config: dict[str, typing.Any],
         runner_id: str,
     ) -> dict[str, typing.Any]:
-        """Resolve runner instance configuration from pipeline configuration.
+        """Resolve runner binding configuration from pipeline configuration.
 
         Priority:
         1. New format: ai.runner_config[runner_id]

src/langbot/pkg/agent/runner/context_builder.py

@@ -10,6 +10,7 @@ from langbot_plugin.api.entities.builtin.pipeline import query as pipeline_query
 from ...core import app
 from .descriptor import AgentRunnerDescriptor
 from .config_migration import ConfigMigration
+from .state_store import get_state_store
 
 
 # Internal models for SDK v1 context protocol matching SDK v1 resources.py
@@ -41,6 +42,14 @@ class AgentInput(typing.TypedDict):
     attachments: list[dict[str, typing.Any]]
 
 
+class AgentRunState(typing.TypedDict):
+    """Agent run state with 4 scopes."""
+    conversation: dict[str, typing.Any]
+    actor: dict[str, typing.Any]
+    subject: dict[str, typing.Any]
+    runner: dict[str, typing.Any]
+
+
 # SDK v1 Protocol resource models - matching langbot-plugin-sdk/resources.py
 
 
@@ -100,7 +109,11 @@ class AgentRuntimeContext(typing.TypedDict):
 
 
 class AgentRunContextV1(typing.TypedDict):
-    """SDK v1 AgentRunContext per PROTOCOL_V1.md."""
+    """SDK v1 AgentRunContext per PROTOCOL_V1.md.
+
+    Note: The 'config' field contains the binding config from ai.runner_config[runner_id],
+    which is Pipeline's configuration for this specific runner binding (not plugin instance config).
+    """
     run_id: str
     trigger: AgentTrigger
     conversation: ConversationContext | None
@@ -109,9 +122,11 @@ class AgentRunContextV1(typing.TypedDict):
     subject: dict[str, typing.Any] | None  # Reserved for EBA
     messages: list[dict[str, typing.Any]]
     input: AgentInput
+    params: dict[str, typing.Any]
     resources: AgentResources
+    state: AgentRunState
     runtime: AgentRuntimeContext
-    config: dict[str, typing.Any]
+    config: dict[str, typing.Any]  # Binding config from ai.runner_config[runner_id]
 
 
 class AgentRunContextBuilder:
@@ -123,13 +138,25 @@ class AgentRunContextBuilder:
     - Build conversation context from session
     - Convert messages to SDK format
     - Build input from user_message and message_chain
+    - Build params from query.variables with filtering
+    - Build state snapshot from state_store
     - Set resources from AgentResourceBuilder result
     - Build runtime context with host info, trace_id, deadline
-    - Set config from runner instance configuration
+    - Set config from runner binding configuration (ai.runner_config[runner_id])
     """
 
     ap: app.Application
 
+    # Params filtering rules
+    # Exclude variables starting with underscore (internal)
+    INTERNAL_PREFIX = '_'
+
+    # Exclude variables with sensitive naming patterns
+    SENSITIVE_PATTERNS = ('secret', 'token', 'key', 'password', 'credential', 'api_key', 'apikey')
+
+    # Exclude permission/control variables
+    PERMISSION_VARS = ('_pipeline_bound_plugins', '_authorized', '_permission')
+
     def __init__(self, ap: app.Application):
         self.ap = ap
 
@@ -178,7 +205,16 @@ class AgentRunContextBuilder:
         # Build messages
         messages = self._build_messages(query)
 
-        # Get runner config
+        # Build params from query.variables with filtering
+        params = self._build_params(query)
+
+        # Build state snapshot from state_store
+        state_store = get_state_store()
+        state: AgentRunState = state_store.build_snapshot(query, descriptor)
+
+        # Get runner binding config from ai.runner_config[runner_id]
+        # This is Pipeline's configuration for this specific runner binding,
+        # passed through AgentRunContext.config to the runner
         runner_config = ConfigMigration.resolve_runner_config(
             query.pipeline_config,
             descriptor.id,
@@ -207,7 +243,9 @@ class AgentRunContextBuilder:
             'subject': None,  # Reserved for EBA
             'messages': messages,
             'input': input,
+            'params': params,
             'resources': resources,
+            'state': state,
             'runtime': runtime,
             'config': runner_config,
         }
@@ -251,4 +289,72 @@ class AgentRunContextBuilder:
             for msg in query.messages:
                 messages.append(msg.model_dump(mode='json'))
 
-        return messages
+        return messages
+
+    def _build_params(self, query: pipeline_query.Query) -> dict[str, typing.Any]:
+        """Build params from query.variables with filtering.
+
+        Filtering rules:
+        1. Exclude variables starting with underscore (internal)
+        2. Exclude variables with sensitive naming patterns (secret, token, key, password)
+        3. Exclude permission/control variables
+        4. Keep only JSON-serializable values
+
+        Args:
+            query: Pipeline query
+
+        Returns:
+            Filtered params dict
+        """
+        params: dict[str, typing.Any] = {}
+
+        if not query.variables:
+            return params
+
+        for key, value in query.variables.items():
+            # Filter internal variables (starting with underscore)
+            if key.startswith(self.INTERNAL_PREFIX):
+                continue
+
+            # Filter sensitive naming patterns
+            key_lower = key.lower()
+            if any(pattern in key_lower for pattern in self.SENSITIVE_PATTERNS):
+                continue
+
+            # Filter permission variables
+            if any(key == perm_var or key.startswith(perm_var) for perm_var in self.PERMISSION_VARS):
+                continue
+
+            # Keep only JSON-serializable values
+            if self._is_json_serializable(value):
+                params[key] = value
+
+        return params
+
+    def _is_json_serializable(self, value: typing.Any) -> bool:
+        """Check if value is JSON-serializable.
+
+        Note: set is NOT JSON-serializable. json.dumps({"x": {1}}) fails.
+        Only list and tuple are allowed as collection types.
+
+        Args:
+            value: Value to check
+
+        Returns:
+            True if JSON-serializable, False otherwise
+        """
+        if value is None:
+            return True
+        if isinstance(value, (str, int, float, bool)):
+            return True
+        # Only allow list and tuple, NOT set (set is not JSON-serializable)
+        if isinstance(value, (list, tuple)):
+            return all(self._is_json_serializable(item) for item in value)
+        if isinstance(value, dict):
+            return all(
+                isinstance(k, str) and self._is_json_serializable(v)
+                for k, v in value.items()
+            )
+        # Pydantic models and other complex types are not directly serializable
+        # as params (they may have internal structure not meant for runners)
+        return False

src/langbot/pkg/agent/runner/orchestrator.py

@@ -13,6 +13,8 @@ from .registry import AgentRunnerRegistry
 from .context_builder import AgentRunContextBuilder, AgentRunContextV1
 from .resource_builder import AgentResourceBuilder
 from .result_normalizer import AgentResultNormalizer
+from .state_store import get_state_store, RunnerScopedStateStore
+from .session_registry import get_session_registry, AgentRunSessionRegistry
 from .config_migration import ConfigMigration
 from .errors import (
     RunnerNotFoundError,
@@ -46,6 +48,10 @@ class AgentRunOrchestrator:
 
     result_normalizer: AgentResultNormalizer
 
+    # Cached singleton references (set in __init__)
+    _session_registry: AgentRunSessionRegistry
+    _state_store: RunnerScopedStateStore
+
     def __init__(
         self,
         ap: app.Application,
@@ -56,6 +62,9 @@ class AgentRunOrchestrator:
         self.context_builder = AgentRunContextBuilder(ap)
         self.resource_builder = AgentResourceBuilder(ap)
         self.result_normalizer = AgentResultNormalizer(ap)
+        # Cache singleton references to avoid per-request getter calls
+        self._session_registry = get_session_registry()
+        self._state_store = get_state_store()
 
     async def run_from_query(
         self,
@@ -93,12 +102,33 @@ class AgentRunOrchestrator:
         # Build context
         context = await self.context_builder.build_context(query, descriptor, resources)
 
-        # Run via plugin connector
-        async for result_dict in self._invoke_runner(descriptor, context):
-            # Normalize result
-            result = await self.result_normalizer.normalize(result_dict, descriptor)
-            if result is not None:
-                yield result
+        # Register session for proxy action permission validation
+        run_id = context['run_id']
+        await self._session_registry.register(
+            run_id=run_id,
+            runner_id=descriptor.id,
+            query_id=query.query_id,
+            plugin_identity=descriptor.get_plugin_id(),
+            resources=resources,
+        )
+
+        try:
+            # Run via plugin connector
+            async for result_dict in self._invoke_runner(descriptor, context):
+                # Handle state.updated first - consume before normalizer
+                if result_dict.get('type') == 'state.updated':
+                    self._handle_state_updated(result_dict, query, descriptor)
+                    # Pass to normalizer for logging, but don't yield to pipeline
+                    await self.result_normalizer.normalize(result_dict, descriptor)
+                    continue
+
+                # Normalize result for other types
+                result = await self.result_normalizer.normalize(result_dict, descriptor)
+                if result is not None:
+                    yield result
+        finally:
+            # Unregister session after run completes (success or error)
+            await self._session_registry.unregister(run_id)
 
     async def _invoke_runner(
         self,
@@ -155,4 +185,48 @@ class AgentRunOrchestrator:
         Returns:
             Runner ID string, or None
         """
-        return ConfigMigration.resolve_runner_id(query.pipeline_config)
+        return ConfigMigration.resolve_runner_id(query.pipeline_config)
+
+    def _handle_state_updated(
+        self,
+        result_dict: dict[str, typing.Any],
+        query: pipeline_query.Query,
+        descriptor: AgentRunnerDescriptor,
+    ) -> None:
+        """Handle state.updated result - apply to state store.
+
+        Args:
+            result_dict: Raw result dict with type='state.updated'
+            query: Pipeline query
+            descriptor: Runner descriptor
+        """
+        data = result_dict.get('data', {})
+
+        # Extract scope (default to 'conversation' for backward compat)
+        scope = data.get('scope', 'conversation')
+
+        # Extract key and value
+        key = data.get('key')
+        value = data.get('value')
+
+        if not key:
+            self.ap.logger.warning(
+                f'Runner {descriptor.id} state.updated missing key, ignoring'
+            )
+            return
+
+        # Apply update to state store
+        success = self._state_store.apply_update(
+            query=query,
+            descriptor=descriptor,
+            scope=scope,
+            key=key,
+            value=value,
+            logger=self.ap.logger,
+        )
+
+        if success:
+            self.ap.logger.debug(
+                f'Runner {descriptor.id} state.updated: scope={scope}, key={key}, value={value}'
+            )
+        # Invalid scope is already logged by state_store.apply_update

src/langbot/pkg/agent/runner/resource_builder.py

@@ -1,6 +1,7 @@
 """Agent resource builder for constructing authorized resources."""
 from __future__ import annotations
 
+import asyncio
 import typing
 
 from ...core import app
@@ -68,10 +69,12 @@ class AgentResourceBuilder:
         from .config_migration import ConfigMigration
         runner_config = ConfigMigration.resolve_runner_config(query.pipeline_config, descriptor.id)
 
-        # Build each resource category
-        models = await self._build_models(manifest_perms, query)
-        tools = await self._build_tools(manifest_perms, bound_plugins, bound_mcp_servers, query)
-        knowledge_bases = await self._build_knowledge_bases(manifest_perms, runner_config, query)
+        # Build each resource category in parallel
+        models, tools, knowledge_bases = await asyncio.gather(
+            self._build_models(manifest_perms, query),
+            self._build_tools(manifest_perms, bound_plugins, bound_mcp_servers, query),
+            self._build_knowledge_bases(manifest_perms, runner_config, query),
+        )
         storage = self._build_storage(manifest_perms)
 
         return {
@@ -104,11 +107,10 @@ class AgentResourceBuilder:
         try:
             model = await self.ap.model_mgr.get_model_by_uuid(model_uuid)
             if model and model.model_entity:
-                # Use SDK v1 field names: model_id, model_type, provider
                 models.append({
                     'model_id': model_uuid,
-                    'model_type': model.model_entity.model_type,
-                    'provider': model.provider_entity.name if hasattr(model, 'provider_entity') else None,
+                    'model_type': getattr(model.model_entity, 'model_type', None),
+                    'provider': getattr(model.provider_entity, 'name', None) if hasattr(model, 'provider_entity') else None,
                 })
         except Exception:
             pass

src/langbot/pkg/agent/runner/result_normalizer.py

@@ -108,9 +108,13 @@ class AgentResultNormalizer:
             return None
 
         elif result_type == 'state.updated':
-            # Log for telemetry, don't yield
+            # Log for telemetry, don't yield to pipeline
+            # Orchestrator already handles the actual state_store.apply_update
+            scope = data.get('scope', 'conversation')  # Default for backward compat
+            key = data.get('key', 'unknown')
+            value_repr = repr(data.get('value', '...'))[:100]  # Truncate for log
             self.ap.logger.debug(
-                f'Runner {descriptor.id} state updated: {data.get("key", "unknown")}={data.get("value", "...")}'
+                f'Runner {descriptor.id} state.updated logged: scope={scope}, key={key}, value={value_repr}'
             )
             return None
 

src/langbot/pkg/agent/runner/session_registry.py

@@ -0,0 +1,217 @@
+"""Agent run session registry for proxy action permission validation."""
+from __future__ import annotations
+
+import asyncio
+import typing
+import time
+import threading
+
+from .context_builder import AgentResources
+
+
+class AgentRunSessionStatus(typing.TypedDict):
+    """Status tracking for agent run session."""
+    started_at: int
+    last_activity_at: int
+
+
+class AgentRunSession(typing.TypedDict):
+    """Session for an active agent runner execution.
+
+    Stored in AgentRunSessionRegistry for proxy action permission validation.
+
+    Fields:
+        run_id: Unique run identifier (UUID from AgentRunContext)
+        runner_id: Runner descriptor ID (plugin:author/name/runner)
+        query_id: Pipeline query ID
+        plugin_identity: Plugin identifier (author/name) of the runner
+        resources: Authorized resources for this run (from AgentResources)
+        status: Session status tracking
+        _authorized_ids: Pre-computed authorized resource IDs for O(1) lookup
+    """
+    run_id: str
+    runner_id: str
+    query_id: int | None
+    plugin_identity: str  # author/name
+    resources: AgentResources
+    status: AgentRunSessionStatus
+    _authorized_ids: dict[str, set[str]]  # Pre-computed sets for O(1) lookup
+
+
+class AgentRunSessionRegistry:
+    """Registry for active agent run sessions.
+
+    Host-owned registry for tracking active AgentRunner executions.
+    Used by proxy actions in handler.py to validate resource access.
+
+    Key: run_id (UUID from AgentRunContext)
+    Value: AgentRunSession with authorized resources
+
+    Thread-safe via asyncio.Lock.
+    """
+
+    _sessions: dict[str, AgentRunSession]
+    _lock: asyncio.Lock
+
+    def __init__(self):
+        self._sessions = {}
+        self._lock = asyncio.Lock()
+
+    async def register(
+        self,
+        run_id: str,
+        runner_id: str,
+        query_id: int | None,
+        plugin_identity: str,
+        resources: AgentResources,
+    ) -> None:
+        """Register a new agent run session.
+
+        Args:
+            run_id: Unique run identifier
+            runner_id: Runner descriptor ID
+            query_id: Pipeline query ID
+            plugin_identity: Plugin identifier (author/name)
+            resources: Authorized resources for this run
+        """
+        now = int(time.time())
+
+        # Pre-compute authorized resource IDs for O(1) lookup
+        authorized_ids: dict[str, set[str]] = {
+            'model': {m.get('model_id') for m in resources.get('models', [])},
+            'tool': {t.get('tool_name') for t in resources.get('tools', [])},
+            'knowledge_base': {kb.get('kb_id') for kb in resources.get('knowledge_bases', [])},
+        }
+
+        session: AgentRunSession = {
+            'run_id': run_id,
+            'runner_id': runner_id,
+            'query_id': query_id,
+            'plugin_identity': plugin_identity,
+            'resources': resources,
+            'status': {
+                'started_at': now,
+                'last_activity_at': now,
+            },
+            '_authorized_ids': authorized_ids,
+        }
+
+        async with self._lock:
+            self._sessions[run_id] = session
+
+    async def unregister(self, run_id: str) -> None:
+        """Unregister an agent run session.
+
+        Args:
+            run_id: Unique run identifier
+        """
+        async with self._lock:
+            if run_id in self._sessions:
+                del self._sessions[run_id]
+
+    async def get(self, run_id: str) -> AgentRunSession | None:
+        """Get session by run_id.
+
+        Args:
+            run_id: Unique run identifier
+
+        Returns:
+            AgentRunSession if found, None otherwise
+        """
+        async with self._lock:
+            return self._sessions.get(run_id)
+
+    async def update_activity(self, run_id: str) -> None:
+        """Update last activity timestamp for session.
+
+        Args:
+            run_id: Unique run identifier
+        """
+        async with self._lock:
+            if run_id in self._sessions:
+                self._sessions[run_id]['status']['last_activity_at'] = int(time.time())
+
+    def is_resource_allowed(
+        self,
+        session: AgentRunSession,
+        resource_type: str,
+        resource_id: str,
+    ) -> bool:
+        """Check if resource access is allowed for this session.
+
+        Uses pre-computed authorized IDs for O(1) lookup.
+
+        Args:
+            session: AgentRunSession to check
+            resource_type: Resource type ('model', 'tool', 'knowledge_base', 'storage')
+            resource_id: Resource identifier (model_id, tool_name, kb_id)
+
+        Returns:
+            True if resource is authorized, False otherwise
+        """
+        authorized_ids = session.get('_authorized_ids', {})
+
+        if resource_type in ('model', 'tool', 'knowledge_base'):
+            return resource_id in authorized_ids.get(resource_type, set())
+
+        if resource_type == 'storage':
+            storage = session['resources'].get('storage', {})
+            if resource_id == 'plugin':
+                return storage.get('plugin_storage', False)
+            elif resource_id == 'workspace':
+                return storage.get('workspace_storage', False)
+            return False
+
+        return False
+
+    async def list_active_runs(self) -> list[AgentRunSession]:
+        """List all active run sessions.
+
+        Returns:
+            List of active AgentRunSession dicts
+        """
+        async with self._lock:
+            return list(self._sessions.values())
+
+    async def cleanup_stale_sessions(self, max_age_seconds: int = 3600) -> int:
+        """Cleanup sessions that have been inactive for too long.
+
+        Args:
+            max_age_seconds: Maximum inactivity time in seconds (default 1 hour)
+
+        Returns:
+            Number of sessions cleaned up
+        """
+        now = int(time.time())
+        cleaned = 0
+
+        async with self._lock:
+            stale_run_ids = []
+            for run_id, session in self._sessions.items():
+                last_activity = session['status'].get('last_activity_at', 0)
+                if now - last_activity > max_age_seconds:
+                    stale_run_ids.append(run_id)
+
+            for run_id in stale_run_ids:
+                del self._sessions[run_id]
+                cleaned += 1
+
+        return cleaned
+
+
+# Global registry instance (singleton)
+_global_registry: AgentRunSessionRegistry | None = None
+_global_registry_lock = threading.Lock()
+
+
+def get_session_registry() -> AgentRunSessionRegistry:
+    """Get global session registry instance (thread-safe singleton).
+
+    Returns:
+        AgentRunSessionRegistry singleton
+    """
+    global _global_registry
+    with _global_registry_lock:
+        if _global_registry is None:
+            _global_registry = AgentRunSessionRegistry()
+        return _global_registry

src/langbot/pkg/agent/runner/state_store.py

@@ -0,0 +1,299 @@
+"""Runner scoped state store for managing AgentRunner state across runs."""
+from __future__ import annotations
+
+import typing
+import threading
+
+from langbot_plugin.api.entities.builtin.pipeline import query as pipeline_query
+
+from .descriptor import AgentRunnerDescriptor
+
+
+# Valid state scopes per PROTOCOL_V1.md
+VALID_STATE_SCOPES = ('conversation', 'actor', 'subject', 'runner')
+
+# Key mapping for backward compatibility
+LEGACY_KEY_MAPPING = {
+    'conversation_id': 'external.conversation_id',
+}
+
+
+class RunnerScopedStateStore:
+    """In-memory scoped state store for AgentRunner protocol state.
+
+    IMPORTANT: This is HOST-OWNED protocol state, NOT plugin instance state.
+
+    Key Design Principles:
+    1. Host-owned: State is owned and managed by LangBot host, not by the plugin.
+       The plugin can only read/write through the SDK v1 protocol state API.
+    2. Scope keys based on stable host identity: Uses host-controlled identifiers
+       (runner_id, bot_uuid, pipeline_uuid, launcher_type, launcher_id) rather
+       than external/unstable identifiers like external conversation id.
+    3. External conversation id is a VALUE: The runner can update external.conversation_id
+       in state, which syncs to conversation.uuid. The scope key remains stable,
+       preventing state loss when conversation identity changes.
+
+    State scopes:
+    - conversation: runner_id + bot_uuid + pipeline_uuid + launcher_type + launcher_id + conversation identity
+    - actor: runner_id + bot_uuid + sender_id
+    - subject: runner_id + bot_uuid + launcher_type + launcher_id
+    - runner: runner_id + pipeline_uuid
+
+    This ensures different runners don't share state and same runner
+    has appropriate isolation per scope.
+
+    Note: This is an in-memory store. State only persists within the
+    current process lifetime. For production use, a persistent storage
+    backend should be implemented.
+    """
+
+    def __init__(self):
+        # Use thread-safe dict for concurrent access
+        self._store: dict[str, dict[str, typing.Any]] = {}
+        self._lock = threading.Lock()
+
+    def _make_conversation_scope_key(
+        self,
+        query: pipeline_query.Query,
+        descriptor: AgentRunnerDescriptor,
+    ) -> str:
+        """Build conversation scope identity key.
+
+        Uses host-owned stable identity, NOT external conversation id.
+        External conversation id is a state VALUE, not part of state KEY.
+
+        This prevents state loss when runner updates external.conversation_id:
+        - First run: scope key uses stable identity, state saved
+        - Runner returns external.conversation_id, synced to conversation.uuid
+        - Next run: scope key still uses same stable identity, state accessible
+        """
+        parts = [
+            descriptor.id,
+            query.bot_uuid or 'unknown_bot',
+            query.pipeline_uuid or 'unknown_pipeline',
+        ]
+
+        if query.session:
+            parts.append(query.session.launcher_type.value)
+            parts.append(query.session.launcher_id)
+
+            # Use stable conversation identity (NOT external uuid)
+            # Options:
+            # 1. conversation.create_time if available (stable host-owned)
+            # 2. Use "conversation" literal as stable identity within launcher scope
+            #    (assumes one active conversation per launcher context)
+            # We use option 2 for simplicity - conversation state is scoped to
+            # launcher (person/group) + bot + pipeline + runner
+            # External conversation id is just a VALUE inside this scope
+            conv_create_time = getattr(query.session.using_conversation, 'create_time', None)
+            if conv_create_time:
+                # Use create_time as stable identity if available
+                parts.append(str(conv_create_time))
+            # else: no additional part - launcher scope identity is sufficient
+
+        return f'conversation:{":".join(parts)}'
+
+    def _make_actor_scope_key(
+        self,
+        query: pipeline_query.Query,
+        descriptor: AgentRunnerDescriptor,
+    ) -> str:
+        """Build actor scope identity key."""
+        parts = [
+            descriptor.id,
+            query.bot_uuid or 'unknown_bot',
+            str(query.sender_id) if query.sender_id else 'unknown_sender',
+        ]
+
+        return f'actor:{":".join(parts)}'
+
+    def _make_subject_scope_key(
+        self,
+        query: pipeline_query.Query,
+        descriptor: AgentRunnerDescriptor,
+    ) -> str:
+        """Build subject scope identity key."""
+        parts = [
+            descriptor.id,
+            query.bot_uuid or 'unknown_bot',
+        ]
+
+        if query.session:
+            parts.append(query.session.launcher_type.value)
+            parts.append(query.session.launcher_id)
+
+        return f'subject:{":".join(parts)}'
+
+    def _make_runner_scope_key(
+        self,
+        query: pipeline_query.Query,
+        descriptor: AgentRunnerDescriptor,
+    ) -> str:
+        """Build runner scope identity key."""
+        parts = [
+            descriptor.id,
+            query.pipeline_uuid or 'unknown_pipeline',
+        ]
+
+        return f'runner:{":".join(parts)}'
+
+    def _get_scope_key(
+        self,
+        scope: str,
+        query: pipeline_query.Query,
+        descriptor: AgentRunnerDescriptor,
+    ) -> str:
+        """Get the storage key for a given scope."""
+        if scope == 'conversation':
+            return self._make_conversation_scope_key(query, descriptor)
+        elif scope == 'actor':
+            return self._make_actor_scope_key(query, descriptor)
+        elif scope == 'subject':
+            return self._make_subject_scope_key(query, descriptor)
+        elif scope == 'runner':
+            return self._make_runner_scope_key(query, descriptor)
+        else:
+            raise ValueError(f'Invalid scope: {scope}')
+
+    def build_snapshot(
+        self,
+        query: pipeline_query.Query,
+        descriptor: AgentRunnerDescriptor,
+    ) -> dict[str, dict[str, typing.Any]]:
+        """Build state snapshot for all scopes.
+
+        Args:
+            query: Pipeline query
+            descriptor: Runner descriptor
+
+        Returns:
+            Dict with 4 scope keys, each containing scope state dict
+        """
+        snapshot: dict[str, dict[str, typing.Any]] = {
+            'conversation': {},
+            'actor': {},
+            'subject': {},
+            'runner': {},
+        }
+
+        with self._lock:
+            for scope in VALID_STATE_SCOPES:
+                scope_key = self._get_scope_key(scope, query, descriptor)
+                scope_state = self._store.get(scope_key, {})
+                snapshot[scope] = dict(scope_state)  # Copy to avoid mutation
+
+        # Seed external.conversation_id from existing conversation uuid
+        if query.session and query.session.using_conversation:
+            conv_uuid = getattr(query.session.using_conversation, 'uuid', None)
+            if conv_uuid and 'external.conversation_id' not in snapshot['conversation']:
+                snapshot['conversation']['external.conversation_id'] = conv_uuid
+
+        return snapshot
+
+    def apply_update(
+        self,
+        query: pipeline_query.Query,
+        descriptor: AgentRunnerDescriptor,
+        scope: str,
+        key: str,
+        value: typing.Any,
+        logger: typing.Any = None,
+    ) -> bool:
+        """Apply a state update to the store.
+
+        Args:
+            query: Pipeline query
+            descriptor: Runner descriptor
+            scope: State scope (conversation, actor, subject, runner)
+            key: State key (should use namespace prefix like external.*)
+            value: State value (must be JSON-serializable)
+            logger: Optional logger for warnings
+
+        Returns:
+            True if update applied successfully, False if invalid scope
+
+        Side effects:
+            - Updates internal store
+            - Syncs external.conversation_id to query.session.using_conversation.uuid
+        """
+        # Validate scope
+        if scope not in VALID_STATE_SCOPES:
+            if logger:
+                logger.warning(
+                    f'Runner {descriptor.id} state.updated with invalid scope: {scope}. '
+                    f'Valid scopes: {", ".join(VALID_STATE_SCOPES)}'
+                )
+            return False
+
+        # Map legacy key names
+        if key in LEGACY_KEY_MAPPING:
+            mapped_key = LEGACY_KEY_MAPPING[key]
+            if logger:
+                logger.debug(
+                    f'Runner {descriptor.id} state.updated legacy key "{key}" mapped to "{mapped_key}"'
+                )
+            key = mapped_key
+
+        # Apply update to store
+        with self._lock:
+            scope_key = self._get_scope_key(scope, query, descriptor)
+            if scope_key not in self._store:
+                self._store[scope_key] = {}
+            self._store[scope_key][key] = value
+
+        # Sync external.conversation_id to query.session.using_conversation.uuid
+        if scope == 'conversation' and key == 'external.conversation_id':
+            if query.session and query.session.using_conversation:
+                # Update conversation uuid for backward compatibility
+                # This ensures old conversation continuation behavior works
+                setattr(query.session.using_conversation, 'uuid', value)
+                if logger:
+                    logger.debug(
+                        f'Synced external.conversation_id "{value}" to conversation.uuid'
+                    )
+
+        return True
+
+    def clear_scope(
+        self,
+        scope: str,
+        query: pipeline_query.Query,
+        descriptor: AgentRunnerDescriptor,
+    ) -> None:
+        """Clear all state for a specific scope.
+
+        Args:
+            scope: State scope to clear
+            query: Pipeline query
+            descriptor: Runner descriptor
+        """
+        with self._lock:
+            scope_key = self._get_scope_key(scope, query, descriptor)
+            if scope_key in self._store:
+                del self._store[scope_key]
+
+    def clear_all(self) -> None:
+        """Clear all stored state (for testing/reset)."""
+        with self._lock:
+            self._store.clear()
+
+
+# Global singleton state store
+_state_store: RunnerScopedStateStore | None = None
+_state_store_lock = threading.Lock()
+
+
+def get_state_store() -> RunnerScopedStateStore:
+    """Get the global state store singleton."""
+    global _state_store
+    with _state_store_lock:
+        if _state_store is None:
+            _state_store = RunnerScopedStateStore()
+        return _state_store
+
+
+def reset_state_store() -> None:
+    """Reset the global state store (for testing)."""
+    global _state_store
+    with _state_store_lock:
+        _state_store = None

src/langbot/pkg/api/http/service/pipeline.py

@@ -45,20 +45,27 @@ class PipelineService:
                 break
 
         if runner_stage:
-            # Find the runner select config
+            # Find the runner select config (now uses 'id' field)
             for config_item in runner_stage.get('config', []):
-                if config_item.get('name') == 'runner':
+                if config_item.get('name') == 'id':
                     # Get plugin agent runners from registry
                     try:
                         runner_options, runner_stages = await self.ap.agent_runner_registry.get_runner_metadata_for_pipeline()
 
-                        # Add plugin runners to options
-                        for option in runner_options:
-                            config_item['options'].append(option)
+                        # Replace options entirely with registry options
+                        # Only installed/available runners should be shown
+                        config_item['options'] = runner_options
+
+                        # Set default to first available runner if not specified
+                        if runner_options and 'default' not in config_item:
+                            config_item['default'] = runner_options[0]['name']
 
                         # Add corresponding stage configuration for each runner
                         for stage_config in runner_stages:
-                            ai_metadata['stages'].append(stage_config)
+                            # Avoid duplicate stages
+                            existing_stage_names = {s.get('name') for s in ai_metadata.get('stages', [])}
+                            if stage_config['name'] not in existing_stage_names:
+                                ai_metadata['stages'].append(stage_config)
 
                     except Exception as e:
                         self.ap.logger.warning(f'Failed to load plugin agent runners from registry: {e}')
@@ -145,10 +152,16 @@ class PipelineService:
         return pipeline_data['uuid']
 
     async def update_pipeline(self, pipeline_uuid: str, pipeline_data: dict) -> None:
+        from ....agent.runner.config_migration import ConfigMigration
+
         pipeline_data = pipeline_data.copy()
         for protected_field in ('uuid', 'for_version', 'stages', 'is_default'):
             pipeline_data.pop(protected_field, None)
 
+        # Migrate config to new format before saving
+        if 'config' in pipeline_data:
+            pipeline_data['config'] = ConfigMigration.migrate_pipeline_config(pipeline_data['config'])
+
         await self.ap.persistence_mgr.execute_async(
             sqlalchemy.update(persistence_pipeline.LegacyPipeline)
             .where(persistence_pipeline.LegacyPipeline.uuid == pipeline_uuid)

src/langbot/pkg/persistence/alembic/versions/0004_migrate_runner_config.py

@@ -0,0 +1,124 @@
+"""Migrate pipeline config to new runner format
+
+Revision ID: 0004_migrate_runner_config
+Revises: 0003_add_rerank_models
+Create Date: 2026-05-10
+"""
+
+import json
+import sqlalchemy as sa
+from alembic import op
+
+revision = '0004_migrate_runner_config'
+down_revision = '0003_add_rerank_models'
+branch_labels = None
+depends_on = None
+
+# Mapping from old built-in runner names to official plugin runner IDs
+OLD_RUNNER_TO_PLUGIN_RUNNER_ID = {
+    'local-agent': 'plugin:langbot/local-agent/default',
+    'dify-service-api': 'plugin:langbot/dify-agent/default',
+    'n8n-service-api': 'plugin:langbot/n8n-agent/default',
+    'coze-api': 'plugin:langbot/coze-agent/default',
+    'dashscope-app-api': 'plugin:langbot/dashscope-agent/default',
+    'langflow-api': 'plugin:langbot/langflow-agent/default',
+    'tbox-app-api': 'plugin:langbot/tbox-agent/default',
+}
+
+
+def is_plugin_runner_id(runner_id: str) -> bool:
+    """Check if runner ID is in plugin:* format."""
+    return runner_id.startswith('plugin:')
+
+
+def migrate_pipeline_config(config: dict) -> dict:
+    """Migrate pipeline config to new format."""
+    new_config = dict(config)
+    ai_config = new_config.get('ai', {})
+    if not ai_config:
+        return new_config
+
+    runner_config = ai_config.get('runner', {})
+    runner_configs = ai_config.get('runner_config', {})
+
+    # Check for new format first
+    runner_id = runner_config.get('id')
+    if runner_id and is_plugin_runner_id(runner_id):
+        # Already in new format, no need to migrate
+        return new_config
+
+    # Check for old format
+    old_runner_name = runner_config.get('runner')
+    if old_runner_name:
+        # Map to new runner ID
+        if is_plugin_runner_id(old_runner_name):
+            runner_id = old_runner_name
+        else:
+            runner_id = OLD_RUNNER_TO_PLUGIN_RUNNER_ID.get(old_runner_name, old_runner_name)
+
+        # Set new format
+        runner_config['id'] = runner_id
+
+        # Remove old runner field if it's a mapped built-in runner
+        if old_runner_name in OLD_RUNNER_TO_PLUGIN_RUNNER_ID:
+            del runner_config['runner']
+
+        # Migrate runner-specific config and remove old config blocks
+        if old_runner_name in ai_config:
+            old_runner_config = ai_config[old_runner_name]
+            if old_runner_config:
+                runner_configs[runner_id] = old_runner_config
+            # Remove old config block after migration
+            del ai_config[old_runner_name]
+
+        # Also check if runner_id has config under other old name formats
+        for old_name, mapped_id in OLD_RUNNER_TO_PLUGIN_RUNNER_ID.items():
+            if mapped_id == runner_id and old_name in ai_config:
+                runner_configs[runner_id] = ai_config[old_name]
+                # Remove old config block after migration
+                del ai_config[old_name]
+
+    # Update configs
+    ai_config['runner'] = runner_config
+    ai_config['runner_config'] = runner_configs
+    new_config['ai'] = ai_config
+
+    return new_config
+
+
+def upgrade() -> None:
+    """Migrate existing pipeline configs to new runner format."""
+    conn = op.get_bind()
+    inspector = sa.inspect(conn)
+
+    # Check if pipelines table exists (may not exist in fresh install)
+    if 'pipelines' not in inspector.get_table_names():
+        return
+
+    # Get all pipelines
+    result = conn.execute(sa.text('SELECT uuid, config FROM pipelines'))
+    pipelines = result.fetchall()
+
+    for pipeline_uuid, config_json in pipelines:
+        if not config_json:
+            continue
+
+        try:
+            config = json.loads(config_json)
+            migrated_config = migrate_pipeline_config(config)
+
+            # Only update if config changed
+            if json.dumps(config, sort_keys=True) != json.dumps(migrated_config, sort_keys=True):
+                conn.execute(
+                    sa.text('UPDATE pipelines SET config = :config WHERE uuid = :uuid'),
+                    {'config': json.dumps(migrated_config), 'uuid': pipeline_uuid}
+                )
+        except Exception:
+            # Skip invalid configs
+            continue
+
+
+def downgrade() -> None:
+    """Downgrade is not supported for data migration."""
+    # No downgrade - keep configs in new format
+    pass

src/langbot/pkg/pipeline/msgtrun/truncators/round.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 from .. import truncator
 import langbot_plugin.api.entities.builtin.pipeline.query as pipeline_query
+from ....agent.runner.config_migration import ConfigMigration
 
 
 @truncator.truncator_class('round')
@@ -10,7 +11,10 @@ class RoundTruncator(truncator.Truncator):
 
     async def truncate(self, query: pipeline_query.Query) -> pipeline_query.Query:
         """截断"""
-        max_round = query.pipeline_config['ai']['local-agent']['max-round']
+        # Get max-round from runner config (new or old format)
+        runner_id = ConfigMigration.resolve_runner_id(query.pipeline_config)
+        runner_config = ConfigMigration.resolve_runner_config(query.pipeline_config, runner_id) if runner_id else {}
+        max_round = runner_config.get('max-round', 10)
 
         temp_messages = []
 

src/langbot/pkg/platform/sources/web_page_bot_adapter.py

@@ -84,6 +84,20 @@ class WebPageBotAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter
     ):
         self.listeners.pop(event_type, None)
 
+    async def is_stream_output_supported(self) -> bool:
+        """Delegate stream output check to ws_adapter."""
+        if self._ws_adapter is not None:
+            return await self._ws_adapter.is_stream_output_supported()
+        return False
+
+    async def create_message_card(
+        self, message_id: str | int, event: platform_events.MessageEvent
+    ) -> bool:
+        """Delegate create_message_card to ws_adapter."""
+        if self._ws_adapter is not None:
+            return await self._ws_adapter.create_message_card(message_id, event)
+        return False
+
     async def is_muted(self, group_id: int) -> bool:
         return False
 

src/langbot/pkg/plugin/handler.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import typing
-from typing import Any
+from typing import Any, Union
 import base64
 import traceback
 
@@ -24,6 +24,7 @@ from ..entity.persistence import bstorage as persistence_bstorage
 
 from ..core import app
 from ..utils import constants
+from ..agent.runner.session_registry import get_session_registry
 
 
 def _make_rag_error_response(error: Exception, error_type: str, **extra_context) -> handler.ActionResponse:
@@ -40,6 +41,48 @@ def _make_rag_error_response(error: Exception, error_type: str, **extra_context)
     return handler.ActionResponse.error(message=message)
 
 
+async def _validate_run_authorization(
+    run_id: str,
+    resource_type: str,
+    resource_id: str,
+    ap: app.Application,
+) -> Union[tuple[None, handler.ActionResponse], tuple[Any, None]]:
+    """Validate run_id authorization for a resource access.
+
+    Common validation logic for INVOKE_LLM, INVOKE_LLM_STREAM, CALL_TOOL,
+    RETRIEVE_KNOWLEDGE_BASE, and RETRIEVE_KNOWLEDGE actions.
+
+    Args:
+        run_id: The run_id to validate.
+        resource_type: Resource type ('model', 'tool', 'knowledge_base').
+        resource_id: Resource identifier (model_uuid, tool_name, kb_id).
+        ap: Application instance for logging.
+
+    Returns:
+        Tuple of (session, None) if validation passes.
+        Tuple of (None, error_response) if validation fails.
+    """
+    session_registry = get_session_registry()
+    session = await session_registry.get(run_id)
+    if not session:
+        ap.logger.warning(
+            f'{resource_type.upper()}: run_id {run_id} not found in session registry'
+        )
+        return None, handler.ActionResponse.error(
+            message=f'Run session {run_id} not found or expired',
+        )
+
+    if not session_registry.is_resource_allowed(session, resource_type, resource_id):
+        ap.logger.warning(
+            f'{resource_type.upper()}: {resource_id} not allowed for run_id {run_id}'
+        )
+        return None, handler.ActionResponse.error(
+            message=f'{resource_type} {resource_id} is not authorized for this agent run',
+        )
+
+    return session, None
+
+
 class RuntimeConnectionHandler(handler.Handler):
     """Runtime connection handler"""
 
@@ -324,11 +367,24 @@ class RuntimeConnectionHandler(handler.Handler):
 
         @self.action(PluginToRuntimeAction.INVOKE_LLM)
         async def invoke_llm(data: dict[str, Any]) -> handler.ActionResponse:
-            """Invoke llm"""
+            """Invoke llm
+
+            For AgentRunner calls: requires run_id and validates model_uuid against session.resources.models.
+            For regular plugin calls: no run_id, unrestricted access (backward compatibility).
+            """
             llm_model_uuid = data['llm_model_uuid']
             messages = data['messages']
             funcs = data.get('funcs', [])
             extra_args = data.get('extra_args', {})
+            run_id = data.get('run_id')  # Optional: present for AgentRunner calls
+
+            # Permission validation for AgentRunner calls
+            if run_id:
+                session, error = await _validate_run_authorization(
+                    run_id, 'model', llm_model_uuid, self.ap
+                )
+                if error:
+                    return error
 
             llm_model = await self.ap.model_mgr.get_model_by_uuid(llm_model_uuid)
             if llm_model is None:
@@ -362,11 +418,25 @@ class RuntimeConnectionHandler(handler.Handler):
 
         @self.action(PluginToRuntimeAction.INVOKE_LLM_STREAM)
         async def invoke_llm_stream(data: dict[str, Any]):
-            """Invoke llm with streaming response"""
+            """Invoke llm with streaming response
+
+            For AgentRunner calls: requires run_id and validates model_uuid against session.resources.models.
+            For regular plugin calls: no run_id, unrestricted access (backward compatibility).
+            """
             llm_model_uuid = data['llm_model_uuid']
             messages = data['messages']
             funcs = data.get('funcs', [])
             extra_args = data.get('extra_args', {})
+            run_id = data.get('run_id')  # Optional: present for AgentRunner calls
+
+            # Permission validation for AgentRunner calls
+            if run_id:
+                session, error = await _validate_run_authorization(
+                    run_id, 'model', llm_model_uuid, self.ap
+                )
+                if error:
+                    yield error
+                    return
 
             llm_model = await self.ap.model_mgr.get_model_by_uuid(llm_model_uuid)
             if llm_model is None:
@@ -393,12 +463,30 @@ class RuntimeConnectionHandler(handler.Handler):
 
         @self.action(PluginToRuntimeAction.CALL_TOOL)
         async def call_tool(data: dict[str, Any]) -> handler.ActionResponse:
-            """Call a tool"""
+            """Call a tool
+
+            For AgentRunner calls: requires run_id and validates tool_name against session.resources.tools.
+            For regular plugin calls: no run_id, unrestricted access (backward compatibility).
+
+            Note: SDK LangBotAPIProxy (legacy) sends 'tool_parameters' and expects 'tool_response'.
+            SDK AgentRunAPIProxy sends 'parameters' and expects 'result'.
+            Handler returns both for backward compatibility.
+            """
             tool_name = data['tool_name']
-            parameters = data['parameters']
+            # Support 'tool_parameters' (LangBotAPIProxy) and 'parameters' (AgentRunAPIProxy)
+            parameters = data.get('tool_parameters') or data.get('parameters', {})
+            run_id = data.get('run_id')  # Optional: present for AgentRunner calls
             # session_data = data['session']
             # query_id = data['query_id']
 
+            # Permission validation for AgentRunner calls
+            if run_id:
+                session, error = await _validate_run_authorization(
+                    run_id, 'tool', tool_name, self.ap
+                )
+                if error:
+                    return error
+
             # Convert session_data to Session object (simplified)
             # In real implementation, you would reconstruct the full session
             # For now, we'll call the tool manager's execute method
@@ -408,9 +496,12 @@ class RuntimeConnectionHandler(handler.Handler):
                     parameters=parameters,
                     query=None,  # TODO: reconstruct query from session_data if needed
                 )
+                # Return both 'tool_response' (LangBotAPIProxy) and 'result' (AgentRunAPIProxy)
+                # LangBotAPIProxy expects 'tool_response', AgentRunAPIProxy expects 'result'
                 return handler.ActionResponse.success(
                     data={
-                        'result': result,
+                        'tool_response': result,
+                        'result': result,  # backward compatibility
                     },
                 )
             except Exception as e:
@@ -419,6 +510,14 @@ class RuntimeConnectionHandler(handler.Handler):
                     message=f'Failed to execute tool {tool_name}: {e}',
                 )
 
+        # ================= Binary Storage Handlers =================
+        # NOTE: These are low-level actions called by SDK Runtime's storage wrapper handlers.
+        # Permission validation is handled in SDK Runtime layer (not here):
+        # - plugin_storage: SDK handler auto-sets owner to caller plugin identity (inherent isolation)
+        # - workspace_storage: SDK handler should validate session.resources.storage.workspace_storage
+        #   TODO: SDK storage handlers need to pass run_id and validate workspace_storage permission.
+        # Current risk: workspace storage access is unrestricted from AgentRunner context.
+
         @self.action(RuntimeToLangBotAction.SET_BINARY_STORAGE)
         async def set_binary_storage(data: dict[str, Any]) -> handler.ActionResponse:
             """Set binary storage"""
@@ -706,11 +805,26 @@ class RuntimeConnectionHandler(handler.Handler):
 
         @self.action(PluginToRuntimeAction.RETRIEVE_KNOWLEDGE)
         async def retrieve_knowledge(data: dict[str, Any]) -> handler.ActionResponse:
-            """Retrieve documents from any knowledge base (unrestricted)."""
+            """Retrieve documents from any knowledge base.
+
+            For AgentRunner calls: requires run_id and validates kb_id against session.resources.knowledge_bases.
+            For regular plugin calls: no run_id, unrestricted access (backward compatibility).
+
+            Note: SDK AgentRunAPIProxy.retrieve_knowledge calls this action with run_id.
+            """
             kb_id = data['kb_id']
             query_text = data['query_text']
             top_k = data.get('top_k', 5)
             filters = data.get('filters', {})
+            run_id = data.get('run_id')  # Optional: present for AgentRunner calls
+
+            # Permission validation for AgentRunner calls
+            if run_id:
+                session, error = await _validate_run_authorization(
+                    run_id, 'knowledge_base', kb_id, self.ap
+                )
+                if error:
+                    return error
 
             kb = await self.ap.rag_mgr.get_knowledge_base_by_uuid(kb_id)
             if not kb:
@@ -769,12 +883,27 @@ class RuntimeConnectionHandler(handler.Handler):
 
         @self.action(PluginToRuntimeAction.RETRIEVE_KNOWLEDGE_BASE)
         async def retrieve_knowledge_base(data: dict[str, Any]) -> handler.ActionResponse:
-            """Retrieve documents from a knowledge base within the pipeline's scope."""
+            """Retrieve documents from a knowledge base within the pipeline's scope.
+
+            For AgentRunner calls: requires run_id and validates kb_id against session.resources.knowledge_bases.
+            For regular plugin calls: no run_id, validates against pipeline's configured knowledge bases.
+
+            Note: This action has dual validation paths:
+            - AgentRunner: uses session_registry for permission check
+            - Regular plugin: uses ConfigMigration.resolve_runner_config for pipeline-level check
+
+            SECURITY TODO: This handler cannot verify the caller's plugin identity.
+            The session contains 'plugin_identity' (author/name), but we don't have access
+            to which plugin is making the API call. This could allow a malicious plugin to
+            use another plugin's run_id if it can guess/obtain it. Future improvement:
+            track caller plugin identity in RuntimeConnectionHandler or pass it in action data.
+            """
             query_id = data['query_id']
             kb_id = data['kb_id']
             query_text = data['query_text']
             top_k = data.get('top_k', 5)
             filters = data.get('filters', {})
+            run_id = data.get('run_id')  # Optional: present for AgentRunner calls
 
             if query_id not in self.ap.query_pool.cached_queries:
                 return handler.ActionResponse.error(
@@ -783,21 +912,32 @@ class RuntimeConnectionHandler(handler.Handler):
 
             query = self.ap.query_pool.cached_queries[query_id]
 
-            # Validate kb_id is in pipeline's allowed list
-            allowed_kb_uuids = []
-            if query.pipeline_config:
-                from langbot.pkg.agent.runner.config_migration import ConfigMigration
-                runner_config = ConfigMigration.resolve_runner_config(query.pipeline_config, None)
-                allowed_kb_uuids = runner_config.get('knowledge-bases', [])
-                if not allowed_kb_uuids:
-                    old_kb_uuid = runner_config.get('knowledge-base', '')
-                    if old_kb_uuid and old_kb_uuid != '__none__':
-                        allowed_kb_uuids = [old_kb_uuid]
-
-            if kb_id not in allowed_kb_uuids:
-                return handler.ActionResponse.error(
-                    message=f'Knowledge base {kb_id} is not configured for this pipeline',
+            # Permission validation for AgentRunner calls
+            if run_id:
+                session, error = await _validate_run_authorization(
+                    run_id, 'knowledge_base', kb_id, self.ap
                 )
+                if error:
+                    return error
+            else:
+                # Regular plugin call: validate against pipeline's configured knowledge bases
+                # FIX: First resolve runner_id, then resolve runner_config
+                allowed_kb_uuids = []
+                if query.pipeline_config:
+                    from langbot.pkg.agent.runner.config_migration import ConfigMigration
+                    runner_id = ConfigMigration.resolve_runner_id(query.pipeline_config)
+                    if runner_id:
+                        runner_config = ConfigMigration.resolve_runner_config(query.pipeline_config, runner_id)
+                        allowed_kb_uuids = runner_config.get('knowledge-bases', [])
+                        if not allowed_kb_uuids:
+                            old_kb_uuid = runner_config.get('knowledge-base', '')
+                            if old_kb_uuid and old_kb_uuid != '__none__':
+                                allowed_kb_uuids = [old_kb_uuid]
+
+                if kb_id not in allowed_kb_uuids:
+                    return handler.ActionResponse.error(
+                        message=f'Knowledge base {kb_id} is not configured for this pipeline',
+                    )
 
             kb = await self.ap.rag_mgr.get_knowledge_base_by_uuid(kb_id)
             if not kb:

src/langbot/templates/metadata/pipeline/ai.yaml

@@ -11,42 +11,13 @@ stages:
       en_US: Strategy to call AI to process messages
       zh_Hans: 调用 AI 处理消息的方式
     config:
-      - name: runner
+      - name: id
         label:
           en_US: Runner
           zh_Hans: 运行器
         type: select
         required: true
-        default: local-agent
-        options:
-          - name: local-agent
-            label:
-              en_US: Local Agent
-              zh_Hans: 内置 Agent
-          - name: dify-service-api
-            label:
-              en_US: Dify Service API
-              zh_Hans: Dify 服务 API
-          - name: n8n-service-api
-            label:
-              en_US: n8n Workflow API
-              zh_Hans: n8n 工作流 API
-          - name: coze-api
-            label:
-              en_US: Coze API
-              zh_Hans: 扣子 API
-          - name: tbox-app-api
-            label:
-              en_US: Tbox App API
-              zh_Hans: 蚂蚁百宝箱平台 API
-          - name: dashscope-app-api
-            label:
-              en_US: Aliyun Dashscope App API
-              zh_Hans: 阿里云百炼平台 API
-          - name: langflow-api
-            label:
-              en_US: Langflow API
-              zh_Hans: Langflow API
+        # Options and default are dynamically populated from AgentRunnerRegistry
       - name: expire-time
         label:
           en_US: Conversation expire time (seconds)
@@ -67,589 +38,6 @@ stages:
         type: integer
         required: true
         default: 0
-  - name: local-agent
-    label:
-      en_US: Local Agent
-      zh_Hans: 内置 Agent
-    description:
-      en_US: Configure the embedded agent of the pipeline
-      zh_Hans: 配置内置 Agent
-    config:
-      - name: model
-        label:
-          en_US: Model
-          zh_Hans: 模型
-        type: model-fallback-selector
-        required: true
-        default:
-          primary: ''
-          fallbacks: []
-      - name: max-round
-        label:
-          en_US: Max Round
-          zh_Hans: 最大回合数
-        description:
-          en_US: The maximum number of previous messages that the agent can remember
-          zh_Hans: 最大前文消息回合数
-        type: integer
-        required: true
-        default: 10
-        show_if:
-          field: __system.is_wizard
-          operator: neq
-          value: true
-      - name: prompt
-        label:
-          en_US: Prompt
-          zh_Hans: 提示词
-        description:
-          en_US: The prompt of the agent
-          zh_Hans: 除非您了解消息结构，否则请只使用 system 单提示词
-        type: prompt-editor
-        required: true
-        default:
-          - role: system
-            content: "You are a helpful assistant."
-      - name: knowledge-bases
-        label:
-          en_US: Knowledge Bases
-          zh_Hans: 知识库
-        description:
-          en_US: Configure the knowledge bases to use for the agent, if not selected, the agent will directly use the LLM to reply
-          zh_Hans: 配置用于提升回复质量的知识库，若不选择，则直接使用大模型回复
-        type: knowledge-base-multi-selector
-        required: false
-        default: []
-        show_if:
-          field: __system.is_wizard
-          operator: neq
-          value: true
-      - name: box-session-id-template
-        label:
-          en_US: Sandbox Scope
-          zh_Hans: 沙箱作用域
-          zh_Hant: 沙箱作用域
-          ja_JP: サンドボックススコープ
-          vi_VN: Phạm vi Sandbox
-          th_TH: ขอบเขต Sandbox
-          es_ES: Alcance del Sandbox
-          ru_RU: Область песочницы
-        description:
-          en_US: Determines how sandbox environments are shared across messages.
-          zh_Hans: 决定沙箱环境在不同消息间的共享方式。
-          zh_Hant: 決定沙箱環境在不同訊息間的共享方式。
-          ja_JP: メッセージ間でサンドボックス環境を共有する方法を決定します。
-          vi_VN: Xác định cách chia sẻ môi trường sandbox giữa các tin nhắn.
-          th_TH: กำหนดวิธีแชร์สภาพแวดล้อม Sandbox ระหว่างข้อความ
-          es_ES: Determina cómo se comparten los entornos sandbox entre mensajes.
-          ru_RU: Определяет, как песочницы используются совместно между сообщениями.
-        disable_if:
-          field: __system.box_available
-          operator: eq
-          value: false
-        disabled_tooltip:
-          en_US: >-
-            Box sandbox is disabled or unavailable. Enable it in config.yaml
-            (box.enabled = true) and ensure the runtime is reachable to change
-            this setting.
-          zh_Hans: Box 沙箱已禁用或不可用。请在配置中启用（box.enabled = true）并确认运行时连接正常，才能修改此项。
-          zh_Hant: Box 沙箱已停用或無法使用。請在設定中啟用（box.enabled = true）並確認執行時連線正常，才能修改此項。
-          ja_JP: Box サンドボックスが無効または利用できません。設定で有効化（box.enabled = true）し、ランタイムが接続できることを確認してから変更してください。
-          vi_VN: Sandbox Box đã tắt hoặc không khả dụng. Hãy bật trong cấu hình (box.enabled = true) và đảm bảo runtime hoạt động để chỉnh sửa.
-          th_TH: Sandbox Box ถูกปิดใช้งานหรือไม่พร้อมใช้งาน กรุณาเปิดใช้งานในการตั้งค่า (box.enabled = true) และตรวจสอบว่ารันไทม์เชื่อมต่อปกติก่อนปรับค่า
-          es_ES: El sandbox de Box está desactivado o no disponible. Actívelo en la configuración (box.enabled = true) y asegúrese de que el runtime esté conectado para modificar este ajuste.
-          ru_RU: Песочница Box отключена или недоступна. Включите её в конфигурации (box.enabled = true) и убедитесь, что среда выполнения работает, чтобы изменить эту настройку.
-        type: select
-        required: false
-        default: "{launcher_type}_{launcher_id}"
-        options:
-          - name: "{global}"
-            label:
-              en_US: Global (shared by all)
-              zh_Hans: 全局（所有人共享）
-              zh_Hant: 全域（所有人共用）
-              ja_JP: グローバル（全員共有）
-              vi_VN: Toàn cục (chia sẻ cho tất cả)
-              th_TH: ทั่วไป (แชร์ทั้งหมด)
-              es_ES: Global (compartido por todos)
-              ru_RU: Глобальный (общий для всех)
-          - name: "{launcher_type}_{launcher_id}"
-            label:
-              en_US: Per chat (Recommended)
-              zh_Hans: 每个会话（推荐）
-              zh_Hant: 每個會話（推薦）
-              ja_JP: チャットごと（推奨）
-              vi_VN: Mỗi cuộc trò chuyện (Khuyến nghị)
-              th_TH: ต่อแชท (แนะนำ)
-              es_ES: Por chat (Recomendado)
-              ru_RU: По чату (Рекомендуется)
-          - name: "{launcher_type}_{launcher_id}_{sender_id}"
-            label:
-              en_US: Per user in chat
-              zh_Hans: 会话中每个用户
-              zh_Hant: 會話中每個用戶
-              ja_JP: チャット内のユーザーごと
-              vi_VN: Mỗi người dùng trong cuộc trò chuyện
-              th_TH: ต่อผู้ใช้ในแชท
-              es_ES: Por usuario en chat
-              ru_RU: По пользователю в чате
-          - name: "{launcher_type}_{launcher_id}_{conversation_id}"
-            label:
-              en_US: Per conversation context
-              zh_Hans: 每个对话上下文
-              zh_Hant: 每個對話上下文
-              ja_JP: 会話コンテキストごと
-              vi_VN: Mỗi ngữ cảnh hội thoại
-              th_TH: ต่อบริบทการสนทนา
-              es_ES: Por contexto de conversación
-              ru_RU: По контексту разговора
-          - name: "{query_id}"
-            label:
-              en_US: Per message (isolated)
-              zh_Hans: 每条消息（完全隔离）
-              zh_Hant: 每條訊息（完全隔離）
-              ja_JP: メッセージごと（隔離）
-              vi_VN: Mỗi tin nhắn (cách ly)
-              th_TH: ต่อข้อความ (แยกส่วน)
-              es_ES: Por mensaje (aislado)
-              ru_RU: По сообщению (изолированно)
-        show_if:
-          field: __system.is_wizard
-          operator: neq
-          value: true
-      - name: rerank-model
-        label:
-          en_US: Rerank Model
-          zh_Hans: 重排序模型
-        description:
-          en_US: Optional rerank model to improve retrieval quality by re-scoring retrieved chunks
-          zh_Hans: 可选的重排序模型，通过重新评分检索结果来提升检索质量
-        type: rerank-model-selector
-        required: false
-        default: ''
-        show_if:
-          field: knowledge-bases
-          operator: neq
-          value: []
-      - name: rerank-top-k
-        label:
-          en_US: Rerank Top K
-          zh_Hans: 重排序保留数量
-        description:
-          en_US: Number of top results to keep after reranking
-          zh_Hans: 重排序后保留的最相关结果数量
-        type: integer
-        required: false
-        default: 5
-        show_if:
-          field: rerank-model
-          operator: neq
-          value: ''
-  - name: dify-service-api
-    label:
-      en_US: Dify Service API
-      zh_Hans: Dify 服务 API
-    description:
-      en_US: Configure the Dify service API of the pipeline
-      zh_Hans: 配置 Dify 服务 API
-    config:
-      - name: base-url
-        label:
-          en_US: Base URL
-          zh_Hans: 基础 URL
-        type: string
-        required: true
-        options:
-          - name: 'https://api.dify.ai/v1'
-            label:
-              en_US: Dify Cloud
-              zh_Hans: Dify 云服务
-        default: 'https://api.dify.ai/v1'
-      - name: base-prompt
-        label:
-          en_US: Base PROMPT
-          zh_Hans: 基础提示词
-        description:
-          en_US: When Dify receives a message with empty input (only images), it will pass this default prompt into it.
-          zh_Hans: 当 Dify 接收到输入文字为空（仅图片）的消息时，传入该默认提示词
-        type: string
-        required: true
-        default: "When the file content is readable, please read the content of this file. When the file is an image, describe the content of this image."
-      - name: app-type
-        label:
-          en_US: App Type
-          zh_Hans: 应用类型
-        type: select
-        required: true
-        default: chat
-        options:
-          - name: chat
-            label:
-              en_US: Chat
-              zh_Hans: 聊天（包括Chatflow）
-          - name: agent
-            label:
-              en_US: Agent
-              zh_Hans: Agent
-          - name: workflow
-            label:
-              en_US: Workflow
-              zh_Hans: 工作流
-      - name: api-key
-        label:
-          en_US: API Key
-          zh_Hans: API 密钥
-        type: string
-        required: true
-        default: 'your-api-key'
-  - name: n8n-service-api
-    label:
-      en_US: n8n Workflow API
-      zh_Hans: n8n 工作流 API
-    description:
-      en_US: Configure the n8n workflow API of the pipeline
-      zh_Hans: 配置 n8n 工作流 API
-    config:
-      - name: webhook-url
-        label:
-          en_US: Webhook URL
-          zh_Hans: Webhook URL
-        description:
-          en_US: The webhook URL of the n8n workflow
-          zh_Hans: n8n 工作流的 webhook URL
-        type: string
-        required: true
-        default: 'http://your-n8n-webhook-url'
-      - name: auth-type
-        label:
-          en_US: Authentication Type
-          zh_Hans: 认证类型
-        description:
-          en_US: The authentication type for the webhook call
-          zh_Hans: webhook 调用的认证类型
-        type: select
-        required: true
-        default: 'none'
-        options:
-          - name: 'none'
-            label:
-              en_US: None
-              zh_Hans: 无认证
-          - name: 'basic'
-            label:
-              en_US: Basic Auth
-              zh_Hans: 基本认证
-          - name: 'jwt'
-            label:
-              en_US: JWT
-              zh_Hans: JWT认证
-          - name: 'header'
-            label:
-              en_US: Header Auth
-              zh_Hans: 请求头认证
-      - name: basic-username
-        label:
-          en_US: Username
-          zh_Hans: 用户名
-        description:
-          en_US: The username for Basic Auth
-          zh_Hans: 基本认证的用户名
-        type: string
-        required: false
-        default: ''
-        show_if:
-          field: auth-type
-          operator: eq
-          value: 'basic'
-      - name: basic-password
-        label:
-          en_US: Password
-          zh_Hans: 密码
-        description:
-          en_US: The password for Basic Auth
-          zh_Hans: 基本认证的密码
-        type: string
-        required: false
-        default: ''
-        show_if:
-          field: auth-type
-          operator: eq
-          value: 'basic'
-      - name: jwt-secret
-        label:
-          en_US: Secret
-          zh_Hans: 密钥
-        description:
-          en_US: The secret for JWT authentication
-          zh_Hans: JWT认证的密钥
-        type: string
-        required: false
-        default: ''
-        show_if:
-          field: auth-type
-          operator: eq
-          value: 'jwt'
-      - name: jwt-algorithm
-        label:
-          en_US: Algorithm
-          zh_Hans: 算法
-        description:
-          en_US: The algorithm for JWT authentication
-          zh_Hans: JWT认证的算法
-        type: string
-        required: false
-        default: 'HS256'
-        show_if:
-          field: auth-type
-          operator: eq
-          value: 'jwt'
-      - name: header-name
-        label:
-          en_US: Header Name
-          zh_Hans: 请求头名称
-        description:
-          en_US: The header name for Header Auth
-          zh_Hans: 请求头认证的名称
-        type: string
-        required: false
-        default: ''
-        show_if:
-          field: auth-type
-          operator: eq
-          value: 'header'
-      - name: header-value
-        label:
-          en_US: Header Value
-          zh_Hans: 请求头值
-        description:
-          en_US: The header value for Header Auth
-          zh_Hans: 请求头认证的值
-        type: string
-        required: false
-        default: ''
-        show_if:
-          field: auth-type
-          operator: eq
-          value: 'header'
-      - name: timeout
-        label:
-          en_US: Timeout
-          zh_Hans: 超时时间
-        description:
-          en_US: The timeout in seconds for the webhook call
-          zh_Hans: webhook 调用的超时时间（秒）
-        type: integer
-        required: false
-        default: 120
-      - name: output-key
-        label:
-          en_US: Output Key
-          zh_Hans: 输出键名
-        description:
-          en_US: The key name of the output in the webhook response
-          zh_Hans: webhook 响应中输出内容的键名
-        type: string
-        required: false
-        default: 'response'
-  - name: coze-api
-    label:
-      en_US: coze API
-      zh_Hans: 扣子 API
-    description:
-      en_US: Configure the Coze API of the pipeline
-      zh_Hans: 配置Coze API
-    config:
-      - name: api-key
-        label:
-          en_US: API Key
-          zh_Hans: API 密钥
-        description:
-          en_US: The API key for the Coze server
-          zh_Hans: Coze服务器的 API 密钥
-        type: string
-        required: true
-        default: ''
-      - name: bot-id
-        label:
-          en_US: Bot ID
-          zh_Hans: 机器人 ID
-        description:
-          en_US: The ID of the bot to run
-          zh_Hans: 要运行的机器人 ID
-        type: string
-        required: true
-        default: ''
-      - name: api-base
-        label:
-          en_US: API Base URL
-          zh_Hans: API 基础 URL
-        description:
-          en_US: The base URL for the Coze API, please use https://api.coze.com for global Coze edition(coze.com).
-          zh_Hans: Coze API 的基础 URL，请使用 https://api.coze.com 用于全球 Coze 版（coze.com）
-        type: string
-        options:
-          - name: 'https://api.coze.cn'
-            label:
-              en_US: Coze China
-              zh_Hans: Coze 中国版
-          - name: 'https://api.coze.com'
-            label:
-              en_US: Coze Global
-              zh_Hans: Coze 全球版
-        default: "https://api.coze.cn"
-      - name: auto-save-history
-        label:
-          en_US: Auto Save History
-          zh_Hans: 自动保存历史
-        description:
-          en_US: Whether to automatically save conversation history
-          zh_Hans: 是否自动保存对话历史
-        type: boolean
-        default: true
-      - name: timeout
-        label:
-          en_US: Request Timeout
-          zh_Hans: 请求超时
-        description:
-          en_US: Timeout in seconds for API requests
-          zh_Hans: API 请求超时时间（秒）
-        type: number
-        default: 120
-  - name: tbox-app-api
-    label:
-      en_US: Tbox App API
-      zh_Hans: 蚂蚁百宝箱平台 API
-    description:
-      en_US: Configure the Tbox App API of the pipeline
-      zh_Hans: 配置蚂蚁百宝箱平台 API
-    config:
-      - name: api-key
-        label:
-          en_US: API Key
-          zh_Hans: API 密钥
-        type: string
-        required: true
-        default: ''
-      - name: app-id
-        label:
-          en_US: App ID
-          zh_Hans: 应用 ID
-        type: string
-        required: true
-        default: ''
-  - name: dashscope-app-api
-    label:
-      en_US: Aliyun Dashscope App API
-      zh_Hans: 阿里云百炼平台 API
-    description:
-      en_US: Configure the Aliyun Dashscope App API of the pipeline
-      zh_Hans: 配置阿里云百炼平台 API
-    config:
-      - name: app-type
-        label:
-          en_US: App Type
-          zh_Hans: 应用类型
-        type: select
-        required: true
-        default: agent
-        options:
-          - name: agent
-            label:
-              en_US: Agent
-              zh_Hans: Agent
-          - name: workflow
-            label:
-              en_US: Workflow
-              zh_Hans: 工作流
-      - name: api-key
-        label:
-          en_US: API Key
-          zh_Hans: API 密钥
-        type: string
-        required: true
-        default: 'your-api-key'
-      - name: app-id
-        label:
-          en_US: App ID
-          zh_Hans: 应用 ID
-        type: string
-        required: true
-        default: 'your-app-id'
-      - name: references_quote
-        label:
-          en_US: References Quote
-          zh_Hans: 引用文本
-        description:
-          en_US: The text prompt when the references are included
-          zh_Hans: 包含引用资料时的文本提示
-        type: string
-        required: false
-        default: '参考资料来自:'
-  - name: langflow-api
-    label:
-      en_US: Langflow API
-      zh_Hans: Langflow API
-    description:
-      en_US: Configure the Langflow API of the pipeline, call the Langflow flow through the `Simplified Run Flow` interface
-      zh_Hans: 配置 Langflow API，通过 `Simplified Run Flow` 接口调用 Langflow 的流程
-    config:
-      - name: base-url
-        label:
-          en_US: Base URL
-          zh_Hans: 基础 URL
-        description:
-          en_US: The base URL of the Langflow server
-          zh_Hans: Langflow 服务器的基础 URL
-        type: string
-        required: true
-        default: 'http://localhost:7860'
-      - name: api-key
-        label:
-          en_US: API Key
-          zh_Hans: API 密钥
-        description:
-          en_US: The API key for the Langflow server
-          zh_Hans: Langflow 服务器的 API 密钥
-        type: string
-        required: true
-        default: 'your-api-key'
-      - name: flow-id
-        label:
-          en_US: Flow ID
-          zh_Hans: 流程 ID
-        description:
-          en_US: The ID of the flow to run
-          zh_Hans: 要运行的流程 ID
-        type: string
-        required: true
-        default: 'your-flow-id'
-      - name: input-type
-        label:
-          en_US: Input Type
-          zh_Hans: 输入类型
-        description:
-          en_US: The input type for the flow
-          zh_Hans: 流程的输入类型
-        type: string
-        required: false
-        default: 'chat'
-      - name: output-type
-        label:
-          en_US: Output Type
-          zh_Hans: 输出类型
-        description:
-          en_US: The output type for the flow
-          zh_Hans: 流程的输出类型
-        type: string
-        required: false
-        default: 'chat'
-      - name: tweaks
-        label:
-          en_US: Tweaks
-          zh_Hans: 调整参数
-        description:
-          en_US: Optional tweaks to apply to the flow
-          zh_Hans: 可选的流程调整参数
-        type: json
-        required: false
-        default: '{}'
+  # Runner config stages are dynamically added from AgentRunnerRegistry
+  # Each plugin runner's config schema is added as a separate stage
+  # The stage name matches the runner id for frontend matching