abstractcode 0.3.0__py3-none-any.whl → 0.3.2__py3-none-any.whl

abstractcode/workflow_agent.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
 import json
+import re
+import zipfile
 from dataclasses import dataclass
 from datetime import datetime, timezone
 from pathlib import Path
@@ -13,10 +15,19 @@ from abstractruntime import RunState, RunStatus, Runtime, WorkflowSpec
 def _now_iso() -> str:
     return datetime.now(timezone.utc).isoformat()
 
-_STATUS_EVENT_NAME = "abstractcode.status"
-_MESSAGE_EVENT_NAME = "abstractcode.message"
-_TOOL_EXEC_EVENT_NAME = "abstractcode.tool_execution"
-_TOOL_RESULT_EVENT_NAME = "abstractcode.tool_result"
+_UI_EVENT_NAMESPACE = "abstract"
+
+_STATUS_EVENT_NAME = f"{_UI_EVENT_NAMESPACE}.status"
+_MESSAGE_EVENT_NAME = f"{_UI_EVENT_NAMESPACE}.message"
+_TOOL_EXEC_EVENT_NAME = f"{_UI_EVENT_NAMESPACE}.tool_execution"
+_TOOL_RESULT_EVENT_NAME = f"{_UI_EVENT_NAMESPACE}.tool_result"
+
+
+def _normalize_ui_event_name(name: str) -> str:
+    s = str(name or "").strip()
+    if s.startswith("abstractcode."):
+        return f"{_UI_EVENT_NAMESPACE}.{s[len('abstractcode.'):]}".strip(".")
+    return s
 
 
 def _new_message(*, role: str, content: str, metadata: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
@@ -44,9 +55,11 @@ def _copy_messages(messages: Any) -> List[Dict[str, Any]]:
 
 @dataclass(frozen=True)
 class ResolvedVisualFlow:
-    visual_flow: Any
-    flows: Dict[str, Any]
+    visual_flow: Dict[str, Any]
+    flows: Dict[str, Dict[str, Any]]
     flows_dir: Path
+    bundle_id: Optional[str] = None
+    bundle_version: Optional[str] = None
 
 
 def _default_flows_dir() -> Path:
@@ -58,77 +71,243 @@ def _default_flows_dir() -> Path:
         return Path("flows")
 
 
-def _load_visual_flows(flows_dir: Path) -> Dict[str, Any]:
+def _default_bundles_dir() -> Path:
+    """Best-effort location for `.flow` bundles (WorkflowBundle zips)."""
+    try:
+        from abstractruntime.workflow_bundle import default_workflow_bundles_dir  # type: ignore
+
+        return default_workflow_bundles_dir()
+    except Exception:
+        candidate = Path("flows") / "bundles"
+        if candidate.exists() and candidate.is_dir():
+            return candidate
+        return Path("flows")
+
+
+def _is_flow_bundle(path: Path) -> bool:
+    try:
+        if path.suffix.lower() == ".flow":
+            return True
+    except Exception:
+        pass
     try:
-        from abstractflow.visual.models import VisualFlow
+        return zipfile.is_zipfile(path)
+    except Exception:
+        return False
+
+
+def _load_visual_flows_from_bundle(bundle_path: Path) -> Tuple[Dict[str, Dict[str, Any]], Dict[str, Any]]:
+    """Load VisualFlow JSON objects from a `.flow` bundle (zip).
+
+    Returns: (flows_by_id, manifest_dict)
+    """
+    try:
+        from abstractruntime.workflow_bundle import open_workflow_bundle  # type: ignore
     except Exception as e:  # pragma: no cover
         raise RuntimeError(
-            "AbstractFlow is required to run VisualFlow workflows.\n"
-            'Install with: pip install "abstractcode[flow]"'
+            "AbstractRuntime workflow_bundle support is required to run `.flow` bundles.\n"
+            'Install with: pip install "abstractruntime"'
         ) from e
 
-    flows: Dict[str, Any] = {}
+    bundle = open_workflow_bundle(bundle_path)
+    man = bundle.manifest
+
+    entrypoints: List[Dict[str, Any]] = []
+    for ep in getattr(man, "entrypoints", None) or []:
+        fid = str(getattr(ep, "flow_id", "") or "").strip()
+        if not fid:
+            continue
+        entrypoints.append(
+            {
+                "flow_id": fid,
+                "name": str(getattr(ep, "name", "") or ""),
+                "description": str(getattr(ep, "description", "") or ""),
+                "interfaces": list(getattr(ep, "interfaces", []) or []),
+            }
+        )
+
+    manifest: Dict[str, Any] = {
+        "bundle_id": str(getattr(man, "bundle_id", "") or ""),
+        "bundle_version": str(getattr(man, "bundle_version", "") or ""),
+        "default_entrypoint": str(getattr(man, "default_entrypoint", "") or ""),
+        "entrypoints": entrypoints,
+        "flows": dict(getattr(man, "flows", None) or {}),
+    }
+
+    flows: Dict[str, Dict[str, Any]] = {}
+    for fid, rel in (getattr(man, "flows", None) or {}).items():
+        if not isinstance(rel, str) or not rel.strip():
+            continue
+        try:
+            raw = bundle.read_json(rel)
+        except Exception:
+            continue
+        if not isinstance(raw, dict):
+            continue
+        flow_id = str(raw.get("id") or fid or "").strip()
+        if not flow_id:
+            continue
+        flows[flow_id] = raw
+    return flows, manifest
+
+
+def _load_visual_flows(flows_dir: Path) -> Dict[str, Dict[str, Any]]:
+    flows: Dict[str, Dict[str, Any]] = {}
     if not flows_dir.exists():
         return flows
     for path in sorted(flows_dir.glob("*.json")):
         try:
-            raw = path.read_text(encoding="utf-8")
-            vf = VisualFlow.model_validate_json(raw)
+            raw = json.loads(path.read_text(encoding="utf-8"))
         except Exception:
             continue
-        flows[str(vf.id)] = vf
+        if not isinstance(raw, dict):
+            continue
+        fid = str(raw.get("id") or "").strip()
+        if not fid:
+            continue
+        flows[fid] = raw
     return flows
 
 
-def resolve_visual_flow(flow_ref: str, *, flows_dir: Optional[str]) -> ResolvedVisualFlow:
-    """Resolve a VisualFlow by id, name, or path to a .json file."""
-    ref = str(flow_ref or "").strip()
-    if not ref:
-        raise ValueError("flow reference is required (flow id, name, or .json path)")
+def resolve_visual_flow(
+    flow_ref: str,
+    *,
+    flows_dir: Optional[str],
+    require_interface: Optional[str] = None,
+) -> ResolvedVisualFlow:
+    """Resolve a VisualFlow by id, name, or path to a `.json` or bundled `.flow` file.
+
+    Also accepts bundle refs (by bundle_id), e.g.:
+      - basic-agent
+      - basic-llm@0.0.2
+      - basic-llm.flow
+      - basic-llm@0.0.2.flow
+      - basic-llm:c4bd3db6      (bundle_id:flow_id)
+      - basic-llm@0.0.2:c4bd3db6
+    """
+    ref_raw = str(flow_ref or "").strip()
+    if not ref_raw:
+        raise ValueError("flow reference is required (flow id, name, .json/.flow path, or bundle id)")
+
+    def _require_flow_interface(raw: Dict[str, Any]) -> None:
+        if not require_interface:
+            return
+        interfaces = raw.get("interfaces")
+        if isinstance(interfaces, list) and require_interface in interfaces:
+            return
+        raise ValueError(f"Workflow does not implement '{require_interface}'")
+
+    ref = ref_raw
+    bundle_flow_id: Optional[str] = None
+    # Support bundle_id:flow_id (like AbstractCode web). Avoid clobbering Windows drive letters.
+    if ":" in ref and not re.match(r"^[A-Za-z]:[\\\\/]", ref):
+        left, right = ref.split(":", 1)
+        if left.strip() and right.strip():
+            ref = left.strip()
+            bundle_flow_id = right.strip()
 
     path = Path(ref).expanduser()
     flows_dir_path: Path
+    if path.exists() and path.is_file() and _is_flow_bundle(path):
+        flows, manifest = _load_visual_flows_from_bundle(path)
+        bundle_id = str(manifest.get("bundle_id") or "").strip() or None
+        bundle_version = str(manifest.get("bundle_version") or "").strip() or None
+        default_id = str(manifest.get("default_entrypoint") or "").strip()
+        selected_id = bundle_flow_id or default_id
+        if not selected_id and flows:
+            selected_id = next(iter(flows.keys()))
+        vf = flows.get(selected_id) if selected_id else None
+        if vf is None:
+            available = ", ".join(sorted(flows.keys()))
+            raise ValueError(f"Bundle entrypoint '{selected_id}' not found in {path} (available: {available})")
+        # Prefer bundle-level interface markers when present; fall back to flow.interfaces.
+        if require_interface:
+            try:
+                eps = list(manifest.get("entrypoints") or [])
+                ep = next(
+                    (
+                        e
+                        for e in eps
+                        if isinstance(e, dict) and str(e.get("flow_id") or "").strip() == str(selected_id)
+                    ),
+                    None,
+                )
+                if ep is None:
+                    raise ValueError
+                if require_interface not in list(ep.get("interfaces") or []):
+                    raise ValueError
+            except Exception:
+                _require_flow_interface(vf)
+        return ResolvedVisualFlow(
+            visual_flow=vf,
+            flows=flows,
+            flows_dir=path.resolve(),
+            bundle_id=bundle_id,
+            bundle_version=bundle_version,
+        )
+
     if path.exists() and path.is_file():
         try:
-            raw = path.read_text(encoding="utf-8")
+            raw = json.loads(path.read_text(encoding="utf-8"))
         except Exception as e:
             raise ValueError(f"Cannot read flow file: {path}") from e
-
-        try:
-            from abstractflow.visual.models import VisualFlow
-        except Exception as e:  # pragma: no cover
-            raise RuntimeError(
-                "AbstractFlow is required to run VisualFlow workflows.\n"
-                'Install with: pip install "abstractcode[flow]"'
-            ) from e
-
-        vf = VisualFlow.model_validate_json(raw)
+        if not isinstance(raw, dict):
+            raise ValueError(f"Flow JSON must be an object: {path}")
         flows_dir_path = Path(flows_dir).expanduser().resolve() if flows_dir else path.parent.resolve()
         flows = _load_visual_flows(flows_dir_path)
-        flows[str(vf.id)] = vf
-        return ResolvedVisualFlow(visual_flow=vf, flows=flows, flows_dir=flows_dir_path)
+        fid = str(raw.get("id") or "").strip()
+        if fid:
+            flows[fid] = raw
+        _require_flow_interface(raw)
+        return ResolvedVisualFlow(visual_flow=raw, flows=flows, flows_dir=flows_dir_path)
+
+    # Prefer installed bundle refs when a bundle_id (or entrypoint name) matches.
+    try:
+        from abstractruntime.workflow_bundle import WorkflowBundleRegistry, WorkflowBundleRegistryError  # type: ignore
+
+        reg = WorkflowBundleRegistry(_default_bundles_dir())
+        ep = reg.resolve_entrypoint(ref_raw, interface=require_interface)
+        b = reg.resolve_bundle(ep.bundle_ref)
+        flows2, _manifest = _load_visual_flows_from_bundle(b.path)
+        vf = flows2.get(ep.flow_id)
+        if vf is None:
+            available = ", ".join(sorted(flows2.keys()))
+            raise ValueError(f"Bundle entrypoint '{ep.flow_id}' not found in {b.path} (available: {available})")
+        return ResolvedVisualFlow(
+            visual_flow=vf,
+            flows=flows2,
+            flows_dir=b.path.resolve(),
+            bundle_id=str(ep.bundle_id),
+            bundle_version=str(ep.bundle_version),
+        )
+    except WorkflowBundleRegistryError:
+        pass
+    except Exception:
+        pass
 
     flows_dir_path = Path(flows_dir).expanduser().resolve() if flows_dir else _default_flows_dir().resolve()
     flows = _load_visual_flows(flows_dir_path)
 
     if ref in flows:
+        _require_flow_interface(flows[ref])
         return ResolvedVisualFlow(visual_flow=flows[ref], flows=flows, flows_dir=flows_dir_path)
 
     # Fall back to exact name match (case-insensitive).
-    matches = []
+    matches: list[Dict[str, Any]] = []
     needle = ref.casefold()
     for vf in flows.values():
-        name = getattr(vf, "name", None)
+        name = vf.get("name")
         if isinstance(name, str) and name.strip() and name.strip().casefold() == needle:
             matches.append(vf)
 
     if not matches:
-        raise ValueError(f"Flow '{ref}' not found in {flows_dir_path}")
+        raise ValueError(f"Flow '{ref_raw}' not found in {flows_dir_path}")
     if len(matches) > 1:
-        options = ", ".join([f"{getattr(v, 'name', '')} ({getattr(v, 'id', '')})" for v in matches])
+        options = ", ".join([f"{str(v.get('name') or '')} ({str(v.get('id') or '')})" for v in matches])
         raise ValueError(f"Multiple flows match '{ref}': {options}")
 
     vf = matches[0]
+    _require_flow_interface(vf)
     return ResolvedVisualFlow(visual_flow=vf, flows=flows, flows_dir=flows_dir_path)
 
 
@@ -162,12 +341,14 @@ def _workflow_registry() -> Any:
 
 
 def _node_type_str(node: Any) -> str:
+    if isinstance(node, dict):
+        return str(node.get("type") or "")
     t = getattr(node, "type", None)
     return t.value if hasattr(t, "value") else str(t or "")
 
 
 def _subflow_id(node: Any) -> Optional[str]:
-    data = getattr(node, "data", None)
+    data = node.get("data") if isinstance(node, dict) else getattr(node, "data", None)
     if not isinstance(data, dict):
         return None
     sid = data.get("subflowId") or data.get("flowId") or data.get("workflowId") or data.get("workflow_id")
@@ -178,44 +359,103 @@ def _subflow_id(node: Any) -> Optional[str]:
 
 def _compile_visual_flow_tree(
     *,
-    root: Any,
-    flows: Dict[str, Any],
+    root: Dict[str, Any],
+    flows: Dict[str, Dict[str, Any]],
     tools: List[Callable[..., Any]],
     runtime: Runtime,
+    bundle_id: Optional[str] = None,
+    bundle_version: Optional[str] = None,
 ) -> Tuple[WorkflowSpec, Any]:
-    from abstractflow.compiler import compile_flow
-    from abstractflow.visual.agent_ids import visual_react_workflow_id
-    from abstractflow.visual.executor import visual_to_flow
+    from abstractruntime.visualflow_compiler import compile_visualflow
+    from abstractruntime.visualflow_compiler.visual.agent_ids import visual_react_workflow_id
 
     # Collect referenced subflows (cycles are allowed; compile/register each id once).
-    ordered: List[Any] = []
+    ordered_ids: List[str] = []
     seen: set[str] = set()
-    queue: List[str] = [str(getattr(root, "id", "") or "")]
+    queue: List[str] = [str(root.get("id") or "")]
 
     while queue:
         fid = queue.pop(0)
         if not fid or fid in seen:
             continue
-        vf = flows.get(fid)
-        if vf is None:
+        vf_raw = flows.get(fid)
+        if vf_raw is None:
             raise ValueError(f"Subflow '{fid}' not found in loaded flows")
         seen.add(fid)
-        ordered.append(vf)
+        ordered_ids.append(fid)
 
-        for n in getattr(vf, "nodes", []) or []:
+        for n in list(vf_raw.get("nodes") or []):
             if _node_type_str(n) != "subflow":
                 continue
             sid = _subflow_id(n)
             if sid:
                 queue.append(sid)
 
+    bundle_ref = None
+    if isinstance(bundle_id, str) and bundle_id.strip() and isinstance(bundle_version, str) and bundle_version.strip():
+        bundle_ref = f"{bundle_id.strip()}@{bundle_version.strip()}"
+
+    def _namespace(prefix: str, flow_id: str) -> str:
+        return f"{prefix}:{flow_id}"
+
+    def _namespace_visualflow_raw(*, raw: Dict[str, Any], prefix: str, flow_id: str, id_map: Dict[str, str]) -> Dict[str, Any]:
+        def _rewrite(v: Any) -> Any:
+            if isinstance(v, str):
+                s = v.strip()
+                return id_map.get(s) or v
+            if isinstance(v, list):
+                return [_rewrite(x) for x in v]
+            if isinstance(v, dict):
+                return {k: _rewrite(v2) for k, v2 in v.items()}
+            return v
+
+        out_any = _rewrite(raw)
+        out: Dict[str, Any] = dict(out_any) if isinstance(out_any, dict) else dict(raw)
+        out["id"] = id_map.get(flow_id) or _namespace(prefix, flow_id)
+
+        nodes_raw = out.get("nodes")
+        if isinstance(nodes_raw, list):
+            new_nodes: list[Any] = []
+            for n_any in nodes_raw:
+                n = dict(n_any) if isinstance(n_any, dict) else n_any
+                if isinstance(n, dict) and str(n.get("type") or "") == "agent":
+                    node_id = str(n.get("id") or "").strip()
+                    data = n.get("data")
+                    data_d = dict(data) if isinstance(data, dict) else {}
+                    cfg_raw = data_d.get("agentConfig")
+                    cfg = dict(cfg_raw) if isinstance(cfg_raw, dict) else {}
+                    if node_id:
+                        cfg["_react_workflow_id"] = visual_react_workflow_id(flow_id=str(out.get("id") or ""), node_id=node_id)
+                    data_d["agentConfig"] = cfg
+                    n["data"] = data_d
+                new_nodes.append(n)
+            out["nodes"] = new_nodes
+
+        return out
+
     registry = _workflow_registry()
 
     specs_by_id: Dict[str, WorkflowSpec] = {}
-    for vf in ordered:
-        f = visual_to_flow(vf)
-        spec = compile_flow(f)
+    id_map: Dict[str, str] = {}
+    if bundle_ref:
+        id_map = {fid: _namespace(bundle_ref, fid) for fid in ordered_ids}
+
+    compiled_flows: list[Dict[str, Any]] = []
+    for fid in ordered_ids:
+        raw0 = flows.get(fid)
+        if raw0 is None:
+            continue
+        raw = (
+            _namespace_visualflow_raw(raw=raw0, prefix=bundle_ref, flow_id=fid, id_map=id_map)
+            if bundle_ref
+            else dict(raw0)
+        )
+        try:
+            spec = compile_visualflow(raw)
+        except Exception as e:
+            raise RuntimeError(f"Failed compiling VisualFlow '{fid}': {e}") from e
         specs_by_id[str(spec.workflow_id)] = spec
+        compiled_flows.append(raw)
         register = getattr(registry, "register", None)
         if callable(register):
             register(spec)
@@ -224,18 +464,19 @@ def _compile_visual_flow_tree(
 
     # Register per-Agent-node ReAct subworkflows so visual Agent nodes can run.
     agent_nodes: List[Tuple[str, Dict[str, Any]]] = []
-    for vf in ordered:
-        for n in getattr(vf, "nodes", []) or []:
+    for vf in compiled_flows:
+        flow_id = str(vf.get("id") or "").strip()
+        for n in list(vf.get("nodes") or []):
             if _node_type_str(n) != "agent":
                 continue
-            data = getattr(n, "data", None)
+            data = n.get("data") if isinstance(n, dict) else None
             cfg = data.get("agentConfig", {}) if isinstance(data, dict) else {}
             cfg = dict(cfg) if isinstance(cfg, dict) else {}
             wf_id_raw = cfg.get("_react_workflow_id")
             wf_id = (
                 wf_id_raw.strip()
                 if isinstance(wf_id_raw, str) and wf_id_raw.strip()
-                else visual_react_workflow_id(flow_id=vf.id, node_id=n.id)
+                else visual_react_workflow_id(flow_id=flow_id or "unknown", node_id=str((n.get("id") if isinstance(n, dict) else "") or ""))
             )
             agent_nodes.append((wf_id, cfg))
 
@@ -244,7 +485,9 @@ def _compile_visual_flow_tree(
         from abstractagent.logic.builtins import (
             ASK_USER_TOOL,
             COMPACT_MEMORY_TOOL,
+            DELEGATE_AGENT_TOOL,
             INSPECT_VARS_TOOL,
+            OPEN_ATTACHMENT_TOOL,
             RECALL_MEMORY_TOOL,
             REMEMBER_NOTE_TOOL,
             REMEMBER_TOOL,
@@ -262,11 +505,13 @@ def _compile_visual_flow_tree(
 
         tool_defs = [
             ASK_USER_TOOL,
+            OPEN_ATTACHMENT_TOOL,
             RECALL_MEMORY_TOOL,
             INSPECT_VARS_TOOL,
             REMEMBER_TOOL,
             REMEMBER_NOTE_TOOL,
             COMPACT_MEMORY_TOOL,
+            DELEGATE_AGENT_TOOL,
             *_tool_definitions_from_callables(tools),
         ]
 
@@ -292,20 +537,135 @@ def _compile_visual_flow_tree(
     else:  # pragma: no cover
         raise RuntimeError("Runtime does not support workflow registries (required for subflows/agent nodes).")
 
-    root_id = str(getattr(root, "id", "") or "")
-    root_spec = specs_by_id.get(root_id)
+    root_id = str(root.get("id") or "")
+    root_wid = id_map.get(root_id) if bundle_ref else root_id
+    root_spec = specs_by_id.get(root_wid)
     if root_spec is None:
         # Shouldn't happen because root id was seeded into the queue.
-        raise RuntimeError(f"Root workflow '{root_id}' was not compiled/registered.")
+        raise RuntimeError(f"Root workflow '{root_wid or root_id}' was not compiled/registered.")
     return root_spec, registry
 
 
+def _apply_abstractcode_agent_v1_scaffold(flow: Dict[str, Any], *, include_recommended: bool = True) -> None:
+    """Best-effort: ensure required pins exist for `abstractcode.agent.v1` flows.
+
+    This mirrors the VisualFlow interface scaffold in `abstractflow.visual.interfaces`,
+    but operates directly on raw dict JSON so AbstractCode can run bundles without
+    depending on AbstractFlow.
+    """
+    iid = "abstractcode.agent.v1"
+
+    interfaces = flow.get("interfaces")
+    if not isinstance(interfaces, list):
+        interfaces = []
+        flow["interfaces"] = interfaces
+    if iid not in interfaces:
+        interfaces.append(iid)
+
+    nodes = flow.get("nodes")
+    if not isinstance(nodes, list):
+        return
+
+    def _ensure_node_data(node: Dict[str, Any]) -> Dict[str, Any]:
+        data = node.get("data")
+        if not isinstance(data, dict):
+            data = {}
+            node["data"] = data
+        return data
+
+    def _ensure_pin_list(data: Dict[str, Any], key: str) -> list[dict[str, Any]]:
+        pins_any = data.get(key)
+        if not isinstance(pins_any, list):
+            pins: list[dict[str, Any]] = []
+            data[key] = pins
+            return pins
+        if all(isinstance(p, dict) for p in pins_any):
+            return pins_any  # type: ignore[return-value]
+        filtered: list[dict[str, Any]] = [p for p in pins_any if isinstance(p, dict)]
+        data[key] = filtered
+        return filtered
+
+    def _ensure_pin(pins: list[dict[str, Any]], *, pin_id: str, pin_type: str, label: Optional[str] = None) -> None:
+        if any(isinstance(p.get("id"), str) and p.get("id") == pin_id for p in pins):
+            return
+        pins.append({"id": pin_id, "label": label if isinstance(label, str) else pin_id, "type": pin_type})
+
+    start = next((n for n in nodes if isinstance(n, dict) and str(n.get("type") or "") == "on_flow_start"), None)
+    if isinstance(start, dict):
+        data = _ensure_node_data(start)
+        outs = _ensure_pin_list(data, "outputs")
+        _ensure_pin(outs, pin_id="exec-out", pin_type="execution", label="")
+        _ensure_pin(outs, pin_id="provider", pin_type="provider")
+        _ensure_pin(outs, pin_id="model", pin_type="model")
+        _ensure_pin(outs, pin_id="prompt", pin_type="string")
+        if include_recommended:
+            _ensure_pin(outs, pin_id="tools", pin_type="tools")
+
+    for end in [n for n in nodes if isinstance(n, dict) and str(n.get("type") or "") == "on_flow_end"]:
+        data = _ensure_node_data(end)
+        ins = _ensure_pin_list(data, "inputs")
+        _ensure_pin(ins, pin_id="exec-in", pin_type="execution", label="")
+        _ensure_pin(ins, pin_id="response", pin_type="string")
+        _ensure_pin(ins, pin_id="success", pin_type="boolean")
+        _ensure_pin(ins, pin_id="meta", pin_type="object")
+        if include_recommended:
+            _ensure_pin(ins, pin_id="scratchpad", pin_type="object")
+
+
+def _validate_abstractcode_agent_v1(flow: Dict[str, Any]) -> List[str]:
+    """Minimal contract validation for `abstractcode.agent.v1` workflows (stdlib-only)."""
+    errors: list[str] = []
+    nodes = flow.get("nodes")
+    if not isinstance(nodes, list):
+        return ["Flow.nodes must be a list"]
+
+    def _pins(node: Dict[str, Any], key: str) -> Optional[set[str]]:
+        data = node.get("data")
+        if not isinstance(data, dict):
+            return None
+        pins = data.get(key)
+        if not isinstance(pins, list):
+            return None
+        out: set[str] = set()
+        for p in pins:
+            if not isinstance(p, dict):
+                continue
+            if p.get("type") == "execution":
+                continue
+            pid = p.get("id")
+            if isinstance(pid, str) and pid.strip():
+                out.add(pid.strip())
+        return out
+
+    start = next((n for n in nodes if isinstance(n, dict) and str(n.get("type") or "") == "on_flow_start"), None)
+    if not isinstance(start, dict):
+        errors.append("Missing On Flow Start node (type=on_flow_start)")
+    else:
+        outs = _pins(start, "outputs")
+        required_out = {"prompt", "provider", "model", "tools"}
+        if outs is not None and not required_out.issubset(outs):
+            missing = ", ".join(sorted(required_out - outs))
+            errors.append(f"On Flow Start outputs missing: {missing}")
+
+    end = next((n for n in nodes if isinstance(n, dict) and str(n.get("type") or "") == "on_flow_end"), None)
+    if not isinstance(end, dict):
+        errors.append("Missing On Flow End node (type=on_flow_end)")
+    else:
+        ins = _pins(end, "inputs")
+        required_in = {"response", "success", "meta"}
+        if ins is not None and not required_in.issubset(ins):
+            missing = ", ".join(sorted(required_in - ins))
+            errors.append(f"On Flow End inputs missing: {missing}")
+
+    return errors
+
+
 class WorkflowAgent(BaseAgent):
-    """Run a VisualFlow workflow as an AbstractCode agent.
+    """Run a VisualFlow workflow as a RunnableFlow in AbstractCode.
 
     Contract: the workflow must declare `interfaces: ["abstractcode.agent.v1"]` and expose:
-    - On Flow Start output pin: `request` (string)
-    - On Flow End input pin: `response` (string)
+    - On Flow Start output pins (required): `provider` (provider), `model` (model), `prompt` (string)
+    - On Flow End input pins (required): `response` (string), `success` (boolean), `meta` (object)
     """
 
     def __init__(
@@ -329,32 +689,17 @@ class WorkflowAgent(BaseAgent):
         if not self._flow_ref:
             raise ValueError("flow_ref is required")
 
-        resolved = resolve_visual_flow(self._flow_ref, flows_dir=flows_dir)
+        ABSTRACTCODE_AGENT_V1 = "abstractcode.agent.v1"
+        resolved = resolve_visual_flow(self._flow_ref, flows_dir=flows_dir, require_interface=ABSTRACTCODE_AGENT_V1)
         self.visual_flow = resolved.visual_flow
         self.flows = resolved.flows
         self.flows_dir = resolved.flows_dir
+        self._bundle_id = resolved.bundle_id
+        self._bundle_version = resolved.bundle_version
 
-        # Validate interface contract before creating the workflow spec.
-        try:
-            from abstractflow.visual.interfaces import (
-                ABSTRACTCODE_AGENT_V1,
-                apply_visual_flow_interface_scaffold,
-                validate_visual_flow_interface,
-            )
-        except Exception as e:  # pragma: no cover
-            raise RuntimeError(
-                "AbstractFlow is required to validate VisualFlow interfaces.\n"
-                'Install with: pip install "abstractcode[flow]"'
-            ) from e
-
-        # Authoring UX: keep interface-marked flows scaffolded even if the underlying
-        # JSON was created before the contract expanded (or was edited manually).
-        try:
-            apply_visual_flow_interface_scaffold(self.visual_flow, ABSTRACTCODE_AGENT_V1, include_recommended=True)
-        except Exception:
-            pass
+        _apply_abstractcode_agent_v1_scaffold(self.visual_flow, include_recommended=True)
 
-        errors = validate_visual_flow_interface(self.visual_flow, ABSTRACTCODE_AGENT_V1)
+        errors = _validate_abstractcode_agent_v1(self.visual_flow)
         if errors:
             joined = "\n".join([f"- {e}" for e in errors])
             raise ValueError(f"Workflow does not implement '{ABSTRACTCODE_AGENT_V1}':\n{joined}")
@@ -373,10 +718,24 @@ class WorkflowAgent(BaseAgent):
 
     def _create_workflow(self) -> WorkflowSpec:
         tools = list(self.tools or [])
-        spec, _registry = _compile_visual_flow_tree(root=self.visual_flow, flows=self.flows, tools=tools, runtime=self.runtime)
+        spec, _registry = _compile_visual_flow_tree(
+            root=self.visual_flow,
+            flows=self.flows,
+            tools=tools,
+            runtime=self.runtime,
+            bundle_id=self._bundle_id,
+            bundle_version=self._bundle_version,
+        )
         return spec
 
-    def start(self, task: str, *, allowed_tools: Optional[List[str]] = None, **_: Any) -> str:
+    def start(
+        self,
+        task: str,
+        *,
+        allowed_tools: Optional[List[str]] = None,
+        attachments: Optional[List[Any]] = None,
+        **_: Any,
+    ) -> str:
         task = str(task or "").strip()
         if not task:
             raise ValueError("task must be a non-empty string")
@@ -406,11 +765,25 @@ class WorkflowAgent(BaseAgent):
         runtime_model = getattr(getattr(self.runtime, "config", None), "model", None)
 
         vars: Dict[str, Any] = {
-            "request": task,
+            "prompt": task,
             "context": {"task": task, "messages": _copy_messages(self.session_messages)},
             "_temp": {},
             "_limits": limits,
         }
+        if attachments:
+            items = list(attachments) if isinstance(attachments, tuple) else attachments if isinstance(attachments, list) else []
+            normalized: list[Any] = []
+            for a in items:
+                if isinstance(a, dict):
+                    normalized.append(dict(a))
+                elif isinstance(a, str) and a.strip():
+                    normalized.append(a.strip())
+            if normalized:
+                ctx = vars.get("context")
+                if not isinstance(ctx, dict):
+                    ctx = {"task": task, "messages": _copy_messages(self.session_messages)}
+                    vars["context"] = ctx
+                ctx["attachments"] = normalized
 
         if isinstance(runtime_provider, str) and runtime_provider.strip():
             vars["provider"] = runtime_provider.strip()
@@ -439,11 +812,13 @@ class WorkflowAgent(BaseAgent):
         # Build a stable node_id -> label map for UX (used for status updates).
         try:
             labels: Dict[str, str] = {}
-            for n in getattr(self.visual_flow, "nodes", []) or []:
-                nid = getattr(n, "id", None)
+            for n in list(self.visual_flow.get("nodes") or []):
+                if not isinstance(n, dict):
+                    continue
+                nid = n.get("id")
                 if not isinstance(nid, str) or not nid:
                     continue
-                data = getattr(n, "data", None)
+                data = n.get("data")
                 label = data.get("label") if isinstance(data, dict) else None
                 if isinstance(label, str) and label.strip():
                     labels[nid] = label.strip()
@@ -465,8 +840,10 @@ class WorkflowAgent(BaseAgent):
                 self.on_step(
                     "init",
                     {
-                        "flow_id": str(getattr(self.visual_flow, "id", "") or ""),
-                        "flow_name": str(getattr(self.visual_flow, "name", "") or ""),
+                        "flow_id": str(self.visual_flow.get("id") or ""),
+                        "flow_name": str(self.visual_flow.get("name") or ""),
+                        "bundle_id": self._bundle_id,
+                        "bundle_version": self._bundle_version,
                     },
                 )
             except Exception:
@@ -635,6 +1012,7 @@ class WorkflowAgent(BaseAgent):
                 name = str(payload.get("name") or payload.get("event_name") or "").strip()
                 if not name:
                     return
+                name = _normalize_ui_event_name(name)
 
                 event_payload = payload.get("payload")
                 if name == _STATUS_EVENT_NAME:
@@ -784,6 +1162,118 @@ class WorkflowAgent(BaseAgent):
 
             time.sleep(min(0.25, max(0.0, float(remaining))))
 
+    def _auto_drive_subworkflow_wait(self, state: RunState) -> Optional[RunState]:
+        """Best-effort: drive async SUBWORKFLOW waits for non-interactive hosts.
+
+        Visual subflow nodes are compiled into async+wait subworkflow effects so
+        interactive hosts (e.g. web) can stream nested runs. AbstractCode's agent
+        loop expects `step()` to keep progressing without needing an external
+        sub-run driver, so we tick sub-runs and bubble their completions up.
+        """
+        from abstractruntime.core.models import WaitReason
+
+        waiting = getattr(state, "waiting", None)
+        if waiting is None or getattr(waiting, "reason", None) != WaitReason.SUBWORKFLOW:
+            return None
+
+        top_run_id = str(getattr(state, "run_id", "") or "")
+        if not top_run_id:
+            return None
+
+        def _extract_sub_run_id(wait_state: object) -> Optional[str]:
+            details = getattr(wait_state, "details", None)
+            if isinstance(details, dict):
+                sub_run_id = details.get("sub_run_id")
+                if isinstance(sub_run_id, str) and sub_run_id:
+                    return sub_run_id
+            wait_key = getattr(wait_state, "wait_key", None)
+            if isinstance(wait_key, str) and wait_key.startswith("subworkflow:"):
+                return wait_key.split("subworkflow:", 1)[1] or None
+            return None
+
+        def _workflow_for(run_state: object) -> Any:
+            reg = getattr(self.runtime, "workflow_registry", None)
+            getter = getattr(reg, "get", None) if reg is not None else None
+            if callable(getter):
+                wf = getter(getattr(run_state, "workflow_id", ""))
+                if wf is not None:
+                    return wf
+            if getattr(self.workflow, "workflow_id", None) == getattr(run_state, "workflow_id", None):
+                return self.workflow
+            raise RuntimeError(f"Workflow '{getattr(run_state, 'workflow_id', '')}' not found in runtime registry")
+
+        def _bubble_completion(child_state: object) -> Optional[str]:
+            parent_id = getattr(child_state, "parent_run_id", None)
+            if not isinstance(parent_id, str) or not parent_id:
+                return None
+            parent_state = self.runtime.get_state(parent_id)
+            parent_wait = getattr(parent_state, "waiting", None)
+            if parent_state.status != RunStatus.WAITING or parent_wait is None:
+                return None
+            if parent_wait.reason != WaitReason.SUBWORKFLOW:
+                return None
+            self.runtime.resume(
+                workflow=_workflow_for(parent_state),
+                run_id=parent_id,
+                wait_key=None,
+                payload={
+                    "sub_run_id": getattr(child_state, "run_id", None),
+                    "output": getattr(child_state, "output", None),
+                    "node_traces": self.runtime.get_node_traces(getattr(child_state, "run_id", "")),
+                },
+                max_steps=0,
+            )
+            return parent_id
+
+        # Drive subruns until we either make progress or hit a non-subworkflow wait.
+        for _ in range(200):
+            # Descend to the deepest sub-run referenced by SUBWORKFLOW waits.
+            current_run_id = top_run_id
+            for _ in range(25):
+                cur_state = self.runtime.get_state(current_run_id)
+                cur_wait = getattr(cur_state, "waiting", None)
+                if cur_state.status != RunStatus.WAITING or cur_wait is None:
+                    break
+                if cur_wait.reason != WaitReason.SUBWORKFLOW:
+                    break
+                next_id = _extract_sub_run_id(cur_wait)
+                if not next_id:
+                    break
+                current_run_id = next_id
+
+            current_state = self.runtime.get_state(current_run_id)
+
+            # Tick running subruns until they block/complete.
+            if current_state.status == RunStatus.RUNNING:
+                current_state = self.runtime.tick(
+                    workflow=_workflow_for(current_state),
+                    run_id=current_run_id,
+                    max_steps=100,
+                )
+
+            if current_state.status == RunStatus.RUNNING:
+                continue
+
+            if current_state.status in (RunStatus.FAILED, RunStatus.CANCELLED):
+                return current_state
+
+            if current_state.status == RunStatus.WAITING:
+                cur_wait = getattr(current_state, "waiting", None)
+                if cur_wait is None:
+                    break
+                if cur_wait.reason == WaitReason.SUBWORKFLOW:
+                    continue
+                # Blocked on a real wait (USER/EVENT/UNTIL/...): stop auto-driving.
+                return self.runtime.get_state(top_run_id)
+
+            if current_state.status == RunStatus.COMPLETED:
+                parent_id = _bubble_completion(current_state)
+                if parent_id is None:
+                    return self.runtime.get_state(top_run_id)
+                continue
+
+        return self.runtime.get_state(top_run_id)
+
     def step(self) -> RunState:
         if not self._current_run_id:
             raise RuntimeError("No active run. Call start() first.")
@@ -800,33 +1290,61 @@ class WorkflowAgent(BaseAgent):
                 # Time passed (or will pass within our polling loop): continue ticking once.
                 state = self.runtime.tick(workflow=self.workflow, run_id=self._current_run_id, max_steps=1)
 
+        if state.status == RunStatus.WAITING:
+            driven = self._auto_drive_subworkflow_wait(state)
+            if isinstance(driven, RunState):
+                state = driven
+
         if state.status == RunStatus.COMPLETED:
             response_text = ""
             meta_out: Dict[str, Any] = {}
             scratchpad_out: Any = None
-            raw_result_out: Any = None
+            workflow_success: Optional[bool] = None
             out = getattr(state, "output", None)
             if isinstance(out, dict):
-                result_payload = out.get("result") if isinstance(out.get("result"), dict) else None
-                if isinstance(out.get("response"), str):
-                    response_text = str(out.get("response") or "")
-                else:
-                    result = out.get("result")
-                    if isinstance(result, dict) and "response" in result:
-                        response_text = str(result.get("response") or "")
-                    elif isinstance(result, str):
-                        response_text = str(result or "")
-                raw_meta = out.get("meta")
+                def _pick_textish(value: Any) -> str:
+                    if isinstance(value, str):
+                        return value.strip()
+                    if value is None:
+                        return ""
+                    if isinstance(value, bool):
+                        return str(value).lower()
+                    if isinstance(value, (int, float)):
+                        return str(value)
+                    return ""
+
+                payload = out.get("result") if isinstance(out.get("result"), dict) else out
+
+                response_text = _pick_textish(payload.get("response"))
+                if not response_text:
+                    response_text = (
+                        _pick_textish(payload.get("answer"))
+                        or _pick_textish(payload.get("message"))
+                        or _pick_textish(payload.get("text"))
+                        or _pick_textish(payload.get("content"))
+                    )
+                if not response_text and isinstance(out.get("result"), str):
+                    response_text = str(out.get("result") or "").strip()
+
+                if isinstance(payload.get("success"), bool):
+                    workflow_success = bool(payload.get("success"))
+
+                raw_meta = payload.get("meta")
                 if isinstance(raw_meta, dict):
                     meta_out = dict(raw_meta)
-                elif isinstance(result_payload, dict) and isinstance(result_payload.get("meta"), dict):
-                    meta_out = dict(result_payload.get("meta") or {})
-                scratchpad_out = out.get("scratchpad")
-                if scratchpad_out is None and isinstance(result_payload, dict) and "scratchpad" in result_payload:
-                    scratchpad_out = result_payload.get("scratchpad")
-                raw_result_out = out.get("raw_result")
-                if raw_result_out is None and isinstance(result_payload, dict) and "raw_result" in result_payload:
-                    raw_result_out = result_payload.get("raw_result")
+                scratchpad_out = payload.get("scratchpad")
+                if scratchpad_out is None and isinstance(out.get("scratchpad"), (dict, list, str, int, float, bool)):
+                    scratchpad_out = out.get("scratchpad")
+
+                # Backward-compat: older runs used meta.success instead of a first-class pin.
+                if workflow_success is None and isinstance(meta_out.get("success"), bool):
+                    workflow_success = bool(meta_out.get("success"))
+
+                # Fallback: if the workflow doesn't expose success, treat run completion as success.
+                if workflow_success is None and isinstance(out.get("success"), bool):
+                    workflow_success = bool(out.get("success"))
+                if workflow_success is None:
+                    workflow_success = True
 
             task = str(self._last_task or "")
             ctx = state.vars.get("context") if isinstance(getattr(state, "vars", None), dict) else None
@@ -843,8 +1361,8 @@ class WorkflowAgent(BaseAgent):
                 assistant_meta["workflow_meta"] = meta_out
             if scratchpad_out is not None:
                 assistant_meta["workflow_scratchpad"] = scratchpad_out
-            if raw_result_out is not None:
-                assistant_meta["workflow_raw_result"] = raw_result_out
+            if workflow_success is not None:
+                assistant_meta["workflow_success"] = workflow_success
 
             msgs.append(_new_message(role="assistant", content=response_text, metadata=assistant_meta))
             ctx["messages"] = msgs
@@ -866,9 +1384,9 @@ class WorkflowAgent(BaseAgent):
                         "done",
                         {
                             "answer": response_text,
+                            "success": workflow_success,
                             "meta": meta_out or None,
                             "scratchpad": scratchpad_out,
-                            "raw_result": raw_result_out,
                         },
                     )
                 except Exception: