feat(agent-runner): add plugin runner host integration

src/langbot/pkg/agent/__init__.py

@@ -0,0 +1,37 @@
+"""Agent runner subsystem for LangBot."""
+from __future__ import annotations
+
+from .runner.descriptor import AgentRunnerDescriptor
+from .runner.id import parse_runner_id, format_runner_id, RunnerIdParts, is_plugin_runner_id
+from .runner.errors import (
+    AgentRunnerError,
+    RunnerNotFoundError,
+    RunnerNotAuthorizedError,
+    RunnerProtocolError,
+    RunnerExecutionError,
+)
+from .runner.registry import AgentRunnerRegistry
+from .runner.context_builder import AgentRunContextBuilder
+from .runner.resource_builder import AgentResourceBuilder
+from .runner.result_normalizer import AgentResultNormalizer
+from .runner.orchestrator import AgentRunOrchestrator
+from .runner.config_migration import ConfigMigration
+
+__all__ = [
+    'AgentRunnerDescriptor',
+    'parse_runner_id',
+    'format_runner_id',
+    'is_plugin_runner_id',
+    'RunnerIdParts',
+    'AgentRunnerError',
+    'RunnerNotFoundError',
+    'RunnerNotAuthorizedError',
+    'RunnerProtocolError',
+    'RunnerExecutionError',
+    'AgentRunnerRegistry',
+    'AgentRunContextBuilder',
+    'AgentResourceBuilder',
+    'AgentResultNormalizer',
+    'AgentRunOrchestrator',
+    'ConfigMigration',
+]

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

@@ -0,0 +1,66 @@
+"""Agent runner modules."""
+
+from __future__ import annotations
+
+from .descriptor import AgentRunnerDescriptor
+from .id import parse_runner_id, format_runner_id, RunnerIdParts
+from .errors import (
+    AgentRunnerError,
+    RunnerNotFoundError,
+    RunnerNotAuthorizedError,
+    RunnerProtocolError,
+    RunnerExecutionError,
+)
+from .registry import AgentRunnerRegistry
+from .context_builder import AgentRunContextBuilder
+from .resource_builder import AgentResourceBuilder
+from .result_normalizer import AgentResultNormalizer
+from .orchestrator import AgentRunOrchestrator
+from .config_migration import ConfigMigration
+from .default_config import AgentRunnerDefaultConfigService
+from .binding_resolver import AgentBindingResolver, AgentBindingResolutionError
+from .session_registry import (
+    AgentRunSessionRegistry,
+    AgentRunSession,
+    RunAuthorizationSnapshot,
+    get_session_registry,
+)
+from .run_ledger_store import RunLedgerStore
+from .events import (
+    MESSAGE_RECEIVED,
+    MESSAGE_RECALLED,
+    GROUP_MEMBER_JOINED,
+    FRIEND_REQUEST_RECEIVED,
+    RESERVED_EVENT_TYPES,
+)
+
+__all__ = [
+    'AgentRunnerDescriptor',
+    'parse_runner_id',
+    'format_runner_id',
+    'RunnerIdParts',
+    'AgentRunnerError',
+    'RunnerNotFoundError',
+    'RunnerNotAuthorizedError',
+    'RunnerProtocolError',
+    'RunnerExecutionError',
+    'AgentRunnerRegistry',
+    'AgentRunContextBuilder',
+    'AgentResourceBuilder',
+    'AgentResultNormalizer',
+    'AgentRunOrchestrator',
+    'ConfigMigration',
+    'AgentRunnerDefaultConfigService',
+    'AgentBindingResolver',
+    'AgentBindingResolutionError',
+    'AgentRunSessionRegistry',
+    'AgentRunSession',
+    'RunAuthorizationSnapshot',
+    'get_session_registry',
+    'RunLedgerStore',
+    'MESSAGE_RECEIVED',
+    'MESSAGE_RECALLED',
+    'GROUP_MEMBER_JOINED',
+    'FRIEND_REQUEST_RECEIVED',
+    'RESERVED_EVENT_TYPES',
+]

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

@@ -0,0 +1,70 @@
+"""Resolve host events to one effective Agent binding."""
+
+from __future__ import annotations
+
+from .host_models import AgentConfig, AgentBinding, AgentEventEnvelope, BindingScope
+
+
+class AgentBindingResolutionError(Exception):
+    """Raised when an event cannot resolve to exactly one Agent binding."""
+
+
+class AgentBindingResolver:
+    """Resolve an event to a single AgentBinding.
+
+    The target product model is one bot / IM channel -> one Agent. Fan-out,
+    observer agents, or multi-runner arbitration require separate delivery and
+    state semantics and are intentionally not hidden in this resolver.
+    """
+
+    def resolve_one(
+        self,
+        event: AgentEventEnvelope,
+        agents: list[AgentConfig],
+    ) -> AgentBinding:
+        """Resolve exactly one enabled Agent for the event.
+
+        Callers that source agents from bot/workspace/global configuration must
+        pre-filter candidates to the event scope before calling this resolver.
+        The current AgentConfig model represents one already-selected product
+        Agent and does not carry enough scope metadata to make that decision
+        safely here.
+        """
+        matches = [
+            agent
+            for agent in agents
+            if agent.enabled and event.event_type in agent.event_types
+        ]
+
+        if not matches:
+            raise AgentBindingResolutionError(
+                f'No Agent binding matches event_type={event.event_type}'
+            )
+
+        if len(matches) > 1:
+            agent_ids = ', '.join(agent.agent_id or '<anonymous>' for agent in matches)
+            raise AgentBindingResolutionError(
+                f'Multiple Agent bindings match event_type={event.event_type}: {agent_ids}'
+            )
+
+        return self._to_binding(matches[0])
+
+    def _to_binding(self, agent: AgentConfig) -> AgentBinding:
+        """Project product-level Agent config into the run-time binding model."""
+        scope = BindingScope(
+            scope_type='agent',
+            scope_id=agent.agent_id,
+        )
+
+        return AgentBinding(
+            binding_id=f"agent_{agent.agent_id or 'default'}_{agent.runner_id}",
+            scope=scope,
+            event_types=list(agent.event_types),
+            runner_id=agent.runner_id,
+            runner_config=agent.runner_config,
+            resource_policy=agent.resource_policy,
+            state_policy=agent.state_policy,
+            delivery_policy=agent.delivery_policy,
+            enabled=agent.enabled,
+            agent_id=agent.agent_id,
+        )

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

@@ -0,0 +1,171 @@
+"""Helpers for the current AgentRunner config shape."""
+
+from __future__ import annotations
+
+import typing
+
+
+LEGACY_RUNNER_ID_MAP: dict[str, str] = {
+    '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',
+    'deerflow-api': 'plugin:langbot/deerflow-agent/default',
+    'langflow-api': 'plugin:langbot/langflow-agent/default',
+    'tbox-app-api': 'plugin:langbot/tbox-agent/default',
+    'weknora-api': 'plugin:langbot/weknora-agent/default',
+}
+
+
+class ConfigMigration:
+    """Configuration helper for agent runner IDs.
+
+    Responsibilities:
+    - Resolve runner ID from ai.runner.id
+    - Migrate legacy ai.runner.runner + ai.<runner-name> blocks
+    - Extract current Agent/runner config from ai.runner_config
+    - Keep the current config container shape stable on save
+    """
+
+    @staticmethod
+    def resolve_runner_id(pipeline_config: dict[str, typing.Any]) -> str | None:
+        """Resolve runner ID from current configuration.
+
+        Args:
+            pipeline_config: Current configuration container
+
+        Returns:
+            Runner ID string, or None if not configured
+        """
+        ai_config = pipeline_config.get('ai', {})
+        runner_config = ai_config.get('runner', {})
+
+        runner_id = runner_config.get('id')
+        if runner_id:
+            return runner_id
+
+        legacy_runner = runner_config.get('runner')
+        if isinstance(legacy_runner, str):
+            return LEGACY_RUNNER_ID_MAP.get(legacy_runner)
+
+        return None
+
+    @staticmethod
+    def resolve_runner_config(
+        pipeline_config: dict[str, typing.Any],
+        runner_id: str,
+    ) -> dict[str, typing.Any]:
+        """Resolve Agent/runner configuration from the current container.
+
+        Args:
+            pipeline_config: Current configuration container
+            runner_id: Resolved runner ID
+
+        Returns:
+            Runner configuration dict (empty if not found)
+        """
+        ai_config = pipeline_config.get('ai', {})
+
+        runner_configs = ai_config.get('runner_config', {})
+        if runner_id in runner_configs:
+            return runner_configs[runner_id]
+
+        legacy_runner = ConfigMigration._legacy_runner_name_for_id(runner_id)
+        if legacy_runner and isinstance(ai_config.get(legacy_runner), dict):
+            return ConfigMigration._normalize_legacy_runner_config(
+                legacy_runner,
+                ai_config[legacy_runner],
+            )
+
+        return {}
+
+    @staticmethod
+    def get_expire_time(pipeline_config: dict[str, typing.Any]) -> int:
+        """Get conversation expire time from configuration.
+
+        Args:
+            pipeline_config: Current configuration container
+
+        Returns:
+            Expire time in seconds (0 means no expiry)
+        """
+        ai_config = pipeline_config.get('ai', {})
+        runner_config = ai_config.get('runner', {})
+        return runner_config.get('expire-time', 0)
+
+    @staticmethod
+    def migrate_pipeline_config(pipeline_config: dict[str, typing.Any]) -> dict[str, typing.Any]:
+        """Normalize the current config container before saving.
+
+        Args:
+            pipeline_config: Original configuration
+
+        Returns:
+            Configuration with explicit ai.runner and ai.runner_config containers
+        """
+        new_config = dict(pipeline_config)
+        if 'ai' not in new_config:
+            return new_config
+
+        ai_config = dict(new_config.get('ai', {}))
+
+        runner_config = dict(ai_config.get('runner', {}))
+        runner_configs = dict(ai_config.get('runner_config', {}))
+
+        legacy_runner = runner_config.get('runner')
+        mapped_runner_id = None
+        if isinstance(legacy_runner, str):
+            mapped_runner_id = LEGACY_RUNNER_ID_MAP.get(legacy_runner)
+
+        if mapped_runner_id and not runner_config.get('id'):
+            runner_config = {
+                key: value
+                for key, value in runner_config.items()
+                if key != 'runner'
+            }
+            runner_config['id'] = mapped_runner_id
+
+        if mapped_runner_id and mapped_runner_id not in runner_configs:
+            legacy_config = ai_config.get(legacy_runner)
+            if isinstance(legacy_config, dict):
+                runner_configs[mapped_runner_id] = ConfigMigration._normalize_legacy_runner_config(
+                    legacy_runner,
+                    legacy_config,
+                )
+
+        ai_config['runner'] = runner_config
+        ai_config['runner_config'] = runner_configs
+        if mapped_runner_id and legacy_runner in ai_config:
+            ai_config.pop(legacy_runner, None)
+        new_config['ai'] = ai_config
+
+        return new_config
+
+    @staticmethod
+    def _legacy_runner_name_for_id(runner_id: str) -> str | None:
+        for legacy_runner, mapped_runner_id in LEGACY_RUNNER_ID_MAP.items():
+            if mapped_runner_id == runner_id:
+                return legacy_runner
+        return None
+
+    @staticmethod
+    def _normalize_legacy_runner_config(
+        legacy_runner: str,
+        legacy_config: dict[str, typing.Any],
+    ) -> dict[str, typing.Any]:
+        """Normalize legacy runner config blocks to current plugin schema quirks."""
+        normalized = dict(legacy_config)
+
+        if legacy_runner == 'local-agent':
+            model = normalized.get('model')
+            if isinstance(model, str):
+                normalized['model'] = {
+                    'primary': model,
+                    'fallbacks': [],
+                }
+            knowledge_base = normalized.pop('knowledge-base', None)
+            if 'knowledge-bases' not in normalized and isinstance(knowledge_base, str):
+                normalized['knowledge-bases'] = [] if knowledge_base in {'', '__none__', '__none'} else [knowledge_base]
+
+        return normalized

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

@@ -0,0 +1,204 @@
+"""Helpers for interpreting AgentRunner DynamicForm configuration."""
+from __future__ import annotations
+
+import typing
+
+from .descriptor import AgentRunnerDescriptor
+
+
+FORM_ITEM_TYPE_ALIASES = {
+    'select-llm-model': 'llm-model-selector',
+    'select-knowledge-bases': 'knowledge-base-multi-selector',
+}
+LLM_MODEL_SELECTOR_TYPES = {'model-fallback-selector', 'llm-model-selector'}
+KB_SELECTOR_TYPES = {'knowledge-base-multi-selector'}
+PROMPT_EDITOR_TYPES = {'prompt-editor'}
+NONE_SENTINELS = {'', '__none__', '__none'}
+
+
+def normalize_schema_item_type(item_type: typing.Any) -> typing.Any:
+    """Normalize legacy/frontend DynamicForm aliases to protocol field types."""
+    if not isinstance(item_type, str):
+        return item_type
+    return FORM_ITEM_TYPE_ALIASES.get(item_type, item_type)
+
+
+def iter_schema_items(
+    descriptor: AgentRunnerDescriptor | None,
+    field_types: set[str],
+) -> typing.Iterator[dict[str, typing.Any]]:
+    """Yield descriptor config schema items whose type is in field_types."""
+    if descriptor is None:
+        return
+    for item in descriptor.config_schema or []:
+        if not isinstance(item, dict):
+            continue
+        if normalize_schema_item_type(item.get('type')) in field_types:
+            yield item
+
+
+def uses_host_models(descriptor: AgentRunnerDescriptor | None) -> bool:
+    """Return whether LangBot should resolve model resources for this runner."""
+    return any(True for _ in iter_schema_items(descriptor, LLM_MODEL_SELECTOR_TYPES))
+
+
+def uses_host_tools(descriptor: AgentRunnerDescriptor | None) -> bool:
+    """Return whether LangBot should expose tool resources to this runner."""
+    return descriptor is not None and descriptor.supports_tool_calling()
+
+
+def uses_host_knowledge_bases(descriptor: AgentRunnerDescriptor | None) -> bool:
+    """Return whether LangBot should expose knowledge-base resources to this runner."""
+    return descriptor is not None and descriptor.supports_knowledge_retrieval()
+
+
+def supports_skill_authoring(descriptor: AgentRunnerDescriptor | None) -> bool:
+    """Return whether the runner wants Host skill-authoring tools."""
+    if descriptor is None:
+        return False
+    return descriptor.capabilities.skill_authoring
+
+
+def extract_prompt_config(
+    descriptor: AgentRunnerDescriptor | None,
+    runner_config: dict[str, typing.Any],
+    default_prompt: list[dict[str, typing.Any]],
+) -> list[dict[str, typing.Any]]:
+    """Extract the prompt-editor value selected by the runner schema."""
+    for item in iter_schema_items(descriptor, PROMPT_EDITOR_TYPES):
+        field_name = item.get('name')
+        if field_name and field_name in runner_config:
+            configured_prompt = runner_config[field_name]
+            if isinstance(configured_prompt, list):
+                return configured_prompt
+        default_value = item.get('default')
+        if isinstance(default_value, list):
+            return default_value
+    return default_prompt
+
+
+def extract_model_selection(
+    descriptor: AgentRunnerDescriptor | None,
+    runner_config: dict[str, typing.Any],
+) -> tuple[str, list[str]]:
+    """Extract primary/fallback LLM selections from schema-defined fields."""
+    primary_uuid = ''
+    fallback_uuids: list[str] = []
+
+    for item in iter_schema_items(descriptor, LLM_MODEL_SELECTOR_TYPES):
+        field_name = item.get('name')
+        if not field_name:
+            continue
+
+        value = runner_config.get(field_name, item.get('default'))
+        item_type = normalize_schema_item_type(item.get('type'))
+        if item_type == 'model-fallback-selector':
+            if isinstance(value, str):
+                primary_uuid = value
+            elif isinstance(value, dict):
+                primary_uuid = value.get('primary') or ''
+                fallbacks = value.get('fallbacks', [])
+                if isinstance(fallbacks, list):
+                    fallback_uuids = [fallback for fallback in fallbacks if isinstance(fallback, str)]
+            break
+
+        if item_type == 'llm-model-selector' and isinstance(value, str):
+            primary_uuid = value
+            break
+
+    return primary_uuid, fallback_uuids
+
+
+def extract_knowledge_base_uuids(
+    descriptor: AgentRunnerDescriptor | None,
+    runner_config: dict[str, typing.Any],
+) -> list[str]:
+    """Extract configured knowledge-base UUIDs from schema-defined fields."""
+    if not uses_host_knowledge_bases(descriptor):
+        return []
+
+    kb_uuids: list[str] = []
+    for item in iter_schema_items(descriptor, KB_SELECTOR_TYPES):
+        field_name = item.get('name')
+        if not field_name:
+            continue
+        value = runner_config.get(field_name, item.get('default', []))
+        if isinstance(value, list):
+            kb_uuids.extend(
+                kb_uuid for kb_uuid in value if isinstance(kb_uuid, str) and kb_uuid not in NONE_SENTINELS
+            )
+
+    return list(dict.fromkeys(kb_uuids))
+
+
+def iter_config_model_refs(
+    descriptor: AgentRunnerDescriptor,
+    runner_config: dict[str, typing.Any],
+) -> typing.Iterator[tuple[str, str]]:
+    """Yield model references declared by schema-defined model selector fields."""
+    for item in descriptor.config_schema or []:
+        if not isinstance(item, dict):
+            continue
+
+        field_name = item.get('name')
+        field_type = normalize_schema_item_type(item.get('type'))
+        if not field_name or field_name not in runner_config:
+            continue
+
+        value = runner_config.get(field_name)
+        if field_type == 'model-fallback-selector':
+            if isinstance(value, str) and value not in NONE_SENTINELS:
+                yield 'llm', value
+            elif isinstance(value, dict):
+                primary = value.get('primary')
+                if isinstance(primary, str) and primary not in NONE_SENTINELS:
+                    yield 'llm', primary
+                fallbacks = value.get('fallbacks', [])
+                if isinstance(fallbacks, list):
+                    for fallback_uuid in fallbacks:
+                        if isinstance(fallback_uuid, str) and fallback_uuid not in NONE_SENTINELS:
+                            yield 'llm', fallback_uuid
+        elif field_type == 'llm-model-selector':
+            if isinstance(value, str) and value not in NONE_SENTINELS:
+                yield 'llm', value
+        elif field_type == 'rerank-model-selector':
+            if isinstance(value, str) and value not in NONE_SENTINELS:
+                yield 'rerank', value
+
+
+def set_empty_llm_model_selection(
+    descriptor: AgentRunnerDescriptor,
+    runner_config: dict[str, typing.Any],
+    model_uuid: str,
+) -> bool:
+    """Set the first empty schema-defined LLM selector to model_uuid."""
+    for item in iter_schema_items(descriptor, LLM_MODEL_SELECTOR_TYPES):
+        field_name = item.get('name')
+        field_type = normalize_schema_item_type(item.get('type'))
+        if not field_name:
+            continue
+
+        value = runner_config.get(field_name, item.get('default'))
+        if field_type == 'model-fallback-selector':
+            if isinstance(value, dict):
+                primary = value.get('primary') or ''
+                if primary not in NONE_SENTINELS:
+                    return False
+                fallbacks = value.get('fallbacks', [])
+                runner_config[field_name] = {
+                    'primary': model_uuid,
+                    'fallbacks': fallbacks if isinstance(fallbacks, list) else [],
+                }
+                return True
+            if isinstance(value, str) and value not in NONE_SENTINELS:
+                return False
+            runner_config[field_name] = {'primary': model_uuid, 'fallbacks': []}
+            return True
+
+        if field_type == 'llm-model-selector':
+            if isinstance(value, str) and value not in NONE_SENTINELS:
+                return False
+            runner_config[field_name] = model_uuid
+            return True
+
+    return False

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

@@ -0,0 +1,490 @@
+"""Agent run context builder for provisioning AgentRunContext envelopes."""
+
+from __future__ import annotations
+
+import uuid
+import time
+import typing
+
+from ...core import app
+from .descriptor import AgentRunnerDescriptor
+from .persistent_state_store import get_persistent_state_store
+from .host_models import AgentEventEnvelope, AgentBinding
+
+
+DEFAULT_RUNNER_TIMEOUT_SECONDS = 300
+
+
+# Internal models for the agent runner context protocol.
+
+
+class AgentTrigger(typing.TypedDict):
+    """Agent trigger information."""
+
+    type: str
+    source: str
+    timestamp: int | None
+
+
+class ConversationContext(typing.TypedDict):
+    """Conversation context."""
+
+    conversation_id: str | None
+    thread_id: str | None
+    launcher_type: str | None
+    launcher_id: str | None
+    sender_id: str | None
+    bot_id: str | None
+    workspace_id: str | None
+    session_id: str | None
+
+
+class AgentInput(typing.TypedDict):
+    """Agent input."""
+
+    text: str | None
+    contents: list[dict[str, typing.Any]]
+    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]
+
+
+# Resource payload models matching langbot-plugin-sdk/resources.py.
+
+
+class ModelResource(typing.TypedDict):
+    """Model resource payload."""
+
+    model_id: str
+    model_type: str | None
+    provider: str | None
+    operations: list[str]
+
+
+class ToolResource(typing.TypedDict):
+    """Tool resource payload."""
+
+    tool_name: str
+    tool_type: str | None
+    description: str | None
+    operations: list[str]
+
+
+class KnowledgeBaseResource(typing.TypedDict):
+    """Knowledge base resource payload."""
+
+    kb_id: str
+    kb_name: str | None
+    kb_type: str | None
+    operations: list[str]
+
+
+class SkillResource(typing.TypedDict):
+    """Skill resource payload."""
+
+    skill_name: str
+    display_name: str | None
+    description: str | None
+
+
+class StorageResource(typing.TypedDict):
+    """Storage resource payload."""
+
+    plugin_storage: bool
+    workspace_storage: bool
+
+
+class AgentResources(typing.TypedDict):
+    """Agent resources payload."""
+
+    models: list[ModelResource]
+    tools: list[ToolResource]
+    knowledge_bases: list[KnowledgeBaseResource]
+    skills: list[SkillResource]
+    storage: StorageResource
+    platform_capabilities: dict[str, typing.Any]
+
+
+class AgentRuntimeContext(typing.TypedDict):
+    """Agent runtime context."""
+
+    langbot_version: str | None
+    trace_id: str | None
+    deadline_at: float | None
+    metadata: dict[str, typing.Any]
+
+
+class AgentRunContextPayload(typing.TypedDict):
+    """AgentRunContext payload passed to an agent runner.
+
+    Protocol v1 structure - matches SDK AgentRunContext.
+
+    Note: The 'config' field contains the current Agent/runner config
+    from ai.runner_config[runner_id] while the current Query entry remains
+    a temporary configuration container. It is not plugin instance config.
+    """
+
+    run_id: str
+    trigger: AgentTrigger
+    conversation: ConversationContext | None
+    event: dict[str, typing.Any]  # REQUIRED for Protocol v1
+    actor: dict[str, typing.Any] | None
+    subject: dict[str, typing.Any] | None
+    input: AgentInput
+    delivery: dict[str, typing.Any]  # REQUIRED for Protocol v1
+    resources: AgentResources
+    context: dict[str, typing.Any]  # ContextAccess - REQUIRED for Protocol v1
+    state: AgentRunState
+    runtime: AgentRuntimeContext
+    config: dict[str, typing.Any]  # Agent/runner config from ai.runner_config[runner_id]
+    adapter: dict[str, typing.Any] | None  # Entry adapter context
+    metadata: dict[str, typing.Any]  # Additional metadata
+
+
+class AgentRunContextBuilder:
+    """Builder for provisioning AgentRunContext.
+
+    Responsibilities:
+    - Generate new run_id (UUID, not query id)
+    - Set trigger type based on event source
+    - Build conversation context from event
+    - Build input from event
+    - Build state snapshot from PersistentStateStore
+    - Build runtime context with host info, trace_id, deadline
+    - Set config from current Agent/runner configuration.
+
+    Query adaptation belongs to QueryEntryAdapter, not this builder.
+    """
+
+    ap: app.Application
+
+    def __init__(self, ap: app.Application):
+        self.ap = ap
+
+    @staticmethod
+    def _positive_int(value: typing.Any) -> int | None:
+        if isinstance(value, bool):
+            return None
+        if isinstance(value, int) and value > 0:
+            return value
+        if isinstance(value, str) and value.isdigit():
+            parsed_value = int(value)
+            if parsed_value > 0:
+                return parsed_value
+        return None
+
+    @staticmethod
+    def _is_llm_model_resource(model_resource: ModelResource) -> bool:
+        operations = model_resource.get('operations')
+        if isinstance(operations, list) and operations:
+            return bool({'invoke', 'stream'} & {str(operation) for operation in operations})
+        return model_resource.get('model_type') != 'rerank'
+
+    async def _build_model_context_window_tokens(self, resources: AgentResources) -> int | None:
+        model_mgr = getattr(self.ap, 'model_mgr', None)
+        if model_mgr is None:
+            return None
+
+        for model_resource in resources.get('models', []):
+            if not self._is_llm_model_resource(model_resource):
+                continue
+
+            model_uuid = model_resource.get('model_id')
+            if not isinstance(model_uuid, str) or not model_uuid:
+                continue
+
+            try:
+                model = await model_mgr.get_model_by_uuid(model_uuid)
+            except Exception as exc:
+                logger = getattr(self.ap, 'logger', None)
+                if logger is not None:
+                    logger.debug(f'Failed to resolve model context window for {model_uuid}: {exc}')
+                continue
+
+            model_entity = getattr(model, 'model_entity', None)
+            context_length = self._positive_int(getattr(model_entity, 'context_length', None))
+            return context_length
+
+        return None
+
+    async def build_context_from_event(
+        self,
+        event: AgentEventEnvelope,
+        binding: AgentBinding,
+        descriptor: AgentRunnerDescriptor,
+        resources: AgentResources,
+    ) -> AgentRunContextPayload:
+        """Build AgentRunContext from event-first envelope.
+
+        This is the main entry point for Protocol v1.
+        Does NOT inline full history by default.
+
+        Args:
+            event: Event envelope
+            binding: Agent binding
+            descriptor: Runner descriptor
+            resources: Built resources
+
+        Returns:
+            AgentRunContextPayload for the runner
+        """
+        # Generate new run_id
+        run_id = str(uuid.uuid4())
+
+        # Build trigger from event
+        trigger: AgentTrigger = {
+            'type': event.event_type,
+            'source': event.source,
+            'timestamp': event.event_time or int(time.time()),
+        }
+
+        # Build conversation context from event
+        conversation: ConversationContext | None = None
+        if event.conversation_id:
+            conversation = {
+                'session_id': None,
+                'conversation_id': event.conversation_id,
+                'thread_id': event.thread_id,
+                'launcher_type': None,  # Will be filled from actor/subject if needed
+                'launcher_id': None,
+                'sender_id': event.actor.actor_id if event.actor else None,
+                'bot_id': event.bot_id,
+                'workspace_id': event.workspace_id,
+            }
+
+        # Build event context (Protocol v1 event-first)
+        event_context = {
+            'event_id': event.event_id,
+            'event_type': event.event_type,
+            'event_time': event.event_time,
+            'source': event.source,
+            'source_event_type': event.source_event_type,
+            'raw_ref': event.raw_ref.model_dump(mode='json') if event.raw_ref else None,
+            'data': event.data,
+        }
+
+        # Build actor context
+        actor_context = None
+        if event.actor:
+            actor_context = {
+                'actor_type': event.actor.actor_type,
+                'actor_id': event.actor.actor_id,
+                'actor_name': event.actor.actor_name,
+            }
+
+        # Build subject context
+        subject_context = None
+        if event.subject:
+            subject_context = {
+                'subject_type': event.subject.subject_type,
+                'subject_id': event.subject.subject_id,
+                'data': event.subject.data,
+            }
+
+        # Build input from event
+        input: AgentInput = {
+            'text': event.input.text,
+            'contents': [c.model_dump(mode='json') if hasattr(c, 'model_dump') else c for c in event.input.contents],
+            'attachments': [
+                a.model_dump(mode='json') if hasattr(a, 'model_dump') else a for a in event.input.attachments
+            ],
+        }
+
+        # Build context access (no history inlined by default for Protocol v1)
+        # Populate with actual values from stores
+        context_access = await self._build_context_access(event, descriptor, binding)
+
+        # Build state snapshot from persistent state store (event-first Protocol v1)
+        persistent_state_store = get_persistent_state_store(self.ap.persistence_mgr.get_db_engine())
+        state: AgentRunState = await persistent_state_store.build_snapshot_from_event(event, binding, descriptor)
+
+        model_context_window_tokens = await self._build_model_context_window_tokens(resources)
+
+        # Build runtime context
+        runtime: AgentRuntimeContext = {
+            'langbot_version': self.ap.ver_mgr.get_current_version(),
+            'trace_id': run_id,
+            'deadline_at': self._build_deadline_from_binding(binding),
+            'metadata': {
+                'bot_id': event.bot_id,
+                'workspace_id': event.workspace_id,
+                'streaming_supported': event.delivery.supports_streaming,
+                'model_context_window_tokens': model_context_window_tokens,
+            },
+        }
+
+        # Build delivery context
+        delivery_context = {
+            'surface': event.delivery.surface,
+            'reply_target': event.delivery.reply_target,
+            'supports_streaming': event.delivery.supports_streaming,
+            'supports_edit': event.delivery.supports_edit,
+            'supports_reaction': event.delivery.supports_reaction,
+            'max_message_size': event.delivery.max_message_size,
+            'platform_capabilities': event.delivery.platform_capabilities,
+        }
+
+        # Build adapter context (empty for event-first)
+        adapter_context = {
+            'extra': {},
+        }
+
+        # Build full context - Protocol v1 structure
+        context: AgentRunContextPayload = {
+            'run_id': run_id,
+            'trigger': trigger,
+            'conversation': conversation,
+            'event': event_context,  # REQUIRED
+            'actor': actor_context,
+            'subject': subject_context,
+            'input': input,
+            'delivery': delivery_context,  # REQUIRED
+            'resources': resources,
+            'context': context_access,  # ContextAccess - REQUIRED
+            'state': state,
+            'runtime': runtime,
+            'config': binding.runner_config,
+            'adapter': adapter_context,
+            'metadata': {},  # Additional metadata
+        }
+
+        return context
+
+    def _build_deadline_from_binding(self, binding: AgentBinding) -> float | None:
+        """Build deadline timestamp from binding timeout config.
+
+        Args:
+            binding: Agent binding with runner_config
+
+        Returns:
+            Deadline timestamp or None
+        """
+        timeout = binding.runner_config.get('timeout', DEFAULT_RUNNER_TIMEOUT_SECONDS)
+        if timeout is None:
+            return None
+
+        try:
+            timeout_seconds = float(timeout)
+        except (TypeError, ValueError):
+            return None
+
+        if timeout_seconds <= 0:
+            return None
+
+        return time.time() + timeout_seconds
+
+    async def _build_context_access(
+        self,
+        event: AgentEventEnvelope,
+        descriptor: AgentRunnerDescriptor,
+        binding: AgentBinding | None = None,
+    ) -> dict[str, typing.Any]:
+        """Build ContextAccess with actual values from stores.
+
+        Args:
+            event: Event envelope
+            descriptor: Runner descriptor
+            binding: Agent binding (required for state_policy in event-first mode)
+
+        Returns:
+            ContextAccess dict
+        """
+        conversation_id = event.conversation_id
+        permissions = descriptor.permissions
+        history_perms = set(permissions.history)
+        event_perms = set(permissions.events)
+        storage_perms = set(permissions.storage)
+
+        history_page_enabled = 'page' in history_perms and conversation_id is not None
+        history_search_enabled = 'search' in history_perms and conversation_id is not None
+        event_get_enabled = 'get' in event_perms
+        event_page_enabled = 'page' in event_perms and conversation_id is not None
+        steering_pull_enabled = (
+            bool(getattr(descriptor.capabilities, 'steering', False)) and conversation_id is not None
+        )
+        run_get_enabled = True
+        run_list_enabled = conversation_id is not None
+        run_events_page_enabled = True
+        run_cancel_enabled = True
+        run_append_result_enabled = False
+        run_finalize_enabled = False
+        run_claim_enabled = False
+        run_renew_claim_enabled = False
+        run_release_claim_enabled = False
+        runtime_register_enabled = False
+        runtime_heartbeat_enabled = False
+        runtime_list_enabled = False
+
+        # Determine state API availability based on binding state_policy.
+        state_enabled = False
+        storage_enabled = False
+        if binding is not None:
+            state_policy = binding.state_policy
+            if state_policy.enable_state and state_policy.state_scopes:
+                state_enabled = True
+
+            resource_policy = binding.resource_policy
+            storage_enabled = ('plugin' in storage_perms and resource_policy.allow_plugin_storage) or (
+                'workspace' in storage_perms and resource_policy.allow_workspace_storage
+            )
+
+        # Get latest cursor and has_history_before if conversation exists
+        latest_cursor = None
+        has_history_before = False
+
+        if conversation_id:
+            try:
+                from .transcript_store import TranscriptStore
+
+                store = TranscriptStore(self.ap.persistence_mgr.get_db_engine())
+
+                latest_cursor = await store.get_latest_cursor(conversation_id)
+                if latest_cursor:
+                    has_history_before = True
+            except Exception as e:
+                self.ap.logger.warning(f'Failed to get transcript cursor: {e}')
+
+        return {
+            'conversation_id': conversation_id,
+            'thread_id': event.thread_id,
+            'latest_cursor': latest_cursor,
+            'event_seq': None,  # Will be populated when EventLog is written
+            'transcript_seq': int(latest_cursor) if latest_cursor else None,
+            'has_history_before': has_history_before,
+            'inline_policy': {
+                'mode': 'current_event',
+                'delivered_count': 0,
+                'source_total_count': None,
+                'messages_complete': False,
+                'reason': 'current_event_only',
+            },
+            'available_apis': {
+                'prompt_get': False,
+                'history_page': history_page_enabled,
+                'history_search': history_search_enabled,
+                'event_get': event_get_enabled,
+                'event_page': event_page_enabled,
+                'state': state_enabled,
+                'storage': storage_enabled,
+                'steering_pull': steering_pull_enabled,
+                'run_get': run_get_enabled,
+                'run_list': run_list_enabled,
+                'run_events_page': run_events_page_enabled,
+                'run_cancel': run_cancel_enabled,
+                'run_append_result': run_append_result_enabled,
+                'run_finalize': run_finalize_enabled,
+                'run_claim': run_claim_enabled,
+                'run_renew_claim': run_renew_claim_enabled,
+                'run_release_claim': run_release_claim_enabled,
+                'runtime_register': runtime_register_enabled,
+                'runtime_heartbeat': runtime_heartbeat_enabled,
+                'runtime_list': runtime_list_enabled,
+            },
+        }

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

@@ -0,0 +1,72 @@
+"""Default AgentRunner binding configuration helpers."""
+
+from __future__ import annotations
+
+import sqlalchemy
+
+from ...core import app
+from ...entity.persistence import pipeline as persistence_pipeline
+from . import config_schema
+from .config_migration import ConfigMigration
+
+
+class AgentRunnerDefaultConfigService:
+    """Apply AgentRunner schema-defined defaults to host binding config."""
+
+    ap: app.Application
+
+    def __init__(self, ap: app.Application) -> None:
+        self.ap = ap
+
+    async def _get_runner_descriptor(self, runner_id: str):
+        registry = getattr(self.ap, 'agent_runner_registry', None)
+        if registry is None:
+            return None
+        try:
+            return await registry.get(runner_id, bound_plugins=None)
+        except Exception as e:
+            logger = getattr(self.ap, 'logger', None)
+            if logger:
+                logger.warning(f'Failed to load AgentRunner descriptor while setting default model: {e}')
+            return None
+
+    async def auto_set_default_pipeline_llm_model(self, model_uuid: str) -> bool:
+        """Set model_uuid into the default pipeline runner config when the selector is empty."""
+        result = await self.ap.persistence_mgr.execute_async(
+            sqlalchemy.select(persistence_pipeline.LegacyPipeline).where(
+                persistence_pipeline.LegacyPipeline.is_default == True
+            )
+        )
+        pipeline = result.first()
+        if pipeline is None:
+            return False
+
+        return await self.set_pipeline_llm_model_if_empty(pipeline, model_uuid)
+
+    async def set_pipeline_llm_model_if_empty(
+        self,
+        pipeline: persistence_pipeline.LegacyPipeline,
+        model_uuid: str,
+    ) -> bool:
+        """Set model_uuid into a pipeline's schema-defined LLM selector if it is empty."""
+        pipeline_config = pipeline.config
+        if not isinstance(pipeline_config, dict):
+            return False
+
+        runner_id = ConfigMigration.resolve_runner_id(pipeline_config)
+        if not runner_id:
+            return False
+
+        descriptor = await self._get_runner_descriptor(runner_id)
+        if descriptor is None:
+            return False
+
+        ai_config = pipeline_config.setdefault('ai', {})
+        runner_configs = ai_config.setdefault('runner_config', {})
+        runner_config = runner_configs.setdefault(runner_id, {})
+
+        if not config_schema.set_empty_llm_model_selection(descriptor, runner_config, model_uuid):
+            return False
+
+        await self.ap.pipeline_service.update_pipeline(pipeline.uuid, {'config': pipeline_config})
+        return True

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

@@ -0,0 +1,82 @@
+"""Agent runner descriptor."""
+from __future__ import annotations
+
+import typing
+import pydantic
+
+from langbot_plugin.api.entities.builtin.agent_runner.manifest import (
+    AgentRunnerCapabilities,
+    AgentRunnerPermissions,
+)
+
+
+class AgentRunnerDescriptor(pydantic.BaseModel):
+    """Descriptor for an agent runner.
+
+    Represents the discovered metadata for a runner, including
+    its identity, capabilities, permissions, and configuration schema.
+    """
+
+    id: str
+    """Unique runner ID: plugin:author/plugin_name/runner_name"""
+
+    source: typing.Literal['plugin']
+    """Runner source type"""
+
+    label: dict[str, str]
+    """Display labels keyed by locale (e.g., en_US, zh_Hans)"""
+
+    description: dict[str, str] | None = None
+    """Optional description keyed by locale"""
+
+    plugin_author: str
+    """Plugin author from manifest"""
+
+    plugin_name: str
+    """Plugin name from manifest"""
+
+    runner_name: str
+    """AgentRunner component name from manifest"""
+
+    plugin_version: str | None = None
+    """Optional plugin version"""
+
+    config_schema: list[dict[str, typing.Any]] = pydantic.Field(default_factory=list)
+    """Configuration schema using DynamicForm format"""
+
+    capabilities: AgentRunnerCapabilities = pydantic.Field(
+        default_factory=AgentRunnerCapabilities
+    )
+    """Runner capabilities: streaming, tool_calling, knowledge_retrieval, etc."""
+
+    permissions: AgentRunnerPermissions = pydantic.Field(
+        default_factory=AgentRunnerPermissions
+    )
+    """Requested LangBot resource permissions."""
+
+    raw_manifest: dict[str, typing.Any] = pydantic.Field(default_factory=dict)
+    """Original manifest for reference"""
+
+    model_config = pydantic.ConfigDict(
+        extra='allow',
+    )
+
+    def get_plugin_id(self) -> str:
+        """Return plugin identifier as author/name."""
+        return f'{self.plugin_author}/{self.plugin_name}'
+
+    def supports_streaming(self) -> bool:
+        """Check if runner supports streaming output."""
+        return self.capabilities.streaming
+
+    def supports_tool_calling(self) -> bool:
+        """Check if runner supports tool calling."""
+        return self.capabilities.tool_calling
+
+    def supports_knowledge_retrieval(self) -> bool:
+        """Check if runner supports knowledge retrieval."""
+        return self.capabilities.knowledge_retrieval
+
+    def supports_steering(self) -> bool:
+        """Check if runner supports run steering/follow-up input."""
+        return bool(getattr(self.capabilities, 'steering', False))

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

@@ -0,0 +1,37 @@
+"""Agent runner errors."""
+from __future__ import annotations
+
+
+class AgentRunnerError(Exception):
+    """Base error for agent runner operations."""
+    pass
+
+
+class RunnerNotFoundError(AgentRunnerError):
+    """Runner not found in registry."""
+    def __init__(self, runner_id: str):
+        self.runner_id = runner_id
+        super().__init__(f'Agent runner not found: {runner_id}')
+
+
+class RunnerNotAuthorizedError(AgentRunnerError):
+    """Runner not authorized for this binding."""
+    def __init__(self, runner_id: str, bound_plugins: list[str] | None):
+        self.runner_id = runner_id
+        self.bound_plugins = bound_plugins
+        super().__init__(f'Agent runner {runner_id} not authorized for bound_plugins={bound_plugins}')
+
+
+class RunnerProtocolError(AgentRunnerError):
+    """Runner protocol version mismatch or invalid manifest."""
+    def __init__(self, runner_id: str, message: str):
+        self.runner_id = runner_id
+        super().__init__(f'Agent runner protocol error for {runner_id}: {message}')
+
+
+class RunnerExecutionError(AgentRunnerError):
+    """Runner execution failed."""
+    def __init__(self, runner_id: str, message: str, retryable: bool = False):
+        self.runner_id = runner_id
+        self.retryable = retryable
+        super().__init__(f'Agent runner {runner_id} execution failed: {message}')

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

@@ -0,0 +1,315 @@
+"""EventLog store for writing and querying event records."""
+from __future__ import annotations
+
+import json
+import datetime
+import typing
+import uuid
+
+import sqlalchemy
+from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession
+from sqlalchemy.orm import sessionmaker
+
+from ...entity.persistence.event_log import EventLog
+
+
+UTC = datetime.timezone.utc
+
+
+def _utc_now() -> datetime.datetime:
+    return datetime.datetime.now(UTC)
+
+
+def _datetime_to_epoch(value: datetime.datetime | None) -> int | None:
+    if value is None:
+        return None
+    if value.tzinfo is None:
+        value = value.replace(tzinfo=UTC)
+    else:
+        value = value.astimezone(UTC)
+    return int(value.timestamp())
+
+
+class EventLogStore:
+    """Store for EventLog records.
+
+    Handles writing events to the event log and querying them.
+    All methods are async and use the provided database engine.
+    """
+
+    engine: AsyncEngine
+
+    # Hard limits
+    MAX_INPUT_SUMMARY_LENGTH = 1000
+
+    def __init__(self, engine: AsyncEngine):
+        self.engine = engine
+        self._session_factory = sessionmaker(
+            engine, class_=AsyncSession, expire_on_commit=False
+        )
+
+    async def append_event(
+        self,
+        event_id: str | None,
+        event_type: str,
+        source: str,
+        bot_id: str | None = None,
+        workspace_id: str | None = None,
+        conversation_id: str | None = None,
+        thread_id: str | None = None,
+        actor_type: str | None = None,
+        actor_id: str | None = None,
+        actor_name: str | None = None,
+        subject_type: str | None = None,
+        subject_id: str | None = None,
+        input_summary: str | None = None,
+        input_json: dict[str, typing.Any] | None = None,
+        raw_ref: str | None = None,
+        run_id: str | None = None,
+        runner_id: str | None = None,
+        event_time: datetime.datetime | None = None,
+        metadata: dict[str, typing.Any] | None = None,
+    ) -> str:
+        """Append an event to the event log.
+
+        Args:
+            event_id: Unique event ID (generated if None)
+            event_type: Event type
+            source: Event source
+            bot_id: Bot UUID
+            workspace_id: Workspace ID
+            conversation_id: Conversation ID
+            thread_id: Thread ID
+            actor_type: Actor type
+            actor_id: Actor ID
+            actor_name: Actor display name
+            subject_type: Subject type
+            subject_id: Subject ID
+            input_summary: Brief input summary
+            input_json: Full input JSON
+            raw_ref: Reference to raw event payload
+            run_id: Run ID processing this event
+            runner_id: Runner ID processing this event
+            event_time: When the event occurred
+            metadata: Additional metadata
+
+        Returns:
+            The event_id
+        """
+        if event_id is None:
+            event_id = str(uuid.uuid4())
+
+        # Truncate input summary if too long
+        if input_summary and len(input_summary) > self.MAX_INPUT_SUMMARY_LENGTH:
+            input_summary = input_summary[:self.MAX_INPUT_SUMMARY_LENGTH - 3] + "..."
+
+        async with self._session_factory() as session:
+            event = EventLog(
+                event_id=event_id,
+                event_type=event_type,
+                event_time=event_time,
+                source=source,
+                bot_id=bot_id,
+                workspace_id=workspace_id,
+                conversation_id=conversation_id,
+                thread_id=thread_id,
+                actor_type=actor_type,
+                actor_id=actor_id,
+                actor_name=actor_name,
+                subject_type=subject_type,
+                subject_id=subject_id,
+                input_summary=input_summary,
+                input_json=json.dumps(input_json) if input_json else None,
+                raw_ref=raw_ref,
+                run_id=run_id,
+                runner_id=runner_id,
+                metadata_json=json.dumps(metadata) if metadata else None,
+                created_at=_utc_now(),
+            )
+            session.add(event)
+            await session.commit()
+
+        return event_id
+
+    async def get_event(
+        self,
+        event_id: str,
+    ) -> dict[str, typing.Any] | None:
+        """Get a single event by ID.
+
+        Args:
+            event_id: Event ID
+
+        Returns:
+            Event record as dict, or None if not found
+        """
+        async with self._session_factory() as session:
+            result = await session.execute(
+                sqlalchemy.select(EventLog).where(EventLog.event_id == event_id)
+            )
+            row = result.scalars().first()
+            if row is None:
+                return None
+            return self._row_to_dict(row)
+
+    async def page_events(
+        self,
+        conversation_id: str | None = None,
+        event_types: list[str] | None = None,
+        before_seq: int | None = None,
+        limit: int = 50,
+        bot_id: str | None = None,
+        workspace_id: str | None = None,
+        thread_id: str | None = None,
+        strict_thread: bool = False,
+    ) -> tuple[list[dict[str, typing.Any]], int | None, bool]:
+        """Page through event records.
+
+        Args:
+            conversation_id: Filter by conversation ID
+            event_types: Filter by event types
+            before_seq: Get events before this sequence number
+            limit: Maximum items to return (capped at 100)
+            bot_id: Optional bot scope filter
+            workspace_id: Optional workspace scope filter
+            thread_id: Optional thread scope filter
+            strict_thread: When true, require thread_id equality including NULL
+
+        Returns:
+            Tuple of (items, next_seq, has_more)
+        """
+        limit = min(limit, 100)  # Hard cap
+
+        async with self._session_factory() as session:
+            query = sqlalchemy.select(EventLog)
+
+            if conversation_id is not None:
+                query = query.where(EventLog.conversation_id == conversation_id)
+            query = self._apply_scope_filters(query, bot_id, workspace_id, thread_id, strict_thread)
+
+            if event_types:
+                query = query.where(EventLog.event_type.in_(event_types))
+
+            if before_seq is not None:
+                query = query.where(EventLog.id < before_seq)
+
+            query = query.order_by(EventLog.id.desc()).limit(limit + 1)
+
+            result = await session.execute(query)
+            rows = result.scalars().all()
+
+            items = [self._row_to_dict(row) for row in rows[:limit]]
+            has_more = len(rows) > limit
+            next_seq = items[-1]['id'] if items and has_more else None
+
+            return items, next_seq, has_more
+
+    async def get_latest_cursor(
+        self,
+        conversation_id: str,
+    ) -> str | None:
+        """Get the latest cursor for a conversation.
+
+        Args:
+            conversation_id: Conversation ID
+
+        Returns:
+            Cursor string (seq number), or None if no events
+        """
+        async with self._session_factory() as session:
+            result = await session.execute(
+                sqlalchemy.select(EventLog.id)
+                .where(EventLog.conversation_id == conversation_id)
+                .order_by(EventLog.id.desc())
+                .limit(1)
+            )
+            row = result.scalars().first()
+            if row is None:
+                return None
+            return str(row)
+
+    async def has_events_before(
+        self,
+        conversation_id: str,
+        seq: int,
+        bot_id: str | None = None,
+        workspace_id: str | None = None,
+        thread_id: str | None = None,
+        strict_thread: bool = False,
+    ) -> bool:
+        """Check if there are events before a sequence number.
+
+        Args:
+            conversation_id: Conversation ID
+            seq: Sequence number
+
+        Returns:
+            True if there are events before
+        """
+        async with self._session_factory() as session:
+            query = (
+                sqlalchemy.select(sqlalchemy.func.count())
+                .select_from(EventLog)
+                .where(EventLog.conversation_id == conversation_id, EventLog.id < seq)
+            )
+            query = self._apply_scope_filters(query, bot_id, workspace_id, thread_id, strict_thread)
+            result = await session.execute(query)
+            count = result.scalar()
+            return count > 0
+
+    def _apply_scope_filters(
+        self,
+        query: typing.Any,
+        bot_id: str | None,
+        workspace_id: str | None,
+        thread_id: str | None,
+        strict_thread: bool,
+    ) -> typing.Any:
+        if bot_id is not None:
+            query = query.where(EventLog.bot_id == bot_id)
+        if workspace_id is not None:
+            query = query.where(EventLog.workspace_id == workspace_id)
+        if strict_thread:
+            if thread_id is None:
+                query = query.where(EventLog.thread_id.is_(None))
+            else:
+                query = query.where(EventLog.thread_id == thread_id)
+        return query
+
+    async def cleanup_events_older_than(
+        self,
+        before: datetime.datetime,
+    ) -> int:
+        """Delete EventLog rows created before the supplied timestamp."""
+        async with self._session_factory() as session:
+            result = await session.execute(
+                sqlalchemy.delete(EventLog).where(EventLog.created_at < before)
+            )
+            await session.commit()
+            return result.rowcount or 0
+
+    def _row_to_dict(self, row: EventLog) -> dict[str, typing.Any]:
+        """Convert an EventLog row to dict."""
+        return {
+            'id': row.id,
+            'event_id': row.event_id,
+            'event_type': row.event_type,
+            'event_time': _datetime_to_epoch(row.event_time),
+            'source': row.source,
+            'bot_id': row.bot_id,
+            'workspace_id': row.workspace_id,
+            'conversation_id': row.conversation_id,
+            'thread_id': row.thread_id,
+            'actor_type': row.actor_type,
+            'actor_id': row.actor_id,
+            'actor_name': row.actor_name,
+            'subject_type': row.subject_type,
+            'subject_id': row.subject_id,
+            'input_summary': row.input_summary,
+            'input_json': json.loads(row.input_json) if row.input_json else None,
+            'raw_ref': row.raw_ref,
+            'run_id': row.run_id,
+            'runner_id': row.runner_id,
+            'created_at': _datetime_to_epoch(row.created_at),
+            'metadata': json.loads(row.metadata_json) if row.metadata_json else {},
+        }

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

@@ -0,0 +1,25 @@
+"""Canonical AgentRunner event names reserved for future EBA integration."""
+from __future__ import annotations
+
+
+MESSAGE_RECEIVED = 'message.received'
+"""A normal message entered the current Pipeline."""
+
+MESSAGE_RECALLED = 'message.recalled'
+"""A platform message was recalled or deleted."""
+
+GROUP_MEMBER_JOINED = 'group.member_joined'
+"""A new member joined a group/channel conversation."""
+
+FRIEND_REQUEST_RECEIVED = 'friend.request_received'
+"""A new friend/contact request was received."""
+
+
+RESERVED_EVENT_TYPES = frozenset(
+    {
+        MESSAGE_RECEIVED,
+        MESSAGE_RECALLED,
+        GROUP_MEMBER_JOINED,
+        FRIEND_REQUEST_RECEIVED,
+    }
+)

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

@@ -0,0 +1,210 @@
+"""Agent event envelope and binding models for LangBot Host.
+
+These are Host-internal models, not exposed to SDK.
+"""
+from __future__ import annotations
+
+import typing
+import pydantic
+
+from langbot_plugin.api.entities.builtin.agent_runner.event import (
+    ActorContext,
+    SubjectContext,
+    RawEventRef,
+)
+from langbot_plugin.api.entities.builtin.agent_runner.input import AgentInput
+from langbot_plugin.api.entities.builtin.agent_runner.delivery import DeliveryContext
+
+
+class AgentEventEnvelope(pydantic.BaseModel):
+    """Event envelope for LangBot Host event gateway.
+
+    This is the unified input model that replaces Query-first approach.
+    IM / WebUI / API / EventRouter all produce this envelope.
+    """
+
+    event_id: str
+    """Unique event identifier."""
+
+    event_type: str
+    """Event type (message.received, message.recalled, etc.)."""
+
+    event_time: int | None = None
+    """Event timestamp (epoch seconds)."""
+
+    source: str
+    """Event source (platform, webui, api, scheduler, system)."""
+
+    source_event_type: str | None = None
+    """Original source event type, when available."""
+
+    bot_id: str | None = None
+    """Bot UUID handling this event."""
+
+    workspace_id: str | None = None
+    """Workspace ID (for multi-tenant)."""
+
+    conversation_id: str | None = None
+    """Conversation ID."""
+
+    thread_id: str | None = None
+    """Thread ID (for platforms supporting threads)."""
+
+    actor: ActorContext | None = None
+    """Actor (who triggered the event)."""
+
+    subject: SubjectContext | None = None
+    """Subject (what the event is about)."""
+
+    input: AgentInput
+    """Event input."""
+
+    delivery: DeliveryContext
+    """Delivery context."""
+
+    raw_ref: RawEventRef | None = None
+    """Reference to raw event payload."""
+
+    data: dict[str, typing.Any] = pydantic.Field(default_factory=dict)
+    """Small structured event payload. Large payloads should be referenced via raw_ref."""
+
+
+# Binding scope types
+class BindingScope(pydantic.BaseModel):
+    """Scope for agent binding."""
+
+    scope_type: typing.Literal["agent", "bot", "workspace", "global"] = "agent"
+    """Scope type."""
+
+    scope_id: str | None = None
+    """Scope identifier (agent_id, bot_uuid, etc.)."""
+
+
+class ResourcePolicy(pydantic.BaseModel):
+    """Resource policy for agent binding.
+
+    Controls what resources the runner can access.
+    """
+
+    allowed_model_uuids: list[str] | None = None
+    """Additional model UUID grants. None means no additional model grants."""
+
+    allowed_tool_names: list[str] | None = None
+    """Additional tool name grants. None means no additional tool grants."""
+
+    allowed_kb_uuids: list[str] | None = None
+    """Additional knowledge base UUID grants. None means no additional KB grants."""
+
+    allowed_skill_names: list[str] | None = None
+    """Allowed skill names. None means all currently visible skills are allowed."""
+
+    allow_plugin_storage: bool = True
+    """Whether plugin storage is allowed."""
+
+    allow_workspace_storage: bool = False
+    """Whether workspace storage is allowed."""
+
+
+class StatePolicy(pydantic.BaseModel):
+    """State policy for agent binding.
+
+    Controls state management behavior.
+    """
+
+    enable_state: bool = True
+    """Whether host-owned state is enabled."""
+
+    state_scopes: list[typing.Literal["conversation", "actor", "subject", "runner"]] = (
+        pydantic.Field(default_factory=lambda: ["conversation", "actor"])
+    )
+    """Enabled state scopes."""
+
+
+class DeliveryPolicy(pydantic.BaseModel):
+    """Delivery policy for agent binding.
+
+    Controls how results are delivered.
+    """
+
+    enable_streaming: bool = True
+    """Whether streaming output is enabled."""
+
+    enable_reply: bool = True
+    """Whether reply is enabled."""
+
+    max_message_size: int | None = None
+    """Maximum message size."""
+
+
+class AgentConfig(pydantic.BaseModel):
+    """Host-side Agent configuration.
+
+    Product-level Agent is the target replacement for Pipeline-owned agent
+    config. Current Pipeline entry paths can project their config into this
+    model during migration.
+    """
+
+    agent_id: str | None = None
+    """Host-side Agent/config identifier."""
+
+    runner_id: str
+    """Runner ID to invoke."""
+
+    runner_config: dict[str, typing.Any] = pydantic.Field(default_factory=dict)
+    """Agent/runner binding configuration."""
+
+    resource_policy: ResourcePolicy = pydantic.Field(default_factory=ResourcePolicy)
+    """Resource policy for this Agent."""
+
+    state_policy: StatePolicy = pydantic.Field(default_factory=StatePolicy)
+    """State policy for this Agent."""
+
+    delivery_policy: DeliveryPolicy = pydantic.Field(default_factory=DeliveryPolicy)
+    """Delivery policy for this Agent."""
+
+    event_types: list[str] = pydantic.Field(default_factory=lambda: ["message.received"])
+    """Event types this Agent handles."""
+
+    enabled: bool = True
+    """Whether this Agent can be selected by a binding resolver."""
+
+    metadata: dict[str, typing.Any] = pydantic.Field(default_factory=dict)
+    """Non-protocol diagnostic metadata, such as legacy config source."""
+
+
+class AgentBinding(pydantic.BaseModel):
+    """Binding configuration for mapping events to runners.
+
+    This is Host-internal model for event-to-runner binding.
+    It replaces the old Pipeline runner config role.
+    """
+
+    binding_id: str
+    """Unique binding identifier."""
+
+    scope: BindingScope = pydantic.Field(default_factory=BindingScope)
+    """Binding scope."""
+
+    event_types: list[str] = pydantic.Field(default_factory=lambda: ["message.received"])
+    """Event types this binding handles."""
+
+    runner_id: str
+    """Runner ID to invoke."""
+
+    runner_config: dict[str, typing.Any] = pydantic.Field(default_factory=dict)
+    """Current Agent/runner configuration."""
+
+    resource_policy: ResourcePolicy = pydantic.Field(default_factory=ResourcePolicy)
+    """Resource policy."""
+
+    state_policy: StatePolicy = pydantic.Field(default_factory=StatePolicy)
+    """State policy."""
+
+    delivery_policy: DeliveryPolicy = pydantic.Field(default_factory=DeliveryPolicy)
+    """Delivery policy."""
+
+    enabled: bool = True
+    """Whether binding is enabled."""
+
+    agent_id: str | None = None
+    """Host-side Agent/config identifier for this binding."""

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

@@ -0,0 +1,91 @@
+"""Agent runner ID parsing and formatting."""
+from __future__ import annotations
+
+import dataclasses
+
+
+@dataclasses.dataclass(frozen=True)
+class RunnerIdParts:
+    """Parsed runner ID components."""
+    source: str  # 'plugin' (future: 'builtin')
+    plugin_author: str
+    plugin_name: str
+    runner_name: str
+
+    def to_plugin_id(self) -> str:
+        """Return plugin identifier as author/name."""
+        return f'{self.plugin_author}/{self.plugin_name}'
+
+
+def parse_runner_id(runner_id: str) -> RunnerIdParts:
+    """Parse runner ID string into components.
+
+    Args:
+        runner_id: Runner ID in format 'plugin:author/plugin_name/runner_name'
+
+    Returns:
+        RunnerIdParts with parsed components
+
+    Raises:
+        ValueError: If runner_id format is invalid
+    """
+    if runner_id.startswith('plugin:'):
+        parts = runner_id[7:].split('/')
+        if len(parts) != 3:
+            raise ValueError(
+                f'Invalid plugin runner ID format: {runner_id}. '
+                f'Expected: plugin:author/plugin_name/runner_name'
+            )
+        plugin_author, plugin_name, runner_name = parts
+        if not plugin_author or not plugin_name or not runner_name:
+            raise ValueError(
+                f'Invalid plugin runner ID: {runner_id}. '
+                f'author, plugin_name, and runner_name must be non-empty'
+            )
+        return RunnerIdParts(
+            source='plugin',
+            plugin_author=plugin_author,
+            plugin_name=plugin_name,
+            runner_name=runner_name,
+        )
+    else:
+        # Only plugin runner IDs are valid at the protocol boundary.
+        raise ValueError(
+            f'Invalid runner ID format: {runner_id}. '
+            f'Expected: plugin:author/plugin_name/runner_name'
+        )
+
+
+def format_runner_id(
+    source: str,
+    plugin_author: str,
+    plugin_name: str,
+    runner_name: str,
+) -> str:
+    """Format runner ID from components.
+
+    Args:
+        source: Runner source ('plugin')
+        plugin_author: Plugin author
+        plugin_name: Plugin name
+        runner_name: Runner component name
+
+    Returns:
+        Runner ID string
+    """
+    if source == 'plugin':
+        return f'plugin:{plugin_author}/{plugin_name}/{runner_name}'
+    else:
+        raise ValueError(f'Invalid runner source: {source}')
+
+
+def is_plugin_runner_id(runner_id: str) -> bool:
+    """Check if runner ID is a plugin runner.
+
+    Args:
+        runner_id: Runner ID string
+
+    Returns:
+        True if runner ID starts with 'plugin:'
+    """
+    return runner_id.startswith('plugin:')

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

@@ -0,0 +1,131 @@
+"""Plugin-runtime invocation for AgentRunner executions."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+import traceback
+import typing
+
+from langbot_plugin.entities.io.errors import ActionCallTimeoutError
+
+from ...core import app
+from .context_builder import AgentRunContextPayload
+from .descriptor import AgentRunnerDescriptor
+from .errors import RunnerExecutionError
+
+
+class AgentRunnerInvoker:
+    """Invoke an AgentRunner through the plugin runtime.
+
+    This keeps runtime transport, deadline enforcement, and transport error
+    mapping out of the orchestration state machine.
+    """
+
+    ap: app.Application
+
+    def __init__(self, ap: app.Application):
+        self.ap = ap
+
+    async def invoke(
+        self,
+        descriptor: AgentRunnerDescriptor,
+        context: AgentRunContextPayload,
+    ) -> typing.AsyncGenerator[dict[str, typing.Any], None]:
+        """Invoke the runner and yield raw result dictionaries."""
+        if not self.ap.plugin_connector.is_enable_plugin:
+            raise RunnerExecutionError(
+                descriptor.id,
+                'Plugin system is disabled',
+                retryable=False,
+            )
+
+        try:
+            gen = self.ap.plugin_connector.run_agent(
+                plugin_author=descriptor.plugin_author,
+                plugin_name=descriptor.plugin_name,
+                runner_name=descriptor.runner_name,
+                context=context,
+            )
+
+            while True:
+                try:
+                    result_dict = await self._next_with_deadline(gen, descriptor, context)
+                except StopAsyncIteration:
+                    break
+                yield result_dict
+
+        except asyncio.TimeoutError as e:
+            raise RunnerExecutionError(
+                descriptor.id,
+                'Runner timed out (code: runner.timeout)',
+                retryable=True,
+            ) from e
+        except ActionCallTimeoutError as e:
+            raise RunnerExecutionError(
+                descriptor.id,
+                f'{e} (code: runner.timeout)',
+                retryable=True,
+            ) from e
+        except RunnerExecutionError:
+            raise
+        except Exception as e:
+            self.ap.logger.error(
+                f'Runner {descriptor.id} unexpected error: {traceback.format_exc()}'
+            )
+            raise RunnerExecutionError(
+                descriptor.id,
+                str(e),
+                retryable=False,
+            )
+
+    async def _next_with_deadline(
+        self,
+        gen: typing.AsyncGenerator[dict[str, typing.Any], None],
+        descriptor: AgentRunnerDescriptor,
+        context: AgentRunContextPayload,
+    ) -> dict[str, typing.Any]:
+        """Read the next runner result while enforcing the run deadline."""
+        remaining = self._remaining_deadline_seconds(context)
+        if remaining is not None and remaining <= 0:
+            await self._close_generator(gen, descriptor)
+            raise asyncio.TimeoutError
+
+        try:
+            if remaining is None:
+                return await anext(gen)
+            return await asyncio.wait_for(anext(gen), timeout=remaining)
+        except StopAsyncIteration:
+            if self._is_deadline_exhausted(context):
+                raise asyncio.TimeoutError
+            raise
+        except asyncio.TimeoutError:
+            await self._close_generator(gen, descriptor)
+            raise
+
+    def _remaining_deadline_seconds(
+        self,
+        context: AgentRunContextPayload,
+    ) -> float | None:
+        runtime = context.get('runtime') or {}
+        deadline_at = runtime.get('deadline_at')
+        if deadline_at is None:
+            return None
+        try:
+            return float(deadline_at) - time.time()
+        except (TypeError, ValueError):
+            return None
+
+    def _is_deadline_exhausted(self, context: AgentRunContextPayload) -> bool:
+        remaining = self._remaining_deadline_seconds(context)
+        return remaining is not None and remaining <= 0
+
+    async def _close_generator(
+        self,
+        gen: typing.AsyncGenerator[dict[str, typing.Any], None],
+        descriptor: AgentRunnerDescriptor,
+    ) -> None:
+        try:
+            await gen.aclose()
+        except Exception as e:
+            self.ap.logger.warning(f'Failed to close timed-out runner {descriptor.id}: {e}')

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

@@ -0,0 +1,536 @@
+"""Agent run orchestrator for coordinating runner execution."""
+
+from __future__ import annotations
+
+import time
+import typing
+
+from langbot_plugin.api.entities.builtin.provider import message as provider_message
+from langbot_plugin.api.entities.builtin.pipeline import query as pipeline_query
+
+from ...core import app
+from .binding_resolver import AgentBindingResolver
+from .context_builder import AgentRunContextBuilder, AgentRunContextPayload
+from .descriptor import AgentRunnerDescriptor
+from .host_models import AgentBinding, AgentEventEnvelope
+from .invoker import AgentRunnerInvoker
+from .query_bridge import QueryRunBridge
+from .registry import AgentRunnerRegistry
+from .resource_builder import AgentResourceBuilder
+from .result_normalizer import AgentResultNormalizer
+from .run_journal import AgentRunJournal
+from .session_registry import AgentRunSessionRegistry, get_session_registry
+from .state_scope import build_state_context
+from ...provider.tools.loaders import skill as skill_loader
+
+
+ACTIVATED_SKILL_NAMES_STATE_KEY = 'host.activated_skills'
+
+
+class AgentRunOrchestrator:
+    """Coordinate one AgentRunner execution.
+
+    The orchestrator keeps the run state machine readable and delegates
+    transport, Query bridging, and persistence side effects to narrower
+    collaborators.
+    """
+
+    ap: app.Application
+    registry: AgentRunnerRegistry
+    context_builder: AgentRunContextBuilder
+    resource_builder: AgentResourceBuilder
+    result_normalizer: AgentResultNormalizer
+    binding_resolver: AgentBindingResolver
+    query_bridge: QueryRunBridge
+    invoker: AgentRunnerInvoker
+    journal: AgentRunJournal
+    _session_registry: AgentRunSessionRegistry
+
+    def __init__(
+        self,
+        ap: app.Application,
+        registry: AgentRunnerRegistry,
+    ):
+        self.ap = ap
+        self.registry = registry
+        self.context_builder = AgentRunContextBuilder(ap)
+        self.resource_builder = AgentResourceBuilder(ap)
+        self.result_normalizer = AgentResultNormalizer(ap)
+        self.binding_resolver = AgentBindingResolver()
+        self.query_bridge = QueryRunBridge(self.binding_resolver)
+        self.invoker = AgentRunnerInvoker(ap)
+        self.journal = AgentRunJournal(ap)
+        self._session_registry = get_session_registry()
+
+    async def run(
+        self,
+        event: AgentEventEnvelope,
+        binding: AgentBinding,
+        bound_plugins: list[str] | None = None,
+        adapter_context: dict[str, typing.Any] | None = None,
+    ) -> typing.AsyncGenerator[provider_message.Message | provider_message.MessageChunk, None]:
+        """Run an AgentRunner from an event-first envelope."""
+        runner_id = binding.runner_id
+        descriptor = await self.registry.get(runner_id, bound_plugins)
+
+        resources = await self.resource_builder.build_resources_from_binding(
+            event=event,
+            binding=binding,
+            descriptor=descriptor,
+        )
+
+        context = await self.context_builder.build_context_from_event(
+            event=event,
+            binding=binding,
+            descriptor=descriptor,
+            resources=resources,
+        )
+
+        session_query_id = None
+        if adapter_context:
+            query = adapter_context.get('_query')
+            if query is not None:
+                skill_loader.restore_activated_skills_from_state(
+                    self.ap,
+                    query,
+                    context.get('state', {}),
+                )
+            session_query_id = adapter_context.get('query_id')
+            if query is not None or session_query_id is not None:
+                context['context']['available_apis']['prompt_get'] = True
+            if 'params' in adapter_context:
+                context['adapter']['extra']['params'] = adapter_context['params']
+
+        state_context = build_state_context(event, binding, descriptor)
+        run_id = context['run_id']
+        available_apis = context.get('context', {}).get('available_apis')
+        run_authorization = {
+            'runner_id': descriptor.id,
+            'binding_id': binding.binding_id,
+            'plugin_identity': descriptor.get_plugin_id(),
+            'resources': resources,
+            'available_apis': available_apis,
+            'conversation_id': event.conversation_id,
+            'bot_id': event.bot_id,
+            'workspace_id': event.workspace_id,
+            'thread_id': event.thread_id,
+            'state_policy': {
+                'enable_state': binding.state_policy.enable_state,
+                'state_scopes': list(binding.state_policy.state_scopes),
+            },
+            'state_context': state_context,
+        }
+
+        seen_sequences: set[int] = set()
+        last_sequence = 0
+        assistant_transcript_written = False
+        terminal_status: str | None = None
+        terminal_reason: str | None = None
+        terminal_usage: dict[str, typing.Any] | None = None
+
+        try:
+            await self.journal.create_run(
+                event=event,
+                binding=binding,
+                descriptor=descriptor,
+                context=context,
+                authorization=run_authorization,
+            )
+            await self._session_registry.register(
+                run_id=run_id,
+                runner_id=descriptor.id,
+                query_id=session_query_id,
+                plugin_identity=descriptor.get_plugin_id(),
+                resources=resources,
+                available_apis=context.get('context', {}).get('available_apis'),
+                conversation_id=event.conversation_id,
+                bot_id=event.bot_id,
+                workspace_id=event.workspace_id,
+                thread_id=event.thread_id,
+                state_policy={
+                    'enable_state': binding.state_policy.enable_state,
+                    'state_scopes': list(binding.state_policy.state_scopes),
+                },
+                state_context=state_context,
+            )
+
+            event_log_id = await self.journal.write_event_log(
+                event=event,
+                binding=binding,
+                run_id=run_id,
+                runner_id=descriptor.id,
+            )
+            if event.event_type == 'message.received' and event.conversation_id:
+                await self.journal.write_user_transcript(
+                    event=event,
+                    event_log_id=event_log_id,
+                )
+
+            async for result_dict in self.invoker.invoke(descriptor, context):
+                result_dict = dict(result_dict)
+                sequence = result_dict.get('sequence')
+                if sequence is not None:
+                    try:
+                        sequence_int = int(sequence)
+                    except (TypeError, ValueError):
+                        self.ap.logger.warning(f'Runner {descriptor.id} returned invalid result sequence: {sequence}')
+                        sequence_int = last_sequence + 1
+                        result_dict['sequence'] = sequence_int
+                    else:
+                        if sequence_int in seen_sequences:
+                            self.ap.logger.warning(
+                                f'Runner {descriptor.id} returned duplicate result sequence '
+                                f'{sequence_int} for run {run_id}; dropping duplicate'
+                            )
+                            continue
+                        if sequence_int <= 0:
+                            self.ap.logger.warning(
+                                f'Runner {descriptor.id} returned non-positive result sequence '
+                                f'{sequence_int} for run {run_id}'
+                            )
+                            sequence_int = last_sequence + 1
+                            result_dict['sequence'] = sequence_int
+                        elif last_sequence and sequence_int != last_sequence + 1:
+                            self.ap.logger.warning(
+                                f'Runner {descriptor.id} result sequence gap or out-of-order '
+                                f'for run {run_id}: previous={last_sequence}, current={sequence_int}'
+                            )
+                        seen_sequences.add(sequence_int)
+                        last_sequence = max(last_sequence, sequence_int)
+                else:
+                    sequence_int = last_sequence + 1
+                    result_dict['sequence'] = sequence_int
+                    seen_sequences.add(sequence_int)
+                    last_sequence = sequence_int
+
+                result_type = result_dict.get('type')
+                if result_type and not self.result_normalizer.validate_payload(
+                    result_type,
+                    result_dict.get('data', {}),
+                    descriptor,
+                ):
+                    continue
+
+                await self.journal.append_run_result(
+                    result_dict=result_dict,
+                    run_id=run_id,
+                    sequence=sequence_int,
+                )
+
+                if result_type == 'state.updated':
+                    await self.journal.handle_state_updated_event(
+                        result_dict,
+                        event,
+                        binding,
+                        descriptor,
+                        run_id=run_id,
+                    )
+                    await self.result_normalizer.normalize(result_dict, descriptor)
+                    continue
+
+                if result_type == 'run.completed':
+                    terminal_status = 'completed'
+                    terminal_reason = (
+                        result_dict.get('data', {}).get('finish_reason')
+                        if isinstance(result_dict.get('data'), dict)
+                        else None
+                    )
+                    usage = result_dict.get('usage')
+                    if isinstance(usage, dict):
+                        terminal_usage = usage
+                elif result_type == 'run.failed':
+                    terminal_status = 'failed'
+                    data = result_dict.get('data') if isinstance(result_dict.get('data'), dict) else {}
+                    terminal_reason = data.get('error') or data.get('code')
+                    usage = result_dict.get('usage')
+                    if isinstance(usage, dict):
+                        terminal_usage = usage
+
+                has_completed_message = result_type == 'message.completed' or (
+                    result_type == 'run.completed'
+                    and isinstance(result_dict.get('data'), dict)
+                    and bool(result_dict['data'].get('message'))
+                )
+                if has_completed_message and event.conversation_id and not assistant_transcript_written:
+                    await self.journal.write_assistant_transcript(
+                        result_dict=result_dict,
+                        event=event,
+                        run_id=run_id,
+                        runner_id=descriptor.id,
+                    )
+                    assistant_transcript_written = True
+
+                result = await self.result_normalizer.normalize(result_dict, descriptor)
+                if result is not None:
+                    yield result
+
+                run_snapshot = await self.journal.get_run(run_id)
+                if run_snapshot and run_snapshot.get('cancel_requested_at') is not None:
+                    terminal_status = 'cancelled'
+                    terminal_reason = run_snapshot.get('status_reason') or 'cancel_requested'
+                    break
+            await self.journal.finalize_run(
+                run_id=run_id,
+                status=terminal_status or 'completed',
+                status_reason=terminal_reason,
+                usage=terminal_usage,
+            )
+        except Exception as exc:
+            failed_usage = terminal_usage
+            await self.journal.finalize_run(
+                run_id=run_id,
+                status='timeout' if self._is_deadline_exhausted(context) else 'failed',
+                status_reason=str(exc),
+                usage=failed_usage,
+            )
+            raise
+        finally:
+            session = await self._session_registry.unregister(run_id)
+            pending_steering = session.get('steering_queue', []) if session else []
+            if pending_steering:
+                try:
+                    await self.journal.write_steering_dropped_audits(
+                        pending_steering,
+                        run_id,
+                        descriptor.id,
+                    )
+                except Exception as exc:
+                    self.ap.logger.warning(
+                        f'Failed to write dropped steering audit for run {run_id}: {exc}',
+                        exc_info=True,
+                    )
+
+    async def run_from_query(
+        self,
+        query: pipeline_query.Query,
+    ) -> typing.AsyncGenerator[provider_message.Message | provider_message.MessageChunk, None]:
+        """Run an AgentRunner from the current Pipeline Query entry point."""
+        plan = self.query_bridge.build_plan(query)
+        adapter_context = dict(plan.adapter_context)
+        adapter_context['_query'] = query
+
+        # Materialize inbound attachments into sandbox before running
+        await self._materialize_inbound_attachments(query, plan.event)
+
+        async for result in self.run(
+            plan.event,
+            plan.binding,
+            bound_plugins=plan.bound_plugins,
+            adapter_context=adapter_context,
+        ):
+            yield result
+
+    async def _materialize_inbound_attachments(
+        self,
+        query: pipeline_query.Query,
+        event: AgentEventEnvelope,
+    ) -> None:
+        """Persist inbound attachments into the sandbox and update event.input.attachments.
+
+        No-op when the box service is unavailable or there are no attachments.
+        On success, updates each attachment in event.input.attachments with the
+        sandbox path so runners can tell the model where to find the files.
+        """
+        box_service = getattr(self.ap, 'box_service', None)
+        if box_service is None or not getattr(box_service, 'available', False):
+            return
+
+        try:
+            materialized = await box_service.materialize_inbound_attachments(query)
+        except Exception as e:
+            # Never break the chat turn over attachment IO
+            self.ap.logger.warning(f'Inbound attachment materialization failed: {e}')
+            return
+
+        if not materialized:
+            return
+
+        # Build a lookup by name for matching
+        materialized_by_name = {att.get('name'): att for att in materialized if att.get('name')}
+
+        # Update event.input.attachments with sandbox paths
+        if event.input and event.input.attachments:
+            for attachment in event.input.attachments:
+                name = attachment.name
+                if name and name in materialized_by_name:
+                    mat = materialized_by_name[name]
+                    # Update the attachment with sandbox path
+                    attachment.path = mat.get('path')
+                    attachment.size = mat.get('size') or attachment.size
+                    attachment.mime_type = attachment.mime_type or mat.get('mime_type')
+
+        # Store materialized descriptors in query variables for downstream use
+        query.variables['_sandbox_inbound_attachments'] = materialized
+
+    def resolve_runner_id_for_telemetry(self, query: pipeline_query.Query) -> str | None:
+        """Resolve runner ID for telemetry/logging without full execution."""
+        return self.query_bridge.resolve_runner_id_for_telemetry(query)
+
+    async def try_claim_steering_from_query(
+        self,
+        query: pipeline_query.Query,
+    ) -> bool:
+        """Claim a query as steering input for an active run when possible."""
+        plan = self.query_bridge.build_plan(query)
+        event = plan.event
+        binding = plan.binding
+
+        if event.event_type != 'message.received' or not event.conversation_id:
+            return False
+
+        descriptor = await self.registry.get(binding.runner_id, plan.bound_plugins)
+        if not descriptor.supports_steering():
+            return False
+
+        target_run_id = await self._session_registry.find_steering_target(
+            conversation_id=event.conversation_id,
+            runner_id=descriptor.id,
+            bot_id=event.bot_id,
+            workspace_id=event.workspace_id,
+            thread_id=event.thread_id,
+        )
+        if target_run_id is None:
+            return False
+
+        steering_item = self._build_steering_item(event, target_run_id, descriptor.id)
+        if not await self._session_registry.enqueue_steering(target_run_id, steering_item):
+            return False
+
+        try:
+            event_log_id = await self.journal.write_event_log(
+                event=event,
+                binding=binding,
+                run_id=target_run_id,
+                runner_id=descriptor.id,
+                metadata={
+                    'steering': {
+                        'status': 'queued',
+                        'trigger_behavior': 'absorbed_into_active_run',
+                        'claimed_by_run_id': target_run_id,
+                        'claimed_runner_id': descriptor.id,
+                        'claimed_at': steering_item.get('claimed_at'),
+                    },
+                },
+            )
+            await self.journal.write_user_transcript(event, event_log_id)
+        except Exception as exc:
+            self.ap.logger.warning(
+                f'Failed to persist steering event {event.event_id} for run {target_run_id}: {exc}',
+                exc_info=True,
+            )
+
+        self.ap.logger.info(f'Claimed event {event.event_id} as steering input for run {target_run_id}')
+        return True
+
+    def _build_steering_item(
+        self,
+        event: AgentEventEnvelope,
+        run_id: str,
+        runner_id: str,
+    ) -> dict[str, typing.Any]:
+        """Build the run-scoped steering item returned by the Host pull API."""
+        return {
+            'claimed_run_id': run_id,
+            'runner_id': runner_id,
+            'claimed_at': int(time.time()),
+            'event': {
+                'event_id': event.event_id,
+                'event_type': event.event_type,
+                'event_time': event.event_time,
+                'source': event.source,
+                'source_event_type': event.source_event_type,
+                'raw_ref': event.raw_ref.model_dump(mode='json') if event.raw_ref else None,
+                'data': event.data,
+            },
+            'conversation': {
+                'conversation_id': event.conversation_id,
+                'thread_id': event.thread_id,
+                'bot_id': event.bot_id,
+                'workspace_id': event.workspace_id,
+            },
+            'actor': event.actor.model_dump(mode='json') if event.actor else None,
+            'subject': event.subject.model_dump(mode='json') if event.subject else None,
+            'input': {
+                'text': event.input.text if event.input else None,
+                'contents': [
+                    c.model_dump(mode='json') if hasattr(c, 'model_dump') else c
+                    for c in (event.input.contents if event.input else [])
+                ],
+                'attachments': [
+                    a.model_dump(mode='json') if hasattr(a, 'model_dump') else a
+                    for a in (event.input.attachments if event.input else [])
+                ],
+            },
+        }
+
+    async def _invoke_runner(
+        self,
+        descriptor: AgentRunnerDescriptor,
+        context: AgentRunContextPayload,
+    ) -> typing.AsyncGenerator[dict[str, typing.Any], None]:
+        """Compatibility delegate for older tests and internal callers."""
+        async for result in self.invoker.invoke(descriptor, context):
+            yield result
+
+    async def _next_with_deadline(
+        self,
+        gen: typing.AsyncGenerator[dict[str, typing.Any], None],
+        descriptor: AgentRunnerDescriptor,
+        context: AgentRunContextPayload,
+    ) -> dict[str, typing.Any]:
+        return await self.invoker._next_with_deadline(gen, descriptor, context)
+
+    def _remaining_deadline_seconds(
+        self,
+        context: AgentRunContextPayload,
+    ) -> float | None:
+        return self.invoker._remaining_deadline_seconds(context)
+
+    def _is_deadline_exhausted(self, context: AgentRunContextPayload) -> bool:
+        return self.invoker._is_deadline_exhausted(context)
+
+    async def _close_generator(
+        self,
+        gen: typing.AsyncGenerator[dict[str, typing.Any], None],
+        descriptor: AgentRunnerDescriptor,
+    ) -> None:
+        await self.invoker._close_generator(gen, descriptor)
+
+    async def _handle_state_updated_event(
+        self,
+        result_dict: dict[str, typing.Any],
+        event: AgentEventEnvelope,
+        binding: AgentBinding,
+        descriptor: AgentRunnerDescriptor,
+    ) -> None:
+        await self.journal.handle_state_updated_event(result_dict, event, binding, descriptor)
+
+    async def _write_event_log(
+        self,
+        event: AgentEventEnvelope,
+        binding: AgentBinding,
+        run_id: str,
+        runner_id: str,
+    ) -> str:
+        return await self.journal.write_event_log(event, binding, run_id, runner_id)
+
+    async def _write_user_transcript(
+        self,
+        event: AgentEventEnvelope,
+        event_log_id: str,
+    ) -> None:
+        await self.journal.write_user_transcript(event, event_log_id)
+
+    async def _write_assistant_transcript(
+        self,
+        result_dict: dict[str, typing.Any],
+        event: AgentEventEnvelope,
+        run_id: str,
+        runner_id: str,
+    ) -> None:
+        await self.journal.write_assistant_transcript(
+            result_dict=result_dict,
+            event=event,
+            run_id=run_id,
+            runner_id=runner_id,
+        )

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

@@ -0,0 +1,435 @@
+"""Persistent state store for AgentRunner protocol state.
+
+This module provides a database-backed state store for event-first Protocol v1.
+"""
+from __future__ import annotations
+
+import typing
+import json
+import threading
+from datetime import datetime
+
+import sqlalchemy
+from sqlalchemy.ext.asyncio import AsyncEngine
+from sqlalchemy import select, delete, update
+from sqlalchemy.dialects.postgresql import insert as postgresql_insert
+from sqlalchemy.dialects.sqlite import insert as sqlite_insert
+from sqlalchemy.exc import IntegrityError
+
+from .descriptor import AgentRunnerDescriptor
+from .host_models import AgentEventEnvelope, AgentBinding
+from .state_scope import (
+    VALID_STATE_SCOPES,
+    build_state_scope_key,
+    get_binding_identity,
+    normalize_state_key,
+)
+from ...entity.persistence.agent_runner_state import AgentRunnerState
+
+
+# Maximum value_json size (256KB)
+MAX_VALUE_JSON_BYTES = 256 * 1024
+
+
+class PersistentStateStore:
+    """Database-backed state store for AgentRunner protocol state.
+
+    IMPORTANT: This is HOST-OWNED protocol state, NOT plugin instance state.
+
+    This store provides:
+    1. Persistent storage across runs via database
+    2. Scope isolation by runner_id + binding_identity + scope
+    3. Policy enforcement (enable_state, state_scopes)
+    4. JSON value validation and size limits
+
+    Used by:
+    - Event-first Protocol v1 (async methods)
+    - State API handlers (get/set/delete/list)
+    """
+
+    def __init__(self, db_engine: AsyncEngine):
+        self._db_engine = db_engine
+
+    def _get_scope_key(
+        self,
+        scope: str,
+        event: AgentEventEnvelope,
+        binding: AgentBinding,
+        descriptor: AgentRunnerDescriptor,
+    ) -> str | None:
+        """Get scope key for given scope."""
+        return build_state_scope_key(scope, event, binding, descriptor)
+
+    def _check_scope_enabled(self, scope: str, binding: AgentBinding) -> bool:
+        """Check if scope is enabled by binding's state_policy."""
+        state_policy = binding.state_policy
+        if not state_policy.enable_state:
+            return False
+        return scope in state_policy.state_scopes
+
+    def _validate_json_value(
+        self,
+        value: typing.Any,
+        logger: typing.Any = None,
+    ) -> tuple[str | None, str | None]:
+        """Validate and serialize value to JSON.
+
+        Returns:
+            Tuple of (json_string, error_message). If error_message is not None,
+            json_string will be None.
+        """
+        try:
+            json_str = json.dumps(value, ensure_ascii=False)
+        except (TypeError, ValueError) as e:
+            return None, f'Value is not JSON-serializable: {e}'
+
+        # Check size limit
+        json_bytes = len(json_str.encode('utf-8'))
+        if json_bytes > MAX_VALUE_JSON_BYTES:
+            return None, f'Value size {json_bytes} bytes exceeds limit {MAX_VALUE_JSON_BYTES} bytes'
+
+        return json_str, None
+
+    async def _upsert_state_row(
+        self,
+        conn: typing.Any,
+        values: dict[str, typing.Any],
+    ) -> None:
+        """Insert or update a state row by the logical scope/key identity."""
+        update_values = {
+            'value_json': values['value_json'],
+            'updated_at': values['updated_at'],
+        }
+        constraint_columns = ['scope_key', 'state_key']
+        dialect_name = self._db_engine.dialect.name
+
+        if dialect_name == 'sqlite':
+            stmt = sqlite_insert(AgentRunnerState).values(**values)
+            await conn.execute(
+                stmt.on_conflict_do_update(
+                    index_elements=constraint_columns,
+                    set_=update_values,
+                )
+            )
+            return
+
+        if dialect_name == 'postgresql':
+            stmt = postgresql_insert(AgentRunnerState).values(**values)
+            await conn.execute(
+                stmt.on_conflict_do_update(
+                    index_elements=constraint_columns,
+                    set_=update_values,
+                )
+            )
+            return
+
+        try:
+            await conn.execute(sqlalchemy.insert(AgentRunnerState).values(**values))
+        except IntegrityError:
+            await conn.execute(
+                update(AgentRunnerState)
+                .where(AgentRunnerState.scope_key == values['scope_key'])
+                .where(AgentRunnerState.state_key == values['state_key'])
+                .values(**update_values)
+            )
+
+    # ========== Async DB Operations ==========
+
+    async def build_snapshot_from_event(
+        self,
+        event: AgentEventEnvelope,
+        binding: AgentBinding,
+        descriptor: AgentRunnerDescriptor,
+    ) -> dict[str, dict[str, typing.Any]]:
+        """Build state snapshot for all scopes from event and binding.
+
+        Reads from database, respects state_policy.
+        """
+        state_policy = binding.state_policy
+
+        # If state is disabled, return all empty scopes
+        if not state_policy.enable_state:
+            return {
+                'conversation': {},
+                'actor': {},
+                'subject': {},
+                'runner': {},
+            }
+
+        snapshot: dict[str, dict[str, typing.Any]] = {
+            'conversation': {},
+            'actor': {},
+            'subject': {},
+            'runner': {},
+        }
+
+        async with self._db_engine.connect() as conn:
+            for scope in VALID_STATE_SCOPES:
+                if not self._check_scope_enabled(scope, binding):
+                    continue
+
+                scope_key = self._get_scope_key(scope, event, binding, descriptor)
+                if not scope_key:
+                    continue
+
+                # Query all state entries for this scope_key
+                result = await conn.execute(
+                    select(AgentRunnerState.state_key, AgentRunnerState.value_json)
+                    .where(AgentRunnerState.scope_key == scope_key)
+                )
+                rows = result.fetchall()
+
+                for row in rows:
+                    key = row.state_key
+                    value_json = row.value_json
+                    if value_json:
+                        try:
+                            snapshot[scope][key] = json.loads(value_json)
+                        except json.JSONDecodeError:
+                            pass  # Skip invalid JSON
+
+        # Seed external.conversation_id from event.conversation_id if not set
+        if self._check_scope_enabled('conversation', binding) and event.conversation_id:
+            if 'external.conversation_id' not in snapshot['conversation']:
+                snapshot['conversation']['external.conversation_id'] = event.conversation_id
+
+        return snapshot
+
+    async def apply_update_from_event(
+        self,
+        event: AgentEventEnvelope,
+        binding: AgentBinding,
+        descriptor: AgentRunnerDescriptor,
+        scope: str,
+        key: str,
+        value: typing.Any,
+        logger: typing.Any = None,
+    ) -> tuple[bool, str | None]:
+        """Apply a state update from event context.
+
+        Returns:
+            Tuple of (success, error_message). If success is False, error_message
+            contains the reason.
+        """
+        state_policy = binding.state_policy
+
+        # Check if state is disabled
+        if not state_policy.enable_state:
+            return False, 'State is disabled by binding policy'
+
+        # Validate scope
+        if scope not in VALID_STATE_SCOPES:
+            return False, f'Invalid scope: {scope}'
+
+        # Check if scope is enabled
+        if not self._check_scope_enabled(scope, binding):
+            return False, f'Scope "{scope}" not enabled by binding policy'
+
+        # Map accepted key aliases
+        key = normalize_state_key(key)
+
+        # Get scope key
+        scope_key = self._get_scope_key(scope, event, binding, descriptor)
+        if not scope_key:
+            return False, f'Missing identity for scope "{scope}"'
+
+        # Validate and serialize value
+        value_json, error = self._validate_json_value(value, logger)
+        if error:
+            return False, error
+
+        # Build context fields
+        binding_identity = get_binding_identity(binding)
+
+        now = datetime.utcnow()
+        async with self._db_engine.begin() as conn:
+            await self._upsert_state_row(
+                conn,
+                {
+                    'runner_id': descriptor.id,
+                    'binding_identity': binding_identity,
+                    'scope': scope,
+                    'scope_key': scope_key,
+                    'state_key': key,
+                    'value_json': value_json,
+                    'bot_id': event.bot_id,
+                    'workspace_id': event.workspace_id,
+                    'conversation_id': event.conversation_id,
+                    'thread_id': event.thread_id,
+                    'actor_type': event.actor.actor_type if event.actor else None,
+                    'actor_id': event.actor.actor_id if event.actor else None,
+                    'subject_type': event.subject.subject_type if event.subject else None,
+                    'subject_id': event.subject.subject_id if event.subject else None,
+                    'created_at': now,
+                    'updated_at': now,
+                },
+            )
+
+        return True, None
+
+    async def state_get(
+        self,
+        scope_key: str,
+        state_key: str,
+    ) -> typing.Any:
+        """Get a single state value by scope_key and state_key.
+
+        Used by State API handlers.
+        """
+        state_key = normalize_state_key(state_key)
+
+        async with self._db_engine.connect() as conn:
+            result = await conn.execute(
+                select(AgentRunnerState.value_json)
+                .where(AgentRunnerState.scope_key == scope_key)
+                .where(AgentRunnerState.state_key == state_key)
+            )
+            row = result.first()
+
+            if not row or not row.value_json:
+                return None
+
+            try:
+                return json.loads(row.value_json)
+            except json.JSONDecodeError:
+                return None
+
+    async def state_set(
+        self,
+        scope_key: str,
+        state_key: str,
+        value: typing.Any,
+        runner_id: str,
+        binding_identity: str,
+        scope: str,
+        context: dict[str, typing.Any] | None = None,
+        logger: typing.Any = None,
+    ) -> tuple[bool, str | None]:
+        """Set a state value.
+
+        Used by State API handlers.
+        Context contains optional fields like bot_id, conversation_id, etc.
+        """
+        state_key = normalize_state_key(state_key)
+
+        # Validate and serialize value
+        value_json, error = self._validate_json_value(value, logger)
+        if error:
+            return False, error
+
+        context = context or {}
+
+        now = datetime.utcnow()
+        async with self._db_engine.begin() as conn:
+            await self._upsert_state_row(
+                conn,
+                {
+                    'runner_id': runner_id,
+                    'binding_identity': binding_identity,
+                    'scope': scope,
+                    'scope_key': scope_key,
+                    'state_key': state_key,
+                    'value_json': value_json,
+                    'bot_id': context.get('bot_id'),
+                    'workspace_id': context.get('workspace_id'),
+                    'conversation_id': context.get('conversation_id'),
+                    'thread_id': context.get('thread_id'),
+                    'actor_type': context.get('actor_type'),
+                    'actor_id': context.get('actor_id'),
+                    'subject_type': context.get('subject_type'),
+                    'subject_id': context.get('subject_id'),
+                    'created_at': now,
+                    'updated_at': now,
+                },
+            )
+
+        return True, None
+
+    async def state_delete(
+        self,
+        scope_key: str,
+        state_key: str,
+    ) -> bool:
+        """Delete a state value.
+
+        Returns True if deleted, False if not found.
+        """
+        state_key = normalize_state_key(state_key)
+
+        async with self._db_engine.begin() as conn:
+            result = await conn.execute(
+                delete(AgentRunnerState)
+                .where(AgentRunnerState.scope_key == scope_key)
+                .where(AgentRunnerState.state_key == state_key)
+            )
+            return (result.rowcount or 0) > 0
+
+    async def state_list(
+        self,
+        scope_key: str,
+        prefix: str | None = None,
+        limit: int = 100,
+    ) -> tuple[list[str], bool]:
+        """List state keys in a scope.
+
+        Returns tuple of (keys, has_more).
+        """
+        # Enforce limit cap
+        limit = min(limit, 100)
+
+        async with self._db_engine.connect() as conn:
+            query = (
+                select(AgentRunnerState.state_key)
+                .where(AgentRunnerState.scope_key == scope_key)
+                .order_by(AgentRunnerState.state_key)
+                .limit(limit + 1)  # Fetch one extra to check has_more
+            )
+
+            if prefix:
+                prefix = normalize_state_key(prefix)
+                query = query.where(
+                    AgentRunnerState.state_key.like(f'{prefix}%')
+                )
+
+            result = await conn.execute(query)
+            rows = result.fetchall()
+
+            keys = [row.state_key for row in rows[:limit]]
+            has_more = len(rows) > limit
+
+            return keys, has_more
+
+    async def clear_all(self) -> None:
+        """Clear all state entries (for testing)."""
+        async with self._db_engine.begin() as conn:
+            await conn.execute(delete(AgentRunnerState))
+
+
+# Global singleton persistent state store
+_persistent_state_store: PersistentStateStore | None = None
+_persistent_state_store_lock = threading.Lock()
+
+
+def get_persistent_state_store(db_engine: AsyncEngine | None = None) -> PersistentStateStore:
+    """Get the global persistent state store singleton.
+
+    Args:
+        db_engine: Database engine (required on first call)
+
+    Returns:
+        PersistentStateStore singleton
+    """
+    global _persistent_state_store
+    with _persistent_state_store_lock:
+        if _persistent_state_store is None:
+            if db_engine is None:
+                raise RuntimeError("db_engine required for first call to get_persistent_state_store")
+            _persistent_state_store = PersistentStateStore(db_engine)
+        return _persistent_state_store
+
+
+def reset_persistent_state_store() -> None:
+    """Reset the global persistent state store (for testing)."""
+    global _persistent_state_store
+    with _persistent_state_store_lock:
+        _persistent_state_store = None

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

@@ -0,0 +1,56 @@
+"""Pipeline Query bridge for AgentRunner execution."""
+
+from __future__ import annotations
+
+import dataclasses
+import typing
+
+from langbot_plugin.api.entities.builtin.pipeline import query as pipeline_query
+
+from .binding_resolver import AgentBindingResolver
+from .config_migration import ConfigMigration
+from .errors import RunnerNotFoundError
+from .host_models import AgentBinding, AgentEventEnvelope
+from .query_entry_adapter import QueryEntryAdapter
+
+
+@dataclasses.dataclass(frozen=True)
+class QueryRunPlan:
+    """Projected event-first execution request for a Query-backed run."""
+
+    event: AgentEventEnvelope
+    binding: AgentBinding
+    bound_plugins: list[str] | None
+    adapter_context: dict[str, typing.Any]
+
+
+class QueryRunBridge:
+    """Project the current Pipeline Query entry point into Protocol v1 inputs."""
+
+    binding_resolver: AgentBindingResolver
+
+    def __init__(self, binding_resolver: AgentBindingResolver):
+        self.binding_resolver = binding_resolver
+
+    def build_plan(self, query: pipeline_query.Query) -> QueryRunPlan:
+        """Build an event-first run plan from a Pipeline Query."""
+        runner_id = ConfigMigration.resolve_runner_id(query.pipeline_config)
+        if not runner_id:
+            raise RunnerNotFoundError('no runner configured')
+
+        event = QueryEntryAdapter.query_to_event(query)
+        agent_config = QueryEntryAdapter.config_to_agent_config(query, runner_id)
+        binding = self.binding_resolver.resolve_one(event, [agent_config])
+        bound_plugins = query.variables.get('_pipeline_bound_plugins')
+        adapter_context = QueryEntryAdapter.build_adapter_context(query, binding)
+
+        return QueryRunPlan(
+            event=event,
+            binding=binding,
+            bound_plugins=bound_plugins,
+            adapter_context=adapter_context,
+        )
+
+    def resolve_runner_id_for_telemetry(self, query: pipeline_query.Query) -> str | None:
+        """Resolve runner ID for telemetry/logging without full execution."""
+        return ConfigMigration.resolve_runner_id(query.pipeline_config)

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

@@ -0,0 +1,649 @@
+"""Query entry adapter for converting Query to event-first envelope.
+
+This adapter bridges the current Query entry point with the event-first
+Protocol v1 architecture without exposing Query internals to runners.
+"""
+from __future__ import annotations
+
+import hashlib
+import typing
+
+from langbot_plugin.api.entities.builtin.pipeline import query as pipeline_query
+from langbot_plugin.api.entities.builtin.platform import message as platform_message
+from langbot_plugin.api.entities.builtin.agent_runner.event import (
+    AgentEventContext,
+    ConversationContext,
+    ActorContext,
+    SubjectContext,
+    RawEventRef,
+)
+from langbot_plugin.api.entities.builtin.agent_runner.input import AgentInput
+from langbot_plugin.api.entities.builtin.agent_runner.delivery import DeliveryContext
+
+from .host_models import (
+    AgentConfig,
+    AgentEventEnvelope,
+    ResourcePolicy,
+    StatePolicy,
+    DeliveryPolicy,
+)
+from .config_migration import ConfigMigration
+from . import events as runner_events
+
+
+class QueryEntryAdapter:
+    """Adapter for converting Query to event-first envelope.
+
+    This adapter is responsible for:
+    - Converting Query to AgentEventEnvelope
+    - Projecting current Pipeline config to temporary AgentConfig
+    - Putting Query-only fields into adapter context
+    """
+
+    INTERNAL_PREFIX = '_'
+    SENSITIVE_PATTERNS = ('secret', 'token', 'key', 'password', 'credential', 'api_key', 'apikey')
+    PERMISSION_VARS = ('_pipeline_bound_plugins', '_authorized', '_permission')
+    EVENT_DATA_MAX_STRING_BYTES = 512
+
+    @classmethod
+    def query_to_event(
+        cls,
+        query: pipeline_query.Query,
+    ) -> AgentEventEnvelope:
+        """Convert Query to AgentEventEnvelope.
+
+        Args:
+            query: Current entry query
+
+        Returns:
+            AgentEventEnvelope for event-first processing
+        """
+        # Build event context
+        event = cls._build_event_context(query)
+
+        # Build conversation context
+        conversation = cls._build_conversation_context(query)
+
+        # Build actor context
+        actor = cls._build_actor_context(query)
+
+        # Build subject context
+        subject = cls._build_subject_context(query)
+
+        # Build input
+        input = cls._build_input(query)
+
+        # Build delivery context
+        delivery = cls._build_delivery_context(query)
+
+        # Build raw ref
+        raw_ref = cls._build_raw_ref(query)
+
+        return AgentEventEnvelope(
+            event_id=event.event_id or str(query.query_id),
+            event_type=event.event_type or runner_events.MESSAGE_RECEIVED,
+            event_time=event.event_time,
+            source="host_adapter",
+            source_event_type=event.source_event_type,
+            bot_id=query.bot_uuid,
+            workspace_id=None,  # Not available in Query
+            conversation_id=conversation.conversation_id,
+            thread_id=conversation.thread_id,
+            actor=actor,
+            subject=subject,
+            input=input,
+            delivery=delivery,
+            raw_ref=raw_ref,
+            data=event.data,
+        )
+
+    @classmethod
+    def config_to_agent_config(
+        cls,
+        query: pipeline_query.Query,
+        runner_id: str,
+    ) -> AgentConfig:
+        """Project the current Pipeline config container into target Agent config."""
+        pipeline_config = query.pipeline_config or {}
+        runner_config = ConfigMigration.resolve_runner_config(pipeline_config, runner_id)
+        agent_id = getattr(query, 'pipeline_uuid', None)
+
+        # Build resource policy from current config
+        resource_policy = ResourcePolicy(
+            allowed_model_uuids=cls._extract_allowed_models(query),
+            allowed_tool_names=cls._extract_allowed_tools(query),
+            allowed_kb_uuids=cls._extract_allowed_kbs(query),
+            allowed_skill_names=cls._extract_allowed_skills(query),
+        )
+
+        # Build state policy
+        state_policy = StatePolicy(
+            enable_state=True,
+            state_scopes=["conversation", "actor", "subject", "runner"],
+        )
+
+        # Build delivery policy
+        delivery_policy = DeliveryPolicy(
+            enable_streaming=True,
+            enable_reply=True,
+        )
+
+        return AgentConfig(
+            agent_id=agent_id,
+            runner_id=runner_id,
+            runner_config=runner_config,
+            resource_policy=resource_policy,
+            state_policy=state_policy,
+            delivery_policy=delivery_policy,
+            event_types=[runner_events.MESSAGE_RECEIVED],
+            enabled=True,
+            metadata={'source': 'pipeline_adapter'},
+        )
+
+    @classmethod
+    def build_adapter_context(
+        cls,
+        query: pipeline_query.Query,
+        binding: AgentBinding,
+    ) -> dict[str, typing.Any]:
+        """Build Query-derived fields for the current entry adapter."""
+        return {
+            'params': cls.build_params(query),
+            'query_id': getattr(query, 'query_id', None),
+        }
+
+    @classmethod
+    def build_params(cls, query: pipeline_query.Query) -> dict[str, typing.Any]:
+        """Build adapter params from Pipeline variables with host filtering."""
+        params: dict[str, typing.Any] = {}
+        variables = getattr(query, 'variables', None)
+        if not variables:
+            return params
+
+        for key, value in variables.items():
+            if key.startswith(cls.INTERNAL_PREFIX):
+                continue
+            key_lower = key.lower()
+            if any(pattern in key_lower for pattern in cls.SENSITIVE_PATTERNS):
+                continue
+            if any(key == perm_var or key.startswith(perm_var) for perm_var in cls.PERMISSION_VARS):
+                continue
+            if cls.is_json_serializable(value):
+                params[key] = value
+
+        return params
+
+    @classmethod
+    def is_json_serializable(cls, value: typing.Any) -> bool:
+        """Return whether a value can safely cross the adapter boundary as JSON."""
+        if value is None or isinstance(value, (str, int, float, bool)):
+            return True
+        if isinstance(value, (list, tuple)):
+            return all(cls.is_json_serializable(item) for item in value)
+        if isinstance(value, dict):
+            return all(
+                isinstance(k, str) and cls.is_json_serializable(v)
+                for k, v in value.items()
+            )
+        return False
+
+    # Private helper methods
+
+    @classmethod
+    def _build_event_context(
+        cls,
+        query: pipeline_query.Query,
+    ) -> AgentEventContext:
+        """Build AgentEventContext from Query."""
+        message_event = getattr(query, 'message_event', None)
+
+        event_data: dict[str, typing.Any] = {}
+        if message_event and hasattr(message_event, 'model_dump'):
+            try:
+                raw_event_data = message_event.model_dump(mode='json')
+            except TypeError:
+                raw_event_data = message_event.model_dump()
+            except Exception:
+                raw_event_data = {}
+            if isinstance(raw_event_data, dict):
+                event_data = cls._compact_event_data(raw_event_data)
+
+        source_event_type = None
+        if message_event:
+            source_event_type = getattr(message_event, 'type', None)
+
+        message_chain = getattr(query, 'message_chain', None)
+        message_id = getattr(message_chain, 'message_id', None)
+        if message_id == -1:
+            message_id = None
+
+        event_time = None
+        if message_event:
+            event_time = getattr(message_event, 'time', None)
+        if isinstance(event_time, (int, float)):
+            event_time = int(event_time)
+
+        source_event_id = str(message_id or query.query_id)
+        return AgentEventContext(
+            event_id=cls._build_scoped_event_id(query, source_event_id, event_time),
+            event_type=runner_events.MESSAGE_RECEIVED,
+            event_time=event_time,
+            source="host_adapter",
+            source_event_type=source_event_type,
+            data=event_data,
+        )
+
+    @classmethod
+    def _compact_event_data(
+        cls,
+        event_data: dict[str, typing.Any],
+    ) -> dict[str, typing.Any]:
+        """Keep only small scalar source-event metadata in event.data."""
+        compact: dict[str, typing.Any] = {}
+        for key, value in event_data.items():
+            if key == 'source_platform_object' or key.startswith('_'):
+                continue
+            if value is None or isinstance(value, (bool, int, float)):
+                compact[key] = value
+                continue
+            if isinstance(value, str):
+                if len(value.encode('utf-8')) <= cls.EVENT_DATA_MAX_STRING_BYTES:
+                    compact[key] = value
+                continue
+        return compact
+
+    @classmethod
+    def _build_scoped_event_id(
+        cls,
+        query: pipeline_query.Query,
+        source_event_id: str,
+        event_time: int | None,
+    ) -> str:
+        """Build a globally unique host event id from pipeline-local ids."""
+        launcher_type = getattr(query, 'launcher_type', None)
+        launcher_type_value = getattr(launcher_type, 'value', launcher_type) if launcher_type is not None else None
+        scope_parts = [
+            'host_adapter',
+            getattr(query, 'pipeline_uuid', None),
+            getattr(query, 'bot_uuid', None),
+            launcher_type_value,
+            getattr(query, 'launcher_id', None),
+            getattr(query, 'sender_id', None),
+            source_event_id,
+            event_time,
+        ]
+        scoped = '|'.join('' if part is None else str(part) for part in scope_parts)
+        digest = hashlib.sha256(scoped.encode('utf-8')).hexdigest()[:32]
+        return f'host:{digest}'
+
+    @classmethod
+    def _build_conversation_context(
+        cls,
+        query: pipeline_query.Query,
+    ) -> ConversationContext:
+        """Build ConversationContext from Query."""
+        # Handle launcher_type safely
+        launcher_type = getattr(query, 'launcher_type', None)
+        launcher_type_value = None
+        if launcher_type is not None:
+            launcher_type_value = getattr(launcher_type, 'value', launcher_type)
+
+        # Handle launcher_id
+        launcher_id = getattr(query, 'launcher_id', None)
+
+        # Build session_id from launcher info if available
+        session_id = None
+        if launcher_type_value and launcher_id:
+            session_id = f'{launcher_type_value}_{launcher_id}'
+
+        # Handle session and conversation_id
+        conversation_id = None
+        session = getattr(query, 'session', None)
+        if session:
+            conversation = getattr(session, 'using_conversation', None)
+            if conversation:
+                conversation_id = getattr(conversation, 'uuid', None)
+
+        if not conversation_id:
+            variables = getattr(query, 'variables', None) or {}
+            conversation_id = variables.get('conversation_id') or None
+
+        if not conversation_id:
+            conversation_id = session_id
+
+        # Handle sender_id
+        sender_id = getattr(query, 'sender_id', None)
+        if sender_id is not None:
+            sender_id = str(sender_id)
+
+        # Handle bot_uuid
+        bot_uuid = getattr(query, 'bot_uuid', None)
+
+        return ConversationContext(
+            conversation_id=str(conversation_id) if conversation_id is not None else None,
+            thread_id=None,
+            launcher_type=launcher_type_value,
+            launcher_id=launcher_id,
+            sender_id=sender_id,
+            bot_id=bot_uuid,
+            workspace_id=None,
+            session_id=session_id,
+        )
+
+    @classmethod
+    def _build_actor_context(
+        cls,
+        query: pipeline_query.Query,
+    ) -> ActorContext:
+        """Build ActorContext from Query."""
+        message_event = getattr(query, 'message_event', None)
+        sender = getattr(message_event, 'sender', None) if message_event else None
+        sender_id = getattr(query, 'sender_id', None)
+        actor_id = getattr(sender, 'id', None) if sender else None
+        if actor_id is None:
+            actor_id = sender_id
+        actor_name = sender.get_name() if sender and hasattr(sender, 'get_name') else None
+
+        return ActorContext(
+            actor_type="user",
+            actor_id=str(actor_id) if actor_id is not None else None,
+            actor_name=actor_name,
+            metadata={},
+        )
+
+    @classmethod
+    def _build_subject_context(
+        cls,
+        query: pipeline_query.Query,
+    ) -> SubjectContext:
+        """Build SubjectContext from Query."""
+        message_chain = getattr(query, 'message_chain', None)
+        message_id = getattr(message_chain, 'message_id', None) if message_chain else None
+        if message_id == -1:
+            message_id = None
+
+        query_id = getattr(query, 'query_id', None)
+
+        # Safely get launcher_type
+        launcher_type = getattr(query, 'launcher_type', None)
+        launcher_type_value = None
+        if launcher_type is not None:
+            launcher_type_value = getattr(launcher_type, 'value', launcher_type)
+
+        return SubjectContext(
+            subject_type="message",
+            subject_id=str(message_id or query_id or ''),
+            data={
+                "launcher_type": launcher_type_value,
+                "launcher_id": getattr(query, 'launcher_id', None),
+                "sender_id": str(getattr(query, 'sender_id', '')) if getattr(query, 'sender_id', None) else None,
+                "bot_uuid": getattr(query, 'bot_uuid', None),
+            },
+        )
+
+    @classmethod
+    def _build_input(
+        cls,
+        query: pipeline_query.Query,
+    ) -> AgentInput:
+        """Build AgentInput from Query."""
+        text = None
+        text_parts: list[str] = []
+        contents: list[dict[str, typing.Any]] = []
+
+        user_message = getattr(query, 'user_message', None)
+        if user_message:
+            content = getattr(user_message, 'content', None)
+            if isinstance(content, list):
+                for elem in content:
+                    elem_dict = None
+                    if hasattr(elem, 'model_dump'):
+                        elem_dict = elem.model_dump(mode='json')
+                    elif isinstance(elem, dict):
+                        elem_dict = elem
+
+                    if not isinstance(elem_dict, dict):
+                        continue
+
+                    contents.append(elem_dict)
+                    if elem_dict.get('type') == 'text':
+                        elem_text = elem_dict.get('text')
+                        if elem_text:
+                            text_parts.append(elem_text)
+            elif content is not None:
+                text = str(content)
+                contents.append({'type': 'text', 'text': text})
+
+        if not contents:
+            message_chain = getattr(query, 'message_chain', None) or []
+            for component in message_chain:
+                if isinstance(component, platform_message.Plain):
+                    component_text = getattr(component, 'text', '')
+                    if component_text:
+                        text_parts.append(component_text)
+                        contents.append({'type': 'text', 'text': component_text})
+                elif isinstance(component, platform_message.Image):
+                    image_base64 = getattr(component, 'base64', None)
+                    image_url = getattr(component, 'url', None)
+                    if image_base64:
+                        contents.append({'type': 'image_base64', 'image_base64': image_base64})
+                    elif image_url:
+                        contents.append({'type': 'image_url', 'image_url': {'url': image_url}})
+
+        if text_parts:
+            text = ''.join(text_parts)
+
+        attachments = cls._build_attachments(query, contents)
+
+        return AgentInput(
+            text=text,
+            contents=contents,
+            attachments=attachments,
+        )
+
+    @classmethod
+    def _build_attachments(
+        cls,
+        query: pipeline_query.Query,
+        contents: list[dict[str, typing.Any]],
+    ) -> list[dict[str, typing.Any]]:
+        """Extract attachments from query."""
+        attachments: list[dict[str, typing.Any]] = []
+        seen_keys: dict[tuple[str, str, str], set[str]] = {}
+
+        def add_attachment(attachment: dict[str, typing.Any]) -> None:
+            key = cls._attachment_dedupe_key(attachment)
+            if key is not None:
+                source = str(attachment.get('source') or '')
+                sources = seen_keys.setdefault(key, set())
+                if source and sources and source not in sources:
+                    return
+                if source:
+                    sources.add(source)
+            attachments.append(attachment)
+
+        for elem in contents:
+            elem_type = elem.get('type')
+
+            if elem_type == 'image_url':
+                image_url = elem.get('image_url') or {}
+                add_attachment({
+                    'type': 'image',
+                    'source': 'url',
+                    'url': image_url.get('url') if isinstance(image_url, dict) else str(image_url),
+                })
+            elif elem_type == 'image_base64':
+                add_attachment({
+                    'type': 'image',
+                    'source': 'base64',
+                    'content': elem.get('image_base64'),
+                })
+            elif elem_type == 'file_url':
+                add_attachment({
+                    'type': 'file',
+                    'source': 'url',
+                    'url': elem.get('file_url'),
+                    'name': elem.get('file_name'),
+                })
+            elif elem_type == 'file_base64':
+                add_attachment({
+                    'type': 'file',
+                    'source': 'base64',
+                    'content': elem.get('file_base64'),
+                    'name': elem.get('file_name'),
+                })
+
+        message_chain = getattr(query, 'message_chain', None)
+        if message_chain:
+            try:
+                message_components = iter(message_chain)
+            except TypeError:
+                message_components = iter(())
+
+            for component in message_components:
+                if isinstance(component, platform_message.Image):
+                    image_id = component.image_id or None
+                    image_url = component.url or None
+                    image_base64 = component.base64 or None
+                    add_attachment({
+                        'type': 'image',
+                        'source': 'message_chain',
+                        'id': image_id,
+                        'url': image_url,
+                        'content': image_base64,
+                    })
+                elif isinstance(component, platform_message.File):
+                    add_attachment({
+                        'type': 'file',
+                        'source': 'message_chain',
+                        'id': component.id or None,
+                        'name': component.name or None,
+                        'url': component.url or None,
+                        'content': component.base64 or None,
+                    })
+                elif isinstance(component, platform_message.Voice):
+                    add_attachment({
+                        'type': 'voice',
+                        'source': 'message_chain',
+                        'id': component.voice_id or None,
+                        'url': component.url or None,
+                        'content': component.base64 or None,
+                    })
+
+        return attachments
+
+    @classmethod
+    def _attachment_dedupe_key(
+        cls,
+        attachment: dict[str, typing.Any],
+    ) -> tuple[str, str, str] | None:
+        """Return a stable key for the same attachment across content sources."""
+        attachment_type = attachment.get('type')
+        if not attachment_type:
+            return None
+        for field in ('id', 'url', 'content'):
+            value = attachment.get(field)
+            if value:
+                if field == 'content':
+                    value = hashlib.sha256(str(value).encode('utf-8')).hexdigest()
+                return str(attachment_type), field, str(value)
+        return None
+
+    @classmethod
+    def _build_delivery_context(
+        cls,
+        query: pipeline_query.Query,
+    ) -> DeliveryContext:
+        """Build DeliveryContext from Query."""
+        message_chain = getattr(query, 'message_chain', None)
+        return DeliveryContext(
+            surface="platform",
+            reply_target={
+                "message_id": getattr(message_chain, 'message_id', None),
+            },
+            supports_streaming=True,
+            supports_edit=False,
+            supports_reaction=False,
+            platform_capabilities={},
+        )
+
+    @classmethod
+    def _build_raw_ref(
+        cls,
+        query: pipeline_query.Query,
+    ) -> RawEventRef | None:
+        """Build RawEventRef from Query."""
+        # For now, we don't store raw event payload
+        return None
+
+    @classmethod
+    def _extract_allowed_models(
+        cls,
+        query: pipeline_query.Query,
+    ) -> list[str] | None:
+        """Extract allowed model UUIDs from query."""
+        model_uuids: list[str] = []
+        model_uuid = getattr(query, 'use_llm_model_uuid', None)
+        if model_uuid:
+            model_uuids.append(model_uuid)
+
+        variables = getattr(query, 'variables', None) or {}
+        for fallback_uuid in variables.get('_fallback_model_uuids', []) or []:
+            if fallback_uuid and fallback_uuid not in model_uuids:
+                model_uuids.append(fallback_uuid)
+
+        return model_uuids or None
+
+    @classmethod
+    def _extract_allowed_tools(
+        cls,
+        query: pipeline_query.Query,
+    ) -> list[str] | None:
+        """Extract allowed tool names from query."""
+        use_funcs = getattr(query, 'use_funcs', None)
+        if not use_funcs:
+            return None
+        try:
+            tool_names = []
+            for func in use_funcs:
+                if isinstance(func, dict):
+                    name = func.get('name')
+                elif hasattr(func, 'name'):
+                    name = func.name
+                else:
+                    continue
+                if name:
+                    tool_names.append(name)
+            return tool_names if tool_names else None
+        except (TypeError, AttributeError):
+            return None
+
+    @classmethod
+    def _extract_allowed_kbs(
+        cls,
+        query: pipeline_query.Query,
+    ) -> list[str] | None:
+        """Extract allowed knowledge base UUIDs from query."""
+        variables = getattr(query, 'variables', None)
+        if not variables:
+            return None
+        kb_uuids = variables.get('_knowledge_base_uuids')
+        if kb_uuids:
+            return kb_uuids
+        return None
+
+    @classmethod
+    def _extract_allowed_skills(
+        cls,
+        query: pipeline_query.Query,
+    ) -> list[str] | None:
+        """Extract pipeline-visible skill names from query."""
+        variables = getattr(query, 'variables', None)
+        if not variables or '_pipeline_bound_skills' not in variables:
+            return None
+        bound_skills = variables.get('_pipeline_bound_skills')
+        if bound_skills is None:
+            return None
+        if not isinstance(bound_skills, list):
+            return []
+        return [str(skill_name) for skill_name in bound_skills if skill_name]

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

@@ -0,0 +1,273 @@
+"""Agent runner registry for discovering and caching runner descriptors."""
+
+from __future__ import annotations
+
+import typing
+import asyncio
+
+from langbot_plugin.api.entities.builtin.agent_runner.manifest import (
+    AgentRunnerManifest,
+)
+
+from ...core import app
+from .descriptor import AgentRunnerDescriptor
+from .id import parse_runner_id, format_runner_id
+from .errors import RunnerNotFoundError, RunnerNotAuthorizedError
+
+
+class AgentRunnerRegistry:
+    """Registry for discovering and managing agent runners.
+
+    Responsibilities:
+    - Discover runners from plugin runtime via LIST_AGENT_RUNNERS
+    - Validate runner manifests (kind, metadata, spec)
+    - Cache discovered runners for performance
+    - Filter runners by bound plugins
+    - Handle manifest errors gracefully (log warning, skip runner)
+    """
+
+    ap: app.Application
+
+    _cache: dict[str, AgentRunnerDescriptor] | None
+    """Cached runner descriptors keyed by runner ID"""
+
+    _cache_lock: asyncio.Lock
+    """Lock for cache refresh operations"""
+
+    def __init__(self, ap: app.Application):
+        self.ap = ap
+        self._cache = None
+        self._cache_lock = asyncio.Lock()
+
+    async def _discover_runners(self) -> dict[str, AgentRunnerDescriptor]:
+        """Discover runners from plugin runtime.
+
+        Always discovers ALL runners (no bound_plugins filter).
+        The cache should contain unfiltered discovery results.
+
+        Returns:
+            Dict of runner descriptors keyed by runner ID
+        """
+        if not self.ap.plugin_connector.is_enable_plugin:
+            return {}
+
+        runners: dict[str, AgentRunnerDescriptor] = {}
+
+        try:
+            # Always list all runners (bound_plugins=None)
+            plugin_runners = await self.ap.plugin_connector.list_agent_runners(None)
+
+            for runner_data in plugin_runners:
+                try:
+                    descriptor = self._validate_and_build_descriptor(runner_data)
+                    if descriptor is not None:
+                        runners[descriptor.id] = descriptor
+                except Exception as e:
+                    plugin_author = runner_data.get('plugin_author', 'unknown')
+                    plugin_name = runner_data.get('plugin_name', 'unknown')
+                    runner_name = runner_data.get('runner_name', 'unknown')
+                    self.ap.logger.warning(
+                        f'Invalid runner manifest for plugin:{plugin_author}/{plugin_name}/{runner_name}: {e}'
+                    )
+                    continue
+
+        except Exception as e:
+            self.ap.logger.warning(f'Failed to list agent runners from plugin runtime: {e}')
+            return {}
+
+        return runners
+
+    def _validate_and_build_descriptor(self, runner_data: dict[str, typing.Any]) -> AgentRunnerDescriptor | None:
+        """Validate runner manifest and build descriptor.
+
+        Args:
+            runner_data: Raw runner data from plugin runtime with fields:
+                - plugin_author, plugin_name, runner_name
+                - manifest (typed AgentRunnerManifest)
+
+        Returns:
+            AgentRunnerDescriptor if valid, None if invalid
+        """
+        plugin_author = runner_data.get('plugin_author', '')
+        plugin_name = runner_data.get('plugin_name', '')
+        runner_name = runner_data.get('runner_name', '')
+
+        if not plugin_author or not plugin_name or not runner_name:
+            return None
+
+        manifest = runner_data.get('manifest', {})
+        runner_id = format_runner_id(
+            source='plugin',
+            plugin_author=plugin_author,
+            plugin_name=plugin_name,
+            runner_name=runner_name,
+        )
+
+        typed_manifest = AgentRunnerManifest.model_validate(manifest)
+        config_schema = [
+            item.model_dump(mode='json') for item in typed_manifest.config_schema
+        ]
+
+        return AgentRunnerDescriptor(
+            id=runner_id,
+            source='plugin',
+            label=typed_manifest.label,
+            description=typed_manifest.description,
+            plugin_author=plugin_author,
+            plugin_name=plugin_name,
+            runner_name=runner_name,
+            plugin_version=runner_data.get('plugin_version'),
+            config_schema=config_schema,
+            capabilities=typed_manifest.capabilities,
+            permissions=typed_manifest.permissions,
+            raw_manifest=manifest,
+        )
+
+    async def refresh(self) -> None:
+        """Refresh runner cache.
+
+        Always discovers ALL runners (no bound_plugins filter).
+        The cache contains unfiltered discovery results.
+        """
+        async with self._cache_lock:
+            self._cache = await self._discover_runners()
+
+    async def list_runners(
+        self,
+        bound_plugins: list[str] | None = None,
+        use_cache: bool = True,
+    ) -> list[AgentRunnerDescriptor]:
+        """List available runners.
+
+        Args:
+            bound_plugins: Optional filter for bound plugins (applied locally)
+            use_cache: Use cached data if available
+
+        Returns:
+            List of runner descriptors
+        """
+        if use_cache and self._cache is not None:
+            # Filter from cache
+            return self._filter_runners_by_bound_plugins(self._cache, bound_plugins)
+
+        # Discover fresh (always full list)
+        runners = await self._discover_runners()
+
+        # Update cache (full list, unfiltered)
+        async with self._cache_lock:
+            self._cache = runners
+
+        # Filter locally
+        return self._filter_runners_by_bound_plugins(runners, bound_plugins)
+
+    def _filter_runners_by_bound_plugins(
+        self,
+        runners: dict[str, AgentRunnerDescriptor],
+        bound_plugins: list[str] | None,
+    ) -> list[AgentRunnerDescriptor]:
+        """Filter runners by bound plugins.
+
+        Args:
+            runners: Dict of runner descriptors
+            bound_plugins: Optional filter (None means all plugins allowed)
+
+        Returns:
+            Filtered list of runner descriptors
+        """
+        if bound_plugins is None:
+            # All plugins allowed
+            return list(runners.values())
+
+        allowed_plugin_ids = set(bound_plugins)
+        filtered = []
+        for descriptor in runners.values():
+            plugin_id = descriptor.get_plugin_id()
+            if plugin_id in allowed_plugin_ids:
+                filtered.append(descriptor)
+
+        return filtered
+
+    async def get(
+        self,
+        runner_id: str,
+        bound_plugins: list[str] | None = None,
+    ) -> AgentRunnerDescriptor:
+        """Get a specific runner descriptor.
+
+        Args:
+            runner_id: Runner ID to lookup
+            bound_plugins: Optional bound plugins filter
+
+        Returns:
+            AgentRunnerDescriptor
+
+        Raises:
+            RunnerNotFoundError: If runner not found
+            RunnerNotAuthorizedError: If runner not in bound plugins
+        """
+        # Parse and validate runner ID format
+        try:
+            parse_runner_id(runner_id)
+        except ValueError as e:
+            raise RunnerNotFoundError(runner_id) from e
+
+        # Get from cache or discover (always full list)
+        if self._cache is None:
+            await self.refresh()
+
+        if self._cache is None:
+            raise RunnerNotFoundError(runner_id)
+
+        descriptor = self._cache.get(runner_id)
+        if descriptor is None:
+            raise RunnerNotFoundError(runner_id)
+
+        # Check authorization
+        if bound_plugins is not None:
+            plugin_id = descriptor.get_plugin_id()
+            if plugin_id not in bound_plugins:
+                raise RunnerNotAuthorizedError(runner_id, bound_plugins)
+
+        return descriptor
+
+    async def get_runner_metadata_for_pipeline(self) -> list[dict[str, typing.Any]]:
+        """Get runner metadata for pipeline configuration UI.
+
+        Returns runner options and their config schemas for the DynamicForm.
+        """
+        # Get all runners (no bound plugin filter for metadata listing)
+        runners = await self.list_runners(bound_plugins=None)
+
+        options = []
+        stages = []
+
+        for descriptor in runners:
+            config_schema = []
+            for index, config_item in enumerate(descriptor.config_schema):
+                item = dict(config_item)
+                if not item.get('id'):
+                    item_name = item.get('name') or str(index)
+                    item['id'] = f'{descriptor.id}.{item_name}'
+                config_schema.append(item)
+
+            # Add runner option
+            options.append(
+                {
+                    'name': descriptor.id,
+                    'label': descriptor.label,
+                    'description': descriptor.description,
+                }
+            )
+
+            # Add config schema as stage if not empty
+            if descriptor.config_schema:
+                stages.append(
+                    {
+                        'name': descriptor.id,
+                        'label': descriptor.label,
+                        'description': descriptor.description,
+                        'config': config_schema,
+                    }
+                )
+
+        return options, stages

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

@@ -0,0 +1,307 @@
+"""Agent resource builder for constructing authorized resources."""
+from __future__ import annotations
+
+import typing
+
+from ...core import app
+from .descriptor import AgentRunnerDescriptor
+from .context_builder import (
+    AgentResources,
+    ModelResource,
+    ToolResource,
+    KnowledgeBaseResource,
+    SkillResource,
+    StorageResource,
+)
+from . import config_schema
+from .host_models import AgentEventEnvelope, AgentBinding
+
+
+class AgentResourceBuilder:
+    """Builder for constructing run-scoped AgentResources with permission filtering.
+
+    Responsibilities:
+    - Apply manifest permissions intersected with binding resource policy
+    - Build models list from authorized models
+    - Build tools list from bound plugins/MCP servers
+    - Build knowledge_bases list from config
+    - Build storage access summary
+
+    Note: This only builds the resource declaration. The actual proxy actions
+    in handler.py must still validate against ctx.resources at runtime.
+
+    Resource field names match the plugin SDK payload:
+    - ModelResource: model_id, model_type, provider
+    - ToolResource: tool_name, tool_type, description
+    - KnowledgeBaseResource: kb_id, kb_name, kb_type
+    - SkillResource: skill_name, display_name, description
+    - StorageResource: plugin_storage, workspace_storage
+    """
+
+    ap: app.Application
+
+    def __init__(self, ap: app.Application):
+        self.ap = ap
+
+    async def build_resources_from_binding(
+        self,
+        event: AgentEventEnvelope,
+        binding: AgentBinding,
+        descriptor: AgentRunnerDescriptor,
+    ) -> AgentResources:
+        """Build AgentResources from event and binding.
+
+        This is the main entry point for Protocol v1.
+
+        Args:
+            event: Event envelope
+            binding: Agent binding with resource policy
+            descriptor: Runner descriptor with capabilities, permissions, and config schema
+
+        Returns:
+            AgentResources dict with filtered resource lists
+        """
+        resource_policy = binding.resource_policy
+        runner_config = binding.runner_config
+        manifest_perms = descriptor.permissions
+
+        # Build each resource category
+        models = await self._build_models_from_binding(
+            manifest_perms, resource_policy, descriptor, runner_config
+        )
+        tools = await self._build_tools_from_binding(
+            manifest_perms, resource_policy, descriptor
+        )
+        knowledge_bases = await self._build_knowledge_bases_from_binding(
+            manifest_perms, resource_policy, descriptor, runner_config
+        )
+        skills = self._build_skills_from_binding(
+            resource_policy, descriptor
+        )
+        storage = self._build_storage_from_binding(manifest_perms, binding)
+
+        return {
+            'models': models,
+            'tools': tools,
+            'knowledge_bases': knowledge_bases,
+            'skills': skills,
+            'storage': storage,
+            'platform_capabilities': {},  # Reserved for EBA
+        }
+
+    async def _build_models_from_binding(
+        self,
+        manifest_perms: typing.Any,
+        resource_policy: typing.Any,
+        descriptor: AgentRunnerDescriptor,
+        runner_config: dict[str, typing.Any],
+    ) -> list[ModelResource]:
+        """Build models list from binding."""
+        models: list[ModelResource] = []
+        seen_model_ids: set[str] = set()
+
+        model_perms = set(manifest_perms.models)
+        include_llm = bool({'invoke', 'stream'} & model_perms)
+        include_rerank = 'rerank' in model_perms
+        llm_operations = [operation for operation in ('invoke', 'stream') if operation in model_perms]
+        if not include_llm and not include_rerank:
+            return models
+
+        # Get additional model UUID grants from resource policy.
+        allowed_uuids = resource_policy.allowed_model_uuids
+
+        # Add model resources from Agent/runner config schema
+        await self._append_config_declared_model_resources(
+            models=models,
+            seen_model_ids=seen_model_ids,
+            descriptor=descriptor,
+            runner_config=runner_config,
+            include_llm=include_llm,
+            include_rerank=include_rerank,
+            llm_operations=llm_operations,
+        )
+
+        # Add explicitly allowed models
+        if allowed_uuids and include_llm:
+            for model_uuid in allowed_uuids:
+                await self._append_llm_model_resource(models, seen_model_ids, model_uuid, llm_operations)
+
+        return models
+
+    async def _build_tools_from_binding(
+        self,
+        manifest_perms: typing.Any,
+        resource_policy: typing.Any,
+        descriptor: AgentRunnerDescriptor,
+    ) -> list[ToolResource]:
+        """Build tools list from binding."""
+        tools: list[ToolResource] = []
+        tool_perms = set(manifest_perms.tools)
+        if not ({'detail', 'call'} & tool_perms):
+            return tools
+
+        if not config_schema.uses_host_tools(descriptor):
+            return tools
+
+        # Get tool names from resource policy
+        allowed_names = resource_policy.allowed_tool_names
+        tool_operations = [operation for operation in ('detail', 'call') if operation in tool_perms]
+
+        if allowed_names:
+            for tool_name in allowed_names:
+                tools.append({
+                    'tool_name': tool_name,
+                    'tool_type': None,
+                    'description': None,
+                    'operations': tool_operations,
+                })
+
+        return tools
+
+    async def _build_knowledge_bases_from_binding(
+        self,
+        manifest_perms: typing.Any,
+        resource_policy: typing.Any,
+        descriptor: AgentRunnerDescriptor,
+        runner_config: dict[str, typing.Any],
+    ) -> list[KnowledgeBaseResource]:
+        """Build knowledge bases list from binding."""
+        kb_resources: list[KnowledgeBaseResource] = []
+        kb_perms = set(manifest_perms.knowledge_bases)
+        if not ({'list', 'retrieve'} & kb_perms):
+            return kb_resources
+        kb_operations = [operation for operation in ('list', 'retrieve') if operation in kb_perms]
+
+        if not config_schema.uses_host_knowledge_bases(descriptor):
+            return kb_resources
+
+        # Get KB UUID grants from schema-defined config fields.
+        kb_uuids = config_schema.extract_knowledge_base_uuids(descriptor, runner_config)
+
+        # Also include resource policy grants.
+        allowed_uuids = resource_policy.allowed_kb_uuids
+        if allowed_uuids:
+            kb_uuids = list(dict.fromkeys([*kb_uuids, *allowed_uuids]))
+
+        for kb_uuid in kb_uuids:
+            try:
+                kb = await self.ap.rag_mgr.get_knowledge_base_by_uuid(kb_uuid)
+                if kb:
+                    kb_resources.append({
+                        'kb_id': kb_uuid,
+                        'kb_name': kb.get_name(),
+                        'kb_type': kb.knowledge_base_entity.kb_type if hasattr(kb.knowledge_base_entity, 'kb_type') else None,
+                        'operations': kb_operations,
+                    })
+            except Exception as e:
+                self.ap.logger.warning(f'Failed to build knowledge base resource {kb_uuid}: {e}')
+
+        return kb_resources
+
+    def _build_skills_from_binding(
+        self,
+        resource_policy: typing.Any,
+        descriptor: AgentRunnerDescriptor,
+    ) -> list[SkillResource]:
+        """Build pipeline-visible skill resource facts."""
+        if not config_schema.supports_skill_authoring(descriptor):
+            return []
+
+        skill_mgr = getattr(self.ap, 'skill_mgr', None)
+        if skill_mgr is None:
+            return []
+
+        loaded_skills = getattr(skill_mgr, 'skills', {}) or {}
+        allowed_names = resource_policy.allowed_skill_names
+        if allowed_names is None:
+            names = sorted(loaded_skills.keys())
+        else:
+            names = sorted(name for name in allowed_names if name in loaded_skills)
+
+        skills: list[SkillResource] = []
+        for skill_name in names:
+            skill_data = loaded_skills.get(skill_name) or {}
+            skills.append({
+                'skill_name': skill_name,
+                'display_name': skill_data.get('display_name') or skill_data.get('name') or skill_name,
+                'description': skill_data.get('description') or None,
+            })
+        return skills
+
+    def _build_storage_from_binding(
+        self,
+        manifest_perms: typing.Any,
+        binding: AgentBinding,
+    ) -> StorageResource:
+        """Build storage access summary from manifest and binding policy."""
+        resource_policy = binding.resource_policy
+        storage_perms = set(manifest_perms.storage)
+
+        return {
+            'plugin_storage': 'plugin' in storage_perms and resource_policy.allow_plugin_storage,
+            'workspace_storage': 'workspace' in storage_perms and resource_policy.allow_workspace_storage,
+        }
+
+    async def _append_config_declared_model_resources(
+        self,
+        models: list[ModelResource],
+        seen_model_ids: set[str],
+        descriptor: AgentRunnerDescriptor,
+        runner_config: dict[str, typing.Any],
+        include_llm: bool,
+        include_rerank: bool,
+        llm_operations: list[str],
+    ) -> None:
+        """Authorize model-like values selected through DynamicForm fields."""
+        for model_type, model_uuid in config_schema.iter_config_model_refs(descriptor, runner_config):
+            if model_type == 'llm' and include_llm:
+                await self._append_llm_model_resource(models, seen_model_ids, model_uuid, llm_operations)
+            elif model_type == 'rerank' and include_rerank:
+                await self._append_rerank_model_resource(models, seen_model_ids, model_uuid)
+
+    async def _append_llm_model_resource(
+        self,
+        models: list[ModelResource],
+        seen_model_ids: set[str],
+        model_uuid: str | None,
+        operations: list[str],
+    ) -> None:
+        """Append an LLM model resource if it exists and has not been added."""
+        if not model_uuid or model_uuid == '__none__' or model_uuid in seen_model_ids:
+            return
+
+        try:
+            model = await self.ap.model_mgr.get_model_by_uuid(model_uuid)
+            if model and model.model_entity:
+                models.append({
+                    'model_id': model_uuid,
+                    'model_type': getattr(model.model_entity, 'model_type', None),
+                    'provider': getattr(model.provider_entity, 'name', None) if hasattr(model, 'provider_entity') else None,
+                    'operations': operations,
+                })
+                seen_model_ids.add(model_uuid)
+        except Exception as e:
+            self.ap.logger.warning(f'Failed to build LLM model resource {model_uuid}: {e}')
+
+    async def _append_rerank_model_resource(
+        self,
+        models: list[ModelResource],
+        seen_model_ids: set[str],
+        model_uuid: str | None,
+    ) -> None:
+        """Append a rerank model resource if it exists and has not been added."""
+        if not model_uuid or model_uuid == '__none__' or model_uuid in seen_model_ids:
+            return
+
+        try:
+            model = await self.ap.model_mgr.get_rerank_model_by_uuid(model_uuid)
+            if model and model.model_entity:
+                models.append({
+                    'model_id': model_uuid,
+                    'model_type': getattr(model.model_entity, 'model_type', 'rerank') or 'rerank',
+                    'provider': getattr(model.provider_entity, 'name', None) if hasattr(model, 'provider_entity') else None,
+                    'operations': ['rerank'],
+                })
+                seen_model_ids.add(model_uuid)
+        except Exception as e:
+            self.ap.logger.warning(f'Failed to build rerank model resource {model_uuid}: {e}')

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

@@ -0,0 +1,234 @@
+"""Agent result normalizer for converting AgentRunResult to Pipeline messages."""
+from __future__ import annotations
+
+import typing
+
+import pydantic
+from langbot_plugin.api.entities.builtin.agent_runner.result import (
+    ActionRequestedPayload,
+    MessageCompletedPayload,
+    MessageDeltaPayload,
+    RunCompletedPayload,
+    RunFailedPayload,
+    StateUpdatedPayload,
+    ToolCallCompletedPayload,
+    ToolCallStartedPayload,
+)
+from langbot_plugin.api.entities.builtin.provider import message as provider_message
+
+from ...core import app
+from .descriptor import AgentRunnerDescriptor
+from .errors import RunnerExecutionError, RunnerProtocolError
+
+
+# Maximum size for a single result payload (prevent memory exhaustion)
+MAX_RESULT_SIZE_BYTES = 1024 * 1024  # 1 MB
+
+STRICT_RESULT_PAYLOADS: dict[str, type[pydantic.BaseModel]] = {
+    'message.delta': MessageDeltaPayload,
+    'message.completed': MessageCompletedPayload,
+    'tool.call.started': ToolCallStartedPayload,
+    'tool.call.completed': ToolCallCompletedPayload,
+    'state.updated': StateUpdatedPayload,
+    'action.requested': ActionRequestedPayload,
+    'run.completed': RunCompletedPayload,
+    'run.failed': RunFailedPayload,
+}
+
+
+class AgentResultNormalizer:
+    """Normalizer for converting AgentRunResult to Pipeline messages.
+
+    Responsibilities:
+    - Accept only supported result types (message.delta, message.completed, etc.)
+    - Map message.delta -> MessageChunk
+    - Map message.completed -> Message
+    - Map run.completed (with message) -> Message
+    - Handle run.failed as controlled error
+    - Ignore unknown types with warning
+    - Validate result size
+    - Validate message schema
+
+    Accepted result types:
+    - message.delta
+    - message.completed
+    - tool.call.started
+    - tool.call.completed
+    - state.updated
+    - run.completed
+    - run.failed
+    - action.requested (log only, don't execute)
+    """
+
+    ap: app.Application
+
+    def __init__(self, ap: app.Application):
+        self.ap = ap
+
+    async def normalize(
+        self,
+        result_dict: dict[str, typing.Any],
+        descriptor: AgentRunnerDescriptor,
+    ) -> provider_message.Message | provider_message.MessageChunk | None:
+        """Normalize AgentRunResult to Message or MessageChunk.
+
+        Args:
+            result_dict: Raw result dict from plugin runtime
+            descriptor: Runner descriptor for error context
+
+        Returns:
+            Message, MessageChunk, or None (for non-message events)
+
+        Raises:
+            RunnerExecutionError: On run.failed
+            RunnerProtocolError: On invalid result format
+        """
+        # Validate result type
+        result_type = result_dict.get('type')
+        if not result_type:
+            raise RunnerProtocolError(descriptor.id, 'Missing result type')
+
+        # Validate result size
+        try:
+            import json
+            result_json = json.dumps(result_dict)
+            if len(result_json) > MAX_RESULT_SIZE_BYTES:
+                self.ap.logger.warning(
+                    f'Runner {descriptor.id} result too large ({len(result_json)} bytes), truncating'
+                )
+                # Truncate content if possible
+                data = result_dict.get('data', {})
+                if 'chunk' in data or 'message' in data:
+                    content = data.get('chunk', {}).get('content', '') or data.get('message', {}).get('content', '')
+                    if isinstance(content, str) and len(content) > 10000:
+                        # Keep reasonable length
+                        data['chunk'] = {'role': 'assistant', 'content': content[:10000] + '...[truncated]'}
+        except Exception as e:
+            self.ap.logger.warning(f'Failed to validate runner {descriptor.id} result size: {e}')
+
+        # Handle each result type
+        data = result_dict.get('data', {})
+
+        if not self.validate_payload(result_type, data, descriptor):
+            return None
+
+        if result_type == 'message.delta':
+            return self._normalize_message_delta(data, descriptor)
+
+        elif result_type == 'message.completed':
+            return self._normalize_message_completed(data, descriptor)
+
+        elif result_type == 'tool.call.started':
+            # Log only, don't yield to pipeline
+            self.ap.logger.debug(
+                f'Runner {descriptor.id} tool call started: {data.get("tool_name", "unknown")}'
+            )
+            return None
+
+        elif result_type == 'tool.call.completed':
+            # Log only, don't yield to pipeline
+            self.ap.logger.debug(
+                f'Runner {descriptor.id} tool call completed: {data.get("tool_name", "unknown")}'
+            )
+            return None
+
+        elif result_type == 'state.updated':
+            # Log for telemetry, don't yield to pipeline
+            # Orchestrator already handles the actual PersistentStateStore update.
+            scope = data.get('scope', 'unknown')
+            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 logged: scope={scope}, key={key}, value={value_repr}'
+            )
+            return None
+
+        elif result_type == 'run.completed':
+            # May include final message
+            if 'message' in data:
+                return self._normalize_message_completed(data, descriptor)
+            # If no message, it's just completion signal
+            return None
+
+        elif result_type == 'run.failed':
+            error_msg = data.get('error', 'Unknown error')
+            error_code = data.get('code', 'unknown')
+            retryable = data.get('retryable', False)
+            raise RunnerExecutionError(
+                descriptor.id,
+                f'{error_msg} (code: {error_code})',
+                retryable=retryable,
+            )
+
+        elif result_type == 'action.requested':
+            # Reserved for EBA - log only, don't execute
+            self.ap.logger.info(
+                f'Runner {descriptor.id} requested action (not executed in current phase): '
+                f'{data.get("action", "unknown")}'
+            )
+            return None
+
+        else:
+            # Unknown type - warn and ignore.
+            self.ap.logger.warning(
+                f'Runner {descriptor.id} returned unknown result type: {result_type}. '
+                f'Expected supported types (message.delta, message.completed, run.completed, run.failed, etc.)'
+            )
+            return None
+
+    def validate_payload(
+        self,
+        result_type: str,
+        data: typing.Any,
+        descriptor: AgentRunnerDescriptor,
+    ) -> bool:
+        """Validate typed payloads that affect Host state or delivery.
+
+        Tool-call telemetry stays intentionally loose so older runners can keep
+        emitting diagnostic fields. Unknown result types are handled by the
+        caller and are not validated here.
+        """
+        payload_model = STRICT_RESULT_PAYLOADS.get(result_type)
+        if payload_model is None:
+            return True
+
+        try:
+            payload_model.model_validate(data)
+            return True
+        except Exception as e:
+            self.ap.logger.warning(
+                f'Runner {descriptor.id} returned invalid {result_type} payload; dropping result: {e}'
+            )
+            return False
+
+    def _normalize_message_delta(
+        self,
+        data: dict[str, typing.Any],
+        descriptor: AgentRunnerDescriptor,
+    ) -> provider_message.MessageChunk:
+        """Normalize message.delta to MessageChunk."""
+        chunk_data = data.get('chunk', {})
+        if not chunk_data:
+            raise RunnerProtocolError(descriptor.id, 'message.delta missing chunk data')
+
+        try:
+            chunk = provider_message.MessageChunk.model_validate(chunk_data)
+            return chunk
+        except Exception as e:
+            raise RunnerProtocolError(descriptor.id, f'Invalid chunk schema: {e}')
+
+    def _normalize_message_completed(
+        self,
+        data: dict[str, typing.Any],
+        descriptor: AgentRunnerDescriptor,
+    ) -> provider_message.Message:
+        """Normalize message.completed to Message."""
+        message_data = data.get('message', {})
+        if not message_data:
+            raise RunnerProtocolError(descriptor.id, 'message.completed missing message data')
+
+        try:
+            msg = provider_message.Message.model_validate(message_data)
+            return msg
+        except Exception as e:
+            raise RunnerProtocolError(descriptor.id, f'Invalid message schema: {e}')

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

@@ -0,0 +1,412 @@
+"""Run-side effects for AgentRunner executions."""
+
+from __future__ import annotations
+
+import typing
+
+from ...core import app
+from .descriptor import AgentRunnerDescriptor
+from .errors import RunnerProtocolError
+from .host_models import AgentBinding, AgentEventEnvelope
+from .persistent_state_store import PersistentStateStore, get_persistent_state_store
+from .run_ledger_store import RunLedgerStore
+
+
+class AgentRunJournal:
+    """Persist run events, transcript records, and state updates."""
+
+    ap: app.Application
+
+    _persistent_state_store: PersistentStateStore | None
+    _run_ledger_store: RunLedgerStore | None
+
+    def __init__(self, ap: app.Application):
+        self.ap = ap
+        self._persistent_state_store = None
+        self._run_ledger_store = None
+
+    def _get_run_ledger_store(self) -> RunLedgerStore:
+        if self._run_ledger_store is None:
+            self._run_ledger_store = RunLedgerStore(self.ap.persistence_mgr.get_db_engine())
+        return self._run_ledger_store
+
+    @staticmethod
+    def _to_plain_dict(value: typing.Any) -> dict[str, typing.Any]:
+        if hasattr(value, 'model_dump'):
+            value = value.model_dump(mode='json')
+        if isinstance(value, dict):
+            return dict(value)
+        return {}
+
+    @classmethod
+    def _sanitize_content_item(cls, value: typing.Any) -> typing.Any:
+        item = cls._to_plain_dict(value)
+        if not item:
+            return value
+        item_type = item.get('type')
+        if item_type == 'image_base64' and item.get('image_base64'):
+            item['image_base64'] = None
+            item['content_redacted'] = True
+        elif item_type == 'file_base64' and item.get('file_base64'):
+            item['file_base64'] = None
+            item['content_redacted'] = True
+        return item
+
+    @classmethod
+    def _sanitize_attachment_ref(cls, value: typing.Any) -> dict[str, typing.Any]:
+        item = cls._to_plain_dict(value)
+        if item.get('content'):
+            item['content'] = None
+            item['content_redacted'] = True
+        return item
+
+    @classmethod
+    def _sanitize_contents(cls, contents: typing.Iterable[typing.Any]) -> list[typing.Any]:
+        return [cls._sanitize_content_item(content) for content in contents]
+
+    @classmethod
+    def _sanitize_attachments(cls, attachments: typing.Iterable[typing.Any]) -> list[dict[str, typing.Any]]:
+        return [cls._sanitize_attachment_ref(attachment) for attachment in attachments]
+
+    async def create_run(
+        self,
+        *,
+        event: AgentEventEnvelope,
+        binding: AgentBinding,
+        descriptor: AgentRunnerDescriptor,
+        context: dict[str, typing.Any],
+        authorization: dict[str, typing.Any],
+    ) -> dict[str, typing.Any]:
+        """Create the Host-owned run ledger record."""
+        runtime = context.get('runtime') if isinstance(context, dict) else {}
+        return await self._get_run_ledger_store().create_run(
+            run_id=context['run_id'],
+            event_id=event.event_id,
+            binding_id=binding.binding_id,
+            runner_id=descriptor.id,
+            conversation_id=event.conversation_id,
+            thread_id=event.thread_id,
+            workspace_id=event.workspace_id,
+            bot_id=event.bot_id,
+            deadline_at=runtime.get('deadline_at') if isinstance(runtime, dict) else None,
+            authorization=authorization,
+            metadata={
+                'event_type': event.event_type,
+                'source': event.source,
+            },
+        )
+
+    async def append_run_result(
+        self,
+        *,
+        result_dict: dict[str, typing.Any],
+        run_id: str,
+        sequence: int,
+        source: str = 'runner',
+        metadata: dict[str, typing.Any] | None = None,
+    ) -> dict[str, typing.Any]:
+        """Persist one AgentRunResult in the run ledger."""
+        usage = result_dict.get('usage')
+        if hasattr(usage, 'model_dump'):
+            usage = usage.model_dump(mode='json')
+        return await self._get_run_ledger_store().append_event(
+            run_id=run_id,
+            sequence=sequence,
+            event_type=str(result_dict.get('type') or 'unknown'),
+            data=result_dict.get('data') if isinstance(result_dict.get('data'), dict) else {},
+            usage=usage if isinstance(usage, dict) else None,
+            source=source,
+            metadata=metadata,
+        )
+
+    async def finalize_run(
+        self,
+        *,
+        run_id: str,
+        status: str,
+        status_reason: str | None = None,
+        usage: dict[str, typing.Any] | None = None,
+        metadata: dict[str, typing.Any] | None = None,
+    ) -> dict[str, typing.Any] | None:
+        """Finalize or update the Host-owned run ledger record."""
+        return await self._get_run_ledger_store().finalize_run(
+            run_id=run_id,
+            status=status,
+            status_reason=status_reason,
+            usage=usage,
+            metadata=metadata,
+        )
+
+    async def get_run(self, run_id: str) -> dict[str, typing.Any] | None:
+        """Return the persisted run ledger record."""
+        return await self._get_run_ledger_store().get_run(run_id)
+
+    async def handle_state_updated_event(
+        self,
+        result_dict: dict[str, typing.Any],
+        event: AgentEventEnvelope,
+        binding: AgentBinding,
+        descriptor: AgentRunnerDescriptor,
+        run_id: str | None = None,
+    ) -> None:
+        """Handle state.updated result in event-first mode."""
+        data = result_dict.get('data', {})
+
+        result_run_id = result_dict.get('run_id')
+        if run_id and result_run_id and result_run_id != run_id:
+            raise RunnerProtocolError(
+                descriptor.id,
+                f'state.updated run_id mismatch: expected {run_id}, got {result_run_id}',
+            )
+
+        scope = data.get('scope')
+        if not scope:
+            raise RunnerProtocolError(
+                descriptor.id,
+                'state.updated missing required field: scope',
+            )
+
+        key = data.get('key')
+        value = data.get('value')
+
+        if not key:
+            raise RunnerProtocolError(
+                descriptor.id,
+                'state.updated missing required field: key',
+            )
+
+        if self._persistent_state_store is None:
+            self._persistent_state_store = get_persistent_state_store(self.ap.persistence_mgr.get_db_engine())
+
+        success, error = await self._persistent_state_store.apply_update_from_event(
+            event=event,
+            binding=binding,
+            descriptor=descriptor,
+            scope=scope,
+            key=key,
+            value=value,
+            logger=self.ap.logger,
+        )
+
+        if success:
+            self.ap.logger.debug(f'Runner {descriptor.id} state.updated (event mode): scope={scope}, key={key}')
+        elif error:
+            self.ap.logger.warning(f'Runner {descriptor.id} state.updated rejected: {error}')
+
+    async def write_event_log(
+        self,
+        event: AgentEventEnvelope,
+        binding: AgentBinding,
+        run_id: str,
+        runner_id: str,
+        metadata: dict[str, typing.Any] | None = None,
+    ) -> str:
+        """Write incoming event to EventLog."""
+        import datetime
+
+        from .event_log_store import EventLogStore
+
+        store = EventLogStore(self.ap.persistence_mgr.get_db_engine())
+
+        input_summary = None
+        input_json = None
+        if event.input:
+            if event.input.text:
+                input_summary = event.input.text[:1000]
+            input_json = {
+                'text': event.input.text,
+                'contents': self._sanitize_contents(event.input.contents),
+                'attachments': self._sanitize_attachments(event.input.attachments),
+            }
+
+        return await store.append_event(
+            event_id=event.event_id,
+            event_type=event.event_type,
+            source=event.source,
+            bot_id=event.bot_id,
+            workspace_id=event.workspace_id,
+            conversation_id=event.conversation_id,
+            thread_id=event.thread_id,
+            actor_type=event.actor.actor_type if event.actor else None,
+            actor_id=event.actor.actor_id if event.actor else None,
+            actor_name=event.actor.actor_name if event.actor else None,
+            subject_type=event.subject.subject_type if event.subject else None,
+            subject_id=event.subject.subject_id if event.subject else None,
+            input_summary=input_summary,
+            input_json=input_json,
+            run_id=run_id,
+            runner_id=runner_id,
+            event_time=(
+                datetime.datetime.fromtimestamp(event.event_time, datetime.timezone.utc) if event.event_time else None
+            ),
+            metadata=metadata,
+        )
+
+    async def write_user_transcript(
+        self,
+        event: AgentEventEnvelope,
+        event_log_id: str,
+    ) -> None:
+        """Write user message to Transcript."""
+        from .transcript_store import TranscriptStore
+
+        store = TranscriptStore(self.ap.persistence_mgr.get_db_engine())
+
+        content = event.input.text if event.input else None
+        content_json = None
+        if event.input:
+            content_json = {
+                'role': 'user',
+                'content': self._sanitize_contents(event.input.contents) if event.input.contents else [],
+            }
+
+        attachment_refs = []
+        if event.input and event.input.attachments:
+            for a in event.input.attachments:
+                attachment_refs.append(self._sanitize_attachment_ref(a))
+
+        await store.append_transcript(
+            transcript_id=None,
+            event_id=event_log_id,
+            conversation_id=event.conversation_id,
+            role='user',
+            bot_id=event.bot_id,
+            workspace_id=event.workspace_id,
+            content=content,
+            content_json=content_json,
+            attachment_refs=attachment_refs if attachment_refs else None,
+            thread_id=event.thread_id,
+            item_type='message',
+            metadata={
+                'actor_type': event.actor.actor_type if event.actor else None,
+                'actor_id': event.actor.actor_id if event.actor else None,
+            },
+        )
+
+    async def write_steering_dropped_audits(
+        self,
+        items: list[dict[str, typing.Any]],
+        run_id: str,
+        runner_id: str,
+        *,
+        reason: str = 'run_ended',
+    ) -> None:
+        """Write terminal audit events for steering items left unconsumed."""
+        if not items:
+            return
+
+        import datetime
+        import uuid
+
+        from .event_log_store import EventLogStore
+
+        store = EventLogStore(self.ap.persistence_mgr.get_db_engine())
+
+        for item in items:
+            event = item.get('event') if isinstance(item.get('event'), dict) else {}
+            input_data = item.get('input') if isinstance(item.get('input'), dict) else {}
+            conversation = item.get('conversation') if isinstance(item.get('conversation'), dict) else {}
+            actor = item.get('actor') if isinstance(item.get('actor'), dict) else {}
+            subject = item.get('subject') if isinstance(item.get('subject'), dict) else {}
+
+            text = input_data.get('text')
+            input_summary = text[:1000] if isinstance(text, str) and text else 'Unconsumed steering input dropped'
+            event_time = None
+            raw_event_time = event.get('event_time')
+            if raw_event_time:
+                try:
+                    event_time = datetime.datetime.fromtimestamp(
+                        raw_event_time,
+                        datetime.timezone.utc,
+                    )
+                except (TypeError, ValueError, OSError):
+                    event_time = None
+
+            await store.append_event(
+                event_id=str(uuid.uuid4()),
+                event_type='steering.dropped',
+                source='host',
+                bot_id=conversation.get('bot_id'),
+                workspace_id=conversation.get('workspace_id'),
+                conversation_id=conversation.get('conversation_id'),
+                thread_id=conversation.get('thread_id'),
+                actor_type=actor.get('actor_type'),
+                actor_id=actor.get('actor_id'),
+                actor_name=actor.get('actor_name'),
+                subject_type=subject.get('subject_type'),
+                subject_id=subject.get('subject_id'),
+                input_summary=input_summary,
+                input_json={
+                    'text': text,
+                    'contents': self._sanitize_contents(input_data.get('contents') or []),
+                    'attachments': self._sanitize_attachments(input_data.get('attachments') or []),
+                },
+                run_id=run_id,
+                runner_id=runner_id,
+                event_time=event_time,
+                metadata={
+                    'steering': {
+                        'status': 'dropped',
+                        'reason': reason,
+                        'original_event_id': event.get('event_id'),
+                        'claimed_run_id': item.get('claimed_run_id'),
+                        'claimed_runner_id': item.get('runner_id'),
+                        'claimed_at': item.get('claimed_at'),
+                    },
+                },
+            )
+
+    async def write_assistant_transcript(
+        self,
+        result_dict: dict[str, typing.Any],
+        event: AgentEventEnvelope,
+        run_id: str,
+        runner_id: str,
+    ) -> None:
+        """Write assistant message to Transcript."""
+        import uuid
+
+        from .transcript_store import TranscriptStore
+
+        store = TranscriptStore(self.ap.persistence_mgr.get_db_engine())
+
+        data = result_dict.get('data', {})
+        message = data.get('message', {})
+
+        content = None
+        content_json = None
+
+        if isinstance(message.get('content'), str):
+            content = message['content']
+            content_json = message
+        elif isinstance(message.get('content'), list):
+            text_parts = []
+            for c in message['content']:
+                if isinstance(c, dict) and c.get('type') == 'text':
+                    text_parts.append(c.get('text', ''))
+            content = ' '.join(text_parts) if text_parts else None
+            content_json = {
+                **message,
+                'content': self._sanitize_contents(message['content']),
+            }
+
+        assistant_event_id = str(uuid.uuid4())
+
+        await store.append_transcript(
+            transcript_id=str(uuid.uuid4()),
+            event_id=assistant_event_id,
+            conversation_id=event.conversation_id,
+            role='assistant',
+            bot_id=event.bot_id,
+            workspace_id=event.workspace_id,
+            content=content,
+            content_json=content_json,
+            thread_id=event.thread_id,
+            item_type='message',
+            run_id=run_id,
+            runner_id=runner_id,
+            metadata={
+                'run_id': run_id,
+                'runner_id': runner_id,
+            },
+        )

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

@@ -0,0 +1,424 @@
+"""Agent run session registry for proxy action permission validation."""
+from __future__ import annotations
+
+import asyncio
+import copy
+import typing
+import time
+import threading
+
+from .context_builder import AgentResources
+
+
+MAX_STEERING_QUEUE_ITEMS = 100
+
+DEFAULT_RESOURCE_OPERATIONS: dict[str, set[str]] = {
+    'model': {'invoke', 'stream', 'rerank'},
+    'tool': {'detail', 'call'},
+    'knowledge_base': {'list', 'retrieve'},
+    'skill': {'activate'},
+}
+
+
+class AgentRunSessionStatus(typing.TypedDict):
+    """Status tracking for agent run session."""
+    started_at: int
+    last_activity_at: int
+
+
+class RunAuthorizationSnapshot(typing.TypedDict):
+    """Frozen authorization data for one active run.
+
+    ResourceBuilder creates the authorized resource list once before runner
+    execution. Runtime proxy handlers must validate against this run-scoped
+    snapshot instead of recomputing resource policy.
+    """
+
+    resources: AgentResources
+    available_apis: dict[str, bool]
+    conversation_id: str | None
+    bot_id: str | None
+    workspace_id: str | None
+    thread_id: str | None
+    state_policy: dict[str, typing.Any]
+    state_context: dict[str, typing.Any]
+    authorized_ids: dict[str, set[str]]
+    authorized_operations: dict[str, dict[str, set[str]]]
+
+
+SteeringQueueItem = dict[str, typing.Any]
+
+
+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: Host entry query ID, only present for query-based adapters
+        plugin_identity: Plugin identifier (author/name) of the runner
+        authorization: Run-scoped authorization snapshot; runtime auth truth
+        status: Session status tracking
+    """
+    run_id: str
+    runner_id: str
+    query_id: int | None
+    plugin_identity: str  # author/name
+    authorization: RunAuthorizationSnapshot
+    status: AgentRunSessionStatus
+    steering_queue: list[SteeringQueueItem]
+
+
+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,
+        conversation_id: str | None = None,
+        bot_id: str | None = None,
+        workspace_id: str | None = None,
+        thread_id: str | None = None,
+        available_apis: dict[str, bool] | None = None,
+        state_policy: dict[str, typing.Any] | None = None,
+        state_context: dict[str, typing.Any] | None = None,
+    ) -> None:
+        """Register a new agent run session.
+
+        Args:
+            run_id: Unique run identifier
+            runner_id: Runner descriptor ID
+            query_id: Host entry query ID, only present for query-based adapters
+            plugin_identity: Plugin identifier (author/name)
+            resources: Authorized resources for this run
+            conversation_id: Conversation ID for history/event access
+            bot_id: Bot UUID for history/event access
+            workspace_id: Workspace ID for history/event access
+            thread_id: Thread ID for history/event access
+            available_apis: Run-scoped pull APIs exposed in AgentRunContext
+            state_policy: State policy from binding (enable_state, state_scopes)
+            state_context: Context for state API (scope_keys, binding_identity, etc.)
+        """
+        if not isinstance(plugin_identity, str) or not plugin_identity.strip():
+            raise ValueError('plugin_identity is required for agent run sessions')
+
+        now = int(time.time())
+
+        available_apis = copy.deepcopy(available_apis or {})
+
+        # Normalize state_policy to defaults if None
+        if state_policy is None:
+            state_policy = {'enable_state': True, 'state_scopes': ['conversation', 'actor']}
+
+        # Normalize state_context to empty dict if None
+        state_context = state_context or {}
+
+        resources_snapshot = copy.deepcopy(resources)
+        authorization: RunAuthorizationSnapshot = {
+            'resources': resources_snapshot,
+            'available_apis': available_apis,
+            'conversation_id': conversation_id,
+            'bot_id': bot_id,
+            'workspace_id': workspace_id,
+            'thread_id': thread_id,
+            'state_policy': copy.deepcopy(state_policy),
+            'state_context': copy.deepcopy(state_context),
+            'authorized_ids': self._build_authorized_ids(resources_snapshot),
+            'authorized_operations': self._build_authorized_operations(resources_snapshot),
+        }
+
+        session: AgentRunSession = {
+            'run_id': run_id,
+            'runner_id': runner_id,
+            'query_id': query_id,
+            'plugin_identity': plugin_identity,
+            'authorization': authorization,
+            'status': {
+                'started_at': now,
+                'last_activity_at': now,
+            },
+            'steering_queue': [],
+        }
+
+        async with self._lock:
+            self._sessions[run_id] = session
+
+    def _build_authorized_ids(self, resources: AgentResources) -> dict[str, set[str]]:
+        """Pre-compute authorized resource IDs for O(1) lookup."""
+        return {
+            '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', [])},
+            'skill': {s.get('skill_name') for s in resources.get('skills', [])},
+        }
+
+    def _build_authorized_operations(
+        self,
+        resources: AgentResources,
+    ) -> dict[str, dict[str, set[str]]]:
+        """Pre-compute resource operations for runtime action validation."""
+        return {
+            'model': {
+                m.get('model_id'): self._resource_operations('model', m)
+                for m in resources.get('models', [])
+                if m.get('model_id')
+            },
+            'tool': {
+                t.get('tool_name'): self._resource_operations('tool', t)
+                for t in resources.get('tools', [])
+                if t.get('tool_name')
+            },
+            'knowledge_base': {
+                kb.get('kb_id'): self._resource_operations('knowledge_base', kb)
+                for kb in resources.get('knowledge_bases', [])
+                if kb.get('kb_id')
+            },
+            'skill': {
+                s.get('skill_name'): self._resource_operations('skill', s)
+                for s in resources.get('skills', [])
+                if s.get('skill_name')
+            },
+        }
+
+    @staticmethod
+    def _resource_operations(resource_type: str, resource: dict[str, typing.Any]) -> set[str]:
+        """Return explicit operations or the compatibility default for old resources."""
+        operations = resource.get('operations')
+        if isinstance(operations, list) and operations:
+            return {str(operation) for operation in operations}
+        return set(DEFAULT_RESOURCE_OPERATIONS.get(resource_type, set()))
+
+    async def unregister(self, run_id: str) -> AgentRunSession | None:
+        """Unregister an agent run session.
+
+        Args:
+            run_id: Unique run identifier
+
+        Returns:
+            The removed session, if one existed. Callers can inspect any
+            pending in-memory queues before they are discarded.
+        """
+        async with self._lock:
+            return self._sessions.pop(run_id, None)
+
+    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())
+
+    async def find_steering_target(
+        self,
+        *,
+        conversation_id: str,
+        runner_id: str,
+        bot_id: str | None = None,
+        workspace_id: str | None = None,
+        thread_id: str | None = None,
+    ) -> str | None:
+        """Find the oldest active run that can accept steering for a conversation."""
+        async with self._lock:
+            candidates: list[tuple[int, str]] = []
+            for run_id, session in self._sessions.items():
+                authorization = session['authorization']
+                if session.get('runner_id') != runner_id:
+                    continue
+                if authorization.get('conversation_id') != conversation_id:
+                    continue
+                if authorization.get('bot_id') != bot_id:
+                    continue
+                if authorization.get('workspace_id') != workspace_id:
+                    continue
+                if authorization.get('thread_id') != thread_id:
+                    continue
+                if not authorization.get('available_apis', {}).get('steering_pull', False):
+                    continue
+                candidates.append((session['status'].get('started_at', 0), run_id))
+
+            if not candidates:
+                return None
+
+            candidates.sort(key=lambda item: item[0])
+            return candidates[0][1]
+
+    async def enqueue_steering(
+        self,
+        run_id: str,
+        item: SteeringQueueItem,
+    ) -> bool:
+        """Append one steering item to an active run queue."""
+        async with self._lock:
+            session = self._sessions.get(run_id)
+            if session is None:
+                return False
+            if len(session['steering_queue']) >= MAX_STEERING_QUEUE_ITEMS:
+                return False
+            session['steering_queue'].append(copy.deepcopy(item))
+            session['status']['last_activity_at'] = int(time.time())
+            return True
+
+    async def pull_steering(
+        self,
+        run_id: str,
+        *,
+        mode: str = 'all',
+        limit: int | None = None,
+    ) -> list[SteeringQueueItem]:
+        """Pop pending steering items from a run queue."""
+        async with self._lock:
+            session = self._sessions.get(run_id)
+            if session is None:
+                return []
+
+            queue = session['steering_queue']
+            if not queue:
+                return []
+
+            normalized_mode = str(mode or 'all').lower()
+            if normalized_mode in {'one', 'one-at-a-time', 'one_at_a_time'}:
+                count = 1
+            elif isinstance(limit, int) and limit > 0:
+                count = min(limit, len(queue))
+            else:
+                count = len(queue)
+
+            count = max(0, min(count, len(queue), 100))
+            items = [copy.deepcopy(item) for item in queue[:count]]
+            del queue[:count]
+            session['status']['last_activity_at'] = int(time.time())
+            return items
+
+    def is_resource_allowed(
+        self,
+        session: AgentRunSession,
+        resource_type: str,
+        resource_id: str,
+        operation: str | None = None,
+    ) -> 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, 'plugin'/'workspace')
+            operation: Optional operation to check within the authorized resource
+
+        Returns:
+            True if resource is authorized, False otherwise
+        """
+        authorization = session['authorization']
+        authorized_ids = authorization['authorized_ids']
+        resources = authorization['resources']
+
+        if resource_type in ('model', 'tool', 'knowledge_base', 'skill'):
+            if resource_id not in authorized_ids.get(resource_type, set()):
+                return False
+            if operation is None:
+                return True
+            operation_map = authorization.get('authorized_operations', {})
+            operations = operation_map.get(resource_type, {}).get(resource_id)
+            if not operations:
+                operations = DEFAULT_RESOURCE_OPERATIONS.get(resource_type, set())
+            return operation in operations
+
+        if resource_type == 'storage':
+            storage = 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_scope.py

@@ -0,0 +1,136 @@
+"""State scope key helpers for AgentRunner host-owned state."""
+from __future__ import annotations
+
+import hashlib
+import json
+import typing
+
+from .descriptor import AgentRunnerDescriptor
+from .host_models import AgentBinding, AgentEventEnvelope
+
+
+VALID_STATE_SCOPES = ('conversation', 'actor', 'subject', 'runner')
+
+STATE_KEY_ALIASES = {
+    'conversation_id': 'external.conversation_id',
+}
+
+
+def normalize_state_key(key: str) -> str:
+    """Map accepted public aliases to protocol state keys."""
+    return STATE_KEY_ALIASES.get(key, key)
+
+
+def get_binding_identity(binding: AgentBinding) -> str:
+    """Return the stable binding identity used for state isolation."""
+    if binding.binding_id:
+        return binding.binding_id
+
+    scope = binding.scope
+    if scope.scope_type and scope.scope_id:
+        return f'{scope.scope_type}:{scope.scope_id}'
+
+    return 'unknown_binding'
+
+
+def _scope_hash(scope: str, parts: dict[str, typing.Any]) -> str:
+    """Encode state scope dimensions without separator ambiguity."""
+    payload = {
+        'version': 2,
+        'scope': scope,
+        **parts,
+    }
+    raw = json.dumps(payload, sort_keys=True, separators=(',', ':'), ensure_ascii=False)
+    return f'{scope}:v2:{hashlib.sha256(raw.encode("utf-8")).hexdigest()}'
+
+
+def _base_scope_parts(
+    event: AgentEventEnvelope,
+    binding: AgentBinding,
+    descriptor: AgentRunnerDescriptor,
+) -> dict[str, typing.Any]:
+    return {
+        'runner_id': descriptor.id,
+        'binding_identity': get_binding_identity(binding),
+        'bot_id': event.bot_id,
+        'workspace_id': event.workspace_id,
+    }
+
+
+def build_state_scope_key(
+    scope: str,
+    event: AgentEventEnvelope,
+    binding: AgentBinding,
+    descriptor: AgentRunnerDescriptor,
+) -> str | None:
+    """Build the storage key for one state scope.
+
+    Returns None when the event lacks the identity required by that scope.
+    """
+    base_parts = _base_scope_parts(event, binding, descriptor)
+
+    if scope == 'conversation':
+        if not event.conversation_id:
+            return None
+        return _scope_hash(scope, {
+            **base_parts,
+            'conversation_id': event.conversation_id,
+            'thread_id': event.thread_id,
+        })
+
+    if scope == 'actor':
+        if not event.actor or not event.actor.actor_id:
+            return None
+        return _scope_hash(scope, {
+            **base_parts,
+            'actor_type': event.actor.actor_type or 'user',
+            'actor_id': event.actor.actor_id,
+        })
+
+    if scope == 'subject':
+        if not event.subject or not event.subject.subject_id:
+            return None
+        return _scope_hash(scope, {
+            **base_parts,
+            'subject_type': event.subject.subject_type or 'unknown',
+            'subject_id': event.subject.subject_id,
+        })
+
+    if scope == 'runner':
+        return _scope_hash(scope, base_parts)
+
+    return None
+
+
+def build_state_scope_keys(
+    event: AgentEventEnvelope,
+    binding: AgentBinding,
+    descriptor: AgentRunnerDescriptor,
+) -> dict[str, str]:
+    """Build all available scope keys for an event/binding pair."""
+    scope_keys: dict[str, str] = {}
+    for scope in VALID_STATE_SCOPES:
+        scope_key = build_state_scope_key(scope, event, binding, descriptor)
+        if scope_key:
+            scope_keys[scope] = scope_key
+    return scope_keys
+
+
+def build_state_context(
+    event: AgentEventEnvelope,
+    binding: AgentBinding,
+    descriptor: AgentRunnerDescriptor,
+) -> dict[str, typing.Any]:
+    """Build the State API context stored in the run session."""
+    return {
+        'scope_keys': build_state_scope_keys(event, binding, descriptor),
+        'binding_identity': get_binding_identity(binding),
+        'bot_id': event.bot_id,
+        'workspace_id': event.workspace_id,
+        'conversation_id': event.conversation_id,
+        'thread_id': event.thread_id,
+        'actor_type': event.actor.actor_type if event.actor else None,
+        'actor_id': event.actor.actor_id if event.actor else None,
+        'subject_type': event.subject.subject_type if event.subject else None,
+        'subject_id': event.subject.subject_id if event.subject else None,
+    }

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

@@ -0,0 +1,426 @@
+"""Transcript store for writing and querying conversation history."""
+from __future__ import annotations
+
+import json
+import datetime
+import typing
+import uuid
+
+import sqlalchemy
+from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession
+from sqlalchemy.orm import sessionmaker
+
+from ...entity.persistence.transcript import Transcript
+from langbot_plugin.api.entities.builtin.provider import message as provider_message
+
+
+UTC = datetime.timezone.utc
+
+
+def _utc_now() -> datetime.datetime:
+    return datetime.datetime.now(UTC)
+
+
+def _datetime_to_epoch(value: datetime.datetime | None) -> int | None:
+    if value is None:
+        return None
+    if value.tzinfo is None:
+        value = value.replace(tzinfo=UTC)
+    else:
+        value = value.astimezone(UTC)
+    return int(value.timestamp())
+
+
+class TranscriptStore:
+    """Store for Transcript records.
+
+    Handles writing transcript items and querying them for history API.
+    All methods are async and use the provided database engine.
+    """
+
+    engine: AsyncEngine
+
+    # Hard limits
+    MAX_CONTENT_LENGTH = 4000
+    HARD_LIMIT = 100
+
+    def __init__(self, engine: AsyncEngine):
+        self.engine = engine
+        self._session_factory = sessionmaker(
+            engine, class_=AsyncSession, expire_on_commit=False
+        )
+
+    async def append_transcript(
+        self,
+        transcript_id: str | None,
+        event_id: str,
+        conversation_id: str,
+        role: str,
+        bot_id: str | None = None,
+        workspace_id: str | None = None,
+        content: str | None = None,
+        content_json: dict[str, typing.Any] | None = None,
+        attachment_refs: list[dict[str, typing.Any]] | None = None,
+        thread_id: str | None = None,
+        item_type: str = "message",
+        run_id: str | None = None,
+        runner_id: str | None = None,
+        metadata: dict[str, typing.Any] | None = None,
+    ) -> str:
+        """Append a transcript item.
+
+        Args:
+            transcript_id: Unique transcript ID (generated if None)
+            event_id: Source event ID
+            conversation_id: Conversation ID
+            role: Message role (user, assistant, system, tool)
+            bot_id: Bot UUID scope
+            workspace_id: Workspace scope
+            content: Text content
+            content_json: Full structured content
+            attachment_refs: Attachment references
+            thread_id: Thread ID
+            item_type: Item type
+            run_id: Run ID that generated this
+            runner_id: Runner ID that generated this
+            metadata: Additional metadata
+
+        Returns:
+            The transcript_id
+        """
+        if transcript_id is None:
+            transcript_id = str(uuid.uuid4())
+
+        # Truncate content if too long
+        if content and len(content) > self.MAX_CONTENT_LENGTH:
+            content = content[:self.MAX_CONTENT_LENGTH - 3] + "..."
+
+        async with self._session_factory() as session:
+            item = Transcript(
+                transcript_id=transcript_id,
+                event_id=event_id,
+                bot_id=bot_id,
+                workspace_id=workspace_id,
+                conversation_id=conversation_id,
+                thread_id=thread_id,
+                role=role,
+                item_type=item_type,
+                content=content,
+                content_json=json.dumps(content_json) if content_json else None,
+                attachment_refs_json=json.dumps(attachment_refs) if attachment_refs else None,
+                seq=0,
+                run_id=run_id,
+                runner_id=runner_id,
+                created_at=_utc_now(),
+                metadata_json=json.dumps(metadata) if metadata else None,
+            )
+            session.add(item)
+            await session.flush()
+            item.seq = item.id or await self._get_next_seq(conversation_id)
+            await session.commit()
+
+        return transcript_id
+
+    async def page_transcript(
+        self,
+        conversation_id: str,
+        before_seq: int | None = None,
+        after_seq: int | None = None,
+        limit: int = 50,
+        direction: str = "backward",
+        include_attachments: bool = False,
+        bot_id: str | None = None,
+        workspace_id: str | None = None,
+        thread_id: str | None = None,
+        strict_thread: bool = False,
+    ) -> tuple[list[dict[str, typing.Any]], int | None, int | None, bool]:
+        """Page through transcript items.
+
+        Args:
+            conversation_id: Conversation ID
+            before_seq: Get items before this sequence (backward)
+            after_seq: Get items after this sequence (forward)
+            limit: Maximum items to return (capped at 100)
+            direction: 'backward' (older) or 'forward' (newer)
+            include_attachments: Include attachment refs
+            bot_id: Optional bot scope filter
+            workspace_id: Optional workspace scope filter
+            thread_id: Optional thread scope filter
+            strict_thread: When true, require thread_id equality including NULL
+
+        Returns:
+            Tuple of (items, next_seq, prev_seq, has_more)
+        """
+        limit = min(limit, self.HARD_LIMIT)
+
+        async with self._session_factory() as session:
+            query = sqlalchemy.select(Transcript).where(
+                Transcript.conversation_id == conversation_id
+            )
+            query = self._apply_scope_filters(query, bot_id, workspace_id, thread_id, strict_thread)
+
+            if direction == "backward" and before_seq is not None:
+                query = query.where(Transcript.seq < before_seq)
+                query = query.order_by(Transcript.seq.desc())
+            elif direction == "forward" and after_seq is not None:
+                query = query.where(Transcript.seq > after_seq)
+                query = query.order_by(Transcript.seq.asc())
+            else:
+                # Default: most recent items first (backward from latest)
+                query = query.order_by(Transcript.seq.desc())
+
+            query = query.limit(limit + 1)
+
+            result = await session.execute(query)
+            rows = result.scalars().all()
+
+            items = [self._row_to_dict(row, include_attachments) for row in rows[:limit]]
+            has_more = len(rows) > limit
+
+            # Calculate cursors
+            next_seq = None
+            prev_seq = None
+
+            if direction == "backward":
+                # Items are in descending order
+                if items:
+                    next_seq = items[-1].get('seq') if has_more else None
+                    prev_seq = items[0].get('seq')
+            else:
+                # Items are in ascending order
+                if items:
+                    next_seq = items[-1].get('seq') if has_more else None
+                    prev_seq = items[0].get('seq')
+
+            return items, next_seq, prev_seq, has_more
+
+    async def search_transcript(
+        self,
+        conversation_id: str,
+        query_text: str,
+        filters: dict[str, typing.Any] | None = None,
+        top_k: int = 10,
+        bot_id: str | None = None,
+        workspace_id: str | None = None,
+        thread_id: str | None = None,
+        strict_thread: bool = False,
+    ) -> list[dict[str, typing.Any]]:
+        """Search transcript items.
+
+        Basic implementation using LIKE filtering.
+
+        Args:
+            conversation_id: Conversation ID
+            query_text: Search query
+            filters: Optional filters
+            top_k: Maximum results
+            bot_id: Optional bot scope filter
+            workspace_id: Optional workspace scope filter
+            thread_id: Optional thread scope filter
+            strict_thread: When true, require thread_id equality including NULL
+
+        Returns:
+            List of matching items
+        """
+        async with self._session_factory() as session:
+            query = sqlalchemy.select(Transcript).where(
+                Transcript.conversation_id == conversation_id,
+                Transcript.content.ilike(f"%{query_text}%"),
+            )
+            query = self._apply_scope_filters(query, bot_id, workspace_id, thread_id, strict_thread)
+
+            # Apply additional filters
+            if filters:
+                if 'roles' in filters:
+                    query = query.where(Transcript.role.in_(filters['roles']))
+                if 'item_types' in filters:
+                    query = query.where(Transcript.item_type.in_(filters['item_types']))
+
+            query = query.order_by(Transcript.seq.desc()).limit(top_k)
+
+            result = await session.execute(query)
+            rows = result.scalars().all()
+
+            return [self._row_to_dict(row, include_attachments=True) for row in rows]
+
+    async def get_latest_cursor(
+        self,
+        conversation_id: str,
+    ) -> str | None:
+        """Get the latest cursor for a conversation.
+
+        Args:
+            conversation_id: Conversation ID
+
+        Returns:
+            Cursor string (seq number), or None if no items
+        """
+        async with self._session_factory() as session:
+            result = await session.execute(
+                sqlalchemy.select(Transcript.seq)
+                .where(Transcript.conversation_id == conversation_id)
+                .order_by(Transcript.seq.desc())
+                .limit(1)
+            )
+            row = result.scalars().first()
+            if row is None:
+                return None
+            return str(row)
+
+    async def get_legacy_provider_messages(
+        self,
+        conversation_id: str,
+        limit: int = HARD_LIMIT,
+        bot_id: str | None = None,
+        workspace_id: str | None = None,
+        thread_id: str | None = None,
+        strict_thread: bool = False,
+    ) -> list[provider_message.Message]:
+        """Project Transcript rows into the legacy provider Message view.
+
+        AgentRunner history is canonical in Transcript. This view exists for
+        legacy Pipeline readers such as PromptPreProcessing that still expect
+        query.messages.
+        """
+        items, _, _, _ = await self.page_transcript(
+            conversation_id=conversation_id,
+            limit=limit,
+            direction="backward",
+            bot_id=bot_id,
+            workspace_id=workspace_id,
+            thread_id=thread_id,
+            strict_thread=strict_thread,
+        )
+
+        messages: list[provider_message.Message] = []
+        for item in reversed(items):
+            message = self._transcript_item_to_provider_message(item)
+            if message is not None:
+                messages.append(message)
+        return messages
+
+    async def has_history_before(
+        self,
+        conversation_id: str,
+        seq: int,
+        bot_id: str | None = None,
+        workspace_id: str | None = None,
+        thread_id: str | None = None,
+        strict_thread: bool = False,
+    ) -> bool:
+        """Check if there is history before a sequence number.
+
+        Args:
+            conversation_id: Conversation ID
+            seq: Sequence number
+
+        Returns:
+            True if there are items before
+        """
+        async with self._session_factory() as session:
+            query = (
+                sqlalchemy.select(sqlalchemy.func.count())
+                .select_from(Transcript)
+                .where(Transcript.conversation_id == conversation_id, Transcript.seq < seq)
+            )
+            query = self._apply_scope_filters(query, bot_id, workspace_id, thread_id, strict_thread)
+            result = await session.execute(query)
+            count = result.scalar()
+            return count > 0
+
+    def _apply_scope_filters(
+        self,
+        query: typing.Any,
+        bot_id: str | None,
+        workspace_id: str | None,
+        thread_id: str | None,
+        strict_thread: bool,
+    ) -> typing.Any:
+        if bot_id is not None:
+            query = query.where(Transcript.bot_id == bot_id)
+        if workspace_id is not None:
+            query = query.where(Transcript.workspace_id == workspace_id)
+        if strict_thread:
+            if thread_id is None:
+                query = query.where(Transcript.thread_id.is_(None))
+            else:
+                query = query.where(Transcript.thread_id == thread_id)
+        return query
+
+    async def cleanup_transcripts_older_than(
+        self,
+        before: datetime.datetime,
+    ) -> int:
+        """Delete Transcript rows created before the supplied timestamp."""
+        async with self._session_factory() as session:
+            result = await session.execute(
+                sqlalchemy.delete(Transcript).where(Transcript.created_at < before)
+            )
+            await session.commit()
+            return result.rowcount or 0
+
+    async def _get_next_seq(self, conversation_id: str) -> int:
+        """Fallback next sequence number for stores that cannot expose autoincrement IDs."""
+        async with self._session_factory() as session:
+            result = await session.execute(
+                sqlalchemy.select(sqlalchemy.func.max(Transcript.seq))
+                .where(Transcript.conversation_id == conversation_id)
+            )
+            max_seq = result.scalar()
+            return (max_seq or 0) + 1
+
+    def _row_to_dict(
+        self,
+        row: Transcript,
+        include_attachments: bool = False,
+    ) -> dict[str, typing.Any]:
+        """Convert a Transcript row to dict."""
+        result = {
+            'transcript_id': row.transcript_id,
+            'event_id': row.event_id,
+            'bot_id': row.bot_id,
+            'workspace_id': row.workspace_id,
+            'conversation_id': row.conversation_id,
+            'thread_id': row.thread_id,
+            'role': row.role,
+            'item_type': row.item_type,
+            'content': row.content,
+            'content_json': json.loads(row.content_json) if row.content_json else None,
+            'seq': row.seq,
+            'cursor': str(row.seq),
+            'created_at': _datetime_to_epoch(row.created_at),
+            'metadata': json.loads(row.metadata_json) if row.metadata_json else {},
+        }
+
+        if include_attachments and row.attachment_refs_json:
+            result['attachment_refs'] = json.loads(row.attachment_refs_json)
+        else:
+            result['attachment_refs'] = []
+
+        return result
+
+    def _transcript_item_to_provider_message(
+        self,
+        item: dict[str, typing.Any],
+    ) -> provider_message.Message | None:
+        """Convert one Transcript API item into a provider Message."""
+        if item.get('item_type') != 'message':
+            return None
+
+        role = item.get('role')
+        if role not in {'user', 'assistant'}:
+            return None
+
+        content_json = item.get('content_json')
+        if isinstance(content_json, dict):
+            message_data = dict(content_json)
+            message_data['role'] = role
+            try:
+                return provider_message.Message.model_validate(message_data)
+            except Exception:
+                pass
+
+        content = item.get('content')
+        if content is None:
+            return None
+        return provider_message.Message(role=role, content=content)

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

@@ -7,7 +7,6 @@ from langbot_plugin.api.entities.builtin.provider import message as provider_mes
 
 from ....core import app
 from ....entity.persistence import model as persistence_model
-from ....entity.persistence import pipeline as persistence_pipeline
 from ....provider.modelmgr import requester as model_requester
 
 
@@ -151,23 +150,9 @@ class LLMModelsService:
         self.ap.model_mgr.llm_models.append(runtime_llm_model)
 
         if auto_set_to_default_pipeline:
-            # set the default pipeline model to this model
-            result = await self.ap.persistence_mgr.execute_async(
-                sqlalchemy.select(persistence_pipeline.LegacyPipeline).where(
-                    persistence_pipeline.LegacyPipeline.is_default == True
-                )
-            )
-            pipeline = result.first()
-            if pipeline is not None:
-                model_config = pipeline.config.get('ai', {}).get('local-agent', {}).get('model', {})
-                if not model_config.get('primary', ''):
-                    pipeline_config = pipeline.config
-                    pipeline_config['ai']['local-agent']['model'] = {
-                        'primary': model_data['uuid'],
-                        'fallbacks': [],
-                    }
-                    pipeline_data = {'config': pipeline_config}
-                    await self.ap.pipeline_service.update_pipeline(pipeline.uuid, pipeline_data)
+            default_config_service = getattr(self.ap, 'agent_runner_default_config_service', None)
+            if default_config_service is not None:
+                await default_config_service.auto_set_default_pipeline_llm_model(model_data['uuid'])
 
         return model_data['uuid']
 

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

@@ -3,6 +3,7 @@ from __future__ import annotations
 import uuid
 import json
 import sqlalchemy
+import typing
 
 from ....core import app
 from ....entity.persistence import pipeline as persistence_pipeline
@@ -13,7 +14,6 @@ default_stage_order = [
     'BanSessionCheckStage',  # 封禁会话检查
     'PreContentFilterStage',  # 内容过滤前置阶段
     'PreProcessor',  # 预处理器
-    'ConversationMessageTruncator',  # 会话消息截断器
     'RequireRateLimitOccupancy',  # 请求速率限制占用
     'MessageProcessor',  # 处理器
     'ReleaseRateLimitOccupancy',  # 释放速率限制占用
@@ -30,11 +30,100 @@ class PipelineService:
     def __init__(self, ap: app.Application) -> None:
         self.ap = ap
 
+    def _get_default_values_from_schema(self, config_schema: list[dict[str, typing.Any]]) -> dict[str, typing.Any]:
+        """Build runner config defaults from a DynamicForm schema."""
+        defaults: dict[str, typing.Any] = {}
+        for item in config_schema:
+            name = item.get('name')
+            if not name:
+                continue
+            if 'default' in item:
+                defaults[name] = item['default']
+        return defaults
+
+    async def get_default_pipeline_config(self) -> dict[str, typing.Any]:
+        """Get the default pipeline config, rendering runner defaults from installed plugins."""
+        from ....utils import paths as path_utils
+
+        template_path = path_utils.get_resource_path('templates/default-pipeline-config.json')
+        with open(template_path, 'r', encoding='utf-8') as f:
+            config = json.load(f)
+
+        agent_runner_registry = getattr(self.ap, 'agent_runner_registry', None)
+        if agent_runner_registry is None:
+            return config
+
+        try:
+            runners = await agent_runner_registry.list_runners(bound_plugins=None)
+        except Exception as e:
+            logger = getattr(self.ap, 'logger', None)
+            if logger:
+                logger.warning(f'Failed to load plugin agent runners for default pipeline config: {e}')
+            return config
+
+        if not runners:
+            return config
+
+        selected_runner = runners[0]
+        ai_config = config.setdefault('ai', {})
+        runner_config = ai_config.setdefault('runner', {})
+        runner_config['id'] = selected_runner.id
+        runner_config.setdefault('expire-time', 0)
+
+        ai_config['runner_config'] = {
+            selected_runner.id: self._get_default_values_from_schema(selected_runner.config_schema),
+        }
+
+        return config
+
     async def get_pipeline_metadata(self) -> list[dict]:
+        """Get pipeline metadata with dynamically loaded plugin runners from registry"""
+        import copy
+
+        # Deep copy AI metadata to avoid modifying the original
+        ai_metadata = copy.deepcopy(self.ap.pipeline_config_meta_ai)
+
+        # Find the runner stage
+        runner_stage = None
+        for stage in ai_metadata.get('stages', []):
+            if stage.get('name') == 'runner':
+                runner_stage = stage
+                break
+
+        if runner_stage:
+            # Find the runner select config (now uses 'id' field)
+            for config_item in runner_stage.get('config', []):
+                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()
+
+                        # Replace options entirely with registry options
+                        # Only installed/available runners should be shown
+                        config_item['options'] = runner_options
+
+                        # Use the registry order as the default order. If no runner is available, leave
+                        # the default unset so the UI can recommend installing an AgentRunner plugin.
+                        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:
+                            # 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}')
+
         return [
             self.ap.pipeline_config_meta_trigger,
             self.ap.pipeline_config_meta_safety,
-            self.ap.pipeline_config_meta_ai,
+            ai_metadata,
             self.ap.pipeline_config_meta_output,
         ]
 
@@ -74,8 +163,6 @@ class PipelineService:
         return self.ap.persistence_mgr.serialize_model(persistence_pipeline.LegacyPipeline, pipeline)
 
     async def create_pipeline(self, pipeline_data: dict, default: bool = False) -> str:
-        from ....utils import paths as path_utils
-
         # Check limitation
         limitation = self.ap.instance_config.data.get('system', {}).get('limitation', {})
         max_pipelines = limitation.get('max_pipelines', -1)
@@ -89,9 +176,7 @@ class PipelineService:
         pipeline_data['stages'] = default_stage_order.copy()
         pipeline_data['is_default'] = default
 
-        template_path = path_utils.get_resource_path('templates/default-pipeline-config.json')
-        with open(template_path, 'r', encoding='utf-8') as f:
-            pipeline_data['config'] = json.load(f)
+        pipeline_data['config'] = await self.get_default_pipeline_config()
 
         # Ensure extensions_preferences is set with enable_all_plugins and enable_all_mcp_servers=True by default
         if 'extensions_preferences' not in pipeline_data:
@@ -113,10 +198,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/box/service.py

@@ -237,12 +237,18 @@ class BoxService:
         if forced_template:
             template = forced_template
         else:
-            template = (
-                (query.pipeline_config or {})
-                .get('ai', {})
-                .get('local-agent', {})
-                .get('box-session-id-template', '{launcher_type}_{launcher_id}')
+            template = '{launcher_type}_{launcher_id}'
+            pipeline_config = query.pipeline_config or {}
+            ai_config = pipeline_config.get('ai', {}) if isinstance(pipeline_config, dict) else {}
+            runner_selector = ai_config.get('runner', {}) if isinstance(ai_config, dict) else {}
+            runner_id = runner_selector.get('id') if isinstance(runner_selector, dict) else None
+            runner_configs = ai_config.get('runner_config', {}) if isinstance(ai_config, dict) else {}
+            runner_config = runner_configs.get(runner_id, {}) if isinstance(runner_configs, dict) else {}
+            configured_template = (
+                runner_config.get('box-session-id-template') if isinstance(runner_config, dict) else None
             )
+            if isinstance(configured_template, str) and configured_template:
+                template = configured_template
         variables = dict(query.variables or {})
         launcher_type = getattr(query, 'launcher_type', None)
         if hasattr(launcher_type, 'value'):

src/langbot/pkg/core/app.py

@@ -4,6 +4,7 @@ import logging
 import asyncio
 import traceback
 import os
+from typing import TYPE_CHECKING
 
 from ..platform import botmgr as im_mgr
 from ..platform.webhook_pusher import WebhookPusher
@@ -46,6 +47,9 @@ from ..telemetry import telemetry as telemetry_module
 from ..survey import manager as survey_module
 from ..skill import manager as skill_mgr
 
+if TYPE_CHECKING:
+    from ..agent.runner import AgentRunnerRegistry, AgentRunOrchestrator, AgentRunnerDefaultConfigService
+
 
 class Application:
     """Runtime application object and context"""
@@ -165,6 +169,13 @@ class Application:
 
     maintenance_service: maintenance_service.MaintenanceService = None
 
+    # Agent runner subsystem
+    agent_runner_registry: AgentRunnerRegistry = None
+
+    agent_runner_default_config_service: AgentRunnerDefaultConfigService = None
+
+    agent_run_orchestrator: AgentRunOrchestrator = None
+
     def __init__(self):
         pass
 

src/langbot/pkg/core/stages/build_app.py

@@ -39,6 +39,7 @@ from ...vector import mgr as vectordb_mgr
 from .. import taskmgr
 from ...telemetry import telemetry as telemetry_module
 from ...survey import manager as survey_module
+from ...agent.runner import AgentRunnerRegistry, AgentRunOrchestrator, AgentRunnerDefaultConfigService
 
 
 @stage.stage_class('BuildAppStage')
@@ -194,5 +195,15 @@ class BuildAppStage(stage.BootingStage):
         await plugin_connector_inst.initialize()
         ap.plugin_connector = plugin_connector_inst
 
+        # Initialize agent runner subsystem
+        agent_runner_registry_inst = AgentRunnerRegistry(ap)
+        ap.agent_runner_registry = agent_runner_registry_inst
+
+        agent_runner_default_config_service_inst = AgentRunnerDefaultConfigService(ap)
+        ap.agent_runner_default_config_service = agent_runner_default_config_service_inst
+
+        agent_run_orchestrator_inst = AgentRunOrchestrator(ap, agent_runner_registry_inst)
+        ap.agent_run_orchestrator = agent_run_orchestrator_inst
+
         ctrl = controller.Controller(ap)
         ap.ctrl = ctrl

src/langbot/pkg/entity/persistence/agent_run.py

@@ -0,0 +1,200 @@
+"""Agent run ledger persistence entities."""
+
+from __future__ import annotations
+
+import datetime
+
+import sqlalchemy
+
+from .base import Base
+
+
+class AgentRun(Base):
+    """AgentRun stores Host-owned execution lifecycle facts."""
+
+    __tablename__ = 'agent_run'
+
+    id = sqlalchemy.Column(sqlalchemy.Integer, primary_key=True, autoincrement=True)
+    """Auto-increment ID for pagination."""
+
+    run_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=False, unique=True, index=True)
+    """Unique AgentRunner run identifier."""
+
+    event_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=True, index=True)
+    """Input event that triggered this run."""
+
+    agent_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=True)
+    """Future Host-owned agent identifier."""
+
+    binding_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=True, index=True)
+    """Binding that selected this runner."""
+
+    runner_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=False, index=True)
+    """Runner descriptor ID."""
+
+    conversation_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=True, index=True)
+    """Conversation this run belongs to."""
+
+    thread_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=True)
+    """Thread this run belongs to."""
+
+    workspace_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=True)
+    """Workspace this run belongs to."""
+
+    bot_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=True, index=True)
+    """Bot UUID this run belongs to."""
+
+    status = sqlalchemy.Column(sqlalchemy.String(50), nullable=False, index=True)
+    """Run lifecycle status."""
+
+    status_reason = sqlalchemy.Column(sqlalchemy.Text, nullable=True)
+    """Human-readable terminal or current status reason."""
+
+    queue_name = sqlalchemy.Column(sqlalchemy.String(255), nullable=True, index=True)
+    """Host queue name this run is waiting in."""
+
+    priority = sqlalchemy.Column(sqlalchemy.Integer, nullable=False, default=0)
+    """Higher values are claimed before lower values within a queue."""
+
+    requested_runtime_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=True, index=True)
+    """Specific runtime requested by the producer, if any."""
+
+    claimed_by_runtime_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=True, index=True)
+    """Runtime that currently owns the claim lease."""
+
+    claim_token = sqlalchemy.Column(sqlalchemy.String(255), nullable=True, index=True)
+    """Opaque token required to renew or release the current claim."""
+
+    claim_lease_expires_at = sqlalchemy.Column(sqlalchemy.DateTime, nullable=True, index=True)
+    """When the current claim lease expires."""
+
+    dispatch_attempts = sqlalchemy.Column(sqlalchemy.Integer, nullable=False, default=0)
+    """Number of times this run has been claimed for dispatch."""
+
+    last_claimed_at = sqlalchemy.Column(sqlalchemy.DateTime, nullable=True)
+    """When this run was last claimed."""
+
+    created_at = sqlalchemy.Column(sqlalchemy.DateTime, nullable=False, default=datetime.datetime.utcnow)
+    """When the run record was created."""
+
+    started_at = sqlalchemy.Column(sqlalchemy.DateTime, nullable=True)
+    """When execution started."""
+
+    finished_at = sqlalchemy.Column(sqlalchemy.DateTime, nullable=True)
+    """When execution reached a terminal status."""
+
+    updated_at = sqlalchemy.Column(
+        sqlalchemy.DateTime, nullable=False, default=datetime.datetime.utcnow, onupdate=datetime.datetime.utcnow
+    )
+    """When the run record was last updated."""
+
+    deadline_at = sqlalchemy.Column(sqlalchemy.DateTime, nullable=True)
+    """Execution deadline if one was assigned."""
+
+    cancel_requested_at = sqlalchemy.Column(sqlalchemy.DateTime, nullable=True)
+    """When cancellation was requested."""
+
+    usage_json = sqlalchemy.Column(sqlalchemy.Text, nullable=True)
+    """Final or latest aggregate token usage JSON."""
+
+    cost_json = sqlalchemy.Column(sqlalchemy.Text, nullable=True)
+    """Host-calculated cost JSON, if available."""
+
+    authorization_json = sqlalchemy.Column(sqlalchemy.Text, nullable=True)
+    """Run-scoped authorization snapshot JSON."""
+
+    metadata_json = sqlalchemy.Column(sqlalchemy.Text, nullable=True)
+    """Additional metadata JSON."""
+
+    __table_args__ = (
+        sqlalchemy.Index(
+            'ix_agent_run_scope_status', 'bot_id', 'workspace_id', 'conversation_id', 'thread_id', 'status'
+        ),
+        sqlalchemy.Index('ix_agent_run_runner_status', 'runner_id', 'status'),
+        sqlalchemy.Index('ix_agent_run_queue_claim', 'queue_name', 'status', 'priority', 'id'),
+    )
+
+
+class AgentRuntime(Base):
+    """AgentRuntime stores Host-owned runtime heartbeat registry facts."""
+
+    __tablename__ = 'agent_runtime'
+
+    id = sqlalchemy.Column(sqlalchemy.Integer, primary_key=True, autoincrement=True)
+    """Auto-increment ID."""
+
+    runtime_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=False, unique=True, index=True)
+    """Unique runtime or daemon identifier."""
+
+    status = sqlalchemy.Column(sqlalchemy.String(50), nullable=False, index=True)
+    """Runtime lifecycle status."""
+
+    display_name = sqlalchemy.Column(sqlalchemy.String(255), nullable=True)
+    """Human-readable runtime display name."""
+
+    endpoint = sqlalchemy.Column(sqlalchemy.String(1024), nullable=True)
+    """Runtime endpoint, if it exposes one."""
+
+    version = sqlalchemy.Column(sqlalchemy.String(255), nullable=True)
+    """Runtime version string."""
+
+    capabilities_json = sqlalchemy.Column(sqlalchemy.Text, nullable=True)
+    """Runtime capabilities JSON."""
+
+    labels_json = sqlalchemy.Column(sqlalchemy.Text, nullable=True)
+    """Runtime labels JSON."""
+
+    metadata_json = sqlalchemy.Column(sqlalchemy.Text, nullable=True)
+    """Additional metadata JSON."""
+
+    last_heartbeat_at = sqlalchemy.Column(sqlalchemy.DateTime, nullable=True, index=True)
+    """When the runtime last sent a heartbeat."""
+
+    heartbeat_deadline_at = sqlalchemy.Column(sqlalchemy.DateTime, nullable=True, index=True)
+    """When the runtime should be considered stale."""
+
+    created_at = sqlalchemy.Column(sqlalchemy.DateTime, nullable=False, default=datetime.datetime.utcnow)
+    """When the runtime record was created."""
+
+    updated_at = sqlalchemy.Column(
+        sqlalchemy.DateTime, nullable=False, default=datetime.datetime.utcnow, onupdate=datetime.datetime.utcnow
+    )
+    """When the runtime record was last updated."""
+
+
+class AgentRunEvent(Base):
+    """AgentRunEvent stores one result event emitted by a run."""
+
+    __tablename__ = 'agent_run_event'
+
+    id = sqlalchemy.Column(sqlalchemy.Integer, primary_key=True, autoincrement=True)
+    """Auto-increment ID."""
+
+    run_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=False, index=True)
+    """Run that produced this event."""
+
+    sequence = sqlalchemy.Column(sqlalchemy.Integer, nullable=False)
+    """Monotonic sequence inside the run."""
+
+    type = sqlalchemy.Column(sqlalchemy.String(100), nullable=False, index=True)
+    """Result event type."""
+
+    data_json = sqlalchemy.Column(sqlalchemy.Text, nullable=True)
+    """Result event payload JSON."""
+
+    usage_json = sqlalchemy.Column(sqlalchemy.Text, nullable=True)
+    """Token usage JSON for this event, if provided."""
+
+    created_at = sqlalchemy.Column(sqlalchemy.DateTime, nullable=False, default=datetime.datetime.utcnow)
+    """When this event was persisted."""
+
+    source = sqlalchemy.Column(sqlalchemy.String(50), nullable=True)
+    """Source that appended the event."""
+
+    metadata_json = sqlalchemy.Column(sqlalchemy.Text, nullable=True)
+    """Additional metadata JSON."""
+
+    __table_args__ = (
+        sqlalchemy.UniqueConstraint('run_id', 'sequence', name='uq_agent_run_event_run_sequence'),
+        sqlalchemy.Index('ix_agent_run_event_run_sequence', 'run_id', 'sequence'),
+    )

src/langbot/pkg/entity/persistence/agent_runner_state.py

@@ -0,0 +1,88 @@
+"""Agent runner state persistence entity for host-owned state."""
+from __future__ import annotations
+
+import sqlalchemy
+import datetime
+
+from .base import Base
+
+
+class AgentRunnerState(Base):
+    """AgentRunnerState stores host-owned state for AgentRunner protocol.
+
+    State is:
+    - Host-owned: Managed by LangBot, not by plugin instances
+    - Scope-isolated: Separated by runner_id + binding_identity + scope
+    - Policy-enforced: Controlled by StatePolicy (enable_state, state_scopes)
+
+    Scope key design:
+    - conversation: runner_id + binding_id + conversation_id [+ thread_id]
+    - actor: runner_id + binding_id + actor_type + actor_id
+    - subject: runner_id + binding_id + subject_type + subject_id
+    - runner: runner_id + binding_id
+
+    This table is the production store for AgentRunner state.
+    """
+
+    __tablename__ = 'agent_runner_state'
+
+    id = sqlalchemy.Column(sqlalchemy.Integer, primary_key=True, autoincrement=True)
+    """Auto-increment ID for sequencing."""
+
+    # Identity
+    runner_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=False, index=True)
+    """Runner descriptor ID (plugin:author/name/runner)."""
+
+    binding_identity = sqlalchemy.Column(sqlalchemy.String(255), nullable=False, index=True)
+    """Binding identity for isolation (binding_id or scope_type:scope_id)."""
+
+    scope = sqlalchemy.Column(sqlalchemy.String(50), nullable=False, index=True)
+    """State scope: 'conversation', 'actor', 'subject', or 'runner'."""
+
+    scope_key = sqlalchemy.Column(sqlalchemy.String(512), nullable=False)
+    """Full scope key for unique lookup (includes all identity parts)."""
+
+    state_key = sqlalchemy.Column(sqlalchemy.String(255), nullable=False)
+    """State key within scope (should use namespace prefix like external.*)."""
+
+    value_json = sqlalchemy.Column(sqlalchemy.Text, nullable=True)
+    """State value as JSON string (size-limited by host)."""
+
+    # Context fields for querying/filtering
+    bot_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=True, index=True)
+    """Bot UUID if applicable."""
+
+    workspace_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=True)
+    """Workspace ID for multi-tenant."""
+
+    conversation_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=True, index=True)
+    """Conversation ID for conversation scope."""
+
+    thread_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=True)
+    """Thread ID for thread-scoped conversation state."""
+
+    actor_type = sqlalchemy.Column(sqlalchemy.String(50), nullable=True)
+    """Actor type for actor scope."""
+
+    actor_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=True, index=True)
+    """Actor ID for actor scope."""
+
+    subject_type = sqlalchemy.Column(sqlalchemy.String(50), nullable=True)
+    """Subject type for subject scope."""
+
+    subject_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=True)
+    """Subject ID for subject scope."""
+
+    # Lifecycle
+    created_at = sqlalchemy.Column(sqlalchemy.DateTime, nullable=False, default=datetime.datetime.utcnow)
+    """When this state entry was created."""
+
+    updated_at = sqlalchemy.Column(sqlalchemy.DateTime, nullable=False, default=datetime.datetime.utcnow, onupdate=datetime.datetime.utcnow)
+    """When this state entry was last updated."""
+
+    # Unique constraint: scope_key + state_key
+    __table_args__ = (
+        sqlalchemy.UniqueConstraint('scope_key', 'state_key', name='uq_agent_runner_state_scope_key_state_key'),
+        sqlalchemy.Index('ix_agent_runner_state_runner_binding', 'runner_id', 'binding_identity'),
+        sqlalchemy.Index('ix_agent_runner_state_scope_key_lookup', 'scope_key'),
+    )

src/langbot/pkg/entity/persistence/event_log.py

@@ -0,0 +1,85 @@
+"""EventLog persistence entity for storing auditable event facts."""
+from __future__ import annotations
+
+import sqlalchemy
+import datetime
+
+from .base import Base
+
+
+class EventLog(Base):
+    """EventLog stores auditable event records for AgentRunner.
+
+    This is the fact source for events - messages, tool calls, system events, etc.
+    Large payloads are stored separately; this table stores references and
+    summaries.
+    """
+
+    __tablename__ = 'event_log'
+
+    id = sqlalchemy.Column(sqlalchemy.Integer, primary_key=True, autoincrement=True)
+    """Auto-increment ID for sequencing."""
+
+    event_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=False, unique=True, index=True)
+    """Unique event identifier."""
+
+    event_type = sqlalchemy.Column(sqlalchemy.String(100), nullable=False, index=True)
+    """Event type (message.received, tool.call.started, etc.)."""
+
+    event_time = sqlalchemy.Column(sqlalchemy.DateTime, nullable=True)
+    """When the event occurred."""
+
+    source = sqlalchemy.Column(sqlalchemy.String(50), nullable=False)
+    """Event source (platform, webui, api, scheduler, system, pipeline_adapter)."""
+
+    bot_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=True, index=True)
+    """Bot UUID that handled this event."""
+
+    workspace_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=True)
+    """Workspace ID for multi-tenant deployments."""
+
+    conversation_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=True, index=True)
+    """Conversation ID this event belongs to."""
+
+    thread_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=True)
+    """Thread ID if platform supports threads."""
+
+    # Actor information
+    actor_type = sqlalchemy.Column(sqlalchemy.String(50), nullable=True)
+    """Actor type (user, system, runner)."""
+
+    actor_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=True)
+    """Actor identifier."""
+
+    actor_name = sqlalchemy.Column(sqlalchemy.String(255), nullable=True)
+    """Actor display name."""
+
+    # Subject information
+    subject_type = sqlalchemy.Column(sqlalchemy.String(50), nullable=True)
+    """Subject type (message, tool_call, attachment, etc.)."""
+
+    subject_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=True)
+    """Subject identifier."""
+
+    # Input information
+    input_summary = sqlalchemy.Column(sqlalchemy.Text, nullable=True)
+    """Brief summary of input (truncated text, max 1000 chars)."""
+
+    input_json = sqlalchemy.Column(sqlalchemy.Text, nullable=True)
+    """Full input JSON if reasonably sized (AgentInput as JSON string)."""
+
+    # Raw event reference
+    raw_ref = sqlalchemy.Column(sqlalchemy.String(255), nullable=True)
+    """Reference to raw event payload stored outside the inline event row."""
+
+    run_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=True, index=True)
+    """Run ID that processed this event."""
+
+    runner_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=True)
+    """Runner ID that processed this event."""
+
+    created_at = sqlalchemy.Column(sqlalchemy.DateTime, nullable=False, default=datetime.datetime.utcnow)
+    """When this record was created."""
+
+    metadata_json = sqlalchemy.Column(sqlalchemy.Text, nullable=True)
+    """Additional metadata as JSON string."""

src/langbot/pkg/entity/persistence/transcript.py

@@ -0,0 +1,79 @@
+"""Transcript persistence entity for conversation history projection."""
+from __future__ import annotations
+
+import sqlalchemy
+import datetime
+
+from .base import Base
+
+
+class Transcript(Base):
+    """Transcript stores conversation-oriented message projection for history API.
+
+    This is a projection of EventLog, optimized for agent history retrieval.
+    It includes message content and attachment refs, but not raw platform payloads.
+    """
+
+    __tablename__ = 'transcript'
+
+    id = sqlalchemy.Column(sqlalchemy.Integer, primary_key=True, autoincrement=True)
+    """Auto-increment ID for sequencing."""
+
+    transcript_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=False, unique=True, index=True)
+    """Unique transcript item identifier."""
+
+    event_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=False, index=True)
+    """Reference to the source event in EventLog."""
+
+    bot_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=True, index=True)
+    """Bot UUID this item belongs to."""
+
+    workspace_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=True)
+    """Workspace this item belongs to."""
+
+    conversation_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=False, index=True)
+    """Conversation this item belongs to."""
+
+    thread_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=True)
+    """Thread ID if platform supports threads."""
+
+    role = sqlalchemy.Column(sqlalchemy.String(50), nullable=False)
+    """Message role: 'user', 'assistant', 'system', or 'tool'."""
+
+    item_type = sqlalchemy.Column(sqlalchemy.String(50), nullable=False, default='message')
+    """Item type: 'message', 'tool_call', 'tool_result', 'system'."""
+
+    # Content
+    content = sqlalchemy.Column(sqlalchemy.Text, nullable=True)
+    """Text content summary (may be truncated for large messages, max 4000 chars)."""
+
+    content_json = sqlalchemy.Column(sqlalchemy.Text, nullable=True)
+    """Full structured content as JSON string (Message model dump)."""
+
+    # Attachment references
+    attachment_refs_json = sqlalchemy.Column(sqlalchemy.Text, nullable=True)
+    """Attachment references as JSON string."""
+
+    # Sequence for cursor-based pagination
+    seq = sqlalchemy.Column(sqlalchemy.Integer, nullable=False)
+    """Monotonic cursor sequence for pagination."""
+
+    # Context
+    run_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=True, index=True)
+    """Run ID that generated this item (for assistant messages)."""
+
+    runner_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=True)
+    """Runner ID that generated this item."""
+
+    created_at = sqlalchemy.Column(sqlalchemy.DateTime, nullable=False, default=datetime.datetime.utcnow)
+    """When this item was created."""
+
+    metadata_json = sqlalchemy.Column(sqlalchemy.Text, nullable=True)
+    """Additional metadata as JSON string (sender_id, platform, etc.)."""
+
+    # Indexes
+    __table_args__ = (
+        sqlalchemy.Index('ix_transcript_conversation_seq', 'conversation_id', 'seq'),
+        sqlalchemy.Index('ix_transcript_conversation_created', 'conversation_id', 'created_at'),
+        sqlalchemy.Index('ix_transcript_scope_seq', 'bot_id', 'workspace_id', 'conversation_id', 'thread_id', 'seq'),
+    )

src/langbot/pkg/persistence/alembic/env.py

@@ -13,6 +13,28 @@ from sqlalchemy.engine import Connection
 
 from langbot.pkg.entity.persistence.base import Base
 
+# Import all ORM models so they are registered with Base.metadata
+# This is required for autogenerate to detect model changes
+from langbot.pkg.entity.persistence import (
+    agent_run,  # noqa: F401
+    agent_runner_state,  # noqa: F401
+    apikey,  # noqa: F401
+    bot,  # noqa: F401
+    bstorage,  # noqa: F401
+    event_log,  # noqa: F401
+    mcp,  # noqa: F401
+    metadata,  # noqa: F401
+    model,  # noqa: F401
+    monitoring,  # noqa: F401
+    pipeline,  # noqa: F401
+    plugin,  # noqa: F401
+    rag,  # noqa: F401
+    transcript,  # noqa: F401
+    user,  # noqa: F401
+    vector,  # noqa: F401
+    webhook,  # noqa: F401
+)
+
 target_metadata = Base.metadata
 
 

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

@@ -0,0 +1,88 @@
+"""Normalize AgentRunner config containers
+
+Revision ID: 0005_migrate_runner_config
+Revises: 0005_add_llm_context_length
+Create Date: 2026-05-10
+"""
+
+import json
+import sqlalchemy as sa
+from alembic import op
+
+from langbot.pkg.agent.runner.config_migration import ConfigMigration
+
+revision = '0005_migrate_runner_config'
+down_revision = '0005_add_llm_context_length'
+branch_labels = None
+depends_on = None
+
+def migrate_pipeline_config(config: dict) -> dict:
+    """Migrate persisted pipeline config to the AgentRunner plugin shape."""
+    return ConfigMigration.migrate_pipeline_config(config)
+
+
+def _load_config(config_value):
+    if isinstance(config_value, dict):
+        return config_value
+    if isinstance(config_value, str):
+        return json.loads(config_value)
+    return None
+
+
+def _update_config(conn, table_name: str, pipeline_uuid: str, migrated_config: dict) -> None:
+    """Write JSON config using a dialect-compatible bind."""
+    config_json = json.dumps(migrated_config)
+    if conn.dialect.name == 'postgresql':
+        conn.execute(
+            sa.text(
+                f'UPDATE {table_name} '
+                'SET config = CAST(:config AS JSON) '
+                'WHERE uuid = :uuid'
+            ),
+            {'config': config_json, 'uuid': pipeline_uuid},
+        )
+        return
+
+    conn.execute(
+        sa.text(f'UPDATE {table_name} SET config = :config WHERE uuid = :uuid'),
+        {'config': config_json, 'uuid': pipeline_uuid},
+    )
+
+
+def upgrade() -> None:
+    """Normalize existing pipeline config containers."""
+    conn = op.get_bind()
+    inspector = sa.inspect(conn)
+
+    table_name = 'legacy_pipelines'
+
+    # Check if pipeline table exists (may not exist in fresh install)
+    if table_name not in inspector.get_table_names():
+        return
+
+    # Get all pipelines
+    result = conn.execute(sa.text(f'SELECT uuid, config FROM {table_name}'))
+    pipelines = result.fetchall()
+
+    for pipeline_uuid, config_json in pipelines:
+        if not config_json:
+            continue
+
+        try:
+            config = _load_config(config_json)
+            if not isinstance(config, dict):
+                continue
+            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):
+                _update_config(conn, table_name, pipeline_uuid, migrated_config)
+        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/persistence/alembic/versions/58846a8d7a81_add_event_log_and_transcript_tables.py

@@ -0,0 +1,148 @@
+"""add_event_log_and_transcript_tables
+
+Revision ID: 58846a8d7a81
+Revises: 0005_migrate_runner_config
+Create Date: 2026-05-23 15:41:47.030841
+"""
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers
+revision = '58846a8d7a81'
+down_revision = '0005_migrate_runner_config'
+branch_labels = None
+depends_on = None
+
+
+def _table_exists(table_name: str) -> bool:
+    return table_name in sa.inspect(op.get_bind()).get_table_names()
+
+
+def _index_exists(table_name: str, index_name: str) -> bool:
+    return index_name in {index['name'] for index in sa.inspect(op.get_bind()).get_indexes(table_name)}
+
+
+def _column_exists(table_name: str, column_name: str) -> bool:
+    return column_name in {column['name'] for column in sa.inspect(op.get_bind()).get_columns(table_name)}
+
+
+def _add_column_if_missing(table_name: str, column: sa.Column) -> None:
+    if not _table_exists(table_name) or _column_exists(table_name, column.name):
+        return
+    with op.batch_alter_table(table_name, schema=None) as batch_op:
+        batch_op.add_column(column)
+
+
+def _create_index_if_missing(table_name: str, index_name: str, columns: list[str], *, unique: bool = False) -> None:
+    if not _table_exists(table_name) or _index_exists(table_name, index_name):
+        return
+    with op.batch_alter_table(table_name, schema=None) as batch_op:
+        batch_op.create_index(index_name, columns, unique=unique)
+
+
+def _drop_index_if_exists(table_name: str, index_name: str) -> None:
+    if not _table_exists(table_name) or not _index_exists(table_name, index_name):
+        return
+    with op.batch_alter_table(table_name, schema=None) as batch_op:
+        batch_op.drop_index(index_name)
+
+
+def upgrade() -> None:
+    # Create event_log table
+    if not _table_exists('event_log'):
+        op.create_table(
+            'event_log',
+            sa.Column('id', sa.Integer(), primary_key=True, autoincrement=True),
+            sa.Column('event_id', sa.String(255), nullable=False, unique=True),
+            sa.Column('event_type', sa.String(100), nullable=False),
+            sa.Column('event_time', sa.DateTime(), nullable=True),
+            sa.Column('source', sa.String(50), nullable=False),
+            sa.Column('bot_id', sa.String(255), nullable=True),
+            sa.Column('workspace_id', sa.String(255), nullable=True),
+            sa.Column('conversation_id', sa.String(255), nullable=True),
+            sa.Column('thread_id', sa.String(255), nullable=True),
+            sa.Column('actor_type', sa.String(50), nullable=True),
+            sa.Column('actor_id', sa.String(255), nullable=True),
+            sa.Column('actor_name', sa.String(255), nullable=True),
+            sa.Column('subject_type', sa.String(50), nullable=True),
+            sa.Column('subject_id', sa.String(255), nullable=True),
+            sa.Column('input_summary', sa.Text(), nullable=True),
+            sa.Column('input_json', sa.Text(), nullable=True),
+            sa.Column('raw_ref', sa.String(255), nullable=True),
+            sa.Column('run_id', sa.String(255), nullable=True),
+            sa.Column('runner_id', sa.String(255), nullable=True),
+            sa.Column('created_at', sa.DateTime(), nullable=False, server_default=sa.text('(CURRENT_TIMESTAMP)')),
+            sa.Column('metadata_json', sa.Text(), nullable=True),
+        )
+
+    # Create indexes for event_log
+    _create_index_if_missing('event_log', 'ix_event_log_event_id', ['event_id'], unique=True)
+    _create_index_if_missing('event_log', 'ix_event_log_event_type', ['event_type'])
+    _create_index_if_missing('event_log', 'ix_event_log_bot_id', ['bot_id'])
+    _create_index_if_missing('event_log', 'ix_event_log_conversation_id', ['conversation_id'])
+    _create_index_if_missing('event_log', 'ix_event_log_run_id', ['run_id'])
+
+    # Create transcript table
+    if not _table_exists('transcript'):
+        op.create_table(
+            'transcript',
+            sa.Column('id', sa.Integer(), primary_key=True, autoincrement=True),
+            sa.Column('transcript_id', sa.String(255), nullable=False, unique=True),
+            sa.Column('event_id', sa.String(255), nullable=False),
+            sa.Column('bot_id', sa.String(255), nullable=True),
+            sa.Column('workspace_id', sa.String(255), nullable=True),
+            sa.Column('conversation_id', sa.String(255), nullable=False),
+            sa.Column('thread_id', sa.String(255), nullable=True),
+            sa.Column('role', sa.String(50), nullable=False),
+            sa.Column('item_type', sa.String(50), nullable=False, server_default='message'),
+            sa.Column('content', sa.Text(), nullable=True),
+            sa.Column('content_json', sa.Text(), nullable=True),
+            sa.Column('attachment_refs_json', sa.Text(), nullable=True),
+            sa.Column('seq', sa.Integer(), nullable=False),
+            sa.Column('run_id', sa.String(255), nullable=True),
+            sa.Column('runner_id', sa.String(255), nullable=True),
+            sa.Column('created_at', sa.DateTime(), nullable=False, server_default=sa.text('(CURRENT_TIMESTAMP)')),
+            sa.Column('metadata_json', sa.Text(), nullable=True),
+        )
+    else:
+        _add_column_if_missing('transcript', sa.Column('bot_id', sa.String(255), nullable=True))
+        _add_column_if_missing('transcript', sa.Column('workspace_id', sa.String(255), nullable=True))
+
+    # Create indexes for transcript
+    _create_index_if_missing('transcript', 'ix_transcript_transcript_id', ['transcript_id'], unique=True)
+    _create_index_if_missing('transcript', 'ix_transcript_event_id', ['event_id'])
+    _create_index_if_missing('transcript', 'ix_transcript_bot_id', ['bot_id'])
+    _create_index_if_missing('transcript', 'ix_transcript_conversation_id', ['conversation_id'])
+    _create_index_if_missing('transcript', 'ix_transcript_conversation_seq', ['conversation_id', 'seq'])
+    _create_index_if_missing('transcript', 'ix_transcript_conversation_created', ['conversation_id', 'created_at'])
+    _create_index_if_missing(
+        'transcript',
+        'ix_transcript_scope_seq',
+        ['bot_id', 'workspace_id', 'conversation_id', 'thread_id', 'seq'],
+    )
+    _create_index_if_missing('transcript', 'ix_transcript_run_id', ['run_id'])
+
+
+def downgrade() -> None:
+    # Drop transcript table
+    _drop_index_if_exists('transcript', 'ix_transcript_run_id')
+    _drop_index_if_exists('transcript', 'ix_transcript_scope_seq')
+    _drop_index_if_exists('transcript', 'ix_transcript_conversation_created')
+    _drop_index_if_exists('transcript', 'ix_transcript_conversation_seq')
+    _drop_index_if_exists('transcript', 'ix_transcript_conversation_id')
+    _drop_index_if_exists('transcript', 'ix_transcript_bot_id')
+    _drop_index_if_exists('transcript', 'ix_transcript_event_id')
+    _drop_index_if_exists('transcript', 'ix_transcript_transcript_id')
+
+    if _table_exists('transcript'):
+        op.drop_table('transcript')
+
+    # Drop event_log table
+    _drop_index_if_exists('event_log', 'ix_event_log_run_id')
+    _drop_index_if_exists('event_log', 'ix_event_log_conversation_id')
+    _drop_index_if_exists('event_log', 'ix_event_log_bot_id')
+    _drop_index_if_exists('event_log', 'ix_event_log_event_type')
+    _drop_index_if_exists('event_log', 'ix_event_log_event_id')
+
+    if _table_exists('event_log'):
+        op.drop_table('event_log')

src/langbot/pkg/persistence/alembic/versions/6dfd3dd7f0c7_add_agent_runner_state_table_for_host_.py

@@ -0,0 +1,94 @@
+# Alembic script.py.mako — template for auto-generated revisions
+"""add agent_runner_state table for host-owned persistent state
+
+Revision ID: 6dfd3dd7f0c7
+Revises: 58846a8d7a81
+Create Date: 2026-05-23 19:49:08.529110
+"""
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers
+revision = '6dfd3dd7f0c7'
+down_revision = '58846a8d7a81'
+branch_labels = None
+depends_on = None
+
+
+def _table_exists(table_name: str) -> bool:
+    return table_name in sa.inspect(op.get_bind()).get_table_names()
+
+
+def _index_exists(table_name: str, index_name: str) -> bool:
+    return index_name in {index['name'] for index in sa.inspect(op.get_bind()).get_indexes(table_name)}
+
+
+def _create_index_if_missing(table_name: str, index_name: str, columns: list[str], *, unique: bool = False) -> None:
+    if not _table_exists(table_name) or _index_exists(table_name, index_name):
+        return
+    with op.batch_alter_table(table_name, schema=None) as batch_op:
+        batch_op.create_index(index_name, columns, unique=unique)
+
+
+def _drop_index_if_exists(table_name: str, index_name: str) -> None:
+    if not _table_exists(table_name) or not _index_exists(table_name, index_name):
+        return
+    with op.batch_alter_table(table_name, schema=None) as batch_op:
+        batch_op.drop_index(index_name)
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    if not _table_exists('agent_runner_state'):
+        op.create_table('agent_runner_state',
+        sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
+        sa.Column('runner_id', sa.String(length=255), nullable=False),
+        sa.Column('binding_identity', sa.String(length=255), nullable=False),
+        sa.Column('scope', sa.String(length=50), nullable=False),
+        sa.Column('scope_key', sa.String(length=512), nullable=False),
+        sa.Column('state_key', sa.String(length=255), nullable=False),
+        sa.Column('value_json', sa.Text(), nullable=True),
+        sa.Column('bot_id', sa.String(length=255), nullable=True),
+        sa.Column('workspace_id', sa.String(length=255), nullable=True),
+        sa.Column('conversation_id', sa.String(length=255), nullable=True),
+        sa.Column('thread_id', sa.String(length=255), nullable=True),
+        sa.Column('actor_type', sa.String(length=50), nullable=True),
+        sa.Column('actor_id', sa.String(length=255), nullable=True),
+        sa.Column('subject_type', sa.String(length=50), nullable=True),
+        sa.Column('subject_id', sa.String(length=255), nullable=True),
+        sa.Column('created_at', sa.DateTime(), nullable=False),
+        sa.Column('updated_at', sa.DateTime(), nullable=False),
+        sa.PrimaryKeyConstraint('id'),
+        sa.UniqueConstraint('scope_key', 'state_key', name='uq_agent_runner_state_scope_key_state_key')
+        )
+    _create_index_if_missing('agent_runner_state', 'ix_agent_runner_state_actor_id', ['actor_id'])
+    _create_index_if_missing('agent_runner_state', 'ix_agent_runner_state_binding_identity', ['binding_identity'])
+    _create_index_if_missing('agent_runner_state', 'ix_agent_runner_state_bot_id', ['bot_id'])
+    _create_index_if_missing('agent_runner_state', 'ix_agent_runner_state_conversation_id', ['conversation_id'])
+    _create_index_if_missing(
+        'agent_runner_state',
+        'ix_agent_runner_state_runner_binding',
+        ['runner_id', 'binding_identity'],
+    )
+    _create_index_if_missing('agent_runner_state', 'ix_agent_runner_state_runner_id', ['runner_id'])
+    _create_index_if_missing('agent_runner_state', 'ix_agent_runner_state_scope', ['scope'])
+    _create_index_if_missing('agent_runner_state', 'ix_agent_runner_state_scope_key_lookup', ['scope_key'])
+
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    _drop_index_if_exists('agent_runner_state', 'ix_agent_runner_state_scope_key_lookup')
+    _drop_index_if_exists('agent_runner_state', 'ix_agent_runner_state_scope')
+    _drop_index_if_exists('agent_runner_state', 'ix_agent_runner_state_runner_id')
+    _drop_index_if_exists('agent_runner_state', 'ix_agent_runner_state_runner_binding')
+    _drop_index_if_exists('agent_runner_state', 'ix_agent_runner_state_conversation_id')
+    _drop_index_if_exists('agent_runner_state', 'ix_agent_runner_state_bot_id')
+    _drop_index_if_exists('agent_runner_state', 'ix_agent_runner_state_binding_identity')
+    _drop_index_if_exists('agent_runner_state', 'ix_agent_runner_state_actor_id')
+
+    if _table_exists('agent_runner_state'):
+        op.drop_table('agent_runner_state')
+    # ### end Alembic commands ###

src/langbot/pkg/persistence/alembic/versions/7b2c1d9e4f30_add_transcript_scope_columns.py

@@ -0,0 +1,78 @@
+"""add transcript scope columns
+
+Revision ID: 7b2c1d9e4f30
+Revises: 6dfd3dd7f0c7
+Create Date: 2026-06-12
+"""
+from alembic import op
+import sqlalchemy as sa
+
+
+revision = '7b2c1d9e4f30'
+down_revision = '6dfd3dd7f0c7'
+branch_labels = None
+depends_on = None
+
+
+def _table_exists(table_name: str) -> bool:
+    return table_name in sa.inspect(op.get_bind()).get_table_names()
+
+
+def _column_exists(table_name: str, column_name: str) -> bool:
+    return column_name in {column['name'] for column in sa.inspect(op.get_bind()).get_columns(table_name)}
+
+
+def _index_exists(table_name: str, index_name: str) -> bool:
+    return index_name in {index['name'] for index in sa.inspect(op.get_bind()).get_indexes(table_name)}
+
+
+def _add_column_if_missing(table_name: str, column: sa.Column) -> None:
+    if not _table_exists(table_name) or _column_exists(table_name, column.name):
+        return
+    with op.batch_alter_table(table_name, schema=None) as batch_op:
+        batch_op.add_column(column)
+
+
+def _create_index_if_missing(table_name: str, index_name: str, columns: list[str]) -> None:
+    if not _table_exists(table_name) or _index_exists(table_name, index_name):
+        return
+    existing_columns = {column['name'] for column in sa.inspect(op.get_bind()).get_columns(table_name)}
+    if not set(columns).issubset(existing_columns):
+        return
+    with op.batch_alter_table(table_name, schema=None) as batch_op:
+        batch_op.create_index(index_name, columns)
+
+
+def _drop_index_if_exists(table_name: str, index_name: str) -> None:
+    if not _table_exists(table_name) or not _index_exists(table_name, index_name):
+        return
+    with op.batch_alter_table(table_name, schema=None) as batch_op:
+        batch_op.drop_index(index_name)
+
+
+def upgrade() -> None:
+    _add_column_if_missing('transcript', sa.Column('bot_id', sa.String(255), nullable=True))
+    _add_column_if_missing('transcript', sa.Column('workspace_id', sa.String(255), nullable=True))
+    _create_index_if_missing('transcript', 'ix_transcript_bot_id', ['bot_id'])
+    _create_index_if_missing(
+        'transcript',
+        'ix_transcript_scope_seq',
+        ['bot_id', 'workspace_id', 'conversation_id', 'thread_id', 'seq'],
+    )
+    _drop_index_if_exists('agent_runner_state', 'ix_agent_runner_state_scope_key')
+    _create_index_if_missing('agent_runner_state', 'ix_agent_runner_state_scope_key_lookup', ['scope_key'])
+
+
+def downgrade() -> None:
+    _drop_index_if_exists('agent_runner_state', 'ix_agent_runner_state_scope_key_lookup')
+    _create_index_if_missing('agent_runner_state', 'ix_agent_runner_state_scope_key', ['scope_key'])
+    _drop_index_if_exists('transcript', 'ix_transcript_scope_seq')
+    _drop_index_if_exists('transcript', 'ix_transcript_bot_id')
+    if not _table_exists('transcript'):
+        return
+    existing_columns = {column['name'] for column in sa.inspect(op.get_bind()).get_columns('transcript')}
+    with op.batch_alter_table('transcript', schema=None) as batch_op:
+        if 'workspace_id' in existing_columns:
+            batch_op.drop_column('workspace_id')
+        if 'bot_id' in existing_columns:
+            batch_op.drop_column('bot_id')

src/langbot/pkg/persistence/alembic/versions/8d3a1f2c4b6e_add_agent_run_ledger.py

@@ -0,0 +1,202 @@
+"""add agent run ledger
+
+Revision ID: 8d3a1f2c4b6e
+Revises: 7b2c1d9e4f30
+Create Date: 2026-06-15
+"""
+
+from alembic import op
+import sqlalchemy as sa
+
+
+revision = '8d3a1f2c4b6e'
+down_revision = '7b2c1d9e4f30'
+branch_labels = None
+depends_on = None
+
+
+def _table_exists(table_name: str) -> bool:
+    return table_name in sa.inspect(op.get_bind()).get_table_names()
+
+
+def _index_exists(table_name: str, index_name: str) -> bool:
+    return index_name in {index['name'] for index in sa.inspect(op.get_bind()).get_indexes(table_name)}
+
+
+def _column_exists(table_name: str, column_name: str) -> bool:
+    if not _table_exists(table_name):
+        return False
+    return column_name in {column['name'] for column in sa.inspect(op.get_bind()).get_columns(table_name)}
+
+
+def _add_column_if_missing(table_name: str, column: sa.Column) -> None:
+    if not _table_exists(table_name) or _column_exists(table_name, column.name):
+        return
+    with op.batch_alter_table(table_name, schema=None) as batch_op:
+        batch_op.add_column(column)
+
+
+def _create_index_if_missing(table_name: str, index_name: str, columns: list[str], *, unique: bool = False) -> None:
+    if not _table_exists(table_name) or _index_exists(table_name, index_name):
+        return
+    existing_columns = {column['name'] for column in sa.inspect(op.get_bind()).get_columns(table_name)}
+    if not set(columns).issubset(existing_columns):
+        return
+    with op.batch_alter_table(table_name, schema=None) as batch_op:
+        batch_op.create_index(index_name, columns, unique=unique)
+
+
+def _drop_index_if_exists(table_name: str, index_name: str) -> None:
+    if not _table_exists(table_name) or not _index_exists(table_name, index_name):
+        return
+    with op.batch_alter_table(table_name, schema=None) as batch_op:
+        batch_op.drop_index(index_name)
+
+
+def upgrade() -> None:
+    if not _table_exists('agent_run'):
+        op.create_table(
+            'agent_run',
+            sa.Column('id', sa.Integer(), primary_key=True, autoincrement=True),
+            sa.Column('run_id', sa.String(255), nullable=False, unique=True),
+            sa.Column('event_id', sa.String(255), nullable=True),
+            sa.Column('agent_id', sa.String(255), nullable=True),
+            sa.Column('binding_id', sa.String(255), nullable=True),
+            sa.Column('runner_id', sa.String(255), nullable=False),
+            sa.Column('conversation_id', sa.String(255), nullable=True),
+            sa.Column('thread_id', sa.String(255), nullable=True),
+            sa.Column('workspace_id', sa.String(255), nullable=True),
+            sa.Column('bot_id', sa.String(255), nullable=True),
+            sa.Column('status', sa.String(50), nullable=False),
+            sa.Column('status_reason', sa.Text(), nullable=True),
+            sa.Column('queue_name', sa.String(255), nullable=True),
+            sa.Column('priority', sa.Integer(), nullable=False, server_default='0'),
+            sa.Column('requested_runtime_id', sa.String(255), nullable=True),
+            sa.Column('claimed_by_runtime_id', sa.String(255), nullable=True),
+            sa.Column('claim_token', sa.String(255), nullable=True),
+            sa.Column('claim_lease_expires_at', sa.DateTime(), nullable=True),
+            sa.Column('dispatch_attempts', sa.Integer(), nullable=False, server_default='0'),
+            sa.Column('last_claimed_at', sa.DateTime(), nullable=True),
+            sa.Column('created_at', sa.DateTime(), nullable=False, server_default=sa.text('(CURRENT_TIMESTAMP)')),
+            sa.Column('started_at', sa.DateTime(), nullable=True),
+            sa.Column('finished_at', sa.DateTime(), nullable=True),
+            sa.Column('updated_at', sa.DateTime(), nullable=False, server_default=sa.text('(CURRENT_TIMESTAMP)')),
+            sa.Column('deadline_at', sa.DateTime(), nullable=True),
+            sa.Column('cancel_requested_at', sa.DateTime(), nullable=True),
+            sa.Column('usage_json', sa.Text(), nullable=True),
+            sa.Column('cost_json', sa.Text(), nullable=True),
+            sa.Column('authorization_json', sa.Text(), nullable=True),
+            sa.Column('metadata_json', sa.Text(), nullable=True),
+        )
+    else:
+        _add_column_if_missing('agent_run', sa.Column('queue_name', sa.String(255), nullable=True))
+        _add_column_if_missing(
+            'agent_run', sa.Column('priority', sa.Integer(), nullable=False, server_default='0')
+        )
+        _add_column_if_missing('agent_run', sa.Column('requested_runtime_id', sa.String(255), nullable=True))
+        _add_column_if_missing('agent_run', sa.Column('claimed_by_runtime_id', sa.String(255), nullable=True))
+        _add_column_if_missing('agent_run', sa.Column('claim_token', sa.String(255), nullable=True))
+        _add_column_if_missing('agent_run', sa.Column('claim_lease_expires_at', sa.DateTime(), nullable=True))
+        _add_column_if_missing(
+            'agent_run', sa.Column('dispatch_attempts', sa.Integer(), nullable=False, server_default='0')
+        )
+        _add_column_if_missing('agent_run', sa.Column('last_claimed_at', sa.DateTime(), nullable=True))
+
+    _create_index_if_missing('agent_run', 'ix_agent_run_run_id', ['run_id'], unique=True)
+    _create_index_if_missing('agent_run', 'ix_agent_run_event_id', ['event_id'])
+    _create_index_if_missing('agent_run', 'ix_agent_run_binding_id', ['binding_id'])
+    _create_index_if_missing('agent_run', 'ix_agent_run_runner_id', ['runner_id'])
+    _create_index_if_missing('agent_run', 'ix_agent_run_conversation_id', ['conversation_id'])
+    _create_index_if_missing('agent_run', 'ix_agent_run_bot_id', ['bot_id'])
+    _create_index_if_missing('agent_run', 'ix_agent_run_status', ['status'])
+    _create_index_if_missing('agent_run', 'ix_agent_run_queue_name', ['queue_name'])
+    _create_index_if_missing('agent_run', 'ix_agent_run_requested_runtime_id', ['requested_runtime_id'])
+    _create_index_if_missing('agent_run', 'ix_agent_run_claimed_by_runtime_id', ['claimed_by_runtime_id'])
+    _create_index_if_missing('agent_run', 'ix_agent_run_claim_token', ['claim_token'])
+    _create_index_if_missing('agent_run', 'ix_agent_run_claim_lease_expires_at', ['claim_lease_expires_at'])
+    _create_index_if_missing(
+        'agent_run',
+        'ix_agent_run_scope_status',
+        ['bot_id', 'workspace_id', 'conversation_id', 'thread_id', 'status'],
+    )
+    _create_index_if_missing('agent_run', 'ix_agent_run_runner_status', ['runner_id', 'status'])
+    _create_index_if_missing('agent_run', 'ix_agent_run_queue_claim', ['queue_name', 'status', 'priority', 'id'])
+
+    if not _table_exists('agent_run_event'):
+        op.create_table(
+            'agent_run_event',
+            sa.Column('id', sa.Integer(), primary_key=True, autoincrement=True),
+            sa.Column('run_id', sa.String(255), nullable=False),
+            sa.Column('sequence', sa.Integer(), nullable=False),
+            sa.Column('type', sa.String(100), nullable=False),
+            sa.Column('data_json', sa.Text(), nullable=True),
+            sa.Column('usage_json', sa.Text(), nullable=True),
+            sa.Column('created_at', sa.DateTime(), nullable=False, server_default=sa.text('(CURRENT_TIMESTAMP)')),
+            sa.Column('source', sa.String(50), nullable=True),
+            sa.Column('metadata_json', sa.Text(), nullable=True),
+            sa.UniqueConstraint('run_id', 'sequence', name='uq_agent_run_event_run_sequence'),
+        )
+
+    _create_index_if_missing('agent_run_event', 'ix_agent_run_event_run_id', ['run_id'])
+    _create_index_if_missing('agent_run_event', 'ix_agent_run_event_type', ['type'])
+    _create_index_if_missing(
+        'agent_run_event',
+        'ix_agent_run_event_run_sequence',
+        ['run_id', 'sequence'],
+    )
+
+    if not _table_exists('agent_runtime'):
+        op.create_table(
+            'agent_runtime',
+            sa.Column('id', sa.Integer(), primary_key=True, autoincrement=True),
+            sa.Column('runtime_id', sa.String(255), nullable=False, unique=True),
+            sa.Column('status', sa.String(50), nullable=False),
+            sa.Column('display_name', sa.String(255), nullable=True),
+            sa.Column('endpoint', sa.String(1024), nullable=True),
+            sa.Column('version', sa.String(255), nullable=True),
+            sa.Column('capabilities_json', sa.Text(), nullable=True),
+            sa.Column('labels_json', sa.Text(), nullable=True),
+            sa.Column('metadata_json', sa.Text(), nullable=True),
+            sa.Column('last_heartbeat_at', sa.DateTime(), nullable=True),
+            sa.Column('heartbeat_deadline_at', sa.DateTime(), nullable=True),
+            sa.Column('created_at', sa.DateTime(), nullable=False, server_default=sa.text('(CURRENT_TIMESTAMP)')),
+            sa.Column('updated_at', sa.DateTime(), nullable=False, server_default=sa.text('(CURRENT_TIMESTAMP)')),
+        )
+
+    _create_index_if_missing('agent_runtime', 'ix_agent_runtime_runtime_id', ['runtime_id'], unique=True)
+    _create_index_if_missing('agent_runtime', 'ix_agent_runtime_status', ['status'])
+    _create_index_if_missing('agent_runtime', 'ix_agent_runtime_last_heartbeat_at', ['last_heartbeat_at'])
+    _create_index_if_missing('agent_runtime', 'ix_agent_runtime_heartbeat_deadline_at', ['heartbeat_deadline_at'])
+
+
+def downgrade() -> None:
+    _drop_index_if_exists('agent_runtime', 'ix_agent_runtime_heartbeat_deadline_at')
+    _drop_index_if_exists('agent_runtime', 'ix_agent_runtime_last_heartbeat_at')
+    _drop_index_if_exists('agent_runtime', 'ix_agent_runtime_status')
+    _drop_index_if_exists('agent_runtime', 'ix_agent_runtime_runtime_id')
+    if _table_exists('agent_runtime'):
+        op.drop_table('agent_runtime')
+
+    _drop_index_if_exists('agent_run_event', 'ix_agent_run_event_run_sequence')
+    _drop_index_if_exists('agent_run_event', 'ix_agent_run_event_type')
+    _drop_index_if_exists('agent_run_event', 'ix_agent_run_event_run_id')
+    if _table_exists('agent_run_event'):
+        op.drop_table('agent_run_event')
+
+    _drop_index_if_exists('agent_run', 'ix_agent_run_queue_claim')
+    _drop_index_if_exists('agent_run', 'ix_agent_run_claim_lease_expires_at')
+    _drop_index_if_exists('agent_run', 'ix_agent_run_claim_token')
+    _drop_index_if_exists('agent_run', 'ix_agent_run_claimed_by_runtime_id')
+    _drop_index_if_exists('agent_run', 'ix_agent_run_requested_runtime_id')
+    _drop_index_if_exists('agent_run', 'ix_agent_run_queue_name')
+    _drop_index_if_exists('agent_run', 'ix_agent_run_runner_status')
+    _drop_index_if_exists('agent_run', 'ix_agent_run_scope_status')
+    _drop_index_if_exists('agent_run', 'ix_agent_run_status')
+    _drop_index_if_exists('agent_run', 'ix_agent_run_bot_id')
+    _drop_index_if_exists('agent_run', 'ix_agent_run_conversation_id')
+    _drop_index_if_exists('agent_run', 'ix_agent_run_runner_id')
+    _drop_index_if_exists('agent_run', 'ix_agent_run_binding_id')
+    _drop_index_if_exists('agent_run', 'ix_agent_run_event_id')
+    _drop_index_if_exists('agent_run', 'ix_agent_run_run_id')
+    if _table_exists('agent_run'):
+        op.drop_table('agent_run')

src/langbot/pkg/persistence/migrations/dbm001_migrate_v3_config.py

@@ -11,6 +11,7 @@ from ...entity.persistence import (
     pipeline as persistence_pipeline,
     bot as persistence_bot,
 )
+from ...agent.runner.config_migration import LEGACY_RUNNER_ID_MAP
 
 
 @migration.migration_class(1)
@@ -114,21 +115,28 @@ class DBMigrateV3Config(migration.DBMigration):
             pipeline_config = default_pipeline['config']
 
             # ai
-            pipeline_config['ai']['runner'] = {
-                'runner': self.ap.provider_cfg.data['runner'],
+            ai_config = pipeline_config.setdefault('ai', {})
+            runner_name = self.ap.provider_cfg.data['runner']
+            runner_id = LEGACY_RUNNER_ID_MAP.get(runner_name, '')
+            ai_config['runner'] = {
+                'id': runner_id,
             }
-            pipeline_config['ai']['local-agent']['model'] = model_uuid
-            pipeline_config['ai']['local-agent']['max-round'] = self.ap.pipeline_cfg.data['msg-truncate']['round'][
-                'max-round'
-            ]
+            runner_configs = ai_config.setdefault('runner_config', {})
 
-            pipeline_config['ai']['local-agent']['prompt'] = [
+            local_agent_runner_id = LEGACY_RUNNER_ID_MAP['local-agent']
+            local_agent_config = runner_configs.setdefault(local_agent_runner_id, {})
+            local_agent_config['model'] = {
+                'primary': model_uuid,
+                'fallbacks': [],
+            }
+
+            local_agent_config['prompt'] = [
                 {
                     'role': 'system',
                     'content': self.ap.provider_cfg.data['prompt']['default'],
                 }
             ]
-            pipeline_config['ai']['dify-service-api'] = {
+            runner_configs[LEGACY_RUNNER_ID_MAP['dify-service-api']] = {
                 'base-url': self.ap.provider_cfg.data['dify-service-api']['base-url'],
                 'app-type': self.ap.provider_cfg.data['dify-service-api']['app-type'],
                 'api-key': self.ap.provider_cfg.data['dify-service-api'][
@@ -139,7 +147,7 @@ class DBMigrateV3Config(migration.DBMigration):
                     self.ap.provider_cfg.data['dify-service-api']['app-type']
                 ]['timeout'],
             }
-            pipeline_config['ai']['dashscope-app-api'] = {
+            runner_configs[LEGACY_RUNNER_ID_MAP['dashscope-app-api']] = {
                 'app-type': self.ap.provider_cfg.data['dashscope-app-api']['app-type'],
                 'api-key': self.ap.provider_cfg.data['dashscope-app-api']['api-key'],
                 'references_quote': self.ap.provider_cfg.data['dashscope-app-api'][

src/langbot/pkg/pipeline/controller.py

@@ -21,11 +21,45 @@ class Controller:
         self.ap = ap
         self.semaphore = asyncio.Semaphore(self.ap.instance_config.data['concurrency']['pipeline'])
 
+    async def _try_claim_steering_before_session_slot(
+        self,
+        query: pipeline_query.Query,
+    ) -> bool:
+        """Claim steering while the normal per-session slot is still busy.
+
+        Follow-up input must be claimed before it waits behind the session
+        semaphore; otherwise the active run can finish before the query reaches
+        ChatMessageHandler.try_claim_steering_from_query.
+        """
+        try:
+            pipeline_uuid = query.pipeline_uuid
+            if not pipeline_uuid:
+                return False
+
+            pipeline = await self.ap.pipeline_mgr.get_pipeline_by_uuid(pipeline_uuid)
+            if not pipeline:
+                return False
+
+            session = await self.ap.sess_mgr.get_session(query)
+            query.session = session
+            query.pipeline_config = pipeline.pipeline_entity.config
+            query.variables['_pipeline_bound_plugins'] = pipeline.bound_plugins
+            query.variables['_pipeline_bound_mcp_servers'] = pipeline.bound_mcp_servers
+
+            return await self.ap.agent_run_orchestrator.try_claim_steering_from_query(query)
+        except Exception as exc:
+            self.ap.logger.warning(
+                f'Failed to claim query {query.query_id} as steering input: {exc}',
+                exc_info=True,
+            )
+            return False
+
     async def consumer(self):
         """事件处理循环"""
         try:
             while True:
                 selected_query: pipeline_query.Query = None
+                claimed_steering_query: pipeline_query.Query = None
 
                 # 取请求
                 async with self.ap.query_pool:
@@ -36,6 +70,13 @@ class Controller:
                         # Debug logging removed from tight loop to prevent excessive log generation
                         # that can cause memory overflow in high-traffic scenarios
 
+                        if session._semaphore.locked():
+                            if await self._try_claim_steering_before_session_slot(query):
+                                claimed_steering_query = query
+                                self.ap.logger.debug(f'Claimed query {query.query_id} as steering before session slot')
+                                break
+                            continue
+
                         if not session._semaphore.locked():
                             selected_query = query
                             await session._semaphore.acquire()
@@ -44,7 +85,12 @@ class Controller:
 
                             break
 
-                    if selected_query:  # 找到了
+                    if claimed_steering_query:
+                        queries.remove(claimed_steering_query)
+                        self.ap.query_pool.cached_queries.pop(claimed_steering_query.query_id, None)
+                        self.ap.query_pool.condition.notify_all()
+                        continue
+                    elif selected_query:  # 找到了
                         queries.remove(selected_query)
                     else:  # 没找到 说明：没有请求 或者 所有query对应的session都已达到并发上限
                         await self.ap.query_pool.condition.wait()

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

@@ -1,35 +0,0 @@
-from __future__ import annotations
-
-from .. import stage, entities
-from . import truncator
-from ...utils import importutil
-import langbot_plugin.api.entities.builtin.pipeline.query as pipeline_query
-from . import truncators
-
-importutil.import_modules_in_pkg(truncators)
-
-
-@stage.stage_class('ConversationMessageTruncator')
-class ConversationMessageTruncator(stage.PipelineStage):
-    """Conversation message truncator
-
-    Used to truncate the conversation message chain to adapt to the LLM message length limit.
-    """
-
-    trun: truncator.Truncator
-
-    async def initialize(self, pipeline_config: dict):
-        use_method = 'round'
-
-        for trun in truncator.preregistered_truncators:
-            if trun.name == use_method:
-                self.trun = trun(self.ap)
-                break
-        else:
-            raise ValueError(f'Unknown truncator: {use_method}')
-
-    async def process(self, query: pipeline_query.Query, stage_inst_name: str) -> entities.StageProcessResult:
-        """处理"""
-        query = await self.trun.truncate(query)
-
-        return entities.StageProcessResult(result_type=entities.ResultType.CONTINUE, new_query=query)

src/langbot/pkg/pipeline/msgtrun/truncator.py

@@ -1,56 +0,0 @@
-from __future__ import annotations
-
-import typing
-import abc
-
-from ...core import app
-import langbot_plugin.api.entities.builtin.pipeline.query as pipeline_query
-
-preregistered_truncators: list[typing.Type[Truncator]] = []
-
-
-def truncator_class(
-    name: str,
-) -> typing.Callable[[typing.Type[Truncator]], typing.Type[Truncator]]:
-    """截断器类装饰器
-
-    Args:
-        name (str): 截断器名称
-
-    Returns:
-        typing.Callable[[typing.Type[Truncator]], typing.Type[Truncator]]: 装饰器
-    """
-
-    def decorator(cls: typing.Type[Truncator]) -> typing.Type[Truncator]:
-        assert issubclass(cls, Truncator)
-
-        cls.name = name
-
-        preregistered_truncators.append(cls)
-
-        return cls
-
-    return decorator
-
-
-class Truncator(abc.ABC):
-    """消息截断器基类"""
-
-    name: str
-
-    ap: app.Application
-
-    def __init__(self, ap: app.Application):
-        self.ap = ap
-
-    async def initialize(self):
-        pass
-
-    @abc.abstractmethod
-    async def truncate(self, query: pipeline_query.Query) -> pipeline_query.Query:
-        """截断
-
-        一般只需要操作query.messages，也可以扩展操作query.prompt, query.user_message。
-        请勿操作其他字段。
-        """
-        pass

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

@@ -1,30 +0,0 @@
-from __future__ import annotations
-
-from .. import truncator
-import langbot_plugin.api.entities.builtin.pipeline.query as pipeline_query
-
-
-@truncator.truncator_class('round')
-class RoundTruncator(truncator.Truncator):
-    """Truncate the conversation message chain to adapt to the LLM message length limit."""
-
-    async def truncate(self, query: pipeline_query.Query) -> pipeline_query.Query:
-        """截断"""
-        max_round = query.pipeline_config['ai']['local-agent']['max-round']
-
-        temp_messages = []
-
-        current_round = 0
-
-        # Traverse from back to front
-        for msg in query.messages[::-1]:
-            if current_round < max_round:
-                temp_messages.append(msg)
-                if msg.role == 'user':
-                    current_round += 1
-            else:
-                break
-
-        query.messages = temp_messages[::-1]
-
-        return query

src/langbot/pkg/pipeline/pipelinemgr.py

@@ -28,7 +28,6 @@ from . import (
     wrapper,
     preproc,
     ratelimit,
-    msgtrun,
 )
 
 importutil.import_modules_in_pkgs(
@@ -42,7 +41,6 @@ importutil.import_modules_in_pkgs(
         wrapper,
         preproc,
         ratelimit,
-        msgtrun,
     ]
 )
 
@@ -278,8 +276,10 @@ class RuntimePipeline:
 
         # Get runner name from pipeline config
         runner_name = None
-        if query.pipeline_config and 'ai' in query.pipeline_config and 'runner' in query.pipeline_config['ai']:
-            runner_name = query.pipeline_config['ai']['runner'].get('runner')
+        if query.pipeline_config:
+            from ..agent.runner.config_migration import ConfigMigration
+
+            runner_name = ConfigMigration.resolve_runner_id(query.pipeline_config)
 
         # Record query start and store message_id
         message_id = ''
@@ -438,6 +438,9 @@ class PipelineManager:
         # initialize stage containers according to pipeline_entity.stages
         stage_containers: list[StageInstContainer] = []
         for stage_name in pipeline_entity.stages:
+            if stage_name not in self.stage_dict:
+                self.ap.logger.warning(f'Pipeline stage {stage_name} is not registered; skipping')
+                continue
             stage_containers.append(StageInstContainer(inst_name=stage_name, inst=self.stage_dict[stage_name](self.ap)))
 
         for stage_container in stage_containers:

src/langbot/pkg/pipeline/preproc/preproc.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import datetime
+import typing
 
 from .. import stage, entities
 from langbot_plugin.api.entities.builtin.provider import message as provider_message
@@ -9,6 +10,15 @@ import langbot_plugin.api.entities.builtin.platform.message as platform_message
 import langbot_plugin.api.entities.builtin.pipeline.query as pipeline_query
 import langbot_plugin.api.entities.builtin.platform.events as platform_events
 
+from ...agent.runner.descriptor import AgentRunnerDescriptor
+from ...agent.runner.config_migration import ConfigMigration
+from ...agent.runner import config_schema
+
+
+DEFAULT_PROMPT_CONFIG = [
+    {'role': 'system', 'content': 'You are a helpful assistant.'},
+]
+
 
 @stage.stage_class('PreProcessor')
 class PreProcessor(stage.PipelineStage):
@@ -25,55 +35,170 @@ class PreProcessor(stage.PipelineStage):
         - use_funcs
     """
 
+    async def _get_runner_descriptor(
+        self,
+        runner_id: str | None,
+        bound_plugins: list[str] | None,
+    ) -> AgentRunnerDescriptor | None:
+        if not runner_id:
+            return None
+
+        registry = getattr(self.ap, 'agent_runner_registry', None)
+        if registry is None:
+            return None
+
+        try:
+            return await registry.get(runner_id, bound_plugins)
+        except Exception as e:
+            self.ap.logger.debug(f'Unable to load AgentRunner descriptor for {runner_id}: {e}')
+            return None
+
+    async def _resolve_llm_model(
+        self,
+        primary_uuid: str,
+    ) -> typing.Any | None:
+        if primary_uuid in config_schema.NONE_SENTINELS:
+            return None
+        try:
+            return await self.ap.model_mgr.get_model_by_uuid(primary_uuid)
+        except ValueError:
+            self.ap.logger.warning(f'LLM model {primary_uuid} not found or not configured')
+            return None
+
+    async def _resolve_fallback_models(self, fallback_uuids: list[str]) -> list[str]:
+        valid_fallbacks = []
+        for fallback_uuid in fallback_uuids:
+            if fallback_uuid in config_schema.NONE_SENTINELS:
+                continue
+            try:
+                await self.ap.model_mgr.get_model_by_uuid(fallback_uuid)
+                valid_fallbacks.append(fallback_uuid)
+            except ValueError:
+                self.ap.logger.warning(f'Fallback model {fallback_uuid} not found, skipping')
+        return valid_fallbacks
+
+    def _runner_accepts_multimodal_input(self, descriptor: AgentRunnerDescriptor | None) -> bool:
+        if descriptor is None:
+            return True
+        return descriptor.capabilities.multimodal_input
+
+    def _model_supports_vision(self, llm_model: typing.Any | None) -> bool:
+        if not llm_model:
+            return False
+        abilities = getattr(getattr(llm_model, 'model_entity', None), 'abilities', [])
+        return 'vision' in (abilities or [])
+
+    def _should_keep_image_inputs(
+        self,
+        descriptor: AgentRunnerDescriptor | None,
+        uses_host_models: bool,
+        llm_model: typing.Any | None,
+    ) -> bool:
+        if not self._runner_accepts_multimodal_input(descriptor):
+            return False
+        if uses_host_models:
+            return self._model_supports_vision(llm_model)
+        return True
+
+    def _strip_images_from_history(self, query: pipeline_query.Query) -> None:
+        for msg in query.messages:
+            if isinstance(msg.content, list):
+                msg.content = [elem for elem in msg.content if elem.type != 'image_url']
+
+    def _has_declared_db_engine(self) -> bool:
+        persistence_mgr = getattr(self.ap, 'persistence_mgr', None)
+        if persistence_mgr is None:
+            return False
+        if 'get_db_engine' in getattr(persistence_mgr, '__dict__', {}):
+            return True
+        return hasattr(type(persistence_mgr), 'get_db_engine')
+
+    async def _load_agent_runner_history_messages(
+        self,
+        runner_id: str | None,
+        conversation_uuid: str | None,
+        bot_id: str | None = None,
+        workspace_id: str | None = None,
+        thread_id: str | None = None,
+    ) -> list[provider_message.Message] | None:
+        if not runner_id or not conversation_uuid or not self._has_declared_db_engine():
+            return None
+
+        try:
+            from ...agent.runner.transcript_store import TranscriptStore
+
+            store = TranscriptStore(self.ap.persistence_mgr.get_db_engine())
+            messages = await store.get_legacy_provider_messages(
+                str(conversation_uuid),
+                bot_id=bot_id,
+                workspace_id=workspace_id,
+                thread_id=thread_id,
+                strict_thread=True,
+            )
+        except Exception as e:
+            self.ap.logger.warning(
+                f'Unable to load Transcript history view for conversation {conversation_uuid}: {e}'
+            )
+            return None
+
+        return messages or None
+
+    async def _resolve_history_messages(
+        self,
+        runner_id: str | None,
+        conversation: typing.Any,
+        bot_id: str | None = None,
+        workspace_id: str | None = None,
+    ) -> list[provider_message.Message]:
+        transcript_messages = await self._load_agent_runner_history_messages(
+            runner_id,
+            getattr(conversation, 'uuid', None),
+            bot_id=bot_id,
+            workspace_id=workspace_id,
+            thread_id=getattr(conversation, 'thread_id', None),
+        )
+        if transcript_messages is not None:
+            return transcript_messages
+        return conversation.messages.copy()
+
     async def process(
         self,
         query: pipeline_query.Query,
         stage_inst_name: str,
     ) -> entities.StageProcessResult:
         """Process"""
-        selected_runner = query.pipeline_config['ai']['runner']['runner']
-        include_skill_authoring = (
-            selected_runner == 'local-agent' and getattr(self.ap, 'skill_service', None) is not None
-        )
+        # Resolve runner ID from the current ai.runner.id shape.
+        runner_id = ConfigMigration.resolve_runner_id(query.pipeline_config)
+
+        # Get runner config from ai.runner_config[runner_id].
+        runner_config = ConfigMigration.resolve_runner_config(query.pipeline_config, runner_id) if runner_id else {}
+        query.variables = query.variables or {}
+        bound_plugins = query.variables.get('_pipeline_bound_plugins', None)
+        bound_mcp_servers = query.variables.get('_pipeline_bound_mcp_servers', None)
+        descriptor = await self._get_runner_descriptor(runner_id, bound_plugins)
 
         session = await self.ap.sess_mgr.get_session(query)
 
-        # When not local-agent, llm_model is None
+        uses_host_models = config_schema.uses_host_models(descriptor)
+        uses_host_tools = config_schema.uses_host_tools(descriptor)
+        include_skill_authoring = (
+            config_schema.supports_skill_authoring(descriptor)
+            and getattr(self.ap, 'skill_service', None) is not None
+        )
         llm_model = None
-        if selected_runner == 'local-agent':
-            # Read model config — new format is { primary: str, fallbacks: [str] },
-            # but handle legacy plain string for backward compatibility
-            model_config = query.pipeline_config['ai']['local-agent'].get('model', {})
-            if isinstance(model_config, str):
-                # Legacy format: plain UUID string
-                primary_uuid = model_config
-                fallback_uuids = []
-            else:
-                primary_uuid = model_config.get('primary', '')
-                fallback_uuids = model_config.get('fallbacks', [])
+        if uses_host_models:
+            primary_uuid, fallback_uuids = config_schema.extract_model_selection(descriptor, runner_config)
+            llm_model = await self._resolve_llm_model(primary_uuid)
+            valid_fallbacks = await self._resolve_fallback_models(fallback_uuids)
+            if valid_fallbacks:
+                query.variables['_fallback_model_uuids'] = valid_fallbacks
 
-            if primary_uuid:
-                try:
-                    llm_model = await self.ap.model_mgr.get_model_by_uuid(primary_uuid)
-                except ValueError:
-                    self.ap.logger.warning(f'LLM model {primary_uuid} not found or not configured')
-
-            # Resolve fallback model UUIDs
-            if fallback_uuids:
-                valid_fallbacks = []
-                for fb_uuid in fallback_uuids:
-                    try:
-                        await self.ap.model_mgr.get_model_by_uuid(fb_uuid)
-                        valid_fallbacks.append(fb_uuid)
-                    except ValueError:
-                        self.ap.logger.warning(f'Fallback model {fb_uuid} not found, skipping')
-                if valid_fallbacks:
-                    query.variables['_fallback_model_uuids'] = valid_fallbacks
+        prompt_config = config_schema.extract_prompt_config(descriptor, runner_config, DEFAULT_PROMPT_CONFIG)
 
         conversation = await self.ap.sess_mgr.get_conversation(
             query,
             session,
-            query.pipeline_config['ai']['local-agent']['prompt'],
+            prompt_config,
             query.pipeline_uuid,
             query.bot_uuid,
         )
@@ -82,7 +207,7 @@ class PreProcessor(stage.PipelineStage):
         # been idle for longer than the configured conversation expire time.
         # The idle window is measured from the last preprocess/update time, not
         # from the conversation creation time.
-        conversation_expire_time = query.pipeline_config.get('ai', {}).get('runner', {}).get('expire-time', None)
+        conversation_expire_time = ConfigMigration.get_expire_time(query.pipeline_config)
         now = datetime.datetime.now()
         if conversation_expire_time is not None and conversation_expire_time > 0:
             last_update_time = getattr(conversation, 'update_time', None) or getattr(conversation, 'create_time', None)
@@ -99,20 +224,21 @@ class PreProcessor(stage.PipelineStage):
         # time instead of the first message/creation time.
         conversation.update_time = now
 
-        # 设置query
+        # Attach resolved session state to the query.
         query.session = session
         query.prompt = conversation.prompt.copy()
-        query.messages = conversation.messages.copy()
+        query.messages = await self._resolve_history_messages(
+            runner_id,
+            conversation,
+            bot_id=query.bot_uuid,
+        )
 
-        if selected_runner == 'local-agent':
+        if uses_host_models:
             query.use_funcs = []
             if llm_model:
                 query.use_llm_model_uuid = llm_model.model_entity.uuid
 
-                if 'func_call' in (llm_model.model_entity.abilities or []):
-                    # Get bound plugins and MCP servers for filtering tools
-                    bound_plugins = query.variables.get('_pipeline_bound_plugins', None)
-                    bound_mcp_servers = query.variables.get('_pipeline_bound_mcp_servers', None)
+                if uses_host_tools and 'func_call' in (llm_model.model_entity.abilities or []):
                     query.use_funcs = await self.ap.tool_mgr.get_all_tools(
                         bound_plugins,
                         bound_mcp_servers,
@@ -125,14 +251,22 @@ class PreProcessor(stage.PipelineStage):
 
             # If primary model doesn't support func_call but fallback models exist,
             # load tools anyway since fallback models may support them
-            if not query.use_funcs and query.variables.get('_fallback_model_uuids'):
-                bound_plugins = query.variables.get('_pipeline_bound_plugins', None)
-                bound_mcp_servers = query.variables.get('_pipeline_bound_mcp_servers', None)
+            if uses_host_tools and not query.use_funcs and query.variables.get('_fallback_model_uuids'):
                 query.use_funcs = await self.ap.tool_mgr.get_all_tools(
                     bound_plugins,
                     bound_mcp_servers,
                     include_skill_authoring=include_skill_authoring,
                 )
+        elif uses_host_tools:
+            query.use_funcs = await self.ap.tool_mgr.get_all_tools(
+                bound_plugins,
+                bound_mcp_servers,
+                include_skill_authoring=include_skill_authoring,
+            )
+
+            self.ap.logger.debug(f'Bound plugins: {bound_plugins}')
+            self.ap.logger.debug(f'Bound MCP servers: {bound_mcp_servers}')
+            self.ap.logger.debug(f'Use funcs: {query.use_funcs}')
 
         sender_name = ''
 
@@ -157,32 +291,25 @@ class PreProcessor(stage.PipelineStage):
         }
         query.variables.update(variables)
 
-        # Check if this model supports vision, if not, remove all images
-        # TODO this checking should be performed in runner, and in this stage, the image should be reserved
-        if selected_runner == 'local-agent' and llm_model and 'vision' not in (llm_model.model_entity.abilities or []):
-            for msg in query.messages:
-                if isinstance(msg.content, list):
-                    for me in msg.content:
-                        if me.type == 'image_url':
-                            msg.content.remove(me)
+        keep_image_inputs = self._should_keep_image_inputs(descriptor, uses_host_models, llm_model)
+        if not keep_image_inputs:
+            self._strip_images_from_history(query)
 
         content_list: list[provider_message.ContentElement] = []
 
         plain_text = ''
-        quote_msg = query.pipeline_config['trigger'].get('misc', '').get('combine-quote-message')
+        quote_msg = query.pipeline_config['trigger'].get('misc', {}).get('combine-quote-message', False)
 
         for me in query.message_chain:
             if isinstance(me, platform_message.Plain):
                 content_list.append(provider_message.ContentElement.from_text(me.text))
                 plain_text += me.text
             elif isinstance(me, platform_message.Image):
-                if selected_runner != 'local-agent' or (
-                    llm_model and 'vision' in (llm_model.model_entity.abilities or [])
-                ):
+                if keep_image_inputs:
                     if me.base64 is not None:
                         content_list.append(provider_message.ContentElement.from_image_base64(me.base64))
             elif isinstance(me, platform_message.Voice):
-                # 转成文件链接，让下游 runner 上传到目标模型
+                # Convert voice input into file content for downstream model upload.
                 if me.base64:
                     content_list.append(provider_message.ContentElement.from_file_base64(me.base64, 'voice.silk'))
                 elif me.url:
@@ -197,9 +324,7 @@ class PreProcessor(stage.PipelineStage):
                     if isinstance(msg, platform_message.Plain):
                         content_list.append(provider_message.ContentElement.from_text(msg.text))
                     elif isinstance(msg, platform_message.Image):
-                        if selected_runner != 'local-agent' or (
-                            llm_model and 'vision' in (llm_model.model_entity.abilities or [])
-                        ):
+                        if keep_image_inputs:
                             if msg.base64 is not None:
                                 content_list.append(provider_message.ContentElement.from_image_base64(msg.base64))
                     elif isinstance(msg, platform_message.File):
@@ -219,16 +344,14 @@ class PreProcessor(stage.PipelineStage):
 
         query.user_message = provider_message.Message(role='user', content=content_list)
 
-        # Extract knowledge base UUIDs into query variables so plugins can modify them
-        # during PromptPreProcessing before the runner performs retrieval.
-        kb_uuids = query.pipeline_config['ai']['local-agent'].get('knowledge-bases', [])
-        if not kb_uuids:
-            old_kb_uuid = query.pipeline_config['ai']['local-agent'].get('knowledge-base', '')
-            if old_kb_uuid and old_kb_uuid != '__none__':
-                kb_uuids = [old_kb_uuid]
-        query.variables['_knowledge_base_uuids'] = list(kb_uuids)
+        # Extract configured KB UUIDs into query variables so PromptPreProcessing
+        # plugins can still adjust the authorized retrieval set before run_agent.
+        query.variables['_knowledge_base_uuids'] = config_schema.extract_knowledge_base_uuids(
+            descriptor,
+            runner_config,
+        )
 
-        # =========== 触发事件 PromptPreProcessing
+        # Emit PromptPreProcessing before the runner receives the query.
 
         event = events.PromptPreProcessing(
             session_name=f'{query.session.launcher_type.value}_{query.session.launcher_id}',
@@ -244,19 +367,7 @@ class PreProcessor(stage.PipelineStage):
         query.prompt.messages = event_ctx.event.default_prompt
         query.messages = event_ctx.event.prompt
 
-        # =========== Skill awareness for the local-agent runner ===========
-        # The actual activation goes through the ``activate`` Tool Call so the
-        # LLM doesn't see full SKILL.md instructions until it commits to a
-        # skill (Claude Code's progressive disclosure). But the LLM still has
-        # to KNOW which skills exist to make that choice, so we:
-        #   1. resolve the pipeline's bound skills and stash them in
-        #      ``query.variables['_pipeline_bound_skills']`` for downstream
-        #      visibility checks (skill loader, native exec workdir);
-        #   2. inject a short ``Available Skills`` index (name + description
-        #      only) into the system prompt. The contributor's original PR
-        #      relied on this injection; without it the LLM never discovers
-        #      the skills are there and just calls native tools instead.
-        if selected_runner == 'local-agent' and self.ap.skill_mgr:
+        if include_skill_authoring and getattr(self.ap, 'skill_mgr', None) is not None:
             pipeline_data = await self.ap.pipeline_service.get_pipeline(query.pipeline_uuid)
             extensions_prefs = (pipeline_data or {}).get('extensions_preferences', {})
             enable_all_skills = extensions_prefs.get('enable_all_skills', True)
@@ -268,43 +379,4 @@ class PreProcessor(stage.PipelineStage):
 
             query.variables['_pipeline_bound_skills'] = bound_skills
 
-            skill_addition = self.ap.skill_mgr.build_skill_aware_prompt_addition(
-                bound_skills=bound_skills,
-            )
-            if skill_addition:
-                # Append to the first system message; create one if the
-                # prompt has none. Handles both plain-string and
-                # content-element (list) message bodies.
-                if query.prompt.messages and query.prompt.messages[0].role == 'system':
-                    head = query.prompt.messages[0]
-                    if isinstance(head.content, str):
-                        head.content = head.content + skill_addition
-                    elif isinstance(head.content, list):
-                        appended = False
-                        for ce in head.content:
-                            if getattr(ce, 'type', None) == 'text':
-                                ce.text = (ce.text or '') + skill_addition
-                                appended = True
-                                break
-                        if not appended:
-                            head.content.append(provider_message.ContentElement(type='text', text=skill_addition))
-                else:
-                    query.prompt.messages.insert(
-                        0,
-                        provider_message.Message(role='system', content=skill_addition.strip()),
-                    )
-                self.ap.logger.debug(
-                    f'Skill index injected into system prompt: '
-                    f'pipeline={query.pipeline_uuid} '
-                    f'bound_skills={bound_skills or "all"} '
-                    f'loaded_skills={len(self.ap.skill_mgr.skills)}'
-                )
-            else:
-                self.ap.logger.debug(
-                    f'No skills available for prompt injection: '
-                    f'pipeline={query.pipeline_uuid} '
-                    f'loaded_skills={len(self.ap.skill_mgr.skills)} '
-                    f'bound_skills={bound_skills}'
-                )
-
         return entities.StageProcessResult(result_type=entities.ResultType.CONTINUE, new_query=query)

src/langbot/pkg/pipeline/process/handlers/chat.py

@@ -9,30 +9,36 @@ from datetime import datetime
 
 from .. import handler
 from ... import entities
-from ....provider import runner as runner_module
 
 import langbot_plugin.api.entities.events as events
-from ....utils import importutil, constants, runner as runner_utils
+from ....agent.runner.config_migration import ConfigMigration
+from ....agent.runner import config_schema
+from ....utils import constants, runner as runner_utils
 from ....telemetry import features as telemetry_features
-from ....provider import runners
 import langbot_plugin.api.entities.builtin.provider.session as provider_session
 import langbot_plugin.api.entities.builtin.pipeline.query as pipeline_query
 import langbot_plugin.api.entities.builtin.provider.message as provider_message
 
 
-importutil.import_modules_in_pkg(runners)
+DEFAULT_PROMPT_CONFIG = [
+    {'role': 'system', 'content': 'You are a helpful assistant.'},
+]
 
 
 class ChatMessageHandler(handler.MessageHandler):
+    """Chat message handler using AgentRunOrchestrator.
+
+    This handler delegates all runner execution to the agent_run_orchestrator,
+    which resolves runner ID, builds context, invokes plugin runtime,
+    and normalizes results.
+    """
+
     async def handle(
         self,
         query: pipeline_query.Query,
     ) -> typing.AsyncGenerator[entities.StageProcessResult, None]:
-        """处理"""
-        # 调API
-        #   生成器
-
-        # 触发插件事件
+        """Handle chat message by delegating to AgentRunOrchestrator."""
+        # Trigger plugin event
         event_class = (
             events.PersonNormalMessageReceived
             if query.launcher_type == provider_session.LauncherTypes.PERSON
@@ -53,7 +59,7 @@ class ChatMessageHandler(handler.MessageHandler):
         bound_plugins = query.variables.get('_pipeline_bound_plugins', None)
         event_ctx = await self.ap.plugin_connector.emit_event(event, bound_plugins)
 
-        is_create_card = False  # 判断下是否需要创建流式卡片
+        is_create_card = False  # Track if streaming card was created
 
         if event_ctx.is_prevented_default():
             if event_ctx.event.reply_message_chain is not None:
@@ -79,40 +85,51 @@ class ChatMessageHandler(handler.MessageHandler):
 
             text_length = 0
             try:
-                is_stream = await query.adapter.is_stream_output_supported()
-            except AttributeError:
-                is_stream = False
-
-            try:
-                for r in runner_module.preregistered_runners:
-                    if r.name == query.pipeline_config['ai']['runner']['runner']:
-                        runner = r(self.ap, query.pipeline_config)
-                        break
-                else:
-                    raise ValueError(f'Request Runner not found: {query.pipeline_config["ai"]["runner"]["runner"]}')
                 # Mark start time for telemetry
                 start_ts = time.time()
 
-                if is_stream:
-                    resp_message_id = uuid.uuid4()
-                    chunk_count = 0  # Track streaming chunks to reduce excessive logging
+                try_claim_steering = getattr(
+                    self.ap.agent_run_orchestrator,
+                    'try_claim_steering_from_query',
+                    None,
+                )
+                if try_claim_steering and await try_claim_steering(query):
+                    yield entities.StageProcessResult(result_type=entities.ResultType.INTERRUPT, new_query=query)
+                    return
 
-                    async for result in runner.run(query):
-                        result.resp_message_id = str(resp_message_id)
+                try:
+                    is_stream = await query.adapter.is_stream_output_supported()
+                except AttributeError:
+                    is_stream = False
+
+                # Create a single resp_message_id for the entire streaming response
+                resp_message_id = uuid.uuid4()
+                chunk_count = 0
+
+                # Use AgentRunOrchestrator to run the agent
+                # This replaces direct runner lookup and PluginAgentRunnerWrapper
+                async for result in self.ap.agent_run_orchestrator.run_from_query(query):
+                    result.resp_message_id = str(resp_message_id)
+
+                    # For streaming mode, pop previous response before adding new chunk
+                    # This allows incremental card updates
+                    if is_stream:
                         if query.resp_messages:
                             query.resp_messages.pop()
                         if query.resp_message_chain:
                             query.resp_message_chain.pop()
-                        # 此时连接外部 AI 服务正常,创建卡片
-                        if not is_create_card:  # 只有不是第一次才创建卡片
+
+                        # Create streaming card on first result (connection established)
+                        if not is_create_card:
                             await query.adapter.create_message_card(str(resp_message_id), query.message_event)
                             is_create_card = True
-                        query.resp_messages.append(result)
 
+                    query.resp_messages.append(result)
+
+                    if is_stream:
                         chunk_count += 1
-                        # Only log every 10th chunk to reduce excessive logging during streaming
-                        # This prevents memory overflow from thousands of log entries per conversation
-                        # First chunk uses INFO level to confirm connection establishment
+                        # Only log every 10th chunk to reduce excessive logging during streaming.
+                        # First chunk uses INFO level to confirm connection establishment.
                         if chunk_count == 1:
                             summary = self.format_result_log(result)
                             if summary is not None:
@@ -123,46 +140,59 @@ class ChatMessageHandler(handler.MessageHandler):
                             self.ap.logger.debug(
                                 f'Conversation({query.query_id}) Streaming chunk {chunk_count}: {self.cut_str(result.readable_str())}'
                             )
-
-                        if result.content is not None:
-                            text_length += len(result.content)
-
-                        yield entities.StageProcessResult(result_type=entities.ResultType.CONTINUE, new_query=query)
-
-                    # Log final summary after streaming completes
-                    self.ap.logger.info(
-                        f'Conversation({query.query_id}) Streaming completed: {chunk_count} chunks, {text_length} chars'
-                    )
-
-                else:
-                    async for result in runner.run(query):
-                        query.resp_messages.append(result)
-
+                    else:
                         summary = self.format_result_log(result)
                         if summary is not None:
                             self.ap.logger.info(f'Conversation({query.query_id}) Response: {summary}')
 
-                        if result.content is not None:
-                            text_length += len(result.content)
+                    if result.content is not None:
+                        text_length += len(result.content)
 
-                        yield entities.StageProcessResult(result_type=entities.ResultType.CONTINUE, new_query=query)
+                    yield entities.StageProcessResult(result_type=entities.ResultType.CONTINUE, new_query=query)
 
-                query.session.using_conversation.messages.append(query.user_message)
+                # Log final summary after streaming completes
+                if is_stream:
+                    self.ap.logger.info(
+                        f'Conversation({query.query_id}) Streaming completed: {chunk_count} chunks, {text_length} chars'
+                    )
+
+                # Keep a conversation object available for downstream legacy
+                # readers, but do not mirror AgentRunner history into
+                # conversation.messages. TranscriptStore is the canonical
+                # history source for this path.
+                await self._ensure_conversation_for_history(query)
 
-                query.session.using_conversation.messages.extend(query.resp_messages)
             except Exception as e:
+                # Import orchestrator errors for specific handling
+                from ....agent.runner.errors import (
+                    RunnerNotFoundError,
+                    RunnerNotAuthorizedError,
+                    RunnerExecutionError,
+                )
+
                 error_info = f'{traceback.format_exc()}'
                 self.ap.logger.error(f'Conversation({query.query_id}) Request Failed: {error_info}')
-                traceback.print_exc()
 
-                exception_handling = query.pipeline_config['output']['misc'].get('exception-handling', 'show-hint')
+                # Handle specific runner errors with appropriate messages
+                if isinstance(e, RunnerNotFoundError):
+                    user_notice = f'Agent runner not found: {e.runner_id}'
+                elif isinstance(e, RunnerNotAuthorizedError):
+                    user_notice = 'Agent runner not authorized for this pipeline'
+                elif isinstance(e, RunnerExecutionError):
+                    if e.retryable:
+                        user_notice = 'Agent runner temporarily unavailable. Please try again.'
+                    else:
+                        user_notice = 'Agent runner execution failed.'
+                else:
+                    # Use existing exception handling
+                    exception_handling = query.pipeline_config['output']['misc'].get('exception-handling', 'show-hint')
 
-                if exception_handling == 'show-error':
-                    user_notice = f'{e}'
-                elif exception_handling == 'show-hint':
-                    user_notice = query.pipeline_config['output']['misc'].get('failure-hint', 'Request failed.')
-                else:  # hide
-                    user_notice = None
+                    if exception_handling == 'show-error':
+                        user_notice = f'{e}'
+                    elif exception_handling == 'show-hint':
+                        user_notice = query.pipeline_config['output']['misc'].get('failure-hint', 'Request failed.')
+                    else:  # hide
+                        user_notice = None
 
                 yield entities.StageProcessResult(
                     result_type=entities.ResultType.INTERRUPT,
@@ -172,7 +202,7 @@ class ChatMessageHandler(handler.MessageHandler):
                     debug_notice=traceback.format_exc(),
                 )
             finally:
-                # Telemetry reporting: collect minimal per-query execution info and send asynchronously
+                # Telemetry reporting
                 try:
                     end_ts = time.time()
                     duration_ms = None
@@ -180,16 +210,14 @@ class ChatMessageHandler(handler.MessageHandler):
                         duration_ms = int((end_ts - start_ts) * 1000)
 
                     adapter_name = query.adapter.__class__.__name__ if hasattr(query, 'adapter') else None
-                    runner_name = (
-                        query.pipeline_config.get('ai', {}).get('runner', {}).get('runner')
-                        if query.pipeline_config
-                        else None
-                    )
 
-                    # Model name if using localagent
+                    # Use orchestrator to resolve runner ID for telemetry
+                    runner_name = self.ap.agent_run_orchestrator.resolve_runner_id_for_telemetry(query)
+
+                    # Model name if available
                     model_name = None
                     try:
-                        if runner_name == 'local-agent' and getattr(query, 'use_llm_model_uuid', None):
+                        if getattr(query, 'use_llm_model_uuid', None):
                             m = await self.ap.model_mgr.get_model_by_uuid(query.use_llm_model_uuid)
                             if m and getattr(m, 'model_entity', None):
                                 model_name = getattr(m.model_entity, 'name', None)
@@ -199,7 +227,7 @@ class ChatMessageHandler(handler.MessageHandler):
                     pipeline_plugins = query.variables.get('_pipeline_bound_plugins', None)
 
                     runner_category = runner_utils.get_runner_category_from_runner(
-                        runner_name, runner, query.pipeline_config
+                        runner_name, None, query.pipeline_config
                     )
 
                     # Feature usage collected during query processing (tool calls,
@@ -223,7 +251,6 @@ class ChatMessageHandler(handler.MessageHandler):
                         'timestamp': datetime.utcnow().isoformat(),
                     }
 
-                    # Send telemetry asynchronously and do not block pipeline via app's telemetry manager
                     await self.ap.telemetry.start_send_task(payload)
 
                     # Trigger survey events on successful non-WebSocket responses
@@ -233,5 +260,70 @@ class ChatMessageHandler(handler.MessageHandler):
                             # Counts toward the bot_response_success_100 milestone event
                             await self.ap.survey.record_bot_response_success()
                 except Exception as ex:
-                    # Ensure telemetry issues do not affect normal flow
                     self.ap.logger.warning(f'Failed to send telemetry: {ex}')
+
+    async def _ensure_conversation_for_history(
+        self,
+        query: pipeline_query.Query,
+    ) -> provider_session.Conversation:
+        session = getattr(query, 'session', None)
+        conversation = getattr(session, 'using_conversation', None)
+        if conversation is not None:
+            return conversation
+
+        if session is None or getattr(self.ap, 'sess_mgr', None) is None:
+            raise RuntimeError('Conversation is not available for history update')
+
+        prompt_config = await self._build_history_prompt_config(query)
+        conversation = await self.ap.sess_mgr.get_conversation(
+            query,
+            session,
+            prompt_config,
+            query.pipeline_uuid,
+            query.bot_uuid,
+        )
+        if conversation is None:
+            raise RuntimeError('Conversation manager did not return a conversation')
+
+        if getattr(session, 'using_conversation', None) is None:
+            session.using_conversation = conversation
+        return conversation
+
+    async def _build_history_prompt_config(
+        self,
+        query: pipeline_query.Query,
+    ) -> list[dict[str, typing.Any]]:
+        prompt_messages = getattr(getattr(query, 'prompt', None), 'messages', None)
+        if prompt_messages:
+            prompt_config = []
+            for message in prompt_messages:
+                if hasattr(message, 'model_dump'):
+                    prompt_config.append(message.model_dump(mode='python'))
+                elif isinstance(message, dict):
+                    prompt_config.append(message)
+            if prompt_config:
+                return prompt_config
+
+        runner_id = ConfigMigration.resolve_runner_id(query.pipeline_config)
+        runner_config = ConfigMigration.resolve_runner_config(query.pipeline_config, runner_id) if runner_id else {}
+        bound_plugins = query.variables.get('_pipeline_bound_plugins', None)
+        descriptor = await self._get_runner_descriptor(runner_id, bound_plugins)
+        return config_schema.extract_prompt_config(descriptor, runner_config, DEFAULT_PROMPT_CONFIG)
+
+    async def _get_runner_descriptor(
+        self,
+        runner_id: str | None,
+        bound_plugins: list[str] | None,
+    ) -> typing.Any | None:
+        if not runner_id:
+            return None
+
+        registry = getattr(self.ap, 'agent_runner_registry', None)
+        if registry is None:
+            return None
+
+        try:
+            return await registry.get(runner_id, bound_plugins)
+        except Exception as e:
+            self.ap.logger.debug(f'Unable to load AgentRunner descriptor for {runner_id}: {e}')
+            return None

src/langbot/pkg/plugin/connector.py

@@ -187,6 +187,15 @@ class PluginRuntimeConnector(ManagedRuntimeConnector):
     async def initialize_plugins(self):
         pass
 
+    async def _refresh_agent_runner_registry(self) -> None:
+        registry = getattr(self.ap, 'agent_runner_registry', None)
+        if registry is None:
+            return
+        try:
+            await registry.refresh()
+        except Exception as e:
+            self.ap.logger.warning(f'Failed to refresh agent runner registry: {e}')
+
     async def ping_plugin_runtime(self):
         if not hasattr(self, 'handler'):
             raise PluginRuntimeNotConnectedError('Plugin runtime is not connected')
@@ -550,6 +559,7 @@ class PluginRuntimeConnector(ManagedRuntimeConnector):
                 task_context.metadata.update(metadata)
 
         await self._wait_for_installed_plugin_ready(plugin_author, plugin_name, task_context)
+        await self._refresh_agent_runner_registry()
 
     async def upgrade_plugin(
         self,
@@ -568,6 +578,8 @@ class PluginRuntimeConnector(ManagedRuntimeConnector):
                 if task_context is not None:
                     task_context.trace(trace)
 
+        await self._refresh_agent_runner_registry()
+
     async def delete_plugin(
         self,
         plugin_author: str,
@@ -592,6 +604,8 @@ class PluginRuntimeConnector(ManagedRuntimeConnector):
                 task_context.trace('Cleaning up plugin configuration and storage...')
             await self.handler.cleanup_plugin_data(plugin_author, plugin_name)
 
+        await self._refresh_agent_runner_registry()
+
     async def list_plugins(self, component_kinds: list[str] | None = None) -> list[dict[str, Any]]:
         """List plugins, optionally filtered by component kinds.
 
@@ -792,6 +806,53 @@ class PluginRuntimeConnector(ManagedRuntimeConnector):
 
             yield cmd_ret
 
+    # AgentRunner methods
+    async def list_agent_runners(self, bound_plugins: list[str] | None = None) -> list[dict[str, Any]]:
+        """List all available AgentRunner components.
+
+        Returns list of dicts with plugin_author, plugin_name, runner_name, manifest, etc.
+        """
+        if not self.is_enable_plugin:
+            return []
+
+        runners_data = await self.handler.list_agent_runners(include_plugins=bound_plugins)
+        return runners_data
+
+    async def run_agent(
+        self,
+        plugin_author: str,
+        plugin_name: str,
+        runner_name: str,
+        context: dict[str, Any],
+    ) -> typing.AsyncGenerator[dict[str, Any], None]:
+        """Run an AgentRunner from a plugin.
+
+        Args:
+            plugin_author: Plugin author
+            plugin_name: Plugin name
+            runner_name: AgentRunner component name
+            context: AgentRunContext as dict
+
+        Yields:
+            AgentRunResult dicts
+        """
+        if not self.is_enable_plugin:
+            # Return a protocol-level failure result.
+            yield {
+                'type': 'run.failed',
+                'data': {
+                    'error': 'Plugin system is disabled',
+                    'code': 'plugin.disabled',
+                    'retryable': False,
+                },
+            }
+            return
+
+        gen = self.handler.run_agent(plugin_author, plugin_name, runner_name, context)
+
+        async for ret in gen:
+            yield ret
+
     async def retrieve_knowledge(
         self,
         plugin_author: str,

src/langbot/pkg/provider/runner.py

@@ -1,45 +0,0 @@
-from __future__ import annotations
-
-import abc
-import typing
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from ..core import app
-    import langbot_plugin.api.entities.builtin.pipeline.query as pipeline_query
-    import langbot_plugin.api.entities.builtin.provider.message as provider_message
-
-
-preregistered_runners: list[typing.Type[RequestRunner]] = []
-
-
-def runner_class(name: str):
-    """注册一个请求运行器"""
-
-    def decorator(cls: typing.Type[RequestRunner]) -> typing.Type[RequestRunner]:
-        cls.name = name
-        preregistered_runners.append(cls)
-        return cls
-
-    return decorator
-
-
-class RequestRunner(abc.ABC):
-    """请求运行器"""
-
-    name: str = None
-
-    ap: app.Application
-
-    pipeline_config: dict
-
-    def __init__(self, ap: app.Application, pipeline_config: dict):
-        self.ap = ap
-        self.pipeline_config = pipeline_config
-
-    @abc.abstractmethod
-    async def run(
-        self, query: pipeline_query.Query
-    ) -> typing.AsyncGenerator[provider_message.Message | provider_message.MessageChunk, None]:
-        """运行请求"""
-        pass

src/langbot/pkg/provider/runners/cozeapi.py

@@ -1,288 +0,0 @@
-from __future__ import annotations
-
-import typing
-import json
-import base64
-
-from langbot.pkg.provider import runner
-from langbot.pkg.core import app
-import langbot_plugin.api.entities.builtin.provider.message as provider_message
-from langbot.pkg.utils import image
-import langbot_plugin.api.entities.builtin.pipeline.query as pipeline_query
-from langbot.libs.coze_server_api.client import AsyncCozeAPIClient
-
-
-@runner.runner_class('coze-api')
-class CozeAPIRunner(runner.RequestRunner):
-    """Coze API 对话请求器"""
-
-    def __init__(self, ap: app.Application, pipeline_config: dict):
-        self.pipeline_config = pipeline_config
-        self.ap = ap
-        self.agent_token = pipeline_config['ai']['coze-api']['api-key']
-        self.bot_id = pipeline_config['ai']['coze-api'].get('bot-id')
-        self.chat_timeout = pipeline_config['ai']['coze-api'].get('timeout')
-        self.auto_save_history = pipeline_config['ai']['coze-api'].get('auto_save_history')
-        self.api_base = pipeline_config['ai']['coze-api'].get('api-base')
-
-        self.coze = AsyncCozeAPIClient(self.agent_token, self.api_base)
-
-    def _process_thinking_content(
-        self,
-        content: str,
-    ) -> tuple[str, str]:
-        """处理思维链内容
-
-        Args:
-            content: 原始内容
-        Returns:
-            (处理后的内容, 提取的思维链内容)
-        """
-        remove_think = self.pipeline_config.get('output', {}).get('misc', {}).get('remove-think', False)
-        thinking_content = ''
-        # 从 content 中提取 <think> 标签内容
-        if content and '<think>' in content and '</think>' in content:
-            import re
-
-            think_pattern = r'<think>(.*?)</think>'
-            think_matches = re.findall(think_pattern, content, re.DOTALL)
-            if think_matches:
-                thinking_content = '\n'.join(think_matches)
-                # 移除 content 中的 <think> 标签
-                content = re.sub(think_pattern, '', content, flags=re.DOTALL).strip()
-
-        # 根据 remove_think 参数决定是否保留思维链
-        if remove_think:
-            return content, ''
-        else:
-            # 如果有思维链内容，将其以 <think> 格式添加到 content 开头
-            if thinking_content:
-                content = f'<think>\n{thinking_content}\n</think>\n{content}'.strip()
-            return content, thinking_content
-
-    async def _preprocess_user_message(self, query: pipeline_query.Query) -> list[dict]:
-        """预处理用户消息，转换为Coze消息格式
-
-        Returns:
-            list[dict]: Coze消息列表
-        """
-        messages = []
-
-        if isinstance(query.user_message.content, list):
-            # 多模态消息处理
-            content_parts = []
-
-            for ce in query.user_message.content:
-                if ce.type == 'text':
-                    content_parts.append({'type': 'text', 'text': ce.text})
-                elif ce.type == 'image_base64':
-                    image_b64, image_format = await image.extract_b64_and_format(ce.image_base64)
-                    file_bytes = base64.b64decode(image_b64)
-                    file_id = await self._get_file_id(file_bytes)
-                    content_parts.append({'type': 'image', 'file_id': file_id})
-                elif ce.type == 'file':
-                    # 处理文件，上传到Coze
-                    file_id = await self._get_file_id(ce.file)
-                    content_parts.append({'type': 'file', 'file_id': file_id})
-
-            # 创建多模态消息
-            if content_parts:
-                messages.append(
-                    {
-                        'role': 'user',
-                        'content': json.dumps(content_parts),
-                        'content_type': 'object_string',
-                        'meta_data': None,
-                    }
-                )
-
-        elif isinstance(query.user_message.content, str):
-            # 纯文本消息
-            messages.append(
-                {'role': 'user', 'content': query.user_message.content, 'content_type': 'text', 'meta_data': None}
-            )
-
-        return messages
-
-    async def _get_file_id(self, file) -> str:
-        """上传文件到Coze服务
-        Args:
-            file: 文件
-        Returns:
-            str: 文件ID
-        """
-        file_id = await self.coze.upload(file=file)
-        return file_id
-
-    async def _chat_messages(
-        self, query: pipeline_query.Query
-    ) -> typing.AsyncGenerator[provider_message.Message, None]:
-        """调用聊天助手（非流式）
-
-        注意：由于cozepy没有提供非流式API，这里使用流式API并在结束后一次性返回完整内容
-        """
-        user_id = f'{query.launcher_type.value}_{query.launcher_id}'
-
-        # 预处理用户消息
-        additional_messages = await self._preprocess_user_message(query)
-
-        # 获取会话ID
-        conversation_id = None
-
-        # 收集完整内容
-        full_content = ''
-        full_reasoning = ''
-
-        try:
-            # 调用Coze API流式接口
-            async for chunk in self.coze.chat_messages(
-                bot_id=self.bot_id,
-                user_id=user_id,
-                additional_messages=additional_messages,
-                conversation_id=conversation_id,
-                timeout=self.chat_timeout,
-                auto_save_history=self.auto_save_history,
-                stream=True,
-            ):
-                self.ap.logger.debug(f'coze-chat-stream: {chunk}')
-
-                event_type = chunk.get('event')
-                data = chunk.get('data', {})
-                # Removed debug print statement to avoid cluttering logs in production
-
-                if event_type == 'conversation.message.delta':
-                    # 收集内容
-                    if 'content' in data:
-                        full_content += data.get('content', '')
-
-                    # 收集推理内容（如果有）
-                    if 'reasoning_content' in data:
-                        full_reasoning += data.get('reasoning_content', '')
-
-                elif event_type.split('.')[-1] == 'done':  # 本地部署coze时，结束event不为done
-                    # 保存会话ID
-                    if 'conversation_id' in data:
-                        conversation_id = data.get('conversation_id')
-
-                elif event_type == 'error':
-                    # 处理错误
-                    error_msg = f'Coze API错误: {data.get("message", "未知错误")}'
-                    yield provider_message.Message(
-                        role='assistant',
-                        content=error_msg,
-                    )
-                    return
-
-            # 处理思维链内容
-            content, thinking_content = self._process_thinking_content(full_content)
-            if full_reasoning:
-                remove_think = self.pipeline_config.get('output', {}).get('misc', {}).get('remove-think', False)
-                if not remove_think:
-                    content = f'<think>\n{full_reasoning}\n</think>\n{content}'.strip()
-
-            # 一次性返回完整内容
-            yield provider_message.Message(
-                role='assistant',
-                content=content,
-            )
-
-            # 保存会话ID
-            if conversation_id and query.session.using_conversation:
-                query.session.using_conversation.uuid = conversation_id
-
-        except Exception as e:
-            self.ap.logger.error(f'Coze API错误: {str(e)}')
-            yield provider_message.Message(
-                role='assistant',
-                content=f'Coze API调用失败: {str(e)}',
-            )
-
-    async def _chat_messages_chunk(
-        self, query: pipeline_query.Query
-    ) -> typing.AsyncGenerator[provider_message.MessageChunk, None]:
-        """调用聊天助手（流式）"""
-        user_id = f'{query.launcher_type.value}_{query.launcher_id}'
-
-        # 预处理用户消息
-        additional_messages = await self._preprocess_user_message(query)
-
-        # 获取会话ID
-        conversation_id = None
-
-        start_reasoning = False
-        stop_reasoning = False
-        message_idx = 1
-        is_final = False
-        full_content = ''
-        remove_think = self.pipeline_config.get('output', {}).get('misc', {}).get('remove-think', False)
-
-        try:
-            # 调用Coze API流式接口
-            async for chunk in self.coze.chat_messages(
-                bot_id=self.bot_id,
-                user_id=user_id,
-                additional_messages=additional_messages,
-                conversation_id=conversation_id,
-                timeout=self.chat_timeout,
-                auto_save_history=self.auto_save_history,
-                stream=True,
-            ):
-                self.ap.logger.debug(f'coze-chat-stream-chunk: {chunk}')
-
-                event_type = chunk.get('event')
-                data = chunk.get('data', {})
-                content = ''
-
-                if event_type == 'conversation.message.delta':
-                    message_idx += 1
-                    # 处理内容增量
-                    if 'reasoning_content' in data and not remove_think:
-                        reasoning_content = data.get('reasoning_content', '')
-                        if reasoning_content and not start_reasoning:
-                            content = '<think/>\n'
-                            start_reasoning = True
-                        content += reasoning_content
-
-                    if 'content' in data:
-                        if data.get('content', ''):
-                            content += data.get('content', '')
-                            if not stop_reasoning and start_reasoning:
-                                content = f'</think>\n{content}'
-                                stop_reasoning = True
-
-                elif event_type.split('.')[-1] == 'done':  # 本地部署coze时，结束event不为done
-                    # 保存会话ID
-                    if 'conversation_id' in data:
-                        conversation_id = data.get('conversation_id')
-                        if query.session.using_conversation:
-                            query.session.using_conversation.uuid = conversation_id
-                    is_final = True
-
-                elif event_type == 'error':
-                    # 处理错误
-                    error_msg = f'Coze API错误: {data.get("message", "未知错误")}'
-                    yield provider_message.MessageChunk(role='assistant', content=error_msg, finish_reason='error')
-                    return
-                full_content += content
-                if message_idx % 8 == 0 or is_final:
-                    if full_content:
-                        yield provider_message.MessageChunk(role='assistant', content=full_content, is_final=is_final)
-
-        except Exception as e:
-            self.ap.logger.error(f'Coze API流式调用错误: {str(e)}')
-            yield provider_message.MessageChunk(
-                role='assistant', content=f'Coze API流式调用失败: {str(e)}', finish_reason='error'
-            )
-
-    async def run(self, query: pipeline_query.Query) -> typing.AsyncGenerator[provider_message.Message, None]:
-        """运行"""
-        msg_seq = 0
-        if await query.adapter.is_stream_output_supported():
-            async for msg in self._chat_messages_chunk(query):
-                if isinstance(msg, provider_message.MessageChunk):
-                    msg_seq += 1
-                    msg.msg_sequence = msg_seq
-                yield msg
-        else:
-            async for msg in self._chat_messages(query):
-                yield msg

src/langbot/pkg/provider/runners/dashscopeapi.py

@@ -1,355 +0,0 @@
-from __future__ import annotations
-
-import typing
-import re
-
-import dashscope
-
-from .. import runner
-from ...core import app
-import langbot_plugin.api.entities.builtin.pipeline.query as pipeline_query
-import langbot_plugin.api.entities.builtin.provider.message as provider_message
-
-
-class DashscopeAPIError(Exception):
-    """Dashscope API 请求失败"""
-
-    def __init__(self, message: str):
-        self.message = message
-        super().__init__(self.message)
-
-
-@runner.runner_class('dashscope-app-api')
-class DashScopeAPIRunner(runner.RequestRunner):
-    "阿里云百炼DashsscopeAPI对话请求器"
-
-    # 运行器内部使用的配置
-    app_type: str  # 应用类型
-    app_id: str  # 应用ID
-    api_key: str  # API Key
-    references_quote: (
-        str  # 引用资料提示（当展示回答来源功能开启时，这个变量会作为引用资料名前的提示，可在provider.json中配置）
-    )
-
-    def __init__(self, ap: app.Application, pipeline_config: dict):
-        """初始化"""
-        self.ap = ap
-        self.pipeline_config = pipeline_config
-
-        valid_app_types = ['agent', 'workflow']
-        self.app_type = self.pipeline_config['ai']['dashscope-app-api']['app-type']
-        # 检查配置文件中使用的应用类型是否支持
-        if self.app_type not in valid_app_types:
-            raise DashscopeAPIError(f'不支持的 Dashscope 应用类型: {self.app_type}')
-
-        # 初始化Dashscope 参数配置
-        self.app_id = self.pipeline_config['ai']['dashscope-app-api']['app-id']
-        self.api_key = self.pipeline_config['ai']['dashscope-app-api']['api-key']
-        self.references_quote = self.pipeline_config['ai']['dashscope-app-api']['references_quote']
-
-    def _replace_references(self, text, references_dict):
-        """阿里云百炼平台的自定义应用支持资料引用，此函数可以将引用标签替换为参考资料"""
-
-        # 匹配 <ref>[index_id]</ref> 形式的字符串
-        pattern = re.compile(r'<ref>\[(.*?)\]</ref>')
-
-        def replacement(match):
-            # 获取引用编号
-            ref_key = match.group(1)
-            if ref_key in references_dict:
-                # 如果有对应的参考资料按照provider.json中的reference_quote返回提示，来自哪个参考资料文件
-                return f'({self.references_quote} {references_dict[ref_key]})'
-            else:
-                # 如果没有对应的参考资料，保留原样
-                return match.group(0)
-
-        # 使用 re.sub() 进行替换
-        return pattern.sub(replacement, text)
-
-    async def _preprocess_user_message(self, query: pipeline_query.Query) -> tuple[str, list[str]]:
-        """预处理用户消息，提取纯文本，阿里云提供的上传文件方法过于复杂，暂不支持上传文件（包括图片）"""
-        plain_text = ''
-        image_ids = []
-        if isinstance(query.user_message.content, list):
-            for ce in query.user_message.content:
-                if ce.type == 'text':
-                    plain_text += ce.text
-                # 暂时不支持上传图片，保留代码以便后续扩展
-                # elif ce.type == "image_base64":
-                #     image_b64, image_format = await image.extract_b64_and_format(ce.image_base64)
-                #     file_bytes = base64.b64decode(image_b64)
-                #     file = ("img.png", file_bytes, f"image/{image_format}")
-                #     file_upload_resp = await self.dify_client.upload_file(
-                #         file,
-                #         f"{query.session.launcher_type.value}_{query.session.launcher_id}",
-                #     )
-                #     image_id = file_upload_resp["id"]
-                #     image_ids.append(image_id)
-        elif isinstance(query.user_message.content, str):
-            plain_text = query.user_message.content
-
-        return plain_text, image_ids
-
-    async def _agent_messages(
-        self, query: pipeline_query.Query
-    ) -> typing.AsyncGenerator[provider_message.Message, None]:
-        """Dashscope 智能体对话请求"""
-
-        # 局部变量
-        chunk = None  # 流式传输的块
-        pending_content = ''  # 待处理的Agent输出内容
-        references_dict = {}  # 用于存储引用编号和对应的参考资料
-        plain_text = ''  # 用户输入的纯文本信息
-        image_ids = []  # 用户输入的图片ID列表 （暂不支持）
-
-        think_start = False
-        think_end = False
-
-        plain_text, image_ids = await self._preprocess_user_message(query)
-        has_thoughts = True  # 获取思考过程
-        remove_think = self.pipeline_config['output'].get('misc', {}).get('remove-think')
-        if remove_think:
-            has_thoughts = False
-        # 发送对话请求
-        response = dashscope.Application.call(
-            api_key=self.api_key,  # 智能体应用的API Key
-            app_id=self.app_id,  # 智能体应用的ID
-            prompt=plain_text,  # 用户输入的文本信息
-            stream=True,  # 流式输出
-            incremental_output=True,  # 增量输出，使用流式输出需要开启增量输出
-            session_id=query.session.using_conversation.uuid,  # 会话ID用于，多轮对话
-            enable_thinking=has_thoughts,
-            has_thoughts=has_thoughts,
-            # rag_options={                                     # 主要用于文件交互，暂不支持
-            #     "session_file_ids": ["FILE_ID1"],             # FILE_ID1 替换为实际的临时文件ID,逗号隔开多个
-            # }
-        )
-        idx_chunk = 0
-        try:
-            is_stream = await query.adapter.is_stream_output_supported()
-
-        except AttributeError:
-            is_stream = False
-        if is_stream:
-            for chunk in response:
-                if chunk.get('status_code') != 200:
-                    raise DashscopeAPIError(
-                        f'Dashscope API 请求失败: status_code={chunk.get("status_code")} message={chunk.get("message")} request_id={chunk.get("request_id")} '
-                    )
-                if not chunk:
-                    continue
-                idx_chunk += 1
-                # 获取流式传输的output
-                stream_output = chunk.get('output', {})
-                stream_think = stream_output.get('thoughts') or []
-                if stream_think and stream_think[0].get('thought'):
-                    if not think_start:
-                        think_start = True
-                        pending_content += f'<think>\n{stream_think[0].get("thought")}'
-                    else:
-                        # 继续输出 reasoning_content
-                        pending_content += stream_think[0].get('thought')
-                elif think_start and (not stream_think or stream_think[0].get('thought') == '') and not think_end:
-                    think_end = True
-                    pending_content += '\n</think>\n'
-                if stream_output.get('text') is not None:
-                    pending_content += stream_output.get('text')
-                # 是否是流式最后一个chunk
-                is_final = False if stream_output.get('finish_reason', False) == 'null' else True
-
-                # 获取模型传出的参考资料列表
-                references_dict_list = stream_output.get('doc_references', [])
-
-                # 从模型传出的参考资料信息中提取用于替换的字典
-                if references_dict_list is not None:
-                    for doc in references_dict_list:
-                        if doc.get('index_id') is not None:
-                            references_dict[doc.get('index_id')] = doc.get('doc_name')
-
-                    # 将参考资料替换到文本中
-                    pending_content = self._replace_references(pending_content, references_dict)
-
-                if idx_chunk % 8 == 0 or is_final:
-                    yield provider_message.MessageChunk(
-                        role='assistant',
-                        content=pending_content,
-                        is_final=is_final,
-                    )
-            # 保存当前会话的session_id用于下次对话的语境
-            query.session.using_conversation.uuid = stream_output.get('session_id')
-        else:
-            for chunk in response:
-                if chunk.get('status_code') != 200:
-                    raise DashscopeAPIError(
-                        f'Dashscope API 请求失败: status_code={chunk.get("status_code")} message={chunk.get("message")} request_id={chunk.get("request_id")} '
-                    )
-                if not chunk:
-                    continue
-                idx_chunk += 1
-                # 获取流式传输的output
-                stream_output = chunk.get('output', {})
-                stream_think = stream_output.get('thoughts') or []
-                if stream_think and stream_think[0].get('thought'):
-                    if not think_start:
-                        think_start = True
-                        pending_content += f'<think>\n{stream_think[0].get("thought")}'
-                    else:
-                        # 继续输出 reasoning_content
-                        pending_content += stream_think[0].get('thought')
-                elif think_start and (not stream_think or stream_think[0].get('thought') == '') and not think_end:
-                    think_end = True
-                    pending_content += '\n</think>\n'
-                if stream_output.get('text') is not None:
-                    pending_content += stream_output.get('text')
-
-            # 保存当前会话的session_id用于下次对话的语境
-            query.session.using_conversation.uuid = stream_output.get('session_id')
-
-            # 获取模型传出的参考资料列表
-            references_dict_list = stream_output.get('doc_references', [])
-
-            # 从模型传出的参考资料信息中提取用于替换的字典
-            if references_dict_list is not None:
-                for doc in references_dict_list:
-                    if doc.get('index_id') is not None:
-                        references_dict[doc.get('index_id')] = doc.get('doc_name')
-
-                # 将参考资料替换到文本中
-                pending_content = self._replace_references(pending_content, references_dict)
-
-            yield provider_message.Message(
-                role='assistant',
-                content=pending_content,
-            )
-
-    async def _workflow_messages(
-        self, query: pipeline_query.Query
-    ) -> typing.AsyncGenerator[provider_message.Message, None]:
-        """Dashscope 工作流对话请求"""
-
-        # 局部变量
-        chunk = None  # 流式传输的块
-        pending_content = ''  # 待处理的Agent输出内容
-        references_dict = {}  # 用于存储引用编号和对应的参考资料
-        plain_text = ''  # 用户输入的纯文本信息
-        image_ids = []  # 用户输入的图片ID列表 （暂不支持）
-
-        plain_text, image_ids = await self._preprocess_user_message(query)
-
-        biz_params = {}
-        biz_params.update(query.variables)
-
-        # 发送对话请求
-        response = dashscope.Application.call(
-            api_key=self.api_key,  # 智能体应用的API Key
-            app_id=self.app_id,  # 智能体应用的ID
-            prompt=plain_text,  # 用户输入的文本信息
-            stream=True,  # 流式输出
-            incremental_output=True,  # 增量输出，使用流式输出需要开启增量输出
-            session_id=query.session.using_conversation.uuid,  # 会话ID用于，多轮对话
-            biz_params=biz_params,  # 工作流应用的自定义输入参数传递
-            flow_stream_mode='message_format',  # 消息模式，输出/结束节点的流式结果
-            # rag_options={                                     # 主要用于文件交互，暂不支持
-            #     "session_file_ids": ["FILE_ID1"],             # FILE_ID1 替换为实际的临时文件ID,逗号隔开多个
-            # }
-        )
-
-        # 处理API返回的流式输出
-        try:
-            is_stream = await query.adapter.is_stream_output_supported()
-
-        except AttributeError:
-            is_stream = False
-        idx_chunk = 0
-        if is_stream:
-            for chunk in response:
-                if chunk.get('status_code') != 200:
-                    raise DashscopeAPIError(
-                        f'Dashscope API 请求失败: status_code={chunk.get("status_code")} message={chunk.get("message")} request_id={chunk.get("request_id")} '
-                    )
-                if not chunk:
-                    continue
-                idx_chunk += 1
-                # 获取流式传输的output
-                stream_output = chunk.get('output', {})
-                if stream_output.get('workflow_message') is not None:
-                    pending_content += stream_output.get('workflow_message').get('message').get('content')
-                # if stream_output.get('text') is not None:
-                #     pending_content += stream_output.get('text')
-
-                is_final = False if stream_output.get('finish_reason', False) == 'null' else True
-
-                # 获取模型传出的参考资料列表
-                references_dict_list = stream_output.get('doc_references', [])
-
-                # 从模型传出的参考资料信息中提取用于替换的字典
-                if references_dict_list is not None:
-                    for doc in references_dict_list:
-                        if doc.get('index_id') is not None:
-                            references_dict[doc.get('index_id')] = doc.get('doc_name')
-
-                    # 将参考资料替换到文本中
-                    pending_content = self._replace_references(pending_content, references_dict)
-                if idx_chunk % 8 == 0 or is_final:
-                    yield provider_message.MessageChunk(
-                        role='assistant',
-                        content=pending_content,
-                        is_final=is_final,
-                    )
-
-            # 保存当前会话的session_id用于下次对话的语境
-            query.session.using_conversation.uuid = stream_output.get('session_id')
-
-        else:
-            for chunk in response:
-                if chunk.get('status_code') != 200:
-                    raise DashscopeAPIError(
-                        f'Dashscope API 请求失败: status_code={chunk.get("status_code")} message={chunk.get("message")} request_id={chunk.get("request_id")} '
-                    )
-                if not chunk:
-                    continue
-
-                # 获取流式传输的output
-                stream_output = chunk.get('output', {})
-                if stream_output.get('text') is not None:
-                    pending_content += stream_output.get('text')
-
-                is_final = False if stream_output.get('finish_reason', False) == 'null' else True
-
-            # 保存当前会话的session_id用于下次对话的语境
-            query.session.using_conversation.uuid = stream_output.get('session_id')
-
-            # 获取模型传出的参考资料列表
-            references_dict_list = stream_output.get('doc_references', [])
-
-            # 从模型传出的参考资料信息中提取用于替换的字典
-            if references_dict_list is not None:
-                for doc in references_dict_list:
-                    if doc.get('index_id') is not None:
-                        references_dict[doc.get('index_id')] = doc.get('doc_name')
-
-                # 将参考资料替换到文本中
-                pending_content = self._replace_references(pending_content, references_dict)
-
-            yield provider_message.Message(
-                role='assistant',
-                content=pending_content,
-            )
-
-    async def run(self, query: pipeline_query.Query) -> typing.AsyncGenerator[provider_message.Message, None]:
-        """运行"""
-        msg_seq = 0
-        if self.app_type == 'agent':
-            async for msg in self._agent_messages(query):
-                if isinstance(msg, provider_message.MessageChunk):
-                    msg_seq += 1
-                    msg.msg_sequence = msg_seq
-                yield msg
-        elif self.app_type == 'workflow':
-            async for msg in self._workflow_messages(query):
-                if isinstance(msg, provider_message.MessageChunk):
-                    msg_seq += 1
-                    msg.msg_sequence = msg_seq
-                yield msg
-        else:
-            raise DashscopeAPIError(f'不支持的 Dashscope 应用类型: {self.app_type}')

src/langbot/pkg/provider/runners/deerflowapi.py

@@ -1,511 +0,0 @@
-"""DeerFlow LangGraph API Runner
-
-参考 astrbot 的 deerflow_agent_runner 实现，适配 LangBot 的 Runner 接口。
-
-特点：
-- 使用 LangGraph HTTP API 接入 deer-flow 后端
-- 自动管理 thread_id（按 session 隔离）
-- 支持 SSE 流式响应解析
-- 支持 streaming/非流式两种输出
-- 处理 values / messages-tuple / custom 三种事件
-"""
-
-from __future__ import annotations
-
-import asyncio
-import hashlib
-import json
-import typing
-from collections import deque
-from dataclasses import dataclass, field
-
-
-from langbot.pkg.provider import runner
-from langbot.pkg.core import app
-import langbot_plugin.api.entities.builtin.provider.message as provider_message
-import langbot_plugin.api.entities.builtin.pipeline.query as pipeline_query
-from langbot.libs.deerflow_api import client, errors, stream_utils
-
-
-_MAX_VALUES_HISTORY = 200
-
-
-@dataclass
-class _StreamState:
-    """流式状态跟踪"""
-
-    latest_text: str = ''
-    prev_text_for_streaming: str = ''
-    clarification_text: str = ''
-    task_failures: list[str] = field(default_factory=list)
-    seen_message_ids: set[str] = field(default_factory=set)
-    seen_message_order: deque[str] = field(default_factory=deque)
-    no_id_message_fingerprints: dict[int, str] = field(default_factory=dict)
-    baseline_initialized: bool = False
-    has_values_text: bool = False
-    run_values_messages: list[dict[str, typing.Any]] = field(default_factory=list)
-    timed_out: bool = False
-
-
-@runner.runner_class('deerflow-api')
-class DeerFlowAPIRunner(runner.RequestRunner):
-    """DeerFlow LangGraph API 对话请求器"""
-
-    deerflow_client: client.AsyncDeerFlowClient
-
-    def __init__(self, ap: app.Application, pipeline_config: dict):
-        super().__init__(ap, pipeline_config)
-
-        cfg = self.pipeline_config['ai']['deerflow-api']
-
-        api_base = cfg.get('api-base', '').strip()
-        if not api_base or not api_base.startswith(('http://', 'https://')):
-            raise errors.DeerFlowAPIError(
-                message='DeerFlow API Base URL 格式错误，必须以 http:// 或 https:// 开头',
-            )
-
-        self.api_base = api_base
-        self.api_key = cfg.get('api-key', '')
-        self.auth_header = cfg.get('auth-header', '')
-        self.assistant_id = cfg.get('assistant-id', 'lead_agent')
-        self.model_name = cfg.get('model-name', '')
-        self.thinking_enabled = bool(cfg.get('thinking-enabled', False))
-        self.plan_mode = bool(cfg.get('plan-mode', False))
-        self.subagent_enabled = bool(cfg.get('subagent-enabled', False))
-        self.max_concurrent_subagents = int(cfg.get('max-concurrent-subagents', 3))
-        self.timeout = int(cfg.get('timeout', 300))
-        self.recursion_limit = int(cfg.get('recursion-limit', 1000))
-
-        self.deerflow_client = client.AsyncDeerFlowClient(
-            api_base=self.api_base,
-            api_key=self.api_key,
-            auth_header=self.auth_header,
-        )
-
-    # ------------------------------------------------------------------
-    # 辅助方法
-    # ------------------------------------------------------------------
-
-    def _fingerprint_message(self, message: dict[str, typing.Any]) -> str:
-        try:
-            raw = json.dumps(message, sort_keys=True, ensure_ascii=False, default=str)
-        except (TypeError, ValueError):
-            raw = repr(message)
-        return hashlib.sha1(raw.encode('utf-8', errors='ignore')).hexdigest()
-
-    def _remember_seen_message_id(self, state: _StreamState, msg_id: str) -> None:
-        if not msg_id or msg_id in state.seen_message_ids:
-            return
-        state.seen_message_ids.add(msg_id)
-        state.seen_message_order.append(msg_id)
-        while len(state.seen_message_order) > _MAX_VALUES_HISTORY:
-            dropped = state.seen_message_order.popleft()
-            state.seen_message_ids.discard(dropped)
-
-    def _extract_new_messages_from_values(
-        self,
-        values_messages: list[typing.Any],
-        state: _StreamState,
-    ) -> list[dict[str, typing.Any]]:
-        new_messages: list[dict[str, typing.Any]] = []
-        no_id_indexes_seen: set[int] = set()
-        for idx, msg in enumerate(values_messages):
-            if not isinstance(msg, dict):
-                continue
-            msg_id = stream_utils.get_message_id(msg)
-            if msg_id:
-                if msg_id in state.seen_message_ids:
-                    continue
-                self._remember_seen_message_id(state, msg_id)
-                new_messages.append(msg)
-                continue
-
-            no_id_indexes_seen.add(idx)
-            fp = self._fingerprint_message(msg)
-            if state.no_id_message_fingerprints.get(idx) == fp:
-                continue
-            state.no_id_message_fingerprints[idx] = fp
-            new_messages.append(msg)
-
-        for idx in list(state.no_id_message_fingerprints.keys()):
-            if idx not in no_id_indexes_seen:
-                state.no_id_message_fingerprints.pop(idx, None)
-        return new_messages
-
-    # ------------------------------------------------------------------
-    # 用户输入处理
-    # ------------------------------------------------------------------
-
-    def _build_user_content(
-        self,
-        prompt: str,
-        image_urls: list[str],
-    ) -> typing.Any:
-        """构建 LangGraph 兼容的 user content（支持多模态）"""
-        if not image_urls:
-            return prompt
-
-        content: list[dict[str, typing.Any]] = []
-        if prompt:
-            content.append({'type': 'text', 'text': prompt})
-        for url in image_urls:
-            if not isinstance(url, str):
-                continue
-            url = url.strip()
-            if not url:
-                continue
-            if url.startswith(('http://', 'https://', 'data:')):
-                content.append({'type': 'image_url', 'image_url': {'url': url}})
-        return content if content else prompt
-
-    def _preprocess_user_message(
-        self,
-        query: pipeline_query.Query,
-    ) -> tuple[str, list[str]]:
-        """提取用户消息的纯文本与图片 URL 列表"""
-        plain_text = ''
-        image_urls: list[str] = []
-
-        if isinstance(query.user_message.content, str):
-            plain_text = query.user_message.content
-        elif isinstance(query.user_message.content, list):
-            for ce in query.user_message.content:
-                if ce.type == 'text':
-                    plain_text += ce.text
-                elif ce.type == 'image_base64':
-                    # 转换为 data URI 形式
-                    b64 = getattr(ce, 'image_base64', '')
-                    if b64:
-                        if not b64.startswith('data:'):
-                            b64 = f'data:image/png;base64,{b64}'
-                        image_urls.append(b64)
-                elif ce.type == 'image_url':
-                    url = getattr(ce, 'image_url', '')
-                    if url:
-                        image_urls.append(url)
-
-        return plain_text, image_urls
-
-    # ------------------------------------------------------------------
-    # 请求构造
-    # ------------------------------------------------------------------
-
-    def _build_messages(
-        self,
-        prompt: str,
-        image_urls: list[str],
-        system_prompt: str = '',
-    ) -> list[dict[str, typing.Any]]:
-        messages: list[dict[str, typing.Any]] = []
-        if system_prompt:
-            messages.append({'role': 'system', 'content': system_prompt})
-        messages.append(
-            {
-                'role': 'user',
-                'content': self._build_user_content(prompt, image_urls),
-            }
-        )
-        return messages
-
-    def _build_runtime_configurable(self, thread_id: str) -> dict[str, typing.Any]:
-        cfg: dict[str, typing.Any] = {
-            'thread_id': thread_id,
-            'thinking_enabled': self.thinking_enabled,
-            'is_plan_mode': self.plan_mode,
-            'subagent_enabled': self.subagent_enabled,
-        }
-        if self.subagent_enabled:
-            cfg['max_concurrent_subagents'] = self.max_concurrent_subagents
-        if self.model_name:
-            cfg['model_name'] = self.model_name
-        return cfg
-
-    def _build_payload(
-        self,
-        thread_id: str,
-        prompt: str,
-        image_urls: list[str],
-        system_prompt: str = '',
-    ) -> dict[str, typing.Any]:
-        runtime_configurable = self._build_runtime_configurable(thread_id)
-        return {
-            'assistant_id': self.assistant_id,
-            'input': {
-                'messages': self._build_messages(prompt, image_urls, system_prompt),
-            },
-            'stream_mode': ['values', 'messages-tuple', 'custom'],
-            # DeerFlow 2.0 从 config.configurable 读取运行时覆盖
-            # 同时保留 context 字段做向后兼容
-            'context': dict(runtime_configurable),
-            'config': {
-                'recursion_limit': self.recursion_limit,
-                'configurable': runtime_configurable,
-            },
-        }
-
-    # ------------------------------------------------------------------
-    # Session/Thread 管理
-    # ------------------------------------------------------------------
-
-    async def _ensure_thread_id(self, query: pipeline_query.Query) -> str:
-        """从 query.session 取/创建 deerflow thread_id
-
-        LangBot 使用 `query.session.using_conversation.uuid` 持久化 conversation id，
-        我们复用这个字段存储 deerflow thread_id（与 Dify Runner 同样做法）。
-        """
-        thread_id = query.session.using_conversation.uuid or ''
-        if thread_id:
-            return thread_id
-
-        thread = await self.deerflow_client.create_thread(timeout=min(30, self.timeout))
-        thread_id = thread.get('thread_id', '')
-        if not thread_id:
-            raise errors.DeerFlowAPIError(message=f'DeerFlow create thread 返回数据缺少 thread_id: {thread}')
-
-        query.session.using_conversation.uuid = thread_id
-        return thread_id
-
-    # ------------------------------------------------------------------
-    # 流式事件处理
-    # ------------------------------------------------------------------
-
-    def _handle_values_event(
-        self,
-        data: typing.Any,
-        state: _StreamState,
-    ) -> str | None:
-        """处理 values 事件，返回新的完整文本（增量基础上的全量）"""
-        values_messages = stream_utils.extract_messages_from_values_data(data)
-        if not values_messages:
-            return None
-
-        new_messages: list[dict[str, typing.Any]] = []
-        if not state.baseline_initialized:
-            state.baseline_initialized = True
-            for idx, msg in enumerate(values_messages):
-                if not isinstance(msg, dict):
-                    continue
-                new_messages.append(msg)
-                msg_id = stream_utils.get_message_id(msg)
-                if msg_id:
-                    self._remember_seen_message_id(state, msg_id)
-                    continue
-                state.no_id_message_fingerprints[idx] = self._fingerprint_message(msg)
-        else:
-            new_messages = self._extract_new_messages_from_values(values_messages, state)
-
-        latest_text = ''
-        if new_messages:
-            state.run_values_messages.extend(new_messages)
-            if len(state.run_values_messages) > _MAX_VALUES_HISTORY:
-                state.run_values_messages = state.run_values_messages[-_MAX_VALUES_HISTORY:]
-            latest_text = stream_utils.extract_latest_ai_text(state.run_values_messages)
-            if latest_text:
-                state.has_values_text = True
-            latest_clarification = stream_utils.extract_latest_clarification_text(
-                state.run_values_messages,
-            )
-            if latest_clarification:
-                state.clarification_text = latest_clarification
-
-        return latest_text or None
-
-    def _handle_message_event(
-        self,
-        data: typing.Any,
-        state: _StreamState,
-    ) -> str | None:
-        """处理 messages-tuple 事件，返回增量文本
-
-        当 values 事件已经提供完整文本时，跳过 messages-tuple 的增量
-        """
-        delta = stream_utils.extract_ai_delta_from_event_data(data)
-        if delta and not state.has_values_text:
-            state.latest_text += delta
-            return delta
-
-        maybe_clar = stream_utils.extract_clarification_from_event_data(data)
-        if maybe_clar:
-            state.clarification_text = maybe_clar
-        return None
-
-    def _build_final_text(self, state: _StreamState) -> str:
-        """构建最终输出文本"""
-        if state.clarification_text:
-            return state.clarification_text
-
-        # 优先使用最后一条 AI message 的文本
-        latest_ai = stream_utils.extract_latest_ai_message(state.run_values_messages)
-        if latest_ai:
-            text = stream_utils.extract_text(latest_ai.get('content'))
-            if text:
-                if state.timed_out:
-                    text += f'\n\nDeerFlow stream 在 {self.timeout}s 后超时，返回部分结果。'
-                return text
-
-        if state.latest_text:
-            text = state.latest_text
-            if state.timed_out:
-                text += f'\n\nDeerFlow stream 在 {self.timeout}s 后超时，返回部分结果。'
-            return text
-
-        # 提取任务失败信息作兜底
-        failure_text = stream_utils.build_task_failure_summary(state.task_failures)
-        if failure_text:
-            return failure_text
-
-        return 'DeerFlow 返回空响应'
-
-    # ------------------------------------------------------------------
-    # 主流程
-    # ------------------------------------------------------------------
-
-    async def _stream_messages_chunk(
-        self,
-        query: pipeline_query.Query,
-    ) -> typing.AsyncGenerator[provider_message.MessageChunk, None]:
-        """流式输出生成器"""
-        plain_text, image_urls = self._preprocess_user_message(query)
-
-        system_prompt = ''
-        # LangBot 的 pipeline 通常通过 prompt-preprocess 已注入 system prompt
-        # 这里保持空，让 prompt-preprocess 的内容作为 user message 一并送给 deerflow
-
-        thread_id = await self._ensure_thread_id(query)
-        payload = self._build_payload(
-            thread_id=thread_id,
-            prompt=plain_text or 'continue',
-            image_urls=image_urls,
-            system_prompt=system_prompt,
-        )
-
-        state = _StreamState()
-        prev_text = ''
-        message_idx = 0
-
-        try:
-            async for event in self.deerflow_client.stream_run(
-                thread_id=thread_id,
-                payload=payload,
-                timeout=self.timeout,
-            ):
-                event_type = event.get('event')
-                data = event.get('data')
-
-                if event_type == 'values':
-                    new_full = self._handle_values_event(data, state)
-                    if new_full and new_full != prev_text:
-                        delta = new_full[len(prev_text) :] if new_full.startswith(prev_text) else new_full
-                        prev_text = new_full
-                        if delta:
-                            message_idx += 1
-                            yield provider_message.MessageChunk(
-                                role='assistant',
-                                content=new_full,
-                                is_final=False,
-                            )
-                    continue
-
-                if event_type in {'messages-tuple', 'messages', 'message'}:
-                    delta = self._handle_message_event(data, state)
-                    if delta:
-                        prev_text = state.latest_text
-                        message_idx += 1
-                        yield provider_message.MessageChunk(
-                            role='assistant',
-                            content=prev_text,
-                            is_final=False,
-                        )
-                    continue
-
-                if event_type == 'custom':
-                    state.task_failures.extend(
-                        stream_utils.extract_task_failures_from_custom_event(data),
-                    )
-                    continue
-
-                if event_type == 'error':
-                    raise errors.DeerFlowAPIError(message=f'DeerFlow stream error event: {data}')
-
-                if event_type == 'end':
-                    break
-        except (asyncio.TimeoutError, TimeoutError):
-            self.ap.logger.warning(f'DeerFlow stream timed out after {self.timeout}s for thread_id={thread_id}')
-            state.timed_out = True
-
-        # 最终消息
-        final_text = self._build_final_text(state)
-        yield provider_message.MessageChunk(
-            role='assistant',
-            content=final_text,
-            is_final=True,
-        )
-
-    async def _messages(
-        self,
-        query: pipeline_query.Query,
-    ) -> typing.AsyncGenerator[provider_message.Message, None]:
-        """非流式聚合输出"""
-        plain_text, image_urls = self._preprocess_user_message(query)
-
-        thread_id = await self._ensure_thread_id(query)
-        payload = self._build_payload(
-            thread_id=thread_id,
-            prompt=plain_text or 'continue',
-            image_urls=image_urls,
-        )
-
-        state = _StreamState()
-
-        try:
-            async for event in self.deerflow_client.stream_run(
-                thread_id=thread_id,
-                payload=payload,
-                timeout=self.timeout,
-            ):
-                event_type = event.get('event')
-                data = event.get('data')
-
-                if event_type == 'values':
-                    self._handle_values_event(data, state)
-                    continue
-
-                if event_type in {'messages-tuple', 'messages', 'message'}:
-                    self._handle_message_event(data, state)
-                    continue
-
-                if event_type == 'custom':
-                    state.task_failures.extend(
-                        stream_utils.extract_task_failures_from_custom_event(data),
-                    )
-                    continue
-
-                if event_type == 'error':
-                    raise errors.DeerFlowAPIError(message=f'DeerFlow stream error event: {data}')
-
-                if event_type == 'end':
-                    break
-        except (asyncio.TimeoutError, TimeoutError):
-            self.ap.logger.warning(f'DeerFlow stream timed out after {self.timeout}s for thread_id={thread_id}')
-            state.timed_out = True
-
-        final_text = self._build_final_text(state)
-        yield provider_message.Message(
-            role='assistant',
-            content=final_text,
-        )
-
-    async def run(
-        self,
-        query: pipeline_query.Query,
-    ) -> typing.AsyncGenerator[provider_message.Message, None]:
-        """主入口：根据 adapter 是否支持流式输出，选择流式或非流式"""
-        if await query.adapter.is_stream_output_supported():
-            msg_idx = 0
-            async for msg in self._stream_messages_chunk(query):
-                msg_idx += 1
-                msg.msg_sequence = msg_idx
-                yield msg
-        else:
-            async for msg in self._messages(query):
-                yield msg

src/langbot/pkg/provider/runners/difysvapi.py

@@ -1,775 +0,0 @@
-from __future__ import annotations
-
-import typing
-import json
-import uuid
-import base64
-import mimetypes
-
-
-from langbot.pkg.provider import runner
-from langbot.pkg.core import app
-import langbot_plugin.api.entities.builtin.provider.message as provider_message
-from langbot.pkg.utils import image
-import langbot_plugin.api.entities.builtin.pipeline.query as pipeline_query
-from langbot.libs.dify_service_api.v1 import client, errors
-import httpx
-
-
-@runner.runner_class('dify-service-api')
-class DifyServiceAPIRunner(runner.RequestRunner):
-    """Dify Service API 对话请求器"""
-
-    dify_client: client.AsyncDifyServiceClient
-
-    def __init__(self, ap: app.Application, pipeline_config: dict):
-        self.ap = ap
-        self.pipeline_config = pipeline_config
-
-        valid_app_types = ['chat', 'agent', 'workflow']
-        if self.pipeline_config['ai']['dify-service-api']['app-type'] not in valid_app_types:
-            raise errors.DifyAPIError(
-                f'不支持的 Dify 应用类型: {self.pipeline_config["ai"]["dify-service-api"]["app-type"]}'
-            )
-
-        api_key = self.pipeline_config['ai']['dify-service-api']['api-key']
-
-        self.dify_client = client.AsyncDifyServiceClient(
-            api_key=api_key,
-            base_url=self.pipeline_config['ai']['dify-service-api']['base-url'],
-        )
-
-    def _process_thinking_content(
-        self,
-        content: str,
-    ) -> tuple[str, str]:
-        """处理思维链内容
-
-        Args:
-            content: 原始内容
-        Returns:
-            (处理后的内容, 提取的思维链内容)
-        """
-        remove_think = self.pipeline_config['output'].get('misc', '').get('remove-think')
-        thinking_content = ''
-        # 从 content 中提取 <think> 标签内容
-        if content and '<think>' in content and '</think>' in content:
-            import re
-
-            think_pattern = r'<think>(.*?)</think>'
-            think_matches = re.findall(think_pattern, content, re.DOTALL)
-            if think_matches:
-                thinking_content = '\n'.join(think_matches)
-                # 移除 content 中的 <think> 标签
-                content = re.sub(think_pattern, '', content, flags=re.DOTALL).strip()
-
-        # 3. 根据 remove_think 参数决定是否保留思维链
-        if remove_think:
-            return content, ''
-        else:
-            # 如果有思维链内容，将其以 <think> 格式添加到 content 开头
-            if thinking_content:
-                content = f'<think>\n{thinking_content}\n</think>\n{content}'.strip()
-            return content, thinking_content
-
-    def _extract_dify_text_output(self, value: typing.Any) -> str:
-        """Extract text content from Dify output payload."""
-        if value is None:
-            return ''
-        if isinstance(value, dict):
-            content = value.get('content')
-            if isinstance(content, str):
-                return content
-            return json.dumps(value, ensure_ascii=False)
-        if isinstance(value, str):
-            text = value.strip()
-            if not text:
-                return ''
-            try:
-                parsed = json.loads(text)
-            except json.JSONDecodeError:
-                return value
-            if isinstance(parsed, dict) and isinstance(parsed.get('content'), str):
-                return parsed['content']
-            return value
-        return str(value)
-
-    async def _preprocess_user_message(self, query: pipeline_query.Query) -> tuple[str, list[dict]]:
-        """预处理用户消息，提取纯文本，并将图片/文件上传到 Dify 服务
-
-        Returns:
-            tuple[str, list[dict]]: 纯文本和上传后的文件描述（包含 type 与 id）
-        """
-        plain_text = ''
-        upload_files: list[dict] = []
-        user_tag = f'{query.session.launcher_type.value}_{query.session.launcher_id}'
-
-        async def upload_file_bytes(file_name: str, file_bytes: bytes, content_type: str) -> str:
-            file_name = file_name or 'file'
-            content_type = content_type or 'application/octet-stream'
-            file = (file_name, file_bytes, content_type)
-            resp = await self.dify_client.upload_file(file, user_tag)
-            return resp['id']
-
-        async def download_file(file_url: str) -> tuple[bytes, str]:
-            """Download file from url (supports data url)."""
-
-            async with httpx.AsyncClient() as client_session:
-                resp = await client_session.get(file_url)
-                resp.raise_for_status()
-                content_type = (
-                    resp.headers.get('content-type') or mimetypes.guess_type(file_url)[0] or 'application/octet-stream'
-                )
-                return resp.content, content_type
-
-        def _detect_file_type(content_type: str) -> str:
-            """Map MIME to dify file type."""
-            if content_type and content_type.startswith('image/'):
-                return 'image'
-            if content_type and content_type.startswith('audio/'):
-                return 'audio'
-            if content_type and content_type.startswith('video/'):
-                return 'video'
-            return 'document'
-
-        if isinstance(query.user_message.content, list):
-            for ce in query.user_message.content:
-                if ce.type == 'text':
-                    plain_text += ce.text
-                elif ce.type == 'image_base64':
-                    image_b64, image_format = await image.extract_b64_and_format(ce.image_base64)
-                    file_bytes = base64.b64decode(image_b64)
-                    image_id = await upload_file_bytes(f'img.{image_format}', file_bytes, f'image/{image_format}')
-                    upload_files.append({'type': 'image', 'id': image_id})
-                elif ce.type == 'file_url':
-                    file_url = getattr(ce, 'file_url', None)
-                    file_name = getattr(ce, 'file_name', None) or 'file'
-                    try:
-                        file_bytes, content_type = await download_file(file_url)
-                        file_id = await upload_file_bytes(file_name, file_bytes, content_type)
-                        file_type = _detect_file_type(content_type)
-                        upload_files.append({'type': file_type, 'id': file_id})
-                    except Exception as e:
-                        self.ap.logger.warning(f'dify file upload failed: {e}')
-                elif ce.type == 'file_base64':
-                    file_name = getattr(ce, 'file_name', None) or 'file'
-
-                    header, b64_data = ce.file_base64.split(',', 1)
-                    content_type = 'application/octet-stream'
-                    if ';' in header:
-                        content_type = header.split(';')[0][5:] or content_type
-                    file_bytes = base64.b64decode(b64_data)
-                    file_id = await upload_file_bytes(file_name, file_bytes, content_type)
-                    file_type = _detect_file_type(content_type)
-                    upload_files.append({'type': file_type, 'id': file_id})
-
-        elif isinstance(query.user_message.content, str):
-            plain_text = query.user_message.content
-
-        plain_text = plain_text if plain_text else self.pipeline_config['ai']['dify-service-api']['base-prompt']
-
-        return plain_text, upload_files
-
-    async def _chat_messages(
-        self, query: pipeline_query.Query
-    ) -> typing.AsyncGenerator[provider_message.Message, None]:
-        """调用聊天助手"""
-        cov_id = query.session.using_conversation.uuid or None
-        query.variables['conversation_id'] = cov_id
-
-        plain_text, upload_files = await self._preprocess_user_message(query)
-
-        files = [
-            {
-                'type': f['type'],
-                'transfer_method': 'local_file',
-                'upload_file_id': f['id'],
-            }
-            for f in upload_files
-        ]
-
-        mode = 'basic'  # 标记是基础编排还是工作流编排
-
-        basic_mode_pending_chunk = ''
-
-        inputs = {}
-
-        inputs.update(query.variables)
-
-        chunk = None  # 初始化chunk变量，防止在没有响应时引用错误
-
-        async for chunk in self.dify_client.chat_messages(
-            inputs=inputs,
-            query=plain_text,
-            user=f'{query.session.launcher_type.value}_{query.session.launcher_id}',
-            conversation_id=cov_id,
-            files=files,
-            timeout=120,
-        ):
-            self.ap.logger.debug('dify-chat-chunk: ' + str(chunk))
-
-            if chunk['event'] == 'workflow_started':
-                mode = 'workflow'
-
-            if mode == 'workflow':
-                if chunk['event'] == 'node_finished':
-                    if chunk['data']['node_type'] == 'answer':
-                        answer = self._extract_dify_text_output(chunk['data']['outputs'].get('answer'))
-                        content, _ = self._process_thinking_content(answer)
-
-                        yield provider_message.Message(
-                            role='assistant',
-                            content=content,
-                        )
-            elif mode == 'basic':
-                if chunk['event'] == 'message':
-                    basic_mode_pending_chunk += chunk['answer']
-                elif chunk['event'] == 'message_end':
-                    content, _ = self._process_thinking_content(basic_mode_pending_chunk)
-                    yield provider_message.Message(
-                        role='assistant',
-                        content=content,
-                    )
-                    basic_mode_pending_chunk = ''
-
-        if chunk is None:
-            raise errors.DifyAPIError('Dify API 没有返回任何响应，请检查网络连接和API配置')
-
-        query.session.using_conversation.uuid = chunk['conversation_id']
-
-    async def _agent_chat_messages(
-        self, query: pipeline_query.Query
-    ) -> typing.AsyncGenerator[provider_message.Message, None]:
-        """调用聊天助手"""
-        cov_id = query.session.using_conversation.uuid or None
-        query.variables['conversation_id'] = cov_id
-
-        plain_text, upload_files = await self._preprocess_user_message(query)
-
-        files = [
-            {
-                'type': f['type'],
-                'transfer_method': 'local_file',
-                'upload_file_id': f['id'],
-            }
-            for f in upload_files
-        ]
-
-        ignored_events = []
-
-        inputs = {}
-
-        inputs.update(query.variables)
-
-        pending_agent_message = ''
-
-        chunk = None  # 初始化chunk变量，防止在没有响应时引用错误
-
-        async for chunk in self.dify_client.chat_messages(
-            inputs=inputs,
-            query=plain_text,
-            user=f'{query.session.launcher_type.value}_{query.session.launcher_id}',
-            response_mode='streaming',
-            conversation_id=cov_id,
-            files=files,
-            timeout=120,
-        ):
-            self.ap.logger.debug('dify-agent-chunk: ' + str(chunk))
-
-            if chunk['event'] in ignored_events:
-                continue
-
-            if chunk['event'] == 'agent_message' or chunk['event'] == 'message':
-                pending_agent_message += chunk['answer']
-            else:
-                if pending_agent_message.strip() != '':
-                    pending_agent_message = pending_agent_message.replace('</details>Action:', '</details>')
-                    content, _ = self._process_thinking_content(pending_agent_message)
-                    yield provider_message.Message(
-                        role='assistant',
-                        content=content,
-                    )
-                pending_agent_message = ''
-
-                if chunk['event'] == 'agent_thought':
-                    if chunk['tool'] != '' and chunk['observation'] != '':  # 工具调用结果，跳过
-                        continue
-
-                    if chunk['tool']:
-                        msg = provider_message.Message(
-                            role='assistant',
-                            tool_calls=[
-                                provider_message.ToolCall(
-                                    id=chunk['id'],
-                                    type='function',
-                                    function=provider_message.FunctionCall(
-                                        name=chunk['tool'],
-                                        arguments=json.dumps({}),
-                                    ),
-                                )
-                            ],
-                        )
-                        yield msg
-                if chunk['event'] == 'message_file':
-                    if chunk['type'] == 'image' and chunk['belongs_to'] == 'assistant':
-                        # 检查URL是否已经是完整的连接
-                        if chunk['url'].startswith('http://') or chunk['url'].startswith('https://'):
-                            image_url = chunk['url']
-                        else:
-                            base_url = self.dify_client.base_url
-
-                            if base_url.endswith('/v1'):
-                                base_url = base_url[:-3]
-
-                            image_url = base_url + chunk['url']
-
-                        yield provider_message.Message(
-                            role='assistant',
-                            content=[provider_message.ContentElement.from_image_url(image_url)],
-                        )
-                if chunk['event'] == 'error':
-                    raise errors.DifyAPIError('dify 服务错误: ' + chunk['message'])
-
-        if chunk is None:
-            raise errors.DifyAPIError('Dify API 没有返回任何响应，请检查网络连接和API配置')
-
-        query.session.using_conversation.uuid = chunk['conversation_id']
-
-    async def _workflow_messages(
-        self, query: pipeline_query.Query
-    ) -> typing.AsyncGenerator[provider_message.Message, None]:
-        """调用工作流"""
-
-        if not query.session.using_conversation.uuid:
-            query.session.using_conversation.uuid = str(uuid.uuid4())
-
-        query.variables['conversation_id'] = query.session.using_conversation.uuid
-
-        plain_text, upload_files = await self._preprocess_user_message(query)
-
-        files = [
-            {
-                'type': f['type'],
-                'transfer_method': 'local_file',
-                'upload_file_id': f['id'],
-            }
-            for f in upload_files
-        ]
-
-        ignored_events = ['text_chunk', 'workflow_started']
-
-        inputs = {  # these variables are legacy variables, we need to keep them for compatibility
-            'langbot_user_message_text': plain_text,
-            'langbot_session_id': query.variables['session_id'],
-            'langbot_conversation_id': query.variables['conversation_id'],
-            'langbot_msg_create_time': query.variables['msg_create_time'],
-        }
-
-        inputs.update(query.variables)
-
-        async for chunk in self.dify_client.workflow_run(
-            inputs=inputs,
-            user=f'{query.session.launcher_type.value}_{query.session.launcher_id}',
-            files=files,
-            timeout=120,
-        ):
-            self.ap.logger.debug('dify-workflow-chunk: ' + str(chunk))
-            if chunk['event'] in ignored_events:
-                continue
-
-            if chunk['event'] == 'node_started':
-                if chunk['data']['node_type'] == 'start' or chunk['data']['node_type'] == 'end':
-                    continue
-
-                msg = provider_message.Message(
-                    role='assistant',
-                    content=None,
-                    tool_calls=[
-                        provider_message.ToolCall(
-                            id=chunk['data']['node_id'],
-                            type='function',
-                            function=provider_message.FunctionCall(
-                                name=chunk['data']['title'],
-                                arguments=json.dumps({}),
-                            ),
-                        )
-                    ],
-                )
-
-                yield msg
-
-            elif chunk['event'] == 'workflow_finished':
-                if chunk['data']['error']:
-                    raise errors.DifyAPIError(chunk['data']['error'])
-                content, _ = self._process_thinking_content(chunk['data']['outputs']['summary'])
-
-                msg = provider_message.Message(
-                    role='assistant',
-                    content=content,
-                )
-
-                yield msg
-
-    async def _chat_messages_chunk(
-        self, query: pipeline_query.Query
-    ) -> typing.AsyncGenerator[provider_message.MessageChunk, None]:
-        """调用聊天助手"""
-        cov_id = query.session.using_conversation.uuid or None
-        query.variables['conversation_id'] = cov_id
-
-        plain_text, upload_files = await self._preprocess_user_message(query)
-
-        files = [
-            {
-                'type': f['type'],
-                'transfer_method': 'local_file',
-                'upload_file_id': f['id'],
-            }
-            for f in upload_files
-        ]
-
-        mode = 'basic'
-        basic_mode_pending_chunk = ''
-
-        inputs = {}
-
-        inputs.update(query.variables)
-        message_idx = 0
-
-        chunk = None  # 初始化chunk变量，防止在没有响应时引用错误
-
-        is_final = False
-        think_start = False
-        think_end = False
-        yielded_final = False
-
-        remove_think = self.pipeline_config['output'].get('misc', '').get('remove-think')
-
-        async for chunk in self.dify_client.chat_messages(
-            inputs=inputs,
-            query=plain_text,
-            user=f'{query.session.launcher_type.value}_{query.session.launcher_id}',
-            conversation_id=cov_id,
-            files=files,
-            timeout=120,
-        ):
-            self.ap.logger.debug('dify-chat-chunk: ' + str(chunk))
-
-            if chunk['event'] == 'workflow_started':
-                mode = 'workflow'
-            elif chunk['event'] in ('node_started', 'node_finished', 'workflow_finished'):
-                # Some Dify deployments may omit workflow_started in streamed chunks.
-                mode = 'workflow'
-
-            if chunk['event'] == 'message':
-                message_idx += 1
-                if remove_think:
-                    if '<think>' in chunk['answer'] and not think_start:
-                        think_start = True
-                        continue
-                    if '</think>' in chunk['answer'] and not think_end:
-                        import re
-
-                        content = re.sub(r'^\n</think>', '', chunk['answer'])
-                        basic_mode_pending_chunk += content
-                        think_end = True
-                    elif think_end:
-                        basic_mode_pending_chunk += chunk['answer']
-                    if think_start:
-                        continue
-
-                else:
-                    basic_mode_pending_chunk += chunk['answer']
-
-            if chunk['event'] == 'message_end':
-                is_final = True
-            elif chunk['event'] == 'workflow_finished':
-                is_final = True
-                if chunk['data'].get('error'):
-                    raise errors.DifyAPIError(chunk['data']['error'])
-
-            if mode == 'workflow' and chunk['event'] == 'node_finished':
-                if chunk['data'].get('node_type') == 'answer':
-                    answer = self._extract_dify_text_output(chunk['data'].get('outputs', {}).get('answer'))
-                    if answer:
-                        basic_mode_pending_chunk = answer
-
-            if (
-                not yielded_final
-                and (is_final or message_idx % 8 == 0)
-                and (basic_mode_pending_chunk != '' or is_final)
-            ):
-                # content, _ = self._process_thinking_content(basic_mode_pending_chunk)
-                yield provider_message.MessageChunk(
-                    role='assistant',
-                    content=basic_mode_pending_chunk,
-                    is_final=is_final,
-                )
-                if is_final:
-                    yielded_final = True
-
-        if chunk is None:
-            raise errors.DifyAPIError('Dify API 没有返回任何响应，请检查网络连接和API配置')
-
-        query.session.using_conversation.uuid = chunk['conversation_id']
-
-    async def _agent_chat_messages_chunk(
-        self, query: pipeline_query.Query
-    ) -> typing.AsyncGenerator[provider_message.MessageChunk, None]:
-        """调用聊天助手"""
-        cov_id = query.session.using_conversation.uuid or None
-        query.variables['conversation_id'] = cov_id
-
-        plain_text, upload_files = await self._preprocess_user_message(query)
-
-        files = [
-            {
-                'type': f['type'],
-                'transfer_method': 'local_file',
-                'upload_file_id': f['id'],
-            }
-            for f in upload_files
-        ]
-
-        ignored_events = []
-
-        inputs = {}
-
-        inputs.update(query.variables)
-
-        pending_agent_message = ''
-
-        chunk = None  # 初始化chunk变量，防止在没有响应时引用错误
-        message_idx = 0
-        is_final = False
-        think_start = False
-        think_end = False
-
-        remove_think = self.pipeline_config['output'].get('misc', '').get('remove-think')
-
-        async for chunk in self.dify_client.chat_messages(
-            inputs=inputs,
-            query=plain_text,
-            user=f'{query.session.launcher_type.value}_{query.session.launcher_id}',
-            response_mode='streaming',
-            conversation_id=cov_id,
-            files=files,
-            timeout=120,
-        ):
-            self.ap.logger.debug('dify-agent-chunk: ' + str(chunk))
-
-            if chunk['event'] in ignored_events:
-                continue
-
-            if chunk['event'] == 'agent_message':
-                message_idx += 1
-                if remove_think:
-                    if '<think>' in chunk['answer'] and not think_start:
-                        think_start = True
-                        continue
-                    if '</think>' in chunk['answer'] and not think_end:
-                        import re
-
-                        content = re.sub(r'^\n</think>', '', chunk['answer'])
-                        pending_agent_message += content
-                        think_end = True
-                    elif think_end or not think_start:
-                        pending_agent_message += chunk['answer']
-                    if think_start and not think_end:
-                        continue
-
-                else:
-                    pending_agent_message += chunk['answer']
-            elif chunk['event'] == 'message_end':
-                is_final = True
-            else:
-                if chunk['event'] == 'agent_thought':
-                    if chunk['tool'] != '' and chunk['observation'] != '':  # 工具调用结果，跳过
-                        continue
-                    message_idx += 1
-                    if chunk['tool']:
-                        msg = provider_message.MessageChunk(
-                            role='assistant',
-                            tool_calls=[
-                                provider_message.ToolCall(
-                                    id=chunk['id'],
-                                    type='function',
-                                    function=provider_message.FunctionCall(
-                                        name=chunk['tool'],
-                                        arguments=json.dumps({}),
-                                    ),
-                                )
-                            ],
-                        )
-                        yield msg
-                if chunk['event'] == 'message_file':
-                    message_idx += 1
-                    if chunk['type'] == 'image' and chunk['belongs_to'] == 'assistant':
-                        # 检查URL是否已经是完整的连接
-                        if chunk['url'].startswith('http://') or chunk['url'].startswith('https://'):
-                            image_url = chunk['url']
-                        else:
-                            base_url = self.dify_client.base_url
-
-                            if base_url.endswith('/v1'):
-                                base_url = base_url[:-3]
-
-                            image_url = base_url + chunk['url']
-
-                        yield provider_message.MessageChunk(
-                            role='assistant',
-                            content=[provider_message.ContentElement.from_image_url(image_url)],
-                            is_final=is_final,
-                        )
-
-                if chunk['event'] == 'error':
-                    raise errors.DifyAPIError('dify 服务错误: ' + chunk['message'])
-            if message_idx % 8 == 0 or is_final:
-                yield provider_message.MessageChunk(
-                    role='assistant',
-                    content=pending_agent_message,
-                    is_final=is_final,
-                )
-
-        if chunk is None:
-            raise errors.DifyAPIError('Dify API 没有返回任何响应，请检查网络连接和API配置')
-
-        query.session.using_conversation.uuid = chunk['conversation_id']
-
-    async def _workflow_messages_chunk(
-        self, query: pipeline_query.Query
-    ) -> typing.AsyncGenerator[provider_message.MessageChunk, None]:
-        """调用工作流"""
-
-        if not query.session.using_conversation.uuid:
-            query.session.using_conversation.uuid = str(uuid.uuid4())
-
-        query.variables['conversation_id'] = query.session.using_conversation.uuid
-
-        plain_text, upload_files = await self._preprocess_user_message(query)
-
-        files = [
-            {
-                'type': f['type'],
-                'transfer_method': 'local_file',
-                'upload_file_id': f['id'],
-            }
-            for f in upload_files
-        ]
-
-        ignored_events = ['workflow_started']
-
-        inputs = {  # these variables are legacy variables, we need to keep them for compatibility
-            'langbot_user_message_text': plain_text,
-            'langbot_session_id': query.variables['session_id'],
-            'langbot_conversation_id': query.variables['conversation_id'],
-            'langbot_msg_create_time': query.variables['msg_create_time'],
-        }
-
-        inputs.update(query.variables)
-        messsage_idx = 0
-        is_final = False
-        think_start = False
-        think_end = False
-        workflow_contents = ''
-
-        remove_think = self.pipeline_config['output'].get('misc', '').get('remove-think')
-        async for chunk in self.dify_client.workflow_run(
-            inputs=inputs,
-            user=f'{query.session.launcher_type.value}_{query.session.launcher_id}',
-            files=files,
-            timeout=120,
-        ):
-            self.ap.logger.debug('dify-workflow-chunk: ' + str(chunk))
-            if chunk['event'] in ignored_events:
-                continue
-            if chunk['event'] == 'workflow_finished':
-                is_final = True
-                if chunk['data']['error']:
-                    raise errors.DifyAPIError(chunk['data']['error'])
-
-            if chunk['event'] == 'text_chunk':
-                messsage_idx += 1
-                if remove_think:
-                    if '<think>' in chunk['data']['text'] and not think_start:
-                        think_start = True
-                        continue
-                    if '</think>' in chunk['data']['text'] and not think_end:
-                        import re
-
-                        content = re.sub(r'^\n</think>', '', chunk['data']['text'])
-                        workflow_contents += content
-                        think_end = True
-                    elif think_end:
-                        workflow_contents += chunk['data']['text']
-                    if think_start:
-                        continue
-
-                else:
-                    workflow_contents += chunk['data']['text']
-
-            if chunk['event'] == 'node_started':
-                if chunk['data']['node_type'] == 'start' or chunk['data']['node_type'] == 'end':
-                    continue
-                messsage_idx += 1
-                msg = provider_message.MessageChunk(
-                    role='assistant',
-                    content=None,
-                    tool_calls=[
-                        provider_message.ToolCall(
-                            id=chunk['data']['node_id'],
-                            type='function',
-                            function=provider_message.FunctionCall(
-                                name=chunk['data']['title'],
-                                arguments=json.dumps({}),
-                            ),
-                        )
-                    ],
-                )
-
-                yield msg
-
-            if messsage_idx % 8 == 0 or is_final:
-                yield provider_message.MessageChunk(
-                    role='assistant',
-                    content=workflow_contents,
-                    is_final=is_final,
-                )
-
-    async def run(self, query: pipeline_query.Query) -> typing.AsyncGenerator[provider_message.Message, None]:
-        """运行请求"""
-        if await query.adapter.is_stream_output_supported():
-            msg_idx = 0
-            if self.pipeline_config['ai']['dify-service-api']['app-type'] == 'chat':
-                async for msg in self._chat_messages_chunk(query):
-                    msg_idx += 1
-                    msg.msg_sequence = msg_idx
-                    yield msg
-            elif self.pipeline_config['ai']['dify-service-api']['app-type'] == 'agent':
-                async for msg in self._agent_chat_messages_chunk(query):
-                    msg_idx += 1
-                    msg.msg_sequence = msg_idx
-                    yield msg
-            elif self.pipeline_config['ai']['dify-service-api']['app-type'] == 'workflow':
-                async for msg in self._workflow_messages_chunk(query):
-                    msg_idx += 1
-                    msg.msg_sequence = msg_idx
-                    yield msg
-            else:
-                raise errors.DifyAPIError(
-                    f'不支持的 Dify 应用类型: {self.pipeline_config["ai"]["dify-service-api"]["app-type"]}'
-                )
-        else:
-            if self.pipeline_config['ai']['dify-service-api']['app-type'] == 'chat':
-                async for msg in self._chat_messages(query):
-                    yield msg
-            elif self.pipeline_config['ai']['dify-service-api']['app-type'] == 'agent':
-                async for msg in self._agent_chat_messages(query):
-                    yield msg
-            elif self.pipeline_config['ai']['dify-service-api']['app-type'] == 'workflow':
-                async for msg in self._workflow_messages(query):
-                    yield msg
-            else:
-                raise errors.DifyAPIError(
-                    f'不支持的 Dify 应用类型: {self.pipeline_config["ai"]["dify-service-api"]["app-type"]}'
-                )

src/langbot/pkg/provider/runners/langflowapi.py

@@ -1,180 +0,0 @@
-from __future__ import annotations
-
-import typing
-import json
-import httpx
-import uuid
-import traceback
-
-from .. import runner
-from ...core import app
-import langbot_plugin.api.entities.builtin.pipeline.query as pipeline_query
-import langbot_plugin.api.entities.builtin.provider.message as provider_message
-
-
-@runner.runner_class('langflow-api')
-class LangflowAPIRunner(runner.RequestRunner):
-    """Langflow API 对话请求器"""
-
-    def __init__(self, ap: app.Application, pipeline_config: dict):
-        self.ap = ap
-        self.pipeline_config = pipeline_config
-
-    async def _build_request_payload(self, query: pipeline_query.Query) -> dict:
-        """构建请求负载
-
-        Args:
-            query: 用户查询对象
-
-        Returns:
-            dict: 请求负载
-        """
-        # 获取用户消息文本
-        user_message_text = ''
-        if isinstance(query.user_message.content, str):
-            user_message_text = query.user_message.content
-        elif isinstance(query.user_message.content, list):
-            for item in query.user_message.content:
-                if item.type == 'text':
-                    user_message_text += item.text
-
-        # 从配置中获取 input_type 和 output_type，如果未配置则使用默认值
-        input_type = self.pipeline_config['ai']['langflow-api'].get('input_type', 'chat')
-        output_type = self.pipeline_config['ai']['langflow-api'].get('output_type', 'chat')
-
-        # 构建基本负载
-        payload = {
-            'output_type': output_type,
-            'input_type': input_type,
-            'input_value': user_message_text,
-            'session_id': str(uuid.uuid4()),
-        }
-
-        # 如果配置中有tweaks，则添加到负载中
-        tweaks = json.loads(self.pipeline_config['ai']['langflow-api'].get('tweaks'))
-        if tweaks:
-            payload['tweaks'] = tweaks
-
-        return payload
-
-    async def run(
-        self, query: pipeline_query.Query
-    ) -> typing.AsyncGenerator[provider_message.Message | provider_message.MessageChunk, None]:
-        """运行请求
-
-        Args:
-            query: 用户查询对象
-
-        Yields:
-            Message: 回复消息
-        """
-        # 检查是否支持流式输出
-        is_stream = False
-        try:
-            is_stream = await query.adapter.is_stream_output_supported()
-        except AttributeError:
-            is_stream = False
-
-        # 从配置中获取API参数
-        base_url = self.pipeline_config['ai']['langflow-api']['base-url']
-        api_key = self.pipeline_config['ai']['langflow-api']['api-key']
-        flow_id = self.pipeline_config['ai']['langflow-api']['flow-id']
-
-        # 构建API URL
-        url = f'{base_url.rstrip("/")}/api/v1/run/{flow_id}'
-
-        # 构建请求负载
-        payload = await self._build_request_payload(query)
-
-        # 设置请求头
-        headers = {'Content-Type': 'application/json', 'x-api-key': api_key}
-
-        # 发送请求
-        async with httpx.AsyncClient() as client:
-            if is_stream:
-                # 流式请求
-                async with client.stream('POST', url, json=payload, headers=headers, timeout=120.0) as response:
-                    response.raise_for_status()
-
-                    accumulated_content = ''
-                    message_count = 0
-
-                    async for line in response.aiter_lines():
-                        data_str = line
-
-                        if data_str.startswith('data: '):
-                            data_str = data_str[6:]  # 移除 "data: " 前缀
-
-                        try:
-                            data = json.loads(data_str)
-
-                            # 提取消息内容
-                            message_text = ''
-                            if 'outputs' in data and len(data['outputs']) > 0:
-                                output = data['outputs'][0]
-                                if 'outputs' in output and len(output['outputs']) > 0:
-                                    inner_output = output['outputs'][0]
-                                    if 'outputs' in inner_output and 'message' in inner_output['outputs']:
-                                        message_data = inner_output['outputs']['message']
-                                        if 'message' in message_data:
-                                            message_text = message_data['message']
-
-                            # 如果没有找到消息，尝试其他可能的路径
-                            if not message_text and 'messages' in data:
-                                messages = data['messages']
-                                if messages and len(messages) > 0:
-                                    message_text = messages[0].get('message', '')
-
-                            if message_text:
-                                # 更新累积内容
-                                accumulated_content = message_text
-                                message_count += 1
-
-                                # 每8条消息或有新内容时生成一个chunk
-                                if message_count % 8 == 0 or len(message_text) > 0:
-                                    yield provider_message.MessageChunk(
-                                        role='assistant', content=accumulated_content, is_final=False
-                                    )
-                        except json.JSONDecodeError:
-                            # 如果不是JSON，跳过这一行
-                            traceback.print_exc()
-                            continue
-
-                    # 发送最终消息
-                    yield provider_message.MessageChunk(role='assistant', content=accumulated_content, is_final=True)
-            else:
-                # 非流式请求
-                response = await client.post(url, json=payload, headers=headers, timeout=120.0)
-                response.raise_for_status()
-
-                # 解析响应
-                response_data = response.json()
-
-                # 提取消息内容
-                # 根据Langflow API文档，响应结构可能在outputs[0].outputs[0].outputs.message.message中
-                message_text = ''
-                if 'outputs' in response_data and len(response_data['outputs']) > 0:
-                    output = response_data['outputs'][0]
-                    if 'outputs' in output and len(output['outputs']) > 0:
-                        inner_output = output['outputs'][0]
-                        if 'outputs' in inner_output and 'message' in inner_output['outputs']:
-                            message_data = inner_output['outputs']['message']
-                            if 'message' in message_data:
-                                message_text = message_data['message']
-
-                # 如果没有找到消息，尝试其他可能的路径
-                if not message_text and 'messages' in response_data:
-                    messages = response_data['messages']
-                    if messages and len(messages) > 0:
-                        message_text = messages[0].get('message', '')
-
-                # 如果仍然没有找到消息，返回完整响应的字符串表示
-                if not message_text:
-                    message_text = json.dumps(response_data, ensure_ascii=False, indent=2)
-
-                # 生成回复消息
-                if is_stream:
-                    yield provider_message.MessageChunk(role='assistant', content=message_text, is_final=True)
-                else:
-                    reply_message = provider_message.Message(role='assistant', content=message_text)
-                    yield reply_message

src/langbot/pkg/provider/runners/localagent.py

@@ -1,587 +0,0 @@
-from __future__ import annotations
-
-import json
-import copy
-import typing
-from .. import runner
-from ...telemetry import features as telemetry_features
-from ..modelmgr import requester as modelmgr_requester
-from ..tools.loaders.native import EXEC_TOOL_NAME
-import langbot_plugin.api.entities.builtin.pipeline.query as pipeline_query
-import langbot_plugin.api.entities.builtin.provider.message as provider_message
-import langbot_plugin.api.entities.builtin.rag.context as rag_context
-
-
-rag_combined_prompt_template = """
-The following are relevant context entries retrieved from the knowledge base. 
-Please use them to answer the user's message. 
-Respond in the same language as the user's input.
-
-<context>
-{rag_context}
-</context>
-
-<user_message>
-{user_message}
-</user_message>
-"""
-
-SANDBOX_EXEC_TOOL_NAME = 'sandbox_exec'
-SANDBOX_EXEC_SYSTEM_GUIDANCE = (
-    'When sandbox_exec is available, use it for exact calculations, statistics, structured data parsing, '
-    'and code execution instead of estimating mentally. If the user provides numbers, tables, CSV-like text, '
-    'JSON, or other data and asks for a computed answer, prefer running a short Python script in sandbox_exec '
-    'and then answer from the tool result.'
-)
-
-
-# Hard cap on tool-call rounds within a single agent turn. A looping or
-# adversarial model can otherwise emit tool calls indefinitely (each potentially
-# a sandbox exec), yielding a non-terminating request and runaway cost. Set
-# generously so it never interrupts legitimate multi-step agentic workflows.
-MAX_TOOL_CALL_ROUNDS = 128
-
-
-def _model_has_ability(model: modelmgr_requester.RuntimeLLMModel, ability: str) -> bool:
-    return ability in (model.model_entity.abilities or [])
-
-
-class _StreamAccumulator:
-    """Accumulate streamed content and fragmented OpenAI-style tool calls."""
-
-    def __init__(self, msg_sequence: int = 0, initial_content: str | None = None):
-        self.tool_calls_map: dict[str, provider_message.ToolCall] = {}
-        self.msg_idx = 0
-        self.accumulated_content = initial_content or ''
-        self.last_role = 'assistant'
-        self.msg_sequence = msg_sequence
-
-    def add(self, msg: provider_message.MessageChunk) -> provider_message.MessageChunk | None:
-        self.msg_idx += 1
-
-        if msg.role:
-            self.last_role = msg.role
-
-        if msg.content:
-            self.accumulated_content += msg.content
-
-        if msg.tool_calls:
-            for tool_call in msg.tool_calls:
-                if tool_call.id not in self.tool_calls_map:
-                    self.tool_calls_map[tool_call.id] = provider_message.ToolCall(
-                        id=tool_call.id,
-                        type=tool_call.type,
-                        function=provider_message.FunctionCall(
-                            name=tool_call.function.name if tool_call.function else '',
-                            arguments='',
-                        ),
-                    )
-                if tool_call.function and tool_call.function.arguments:
-                    self.tool_calls_map[tool_call.id].function.arguments += tool_call.function.arguments
-
-        if self.msg_idx % 8 == 0 or msg.is_final:
-            self.msg_sequence += 1
-            return provider_message.MessageChunk(
-                role=self.last_role,
-                content=self.accumulated_content,
-                tool_calls=list(self.tool_calls_map.values()) if (self.tool_calls_map and msg.is_final) else None,
-                is_final=msg.is_final,
-                msg_sequence=self.msg_sequence,
-            )
-
-        return None
-
-    def final_message(self) -> provider_message.MessageChunk:
-        return provider_message.MessageChunk(
-            role=self.last_role,
-            content=self.accumulated_content,
-            tool_calls=list(self.tool_calls_map.values()) if self.tool_calls_map else None,
-            msg_sequence=self.msg_sequence,
-        )
-
-
-@runner.runner_class('local-agent')
-class LocalAgentRunner(runner.RequestRunner):
-    """Local agent request runner"""
-
-    async def _inject_inbound_attachments(
-        self,
-        query: pipeline_query.Query,
-        user_message: provider_message.Message,
-    ) -> None:
-        """Persist inbound attachments into the sandbox and tell the model.
-
-        No-op when the box service is unavailable or there are no attachments.
-        On success, appends an extra text ContentElement to the user message
-        listing the in-sandbox paths and the outbox convention, and stashes the
-        descriptors in ``query.variables['_sandbox_inbound_attachments']``.
-        """
-        box_service = getattr(self.ap, 'box_service', None)
-        if box_service is None or not getattr(box_service, 'available', False):
-            return
-        try:
-            attachments = await box_service.materialize_inbound_attachments(query)
-        except Exception as e:  # never break the chat turn over attachment IO
-            self.ap.logger.warning(f'Inbound attachment materialization failed: {e}')
-            return
-        if not attachments:
-            return
-
-        query.variables['_sandbox_inbound_attachments'] = attachments
-
-        lines = [
-            'The user sent attachments. They have been saved into the sandbox and are '
-            'available to the exec/read/write tools at these paths:'
-        ]
-        for att in attachments:
-            lines.append(f'- {att["type"]}: {att["path"]} ({att["size"]} bytes)')
-        outbox_dir = f'{box_service.OUTBOX_MOUNT_DIR}/{query.query_id}'
-        lines.append(
-            'If you produce any file (image, audio, document, etc.) that should be sent '
-            f'back to the user, write it into {outbox_dir}/ (create the directory if '
-            'needed). Every file placed there will be delivered to the user automatically.'
-        )
-        note = '\n'.join(lines)
-
-        # Voice/File attachments are now available to the agent via the sandbox
-        # (exec/read/write tools). Their raw bytes must NOT be forwarded to the
-        # chat model as multimodal content: providers reject non-image file
-        # parts ("Invalid user message ... ensure all user messages are valid
-        # OpenAI chat completion messages"). Strip those content elements and
-        # rely on the sandbox-path note instead. Images are kept so vision
-        # models can still see them.
-        _model_unsafe_types = {'file_base64', 'file_url'}
-        if isinstance(user_message.content, list):
-            user_message.content = [
-                ce for ce in user_message.content if getattr(ce, 'type', None) not in _model_unsafe_types
-            ]
-
-        if isinstance(user_message.content, str):
-            user_message.content = [
-                provider_message.ContentElement.from_text(user_message.content),
-                provider_message.ContentElement.from_text(note),
-            ]
-        elif isinstance(user_message.content, list):
-            user_message.content.append(provider_message.ContentElement.from_text(note))
-        else:
-            user_message.content = [provider_message.ContentElement.from_text(note)]
-
-    def _build_request_messages(
-        self,
-        query: pipeline_query.Query,
-        user_message: provider_message.Message,
-    ) -> list[provider_message.Message]:
-        req_messages = query.prompt.messages.copy() + query.messages.copy()
-
-        if any(getattr(tool, 'name', None) == EXEC_TOOL_NAME for tool in query.use_funcs or []):
-            req_messages.append(
-                provider_message.Message(
-                    role='system',
-                    content=self.ap.box_service.get_system_guidance(query.query_id),
-                )
-            )
-
-        req_messages.append(user_message)
-        return req_messages
-
-    async def _get_model_candidates(
-        self,
-        query: pipeline_query.Query,
-    ) -> list[modelmgr_requester.RuntimeLLMModel]:
-        """Build ordered list of models to try: primary model + fallback models."""
-        candidates = []
-
-        # Primary model
-        if query.use_llm_model_uuid:
-            try:
-                primary = await self.ap.model_mgr.get_model_by_uuid(query.use_llm_model_uuid)
-                candidates.append(primary)
-            except ValueError:
-                self.ap.logger.warning(f'Primary model {query.use_llm_model_uuid} not found')
-
-        # Fallback models
-        fallback_uuids = (query.variables or {}).get('_fallback_model_uuids', [])
-        for fb_uuid in fallback_uuids:
-            try:
-                fb_model = await self.ap.model_mgr.get_model_by_uuid(fb_uuid)
-                candidates.append(fb_model)
-            except ValueError:
-                self.ap.logger.warning(f'Fallback model {fb_uuid} not found, skipping')
-
-        return candidates
-
-    async def _invoke_with_fallback(
-        self,
-        query: pipeline_query.Query,
-        candidates: list[modelmgr_requester.RuntimeLLMModel],
-        messages: list,
-        funcs: list,
-        remove_think: bool,
-    ) -> tuple[provider_message.Message, modelmgr_requester.RuntimeLLMModel]:
-        """Try non-streaming invocation with sequential fallback. Returns (message, model_used)."""
-        last_error = None
-        for model in candidates:
-            try:
-                msg = await model.provider.invoke_llm(
-                    query,
-                    model,
-                    messages,
-                    funcs if _model_has_ability(model, 'func_call') else [],
-                    extra_args=model.model_entity.extra_args,
-                    remove_think=remove_think,
-                )
-                return msg, model
-            except Exception as e:
-                last_error = e
-                self.ap.logger.warning(f'Model {model.model_entity.name} failed: {e}, trying next fallback...')
-        raise last_error or RuntimeError('No model candidates available')
-
-    async def _invoke_stream_with_fallback(
-        self,
-        query: pipeline_query.Query,
-        candidates: list[modelmgr_requester.RuntimeLLMModel],
-        messages: list,
-        funcs: list,
-        remove_think: bool,
-    ) -> tuple[typing.AsyncGenerator, modelmgr_requester.RuntimeLLMModel]:
-        """Try streaming invocation with sequential fallback. Returns (stream_generator, model_used).
-
-        Fallback is only possible before any chunks have been yielded to the client.
-        Once streaming starts, the model is committed.
-        """
-        last_error = None
-        for model in candidates:
-            try:
-                stream = model.provider.invoke_llm_stream(
-                    query,
-                    model,
-                    messages,
-                    funcs if _model_has_ability(model, 'func_call') else [],
-                    extra_args=model.model_entity.extra_args,
-                    remove_think=remove_think,
-                )
-                # Attempt to get the first chunk to verify the stream works
-                first_chunk = await stream.__anext__()
-
-                async def _chain_stream(first, rest):
-                    yield first
-                    async for chunk in rest:
-                        yield chunk
-
-                return _chain_stream(first_chunk, stream), model
-            except StopAsyncIteration:
-                # Empty stream — treat as success (model returned nothing)
-                async def _empty_stream():
-                    return
-                    yield  # make it a generator
-
-                return _empty_stream(), model
-            except Exception as e:
-                last_error = e
-                self.ap.logger.warning(f'Model {model.model_entity.name} stream failed: {e}, trying next fallback...')
-        raise last_error or RuntimeError('No model candidates available')
-
-    async def run(
-        self, query: pipeline_query.Query
-    ) -> typing.AsyncGenerator[provider_message.Message | provider_message.MessageChunk, None]:
-        """Run request"""
-        pending_tool_calls = []
-        initial_response_emitted = False
-
-        # Get knowledge bases list from query variables (set by PreProcessor,
-        # may have been modified by plugins during PromptPreProcessing)
-        kb_uuids = query.variables.get('_knowledge_base_uuids', [])
-
-        user_message = copy.deepcopy(query.user_message)
-
-        # Materialize inbound attachments (images / voices / files) into the
-        # sandbox so the agent's exec/read/write tools can operate on the real
-        # bytes — not just the multimodal copy the model sees. The exact
-        # in-sandbox paths are announced to the model as a system note.
-        await self._inject_inbound_attachments(query, user_message)
-
-        user_message_text = ''
-
-        if isinstance(user_message.content, str):
-            user_message_text = user_message.content
-        elif isinstance(user_message.content, list):
-            for ce in user_message.content:
-                if ce.type == 'text':
-                    user_message_text += ce.text
-                    break
-
-        if kb_uuids and user_message_text:
-            # only support text for now
-            all_results: list[rag_context.RetrievalResultEntry] = []
-
-            kb_engine_plugins: set[str] = set()
-
-            # Retrieve from each knowledge base
-            for kb_uuid in kb_uuids:
-                kb = await self.ap.rag_mgr.get_knowledge_base_by_uuid(kb_uuid)
-
-                if not kb:
-                    self.ap.logger.warning(f'Knowledge base {kb_uuid} not found, skipping')
-                    continue
-
-                try:
-                    engine_plugin_id = kb.get_knowledge_engine_plugin_id() or 'builtin'
-                except Exception:
-                    engine_plugin_id = 'builtin'
-                kb_engine_plugins.add(engine_plugin_id)
-
-                result = await kb.retrieve(
-                    user_message_text,
-                    settings={
-                        'bot_uuid': query.bot_uuid or '',
-                        'sender_id': str(query.sender_id),
-                        'session_name': f'{query.session.launcher_type.value}_{query.session.launcher_id}',
-                    },
-                )
-
-                if result:
-                    all_results.extend(result)
-
-            # Telemetry: knowledge base usage (counts and engine categories only)
-            telemetry_features.set_value(
-                query,
-                'kb',
-                {
-                    'kb_count': len(kb_uuids),
-                    'engine_plugins': sorted(kb_engine_plugins),
-                    'retrieved_entries': len(all_results),
-                },
-            )
-
-            # Rerank step: re-score results using a rerank model if configured
-            local_agent_config = query.pipeline_config.get('ai', {}).get('local-agent', {})
-            rerank_model_uuid = local_agent_config.get('rerank-model', '')
-            if rerank_model_uuid == '__none__':
-                rerank_model_uuid = ''
-            self.ap.logger.info(
-                f'Rerank config: model_uuid={rerank_model_uuid!r}, '
-                f'results={len(all_results)}, '
-                f'local_agent_keys={list(local_agent_config.keys())}'
-            )
-            if all_results and rerank_model_uuid:
-                try:
-                    rerank_model = await self.ap.model_mgr.get_rerank_model_by_uuid(rerank_model_uuid)
-                    rerank_top_k = int(local_agent_config.get('rerank-top-k', 5))
-
-                    doc_texts = []
-                    for entry in all_results:
-                        text = ' '.join(c.text for c in entry.content if c.type == 'text' and c.text)
-                        doc_texts.append(text)
-
-                    doc_texts_capped = doc_texts[:64]
-                    scores = await rerank_model.provider.invoke_rerank(
-                        model=rerank_model,
-                        query=user_message_text,
-                        documents=doc_texts_capped,
-                    )
-
-                    scored = sorted(scores, key=lambda x: x.get('relevance_score', 0), reverse=True)
-                    top_indices = [s['index'] for s in scored[:rerank_top_k] if s['index'] < len(all_results)]
-                    all_results = [all_results[i] for i in top_indices]
-
-                    self.ap.logger.info(
-                        f'Rerank complete: {len(doc_texts)} docs reranked -> top {len(all_results)} kept (top_k={rerank_top_k})'
-                    )
-                except ValueError:
-                    self.ap.logger.warning(f'Rerank model {rerank_model_uuid} not found, skipping rerank')
-                except Exception as e:
-                    self.ap.logger.warning(f'Rerank failed, using original order: {e}')
-
-            final_user_message_text = ''
-
-            if all_results:
-                texts = []
-                idx = 1
-                for entry in all_results:
-                    for content in entry.content:
-                        if content.type == 'text' and content.text is not None:
-                            texts.append(f'[{idx}] {content.text}')
-                            idx += 1
-                rag_context_text = '\n\n'.join(texts)
-                final_user_message_text = rag_combined_prompt_template.format(
-                    rag_context=rag_context_text, user_message=user_message_text
-                )
-
-            else:
-                final_user_message_text = user_message_text
-
-            self.ap.logger.debug(f'Final user message text: {final_user_message_text}')
-
-            for ce in user_message.content:
-                if ce.type == 'text':
-                    ce.text = final_user_message_text
-                    break
-
-        req_messages = self._build_request_messages(query, user_message)
-
-        try:
-            is_stream = await query.adapter.is_stream_output_supported()
-        except AttributeError:
-            is_stream = False
-
-        remove_think = query.pipeline_config['output'].get('misc', '').get('remove-think')
-
-        # Build ordered candidate list (primary + fallbacks)
-        candidates = await self._get_model_candidates(query)
-        if not candidates:
-            raise RuntimeError('No LLM model configured for local-agent runner')
-
-        self.ap.logger.debug(
-            f'localagent req: query={query.query_id} req_messages={req_messages} '
-            f'candidates={[m.model_entity.name for m in candidates]}'
-        )
-
-        if not is_stream:
-            # Non-streaming: invoke with fallback
-            msg, use_llm_model = await self._invoke_with_fallback(
-                query,
-                candidates,
-                req_messages,
-                query.use_funcs,
-                remove_think,
-            )
-            final_msg = msg
-        else:
-            # Streaming: invoke with fallback
-            stream_accumulator = _StreamAccumulator(msg_sequence=1)
-
-            stream_src, use_llm_model = await self._invoke_stream_with_fallback(
-                query,
-                candidates,
-                req_messages,
-                query.use_funcs,
-                remove_think,
-            )
-            async for msg in stream_src:
-                chunk = stream_accumulator.add(msg)
-                if chunk:
-                    yield chunk
-                    initial_response_emitted = True
-
-            final_msg = stream_accumulator.final_message()
-
-        pending_tool_calls = final_msg.tool_calls
-        first_content = final_msg.content
-        if isinstance(final_msg, provider_message.MessageChunk):
-            first_end_sequence = final_msg.msg_sequence
-
-        if not is_stream:
-            yield final_msg
-        elif not initial_response_emitted:
-            yield final_msg
-            initial_response_emitted = True
-
-        req_messages.append(final_msg)
-
-        # Once a model succeeds, commit to it for the tool call loop
-        # (no fallback mid-conversation — different models may interpret tool results differently)
-        tool_call_round = 0
-        while pending_tool_calls:
-            tool_call_round += 1
-            telemetry_features.set_value(query, 'tool_call_rounds', tool_call_round)
-            if tool_call_round > MAX_TOOL_CALL_ROUNDS:
-                self.ap.logger.warning(
-                    f'Tool-call loop reached the {MAX_TOOL_CALL_ROUNDS}-round cap '
-                    f'(query_id={query.query_id}); stopping to avoid a non-terminating request.'
-                )
-                break
-            for tool_call in pending_tool_calls:
-                try:
-                    func = tool_call.function
-
-                    if func.arguments:
-                        parameters = json.loads(func.arguments)
-                    else:
-                        parameters = {}
-
-                    func_ret = await self.ap.tool_mgr.execute_func_call(func.name, parameters, query=query)
-
-                    # Handle return value content
-                    tool_content = None
-                    if (
-                        isinstance(func_ret, list)
-                        and len(func_ret) > 0
-                        and isinstance(func_ret[0], provider_message.ContentElement)
-                    ):
-                        tool_content = func_ret
-                    else:
-                        tool_content = json.dumps(func_ret, ensure_ascii=False)
-
-                    if is_stream:
-                        msg = provider_message.MessageChunk(
-                            role='tool',
-                            content=tool_content,
-                            tool_call_id=tool_call.id,
-                        )
-                    else:
-                        msg = provider_message.Message(
-                            role='tool',
-                            content=tool_content,
-                            tool_call_id=tool_call.id,
-                        )
-
-                    yield msg
-
-                    req_messages.append(msg)
-                except Exception as e:
-                    if is_stream:
-                        err_msg = provider_message.MessageChunk(
-                            role='tool',
-                            content=f'err: {e}',
-                            tool_call_id=tool_call.id,
-                            is_final=True,
-                        )
-                    else:
-                        err_msg = provider_message.Message(role='tool', content=f'err: {e}', tool_call_id=tool_call.id)
-
-                    yield err_msg
-
-                    req_messages.append(err_msg)
-
-            self.ap.logger.debug(
-                f'localagent req: query={query.query_id} req_messages={req_messages} '
-                f'use_llm_model={use_llm_model.model_entity.name}'
-            )
-
-            if is_stream:
-                stream_accumulator = _StreamAccumulator(
-                    msg_sequence=first_end_sequence,
-                    initial_content=first_content,
-                )
-
-                tool_stream_src = use_llm_model.provider.invoke_llm_stream(
-                    query,
-                    use_llm_model,
-                    req_messages,
-                    query.use_funcs if _model_has_ability(use_llm_model, 'func_call') else [],
-                    extra_args=use_llm_model.model_entity.extra_args,
-                    remove_think=remove_think,
-                )
-                async for msg in tool_stream_src:
-                    chunk = stream_accumulator.add(msg)
-                    if chunk:
-                        yield chunk
-
-                final_msg = stream_accumulator.final_message()
-            else:
-                # Non-streaming: use committed model directly (no fallback in tool loop)
-                msg = await use_llm_model.provider.invoke_llm(
-                    query,
-                    use_llm_model,
-                    req_messages,
-                    query.use_funcs if _model_has_ability(use_llm_model, 'func_call') else [],
-                    extra_args=use_llm_model.model_entity.extra_args,
-                    remove_think=remove_think,
-                )
-
-                yield msg
-                final_msg = msg
-
-            pending_tool_calls = final_msg.tool_calls
-
-            req_messages.append(final_msg)

src/langbot/pkg/provider/runners/n8nsvapi.py

@@ -1,277 +0,0 @@
-from __future__ import annotations
-
-import typing
-import json
-import uuid
-import aiohttp
-
-from langbot.pkg.utils import httpclient
-
-from .. import runner
-from ...core import app
-import langbot_plugin.api.entities.builtin.pipeline.query as pipeline_query
-import langbot_plugin.api.entities.builtin.provider.message as provider_message
-
-
-class N8nAPIError(Exception):
-    """N8n API 请求失败"""
-
-    def __init__(self, message: str):
-        self.message = message
-        super().__init__(self.message)
-
-
-@runner.runner_class('n8n-service-api')
-class N8nServiceAPIRunner(runner.RequestRunner):
-    """N8n Service API 工作流请求器"""
-
-    def __init__(self, ap: app.Application, pipeline_config: dict):
-        self.ap = ap
-        self.pipeline_config = pipeline_config
-
-        # 获取webhook URL
-        self.webhook_url = self.pipeline_config['ai']['n8n-service-api']['webhook-url']
-
-        # 获取超时设置，默认为120秒
-        self.timeout = self.pipeline_config['ai']['n8n-service-api'].get('timeout', 120)
-
-        # 获取输出键名，默认为response
-        self.output_key = self.pipeline_config['ai']['n8n-service-api'].get('output-key', 'response')
-
-        # 获取认证类型，默认为none
-        self.auth_type = self.pipeline_config['ai']['n8n-service-api'].get('auth-type', 'none')
-
-        # 根据认证类型获取相应的认证信息
-        if self.auth_type == 'basic':
-            self.basic_username = self.pipeline_config['ai']['n8n-service-api'].get('basic-username', '')
-            self.basic_password = self.pipeline_config['ai']['n8n-service-api'].get('basic-password', '')
-        elif self.auth_type == 'jwt':
-            self.jwt_secret = self.pipeline_config['ai']['n8n-service-api'].get('jwt-secret', '')
-            self.jwt_algorithm = self.pipeline_config['ai']['n8n-service-api'].get('jwt-algorithm', 'HS256')
-        elif self.auth_type == 'header':
-            self.header_name = self.pipeline_config['ai']['n8n-service-api'].get('header-name', '')
-            self.header_value = self.pipeline_config['ai']['n8n-service-api'].get('header-value', '')
-
-    async def _preprocess_user_message(self, query: pipeline_query.Query) -> str:
-        """预处理用户消息，提取纯文本
-
-        Returns:
-            str: 纯文本消息
-        """
-        plain_text = ''
-
-        if isinstance(query.user_message.content, list):
-            for ce in query.user_message.content:
-                if ce.type == 'text':
-                    plain_text += ce.text
-                # 注意：n8n webhook目前不支持直接处理图片，如需支持可在此扩展
-        elif isinstance(query.user_message.content, str):
-            plain_text = query.user_message.content
-
-        return plain_text
-
-    async def _process_response(
-        self, response: aiohttp.ClientResponse
-    ) -> typing.AsyncGenerator[provider_message.Message, None]:
-        """处理响应——支持流式格式和普通 JSON 格式"""
-        full_content = ''
-        full_text = ''
-        chunk_idx = 0
-        is_final = False
-        message_idx = 0
-
-        buffer = ''
-        decoder = json.JSONDecoder()
-
-        async for raw_chunk in response.content.iter_chunked(1024):
-            if not raw_chunk:
-                continue
-
-            try:
-                # 将 bytes 解码为字符串（容忍错误）
-                if isinstance(raw_chunk, (bytes, bytearray)):
-                    chunk_str = raw_chunk.decode('utf-8', errors='replace')
-                else:
-                    chunk_str = str(raw_chunk)
-
-                full_text += chunk_str
-                buffer += chunk_str
-
-                # 尝试从 buffer 中循环解析出 JSON 对象（处理多个对象或部分对象）
-                while buffer:
-                    buffer = buffer.lstrip()
-                    if not buffer:
-                        break
-                    try:
-                        obj, idx = decoder.raw_decode(buffer)
-                        buffer = buffer[idx:]
-
-                        if not isinstance(obj, dict):
-                            # 忽略非字典类型的顶级 JSON
-                            continue
-
-                        if obj.get('type') == 'item' and 'content' in obj:
-                            chunk_idx += 1
-                            content = obj['content']
-                            full_content += content
-                        elif obj.get('type') == 'end':
-                            is_final = True
-
-                        if is_final or (chunk_idx > 0 and chunk_idx % 8 == 0):
-                            message_idx += 1
-                            yield provider_message.MessageChunk(
-                                role='assistant',
-                                content=full_content,
-                                is_final=is_final,
-                                msg_sequence=message_idx,
-                            )
-                    except json.JSONDecodeError:
-                        # buffer 末尾可能是一个不完整的 JSON，等待更多数据
-                        break
-            except Exception as e:
-                # 记录解析失败并继续接收后续 chunk
-                try:
-                    preview = chunk_str[:200]
-                except Exception:
-                    preview = '<unavailable>'
-                self.ap.logger.warning(f'Failed to process chunk: {e}; chunk preview: {preview}')
-
-        # 流结束后，尝试解析残余 buffer
-        if buffer:
-            try:
-                buffer = buffer.strip()
-                if buffer:
-                    obj, _ = decoder.raw_decode(buffer)
-                    if isinstance(obj, dict):
-                        if obj.get('type') == 'item' and 'content' in obj:
-                            chunk_idx += 1
-                            full_content += obj['content']
-                        elif obj.get('type') == 'end':
-                            is_final = True
-                    message_idx += 1
-                    yield provider_message.MessageChunk(
-                        role='assistant',
-                        content=full_content,
-                        is_final=is_final,
-                        msg_sequence=message_idx,
-                    )
-            except Exception as e:
-                preview = buffer[:200]
-                self.ap.logger.warning(f'Failed to parse remaining buffer: {e}; buffer preview: {preview}')
-
-        # n8n 返回普通 JSON 格式（无任何流式 type:item 内容）
-        if chunk_idx == 0:
-            output_content = ''
-            try:
-                response_data = json.loads(full_text.strip())
-                if isinstance(response_data, dict):
-                    if self.output_key in response_data:
-                        output_content = response_data[self.output_key]
-                    else:
-                        output_content = json.dumps(response_data, ensure_ascii=False)
-                else:
-                    output_content = full_text
-            except json.JSONDecodeError:
-                output_content = full_text
-            self.ap.logger.debug(f'n8n webhook response (non-stream): {full_text[:200]}')
-            yield provider_message.MessageChunk(
-                role='assistant',
-                content=output_content,
-                is_final=True,
-                msg_sequence=message_idx + 1,
-            )
-
-    async def _call_webhook(self, query: pipeline_query.Query) -> typing.AsyncGenerator[provider_message.Message, None]:
-        """调用n8n webhook"""
-        # 生成会话ID（如果不存在）
-        if not query.session.using_conversation.uuid:
-            query.session.using_conversation.uuid = str(uuid.uuid4())
-
-        # Keep query variables in sync with the generated/new conversation id.
-        # query.variables is later merged into payload and would otherwise
-        # overwrite the generated conversation_id with the stale preprocessor
-        # value (usually None for a new conversation).
-        query.variables['conversation_id'] = query.session.using_conversation.uuid
-
-        # 预处理用户消息
-        plain_text = await self._preprocess_user_message(query)
-
-        # 准备请求数据
-        payload = {
-            # 基本消息内容
-            'chatInput': plain_text,  # 考虑到之前用户直接用的message model这里添加新键
-            'message': plain_text,
-            'user_message_text': plain_text,
-            'conversation_id': query.session.using_conversation.uuid,
-            'session_id': query.variables.get('session_id', ''),
-            'user_id': f'{query.session.launcher_type.value}_{query.session.launcher_id}',
-            'msg_create_time': query.variables.get('msg_create_time', ''),
-        }
-
-        # 添加所有变量到payload
-        payload.update(query.variables)
-
-        try:
-            is_stream = await query.adapter.is_stream_output_supported()
-        except AttributeError:
-            is_stream = False
-
-        try:
-            # 准备请求头和认证信息
-            headers = {}
-            auth = None
-
-            # 根据认证类型设置相应的认证信息
-            if self.auth_type == 'basic':
-                # 使用Basic认证
-                auth = aiohttp.BasicAuth(self.basic_username, self.basic_password)
-                self.ap.logger.debug(f'using basic auth: {self.basic_username}')
-            elif self.auth_type == 'jwt':
-                # 使用JWT认证
-                import jwt
-                import time
-
-                # 创建JWT令牌
-                payload_jwt = {
-                    'exp': int(time.time()) + 3600,  # 1小时过期
-                    'iat': int(time.time()),
-                    'sub': 'n8n-webhook',
-                }
-                token = jwt.encode(payload_jwt, self.jwt_secret, algorithm=self.jwt_algorithm)
-
-                # 添加到Authorization头
-                headers['Authorization'] = f'Bearer {token}'
-                self.ap.logger.debug('using jwt auth')
-            elif self.auth_type == 'header':
-                # 使用自定义请求头认证
-                headers[self.header_name] = self.header_value
-                self.ap.logger.debug(f'using header auth: {self.header_name}')
-            else:
-                self.ap.logger.debug('no auth')
-
-            # 调用webhook
-            session = httpclient.get_session()
-            async with session.post(
-                self.webhook_url, json=payload, headers=headers, auth=auth, timeout=self.timeout
-            ) as response:
-                if response.status != 200:
-                    error_text = await response.text()
-                    self.ap.logger.error(f'n8n webhook call failed: {response.status}, {error_text}')
-                    raise Exception(f'n8n webhook call failed: {response.status}, {error_text}')
-
-                async for chunk in self._process_response(response):
-                    if is_stream:
-                        yield chunk
-                    elif chunk.is_final:
-                        yield provider_message.Message(
-                            role='assistant',
-                            content=chunk.content,
-                        )
-        except Exception as e:
-            self.ap.logger.error(f'n8n webhook call exception: {str(e)}')
-            raise N8nAPIError(f'n8n webhook call exception: {str(e)}')
-
-    async def run(self, query: pipeline_query.Query) -> typing.AsyncGenerator[provider_message.Message, None]:
-        """运行请求"""
-        async for msg in self._call_webhook(query):
-            yield msg

src/langbot/pkg/provider/runners/tboxapi.py

@@ -1,202 +0,0 @@
-from __future__ import annotations
-
-import typing
-import json
-import base64
-import tempfile
-import os
-
-from tboxsdk.tbox import TboxClient
-from tboxsdk.model.file import File, FileType
-
-from .. import runner
-from ...core import app
-from ...utils import image
-import langbot_plugin.api.entities.builtin.pipeline.query as pipeline_query
-import langbot_plugin.api.entities.builtin.provider.message as provider_message
-
-
-class TboxAPIError(Exception):
-    """TBox API 请求失败"""
-
-    def __init__(self, message: str):
-        self.message = message
-        super().__init__(self.message)
-
-
-@runner.runner_class('tbox-app-api')
-class TboxAPIRunner(runner.RequestRunner):
-    "蚂蚁百宝箱API对话请求器"
-
-    # 运行器内部使用的配置
-    app_id: str  # 蚂蚁百宝箱平台中的应用ID
-    api_key: str  # 在蚂蚁百宝箱平台中申请的令牌
-
-    def __init__(self, ap: app.Application, pipeline_config: dict):
-        """初始化"""
-        self.ap = ap
-        self.pipeline_config = pipeline_config
-
-        # 初始化Tbox 参数配置
-        self.app_id = self.pipeline_config['ai']['tbox-app-api']['app-id']
-        self.api_key = self.pipeline_config['ai']['tbox-app-api']['api-key']
-
-        # 初始化Tbox client
-        self.tbox_client = TboxClient(authorization=self.api_key)
-
-    async def _preprocess_user_message(self, query: pipeline_query.Query) -> tuple[str, list[str]]:
-        """预处理用户消息，提取纯文本，并将图片上传到 Tbox 服务
-
-        Returns:
-            tuple[str, list[str]]: 纯文本和图片的 Tbox 文件ID
-        """
-        plain_text = ''
-        image_ids = []
-
-        if isinstance(query.user_message.content, list):
-            for ce in query.user_message.content:
-                if ce.type == 'text':
-                    plain_text += ce.text
-                elif ce.type == 'image_base64':
-                    image_b64, image_format = await image.extract_b64_and_format(ce.image_base64)
-                    # 创建临时文件
-                    file_bytes = base64.b64decode(image_b64)
-                    try:
-                        with tempfile.NamedTemporaryFile(suffix=f'.{image_format}', delete=False) as tmp_file:
-                            tmp_file.write(file_bytes)
-                            tmp_file_path = tmp_file.name
-                        file_upload_resp = self.tbox_client.upload_file(tmp_file_path)
-                        image_id = file_upload_resp.get('data', '')
-                        image_ids.append(image_id)
-                    finally:
-                        # 清理临时文件
-                        if os.path.exists(tmp_file_path):
-                            os.unlink(tmp_file_path)
-        elif isinstance(query.user_message.content, str):
-            plain_text = query.user_message.content
-
-        return plain_text, image_ids
-
-    async def _agent_messages(
-        self, query: pipeline_query.Query
-    ) -> typing.AsyncGenerator[provider_message.Message, None]:
-        """TBox 智能体对话请求"""
-
-        plain_text, image_ids = await self._preprocess_user_message(query)
-        remove_think = self.pipeline_config['output'].get('misc', {}).get('remove-think')
-
-        try:
-            is_stream = await query.adapter.is_stream_output_supported()
-        except AttributeError:
-            is_stream = False
-
-        # 获取Tbox的conversation_id
-        conversation_id = query.session.using_conversation.uuid or None
-
-        files = None
-        if image_ids:
-            files = [File(file_id=image_id, type=FileType.IMAGE) for image_id in image_ids]
-
-        # 发送对话请求
-        response = self.tbox_client.chat(
-            app_id=self.app_id,  # Tbox中智能体应用的ID
-            user_id=query.bot_uuid,  # 用户ID
-            query=plain_text,  # 用户输入的文本信息
-            stream=is_stream,  # 是否流式输出
-            conversation_id=conversation_id,  # 会话ID，为None时Tbox会自动创建一个新会话
-            files=files,  # 图片内容
-        )
-
-        if is_stream:
-            # 解析Tbox流式输出内容，并发送给上游
-            for chunk in self._process_stream_message(response, query, remove_think):
-                yield chunk
-        else:
-            message = self._process_non_stream_message(response, query, remove_think)
-            yield provider_message.Message(
-                role='assistant',
-                content=message,
-            )
-
-    def _process_non_stream_message(self, response: typing.Dict, query: pipeline_query.Query, remove_think: bool):
-        if response.get('errorCode') != '0':
-            raise TboxAPIError(f'Tbox API 请求失败: {response.get("errorMsg", "")}')
-        payload = response.get('data', {})
-        conversation_id = payload.get('conversationId', '')
-        query.session.using_conversation.uuid = conversation_id
-        thinking_content = payload.get('reasoningContent', [])
-        result = ''
-        if thinking_content and not remove_think:
-            result += f'<think>\n{thinking_content[0].get("text", "")}\n</think>\n'
-        content = payload.get('result', [])
-        if content:
-            result += content[0].get('chunk', '')
-        return result
-
-    def _process_stream_message(
-        self, response: typing.Generator[dict], query: pipeline_query.Query, remove_think: bool
-    ):
-        idx_msg = 0
-        pending_content = ''
-        conversation_id = None
-        think_start = False
-        think_end = False
-        for chunk in response:
-            if chunk.get('type', '') == 'chunk':
-                """
-                Tbox返回的消息内容chunk结构
-                {'lane': 'default', 'payload': {'conversationId': '20250918tBI947065406', 'messageId': '20250918TB1f53230954', 'text': '️'}, 'type': 'chunk'}
-                """
-                # 如果包含思考过程，拼接</think>
-                if think_start and not think_end:
-                    pending_content += '\n</think>\n'
-                    think_end = True
-
-                payload = chunk.get('payload', {})
-                if not conversation_id:
-                    conversation_id = payload.get('conversationId')
-                    query.session.using_conversation.uuid = conversation_id
-                if payload.get('text'):
-                    idx_msg += 1
-                    pending_content += payload.get('text')
-            elif chunk.get('type', '') == 'thinking' and not remove_think:
-                """
-                Tbox返回的思考过程chunk结构
-                {'payload': '{"ext_data":{"text":"日期"},"event":"flow.node.llm.thinking","entity":{"node_type":"text-completion","execute_id":"6","group_id":0,"parent_execute_id":"6","node_name":"模型推理","node_id":"TC_5u6gl0"}}', 'type': 'thinking'}
-                """
-                payload = json.loads(chunk.get('payload', '{}'))
-                if payload.get('ext_data', {}).get('text'):
-                    idx_msg += 1
-                    content = payload.get('ext_data', {}).get('text')
-                    if not think_start:
-                        think_start = True
-                        pending_content += f'<think>\n{content}'
-                    else:
-                        pending_content += content
-            elif chunk.get('type', '') == 'error':
-                raise TboxAPIError(
-                    f'Tbox API 请求失败: status_code={chunk.get("status_code")} message={chunk.get("message")} request_id={chunk.get("request_id")} '
-                )
-
-            if idx_msg % 8 == 0:
-                yield provider_message.MessageChunk(
-                    role='assistant',
-                    content=pending_content,
-                    is_final=False,
-                )
-
-        # Tbox不返回END事件，默认发一个最终消息
-        yield provider_message.MessageChunk(
-            role='assistant',
-            content=pending_content,
-            is_final=True,
-        )
-
-    async def run(self, query: pipeline_query.Query) -> typing.AsyncGenerator[provider_message.Message, None]:
-        """运行"""
-        msg_seq = 0
-        async for msg in self._agent_messages(query):
-            if isinstance(msg, provider_message.MessageChunk):
-                msg_seq += 1
-                msg.msg_sequence = msg_seq
-            yield msg

src/langbot/pkg/provider/runners/weknoraapi.py

@@ -1,351 +0,0 @@
-from __future__ import annotations
-
-import typing
-import json
-
-
-from langbot.pkg.provider import runner
-from langbot.pkg.core import app
-import langbot_plugin.api.entities.builtin.provider.message as provider_message
-import langbot_plugin.api.entities.builtin.pipeline.query as pipeline_query
-from langbot.libs.weknora_api import client, errors
-
-
-@runner.runner_class('weknora-api')
-class WeKnoraAPIRunner(runner.RequestRunner):
-    """WeKnora API 对话请求器"""
-
-    weknora_client: client.AsyncWeKnoraClient
-
-    def __init__(self, ap: app.Application, pipeline_config: dict):
-        super().__init__(ap, pipeline_config)
-
-        valid_app_types = ['chat', 'agent']
-        if self.pipeline_config['ai']['weknora-api']['app-type'] not in valid_app_types:
-            raise errors.WeKnoraAPIError(
-                f'不支持的 WeKnora 应用类型: {self.pipeline_config["ai"]["weknora-api"]["app-type"]}'
-            )
-
-        api_key = self.pipeline_config['ai']['weknora-api'].get('api-key', '').strip()
-        if not api_key:
-            raise errors.WeKnoraAPIError(
-                'WeKnora API Key 未配置，请在流水线的 WeKnora API 配置中填入 API Key '
-                '(从 WeKnora 前端 设置 → API Keys 生成)'
-            )
-
-        base_url = self.pipeline_config['ai']['weknora-api'].get('base-url', '').strip()
-        if not base_url:
-            raise errors.WeKnoraAPIError('WeKnora Base URL 未配置，请填入服务器地址，例如 http://localhost:8080/api/v1')
-
-        self.weknora_client = client.AsyncWeKnoraClient(
-            api_key=api_key,
-            base_url=base_url,
-        )
-
-    async def _extract_plain_text(self, query: pipeline_query.Query) -> str:
-        """从用户消息中提取纯文本内容"""
-        plain_text = ''
-        if isinstance(query.user_message.content, str):
-            plain_text = query.user_message.content
-        elif isinstance(query.user_message.content, list):
-            for ce in query.user_message.content:
-                if ce.type == 'text':
-                    plain_text += ce.text
-
-        if not plain_text:
-            plain_text = self.pipeline_config['ai']['weknora-api'].get('base-prompt', '')
-
-        return plain_text
-
-    async def _ensure_session(self, query: pipeline_query.Query) -> str:
-        """确保会话存在，如果不存在则创建"""
-        session_id = query.session.using_conversation.uuid or ''
-
-        if not session_id:
-            user_tag = f'{query.session.launcher_type.value}_{query.session.launcher_id}'
-            session_id = await self.weknora_client.create_session(title=f'IM Chat - {user_tag}')
-            query.session.using_conversation.uuid = session_id
-
-        return session_id
-
-    async def _agent_chat_messages(
-        self, query: pipeline_query.Query
-    ) -> typing.AsyncGenerator[provider_message.Message, None]:
-        """调用 Agent 智能对话（非流式聚合输出）"""
-        session_id = await self._ensure_session(query)
-        plain_text = await self._extract_plain_text(query)
-        user_tag = f'{query.session.launcher_type.value}_{query.session.launcher_id}'
-
-        config = self.pipeline_config['ai']['weknora-api']
-        agent_id = config.get('agent-id', 'builtin-smart-reasoning')
-        knowledge_base_ids = config.get('knowledge-base-ids', [])
-        web_search_enabled = config.get('web-search-enabled', False)
-        timeout = config.get('timeout', 120)
-
-        full_answer = ''
-        chunk = None
-
-        async for chunk in self.weknora_client.agent_chat(
-            session_id=session_id,
-            query=plain_text,
-            user=user_tag,
-            agent_id=agent_id,
-            knowledge_base_ids=knowledge_base_ids,
-            web_search_enabled=web_search_enabled,
-            timeout=timeout,
-        ):
-            self.ap.logger.debug('weknora-agent-chunk: ' + str(chunk))
-
-            response_type = chunk.get('response_type', '')
-            content = chunk.get('content', '')
-
-            if response_type == 'tool_call':
-                # 工具调用
-                tool_data = chunk.get('data', {})
-                tool_name = tool_data.get('tool_name', '')
-                if tool_name:
-                    yield provider_message.Message(
-                        role='assistant',
-                        tool_calls=[
-                            provider_message.ToolCall(
-                                id=chunk.get('id', ''),
-                                type='function',
-                                function=provider_message.FunctionCall(
-                                    name=tool_name,
-                                    arguments=json.dumps(tool_data.get('arguments', {})),
-                                ),
-                            )
-                        ],
-                    )
-
-            elif response_type == 'answer':
-                if content:
-                    full_answer += content
-
-            elif response_type == 'error':
-                raise errors.WeKnoraAPIError(f'WeKnora 服务错误: {content}')
-
-        if chunk is None:
-            raise errors.WeKnoraAPIError('WeKnora API 没有返回任何响应，请检查网络连接和API配置')
-
-        if full_answer:
-            yield provider_message.Message(
-                role='assistant',
-                content=full_answer,
-            )
-
-    async def _chat_messages(
-        self, query: pipeline_query.Query
-    ) -> typing.AsyncGenerator[provider_message.Message, None]:
-        """调用知识库 RAG 问答（非流式聚合输出）"""
-        session_id = await self._ensure_session(query)
-        plain_text = await self._extract_plain_text(query)
-        user_tag = f'{query.session.launcher_type.value}_{query.session.launcher_id}'
-
-        config = self.pipeline_config['ai']['weknora-api']
-        agent_id = config.get('agent-id', 'builtin-quick-answer')
-        knowledge_base_ids = config.get('knowledge-base-ids', [])
-        timeout = config.get('timeout', 120)
-
-        full_answer = ''
-        chunk = None
-
-        async for chunk in self.weknora_client.knowledge_chat(
-            session_id=session_id,
-            query=plain_text,
-            user=user_tag,
-            agent_id=agent_id,
-            knowledge_base_ids=knowledge_base_ids,
-            timeout=timeout,
-        ):
-            self.ap.logger.debug('weknora-chat-chunk: ' + str(chunk))
-
-            response_type = chunk.get('response_type', '')
-            content = chunk.get('content', '')
-
-            if response_type == 'answer':
-                if content:
-                    full_answer += content
-
-            elif response_type == 'error':
-                raise errors.WeKnoraAPIError(f'WeKnora 服务错误: {content}')
-
-        if chunk is None:
-            raise errors.WeKnoraAPIError('WeKnora API 没有返回任何响应，请检查网络连接和API配置')
-
-        if full_answer:
-            yield provider_message.Message(
-                role='assistant',
-                content=full_answer,
-            )
-
-    async def _agent_chat_messages_chunk(
-        self, query: pipeline_query.Query
-    ) -> typing.AsyncGenerator[provider_message.MessageChunk, None]:
-        """调用 Agent 智能对话（流式输出）"""
-        session_id = await self._ensure_session(query)
-        plain_text = await self._extract_plain_text(query)
-        user_tag = f'{query.session.launcher_type.value}_{query.session.launcher_id}'
-
-        config = self.pipeline_config['ai']['weknora-api']
-        agent_id = config.get('agent-id', 'builtin-smart-reasoning')
-        knowledge_base_ids = config.get('knowledge-base-ids', [])
-        web_search_enabled = config.get('web-search-enabled', False)
-        timeout = config.get('timeout', 120)
-
-        pending_answer = ''
-        message_idx = 0
-        is_final = False
-        chunk = None
-
-        async for chunk in self.weknora_client.agent_chat(
-            session_id=session_id,
-            query=plain_text,
-            user=user_tag,
-            agent_id=agent_id,
-            knowledge_base_ids=knowledge_base_ids,
-            web_search_enabled=web_search_enabled,
-            timeout=timeout,
-        ):
-            self.ap.logger.debug('weknora-agent-chunk: ' + str(chunk))
-
-            response_type = chunk.get('response_type', '')
-            content = chunk.get('content', '')
-            done = chunk.get('done', False)
-
-            if response_type == 'tool_call':
-                tool_data = chunk.get('data', {})
-                tool_name = tool_data.get('tool_name', '')
-                if tool_name:
-                    message_idx += 1
-                    yield provider_message.MessageChunk(
-                        role='assistant',
-                        tool_calls=[
-                            provider_message.ToolCall(
-                                id=chunk.get('id', ''),
-                                type='function',
-                                function=provider_message.FunctionCall(
-                                    name=tool_name,
-                                    arguments=json.dumps(tool_data.get('arguments', {})),
-                                ),
-                            )
-                        ],
-                    )
-
-            elif response_type == 'answer':
-                message_idx += 1
-                if content:
-                    pending_answer += content
-
-                if done:
-                    is_final = True
-
-                # 每 8 个 chunk 输出一次，或最终输出
-                if message_idx % 8 == 0 or is_final:
-                    yield provider_message.MessageChunk(
-                        role='assistant',
-                        content=pending_answer,
-                        is_final=is_final,
-                    )
-
-            elif response_type == 'error':
-                raise errors.WeKnoraAPIError(f'WeKnora 服务错误: {content}')
-
-        if chunk is None:
-            raise errors.WeKnoraAPIError('WeKnora API 没有返回任何响应，请检查网络连接和API配置')
-
-        # 确保最终消息已发出
-        if not is_final and pending_answer:
-            yield provider_message.MessageChunk(
-                role='assistant',
-                content=pending_answer,
-                is_final=True,
-            )
-
-    async def _chat_messages_chunk(
-        self, query: pipeline_query.Query
-    ) -> typing.AsyncGenerator[provider_message.MessageChunk, None]:
-        """调用知识库 RAG 问答（流式输出）"""
-        session_id = await self._ensure_session(query)
-        plain_text = await self._extract_plain_text(query)
-        user_tag = f'{query.session.launcher_type.value}_{query.session.launcher_id}'
-
-        config = self.pipeline_config['ai']['weknora-api']
-        agent_id = config.get('agent-id', 'builtin-quick-answer')
-        knowledge_base_ids = config.get('knowledge-base-ids', [])
-        timeout = config.get('timeout', 120)
-
-        pending_answer = ''
-        message_idx = 0
-        is_final = False
-        chunk = None
-
-        async for chunk in self.weknora_client.knowledge_chat(
-            session_id=session_id,
-            query=plain_text,
-            user=user_tag,
-            agent_id=agent_id,
-            knowledge_base_ids=knowledge_base_ids,
-            timeout=timeout,
-        ):
-            self.ap.logger.debug('weknora-chat-chunk: ' + str(chunk))
-
-            response_type = chunk.get('response_type', '')
-            content = chunk.get('content', '')
-            done = chunk.get('done', False)
-
-            if response_type == 'answer':
-                message_idx += 1
-                if content:
-                    pending_answer += content
-
-                if done:
-                    is_final = True
-
-                if message_idx % 8 == 0 or is_final:
-                    yield provider_message.MessageChunk(
-                        role='assistant',
-                        content=pending_answer,
-                        is_final=is_final,
-                    )
-
-            elif response_type == 'error':
-                raise errors.WeKnoraAPIError(f'WeKnora 服务错误: {content}')
-
-        if chunk is None:
-            raise errors.WeKnoraAPIError('WeKnora API 没有返回任何响应，请检查网络连接和API配置')
-
-        if not is_final and pending_answer:
-            yield provider_message.MessageChunk(
-                role='assistant',
-                content=pending_answer,
-                is_final=True,
-            )
-
-    async def run(self, query: pipeline_query.Query) -> typing.AsyncGenerator[provider_message.Message, None]:
-        """运行请求"""
-        app_type = self.pipeline_config['ai']['weknora-api']['app-type']
-
-        if await query.adapter.is_stream_output_supported():
-            msg_idx = 0
-            if app_type == 'agent':
-                async for msg in self._agent_chat_messages_chunk(query):
-                    msg_idx += 1
-                    msg.msg_sequence = msg_idx
-                    yield msg
-            elif app_type == 'chat':
-                async for msg in self._chat_messages_chunk(query):
-                    msg_idx += 1
-                    msg.msg_sequence = msg_idx
-                    yield msg
-            else:
-                raise errors.WeKnoraAPIError(f'不支持的 WeKnora 应用类型: {app_type}')
-        else:
-            if app_type == 'agent':
-                async for msg in self._agent_chat_messages(query):
-                    yield msg
-            elif app_type == 'chat':
-                async for msg in self._chat_messages(query):
-                    yield msg
-            else:
-                raise errors.WeKnoraAPIError(f'不支持的 WeKnora 应用类型: {app_type}')

src/langbot/pkg/provider/tools/loaders/skill.py

@@ -10,6 +10,7 @@ if typing.TYPE_CHECKING:
     from langbot_plugin.api.entities.events import pipeline_query
 
 ACTIVATED_SKILLS_KEY = '_activated_skills'
+ACTIVATED_SKILL_NAMES_STATE_KEY = 'host.activated_skills'
 PIPELINE_BOUND_SKILLS_KEY = '_pipeline_bound_skills'
 SKILL_MOUNT_PREFIX = '/workspace/.skills'
 _SKILL_MOUNT_PATTERN = re.compile(r'/workspace/\.skills/([A-Za-z0-9_-]+)')
@@ -111,6 +112,29 @@ def restore_activated_skills(
     return restored
 
 
+def restore_activated_skills_from_state(
+    ap: app.Application,
+    query: pipeline_query.Query,
+    state: dict[str, dict[str, typing.Any]],
+) -> list[str]:
+    """Restore persisted activated skill names into Query variables.
+
+    The state value stores names only. Full skill metadata is rebuilt from the
+    current pipeline-visible skill cache so removed or unbound skills remain
+    unavailable to native exec/write/edit.
+    """
+    conversation_state = state.get('conversation', {}) if isinstance(state, dict) else {}
+    skill_names = normalize_skill_names(conversation_state.get(ACTIVATED_SKILL_NAMES_STATE_KEY))
+    restored: list[str] = []
+    for skill_name in skill_names:
+        skill_data = get_visible_skill(ap, query, skill_name)
+        if skill_data is None:
+            continue
+        register_activated_skill(query, skill_data)
+        restored.append(skill_name)
+    return restored
+
+
 def parse_skill_mount_path(sandbox_path: str) -> tuple[str | None, str]:
     normalized_path = str(sandbox_path or '/workspace').strip() or '/workspace'
     if normalized_path == SKILL_MOUNT_PREFIX:

src/langbot/pkg/provider/tools/loaders/skill_authoring.py

@@ -92,6 +92,7 @@ class SkillToolLoader(loader.ToolLoader):
 
         # Register activated skill for sandbox mount path resolution
         skill_loader.register_activated_skill(query, skill_data)
+        await skill_loader.persist_activated_skill(self.ap, query, skill_name)
 
         # Return SKILL.md content as Tool Result (injects into context)
         instructions = skill_data.get('instructions', '')

src/langbot/pkg/skill/manager.py

@@ -93,50 +93,3 @@ class SkillManager:
     def get_skill_by_name(self, name: str) -> dict | None:
         """Get skill data by name."""
         return self.skills.get(name)
-
-    def get_skill_index(self, bound_skills: list[str] | None = None) -> str:
-        """Render the pipeline-visible skills as a short ``name: description``
-        index suitable for the system prompt.
-
-        ``bound_skills`` follows the same convention as
-        ``query.variables['_pipeline_bound_skills']``: ``None`` means every
-        loaded skill is exposed; an explicit list filters to that subset.
-        Returns an empty string when no skills are visible.
-        """
-        lines: list[str] = []
-        for skill in self.skills.values():
-            name = skill.get('name')
-            if not name:
-                continue
-            if bound_skills is not None and name not in bound_skills:
-                continue
-            display = skill.get('display_name') or name
-            description = (skill.get('description') or '').strip().replace('\n', ' ')
-            lines.append(f'- {name} ({display}): {description}')
-
-        if not lines:
-            return ''
-        return 'Available Skills:\n' + '\n'.join(lines)
-
-    def build_skill_aware_prompt_addition(self, bound_skills: list[str] | None = None) -> str:
-        """Build the system-prompt addendum that makes the LLM aware of the
-        pipeline-visible skills.
-
-        Only metadata (name + description) is injected — the full SKILL.md is
-        loaded later via the ``activate`` Tool Call, protecting KV cache and
-        matching Claude Code's progressive disclosure pattern. Returns an
-        empty string when no skills are visible (no prompt change at all).
-        """
-        skill_index = self.get_skill_index(bound_skills)
-        if not skill_index:
-            return ''
-        return (
-            '\n\n'
-            f'{skill_index}\n\n'
-            "When the user's request clearly matches one or more skills "
-            'based on their descriptions above, call the `activate` tool with '
-            'the skill name to load its full instructions. Only the name and '
-            'description are visible here; the actual instructions arrive as '
-            'the tool result. If no skill is a clear match, respond normally '
-            'without activating any skill.'
-        )

src/langbot/templates/config.yaml

@@ -113,6 +113,19 @@ plugin:
     binary_storage:
         # Max bytes for a single plugin binary storage value
         max_value_bytes: 10485760
+agent_runner:
+    # Host-level admin permissions for trusted control plugins. These plugins
+    # can use existing plugin action handlers to inspect or manage AgentRunner
+    # infrastructure across runner/plugin boundaries. Keep empty unless you
+    # fully trust the plugin identity.
+    #
+    # Example:
+    # admin_plugins:
+    #   - identity: langbot/agent-runner-control
+    #     permissions:
+    #       - agent_run:admin
+    #       - runtime:admin
+    admin_plugins: []
 monitoring:
     auto_cleanup:
         # Enable automatic cleanup of expired monitoring records

src/langbot/templates/default-pipeline-config.json

@@ -38,58 +38,10 @@
     },
     "ai": {
         "runner": {
-            "runner": "local-agent",
+            "id": "",
             "expire-time": 0
         },
-        "local-agent": {
-            "model": {
-                "primary": "",
-                "fallbacks": []
-            },
-            "max-round": 10,
-            "prompt": [
-                {
-                    "role": "system",
-                    "content": "You are a helpful assistant. When tools are available, use them for exact calculations, data processing, and code execution instead of guessing. Unless the user explicitly asks for code or a script, return the result directly instead of printing the generated code."
-                }
-            ],
-            "knowledge-bases": [],
-            "box-session-id-template": "{launcher_type}_{launcher_id}",
-            "rerank-model": "",
-            "rerank-top-k": 5
-        },
-        "dify-service-api": {
-            "base-url": "https://api.dify.ai/v1",
-            "app-type": "chat",
-            "api-key": "your-api-key",
-            "timeout": 30
-        },
-        "dashscope-app-api": {
-            "app-type": "agent",
-            "api-key": "your-api-key",
-            "app-id": "your-app-id",
-            "references-quote": "参考资料来自:"
-        },
-        "n8n-service-api": {
-            "webhook-url": "http://your-n8n-webhook-url",
-            "auth-type": "none",
-            "basic-username": "",
-            "basic-password": "",
-            "jwt-secret": "",
-            "jwt-algorithm": "HS256",
-            "header-name": "",
-            "header-value": "",
-            "timeout": 120,
-            "output-key": "response"
-        },
-        "langflow-api": {
-            "base-url": "http://localhost:7860",
-            "api-key": "your-api-key",
-            "flow-id": "your-flow-id",
-            "input-type": "chat",
-            "output-type": "chat",
-            "tweaks": "{}"
-        }
+        "runner_config": {}
     },
     "output": {
         "long-text-processing": {

src/langbot/templates/legacy/pipeline.json

@@ -34,11 +34,5 @@
                 "limit": 60
             }
         }
-    },
-    "msg-truncate": {
-        "method": "round",
-        "round": {
-            "max-round": 10
-        }
     }
-}
+}

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

@@ -11,50 +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
-          - name: weknora-api
-            label:
-              en_US: WeKnora API
-              zh_Hans: WeKnora API
-          - name: deerflow-api
-            label:
-              en_US: DeerFlow API
-              zh_Hans: DeerFlow API
+        # Options and default are dynamically populated from AgentRunnerRegistry
       - name: expire-time
         label:
           en_US: Conversation expire time (seconds)
@@ -75,802 +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_scope_editable
-          operator: eq
-          value: false
-        disabled_tooltip:
-          en_US: >-
-            Sandbox scope can't be changed: either the Box sandbox is disabled
-            or unavailable (enable it in config.yaml with box.enabled = true and
-            ensure the runtime is reachable), or this deployment pins all
-            pipelines to a fixed scope.
-          zh_Hans: "无法修改沙箱作用域：Box 沙箱已禁用或不可用（请在配置中启用 box.enabled = true 并确认运行时连接正常），或本部署已将所有流水线固定为统一作用域。"
-          zh_Hant: "無法修改沙箱作用域：Box 沙箱已停用或無法使用（請在設定中啟用 box.enabled = true 並確認執行時連線正常），或本部署已將所有流水線固定為統一作用域。"
-          ja_JP: "サンドボックススコープを変更できません：Box サンドボックスが無効/利用不可（設定で box.enabled = true にしてランタイム接続を確認）、またはこのデプロイがすべてのパイプラインを固定スコープに制限しています。"
-          vi_VN: "Không thể thay đổi phạm vi sandbox：Box sandbox bị tắt hoặc không khả dụng (bật box.enabled = true và đảm bảo runtime hoạt động), hoặc bản triển khai này cố định mọi pipeline về một phạm vi."
-          th_TH: "ไม่สามารถเปลี่ยนขอบเขต Sandbox：Box sandbox ถูกปิดหรือไม่พร้อมใช้งาน (เปิด box.enabled = true และตรวจสอบรันไทม์) หรือการ deploy นี้ล็อกทุก pipeline ไว้ที่ขอบเขตเดียว"
-          es_ES: "No se puede cambiar el alcance del sandbox: el sandbox de Box está desactivado o no disponible (actívelo con box.enabled = true y verifique el runtime), o este despliegue fija todas las pipelines a un alcance único."
-          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: '{}'
-  - name: weknora-api
-    label:
-      en_US: WeKnora API
-      zh_Hans: WeKnora API
-    description:
-      en_US: Configure the WeKnora API of the pipeline
-      zh_Hans: 配置 WeKnora API
-    config:
-      - name: base-url
-        label:
-          en_US: Base URL
-          zh_Hans: 基础 URL
-        description:
-          en_US: The base URL of the WeKnora server (with /api/v1)
-          zh_Hans: WeKnora 服务器的基础 URL（包含 /api/v1）
-        type: string
-        required: true
-        default: 'http://localhost:8080/api/v1'
-      - name: api-key
-        label:
-          en_US: API Key
-          zh_Hans: API 密钥
-        description:
-          en_US: The API key for WeKnora, generated from WeKnora frontend Settings → API Keys
-          zh_Hans: WeKnora 的 API 密钥，从 WeKnora 前端 设置 → API Keys 生成
-        type: string
-        required: true
-        default: ''
-      - name: app-type
-        label:
-          en_US: App Type
-          zh_Hans: 应用类型
-        type: select
-        required: true
-        default: agent
-        options:
-          - name: agent
-            label:
-              en_US: Agent (Smart Reasoning)
-              zh_Hans: Agent（智能推理）
-          - name: chat
-            label:
-              en_US: Chat (Knowledge Base RAG)
-              zh_Hans: 聊天（知识库 RAG）
-      - name: agent-id
-        label:
-          en_US: Agent ID
-          zh_Hans: 智能体 ID
-        description:
-          en_US: The Agent ID to use. Built-in agents include builtin-quick-answer, builtin-smart-reasoning, builtin-data-analyst
-          zh_Hans: 要使用的智能体 ID。内置智能体：builtin-quick-answer、builtin-smart-reasoning、builtin-data-analyst
-        type: string
-        required: true
-        default: 'builtin-smart-reasoning'
-      - name: knowledge-base-ids
-        label:
-          en_US: Knowledge Base IDs
-          zh_Hans: 知识库 ID 列表
-        description:
-          en_US: List of WeKnora knowledge base IDs to use (one per line)
-          zh_Hans: 要使用的 WeKnora 知识库 ID 列表（每行一个）
-        type: array
-        required: false
-        default: []
-      - name: web-search-enabled
-        label:
-          en_US: Enable Web Search
-          zh_Hans: 启用网络搜索
-        description:
-          en_US: Whether to enable web search in agent mode
-          zh_Hans: 在 Agent 模式下是否启用网络搜索
-        type: boolean
-        required: false
-        default: false
-      - name: timeout
-        label:
-          en_US: Timeout
-          zh_Hans: 超时时间
-        description:
-          en_US: Request timeout in seconds
-          zh_Hans: 请求超时时间（秒）
-        type: integer
-        required: false
-        default: 120
-      - name: base-prompt
-        label:
-          en_US: Base Prompt
-          zh_Hans: 基础提示词
-        description:
-          en_US: Default prompt when user message is empty (e.g. only images)
-          zh_Hans: 当用户消息为空（例如仅图片）时使用的默认提示词
-        type: string
-        required: false
-        default: '请回答用户的问题。'
-  - name: deerflow-api
-    label:
-      en_US: DeerFlow API
-      zh_Hans: DeerFlow API
-    description:
-      en_US: Configure the DeerFlow LangGraph API of the pipeline
-      zh_Hans: 配置 DeerFlow LangGraph API
-    config:
-      - name: api-base
-        label:
-          en_US: API Base URL
-          zh_Hans: API 基础 URL
-        description:
-          en_US: The base URL of the DeerFlow server (e.g. http://127.0.0.1:2026)
-          zh_Hans: DeerFlow 服务器的基础 URL（例如 http://127.0.0.1:2026）
-        type: string
-        required: true
-        default: 'http://127.0.0.1:2026'
-      - name: api-key
-        label:
-          en_US: API Key
-          zh_Hans: API 密钥
-        description:
-          en_US: Optional API key for DeerFlow (leave empty if not required)
-          zh_Hans: DeerFlow 的 API 密钥（如果不需要可留空）
-        type: string
-        required: false
-        default: ''
-      - name: auth-header
-        label:
-          en_US: Auth Header Name
-          zh_Hans: 鉴权请求头名称
-        description:
-          en_US: Custom auth header name. Leave empty to use "x-api-key"
-          zh_Hans: 自定义鉴权请求头名称，留空则使用 "x-api-key"
-        type: string
-        required: false
-        default: ''
-      - name: assistant-id
-        label:
-          en_US: Assistant ID
-          zh_Hans: 助手 ID
-        description:
-          en_US: The DeerFlow assistant/graph id (default lead_agent)
-          zh_Hans: DeerFlow 助手/图 ID（默认 lead_agent）
-        type: string
-        required: true
-        default: 'lead_agent'
-      - name: model-name
-        label:
-          en_US: Model Name
-          zh_Hans: 模型名称
-        description:
-          en_US: Optional model override forwarded to DeerFlow configurable
-          zh_Hans: 可选的模型名称覆盖，会作为 configurable 转发给 DeerFlow
-        type: string
-        required: false
-        default: ''
-      - name: thinking-enabled
-        label:
-          en_US: Enable Thinking
-          zh_Hans: 启用思考
-        description:
-          en_US: Whether to enable DeerFlow thinking mode
-          zh_Hans: 是否启用 DeerFlow 思考模式
-        type: boolean
-        required: false
-        default: false
-      - name: plan-mode
-        label:
-          en_US: Plan Mode
-          zh_Hans: 规划模式
-        description:
-          en_US: Whether to enable DeerFlow plan mode
-          zh_Hans: 是否启用 DeerFlow 规划模式
-        type: boolean
-        required: false
-        default: false
-      - name: subagent-enabled
-        label:
-          en_US: Enable Subagents
-          zh_Hans: 启用子代理
-        description:
-          en_US: Whether to enable parallel subagent execution
-          zh_Hans: 是否启用并行子代理执行
-        type: boolean
-        required: false
-        default: false
-      - name: max-concurrent-subagents
-        label:
-          en_US: Max Concurrent Subagents
-          zh_Hans: 最大并发子代理数
-        description:
-          en_US: Maximum number of concurrent subagents (only effective when subagents are enabled)
-          zh_Hans: 最大并发子代理数（仅在启用子代理时生效）
-        type: integer
-        required: false
-        default: 3
-      - name: timeout
-        label:
-          en_US: Timeout
-          zh_Hans: 超时时间
-        description:
-          en_US: Request timeout in seconds (DeerFlow runs may take a long time)
-          zh_Hans: 请求超时时间（秒），DeerFlow 运行可能耗时较长
-        type: integer
-        required: false
-        default: 300
-      - name: recursion-limit
-        label:
-          en_US: Recursion Limit
-          zh_Hans: 递归上限
-        description:
-          en_US: LangGraph recursion limit for a single run
-          zh_Hans: 单次运行的 LangGraph 递归上限
-        type: integer
-        required: false
-        default: 1000
+  # 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