execweave 0.8.28__tar.gz → 0.8.31__tar.gz

{execweave-0.8.28 → execweave-0.8.31}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: execweave
-Version: 0.8.28
+Version: 0.8.31
 Summary: Turn AI-agent runtime behavior into a local interactive execution graph.
 Project-URL: Homepage, https://github.com/Irish-kw/ExecWeave
 Project-URL: Repository, https://github.com/Irish-kw/ExecWeave
@@ -388,5 +388,13 @@ Paper context: Li et al., *CAMEL: Communicative Agents for "Mind" Exploration of
 
 ```python
 from execweave.framework_adapters import AdapterContext, CAMELAdapter
-adapter = CAMELAdapter(AdapterContext.from_environment("camel"))
+context = AdapterContext.from_environment("camel", capture_mode="prompt_and_response")
+adapter = CAMELAdapter(context)
+task = adapter.task_created("task-1", content="Inspect the endpoint and report completion.")
 ```
+
+When the application is launched by `execweave record` or `execweave live`,
+the adapter automatically joins that run and the finished Dashboard is built
+from the merged runtime plus framework evidence. Task prompts and routed
+messages remain local content references and are visible from their task and
+agent nodes.

{execweave-0.8.28 → execweave-0.8.31}/README.md

@@ -328,5 +328,13 @@ Paper context: Li et al., *CAMEL: Communicative Agents for "Mind" Exploration of
 
 ```python
 from execweave.framework_adapters import AdapterContext, CAMELAdapter
-adapter = CAMELAdapter(AdapterContext.from_environment("camel"))
+context = AdapterContext.from_environment("camel", capture_mode="prompt_and_response")
+adapter = CAMELAdapter(context)
+task = adapter.task_created("task-1", content="Inspect the endpoint and report completion.")
 ```
+
+When the application is launched by `execweave record` or `execweave live`,
+the adapter automatically joins that run and the finished Dashboard is built
+from the merged runtime plus framework evidence. Task prompts and routed
+messages remain local content references and are visible from their task and
+agent nodes.

{execweave-0.8.28 → execweave-0.8.31}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "execweave"
-# ExecWeave v0.8.28 release metadata
-version = "0.8.28"
+# ExecWeave v0.8.31 release metadata
+version = "0.8.31"
 description = "Turn AI-agent runtime behavior into a local interactive execution graph."
 readme = "README.md"
 requires-python = ">=3.10"

{execweave-0.8.28 → execweave-0.8.31}/src/execweave/__init__.py

@@ -1,3 +1,3 @@
 """ExecWeave runtime graph package."""
 
-__version__ = "0.8.28"
+__version__ = "0.8.31"

{execweave-0.8.28 → execweave-0.8.31}/src/execweave/framework_adapters/autogen.py

@@ -15,6 +15,7 @@ from .base import (
     FrameworkCompatibility,
     MessageRecord,
     ModelCallRecord,
+    TaskRecord,
     ToolCallRecord,
 )
 
@@ -26,6 +27,13 @@ class AutoGenAdapter(FrameworkAdapter):
             "AGENT_CREATED",
             "AGENT_STARTED",
             "AGENT_STOPPED",
+            "TASK_CREATED",
+            "TASK_ASSIGNED",
+            "TASK_STARTED",
+            "TASK_UPDATED",
+            "TASK_COMPLETED",
+            "TASK_FAILED",
+            "TASK_CONTENT_RECORDED",
             "MESSAGE_SENT",
             "MESSAGE_RECEIVED",
             "MODEL_REQUEST",
@@ -86,6 +94,46 @@ class AutoGenAdapter(FrameworkAdapter):
         self.context.record_agent(AgentRecord(agent, role=role, process=process, attributes=attributes))
         return agent
 
