flowent 0.0.4 → 0.0.5

package/backend/src/flowent/agent.py

@@ -10,10 +10,11 @@ from dataclasses import dataclass, field
 from functools import lru_cache, partial
 from queue import Empty, Queue
 from typing import Any
+from urllib.parse import urlparse
 
 from loguru import logger
 
-from flowent.assistant_commands import build_assistant_help_text
+from flowent.assistant_commands import build_conversation_help_text
 from flowent.events import event_bus
 from flowent.image_assets import create_image_asset, require_image_asset
 from flowent.models import (
@@ -35,15 +36,17 @@ from flowent.models import (
     ModelInfo,
     NodeConfig,
     NodeType,
+    PortInboundEntry,
     ReceivedMessage,
     SentMessage,
-    StateEntry,
     SystemEntry,
     TextPart,
     ThinkingDelta,
     TodoItem,
     ToolCall,
     ToolResultDelta,
+    WorkflowActivationState,
+    WorkflowNodeKind,
     content_parts_to_text,
     deserialize_content_parts,
     has_image_parts,
@@ -123,6 +126,7 @@ class ResolvedModelSource:
     provider_id: str | None
     provider_name: str | None
     provider_type: str | None
+    provider_base_url: str | None
     model: str | None
     model_info: ModelInfo | None
 
@@ -145,7 +149,6 @@ class Agent:
         self.todos: list[TodoItem] = []
         self.connections: list[str] = []
         self.history: list[HistoryEntry] = []
-        self.history.append(StateEntry(state=self.state.value, reason="created"))
         self._terminate = threading.Event()
         self._interrupt_requested = threading.Event()
         self._interrupt_callback_lock = threading.Lock()
@@ -329,7 +332,7 @@ class Agent:
         return max(0.0, _time.perf_counter() - started_at)
 
     def get_contact_ids_snapshot(self) -> list[str]:
-        from flowent.graph_service import get_tab_leader_id
+        from flowent.graph_service import get_tab_leader_id, list_agent_contact_paths
         from flowent.registry import registry
         from flowent.workspace_store import workspace_store
 
@@ -361,8 +364,6 @@ class Agent:
         assistant = registry.get_assistant()
         if is_leader and assistant is not None:
             append_contact(assistant.uuid)
-        if not is_leader and leader_id is not None:
-            append_contact(leader_id)
 
         if is_leader:
             for node in registry.get_all():
@@ -375,13 +376,34 @@ class Agent:
                 append_contact(node.uuid)
             return contact_ids
 
+        for path in list_agent_contact_paths(
+            tab_id=self.config.tab_id,
+            node_id=self.uuid,
+        ):
+            append_contact(path.target_id)
         return contact_ids
 
     def get_contacts_info(self) -> list[dict[str, Any]]:
-        from flowent.graph_service import is_tab_leader
+        from flowent.graph_service import (
+            is_tab_leader,
+            list_agent_contact_paths,
+        )
         from flowent.registry import registry
 
         result: list[dict[str, Any]] = []
+        if (
+            self.config.tab_id is not None
+            and not is_tab_leader(node_id=self.uuid, tab_id=self.config.tab_id)
+            and self.node_type == NodeType.AGENT
+        ):
+            return [
+                path.serialize()
+                for path in list_agent_contact_paths(
+                    tab_id=self.config.tab_id,
+                    node_id=self.uuid,
+                )
+            ]
+
         for contact_id in self.get_contact_ids_snapshot():
             node = registry.get(contact_id)
             if node is None:
@@ -504,7 +526,7 @@ class Agent:
         if self.state not in {AgentState.RUNNING, AgentState.SLEEPING}:
             return False
         if not self._command_interrupt_lock.acquire(timeout=timeout):
-            raise TimeoutError("Assistant did not pause for the command in time")
+            raise TimeoutError("Current chat did not pause for the command in time")
 
         self._pause_after_interrupt_requested.set()
         self._paused_for_command.clear()
@@ -517,7 +539,7 @@ class Agent:
                 self._command_interrupt_lock.release()
                 return False
             if not self._paused_for_command.wait(timeout=timeout):
-                raise TimeoutError("Assistant did not pause after interrupt")
+                raise TimeoutError("Current chat did not pause after interrupt")
             return True
         except Exception:
             self._pause_after_interrupt_requested.clear()
@@ -532,7 +554,10 @@ class Agent:
 
     def clear_chat_history(self, *, interrupt_timeout: float = 5.0) -> None:
         if self.node_type != NodeType.ASSISTANT:
-            raise RuntimeError("Only assistant chat history can be cleared")
+            from flowent.graph_service import is_tab_leader
+
+            if not is_tab_leader(node_id=self.uuid, tab_id=self.config.tab_id):
+                raise RuntimeError("Only Assistant or workflow chats can be cleared")
 
         paused_for_command = self._pause_for_command_execution(
             timeout=interrupt_timeout
@@ -543,9 +568,7 @@ class Agent:
                 self._pending_runtime_notices.clear()
             with self._history_lock:
                 self.history = [
-                    entry
-                    for entry in self.history
-                    if isinstance(entry, (SystemEntry, StateEntry))
+                    entry for entry in self.history if isinstance(entry, SystemEntry)
                 ]
                 self._pending_input_turn = False
                 self._turn_started_with_pending_input = False
@@ -556,7 +579,11 @@ class Agent:
                 Event(
                     type=EventType.HISTORY_CLEARED,
                     agent_id=self.uuid,
-                    data={"scope": "assistant_chat"},
+                    data={
+                        "scope": "assistant_chat"
+                        if self.node_type == NodeType.ASSISTANT
+                        else "workflow_chat"
+                    },
                 )
             )
             self._persist_workspace_node()
@@ -634,8 +661,7 @@ class Agent:
                 self.history = [
                     entry
                     for index, entry in enumerate(previous_history)
-                    if index < anchor_index
-                    or isinstance(entry, (SystemEntry, StateEntry))
+                    if index < anchor_index or isinstance(entry, SystemEntry)
                 ]
                 retried_message_id = str(_uuid.uuid4())
                 self.history.append(
@@ -785,8 +811,7 @@ class Agent:
                 self.history = [
                     entry
                     for index, entry in enumerate(previous_history)
-                    if index < anchor_index
-                    or isinstance(entry, (SystemEntry, StateEntry))
+                    if index < anchor_index or isinstance(entry, SystemEntry)
                 ]
                 retried_message_id = str(_uuid.uuid4())
                 self.history.append(
@@ -862,14 +887,20 @@ class Agent:
         interrupt_timeout: float = 5.0,
     ) -> CommandResultEntry:
         if self.node_type != NodeType.ASSISTANT:
-            raise RuntimeError("Only assistant chat history can be compacted")
+            from flowent.graph_service import is_tab_leader
+
+            if not is_tab_leader(node_id=self.uuid, tab_id=self.config.tab_id):
+                raise RuntimeError("Only Assistant or workflow chats can be compacted")
 
         paused_for_command = self._pause_for_command_execution(
             timeout=interrupt_timeout
         )
         try:
-            self._run_compact_with_stats(trigger_type="manual", focus=focus)
-            content = "Compacted the current Assistant execution context."
+            self._run_compact_with_observability(
+                trigger_type="manual",
+                focus=focus,
+            )
+            content = "Compacted this chat for future replies."
             if focus and focus.strip():
                 content += f"\n\nFocus: {focus.strip()}"
 
@@ -885,7 +916,7 @@ class Agent:
             if paused_for_command:
                 self._resume_after_command_execution()
 
-    def execute_assistant_command(
+    def execute_conversation_command(
         self,
         *,
         command_name: str,
@@ -897,7 +928,7 @@ class Agent:
             self.clear_chat_history(interrupt_timeout=interrupt_timeout)
             entry = CommandResultEntry(
                 command_name=command_name,
-                content="Cleared the current Assistant chat history.",
+                content="Cleared the current chat.",
                 include_in_context=False,
             )
             append_to_history = False
@@ -909,15 +940,28 @@ class Agent:
         elif command_name == "/help":
             entry = CommandResultEntry(
                 command_name=command_name,
-                content=build_assistant_help_text(),
+                content=build_conversation_help_text(),
             )
         else:
-            raise RuntimeError(f"Unsupported Assistant command: {command_name}")
+            raise RuntimeError(f"Unsupported conversation command: {command_name}")
 
         if append_to_history:
             self._append_history(entry)
         return entry
 
+    def execute_assistant_command(
+        self,
+        *,
+        command_name: str,
+        argument: str = "",
+        interrupt_timeout: float = 5.0,
+    ) -> CommandResultEntry:
+        return self.execute_conversation_command(
+            command_name=command_name,
+            argument=argument,
+            interrupt_timeout=interrupt_timeout,
+        )
+
     def _run(self) -> None:
         with logger.contextualize(
             agent_id=self.uuid[:8],
@@ -1237,11 +1281,20 @@ class Agent:
         has_todos: bool,
         pending_agent_dispatches: list[str],
     ) -> dict[str, str]:
+        if self._is_entry_level_sender():
+            send_lines = [
+                "- To send a formal message to another node, use `send` with a single `target` and ordered `parts`.",
+                "- Use `contacts` to inspect the node ids and names you can currently message directly.",
+            ]
+        else:
+            send_lines = [
+                "- To send through a workflow path, use `send` with one target, source output port, target input port, and a value matching that port type.",
+                "- Use `contacts` to inspect the current output-port paths you can send through.",
+            ]
         lines = [
             "Runtime post prompt:",
             "- Plain content is never delivered to other agents.",
-            "- To send a formal message to another node, use `send` with a single `target` and ordered `parts`.",
-            "- Use `contacts` to inspect the node ids and names you can currently message directly.",
+            *send_lines,
             "- `@target:` or any other `@name:` text inside normal content is just text. It does not send anything.",
         ]
         if pending_agent_dispatches:
@@ -1416,6 +1469,10 @@ class Agent:
             ),
         )
 
+    @staticmethod
+    def _parts_value(parts: list[TextPart | ImagePart]) -> list[dict[str, Any]]:
+        return [part.serialize() for part in parts]
+
     def _record_text_output(
         self,
         content: str,
@@ -1526,6 +1583,68 @@ class Agent:
             raise ValueError(f"Send failed: target `{target_ref}` is not in contacts.")
         return target
 
+    def _is_entry_level_sender(self) -> bool:
+        if self.node_type == NodeType.ASSISTANT:
+            return True
+        if self.config.tab_id is None:
+            return False
+        from flowent.graph_service import is_tab_leader
+
+        return is_tab_leader(node_id=self.uuid, tab_id=self.config.tab_id)
+
+    def _resolve_port_send_path(
+        self,
+        *,
+        target_ref: str,
+        from_output_port_key: str,
+        to_input_port_key: str,
+    ):
+        if self.config.tab_id is None:
+            raise ValueError("Send failed: node is not part of a workflow.")
+        from flowent.graph_service import (
+            resolve_agent_contact_path,
+            resolve_workflow_node_ref,
+        )
+
+        target_id = resolve_workflow_node_ref(
+            tab_id=self.config.tab_id,
+            node_ref=target_ref,
+        )
+        if target_id is None:
+            raise ValueError(f"Send failed: target `{target_ref}` was not found.")
+        path = resolve_agent_contact_path(
+            tab_id=self.config.tab_id,
+            source_node_id=self.uuid,
+            target_node_id=target_id,
+            from_output_port_key=from_output_port_key,
+            to_input_port_key=to_input_port_key,
+        )
+        if path is None:
+            raise ValueError(
+                f"Send failed: target `{target_ref}` is not connected from `{from_output_port_key}` to `{to_input_port_key}`."
+            )
+        return path
+
+    def _ensure_can_dispatch_to_contact(self, target: Agent) -> None:
+        if self.config.tab_id is None:
+            return
+
+        from flowent.graph_service import is_tab_leader
+        from flowent.workspace_store import workspace_store
+
+        if not is_tab_leader(node_id=self.uuid, tab_id=self.config.tab_id):
+            return
+        if target.node_type != NodeType.AGENT:
+            return
+        if is_tab_leader(node_id=target.uuid, tab_id=target.config.tab_id):
+            return
+
+        tab = workspace_store.get_tab(self.config.tab_id)
+        if tab is not None and tab.activation_state != WorkflowActivationState.ACTIVE:
+            raise ValueError(
+                "Activate this workflow before sending work to agent nodes."
+            )
+
     def supports_input_image(self) -> bool:
         _, model_info = self._get_effective_model_info()
         if model_info is None:
@@ -1543,9 +1662,20 @@ class Agent:
         *,
         target_ref: str,
         raw_parts: Any,
+        from_output_port_key: str | None = None,
+        to_input_port_key: str | None = None,
+        raw_value: Any | None = None,
     ) -> str:
+        if not self._is_entry_level_sender():
+            return self.send_port_value(
+                target_ref=target_ref,
+                from_output_port_key=from_output_port_key,
+                to_input_port_key=to_input_port_key,
+                raw_value=raw_value if raw_value is not None else raw_parts,
+            )
         parts = parse_content_parts_payload(raw_parts)
         target = self._resolve_contact_target(target_ref)
+        self._ensure_can_dispatch_to_contact(target)
         if has_image_parts(parts) and not target.supports_input_image():
             raise ValueError(
                 f"Send failed: target `{target_ref}` does not support `input_image`."
@@ -1566,6 +1696,78 @@ class Agent:
         )
         return json.dumps({"status": "sent", "target_id": target.uuid})
 
+    def send_port_value(
+        self,
+        *,
+        target_ref: str,
+        from_output_port_key: str | None,
+        to_input_port_key: str | None,
+        raw_value: Any,
+    ) -> str:
+        if self._is_entry_level_sender():
+            raise ValueError("Send failed: entry contacts use target and parts.")
+        if (
+            not isinstance(from_output_port_key, str)
+            or not from_output_port_key.strip()
+        ):
+            raise ValueError("send.from_output_port_key must be a non-empty string")
+        if not isinstance(to_input_port_key, str) or not to_input_port_key.strip():
+            raise ValueError("send.to_input_port_key must be a non-empty string")
+
+        path = self._resolve_port_send_path(
+            target_ref=target_ref,
+            from_output_port_key=from_output_port_key.strip(),
+            to_input_port_key=to_input_port_key.strip(),
+        )
+        value = raw_value
+        if path.port_type == "parts":
+            parts = parse_content_parts_payload(raw_value)
+            value = self._parts_value(parts)
+            if path.target_node_type == WorkflowNodeKind.AGENT.value:
+                target = self._resolve_contact_target(path.target_id)
+                if has_image_parts(parts) and not target.supports_input_image():
+                    raise ValueError(
+                        f"Send failed: target `{target_ref}` does not support `input_image`."
+                    )
+            for part in parts:
+                asset_id = getattr(part, "asset_id", None)
+                if isinstance(asset_id, str):
+                    require_image_asset(asset_id)
+
+        message_id = str(_uuid.uuid4())
+        from flowent.graph_service import dispatch_port_value
+
+        payload, error = dispatch_port_value(
+            tab_id=self.config.tab_id or "",
+            source_node_id=self.uuid,
+            source_output_port_key=path.from_output_port_key,
+            target_node_id=path.target_id,
+            target_input_port_key=path.to_input_port_key,
+            value=value,
+            source_is_agent_send=True,
+            message_id=message_id,
+        )
+        if error is not None or payload is None:
+            raise ValueError(f"Send failed: {error or 'path unavailable'}.")
+
+        self._mark_turn_progress()
+        sent_parts = (
+            parse_content_parts_payload(value) if path.port_type == "parts" else []
+        )
+        value_summary = str(payload.get("value_summary", ""))
+        self._append_history(
+            SentMessage(
+                to_id=path.target_id,
+                parts=sent_parts,
+                content=value_summary if path.port_type != "parts" else "",
+                message_id=message_id,
+                from_output_port_key=path.from_output_port_key,
+                to_input_port_key=path.to_input_port_key,
+                value_summary=value_summary,
+            )
+        )
+        return json.dumps(payload)
+
     def _mark_turn_progress(self) -> None:
         self._turn_made_progress = True
         self._pending_input_turn = False
@@ -1662,6 +1864,7 @@ class Agent:
         retry_limit = self._get_llm_max_retries()
         retry_count = 0
         started_at = _time.time()
+        self._raise_if_llm_network_disallowed()
 
         while True:
             stream_state = StreamingContentState()
@@ -1682,7 +1885,7 @@ class Agent:
                 finally:
                     self.set_interrupt_callback(None)
                 self._raise_if_interrupt_requested()
-                self._record_request_stats(
+                self._record_request_observability(
                     started_at=started_at,
                     ended_at=_time.time(),
                     retry_count=retry_count,
@@ -1705,7 +1908,7 @@ class Agent:
                     elif retry_policy == "unlimited":
                         should_retry = True
                 if not should_retry:
-                    self._record_request_stats(
+                    self._record_request_observability(
                         started_at=started_at,
                         ended_at=_time.time(),
                         retry_count=retry_count,
@@ -1726,7 +1929,7 @@ class Agent:
                 )
                 self._wait_for_llm_retry_delay(delay_seconds)
             except Exception as exc:
-                self._record_request_stats(
+                self._record_request_observability(
                     started_at=started_at,
                     ended_at=_time.time(),
                     retry_count=retry_count,
@@ -1767,6 +1970,8 @@ class Agent:
         if not context_messages:
             return "- No prior execution context was available to compact."
 
+        self._raise_if_llm_network_disallowed()
+
         focus_text = focus.strip() if focus else ""
         request_lines = [
             "Compact this agent execution context into a durable markdown summary.",
@@ -1889,12 +2094,20 @@ class Agent:
 
             elif isinstance(entry, ReceivedMessage):
                 self._flush_tool_calls(messages, pending_tool_calls)
+                if entry.from_output_port_key and entry.to_input_port_key:
+                    prefix = (
+                        f'<message from="{entry.from_id}" '
+                        f'from_output="{entry.from_output_port_key}" '
+                        f'to_input="{entry.to_input_port_key}">'
+                    )
+                else:
+                    prefix = f'<message from="{entry.from_id}">'
                 messages.append(
                     {
                         "role": "user",
                         "content": self._wrap_context_parts(
                             entry.parts,
-                            prefix=f'<message from="{entry.from_id}">',
+                            prefix=prefix,
                             suffix="</message>",
                         ),
                     }
@@ -1911,12 +2124,20 @@ class Agent:
 
             elif isinstance(entry, SentMessage):
                 self._flush_tool_calls(messages, pending_tool_calls)
+                if entry.from_output_port_key and entry.to_input_port_key:
+                    prefix = (
+                        f'<message to="{entry.to_id}" '
+                        f'from_output="{entry.from_output_port_key}" '
+                        f'to_input="{entry.to_input_port_key}">'
+                    )
+                else:
+                    prefix = f'<message to="{entry.to_id}">'
                 messages.append(
                     {
                         "role": "assistant",
                         "content": self._wrap_context_parts(
                             entry.parts,
-                            prefix=f'<message to="{entry.to_id}">',
+                            prefix=prefix,
                             suffix="</message>",
                         ),
                     }
@@ -1967,6 +2188,18 @@ class Agent:
                 self._flush_tool_calls(messages, pending_tool_calls)
                 messages.append(self._build_runtime_system_message(entry.content))
 
+            elif isinstance(entry, PortInboundEntry):
+                self._flush_tool_calls(messages, pending_tool_calls)
+                messages.append(
+                    self._build_runtime_system_message(
+                        "Port input received: "
+                        f"from {entry.from_id}.{entry.from_output_port_key} "
+                        f"to {entry.to_input_port_key} "
+                        f"({entry.port_type})\n"
+                        f"{json.dumps(entry.value, ensure_ascii=False, sort_keys=True)}"
+                    )
+                )
+
         self._flush_tool_calls(messages, pending_tool_calls)
         return messages
 
@@ -2047,7 +2280,7 @@ class Agent:
                 runtime_tail_messages=list(prepared_context.runtime_tail_messages),
             )
 
-    def _get_stats_node_label(self) -> str:
+    def _get_observability_node_label(self) -> str:
         if self.config.name:
             return self.config.name
         if self.config.role_name:
@@ -2060,7 +2293,7 @@ class Agent:
             return "Leader"
         return "Agent"
 
-    def _get_stats_tab_title(self) -> str | None:
+    def _get_observability_tab_title(self) -> str | None:
         if not self.config.tab_id:
             return None
         from flowent.workspace_store import workspace_store
@@ -2096,6 +2329,7 @@ class Agent:
                 provider_id=None,
                 provider_name=None,
                 provider_type=None,
+                provider_base_url=None,
                 model=None,
                 model_info=None,
             )
@@ -2105,6 +2339,7 @@ class Agent:
                 provider_id=None,
                 provider_name=None,
                 provider_type=None,
+                provider_base_url=None,
                 model=None,
                 model_info=None,
             )
@@ -2112,6 +2347,7 @@ class Agent:
             provider_id=provider.id,
             provider_name=provider.name,
             provider_type=provider.type,
+            provider_base_url=provider.base_url,
             model=model_id,
             model_info=resolve_model_info(
                 provider=provider,
@@ -2130,11 +2366,34 @@ class Agent:
             ),
         )
 
+    def _raise_if_llm_network_disallowed(self) -> None:
+        from flowent.graph_service import resolve_effective_permissions_for_agent
+
+        allow_network, _ = resolve_effective_permissions_for_agent(self)
+        if allow_network:
+            return
+        source = self._get_effective_model_source()
+        if not self._model_source_requires_network(source):
+            return
+        raise LLMProviderError(
+            "Network access is disabled for this workflow",
+            transient=False,
+        )
+
+    @staticmethod
+    def _model_source_requires_network(source: ResolvedModelSource) -> bool:
+        base_url = source.provider_base_url
+        if not base_url:
+            return False
+        parsed = urlparse(base_url)
+        host = (parsed.hostname or "").lower()
+        return host not in {"localhost", "127.0.0.1", "::1"}
+
     def _get_effective_model_info(self) -> tuple[str | None, ModelInfo | None]:
         resolved_source = self._get_effective_model_source()
         return resolved_source.provider_type, resolved_source.model_info
 
-    def _record_request_stats(
+    def _record_request_observability(
         self,
         *,
         started_at: float,
@@ -2145,16 +2404,19 @@ class Agent:
         raw_usage: dict[str, Any] | None = None,
         error_summary: str | None = None,
     ) -> None:
-        from flowent.stats_service import RequestRecordInput, stats_store
+        from flowent.observability_service import (
+            RequestRecordInput,
+            observability_store,
+        )
 
         resolved_source = self._get_effective_model_source()
-        stats_store.record_request(
+        observability_store.record_request(
             RequestRecordInput(
                 node_id=self.uuid,
-                node_label=self._get_stats_node_label(),
+                node_label=self._get_observability_node_label(),
                 role_name=self.config.role_name,
                 tab_id=self.config.tab_id,
-                tab_title=self._get_stats_tab_title(),
+                tab_title=self._get_observability_tab_title(),
                 provider_id=resolved_source.provider_id,
                 provider_name=resolved_source.provider_name,
                 provider_type=resolved_source.provider_type,
@@ -2169,26 +2431,29 @@ class Agent:
             )
         )
 
-    def _run_compact_with_stats(
+    def _run_compact_with_observability(
         self,
         *,
         trigger_type: str,
         focus: str | None = None,
     ) -> str:
-        from flowent.stats_service import CompactRecordInput, stats_store
+        from flowent.observability_service import (
+            CompactRecordInput,
+            observability_store,
+        )
 
         started_at = _time.time()
         resolved_source = self._get_effective_model_source()
         try:
             result = self._compact_execution_context(focus=focus)
         except Exception as exc:
-            stats_store.record_compact(
+            observability_store.record_compact(
                 CompactRecordInput(
                     node_id=self.uuid,
-                    node_label=self._get_stats_node_label(),
+                    node_label=self._get_observability_node_label(),
                     role_name=self.config.role_name,
                     tab_id=self.config.tab_id,
-                    tab_title=self._get_stats_tab_title(),
+                    tab_title=self._get_observability_tab_title(),
                     provider_id=resolved_source.provider_id,
                     provider_name=resolved_source.provider_name,
                     provider_type=resolved_source.provider_type,
@@ -2201,13 +2466,13 @@ class Agent:
                 )
             )
             raise
-        stats_store.record_compact(
+        observability_store.record_compact(
             CompactRecordInput(
                 node_id=self.uuid,
-                node_label=self._get_stats_node_label(),
+                node_label=self._get_observability_node_label(),
                 role_name=self.config.role_name,
                 tab_id=self.config.tab_id,
-                tab_title=self._get_stats_tab_title(),
+                tab_title=self._get_observability_tab_title(),
                 provider_id=resolved_source.provider_id,
                 provider_name=resolved_source.provider_name,
                 provider_type=resolved_source.provider_type,
@@ -2311,7 +2576,7 @@ class Agent:
             preflight.context_window_tokens,
         )
         try:
-            self._run_compact_with_stats(trigger_type="auto")
+            self._run_compact_with_observability(trigger_type="auto")
         except Exception as exc:
             if (
                 preflight.safe_input_tokens is not None
@@ -2385,6 +2650,7 @@ class Agent:
             from_id = message.get("from", "")
             message_id = message.get("message_id")
             history_recorded = bool(message.get("history_recorded", False))
+            port_inbound_recorded = bool(message.get("port_inbound_recorded", False))
             if (
                 not isinstance(content, str)
                 or not isinstance(from_id, str)
@@ -2405,6 +2671,23 @@ class Agent:
                         message_id=message_id,
                     ),
                 )
+            elif not port_inbound_recorded and message.get("port_type") in {
+                "string",
+                "json",
+            }:
+                value = message.get("value")
+                self._append_history(
+                    PortInboundEntry(
+                        from_id=from_id,
+                        from_output_port_key=str(
+                            message.get("from_output_port_key", "")
+                        ),
+                        to_input_port_key=str(message.get("to_input_port_key", "")),
+                        port_type=str(message.get("port_type", "")),
+                        value=value,
+                        value_summary=str(message.get("value_summary", "")),
+                    )
+                )
 
     def _wait_for_input(self) -> None:
         signal = self._wait_for_wakeup()
@@ -2422,6 +2705,9 @@ class Agent:
                 from_id = message.get("from")
                 message_id = message.get("message_id")
                 history_recorded = bool(message.get("history_recorded", False))
+                port_inbound_recorded = bool(
+                    message.get("port_inbound_recorded", False)
+                )
                 if (
                     isinstance(content, str)
                     and isinstance(from_id, str)
@@ -2436,6 +2722,24 @@ class Agent:
                             message_id=message_id,
                         )
                     )
+                elif (
+                    isinstance(from_id, str)
+                    and history_recorded
+                    and not port_inbound_recorded
+                    and message.get("port_type") in {"string", "json"}
+                ):
+                    self._append_history(
+                        PortInboundEntry(
+                            from_id=from_id,
+                            from_output_port_key=str(
+                                message.get("from_output_port_key", "")
+                            ),
+                            to_input_port_key=str(message.get("to_input_port_key", "")),
+                            port_type=str(message.get("port_type", "")),
+                            value=message.get("value"),
+                            value_summary=str(message.get("value_summary", "")),
+                        )
+                    )
 
         if signal.reason != "termination":
             self.set_state(
@@ -2657,6 +2961,18 @@ class Agent:
             "parts": [part.serialize() for part in msg.parts],
             "history_recorded": msg.history_recorded,
         }
+        if msg.from_output_port_key is not None:
+            payload["from_output_port_key"] = msg.from_output_port_key
+        if msg.to_input_port_key is not None:
+            payload["to_input_port_key"] = msg.to_input_port_key
+        if msg.port_type is not None:
+            payload["port_type"] = msg.port_type
+        if msg.value is not None:
+            payload["value"] = msg.value
+        if msg.value_summary is not None:
+            payload["value_summary"] = msg.value_summary
+        if msg.port_inbound_recorded:
+            payload["port_inbound_recorded"] = msg.port_inbound_recorded
         if msg.message_id is not None:
             payload["message_id"] = msg.message_id
         self._wake_queue.put(
@@ -2688,10 +3004,6 @@ class Agent:
                 self._idle_started_by_tool_call_id = None
             self._idle_state_event.clear()
         if old != state or force_emit:
-            if old != state:
-                self._append_history(
-                    StateEntry(state=state.value, reason=reason),
-                )
             self._log.debug(
                 "State: {} -> {}{}",
                 old.value,