feat(agent-runner): add event-first context facts and pull APIs

Add EventLog and Transcript persistence entities for storing auditable
event facts and conversation history projection. Implement event-first
AgentRunContext builder that produces Protocol v1 compliant context
payloads with required fields: event, delivery, context (ContextAccess).

Key changes:
- EventLog ORM: auditable event records with indexes
- Transcript ORM: conversation history projection with composite indexes
- AgentRunContextBuilder: Protocol v1 payload with delivery, context, bootstrap
- EventLogStore/TranscriptStore: async stores for fact sources
- Host action handlers: HISTORY_PAGE, HISTORY_SEARCH, EVENT_GET, EVENT_PAGE
- Context validation: build_context output validates via SDK AgentRunContext
- Alembic migration for event_log and transcript tables
- Alembic env.py imports all ORM models for autogenerate discovery

Legacy compatibility: max-round messages go into bootstrap.messages and
compatibility.legacy_messages, not top-level messages field.

tests/unit_tests/agent/test_context_builder_params_state.py

@@ -420,9 +420,12 @@ class TestBuildParamsInContext:
 
         context = await builder.build_context(query, descriptor, resources)
 
-        assert 'params' in context
-        assert context['params']['public_param'] == 'value'
-        assert '_private' not in context['params']
+        # Protocol v1: params is in compatibility.extra
+        assert 'compatibility' in context
+        assert 'extra' in context['compatibility']
+        assert 'params' in context['compatibility']['extra']
+        assert context['compatibility']['extra']['params']['public_param'] == 'value'
+        assert '_private' not in context['compatibility']['extra']['params']
 
     @pytest.mark.asyncio
     async def test_params_and_state_both_present(self):
@@ -454,10 +457,12 @@ class TestBuildParamsInContext:
 
         context = await builder.build_context(query, descriptor, resources)
 
-        # params should have public vars
-        assert 'params' in context
-        assert context['params']['workflow_input'] == 'user_question'
-        assert context['params']['sender_name'] == 'John'
+        # Protocol v1: params is in compatibility.extra
+        assert 'compatibility' in context
+        assert 'extra' in context['compatibility']
+        assert 'params' in context['compatibility']['extra']
+        assert context['compatibility']['extra']['params']['workflow_input'] == 'user_question'
+        assert context['compatibility']['extra']['params']['sender_name'] == 'John'
 
         # state should have seeded conversation_id
         assert 'state' in context
@@ -490,6 +495,10 @@ class TestBuildParamsInContext:
 
         context = await builder.build_context(query, descriptor, resources)
 
-        assert context['prompt'][0]['content'] == 'Effective prompt'
+        # Protocol v1: prompt is in compatibility.extra
+        assert 'compatibility' in context
+        assert 'extra' in context['compatibility']
+        assert 'prompt' in context['compatibility']['extra']
+        assert context['compatibility']['extra']['prompt'][0]['content'] == 'Effective prompt'
         assert context['runtime']['metadata']['streaming_supported'] is True
         assert context['runtime']['metadata']['remove_think'] is True

tests/unit_tests/agent/test_context_validation.py

