abstractgateway 0.1.0__py3-none-any.whl → 0.1.1__py3-none-any.whl

abstractgateway/hosts/bundle_host.py

@@ -1,15 +1,20 @@
 from __future__ import annotations
 
+import json
 import logging
 import os
-from dataclasses import dataclass
+import re
+import threading
+from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Dict, Optional, Tuple
 
-from abstractruntime import Runtime, WorkflowRegistry, WorkflowSpec
+from abstractruntime import Runtime, WorkflowRegistry, WorkflowSpec, persist_workflow_snapshot
 from abstractruntime.visualflow_compiler import compile_visualflow
 from abstractruntime.workflow_bundle import WorkflowBundle, WorkflowBundleError, open_workflow_bundle
 
+from ..workflow_deprecations import WorkflowDeprecatedError, WorkflowDeprecationStore
+
 
 logger = logging.getLogger(__name__)
 
@@ -18,6 +23,66 @@ def _namespace(bundle_id: str, flow_id: str) -> str:
     return f"{bundle_id}:{flow_id}"
 
 
+def _bundle_ref(bundle_id: str, bundle_version: str) -> str:
+    bid = str(bundle_id or "").strip()
+    bv = str(bundle_version or "").strip()
+    if not bid:
+        raise ValueError("bundle_id is required")
+    if not bv:
+        raise ValueError("bundle_version is required")
+    return f"{bid}@{bv}"
+
+
+def _split_bundle_ref(raw: str) -> tuple[str, Optional[str]]:
+    s = str(raw or "").strip()
+    if not s:
+        return ("", None)
+    if "@" not in s:
+        return (s, None)
+    a, b = s.split("@", 1)
+    a = a.strip()
+    b = b.strip()
+    if not a:
+        return ("", None)
+    if not b:
+        return (a, None)
+    return (a, b)
+
+
+def _try_parse_semver(v: str) -> Optional[tuple[int, int, int]]:
+    s = str(v or "").strip()
+    if not s:
+        return None
+    parts = [p.strip() for p in s.split(".")]
+    if not parts or any(not p for p in parts):
+        return None
+    nums: list[int] = []
+    for p in parts:
+        if not p.isdigit():
+            return None
+        nums.append(int(p))
+    while len(nums) < 3:
+        nums.append(0)
+    return (nums[0], nums[1], nums[2])
+
+
+def _pick_latest_version(versions: Dict[str, WorkflowBundle]) -> str:
+    items = [(str(k), v) for k, v in (versions or {}).items() if isinstance(k, str)]
+    if not items:
+        return "0.0.0"
+
+    if all(_try_parse_semver(ver) is not None for ver, _ in items):
+        return max(items, key=lambda x: _try_parse_semver(x[0]) or (0, 0, 0))[0]
+
+    # Fallback when versions are not semver-like: prefer newest created_at.
+    def _key(x: tuple[str, WorkflowBundle]) -> tuple[str, str]:
+        ver, b = x
+        created = str(getattr(getattr(b, "manifest", None), "created_at", "") or "")
+        return (created, ver)
+
+    return max(items, key=_key)[0]
+
+
 def _coerce_namespaced_id(*, bundle_id: Optional[str], flow_id: str, default_bundle_id: Optional[str]) -> str:
     fid = str(flow_id or "").strip()
     if not fid:
@@ -192,6 +257,17 @@ def _flow_uses_tools(raw: Dict[str, Any]) -> bool:
     return False
 
 
+def _flow_uses_memory_kg(raw: Dict[str, Any]) -> bool:
+    nodes = raw.get("nodes")
+    if not isinstance(nodes, list):
+        return False
+    for n in nodes:
+        t = _node_type_from_raw(n)
+        if t in {"memory_kg_assert", "memory_kg_query"}:
+            return True
+    return False
+
+
 def _collect_agent_nodes(raw: Dict[str, Any]) -> list[tuple[str, Dict[str, Any]]]:
     nodes = raw.get("nodes")
     if not isinstance(nodes, list):
@@ -229,7 +305,7 @@ def _visual_event_listener_workflow_id(*, flow_id: str, node_id: str) -> str:
     return f"visual_event_listener_{_sanitize(flow_id)}_{_sanitize(node_id)}"
 
 
-@dataclass(frozen=True)
+@dataclass
 class WorkflowBundleGatewayHost:
     """Gateway host that starts/ticks runs from WorkflowBundles (no AbstractFlow import).
 
@@ -238,17 +314,139 @@ class WorkflowBundleGatewayHost:
     """
 
     bundles_dir: Path
-    bundles: Dict[str, WorkflowBundle]
+    data_dir: Path
+    dynamic_flows_dir: Path
+    deprecation_store: WorkflowDeprecationStore
+    # bundle_id -> bundle_version -> WorkflowBundle
+    bundles: Dict[str, Dict[str, WorkflowBundle]]
+    # bundle_id -> latest bundle_version
+    latest_bundle_versions: Dict[str, str]
     runtime: Runtime
     workflow_registry: WorkflowRegistry
     specs: Dict[str, WorkflowSpec]
     event_listener_specs_by_root: Dict[str, list[str]]
     _default_bundle_id: Optional[str]
+    _lock: Any = field(default_factory=threading.RLock, repr=False, compare=False)
+
+    @staticmethod
+    def _dynamic_flow_filename(workflow_id: str) -> str:
+        safe_re = re.compile(r"[^a-zA-Z0-9._-]+")
+        s = safe_re.sub("_", str(workflow_id or "").strip())
+        if not s or s in {".", ".."}:
+            s = "workflow"
+        return f"{s}.json"
+
+    def _dynamic_flow_path(self, workflow_id: str) -> Path:
+        return Path(self.dynamic_flows_dir) / self._dynamic_flow_filename(workflow_id)
+
+    def load_dynamic_visualflow(self, workflow_id: str) -> Optional[Dict[str, Any]]:
+        """Load a persisted dynamic VisualFlow JSON from disk (best-effort)."""
+        wid = str(workflow_id or "").strip()
+        if not wid:
+            return None
+        p = self._dynamic_flow_path(wid)
+        if not p.exists() or not p.is_file():
+            return None
+        try:
+            raw = json.loads(p.read_text(encoding="utf-8"))
+        except Exception:
+            return None
+        return raw if isinstance(raw, dict) else None
+
+    def register_dynamic_visualflow(self, raw: Dict[str, Any], *, persist: bool = True) -> str:
+        """Register a VisualFlow JSON object as a dynamic workflow (durable in data_dir).
+
+        This is used for gateway-generated wrapper workflows (e.g. scheduled runs).
+        """
+        if not isinstance(raw, dict):
+            raise TypeError("Dynamic VisualFlow must be an object")
+        wid = str(raw.get("id") or "").strip()
+        if not wid:
+            raise ValueError("Dynamic VisualFlow missing required 'id'")
+
+        spec = compile_visualflow(raw)
+        self.workflow_registry.register(spec)
+        self.specs[str(spec.workflow_id)] = spec
+
+        if persist:
+            try:
+                Path(self.dynamic_flows_dir).mkdir(parents=True, exist_ok=True)
+                p = self._dynamic_flow_path(str(spec.workflow_id))
+                p.write_text(json.dumps(raw, ensure_ascii=False, indent=2), encoding="utf-8")
+            except Exception as e:
+                raise RuntimeError(f"Failed to persist dynamic VisualFlow: {e}") from e
+
+        return str(spec.workflow_id)
+
+    def upsert_dynamic_visualflow(self, raw: Dict[str, Any], *, persist: bool = True) -> str:
+        """Register or replace a dynamic VisualFlow JSON object (durable in data_dir).
+
+        This is used for gateway-generated wrapper workflows that must be edited in-place
+        (e.g. rescheduling a recurrent job without killing the parent run).
+        """
+        if not isinstance(raw, dict):
+            raise TypeError("Dynamic VisualFlow must be an object")
+        wid = str(raw.get("id") or "").strip()
+        if not wid:
+            raise ValueError("Dynamic VisualFlow missing required 'id'")
+
+        spec = compile_visualflow(raw)
+        with self._lock:
+            try:
+                existing = self.workflow_registry.get(spec.workflow_id)
+            except Exception:
+                existing = None
+            if existing is not None:
+                try:
+                    self.workflow_registry.unregister(spec.workflow_id)
+                except Exception:
+                    pass
+            try:
+                self.workflow_registry.register(spec)
+            except Exception as e:
+                raise RuntimeError(f"Failed to register workflow '{spec.workflow_id}': {e}") from e
+
+            self.specs[str(spec.workflow_id)] = spec
+
+            if persist:
+                try:
+                    Path(self.dynamic_flows_dir).mkdir(parents=True, exist_ok=True)
+                    p = self._dynamic_flow_path(str(spec.workflow_id))
+                    p.write_text(json.dumps(raw, ensure_ascii=False, indent=2), encoding="utf-8")
+                except Exception as e:
+                    raise RuntimeError(f"Failed to persist dynamic VisualFlow: {e}") from e
+
+        return str(spec.workflow_id)
+
+    def _try_register_dynamic_workflow_from_disk(self, workflow_id: str) -> Optional[WorkflowSpec]:
+        wid = str(workflow_id or "").strip()
+        if not wid:
+            return None
+        p = self._dynamic_flow_path(wid)
+        if not p.exists() or not p.is_file():
+            return None
+        try:
+            raw = json.loads(p.read_text(encoding="utf-8"))
+        except Exception:
+            return None
+        if not isinstance(raw, dict):
+            return None
+        try:
+            spec = compile_visualflow(raw)
+        except Exception:
+            return None
+        try:
+            self.workflow_registry.register(spec)
+            self.specs[str(spec.workflow_id)] = spec
+        except Exception:
+            return None
+        return spec
 
     @staticmethod
     def load_from_dir(
         *,
         bundles_dir: Path,
+        data_dir: Path,
         run_store: Any,
         ledger_store: Any,
         artifact_store: Any,
@@ -263,52 +461,150 @@ class WorkflowBundleGatewayHost:
         else:
             bundle_paths = sorted([p for p in base.glob("*.flow") if p.is_file()])
 
-        bundles: Dict[str, WorkflowBundle] = {}
+        bundles_by_id: Dict[str, Dict[str, WorkflowBundle]] = {}
         for p in bundle_paths:
             try:
                 b = open_workflow_bundle(p)
-                bundles[str(b.manifest.bundle_id)] = b
+                bid = str(getattr(getattr(b, "manifest", None), "bundle_id", "") or "").strip()
+                bver = str(getattr(getattr(b, "manifest", None), "bundle_version", "0.0.0") or "0.0.0").strip() or "0.0.0"
+                if not bid:
+                    raise WorkflowBundleError(f"Bundle '{p}' has empty bundle_id")
+                versions = bundles_by_id.setdefault(bid, {})
+                if bver in versions:
+                    logger.warning("Duplicate bundle version '%s@%s' at %s; keeping first", bid, bver, p)
+                    continue
+                versions[bver] = b
             except Exception as e:
                 logger.warning("Failed to load bundle %s: %s", p, e)
 
-        if not bundles:
-            raise FileNotFoundError(f"No bundles found in {base} (expected *.flow)")
+        if not bundles_by_id:
+            logger.warning("No bundles found in %s (expected *.flow). Starting gateway with zero loaded bundles.", base)
+
+        default_bundle_id = next(iter(bundles_by_id.keys())) if len(bundles_by_id) == 1 else None
+        latest_versions: Dict[str, str] = {bid: _pick_latest_version(versions) for bid, versions in bundles_by_id.items()}
 
-        default_bundle_id = next(iter(bundles.keys())) if len(bundles) == 1 else None
+        data_root = Path(data_dir).expanduser().resolve()
+        dep_store = WorkflowDeprecationStore(path=data_root / "workflow_deprecations.json")
+        dynamic_dir = data_root / "dynamic_flows"
+        try:
+            dynamic_dir.mkdir(parents=True, exist_ok=True)
+        except Exception:
+            # Best-effort: dynamic workflows are optional.
+            pass
 
         # Build runtime + registry and register all workflow specs.
         wf_reg: WorkflowRegistry = WorkflowRegistry()
         specs: Dict[str, WorkflowSpec] = {}
         flows_by_namespaced_id: Dict[str, Dict[str, Any]] = {}
 
-        for bid, b in bundles.items():
-            man = b.manifest
-            if not man.flows:
-                raise WorkflowBundleError(f"Bundle '{bid}' has no flows (manifest.flows is empty)")
-
-            flow_ids = set(man.flows.keys())
-            id_map = {flow_id: _namespace(bid, flow_id) for flow_id in flow_ids}
-
-            for flow_id, rel in man.flows.items():
-                raw = b.read_json(rel)
+        for bid, versions in bundles_by_id.items():
+            for bver, b in versions.items():
+                bundle_ref = _bundle_ref(bid, bver)
+                man = b.manifest
+                if not man.flows:
+                    raise WorkflowBundleError(f"Bundle '{bid}@{bver}' has no flows (manifest.flows is empty)")
+
+                flow_ids = set(man.flows.keys())
+                id_map = {flow_id: _namespace(bundle_ref, flow_id) for flow_id in flow_ids}
+
+                for flow_id, rel in man.flows.items():
+                    raw = b.read_json(rel)
+                    if not isinstance(raw, dict):
+                        raise WorkflowBundleError(f"VisualFlow JSON for '{bid}@{bver}:{flow_id}' must be an object")
+                    namespaced_raw = _namespace_visualflow_raw(
+                        raw=raw,
+                        bundle_id=bundle_ref,
+                        flow_id=flow_id,
+                        id_map=id_map,
+                    )
+                    flows_by_namespaced_id[str(namespaced_raw.get("id") or _namespace(bundle_ref, flow_id))] = namespaced_raw
+                    try:
+                        spec = compile_visualflow(namespaced_raw)
+                    except Exception as e:
+                        raise WorkflowBundleError(f"Failed compiling VisualFlow '{bid}@{bver}:{flow_id}': {e}") from e
+                    wf_reg.register(spec)
+                    specs[str(spec.workflow_id)] = spec
+
+        # Load dynamic flows persisted in data_dir (e.g. scheduled wrapper flows).
+        try:
+            for p in sorted(dynamic_dir.glob("*.json")):
+                if not p.is_file():
+                    continue
+                try:
+                    raw = json.loads(p.read_text(encoding="utf-8"))
+                except Exception as e:
+                    logger.warning("Failed to read dynamic flow %s: %s", p, e)
+                    continue
                 if not isinstance(raw, dict):
-                    raise WorkflowBundleError(f"VisualFlow JSON for '{bid}:{flow_id}' must be an object")
-                namespaced_raw = _namespace_visualflow_raw(
-                    raw=raw,
-                    bundle_id=bid,
-                    flow_id=flow_id,
-                    id_map=id_map,
-                )
-                flows_by_namespaced_id[str(namespaced_raw.get("id") or _namespace(bid, flow_id))] = namespaced_raw
+                    continue
                 try:
-                    spec = compile_visualflow(namespaced_raw)
+                    spec = compile_visualflow(raw)
                 except Exception as e:
-                    raise WorkflowBundleError(f"Failed compiling VisualFlow '{bid}:{flow_id}': {e}") from e
-                wf_reg.register(spec)
-                specs[str(spec.workflow_id)] = spec
+                    logger.warning("Failed compiling dynamic flow %s: %s", p, e)
+                    continue
+                try:
+                    wf_reg.register(spec)
+                    specs[str(spec.workflow_id)] = spec
+                except Exception as e:
+                    logger.warning("Failed registering dynamic flow %s: %s", p, e)
+                    continue
+        except Exception:
+            pass
 
         needs_llm = any(_flow_uses_llm(raw) for raw in flows_by_namespaced_id.values())
         needs_tools = any(_flow_uses_tools(raw) for raw in flows_by_namespaced_id.values())
+        needs_memory_kg = any(_flow_uses_memory_kg(raw) for raw in flows_by_namespaced_id.values())
+
+        extra_effect_handlers: Dict[Any, Any] = {}
+        if needs_memory_kg:
+            try:
+                from abstractmemory import LanceDBTripleStore
+                from abstractruntime.integrations.abstractmemory.effect_handlers import build_memory_kg_effect_handlers
+                from abstractruntime.storage.artifacts import utc_now_iso
+            except Exception as e:  # pragma: no cover
+                raise WorkflowBundleError(
+                    "Bundle uses memory_kg_* nodes but AbstractMemory integration is not available. "
+                    "Install `abstractmemory` (and optionally `abstractmemory[lancedb]`)."
+                ) from e
+
+            embedder = None
+            try:
+                from abstractruntime.integrations.abstractcore.embeddings_client import AbstractCoreEmbeddingsClient
+                from abstractgateway.embeddings_config import resolve_embedding_config
+
+                emb_provider, emb_model = resolve_embedding_config(base_dir=Path(data_root))
+                emb_client = AbstractCoreEmbeddingsClient(
+                    provider=str(emb_provider).strip().lower(),
+                    model=str(emb_model).strip(),
+                    manager_kwargs={
+                        "cache_dir": Path(data_root) / "abstractcore" / "embeddings",
+                        # Embeddings must be trustworthy for semantic retrieval; do not return zero vectors on failure.
+                        "strict": True,
+                    },
+                )
+
+                class _Embedder:
+                    def __init__(self, client: Any) -> None:
+                        self._client = client
+
+                    def embed_texts(self, texts):
+                        return self._client.embed_texts(texts).embeddings
+
+                embedder = _Embedder(emb_client)
+            except Exception:
+                embedder = None
+
+            try:
+                store_path = Path(data_root) / "abstractmemory" / "kg"
+                store_path.parent.mkdir(parents=True, exist_ok=True)
+                store_obj = LanceDBTripleStore(store_path, embedder=embedder)
+            except Exception as e:
+                raise WorkflowBundleError(
+                    "Bundle uses memory_kg_* nodes, which require a LanceDB-backed store. "
+                    "Install `lancedb` and ensure the gateway runs under the same environment."
+                ) from e
+
+            extra_effect_handlers = build_memory_kg_effect_handlers(store=store_obj, run_store=run_store, now_iso=utc_now_iso)
 
         # Optional AbstractCore integration for LLM_CALL + TOOL_CALLS.
         if needs_llm or needs_tools:
@@ -368,6 +664,7 @@ class WorkflowBundleGatewayHost:
                     ledger_store=ledger_store,
                     artifact_store=artifact_store,
                     tool_executor=tool_executor,
+                    extra_effect_handlers=extra_effect_handlers,
                 )
                 runtime.set_workflow_registry(wf_reg)
             else:
@@ -381,7 +678,12 @@ class WorkflowBundleGatewayHost:
                     workflow_registry=wf_reg,
                     artifact_store=artifact_store,
                     effect_handlers={
-                        EffectType.TOOL_CALLS: make_tool_calls_handler(tools=tool_executor),
+                        EffectType.TOOL_CALLS: make_tool_calls_handler(
+                            tools=tool_executor,
+                            artifact_store=artifact_store,
+                            run_store=run_store,
+                        ),
+                        **extra_effect_handlers,
                     },
                 )
         else:
@@ -455,12 +757,20 @@ class WorkflowBundleGatewayHost:
                 from abstractagent.logic.builtins import (  # type: ignore
                     ASK_USER_TOOL,
                     COMPACT_MEMORY_TOOL,
+                    DELEGATE_AGENT_TOOL,
                     INSPECT_VARS_TOOL,
                     RECALL_MEMORY_TOOL,
                     REMEMBER_TOOL,
                 )
 
-                builtin_defs = [ASK_USER_TOOL, RECALL_MEMORY_TOOL, INSPECT_VARS_TOOL, REMEMBER_TOOL, COMPACT_MEMORY_TOOL]
+                builtin_defs = [
+                    ASK_USER_TOOL,
+                    RECALL_MEMORY_TOOL,
+                    INSPECT_VARS_TOOL,
+                    REMEMBER_TOOL,
+                    COMPACT_MEMORY_TOOL,
+                    DELEGATE_AGENT_TOOL,
+                ]
                 seen_names = {t.name for t in all_tool_defs if getattr(t, "name", None)}
                 for t in builtin_defs:
                     if getattr(t, "name", None) and t.name not in seen_names:
@@ -523,7 +833,11 @@ class WorkflowBundleGatewayHost:
 
         return WorkflowBundleGatewayHost(
             bundles_dir=base,
-            bundles=bundles,
+            data_dir=data_root,
+            dynamic_flows_dir=dynamic_dir,
+            deprecation_store=dep_store,
+            bundles=bundles_by_id,
+            latest_bundle_versions=latest_versions,
             runtime=runtime,
             workflow_registry=wf_reg,
             specs=specs,
@@ -543,6 +857,34 @@ class WorkflowBundleGatewayHost:
     def artifact_store(self) -> Any:
         return self.runtime.artifact_store
 
+    def reload_bundles_from_disk(self) -> Dict[str, Any]:
+        """Reload bundles/specs from bundles_dir (best-effort, intended for dev).
+
+        Notes:
+        - This rebuilds the in-memory registry and swaps host internals in-place so the
+          runner can keep using the same host object.
+        - Dynamic flows persisted in `data_dir/dynamic_flows` are reloaded as part of
+          the rebuild.
+        """
+        new_host = WorkflowBundleGatewayHost.load_from_dir(
+            bundles_dir=self.bundles_dir,
+            data_dir=self.data_dir,
+            run_store=self.run_store,
+            ledger_store=self.ledger_store,
+            artifact_store=self.artifact_store,
+        )
+        with self._lock:
+            self.bundles = new_host.bundles
+            self.latest_bundle_versions = new_host.latest_bundle_versions
+            self.runtime = new_host.runtime
+            self.workflow_registry = new_host.workflow_registry
+            self.specs = new_host.specs
+            self.event_listener_specs_by_root = new_host.event_listener_specs_by_root
+            self._default_bundle_id = new_host._default_bundle_id
+            self.deprecation_store = new_host.deprecation_store
+        bundle_ids = sorted([str(k) for k in (self.bundles or {}).keys() if isinstance(k, str)])
+        return {"ok": True, "bundle_ids": bundle_ids, "count": len(bundle_ids)}
+
     def start_run(
         self,
         *,
@@ -550,47 +892,166 @@ class WorkflowBundleGatewayHost:
         input_data: Dict[str, Any],
         actor_id: str = "gateway",
         bundle_id: Optional[str] = None,
+        bundle_version: Optional[str] = None,
+        session_id: Optional[str] = None,
     ) -> str:
-        fid = str(flow_id or "").strip()
-        bid = str(bundle_id or "").strip() if isinstance(bundle_id, str) else ""
-        bundle_id_clean = bid or None
-
-        if not fid:
-            # Default entrypoint selection for the common case:
-            # start {bundle_id, input_data} without needing flow_id.
-            selected_bundle_id = bundle_id_clean or self._default_bundle_id
+        fid_raw = str(flow_id or "").strip()
+
+        bid_raw = str(bundle_id or "").strip() if isinstance(bundle_id, str) else ""
+        bid_base, bid_ver = _split_bundle_ref(bid_raw)
+
+        bver_raw = str(bundle_version or "").strip() if isinstance(bundle_version, str) else ""
+        if bid_ver and bver_raw and bid_ver != bver_raw:
+            raise ValueError("bundle_version conflicts with bundle_id (bundle_id already includes '@version')")
+
+        # Effective requested version (may still be None; default to latest per bundle_id).
+        requested_ver = bver_raw or bid_ver
+
+        def _get_bundle(*, bundle_id2: str, bundle_version2: Optional[str]) -> tuple[str, WorkflowBundle]:
+            bid2 = str(bundle_id2 or "").strip()
+            if not bid2:
+                raise ValueError("bundle_id is required")
+            versions = self.bundles.get(bid2)
+            if not isinstance(versions, dict) or not versions:
+                raise KeyError(f"Bundle '{bid2}' not found")
+            ver2 = str(bundle_version2 or "").strip() if isinstance(bundle_version2, str) and str(bundle_version2).strip() else ""
+            if not ver2:
+                ver2 = str(self.latest_bundle_versions.get(bid2) or "").strip()
+            if not ver2:
+                raise KeyError(f"Bundle '{bid2}' has no versions loaded")
+            bundle2 = versions.get(ver2)
+            if bundle2 is None:
+                raise KeyError(f"Bundle '{bid2}@{ver2}' not found")
+            return (ver2, bundle2)
+
+        # Default entrypoint selection for the common case:
+        # start {bundle_id, input_data} without needing flow_id.
+        if not fid_raw:
+            selected_bundle_id = bid_base or (str(self._default_bundle_id or "").strip() if self._default_bundle_id else "")
             if not selected_bundle_id:
                 raise ValueError(
                     "flow_id is required when multiple bundles are loaded; "
                     "provide bundle_id (or pass flow_id as 'bundle:flow')"
                 )
-            bundle = self.bundles.get(str(selected_bundle_id))
-            if bundle is None:
-                raise KeyError(f"Bundle '{selected_bundle_id}' not found")
-            entrypoints = list(getattr(bundle.manifest, "entrypoints", None) or [])
-            default_ep = str(getattr(bundle.manifest, "default_entrypoint", "") or "").strip()
+            selected_ver, bundle2 = _get_bundle(bundle_id2=selected_bundle_id, bundle_version2=requested_ver)
+            entrypoints = list(getattr(bundle2.manifest, "entrypoints", None) or [])
+            default_ep = str(getattr(bundle2.manifest, "default_entrypoint", "") or "").strip()
             if len(entrypoints) == 1:
                 ep_fid = str(getattr(entrypoints[0], "flow_id", "") or "").strip()
             elif default_ep:
                 ep_fid = default_ep
             else:
                 raise ValueError(
-                    f"Bundle '{selected_bundle_id}' has {len(entrypoints)} entrypoints; "
+                    f"Bundle '{selected_bundle_id}@{selected_ver}' has {len(entrypoints)} entrypoints; "
                     "specify flow_id to select which entrypoint to start "
                     "(or set manifest.default_entrypoint)"
                 )
             if not ep_fid:
-                raise ValueError(f"Bundle '{selected_bundle_id}' entrypoint flow_id is empty")
-            workflow_id = _namespace(str(selected_bundle_id), ep_fid)
+                raise ValueError(f"Bundle '{selected_bundle_id}@{selected_ver}' entrypoint flow_id is empty")
+            workflow_id = _namespace(_bundle_ref(selected_bundle_id, selected_ver), ep_fid)
         else:
-            workflow_id = _coerce_namespaced_id(
-                bundle_id=bundle_id_clean, flow_id=fid, default_bundle_id=self._default_bundle_id
-            )
+            # Allow passing fully qualified flow_id:
+            # - bundle:flow (defaults to latest version)
+            # - bundle@ver:flow (exact)
+            if ":" in fid_raw:
+                prefix, inner = fid_raw.split(":", 1)
+                prefix_base, prefix_ver = _split_bundle_ref(prefix)
+                # Dynamic workflows often use ':' in their ids (e.g. scheduled:uuid).
+                # Only treat this as a bundle namespace when the prefix matches a loaded bundle id.
+                if prefix_base and prefix_base in self.bundles:
+                    if bid_base and prefix_base and bid_base != prefix_base:
+                        raise ValueError("flow_id bundle prefix does not match bundle_id")
+                    if prefix_ver and requested_ver and prefix_ver != requested_ver:
+                        raise ValueError("flow_id version does not match bundle_version")
+                    selected_bundle_id = prefix_base or bid_base
+                    if not selected_bundle_id:
+                        raise ValueError("bundle_id is required")
+                    selected_ver, _bundle2 = _get_bundle(
+                        bundle_id2=selected_bundle_id,
+                        bundle_version2=prefix_ver or requested_ver,
+                    )
+                    workflow_id = _namespace(_bundle_ref(selected_bundle_id, selected_ver), inner.strip())
+                else:
+                    if bid_base or requested_ver:
+                        raise ValueError(
+                            f"flow_id '{fid_raw}' is already namespaced, but bundle_id/bundle_version was also provided"
+                        )
+                    workflow_id = fid_raw
+            else:
+                selected_bundle_id = bid_base or (str(self._default_bundle_id or "").strip() if self._default_bundle_id else "")
+                if not selected_bundle_id:
+                    raise ValueError("bundle_id is required when multiple bundles are loaded (or pass flow_id as 'bundle:flow')")
+                selected_ver, _bundle2 = _get_bundle(bundle_id2=selected_bundle_id, bundle_version2=requested_ver)
+                workflow_id = _namespace(_bundle_ref(selected_bundle_id, selected_ver), fid_raw)
+
+        # Enforce workflow deprecations (bundle-owned entry workflows).
+        # This must live in the host so scheduled child launches are also blocked.
+        if ":" in workflow_id:
+            prefix, inner = workflow_id.split(":", 1)
+            dep_bid, _dep_ver = _split_bundle_ref(prefix)
+            dep_flow = inner.strip()
+            if dep_bid and dep_flow and dep_bid in self.bundles:
+                rec = self.deprecation_store.get_record(bundle_id=dep_bid, flow_id=dep_flow)
+                if rec is not None:
+                    raise WorkflowDeprecatedError(bundle_id=dep_bid, flow_id=dep_flow, record=rec)
 
         spec = self.specs.get(workflow_id)
         if spec is None:
             raise KeyError(f"Workflow '{workflow_id}' not found")
-        run_id = str(self.runtime.start(workflow=spec, vars=dict(input_data or {}), actor_id=actor_id))
+        sid = str(session_id).strip() if isinstance(session_id, str) and session_id.strip() else None
+        run_id = str(self.runtime.start(workflow=spec, vars=dict(input_data or {}), actor_id=actor_id, session_id=sid))
+
+        # Default session_id to the root run_id for durable session-scoped behavior
+        # (matches VisualSessionRunner semantics).
+        effective_session_id = sid
+        if effective_session_id is None:
+            try:
+                state = self.runtime.get_state(run_id)
+                if not getattr(state, "session_id", None):
+                    state.session_id = run_id  # type: ignore[attr-defined]
+                    self.runtime.run_store.save(state)
+                effective_session_id = str(getattr(state, "session_id", None) or run_id).strip() or run_id
+            except Exception:
+                effective_session_id = run_id
+
+        # Persist a workflow snapshot for reproducible replay (best-effort).
+        try:
+            if ":" in workflow_id:
+                prefix, inner = workflow_id.split(":", 1)
+                bid_base, bid_ver2 = _split_bundle_ref(prefix)
+                if bid_base and bid_ver2:
+                    versions = self.bundles.get(bid_base)
+                    bundle2 = versions.get(bid_ver2) if isinstance(versions, dict) else None
+                    if bundle2 is not None:
+                        bundle_ref = _bundle_ref(bid_base, bid_ver2)
+                        man = bundle2.manifest
+                        flow_ids = set(man.flows.keys()) if isinstance(getattr(man, "flows", None), dict) else set()
+                        id_map = {fid: _namespace(bundle_ref, fid) for fid in flow_ids if isinstance(fid, str) and fid.strip()}
+                        rel = man.flow_path_for(inner) if hasattr(man, "flow_path_for") else None
+                        raw = bundle2.read_json(rel) if isinstance(rel, str) and rel.strip() else None
+                        if isinstance(raw, dict):
+                            namespaced_raw = _namespace_visualflow_raw(
+                                raw=raw,
+                                bundle_id=bundle_ref,
+                                flow_id=inner,
+                                id_map=id_map,
+                            )
+                            snapshot = {
+                                "kind": "visualflow_json",
+                                "bundle_ref": bundle_ref,
+                                "flow_id": str(inner),
+                                "visualflow": namespaced_raw,
+                            }
+                            persist_workflow_snapshot(
+                                run_store=self.run_store,
+                                artifact_store=self.artifact_store,
+                                run_id=str(run_id),
+                                workflow_id=str(workflow_id),
+                                snapshot=snapshot,
+                                format="visualflow_json",
+                            )
+        except Exception:
+            pass
 
         # Start session-scoped event listener workflows (best-effort).
         listener_ids = self.event_listener_specs_by_root.get(workflow_id) or []
@@ -602,7 +1063,7 @@ class WorkflowBundleGatewayHost:
                 child_run_id = self.runtime.start(
                     workflow=listener_spec,
                     vars={},
-                    session_id=run_id,
+                    session_id=effective_session_id,
                     parent_run_id=run_id,
                     actor_id=actor_id,
                 )
@@ -621,6 +1082,18 @@ class WorkflowBundleGatewayHost:
         if not isinstance(workflow_id, str) or not workflow_id:
             raise ValueError(f"Run '{run_id}' missing workflow_id")
         spec = self.specs.get(workflow_id)
+        if spec is None and ":" in workflow_id:
+            # Backward compatibility: older runs may store workflow_id as "bundle:flow"
+            # (without bundle_version). Best-effort map to the latest loaded version.
+            prefix, fid = workflow_id.split(":", 1)
+            prefix_base, prefix_ver = _split_bundle_ref(prefix)
+            if prefix_base and not prefix_ver:
+                latest = str(self.latest_bundle_versions.get(prefix_base) or "").strip()
+                if latest:
+                    workflow_id2 = _namespace(_bundle_ref(prefix_base, latest), fid.strip())
+                    spec = self.specs.get(workflow_id2)
+        if spec is None:
+            spec = self._try_register_dynamic_workflow_from_disk(workflow_id)
         if spec is None:
             raise KeyError(f"Workflow '{workflow_id}' not registered")
         return (self.runtime, spec)