execweave 0.8.27__tar.gz → 0.8.29__tar.gz

{execweave-0.8.27 → execweave-0.8.29}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: execweave
-Version: 0.8.27
+Version: 0.8.29
 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.27 → execweave-0.8.29}/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.27 → execweave-0.8.29}/pyproject.toml

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

{execweave-0.8.27 → execweave-0.8.29}/src/execweave/__init__.py

@@ -1,3 +1,3 @@
 """ExecWeave runtime graph package."""
 
-__version__ = "0.8.27"
+__version__ = "0.8.29"

{execweave-0.8.27 → execweave-0.8.29}/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.27 → execweave-0.8.29}/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
 
@@ -33,6 +36,7 @@ CANONICAL_EVENT_TYPES = frozenset(
     {
         "AGENT_CREATED", "AGENT_STARTED", "AGENT_STOPPED",
         "TASK_CREATED", "TASK_ASSIGNED", "TASK_STARTED", "TASK_UPDATED",
+        "TASK_CONTENT_RECORDED",
         "TASK_COMPLETED", "TASK_FAILED",
         "MESSAGE_SENT", "MESSAGE_RECEIVED", "MESSAGE_UNROUTED",
         "MODEL_REQUEST", "MODEL_RESPONSE", "MODEL_FAILURE",
@@ -136,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, ...] = ()
@@ -298,6 +316,8 @@ class TaskRecord:
     task: EntityRef
     owner: EntityRef | None = None
     parent_task: EntityRef | None = None
+    content: str | None = None
+    content_kind: str = "task_prompt"
     attributes: Mapping[str, Any] = field(default_factory=dict)
 
 
@@ -359,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:
@@ -391,9 +417,38 @@ class AdapterContext:
         return record.agent
 
     def record_task(self, record: TaskRecord, *, event_type: str = "TASK_CREATED") -> EntityRef:
-        self.emit(event_type, event_type, source=record.owner, target=record.task, attributes={"parent_task_id": record.parent_task.id if record.parent_task else None, **dict(record.attributes)})
+        content_reference = None
+        if record.content is not None:
+            content_kind = record.content_kind
+            if "." not in content_kind:
+                content_kind = f"{self.framework}.{content_kind}"
+            content_reference = self.content.put_text(record.content, content_kind=content_kind)
+        task_attributes = {
+            "parent_task_id": record.parent_task.id if record.parent_task else None,
+            **self.content.reference_attributes(content_reference),
+            **dict(record.attributes),
+        }
+        self.emit(event_type, event_type, source=record.owner, target=record.task, attributes=task_attributes)
         if record.parent_task is not None:
             self.emit("TASK_CREATED", "PARENT_TASK", source=record.parent_task, target=record.task, attributes={"parent_task_id": record.parent_task.id})
+        if content_reference is not None:
+            content = EntityRef(
+                "observed_content",
+                f"observed-content:task:sha256:{content_reference.sha256}",
+                content_reference.content_kind,
+                content_reference.to_dict(),
+            )
+            self.emit(
+                "TASK_CONTENT_RECORDED",
+                "HAS_TASK_CONTENT",
+                source=record.task,
+                target=content,
+                attributes={
+                    "task_id": record.task.id,
+                    "conversation_scope": "task",
+                    **self.content.reference_attributes(content_reference),
+                },
+            )
         return record.task
 
     def record_message(self, record: MessageRecord) -> EntityRef:

{execweave-0.8.27 → execweave-0.8.29}/src/execweave/framework_adapters/camel.py

@@ -11,7 +11,7 @@ from .base import AdapterCapabilities, AdapterContext, AgentRecord, EntityRef, F
 class CAMELAdapter(FrameworkAdapter):
     framework_name = "camel"
     capabilities = AdapterCapabilities(
-        events=("AGENT_CREATED", "AGENT_STARTED", "AGENT_STOPPED", "TASK_CREATED", "TASK_ASSIGNED", "TASK_STARTED", "TASK_UPDATED", "TASK_COMPLETED", "TASK_FAILED", "MESSAGE_SENT", "MESSAGE_RECEIVED", "MESSAGE_UNROUTED", "MODEL_REQUEST", "MODEL_RESPONSE", "MODEL_FAILURE"),
+        events=("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", "MESSAGE_UNROUTED", "MODEL_REQUEST", "MODEL_RESPONSE", "MODEL_FAILURE"),
         content_modes=("metadata_only", "content_ref_only", "prompt_only", "prompt_and_response"),
         authoritative_surfaces=("camel.societies.workforce.WorkforceCallback", "camel.models.BaseModelBackend.run", "camel.models.BaseModelBackend.arun"),
         known_limitations=("WorkforceCallback LogEvent does not expose the emitting worker or recipient; those log messages are explicitly marked MESSAGE_UNROUTED and correlated to the observed process instead of being assigned to a guessed agent.", "A created worker is not treated as assigned until CAMEL reports a task assignment."),
@@ -21,6 +21,7 @@ class CAMELAdapter(FrameworkAdapter):
         super().__init__(context)
         self._agents: dict[str, EntityRef] = {}
         self._tasks: dict[str, EntityRef] = {}
+        self._active_tasks_by_agent: dict[str, EntityRef] = {}
         self._message_counter = 0
 
     @classmethod
@@ -44,18 +45,43 @@ class CAMELAdapter(FrameworkAdapter):
     def agent_stopped(self, agent: EntityRef, **attributes: Any) -> None:
         self.emit("AGENT_STOPPED", "AGENT_STOPPED", source=agent, attributes=attributes)
 
-    def task_event(self, event_type: str, native_id: str | int, *, name: str | None = None, owner: EntityRef | None = None, parent: EntityRef | None = None, **attributes: Any) -> EntityRef:
-        task = self.task(native_id, name=name, provider="camel", **attributes)
+    def task_event(self, event_type: str, native_id: str | int, *, name: str | None = None, owner: EntityRef | None = None, parent: EntityRef | None = None, content: str | None = None, content_kind: str = "task_prompt", **attributes: Any) -> EntityRef:
+        existing = self._tasks.get(str(native_id))
+        if existing is not None and name is None and content is None and not attributes:
+            task = existing
+        else:
+            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(native_id, name=name, provider="camel", **entity_attributes)
         self._tasks[str(native_id)] = task
-        self.context.record_task(TaskRecord(task, owner=owner, parent_task=parent, attributes=attributes), event_type=event_type)
+        self.context.record_task(
+            TaskRecord(
+                task,
+                owner=owner,
+                parent_task=parent,
+                content=content,
+                content_kind=content_kind,
+                attributes=attributes,
+            ),
+            event_type=event_type,
+        )
         return task
 
     def task_created(self, native_id: str | int, **kwargs: Any) -> EntityRef:
         return self.task_event("TASK_CREATED", native_id, **kwargs)
 
     def task_assigned(self, task: EntityRef, agent: EntityRef, **attributes: Any) -> None:
+        self._active_tasks_by_agent[agent.id] = task
         self.emit("TASK_ASSIGNED", "ASSIGNED_TO", source=task, target=agent, attributes=attributes)
 
+    def active_task_for(self, agent: EntityRef | None) -> EntityRef | None:
+        """Return the latest provider-observed task assigned to an agent."""
+        return self._active_tasks_by_agent.get(agent.id) if agent is not None else None
+
     def task_started(self, task: EntityRef, agent: EntityRef | None = None, **attributes: Any) -> None:
         self.emit("TASK_STARTED", "TASK_STARTED", source=agent or task, target=task, attributes=attributes)
 
@@ -170,7 +196,11 @@ class CAMELAdapter(FrameworkAdapter):
         if name == "log_worker_created":
             return self.agent_created(_native(payload, "worker_id", "id", "name"), name=_string(_value(payload, "name", "role")), role=_string(_value(payload, "role", "worker_type")))
         if name == "log_task_created":
-            return self.task_created(_native(payload, "task_id", "id", "name"), name=_string(_value(payload, "name", "description")))
+            task_key = _native(payload, "task_id", "id", "name")
+            existing = self._tasks.get(str(task_key))
+            if existing is not None:
+                return existing
+            return self.task_created(task_key, name=_string(_value(payload, "name", "description")))
         if name == "log_task_assigned":
             task_key = _native(payload, "task_id", "id", "name")
             task = self._tasks.get(str(task_key)) or self.task_created(task_key)

{execweave-0.8.27 → execweave-0.8.29}/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.27 → execweave-0.8.29}/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.27 → execweave-0.8.29}/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.27 → execweave-0.8.29}/src/execweave/viewer_agent_panel.py

@@ -372,6 +372,10 @@ function execweaveNodeCardsBase(node){
     add('Command',a.command);
     add('Working directory',a.cwd);
     add('Backend',a.backend);
+  }else if(kind==='task'){
+    add('Task',a.task_prompt||a.prompt||a.description||node?.name);
+    add('Prompt',a.task_prompt||a.prompt||a.description);
+    add('Provider',a.provider);
   }else if(kind==='network_endpoint'){
     const endpoints=Array.isArray(a.endpoints)?a.endpoints:[];
     if(endpoints.length){
@@ -414,6 +418,26 @@ function toolOccurrenceSection(node){
   });
   return section;
 }
+function execweaveAssignedTaskText(agent){
+  if(!agent||String(agent.type||'')!=='agent')return '';
+  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;
@@ -432,10 +456,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.27 → execweave-0.8.29}/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,
     )