@@ -0,0 +1,232 @@
+"""Test that LangBot context builder output validates against SDK AgentRunContext."""
+from __future__ import annotations
+
+import pytest
+from unittest.mock import MagicMock, AsyncMock, patch
+import uuid
+
+# SDK imports for validation
+from langbot_plugin.api.entities.builtin.agent_runner.context import AgentRunContext
+from langbot_plugin.api.entities.builtin.agent_runner.event import AgentEventContext
+from langbot_plugin.api.entities.builtin.agent_runner.delivery import DeliveryContext
+from langbot_plugin.api.entities.builtin.agent_runner.context_access import ContextAccess
+from langbot_plugin.api.entities.builtin.agent_runner.trigger import AgentTrigger
+from langbot_plugin.api.entities.builtin.agent_runner.input import AgentInput
+from langbot_plugin.api.entities.builtin.agent_runner.resources import AgentResources
+from langbot_plugin.api.entities.builtin.agent_runner.runtime import AgentRuntimeContext
+from langbot_plugin.api.entities.builtin.agent_runner.state import AgentRunState
+
+# LangBot imports
+from langbot.pkg.agent.runner.context_builder import (
+    AgentRunContextBuilder,
+    AgentTrigger as BuilderTrigger,
+    ConversationContext as BuilderConversation,
+    AgentInput as BuilderInput,
+    AgentRunState as BuilderState,
+    AgentResources as BuilderResources,
+    AgentRuntimeContext as BuilderRuntime,
+)
+from langbot.pkg.agent.runner.host_models import AgentEventEnvelope, AgentBinding, BindingScope
+from langbot.pkg.core import app
+
+
+class TestContextValidation:
+    """Test that context builder output validates against SDK AgentRunContext."""
+
+    def _make_mock_app(self):
+        """Create a mock application."""
+        mock_app = MagicMock(spec=app.Application)
+        mock_app.ver_mgr = MagicMock()
+        mock_app.ver_mgr.get_current_version = MagicMock(return_value="1.0.0")
+        mock_app.persistence_mgr = MagicMock()
+        mock_app.persistence_mgr.get_db_engine = MagicMock()
+        mock_app.logger = MagicMock()
+        return mock_app
+
+    def _make_event_envelope(self) -> AgentEventEnvelope:
+        """Create a test event envelope."""
+        from langbot_plugin.api.entities.builtin.agent_runner.event import ActorContext
+        from langbot_plugin.api.entities.builtin.agent_runner.input import AgentInput as EventInput
+        from langbot_plugin.api.entities.builtin.agent_runner.delivery import DeliveryContext
+
+        return AgentEventEnvelope(
+            event_id="evt_1",
+            event_type="message.received",
+            event_time=1700000000,
+            source="platform",
+            bot_id="bot_1",
+            workspace_id=None,
+            conversation_id="conv_1",
+            thread_id=None,
+            actor=ActorContext(
+                actor_type="user",
+                actor_id="user_1",
+                actor_name="Test User",
+            ),
+            subject=None,
+            input=EventInput(text="Hello world"),
+            delivery=DeliveryContext(surface="test"),
+        )
+
+    def _make_binding(self) -> AgentBinding:
+        """Create a test binding."""
+        return AgentBinding(
+            binding_id="binding_1",
+            scope=BindingScope(scope_type="pipeline", scope_id="pipeline_1"),
+            event_types=["message.received"],
+            runner_id="plugin:test/plugin/runner",
+            runner_config={"timeout": 300},
+            pipeline_uuid="pipeline_1",
+            enabled=True,
+        )
+
+    def _make_resources(self) -> BuilderResources:
+        """Create test resources."""
+        return {
+            'models': [],
+            'tools': [],
+            'knowledge_bases': [],
+            'files': [],
+            'storage': {'plugin_storage': True, 'workspace_storage': True},
+            'platform_capabilities': {},
+        }
+
+    def _make_descriptor(self):
+        """Create a mock runner descriptor."""
+        descriptor = MagicMock()
+        descriptor.id = "plugin:test/plugin/runner"
+        descriptor.protocol_version = "1"
+        descriptor.permissions = {
+            'history': ['page', 'search'],
+            'events': ['get', 'page'],
+        }
+        return descriptor
+
+    @pytest.mark.asyncio
+    async def test_build_context_from_event_validates(self):
+        """Test that build_context_from_event output validates against SDK AgentRunContext."""
+        mock_app = self._make_mock_app()
+        builder = AgentRunContextBuilder(mock_app)
+
+        event = self._make_event_envelope()
+        binding = self._make_binding()
+        resources = self._make_resources()
+        descriptor = self._make_descriptor()
+
+        # Build context
+        context_dict = await builder.build_context_from_event(
+            event=event,
+            binding=binding,
+            descriptor=descriptor,
+            resources=resources,
+        )
+
+        # Validate it can be parsed by SDK AgentRunContext
+        # This will raise ValidationError if invalid
+        validated = AgentRunContext.model_validate(context_dict)
+
+        # Verify required fields
+        assert validated.run_id is not None
+        assert validated.event is not None
+        assert isinstance(validated.event, AgentEventContext)
+        assert validated.delivery is not None
+        assert isinstance(validated.delivery, DeliveryContext)
+        assert validated.context is not None
+        assert isinstance(validated.context, ContextAccess)
+        assert validated.input is not None
+        assert isinstance(validated.input, AgentInput)
+        assert validated.resources is not None
+        assert isinstance(validated.resources, AgentResources)
+        assert validated.runtime is not None
+        assert isinstance(validated.runtime, AgentRuntimeContext)
+
+        # Verify event context
+        assert validated.event.event_id == "evt_1"
+        assert validated.event.event_type == "message.received"
+        assert validated.event.source == "platform"
+
+        # Verify delivery context
+        assert validated.delivery.surface == "test"
+
+        # Verify input
+        assert validated.input.text == "Hello world"
+
+    @pytest.mark.asyncio
+    async def test_build_context_from_event_has_no_legacy_top_level_fields(self):
+        """Test that build_context_from_event does NOT have top-level messages/prompt/params."""
+        mock_app = self._make_mock_app()
+        builder = AgentRunContextBuilder(mock_app)
+
+        event = self._make_event_envelope()
+        binding = self._make_binding()
+        resources = self._make_resources()
+        descriptor = self._make_descriptor()
+
+        context_dict = await builder.build_context_from_event(
+            event=event,
+            binding=binding,
+            descriptor=descriptor,
+            resources=resources,
+        )
+
+        # Protocol v1 does NOT have these as core fields
+        assert 'messages' not in context_dict, "messages should not be top-level in Protocol v1"
+        assert 'prompt' not in context_dict, "prompt should not be top-level in Protocol v1"
+        assert 'params' not in context_dict, "params should not be top-level in Protocol v1"
+
+        # Protocol v1 DOES have these
+        assert 'delivery' in context_dict, "delivery is REQUIRED in Protocol v1"
+        assert 'context' in context_dict, "context (ContextAccess) is REQUIRED in Protocol v1"
+        assert 'bootstrap' in context_dict, "bootstrap should exist (can be None)"
+        assert 'compatibility' in context_dict, "compatibility should exist"
+        assert 'metadata' in context_dict, "metadata should exist"
+
+    @pytest.mark.asyncio
+    async def test_build_context_from_event_event_is_not_none(self):
+        """Test that event field is NOT None in Protocol v1."""
+        mock_app = self._make_mock_app()
+        builder = AgentRunContextBuilder(mock_app)
+
+        event = self._make_event_envelope()
+        binding = self._make_binding()
+        resources = self._make_resources()
+        descriptor = self._make_descriptor()
+
+        context_dict = await builder.build_context_from_event(
+            event=event,
+            binding=binding,
+            descriptor=descriptor,
+            resources=resources,
+        )
+
+        # event is REQUIRED in Protocol v1
+        assert context_dict.get('event') is not None, "event is REQUIRED for Protocol v1"
+
+        # Validate
+        validated = AgentRunContext.model_validate(context_dict)
+        assert validated.event is not None
+
+    @pytest.mark.asyncio
+    async def test_build_context_from_event_delivery_is_not_none(self):
+        """Test that delivery field is NOT None in Protocol v1."""
+        mock_app = self._make_mock_app()
+        builder = AgentRunContextBuilder(mock_app)
+
+        event = self._make_event_envelope()
+        binding = self._make_binding()
+        resources = self._make_resources()
+        descriptor = self._make_descriptor()
+
+        context_dict = await builder.build_context_from_event(
+            event=event,
+            binding=binding,
+            descriptor=descriptor,
+            resources=resources,
+        )
+
+        # delivery is REQUIRED in Protocol v1
+        assert context_dict.get('delivery') is not None, "delivery is REQUIRED for Protocol v1"
+
+        # Validate
+        validated = AgentRunContext.model_validate(context_dict)
+        assert validated.delivery is not None