+    def observe_task(
+        self,
+        task_id: str | int,
+        *,
+        owner: EntityRef | None = None,
+        name: str | None = None,
+        content: str | None = None,
+        content_kind: str = "task_prompt",
+        status: str = "created",
+        **attributes: Any,
+    ) -> EntityRef:
+        """Record an authoritative AutoGen task and its visible task prompt."""
+        entity_attributes = dict(attributes)
+        if content is not None and self.context.capture_policy.mode in {
+            "prompt_only",
+            "prompt_and_response",
+        }:
+            entity_attributes.setdefault("task_prompt", content)
+        task = self.task(task_id, name=name, provider="autogen", **entity_attributes)
+        event = {
+            "created": "TASK_CREATED",
+            "started": "TASK_STARTED",
+            "updated": "TASK_UPDATED",
+            "completed": "TASK_COMPLETED",
+            "failed": "TASK_FAILED",
+        }.get(status)
+        if event is None:
+            raise ValueError(f"unsupported AutoGen task status: {status}")
+        self.context.record_task(
+            TaskRecord(
+                task,
+                owner=owner,
+                content=content,
+                content_kind=content_kind,
+                attributes=attributes,
+            ),
+            event_type=event,
+        )
+        return task
+
     def observe_message(
         self,
         message_id: str | int,

{execweave-0.8.28 → execweave-0.8.31}/src/execweave/framework_adapters/base.py

@@ -11,6 +11,7 @@ import hashlib
 import json
 import os
 import re
+import sys
 import threading
 import time
 from dataclasses import asdict, dataclass, field
@@ -19,6 +20,8 @@ from pathlib import Path
 from typing import Any, Literal, Mapping
 from uuid import uuid4
 
+import psutil
+
 from ..content_store import ContentReference, FullFidelityContentStore
 from ..schema import SCHEMA_VERSION
 
@@ -137,6 +140,20 @@ class ProcessRef:
         return EntityRef("process_reference", f"process-reference:{identity}", self.executable or f"pid {self.pid}", attributes)
 
 
+def _current_process_ref() -> ProcessRef:
+    """Return the authoritative identity of the adapter's current process."""
+    process = psutil.Process(os.getpid())
+    try:
+        create_time = process.create_time()
+    except (psutil.AccessDenied, psutil.NoSuchProcess, psutil.ZombieProcess):
+        create_time = None
+    try:
+        executable = process.exe()
+    except (psutil.AccessDenied, psutil.NoSuchProcess, psutil.ZombieProcess):
+        executable = sys.executable
+    return ProcessRef(os.getpid(), create_time, executable or sys.executable)
+
+
 @dataclass(frozen=True)
 class AdapterCapabilities:
     events: tuple[str, ...] = ()
@@ -362,6 +379,12 @@ class AdapterContext:
 
     @classmethod
     def from_environment(cls, framework: str, *, capture_mode: CaptureMode = "metadata_only", content_root: str | Path | None = None, run_id: str | None = None, session_id: str | None = None, conversation_id: str | None = None, process: ProcessRef | None = None) -> "AdapterContext":
+        if (
+            process is None
+            and os.environ.get("EXECWEAVE_SEMANTIC_SIDECAR")
+            and os.environ.get("EXECWEAVE_SESSION_ID")
+        ):
+            process = _current_process_ref()
         return cls(framework=framework, run_id=run_id, session_id=session_id, conversation_id=conversation_id, content_root=content_root, capture_policy=ContentCapturePolicy(capture_mode), process=process)
 
     def entity(self, entity_type: str, native_id: str | int | None, *, name: str | None = None, attributes: Mapping[str, Any] | None = None) -> EntityRef:

{execweave-0.8.28 → execweave-0.8.31}/src/execweave/framework_adapters/camel.py

@@ -51,7 +51,10 @@ class CAMELAdapter(FrameworkAdapter):
             task = existing
         else:
             entity_attributes = dict(attributes)
-            if content is not None:
+            if content is not None and self.context.capture_policy.mode in {
+                "prompt_only",
+                "prompt_and_response",
+            }:
                 entity_attributes.setdefault("task_prompt", content)
             task = self.task(native_id, name=name, provider="camel", **entity_attributes)
         self._tasks[str(native_id)] = task

{execweave-0.8.28 → execweave-0.8.31}/src/execweave/framework_adapters/metagpt.py

@@ -30,6 +30,7 @@ class MetaGPTAdapter(FrameworkAdapter):
             "TASK_COMPLETED",
             "TASK_FAILED",
             "TASK_UPDATED",
+            "TASK_CONTENT_RECORDED",
             "MESSAGE_SENT",
             "MESSAGE_RECEIVED",
             "MODEL_REQUEST",
@@ -96,10 +97,18 @@ class MetaGPTAdapter(FrameworkAdapter):
         *,
         owner: EntityRef | None = None,
         name: str | None = None,
+        content: str | None = None,
+        content_kind: str = "task_prompt",
         status: str = "created",
         **attributes: Any,
     ) -> EntityRef:
-        task = self.task(task_id, name=name, provider="metagpt", **attributes)
+        entity_attributes = dict(attributes)
+        if content is not None and self.context.capture_policy.mode in {
+            "prompt_only",
+            "prompt_and_response",
+        }:
+            entity_attributes.setdefault("task_prompt", content)
+        task = self.task(task_id, name=name, provider="metagpt", **entity_attributes)
         event = {
             "created": "TASK_CREATED",
             "started": "TASK_STARTED",
@@ -108,7 +117,16 @@ class MetaGPTAdapter(FrameworkAdapter):
         }.get(status)
         if event is None:
             raise ValueError(f"unsupported MetaGPT task status: {status}")
-        self.context.record_task(TaskRecord(task, owner=owner, attributes=attributes), event_type=event)
+        self.context.record_task(
+            TaskRecord(
+                task,
+                owner=owner,
+                content=content,
+                content_kind=content_kind,
+                attributes=attributes,
+            ),
+            event_type=event,
+        )
         return task
 
     def observe_message(

{execweave-0.8.28 → execweave-0.8.31}/src/execweave/live_core.py

@@ -37,6 +37,8 @@ from .viewer import (
 LIVE_DELTA_HISTORY = 256
 LIVE_DELTA_HISTORY_BYTES = 8 * 1024 * 1024
 _SEMANTIC_ENV = "EXECWEAVE_SEMANTIC_SIDECAR"
+_RUN_ID_ENV = "EXECWEAVE_RUN_ID"
+_SESSION_ID_ENV = "EXECWEAVE_SESSION_ID"
 _LIVE_TOKEN_HEADER = "X-ExecWeave-Token"
 
 _FINAL_THEME_CSS = """
@@ -737,16 +739,24 @@ def run_live(
         webbrowser.open(authenticated_live_url)
 
     return_code = 1
-    previous_semantic_sidecar = os.environ.get(_SEMANTIC_ENV)
-    os.environ[_SEMANTIC_ENV] = str(semantic_path)
+    environment_updates = {
+        _SEMANTIC_ENV: str(semantic_path),
+        _RUN_ID_ENV: session_id,
+        _SESSION_ID_ENV: session_id,
+    }
+    previous_environment = {
+        key: os.environ.get(key) for key in environment_updates
+    }
+    os.environ.update(environment_updates)
     try:
         try:
             return_code = collector.run(command)
         finally:
-            if previous_semantic_sidecar is None:
-                os.environ.pop(_SEMANTIC_ENV, None)
-            else:
-                os.environ[_SEMANTIC_ENV] = previous_semantic_sidecar
+            for key, value in previous_environment.items():
+                if value is None:
+                    os.environ.pop(key, None)
+                else:
+                    os.environ[key] = value
 
         validation = validate_event_stream(event_path)
         if not validation.valid:

{execweave-0.8.28 → execweave-0.8.31}/src/execweave/provider_record.py

@@ -183,6 +183,7 @@ def record_provider_to_viewer(
             collect_network=collect_network,
             keep_raw_trace=keep_raw_trace,
             open_browser=False,
+            integrate_semantic=False,
         )
     finally:
         _restore_environment(previous_environment)

{execweave-0.8.28 → execweave-0.8.31}/src/execweave/viewer_agent_panel.py

@@ -418,6 +418,28 @@ function toolOccurrenceSection(node){
   });
   return section;
 }
+function execweaveAssignedTaskText(agent){
+  if(!agent||String(agent.type||'')!=='agent')return '';
+  const projected=attrs(agent),attached=projected.viewer_assigned_task_prompt||projected.viewer_assigned_task_name;
+  if(attached)return commandText(attached);
+  const graph=rawGraph(),nodes=Array.isArray(graph.nodes)?graph.nodes:[],edges=Array.isArray(graph.edges)?graph.edges:[];
+  const nodeMap=new Map(nodes.filter(node=>node&&node.id).map(node=>[String(node.id),node]));
+  const exactAssignment=['ASSIGNED','AGENT','TASK'].join('_');
+  const direct=edges.filter(edge=>edge&&String(edge.target||'')===String(agent.id||'')&&['ASSIGNED_TO',exactAssignment].includes(String(edge.relation||''))).sort((a,b)=>(Number(a.first_sequence)||0)-(Number(b.first_sequence)||0));
+  const owned=edges.filter(edge=>edge&&String(edge.source||'')===String(agent.id||'')&&String(edge.relation||'')==='TASK_CREATED').sort((a,b)=>(Number(a.first_sequence)||0)-(Number(b.first_sequence)||0));
+  const started=edges.filter(edge=>edge&&String(edge.source||'')===String(agent.id||'')&&String(edge.relation||'')==='TASK_STARTED').sort((a,b)=>(Number(a.first_sequence)||0)-(Number(b.first_sequence)||0));
+  const edge=direct.at(-1)||owned.at(-1)||started.at(-1);if(!edge)return '';
+  const taskId=direct.length?edge.source:edge.target,task=nodeMap.get(String(taskId||''));
+  if(!task||String(task.type||'')!=='task')return '';
+  const a=attrs(task);return commandText(a.task_prompt||a.prompt||a.description||task.name);
+}
+function execweaveFillAssignedTask(round,node,isRoot){
+  const task=execweaveAssignedTaskText(node);if(!task)return round;
+  const value=round||{cards:[]},cards=Array.isArray(value.cards)?value.cards.map(card=>[card[0],card[1]]):[];
+  const label=isRoot?'Prompt':'Task',index=cards.findIndex(card=>String(card[0]||'')===label);
+  if(index<0)cards.unshift([label,task]);else if(!commandText(cards[index][1]))cards[index][1]=task;
+  return{...value,cards};
+}
 function renderNode(node){
   const rows=nodeCards(node);
   if(!rows.length)return false;
@@ -436,10 +458,11 @@ function render(node){
   selectedNode=node;selectedConversationSignature=conversationSignature(node);detailsEmpty.hidden=true;details.replaceChildren();
   const record=recordFor(node),preview=record?.conversation_preview||{},path=String(preview.agent_path||nodePath(node)||'').trim(),messages=Array.isArray(preview.messages)?preview.messages:[];
   const isRoot=nodeHasRootAuthority(node)||previewUsesRootRenderer(preview);
-  const rounds=isRoot?rootRounds(messages,path||'/root'):childRounds(messages,path);
+  const rounds=(isRoot?rootRounds(messages,path||'/root'):childRounds(messages,path)).map(round=>execweaveFillAssignedTask(round,node,isRoot));
   const tools=toolCallsFor(String(node.id||''));
-  const appendTools=()=>{if(tools)details.appendChild(card('Tools',tools))};
-  if(rounds.length<2){details.appendChild(roundView(rounds[0]||{cards:isRoot?[['Prompt',''],['Final response','']]:[['Task',''],['Thinking',''],['Response','']]}));appendTools();return true}
+  const frameworkCommunication=attrs(node).conversation_scope==='framework_agent'?uniqueTexts(messages.filter(message=>isObserved(message)&&!isInjected(message)&&String(message?.kind||'')==='agent_message')).join('\n\n'):'';
+  const appendTools=()=>{if(frameworkCommunication)details.appendChild(card('Agent communication',frameworkCommunication));if(tools)details.appendChild(card('Tools',tools))};
+  if(rounds.length<2){const fallback={cards:isRoot?[['Prompt',''],['Final response','']]:[['Task',''],['Thinking',''],['Response','']]};details.appendChild(roundView(rounds[0]||execweaveFillAssignedTask(fallback,node,isRoot)));appendTools();return true}
   // A subagent borrows the moment and the wording of the unique canonical root round
   // it belongs to. If root identity is ambiguous, the child keeps its own timestamp.
   const runs=isRoot?rounds:runRounds();

{execweave-0.8.28 → execweave-0.8.31}/src/execweave/viewer_semantic_projection.py

@@ -258,6 +258,151 @@ def orphan_audit(nodes: list[dict[str, Any]], edges: list[dict[str, Any]]) -> di
     return {"count": sum(item["count"] for item in by_type), "by_type": by_type}
 
 
+_FRAMEWORK_TASK_RELATIONS = frozenset(
+    {"ASSIGNED_TO", "TASK_CREATED", "TASK_STARTED", "TASK_UPDATED", "TASK_COMPLETED", "TASK_FAILED"}
+)
+
+
+def _framework_task_edge_score(edge: dict[str, Any]) -> tuple[int, str, str]:
+    sequence = edge.get("last_sequence")
+    if not isinstance(sequence, int) or isinstance(sequence, bool):
+        sequence = edge.get("first_sequence")
+    if not isinstance(sequence, int) or isinstance(sequence, bool):
+        sequence = -1
+    return (sequence, str(edge.get("last_seen") or edge.get("first_seen") or ""), str(edge.get("id") or ""))
+
+
+def _framework_task_text(task: dict[str, Any]) -> str:
+    attributes = _attrs(task)
+    for value in (
+        attributes.get("task_prompt"),
+        attributes.get("prompt"),
+        attributes.get("description"),
+        task.get("name"),
+    ):
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+    return ""
+
+
+def collapse_framework_tasks(
+    nodes: list[dict[str, Any]],
+    edges: list[dict[str, Any]],
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]], dict[str, int]]:
+    """Fold framework task presentation into the owning agent, like provider views.
+
+    Framework adapters retain first-class task entities in the raw graph because task
+    lifecycle and prompt evidence must remain auditable.  Provider dashboards expose
+    that same information on the agent card, however, so the viewer projection hides
+    only framework task nodes and copies the latest authoritative task text onto each
+    assigned framework agent.  Provider graphs are untouched because they do not use
+    the framework-agent conversation scope.
+    """
+    node_by_id = {
+        str(node["id"]): node
+        for node in nodes
+        if isinstance(node, dict) and isinstance(node.get("id"), str)
+    }
+    framework_agents = {
+        node_id
+        for node_id, node in node_by_id.items()
+        if node.get("type") == "agent" and _attrs(node).get("conversation_scope") == "framework_agent"
+    }
+    if not framework_agents:
+        return nodes, edges, {
+            "framework_task_node_count": 0,
+            "framework_task_content_node_count": 0,
+            "framework_task_agent_count": 0,
+        }
+
+    task_ids: set[str] = set()
+    tasks_by_agent: dict[str, list[tuple[tuple[int, str, str], str]]] = defaultdict(list)
+    for edge in edges:
+        if not isinstance(edge, dict) or edge.get("relation") not in _FRAMEWORK_TASK_RELATIONS:
+            continue
+        source = str(edge.get("source") or "")
+        target = str(edge.get("target") or "")
+        source_node = node_by_id.get(source)
+        target_node = node_by_id.get(target)
+        task_id = source if source_node and source_node.get("type") == "task" else target if target_node and target_node.get("type") == "task" else None
+        if task_id is None:
+            continue
+        agent_id = source if source in framework_agents else target if target in framework_agents else None
+        if agent_id is None:
+            continue
+        task_ids.add(task_id)
+        tasks_by_agent[agent_id].append((_framework_task_edge_score(edge), task_id))
+
+    if not task_ids:
+        return nodes, edges, {
+            "framework_task_node_count": 0,
+            "framework_task_content_node_count": 0,
+            "framework_task_agent_count": 0,
+        }
+
+    projected_nodes: list[dict[str, Any]] = []
+    for node in nodes:
+        node_id = str(node.get("id") or "")
+        if node_id in task_ids:
+            continue
+        if node.get("type") == "agent" and node_id in framework_agents:
+            candidates: dict[str, tuple[int, str, str]] = {}
+            for score, task_id in tasks_by_agent.get(node_id, []):
+                previous = candidates.get(task_id)
+                if previous is None or score > previous:
+                    candidates[task_id] = score
+            ordered_ids = [
+                task_id
+                for task_id, _ in sorted(
+                    candidates.items(),
+                    key=lambda item: (item[1], item[0]),
+                    reverse=True,
+                )
+            ]
+            latest_task = node_by_id.get(ordered_ids[0]) if ordered_ids else None
+            attributes = dict(_attrs(node))
+            attributes["viewer_assigned_task_ids"] = ordered_ids
+            attributes["viewer_assigned_task_count"] = len(ordered_ids)
+            if latest_task is not None:
+                attributes["viewer_assigned_task_id"] = str(latest_task.get("id") or "")
+                attributes["viewer_assigned_task_name"] = str(latest_task.get("name") or "")
+                task_text = _framework_task_text(latest_task)
+                if task_text:
+                    attributes["viewer_assigned_task_prompt"] = task_text
+            projected_nodes.append({**node, "attributes": attributes})
+            continue
+        projected_nodes.append(node)
+
+    hidden_content_ids: set[str] = set()
+    for node in nodes:
+        node_id = str(node.get("id") or "")
+        if node.get("type") != "observed_content" or not node_id:
+            continue
+        incident = [
+            edge
+            for edge in edges
+            if edge.get("source") == node_id or edge.get("target") == node_id
+        ]
+        if incident and all(
+            (edge.get("source") in task_ids or edge.get("target") in task_ids)
+            for edge in incident
+        ):
+            hidden_content_ids.add(node_id)
+
+    hidden_ids = task_ids | hidden_content_ids
+    projected_nodes = [node for node in projected_nodes if str(node.get("id") or "") not in hidden_content_ids]
+    projected_edges = [
+        edge
+        for edge in edges
+        if edge.get("source") not in hidden_ids and edge.get("target") not in hidden_ids
+    ]
+    return projected_nodes, projected_edges, {
+        "framework_task_node_count": len(task_ids),
+        "framework_task_content_node_count": len(hidden_content_ids),
+        "framework_task_agent_count": len(tasks_by_agent),
+    }
+
+
 def project_provider_neutral_viewer_graph(graph: dict[str, Any]) -> dict[str, Any]:
     """Provider-neutral display projection; raw graph/evidence remains unchanged."""
     from . import viewer_projection_base as base
@@ -268,6 +413,7 @@ def project_provider_neutral_viewer_graph(graph: dict[str, Any]) -> dict[str, An
     nodes = [deepcopy(n) for n in filtered.get("nodes", []) if isinstance(n, dict)]
     edges = [deepcopy(e) for e in filtered.get("edges", []) if isinstance(e, dict)]
     entries = _entries(graph)
+    nodes, edges, framework_tasks = collapse_framework_tasks(nodes, edges)
     nodes, edges, inference = collapse_inference_requests(nodes, edges, entries)
     roots, _ = _roots(nodes, entries)
     nodes, edges, files = collapse_orphan_files(nodes, edges, roots[0] if len(roots) == 1 else None)
@@ -297,6 +443,7 @@ def project_provider_neutral_viewer_graph(graph: dict[str, Any]) -> dict[str, An
         or inference["collapsed_request_count"]
         or local is not None
         or files is not None
+        or framework_tasks["framework_task_node_count"]
     )
     if not topology_changed:
         if audit["count"]:
@@ -313,6 +460,9 @@ def project_provider_neutral_viewer_graph(graph: dict[str, Any]) -> dict[str, An
         "orphan_file_node_count": len(files.get("nodes") or []) if files else 0,
         "inference_request_count": inference["collapsed_request_count"], "logical_inference_count": inference["logical_inference_count"],
         "direct_inference_edge_count": inference["direct_inference_edge_count"], "unresolved_inference_requests": inference["unresolved"],
+        "framework_task_node_count": framework_tasks["framework_task_node_count"],
+        "framework_task_content_node_count": framework_tasks["framework_task_content_node_count"],
+        "framework_task_agent_count": framework_tasks["framework_task_agent_count"],
         "internal_hook_node_count": len(hook_nodes), "internal_hook_edge_count": len(hook_edges),
         "projection_topology_changed": True,
     })

{execweave-0.8.28 → execweave-0.8.31}/src/execweave/workflow.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import os
 from dataclasses import dataclass
 from pathlib import Path
 from uuid import uuid4
@@ -7,11 +8,16 @@ from uuid import uuid4
 from .backends import BackendName, create_collector, resolve_backend
 from .fidelity import write_fidelity_report
 from .graph import build_execution_graph, write_execution_graph
+from .semantic import merge_semantic_sidecar
 from .sink import JsonlSink
 from .theme import ensure_viewer_theme
 from .validate import validate_event_stream
 from .viewer_projection import strip_internal_hook_execution_graph, write_graph_html
 
+_SEMANTIC_ENV = "EXECWEAVE_SEMANTIC_SIDECAR"
+_RUN_ID_ENV = "EXECWEAVE_RUN_ID"
+_SESSION_ID_ENV = "EXECWEAVE_SESSION_ID"
+
 
 @dataclass(frozen=True)
 class RecordResult:
@@ -26,6 +32,9 @@ class RecordResult:
     event_count: int
     node_count: int
     edge_count: int
+    semantic_sidecar: Path | None = None
+    materialized_event_stream: Path | None = None
+    semantic_event_count: int = 0
 
     def to_dict(self) -> dict[str, object]:
         return {
@@ -40,6 +49,15 @@ class RecordResult:
             "event_count": self.event_count,
             "node_count": self.node_count,
             "edge_count": self.edge_count,
+            "semantic_sidecar": (
+                str(self.semantic_sidecar) if self.semantic_sidecar is not None else None
+            ),
+            "materialized_event_stream": (
+                str(self.materialized_event_stream)
+                if self.materialized_event_stream is not None
+                else str(self.event_stream)
+            ),
+            "semantic_event_count": self.semantic_event_count,
         }
 
 
@@ -61,6 +79,7 @@ def record_to_viewer(
     collect_network: bool = True,
     keep_raw_trace: bool = False,
     open_browser: bool = False,
+    integrate_semantic: bool = True,
 ) -> RecordResult:
     """Record one command and materialize a local graph/viewer after it exits."""
     if not command:
@@ -79,7 +98,12 @@ def record_to_viewer(
     fidelity_path = run_dir / "fidelity.json"
     graph_path = run_dir / "graph.json"
     viewer_path = run_dir / "viewer.html"
-    _preflight_artifacts([event_path, fidelity_path, graph_path, viewer_path])
+    semantic_path = run_dir / "semantic.jsonl"
+    merged_event_path = run_dir / "events.semantic.jsonl"
+    artifacts = [event_path, fidelity_path, graph_path, viewer_path]
+    if integrate_semantic:
+        artifacts.extend([semantic_path, merged_event_path])
+    _preflight_artifacts(artifacts)
 
     sink = JsonlSink(event_path)
     resolved = resolve_backend(backend)
@@ -94,14 +118,44 @@ def record_to_viewer(
         keep_raw_trace=keep_raw_trace,
     )
 
-    return_code = collector.run(command)
+    environment_updates = {
+        _RUN_ID_ENV: session_id,
+        _SESSION_ID_ENV: session_id,
+    }
+    if integrate_semantic:
+        environment_updates[_SEMANTIC_ENV] = str(semantic_path)
+    previous_environment = {
+        key: os.environ.get(key) for key in environment_updates
+    }
+    os.environ.update(environment_updates)
+    try:
+        return_code = collector.run(command)
+    finally:
+        for key, value in previous_environment.items():
+            if value is None:
+                os.environ.pop(key, None)
+            else:
+                os.environ[key] = value
 
     validation = validate_event_stream(event_path)
     if not validation.valid:
         details = "; ".join(validation.errors)
         raise RuntimeError(f"recorded event stream failed validation: {details}")
 
-    execution_graph = strip_internal_hook_execution_graph(build_execution_graph(event_path))
+    materialized_event_path = event_path
+    semantic_event_count = 0
+    if integrate_semantic and semantic_path.exists() and semantic_path.stat().st_size > 0:
+        semantic_merge = merge_semantic_sidecar(
+            event_path,
+            semantic_path,
+            merged_event_path,
+        )
+        materialized_event_path = merged_event_path
+        semantic_event_count = semantic_merge.semantic_event_count
+
+    execution_graph = strip_internal_hook_execution_graph(
+        build_execution_graph(materialized_event_path)
+    )
     write_fidelity_report(execution_graph.fidelity, fidelity_path)
     write_execution_graph(execution_graph, graph_path)
     write_graph_html(execution_graph.to_dict(), viewer_path, open_browser=False)
@@ -123,4 +177,7 @@ def record_to_viewer(
         event_count=execution_graph.event_count,
         node_count=len(execution_graph.nodes),
         edge_count=len(execution_graph.edges),
+        semantic_sidecar=semantic_path.resolve() if integrate_semantic else None,
+        materialized_event_stream=materialized_event_path.resolve(),
+        semantic_event_count=semantic_event_count,
     )