roscoe 2.2.0__tar.gz → 2.4.0__tar.gz

{roscoe-2.2.0/roscoe.egg-info → roscoe-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: roscoe
-Version: 2.2.0
+Version: 2.4.0
 Summary: roscoe — Ready-to-run Orchestration SDK: Configurable, Observable, Extensible.
 Author-email: rhealaloo <rhealaloo@gmail.com>
 License-Expression: MIT
@@ -216,7 +216,9 @@ agent = AgentRunner.from_config("agent.yaml", tools=[my_tool] + gh.tools)
 | **SharePoint** | list files, download, upload, search | MS Graph (OAuth2) |
 | **GitHub** | list repos, issues, PRs, create issue | Personal access token |
 | **Notion** | search, pages, databases, blocks | Integration token |
-| **Google Workspace** | Gmail send/read, Calendar, Tasks, Drive search | Service account or OAuth2 (`roscoe google-auth`) |
+| **Google Workspace** | Gmail send/read, Calendar, Tasks, Drive search + file read | Service account or OAuth2 (`roscoe google-auth`) |
+| **TickTick** | list projects, create/get/complete tasks | OAuth2 access token |
+| **Database** | query, execute, list/describe tables | SQLite built in (`schema:` builds it on first use); any DB-API driver by name |
 | **Snowflake** | execute SQL queries | `pip install roscoe[snowflake]` |
 
 ### Human-in-the-loop
@@ -343,6 +345,69 @@ roscoe init my-gws --template google_workspace_agent
 
 ---
 
+## Workflows — no-code agents
+
+`agent_config.yaml` configures the scaffolding; a **workflow** defines the behaviour,
+so the common cases stop costing a Python file each:
+
+```bash
+roscoe init-nc my-agent      # agent_config.yaml + workflow.yaml, no Python
+roscoe validate              # check it before running it
+roscoe run --set topic="cloud security"
+```
+
+```yaml
+workflow:
+  entry: lookup
+  nodes:
+    - id: lookup
+      type: connector_action        # call a connector method — config, not code
+      connector: hr_api
+      method: get_employee
+      inputs: { employee_id: "{{ input.id }}" }
+      output: employee
+
+    - id: eligible
+      type: condition               # branch on the state
+      when: "employee.department in ['Engineering', 'Product']"
+      then: grant
+      else: explain
+
+    - id: grant
+      type: connector_action
+      requires_approval: true       # pause for a human before it runs
+      connector: vpn
+      method: grant_access
+      inputs: { employee_id: "{{ employee.id }}" }
+      next: END
+
+    - id: explain
+      type: llm_step                # one prompt, no tools
+      prompt: "Explain why {{ employee.name }} was denied."
+```
+
+| Node type | Does |
+|---|---|
+| `connector_action` | Calls one connector method with templated arguments |
+| `condition` | Branches on a sandboxed expression over the shared state |
+| `llm_step` | Sends one prompt to the model |
+| `agent_step` | Hands a task to a named agent running the autonomous ReAct loop |
+
+`agent_step` is the escape hatch — when a stretch of work is too open-ended to wire
+by hand, let an agent pick its own tool calls. Several `agent_step` nodes passing
+results through the state is how multi-agent works, with the graph as the
+orchestrator. Agents inherit the workflow's approval gate, so wrapping work in an
+agent is never a way around one.
+
+Expressions are parsed and walked against an allowlist, never `eval()`'d: dotted
+access is dict lookup rather than `getattr`, and only allowlisted helpers can be
+called. Full reference: [`docs/WORKFLOW_SPEC.md`](docs/WORKFLOW_SPEC.md).
+
+Projects that write their tools in Python are unaffected — `roscoe init` and the
+existing `@tool` flow work exactly as before.
+
+---
+
 ## Architecture
 
 roscoe runs its own async ReAct loop (no LangGraph dependency). The loop is ~100 lines
@@ -371,7 +436,17 @@ roscoe init <name>                              # scaffold with GUI wizard
 roscoe init <name> --quick                      # scaffold with defaults (no wizard)
 roscoe init <name> --cli                        # scaffold with terminal wizard
 roscoe init <name> --template <t>               # scaffold from a template
+roscoe init-nc <name>                           # no-code project — behaviour in workflow.yaml
 
+roscoe validate                                 # check a workflow before running it
+roscoe validate --workflow flow.yaml            # check a specific workflow file
+
+roscoe graph                                    # see the workflow as a diagram
+roscoe graph --terminal                         # print Mermaid source instead
+
+roscoe build                                    # visual editor — drag, connect, save
+
+roscoe run --set topic="cloud security"         # run a workflow with inputs
 roscoe run                                      # browser chat (default)
 roscoe run --terminal                           # interactive chat in the terminal, streamed
 roscoe run -m "message"                         # one-shot message, terminal, exits after
@@ -400,6 +475,13 @@ UI entry point — `app.py`, or whatever `ui_script:` names in `agent_config.yam
 login/dashboard/chat app just works with no flags. `--terminal` and `-m` always
 bypass any custom UI script and talk to the agent directly in-process.
 
+Every scaffolded project ships `custom_ui_example.py` — a minimal Flask app showing
+how to build one: it constructs the same `WorkflowRunner`/`AgentRunner` `roscoe run`
+uses internally and calls `.run()` / `.resume()` on it, so approval pauses, cost
+tracking, and audit logging all come for free. Rename it to `app.py` (or point
+`ui_script:` at it) to switch it on; swap Flask for whatever framework you prefer —
+the runner calls are the part worth keeping.
+
 ---
 
 ## Install

{roscoe-2.2.0 → roscoe-2.4.0}/README.md

@@ -179,7 +179,9 @@ agent = AgentRunner.from_config("agent.yaml", tools=[my_tool] + gh.tools)
 | **SharePoint** | list files, download, upload, search | MS Graph (OAuth2) |
 | **GitHub** | list repos, issues, PRs, create issue | Personal access token |
 | **Notion** | search, pages, databases, blocks | Integration token |
-| **Google Workspace** | Gmail send/read, Calendar, Tasks, Drive search | Service account or OAuth2 (`roscoe google-auth`) |
+| **Google Workspace** | Gmail send/read, Calendar, Tasks, Drive search + file read | Service account or OAuth2 (`roscoe google-auth`) |
+| **TickTick** | list projects, create/get/complete tasks | OAuth2 access token |
+| **Database** | query, execute, list/describe tables | SQLite built in (`schema:` builds it on first use); any DB-API driver by name |
 | **Snowflake** | execute SQL queries | `pip install roscoe[snowflake]` |
 
 ### Human-in-the-loop
@@ -306,6 +308,69 @@ roscoe init my-gws --template google_workspace_agent
 
 ---
 
+## Workflows — no-code agents
+
+`agent_config.yaml` configures the scaffolding; a **workflow** defines the behaviour,
+so the common cases stop costing a Python file each:
+
+```bash
+roscoe init-nc my-agent      # agent_config.yaml + workflow.yaml, no Python
+roscoe validate              # check it before running it
+roscoe run --set topic="cloud security"
+```
+
+```yaml
+workflow:
+  entry: lookup
+  nodes:
+    - id: lookup
+      type: connector_action        # call a connector method — config, not code
+      connector: hr_api
+      method: get_employee
+      inputs: { employee_id: "{{ input.id }}" }
+      output: employee
+
+    - id: eligible
+      type: condition               # branch on the state
+      when: "employee.department in ['Engineering', 'Product']"
+      then: grant
+      else: explain
+
+    - id: grant
+      type: connector_action
+      requires_approval: true       # pause for a human before it runs
+      connector: vpn
+      method: grant_access
+      inputs: { employee_id: "{{ employee.id }}" }
+      next: END
+
+    - id: explain
+      type: llm_step                # one prompt, no tools
+      prompt: "Explain why {{ employee.name }} was denied."
+```
+
+| Node type | Does |
+|---|---|
+| `connector_action` | Calls one connector method with templated arguments |
+| `condition` | Branches on a sandboxed expression over the shared state |
+| `llm_step` | Sends one prompt to the model |
+| `agent_step` | Hands a task to a named agent running the autonomous ReAct loop |
+
+`agent_step` is the escape hatch — when a stretch of work is too open-ended to wire
+by hand, let an agent pick its own tool calls. Several `agent_step` nodes passing
+results through the state is how multi-agent works, with the graph as the
+orchestrator. Agents inherit the workflow's approval gate, so wrapping work in an
+agent is never a way around one.
+
+Expressions are parsed and walked against an allowlist, never `eval()`'d: dotted
+access is dict lookup rather than `getattr`, and only allowlisted helpers can be
+called. Full reference: [`docs/WORKFLOW_SPEC.md`](docs/WORKFLOW_SPEC.md).
+
+Projects that write their tools in Python are unaffected — `roscoe init` and the
+existing `@tool` flow work exactly as before.
+
+---
+
 ## Architecture
 
 roscoe runs its own async ReAct loop (no LangGraph dependency). The loop is ~100 lines
@@ -334,7 +399,17 @@ roscoe init <name>                              # scaffold with GUI wizard
 roscoe init <name> --quick                      # scaffold with defaults (no wizard)
 roscoe init <name> --cli                        # scaffold with terminal wizard
 roscoe init <name> --template <t>               # scaffold from a template
+roscoe init-nc <name>                           # no-code project — behaviour in workflow.yaml
 
+roscoe validate                                 # check a workflow before running it
+roscoe validate --workflow flow.yaml            # check a specific workflow file
+
+roscoe graph                                    # see the workflow as a diagram
+roscoe graph --terminal                         # print Mermaid source instead
+
+roscoe build                                    # visual editor — drag, connect, save
+
+roscoe run --set topic="cloud security"         # run a workflow with inputs
 roscoe run                                      # browser chat (default)
 roscoe run --terminal                           # interactive chat in the terminal, streamed
 roscoe run -m "message"                         # one-shot message, terminal, exits after
@@ -363,6 +438,13 @@ UI entry point — `app.py`, or whatever `ui_script:` names in `agent_config.yam
 login/dashboard/chat app just works with no flags. `--terminal` and `-m` always
 bypass any custom UI script and talk to the agent directly in-process.
 
+Every scaffolded project ships `custom_ui_example.py` — a minimal Flask app showing
+how to build one: it constructs the same `WorkflowRunner`/`AgentRunner` `roscoe run`
+uses internally and calls `.run()` / `.resume()` on it, so approval pauses, cost
+tracking, and audit logging all come for free. Rename it to `app.py` (or point
+`ui_script:` at it) to switch it on; swap Flask for whatever framework you prefer —
+the runner calls are the part worth keeping.
+
 ---
 
 ## Install

{roscoe-2.2.0 → roscoe-2.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "roscoe"
-version = "2.2.0"
+version = "2.4.0"
 description = "roscoe — Ready-to-run Orchestration SDK: Configurable, Observable, Extensible."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -61,6 +61,7 @@ roscoe = [
     "templates/**/*.txt",
     "cli/scaffold/**/*",
     "cli/scaffold/.env.example",
+    "cli/scaffold_nc/**/*",
 ]
 
 [tool.pytest.ini_options]

roscoe-2.4.0/roscoe/__init__.py

@@ -0,0 +1,18 @@
+"""roscoe — provider-agnostic LangChain agent framework with middleware and evals."""
+
+import os
+
+# langchain_core imports transformers (for token counting) as soon as a chat
+# model class is touched, and transformers imports torch unconditionally on
+# import. roscoe never uses torch itself, but a broken local torch install
+# (e.g. a missing DLL dependency) would otherwise crash every roscoe import.
+# USE_TORCH=0 is transformers' own documented flag for skipping that import;
+# setdefault so a project that genuinely wants torch can still opt back in.
+os.environ.setdefault("USE_TORCH", "0")
+
+from roscoe.core.agent_result import AgentResult
+from roscoe.core.agent_runner import AgentRunner
+
+__version__ = "2.4.0"
+
+__all__ = ["AgentRunner", "AgentResult", "__version__"]

roscoe-2.4.0/roscoe/cli/build_command.py

@@ -0,0 +1,406 @@
+"""``roscoe build`` — a visual editor for workflows.
+
+Two tabs. **Flow** is the canvas: drag nodes on, connect them, fill in a form per
+node, and save — the project's ``workflow.yaml`` is written from the graph.
+**Setup** edits the rest of the project: the model, connectors, agents and the
+``ui:`` block, writing ``agent_config.yaml``. Together they cover everything a
+declarative project needs, so a whole agent can be built without opening a YAML
+file. Editing by hand still works — the editor loads whatever is on disk, so
+neither way of working locks you out of the other.
+
+Setup reads the config *raw*, never through :func:`load_config`: that resolves
+``${VAR}`` against the environment, and writing the result back would bake real
+credentials into a file the user is about to commit.
+
+Node positions live in a sibling ``.workflow-layout.json`` rather than in the
+workflow itself, so the config stays about behaviour and a hand-edited file never
+fills up with pixel coordinates.
+
+**Saving rewrites the file, so YAML comments in the ``workflow:`` block are lost.**
+That is inherent to round-tripping through a graph; the command says so before it
+overwrites anything.
+"""
+
+from __future__ import annotations
+
+import json
+import webbrowser
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from pathlib import Path
+from typing import Any
+
+import click
+import yaml
+
+from roscoe.config.loader import ConfigError, load_config
+from roscoe.workflow.loader import DEFAULT_WORKFLOW_FILE, find_workflow_file
+from roscoe.workflow.registry import available_types, build_connectors
+from roscoe.workflow.schema import Workflow, WorkflowError
+from roscoe.workflow.validate import validate_workflow
+
+#: Where node positions are kept — beside the workflow, out of the config.
+LAYOUT_FILE = ".workflow-layout.json"
+
+#: Config keys the Setup tab owns. Everything else in the file — `agent_name`,
+#: `middleware`, `memory` — is read and written back untouched.
+_EDITABLE_CONFIG_KEYS = ("model", "connectors", "ui")
+
+_CONFIG_HEADER = (
+    "# roscoe agent configuration. Edited by `roscoe build`, or by hand — the\n"
+    "# editor reloads whatever is here.\n"
+    "# ${VAR_NAME} resolves from your shell env or .env.\n\n"
+)
+
+_WORKFLOW_HEADER = (
+    "# Generated by `roscoe build`. Editing by hand is fine — the editor\n"
+    "# reloads whatever is here.\n\n"
+)
+
+
+@click.command("build")
+@click.option("--config", default="agent_config.yaml", show_default=True,
+              help="Path to the agent config YAML.")
+@click.option("--workflow", "workflow_path", default=None,
+              help="Workflow file to edit. Defaults to workflow.yaml beside the config.")
+@click.option("--host", default="127.0.0.1", show_default=True, help="Editor host.")
+@click.option("--port", default=8099, show_default=True, help="Editor port.")
+@click.option("--no-browser", is_flag=True, help="Serve without opening a browser.")
+def build_command(
+    config: str, workflow_path: str | None, host: str, port: int, no_browser: bool
+) -> None:
+    """Open the visual workflow editor."""
+    config_file = Path(config)
+    target = Path(workflow_path) if workflow_path else (
+        find_workflow_file(config_file) or config_file.parent / DEFAULT_WORKFLOW_FILE
+    )
+
+    state = _EditorState(config_file, target)
+    httpd = HTTPServer((host, port), _handler_for(state))
+    url = f"http://{host}:{port}"
+
+    click.secho(f"roscoe build — editing {target}", fg="blue", bold=True)
+    if target.is_file():
+        click.secho("  Saving rewrites this file; comments in it will be lost.", fg="yellow")
+    else:
+        click.secho("  New workflow — it will be created when you save.", dim=True)
+    click.secho(f"  {url}   (Ctrl-C to stop)", dim=True)
+
+    if not no_browser:
+        try:
+            webbrowser.open(url)
+        except Exception:  # noqa: BLE001
+            pass
+    try:
+        httpd.serve_forever()
+    except KeyboardInterrupt:
+        click.echo("\nstopped.")
+    finally:
+        httpd.server_close()
+
+
+class _EditorState:
+    """Reads and writes the workflow file the editor is pointed at."""
+
+    def __init__(self, config_file: Path, workflow_file: Path) -> None:
+        self.config_file = config_file
+        self.workflow_file = workflow_file
+        self.layout_file = workflow_file.parent / LAYOUT_FILE
+
+    # --- loading ---
+
+    def load(self) -> dict[str, Any]:
+        """Current workflow + saved positions + what connectors offer."""
+        block = self._read_block()
+        try:
+            workflow = Workflow.from_dict(block, self._agents()) if block else None
+            error = None
+        except WorkflowError as exc:
+            workflow, error = None, str(exc)
+
+        raw_config = self._raw_config()
+        return {
+            "file": str(self.workflow_file),
+            "config_file": str(self.config_file),
+            "workflow": workflow.to_dict() if workflow else _starter(),
+            "layout": self._read_layout(),
+            "methods": self._methods(),
+            "agents": sorted(self._agents()),
+            "error": error,
+            # Setup tab. Read raw, never through load_config — that resolves
+            # ${VAR} against the environment, and a save would then bake real
+            # secrets into a file the user commits.
+            "config": {key: raw_config.get(key) for key in _EDITABLE_CONFIG_KEYS},
+            "agents_detail": self._agents(),
+            "connector_types": available_types(),
+        }
+
+    def _raw_config(self) -> dict[str, Any]:
+        """The config file exactly as written — placeholders left as placeholders."""
+        if not self.config_file.is_file():
+            return {}
+        try:
+            raw = yaml.safe_load(self.config_file.read_text(encoding="utf-8")) or {}
+        except yaml.YAMLError:
+            return {}
+        return raw if isinstance(raw, dict) else {}
+
+    def _read_block(self) -> dict[str, Any]:
+        """The workflow mapping, from its own file or the config's `workflow:` key."""
+        if self.workflow_file.is_file():
+            raw = yaml.safe_load(self.workflow_file.read_text(encoding="utf-8")) or {}
+            return raw.get("workflow", raw)
+        if self.config_file.is_file():
+            try:
+                return (load_config(self.config_file) or {}).get("workflow") or {}
+            except ConfigError:
+                return {}
+        return {}
+
+    def _agents(self) -> dict[str, Any]:
+        for source in (self.workflow_file, self.config_file):
+            if not source.is_file():
+                continue
+            try:
+                raw = yaml.safe_load(source.read_text(encoding="utf-8")) or {}
+            except yaml.YAMLError:
+                continue
+            if raw.get("agents"):
+                return raw["agents"]
+        return {}
+
+    def _methods(self) -> dict[str, list[str]]:
+        """Method names per connector, so the editor offers real choices."""
+        connectors = self._connectors()
+        if not connectors:
+            return {}
+        try:
+            return {
+                name: sorted(tool.name for tool in connector.tools)
+                for name, connector in connectors.items()
+            }
+        finally:
+            _close(connectors)
+
+    def _existing_document(self) -> dict[str, Any]:
+        """The workflow file's other top-level keys, so a save preserves them."""
+        if not self.workflow_file.is_file():
+            return {}
+        try:
+            raw = yaml.safe_load(self.workflow_file.read_text(encoding="utf-8")) or {}
+        except yaml.YAMLError:
+            return {}
+        if not isinstance(raw, dict) or "workflow" not in raw:
+            return {}  # bare file: nodes were at the top level, nothing to keep
+        return {key: value for key, value in raw.items() if key != "workflow"}
+
+    def _read_layout(self) -> dict[str, Any]:
+        if not self.layout_file.is_file():
+            return {}
+        try:
+            return json.loads(self.layout_file.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            return {}
+
+    # --- saving ---
+
+    def check(self, block: dict[str, Any]) -> dict[str, Any]:
+        """Parse and validate a graph without writing it."""
+        try:
+            workflow = Workflow.from_dict(block, self._agents())
+        except WorkflowError as exc:
+            return {"ok": False, "issues": [{"level": "error", "message": str(exc)}]}
+
+        connectors = self._connectors()
+        try:
+            issues = validate_workflow(workflow, connectors=connectors)
+        finally:
+            _close(connectors)
+        return {
+            "ok": not any(i.level == "error" for i in issues),
+            "issues": [{"level": i.level, "message": i.message, "node": i.node} for i in issues],
+        }
+
+    def _connectors(self) -> dict[str, Any] | None:
+        try:
+            config = load_config(self.config_file) if self.config_file.is_file() else {}
+            block = config.get("connectors") or {}
+            return build_connectors(block) if block else None
+        except Exception:  # noqa: BLE001
+            return None
+
+    def save(self, block: dict[str, Any], layout: dict[str, Any]) -> dict[str, Any]:
+        """Write the workflow, refusing anything that would not parse."""
+        result = self.check(block)
+        if not result["ok"]:
+            return {"saved": False, **result}
+
+        # Round-trip through the parser so what lands on disk is normalised, not
+        # whatever shape the browser happened to send.
+        workflow = Workflow.from_dict(block, self._agents())
+
+        # Keep every other top-level key the file already had — `agents:` above all.
+        # Writing only the workflow would quietly delete the rest of the user's file.
+        document = self._existing_document()
+        document["workflow"] = workflow.to_dict()
+        _write_yaml(self.workflow_file, document, _WORKFLOW_HEADER)
+        self.layout_file.write_text(json.dumps(layout, indent=2), encoding="utf-8")
+        return {"saved": True, "file": str(self.workflow_file), **result}
+
+    def save_config(self, payload: dict[str, Any]) -> dict[str, Any]:
+        """Write model/connectors/ui to the config, and agents beside the workflow.
+
+        Setup is saved separately from the graph on purpose: a half-configured
+        connector should not block saving the nodes, and a broken node should not
+        cost you the credentials you just typed in.
+        """
+        raw = self._raw_config()
+        for key in _EDITABLE_CONFIG_KEYS:
+            value = payload.get(key)
+            if value in (None, {}, []):
+                raw.pop(key, None)
+            else:
+                raw[key] = value
+        _write_yaml(self.config_file, raw, _CONFIG_HEADER)
+
+        self._write_agents(payload.get("agents") or {})
+
+        # Rebuild connectors so the method dropdowns reflect what was just saved —
+        # the whole point of typing credentials here is that the next dropdown works.
+        methods = self._methods()
+        return {
+            "saved": True,
+            "config_file": str(self.config_file),
+            "methods": methods,
+            "agents": sorted(self._agents()),
+            "issues": self._setup_issues(payload, methods),
+        }
+
+    def _write_agents(self, agents: dict[str, Any]) -> None:
+        """Agents live beside the workflow, above it, as the scaffold writes them."""
+        existing = self._existing_document()
+        existing.pop("agents", None)
+        document: dict[str, Any] = {}
+        if agents:
+            document["agents"] = agents
+        document.update(existing)
+        if self.workflow_file.is_file():
+            block = self._read_block()
+            if block:
+                document["workflow"] = block
+        _write_yaml(self.workflow_file, document, _WORKFLOW_HEADER)
+
+    def _setup_issues(
+        self, payload: dict[str, Any], methods: dict[str, list[str]]
+    ) -> list[dict[str, Any]]:
+        """Warn about setup that saved fine but will not work at run time."""
+        issues: list[dict[str, Any]] = []
+        for name in (payload.get("connectors") or {}):
+            if name not in methods:
+                issues.append({
+                    "level": "warning",
+                    "message": (
+                        f"Connector '{name}' saved, but could not be opened — check its "
+                        "credentials and that the ${VAR} names exist in .env. Its methods "
+                        "will not appear in the dropdowns until it builds."
+                    ),
+                })
+        for name, spec in (payload.get("agents") or {}).items():
+            for ref in (spec or {}).get("tools") or []:
+                connector, _, method = str(ref).partition(".")
+                if method and connector in methods and method not in methods[connector]:
+                    issues.append({
+                        "level": "error",
+                        "message": f"Agent '{name}': '{connector}' has no method '{method}'.",
+                    })
+        if not issues:
+            issues.append({"level": "ok", "message": "Setup saved."})
+        return issues
+
+
+def _write_yaml(path: Path, document: dict[str, Any], header: str) -> None:
+    """Write a YAML document with a header, preserving key order as given."""
+    body = yaml.safe_dump(document, sort_keys=False, allow_unicode=True, width=88)
+    path.write_text(header + body, encoding="utf-8")
+
+
+def _close(connectors: dict[str, Any] | None) -> None:
+    """Release connections opened just to inspect a connector.
+
+    The editor is long-lived, so leaving these open holds a sqlite file locked for
+    as long as it runs — on Windows that blocks the agent from touching its own
+    database.
+    """
+    for connector in (connectors or {}).values():
+        try:
+            connector.close()
+        except Exception:  # noqa: BLE001 — best effort, never break the editor
+            pass
+
+
+def _starter() -> dict[str, Any]:
+    """A one-node workflow, so a new project opens with something on the canvas."""
+    return {
+        "entry": "start",
+        "nodes": [{"id": "start", "type": "llm_step", "prompt": "Say hello.", "output": "reply"}],
+    }
+
+
+def _handler_for(state: _EditorState) -> type[BaseHTTPRequestHandler]:
+    from roscoe.cli.build_ui import PAGE
+
+    class _Handler(BaseHTTPRequestHandler):
+        def log_message(self, *args: object) -> None:
+            pass
+
+        def handle_one_request(self) -> None:
+            """Swallow the client hanging up.
+
+            A reload or a cancelled favicon request aborts the socket mid-response,
+            and the stdlib prints a full traceback for it. Nothing has gone wrong
+            and there is nothing to do, but the noise reads like a crash.
+            """
+            try:
+                super().handle_one_request()
+            except (ConnectionAbortedError, ConnectionResetError, BrokenPipeError):
+                self.close_connection = True
+
+        def _send(self, body: bytes, content_type: str, code: int = 200) -> None:
+            self.send_response(code)
+            self.send_header("Content-Type", content_type)
+            self.send_header("Content-Length", str(len(body)))
+            self.end_headers()
+            self.wfile.write(body)
+
+        def _json(self, payload: dict[str, Any], code: int = 200) -> None:
+            self._send(json.dumps(payload, default=str).encode(), "application/json", code)
+
+        def _read(self) -> dict[str, Any]:
+            length = int(self.headers.get("Content-Length", 0))
+            if not length:
+                return {}
+            try:
+                return json.loads(self.rfile.read(length) or b"{}")
+            except json.JSONDecodeError:
+                return {}
+
+        def do_GET(self) -> None:  # noqa: N802
+            if self.path.startswith("/api/workflow"):
+                self._json(state.load())
+                return
+            self._send(PAGE.encode(), "text/html; charset=utf-8")
+
+        def do_POST(self) -> None:  # noqa: N802
+            payload = self._read()
+            if self.path.startswith("/api/validate"):
+                self._json(state.check(payload.get("workflow") or {}))
+            elif self.path.startswith("/api/save-config"):
+                self._json(state.save_config(payload))
+            elif self.path.startswith("/api/save"):
+                self._json(
+                    state.save(payload.get("workflow") or {}, payload.get("layout") or {})
+                )
+            else:
+                self.send_response(404)
+                self.end_headers()
+
+    return _Handler