tests/unit_tests/agent/test_event_first_protocol.py

@@ -0,0 +1,431 @@
+"""Tests for event-first Protocol v1 entities and Pipeline compatibility adapter.
+
+Tests cover:
+1. Pipeline Query -> AgentEventEnvelope conversion
+2. Pipeline config -> AgentBinding conversion
+3. AgentRunContext not inlining full history by default
+4. Legacy max-round only affecting bootstrap/compat adapter
+5. Event-first run() entry point
+"""
+from __future__ import annotations
+
+import pytest
+from unittest.mock import Mock, MagicMock, patch
+import typing
+
+# Import SDK entities
+from langbot_plugin.api.entities.builtin.agent_runner.event import (
+    AgentEventContext,
+    ConversationContext,
+    ActorContext,
+    SubjectContext,
+)
+from langbot_plugin.api.entities.builtin.agent_runner.input import AgentInput
+from langbot_plugin.api.entities.builtin.agent_runner.trigger import AgentTrigger
+from langbot_plugin.api.entities.builtin.agent_runner.context import AgentRunContext
+from langbot_plugin.api.entities.builtin.agent_runner.result import (
+    AgentRunResult,
+    AgentRunResultType,
+)
+from langbot_plugin.api.entities.builtin.agent_runner.capabilities import (
+    AgentRunnerCapabilities,
+)
+from langbot_plugin.api.entities.builtin.agent_runner.permissions import (
+    AgentRunnerPermissions,
+)
+from langbot_plugin.api.entities.builtin.agent_runner.context_policy import (
+    AgentRunnerContextPolicy,
+)
+from langbot_plugin.api.entities.builtin.agent_runner.manifest import (
+    AgentRunnerManifest,
+)
+
+# Import LangBot host models
+from langbot.pkg.agent.runner.host_models import (
+    AgentEventEnvelope,
+    AgentBinding,
+    BindingScope,
+    ResourcePolicy,
+    StatePolicy,
+    DeliveryPolicy,
+)
+from langbot.pkg.agent.runner.pipeline_compat_adapter import PipelineCompatAdapter
+
+
+class TestPipelineQueryToEventEnvelope:
+    """Test Pipeline Query -> AgentEventEnvelope conversion."""
+
+    def test_query_to_event_basic_fields(self, mock_query):
+        """Test basic field conversion from Query to Event envelope."""
+        event = PipelineCompatAdapter.query_to_event(mock_query)
+
+        assert event.event_type == "message.received"
+        assert event.source == "pipeline_compat"
+        assert event.bot_id == mock_query.bot_uuid
+        assert event.actor is not None
+        assert event.actor.actor_type == "user"
+
+    def test_query_to_event_input(self, mock_query):
+        """Test input conversion from Query."""
+        event = PipelineCompatAdapter.query_to_event(mock_query)
+
+        assert event.input is not None
+        assert event.input.text == "Hello world"
+
+    def test_query_to_event_conversation(self, mock_query):
+        """Test conversation context extraction."""
+        event = PipelineCompatAdapter.query_to_event(mock_query)
+
+        # Conversation may be None if no session
+        if event.conversation_id:
+            assert event.conversation_id is not None
+
+    def test_query_to_event_delivery_context(self, mock_query):
+        """Test delivery context extraction."""
+        event = PipelineCompatAdapter.query_to_event(mock_query)
+
+        assert event.delivery is not None
+        assert event.delivery.surface == "platform"
+        assert isinstance(event.delivery.supports_streaming, bool)
+
+
+class TestPipelineConfigToBinding:
+    """Test Pipeline config -> AgentBinding conversion."""
+
+    def test_config_to_binding_runner_id(self, mock_query):
+        """Test binding runner_id extraction."""
+        binding = PipelineCompatAdapter.pipeline_config_to_binding(
+            mock_query, "plugin:author/plugin/runner"
+        )
+
+        assert binding.runner_id == "plugin:author/plugin/runner"
+
+    def test_config_to_binding_scope(self, mock_query):
+        """Test binding scope extraction."""
+        binding = PipelineCompatAdapter.pipeline_config_to_binding(
+            mock_query, "plugin:test/plugin/runner"
+        )
+
+        assert binding.scope.scope_type == "pipeline"
+        assert binding.scope.scope_id == mock_query.pipeline_uuid
+
+    def test_config_to_binding_max_round(self, mock_query_with_max_round):
+        """Test max_round extraction for compatibility adapter."""
+        binding = PipelineCompatAdapter.pipeline_config_to_binding(
+            mock_query_with_max_round, "plugin:test/plugin/runner"
+        )
+
+        # max_round should be captured but NOT in Protocol v1 entities
+        assert binding.max_round == 10
+
+    def test_config_to_binding_no_max_round(self, mock_query):
+        """Test binding without max_round."""
+        binding = PipelineCompatAdapter.pipeline_config_to_binding(
+            mock_query, "plugin:test/plugin/runner"
+        )
+
+        # max_round may be None
+        assert binding.max_round is None
+
+
+class TestAgentRunContextProtocolV1:
+    """Test AgentRunContext Protocol v1 behavior."""
+
+    def test_sdk_context_event_required(self):
+        """Test that event is required in Protocol v1 context."""
+        trigger = AgentTrigger(type="message.received")
+        event = AgentEventContext(
+            event_id="evt_1",
+            event_type="message.received",
+            source="platform",
+        )
+        input = AgentInput(text="Hello")
+        from langbot_plugin.api.entities.builtin.agent_runner.resources import AgentResources
+        from langbot_plugin.api.entities.builtin.agent_runner.runtime import AgentRuntimeContext
+        from langbot_plugin.api.entities.builtin.agent_runner.delivery import DeliveryContext
+
+        ctx = AgentRunContext(
+            run_id="run_1",
+            trigger=trigger,
+            event=event,
+            input=input,
+            delivery=DeliveryContext(surface="platform"),
+            resources=AgentResources(),
+            runtime=AgentRuntimeContext(),
+        )
+
+        assert ctx.event is not None
+        assert ctx.event.event_type == "message.received"
+
+    def test_sdk_context_messages_default_empty(self):
+        """Test that messages default to empty (not full history)."""
+        trigger = AgentTrigger(type="message.received")
+        event = AgentEventContext(
+            event_id="evt_1",
+            event_type="message.received",
+            source="platform",
+        )
+        input = AgentInput(text="Hello")
+        from langbot_plugin.api.entities.builtin.agent_runner.resources import AgentResources
+        from langbot_plugin.api.entities.builtin.agent_runner.runtime import AgentRuntimeContext
+        from langbot_plugin.api.entities.builtin.agent_runner.delivery import DeliveryContext
+
+        ctx = AgentRunContext(
+            run_id="run_1",
+            trigger=trigger,
+            event=event,
+            input=input,
+            delivery=DeliveryContext(surface="platform"),
+            resources=AgentResources(),
+            runtime=AgentRuntimeContext(),
+        )
+
+        # messages is now in bootstrap, not top-level
+        assert ctx.bootstrap is None or ctx.bootstrap.messages == []
+
+    def test_sdk_context_bootstrap_optional(self):
+        """Test that bootstrap is optional."""
+        trigger = AgentTrigger(type="message.received")
+        event = AgentEventContext(
+            event_id="evt_1",
+            event_type="message.received",
+            source="platform",
+        )
+        input = AgentInput(text="Hello")
+        from langbot_plugin.api.entities.builtin.agent_runner.resources import AgentResources
+        from langbot_plugin.api.entities.builtin.agent_runner.runtime import AgentRuntimeContext
+        from langbot_plugin.api.entities.builtin.agent_runner.delivery import DeliveryContext
+
+        ctx = AgentRunContext(
+            run_id="run_1",
+            trigger=trigger,
+            event=event,
+            input=input,
+            delivery=DeliveryContext(surface="platform"),
+            resources=AgentResources(),
+            runtime=AgentRuntimeContext(),
+        )
+
+        # bootstrap is optional
+        assert ctx.bootstrap is None or isinstance(ctx.bootstrap.messages, list)
+
+
+class TestLegacyMaxRoundNotInProtocol:
+    """Test that legacy max-round only affects compat adapter, not Protocol v1."""
+
+    def test_max_round_not_in_sdk_context(self):
+        """Test max-round is not a field in SDK AgentRunContext."""
+        # AgentRunContext should not have max_round field
+        ctx_fields = AgentRunContext.model_fields.keys()
+
+        assert "max_round" not in ctx_fields
+        assert "maxRound" not in ctx_fields
+
+    def test_max_round_in_compatibility_context(self):
+        """Test max_round is in compatibility context, not main context."""
+        trigger = AgentTrigger(type="message.received")
+        event = AgentEventContext(
+            event_id="evt_1",
+            event_type="message.received",
+            source="platform",
+        )
+        input = AgentInput(text="Hello")
+        from langbot_plugin.api.entities.builtin.agent_runner.resources import AgentResources
+        from langbot_plugin.api.entities.builtin.agent_runner.runtime import AgentRuntimeContext
+        from langbot_plugin.api.entities.builtin.agent_runner.delivery import DeliveryContext
+        from langbot_plugin.api.entities.builtin.agent_runner.context import CompatibilityContext
+
+        compat = CompatibilityContext(max_round=10)
+
+        ctx = AgentRunContext(
+            run_id="run_1",
+            trigger=trigger,
+            event=event,
+            input=input,
+            delivery=DeliveryContext(surface="platform"),
+            resources=AgentResources(),
+            runtime=AgentRuntimeContext(),
+            compatibility=compat,
+        )
+
+        # max_round is in compatibility context, not main context
+        assert ctx.compatibility is not None
+        assert ctx.compatibility.max_round == 10
+
+    def test_binding_max_round_for_adapter_only(self, mock_query_with_max_round):
+        """Test max_round in binding is for adapter use, not Protocol v1."""
+        binding = PipelineCompatAdapter.pipeline_config_to_binding(
+            mock_query_with_max_round, "plugin:test/plugin/runner"
+        )
+
+        # max_round is in binding (Host-internal) for compat adapter
+        assert binding.max_round == 10
+
+        # But SDK entities don't have it
+        ctx_fields = AgentRunContext.model_fields.keys()
+        assert "max_round" not in ctx_fields
+
+
+class TestSDKCapabilitiesProtocolV1:
+    """Test SDK capabilities for Protocol v1."""
+
+    def test_self_managed_context_default_true(self):
+        """Test self_managed_context defaults to True for Protocol v1."""
+        caps = AgentRunnerCapabilities()
+
+        assert caps.self_managed_context is True
+
+    def test_event_context_default_true(self):
+        """Test event_context defaults to True for Protocol v1."""
+        caps = AgentRunnerCapabilities()
+
+        assert caps.event_context is True
+
+
+class TestSDKPermissionsProtocolV1:
+    """Test SDK permissions for Protocol v1."""
+
+    def test_permissions_new_fields(self):
+        """Test new permission fields for Protocol v1."""
+        perms = AgentRunnerPermissions(
+            models=["invoke", "stream", "rerank"],
+            tools=["detail", "call"],
+            knowledge_bases=["list", "retrieve"],
+            history=["page", "search"],
+            events=["get", "page"],
+            artifacts=["metadata", "read"],
+            storage=["plugin", "workspace", "binding"],
+        )
+
+        assert perms.history == ["page", "search"]
+        assert perms.events == ["get", "page"]
+        assert perms.artifacts == ["metadata", "read"]
+        assert perms.storage == ["plugin", "workspace", "binding"]
+
+
+class TestSDKResultProtocolV1:
+    """Test SDK AgentRunResult for Protocol v1."""
+
+    def test_result_requires_run_id(self):
+        """Test result requires run_id for Protocol v1."""
+        from langbot_plugin.api.entities.builtin.provider.message import Message
+
+        result = AgentRunResult.message_completed(
+            run_id="run_1",
+            message=Message(role="assistant", content="Hello"),
+        )
+
+        assert result.run_id == "run_1"
+
+    def test_artifact_created_result_type(self):
+        """Test artifact.created result type."""
+        result = AgentRunResult.artifact_created(
+            run_id="run_1",
+            artifact_id="artifact_1",
+            artifact_type="image",
+        )
+
+        assert result.type == AgentRunResultType.ARTIFACT_CREATED
+        assert result.data["artifact_id"] == "artifact_1"
+
+
+# Fixtures
+@pytest.fixture
+def mock_query():
+    """Create a mock Pipeline Query for testing."""
+    query = Mock()
+    query.query_id = 123
+    query.bot_uuid = "bot-uuid-123"
+    query.pipeline_uuid = "pipeline-uuid-456"
+    query.launcher_type = Mock(value="person")
+    query.launcher_id = "launcher-123"
+    query.sender_id = "sender-123"
+    query.pipeline_config = {
+        "ai": {
+            "runner": "plugin:test/plugin/runner",
+        }
+    }
+    query.variables = {}
+
+    # Create a proper content element mock
+    content_elem = Mock(spec=['type', 'text', 'model_dump'])
+    content_elem.type = 'text'
+    content_elem.text = 'Hello world'
+    content_elem.model_dump = Mock(return_value={'type': 'text', 'text': 'Hello world'})
+
+    query.user_message = Mock()
+    query.user_message.content = [content_elem]
+
+    # Create message_chain mock
+    message_chain = Mock()
+    message_chain.message_id = 789
+    message_chain.model_dump = Mock(return_value={'message_id': 789, 'components': []})
+    query.message_chain = message_chain
+
+    query.message_event = None
+
+    # Mock session with proper conversation
+    query.session = Mock()
+    query.session.launcher_type = Mock(value="person")
+    query.session.launcher_id = "launcher-123"
+    query.session.using_conversation = Mock()
+    query.session.using_conversation.uuid = "conv-uuid-123"
+
+    # Mock use_funcs (empty list by default)
+    query.use_funcs = []
+    query.use_llm_model_uuid = None
+
+    return query
+
+
+@pytest.fixture
+def mock_query_with_max_round(mock_query):
+    """Create a mock Query with max_round configuration."""
+    mock_query.pipeline_config = {
+        "ai": {
+            "runner": "plugin:test/plugin/runner",
+            "max-round": 10,
+        }
+    }
+    return mock_query
+
+
+@pytest.fixture
+def mock_query_no_session():
+    """Create a mock Query without session."""
+    query = Mock()
+    query.query_id = 456
+    query.bot_uuid = "bot-uuid-456"
+    query.pipeline_uuid = "pipeline-uuid-789"
+    query.launcher_type = Mock(value="person")
+    query.launcher_id = "launcher-456"
+    query.sender_id = "sender-456"
+    query.pipeline_config = {
+        "ai": {
+            "runner": "plugin:test/plugin/runner",
+        }
+    }
+    query.variables = {}
+
+    # Create a proper content element mock
+    content_elem = Mock(spec=['type', 'text', 'model_dump'])
+    content_elem.type = 'text'
+    content_elem.text = 'Test message'
+    content_elem.model_dump = Mock(return_value={'type': 'text', 'text': 'Test message'})
+
+    query.user_message = Mock()
+    query.user_message.content = [content_elem]
+
+    message_chain = Mock()
+    message_chain.message_id = -1
+    message_chain.model_dump = Mock(return_value={'message_id': -1, 'components': []})
+    query.message_chain = message_chain
+
+    query.message_event = None
+    query.session = None
+
+    # Mock use_funcs
+    query.use_funcs = []
+    query.use_llm_model_uuid = None
+
+    return query

tests/unit_tests/agent/test_event_log_transcript.py

@@ -0,0 +1,324 @@
+"""Tests for EventLog, Transcript, and history/event APIs."""
+from __future__ import annotations
+
+import pytest
+from unittest.mock import Mock, MagicMock, patch
+import datetime
+
+from langbot.pkg.agent.runner.host_models import (
+    AgentEventEnvelope,
+    AgentBinding,
+    BindingScope,
+    ResourcePolicy,
+    StatePolicy,
+    DeliveryPolicy,
+)
+from langbot.pkg.agent.runner.event_log_store import EventLogStore
+from langbot.pkg.agent.runner.transcript_store import TranscriptStore
+from langbot.pkg.agent.runner.session_registry import get_session_registry
+from langbot_plugin.api.entities.builtin.agent_runner.event import (
+    AgentEventContext,
+    ActorContext,
+)
+from langbot_plugin.api.entities.builtin.agent_runner.input import AgentInput
+from langbot_plugin.api.entities.builtin.agent_runner.delivery import DeliveryContext
+
+
+def make_event_envelope(
+    event_id: str = "evt_1",
+    event_type: str = "message.received",
+    conversation_id: str | None = "conv_1",
+    actor_id: str | None = "user_1",
+    input_text: str = "Hello",
+) -> AgentEventEnvelope:
+    """Create a test event envelope."""
+    return AgentEventEnvelope(
+        event_id=event_id,
+        event_type=event_type,
+        event_time=1700000000,
+        source="platform",
+        bot_id="bot_1",
+        workspace_id=None,
+        conversation_id=conversation_id,
+        thread_id=None,
+        actor=ActorContext(
+            actor_type="user",
+            actor_id=actor_id,
+            actor_name="Test User",
+        ) if actor_id else None,
+        subject=None,
+        input=AgentInput(text=input_text),
+        delivery=DeliveryContext(surface="test"),
+    )
+
+
+def make_binding(runner_id: str = "plugin:test/plugin/runner") -> AgentBinding:
+    """Create a test binding."""
+    return AgentBinding(
+        binding_id="binding_1",
+        scope=BindingScope(scope_type="pipeline", scope_id="pipeline_1"),
+        event_types=["message.received"],
+        runner_id=runner_id,
+        runner_config={},
+        resource_policy=ResourcePolicy(),
+        state_policy=StatePolicy(),
+        delivery_policy=DeliveryPolicy(),
+        enabled=True,
+    )
+
+
+class TestEventLogStore:
+    """Test EventLogStore operations."""
+
+    @pytest.mark.asyncio
+    async def test_append_event(self, mock_db_engine):
+        """Test appending an event to EventLog."""
+        store = EventLogStore(mock_db_engine)
+
+        event_id = await store.append_event(
+            event_id="evt_1",
+            event_type="message.received",
+            source="platform",
+            bot_id="bot_1",
+            conversation_id="conv_1",
+            actor_type="user",
+            actor_id="user_1",
+            input_summary="Hello world",
+            run_id="run_1",
+            runner_id="plugin:test/plugin/runner",
+        )
+
+        assert event_id == "evt_1"
+
+    @pytest.mark.asyncio
+    async def test_append_event_truncates_input_summary(self, mock_db_engine):
+        """Test that long input summaries are truncated."""
+        store = EventLogStore(mock_db_engine)
+
+        long_text = "x" * 2000
+        event_id = await store.append_event(
+            event_id="evt_2",
+            event_type="message.received",
+            source="platform",
+            input_summary=long_text,
+        )
+
+        assert event_id == "evt_2"
+
+    @pytest.mark.asyncio
+    async def test_page_events_with_conversation_filter(self, mock_db_engine):
+        """Test paging events with conversation_id filter."""
+        store = EventLogStore(mock_db_engine)
+
+        items, next_seq, has_more = await store.page_events(
+            conversation_id="conv_1",
+            limit=10,
+        )
+
+        assert isinstance(items, list)
+
+
+class TestTranscriptStore:
+    """Test TranscriptStore operations."""
+
+    @pytest.mark.asyncio
+    async def test_append_transcript(self, mock_db_engine):
+        """Test appending a transcript item."""
+        store = TranscriptStore(mock_db_engine)
+
+        transcript_id = await store.append_transcript(
+            transcript_id=None,  # Auto-generate
+            event_id="evt_1",
+            conversation_id="conv_1",
+            role="user",
+            content="Hello",
+        )
+
+        assert transcript_id is not None
+
+    @pytest.mark.asyncio
+    async def test_append_transcript_with_artifacts(self, mock_db_engine):
+        """Test appending transcript with artifact refs."""
+        store = TranscriptStore(mock_db_engine)
+
+        transcript_id = await store.append_transcript(
+            transcript_id=None,  # Auto-generate
+            event_id="evt_2",
+            conversation_id="conv_1",
+            role="assistant",
+            content="Here's an image",
+            artifact_refs=[
+                {"artifact_id": "art_1", "artifact_type": "image", "url": "http://example.com/img.png"}
+            ],
+        )
+
+        assert transcript_id is not None
+
+    @pytest.mark.asyncio
+    async def test_page_transcript_backward(self, mock_db_engine):
+        """Test paging transcript backward (older items)."""
+        store = TranscriptStore(mock_db_engine)
+
+        items, next_seq, prev_seq, has_more = await store.page_transcript(
+            conversation_id="conv_1",
+            limit=10,
+            direction="backward",
+        )
+
+        assert isinstance(items, list)
+
+    @pytest.mark.asyncio
+    async def test_page_transcript_has_hard_limit(self, mock_db_engine):
+        """Test that transcript paging has a hard limit."""
+        store = TranscriptStore(mock_db_engine)
+
+        # Request more than the hard limit
+        items, next_seq, prev_seq, has_more = await store.page_transcript(
+            conversation_id="conv_1",
+            limit=200,  # Request 200, but hard limit is 100
+        )
+
+        # The store should cap at 100
+        assert len(items) <= store.HARD_LIMIT
+
+    @pytest.mark.asyncio
+    async def test_search_transcript(self, mock_db_engine):
+        """Test searching transcript."""
+        store = TranscriptStore(mock_db_engine)
+
+        items = await store.search_transcript(
+            conversation_id="conv_1",
+            query_text="database",
+            top_k=10,
+        )
+
+        assert isinstance(items, list)
+
+
+class TestHistoryPageAuthorization:
+    """Test history.page authorization."""
+
+    @pytest.mark.asyncio
+    async def test_history_page_requires_run_id(self, mock_handler, mock_db_engine):
+        """Test history.page requires run_id."""
+        from langbot_plugin.entities.io.actions.enums import PluginToRuntimeAction
+
+        # Mock call_action to simulate the handler
+        result = await mock_handler.call_action(
+            PluginToRuntimeAction.HISTORY_PAGE,
+            {"run_id": None},
+        )
+
+        # Should return error
+        assert result.get("ok") is False or "error" in str(result).lower()
+
+    @pytest.mark.asyncio
+    async def test_history_page_validates_conversation_scope(self, mock_db_engine):
+        """Test history.page only allows access to run's conversation."""
+        # This test verifies the authorization logic
+        # The actual implementation validates conversation_id matches session
+        session_registry = get_session_registry()
+
+        await session_registry.register(
+            run_id="run_1",
+            runner_id="plugin:test/plugin/runner",
+            query_id=None,
+            plugin_identity="test/plugin",
+            resources={"models": [], "tools": [], "knowledge_bases": [], "storage": {"plugin_storage": True}},
+            conversation_id="conv_1",
+        )
+
+        session = await session_registry.get("run_1")
+        assert session is not None
+        assert session["conversation_id"] == "conv_1"
+
+        # Cleanup
+        await session_registry.unregister("run_1")
+
+
+class TestEventGetAuthorization:
+    """Test event.get authorization."""
+
+    @pytest.mark.asyncio
+    async def test_event_get_requires_run_id(self, mock_handler):
+        """Test event.get requires run_id."""
+        from langbot_plugin.entities.io.actions.enums import PluginToRuntimeAction
+
+        result = await mock_handler.call_action(
+            PluginToRuntimeAction.EVENT_GET,
+            {"run_id": None, "event_id": "evt_1"},
+        )
+
+        # Should return error
+        assert result.get("ok") is False or "error" in str(result).lower()
+
+
+class TestContextAccessPopulation:
+    """Test ContextAccess population in build_context_from_event."""
+
+    @pytest.mark.asyncio
+    async def test_context_access_has_history_apis_when_permitted(self, mock_db_engine):
+        """Test ContextAccess shows available APIs based on permissions."""
+        # This would test the context builder logic
+        # For now we verify the store methods work
+        store = TranscriptStore(mock_db_engine)
+
+        cursor = await store.get_latest_cursor("conv_1")
+        # Should return None or a cursor string
+        assert cursor is None or isinstance(cursor, str)
+
+    @pytest.mark.asyncio
+    async def test_context_access_shows_has_history_before(self, mock_db_engine):
+        """Test ContextAccess indicates if history exists."""
+        store = TranscriptStore(mock_db_engine)
+
+        has_history = await store.has_history_before("conv_1", 10)
+        assert isinstance(has_history, bool)
+
+
+# Fixtures
+@pytest.fixture
+def mock_db_engine():
+    """Create a mock database engine."""
+    from unittest.mock import MagicMock, AsyncMock
+    from sqlalchemy.ext.asyncio import AsyncEngine
+
+    engine = MagicMock(spec=AsyncEngine)
+
+    # Mock connection
+    mock_conn = MagicMock()
+    mock_result = MagicMock()
+    mock_result.fetchone.return_value = None
+    mock_result.fetchall.return_value = []
+    mock_result.scalar.return_value = 0
+    mock_conn.execute = AsyncMock(return_value=mock_result)
+    mock_conn.commit = AsyncMock()
+
+    # Create async context manager for connect()
+    class AsyncConnectContextManager:
+        async def __aenter__(self):
+            return mock_conn
+        async def __aexit__(self, *args):
+            pass
+
+    # connect() should return an async context manager
+    engine.connect = MagicMock(return_value=AsyncConnectContextManager())
+    return engine
+
+
+@pytest.fixture
+def mock_handler():
+    """Create a mock handler for testing actions."""
+    from langbot_plugin.runtime.io.handler import Handler, ActionResponse
+
+    class MockHandler(Handler):
+        def __init__(self):
+            self._responses = {}
+
+        async def call_action(self, action, data, timeout=30):
+            # Simulate error response for missing run_id
+            if not data.get("run_id"):
+                return {"ok": False, "message": "run_id is required"}
+            return {"ok": True, "data": {}}
+
+    return MockHandler()

tests/unit_tests/agent/test_orchestrator_integration.py

@@ -288,7 +288,8 @@ async def test_orchestrator_runs_fake_plugin_with_authorized_context():
     context = plugin_connector.contexts[0]
     assert context["config"]["timeout"] == 30
     assert context["runtime"]["deadline_at"] is not None
-    assert context["params"] == {"public_param": "visible"}
+    # Protocol v1: params is in compatibility.extra
+    assert context["compatibility"]["extra"]["params"] == {"public_param": "visible"}
     assert context["event"]["event_type"] == "message.received"
     assert context["event"]["event_data"]["source_event_type"] == "FriendMessage"
     assert context["actor"]["actor_id"] == "user_001"
@@ -337,7 +338,16 @@ async def test_orchestrator_packages_legacy_max_round_without_mutating_query():
 
     assert len(messages) == 1
     context = plugin_connector.contexts[0]
-    assert [message["content"] for message in context["messages"]] == [
+    # Protocol v1: legacy messages are in bootstrap.messages
+    assert context["bootstrap"] is not None
+    assert [message["content"] for message in context["bootstrap"]["messages"]] == [
+        "message 2",
+        "response 2",
+        "message 3",
+        "response 3",
+    ]
+    # Also in compatibility.legacy_messages for legacy runners
+    assert [message["content"] for message in context["compatibility"]["legacy_messages"]] == [
         "message 2",
         "response 2",
         "message 3",