optio-demo 0.1.0__tar.gz

optio_demo-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: optio-demo
+Version: 0.1.0
+Summary: Demo application exercising all optio-core features
+Author-email: Kristof Csillag <kristof.csillag@deai-labs.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/deai-network/optio
+Project-URL: Repository, https://github.com/deai-network/optio
+Project-URL: Issues, https://github.com/deai-network/optio/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: optio-core[redis]<0.3,>=0.2
+Requires-Dist: marimo>=0.9
+Requires-Dist: optio-opencode<0.2,>=0.1
+Requires-Dist: optio-claudecode<0.2,>=0.1
+Requires-Dist: watchfiles>=1.0
+
+# optio-demo
+
+A demo application that exercises all [optio-core](../optio-core) features through a collection of whimsical long-running task trees. Run it, open the dashboard, and watch processes unfold in real time — or cancel, relaunch, and dismiss them from the UI.
+
+## Prerequisites
+
+- **Docker** — for MongoDB and Redis (started automatically by `make install`)
+- **Python 3.11+** — for the demo worker
+- **Node.js** — for the dashboard (`npx optio-dashboard`)
+
+## Quick start
+
+```bash
+# 1. Start infrastructure and install Python dependencies
+make install
+
+# 2. Start the demo worker
+make run
+
+# 3. In a second terminal, launch the dashboard
+make run-dashboard
+```
+
+Then open [http://localhost:3000](http://localhost:3000).
+
+From the dashboard you can **launch**, **cancel**, and **dismiss** any process. Click a process name to drill into its task tree with live progress and a log panel.
+
+## Task themes
+
+### Terraforming Mars (~30 min)
+
+The flagship showcase. A four-level nested task tree covering all progress helpers (`sequential_progress`, `average_progress`, `mapped_progress`), parallel groups with concurrency limits, `survive_failure` subtasks, and a full cooperative cancellation cascade. Metadata is set at the root and inherited by children.
+
+### Organizing Your Home (~10 min)
+
+A household chore tree mixing sequential and parallel subtasks. Demonstrates `survive_failure` (some chores are optional), non-cancellable tasks (you can't un-wash the dishes mid-stream), and indeterminate progress bars for tasks that can't report a percentage.
+
+### The Great Museum Heist (~8 min)
+
+A parallel heist plan where things go wrong. Exercises parallel failure propagation, cascading errors across sibling tasks, and the `warning` field — the dashboard shows a confirmation popover before you relaunch a task that carries a warning.
+
+### Intergalactic Music Festival
+
+Eight generated concert tasks, one per venue (Europa, Titan, Ganymede, …). Each is created from the same template but with different `params` and `metadata` (genre, audience size, song count, encore flag). Demonstrates generating task lists programmatically and conditional child execution driven by params.
+
+### Your 15-min Wake-up Call
+
+A cron-scheduled task that fires every 15 minutes. Demonstrates `cron` scheduling and automatic re-launch — after each run completes it returns to `scheduled` state and fires again at the next interval.
+
+## Feature coverage
+
+| Feature | Terraforming Mars | Organizing Home | Museum Heist | Music Festival | Wake-up Call |
+|---------|:-----------------:|:---------------:|:------------:|:--------------:|:------------:|
+| Sequential progress | x | | | x | |
+| Average progress | x | | | | |
+| Mapped progress | x | | | | |
+| Parallel groups | x | x | x | | |
+| max_concurrency | x | | | | |
+| survive_failure | x | x | | | |
+| Non-cancellable tasks | | x | | | |
+| Indeterminate progress | | x | | | |
+| Parallel failure / cascading errors | | | x | | |
+| warning field | | | x | | |
+| params / metadata | | | | x | |
+| Metadata inheritance | x | | | x | |
+| Cron scheduling | | | | | x |
+| Cooperative cancellation | x | | | | |
+| Deep nesting (4 levels) | x | | | | |
+| Generated tasks (loop) | | | | x | |
+
+## Widget smoke test (Task 21)
+
+Exercises all four widget primitives end-to-end via a live marimo notebook.
+
+1. `docker compose up` in this directory to start MongoDB + Redis.
+2. `pnpm --filter optio-dashboard dev` in another terminal to serve the dashboard.
+3. `python -m optio_demo` in a third terminal to run the demo worker (make sure `pip install -e .` or equivalent has been run so the `optio-demo` package is available).
+4. Open the dashboard in a browser. Authenticate if prompted.
+5. Find the "Marimo Notebook" task in the process list. Click launch.
+6. Click the running process — the iframe widget should mount and show a live marimo notebook.
+7. Interact with the notebook. Reactive updates flow through the widget proxy.
+8. Cancel the process. The "session ended" banner overlays the iframe; the marimo subprocess is terminated.
+9. Dismiss. The iframe unmounts; `widgetUpstream` and `widgetData` are cleared on the process document.

optio_demo-0.1.0/README.md

@@ -0,0 +1,83 @@
+# optio-demo
+
+A demo application that exercises all [optio-core](../optio-core) features through a collection of whimsical long-running task trees. Run it, open the dashboard, and watch processes unfold in real time — or cancel, relaunch, and dismiss them from the UI.
+
+## Prerequisites
+
+- **Docker** — for MongoDB and Redis (started automatically by `make install`)
+- **Python 3.11+** — for the demo worker
+- **Node.js** — for the dashboard (`npx optio-dashboard`)
+
+## Quick start
+
+```bash
+# 1. Start infrastructure and install Python dependencies
+make install
+
+# 2. Start the demo worker
+make run
+
+# 3. In a second terminal, launch the dashboard
+make run-dashboard
+```
+
+Then open [http://localhost:3000](http://localhost:3000).
+
+From the dashboard you can **launch**, **cancel**, and **dismiss** any process. Click a process name to drill into its task tree with live progress and a log panel.
+
+## Task themes
+
+### Terraforming Mars (~30 min)
+
+The flagship showcase. A four-level nested task tree covering all progress helpers (`sequential_progress`, `average_progress`, `mapped_progress`), parallel groups with concurrency limits, `survive_failure` subtasks, and a full cooperative cancellation cascade. Metadata is set at the root and inherited by children.
+
+### Organizing Your Home (~10 min)
+
+A household chore tree mixing sequential and parallel subtasks. Demonstrates `survive_failure` (some chores are optional), non-cancellable tasks (you can't un-wash the dishes mid-stream), and indeterminate progress bars for tasks that can't report a percentage.
+
+### The Great Museum Heist (~8 min)
+
+A parallel heist plan where things go wrong. Exercises parallel failure propagation, cascading errors across sibling tasks, and the `warning` field — the dashboard shows a confirmation popover before you relaunch a task that carries a warning.
+
+### Intergalactic Music Festival
+
+Eight generated concert tasks, one per venue (Europa, Titan, Ganymede, …). Each is created from the same template but with different `params` and `metadata` (genre, audience size, song count, encore flag). Demonstrates generating task lists programmatically and conditional child execution driven by params.
+
+### Your 15-min Wake-up Call
+
+A cron-scheduled task that fires every 15 minutes. Demonstrates `cron` scheduling and automatic re-launch — after each run completes it returns to `scheduled` state and fires again at the next interval.
+
+## Feature coverage
+
+| Feature | Terraforming Mars | Organizing Home | Museum Heist | Music Festival | Wake-up Call |
+|---------|:-----------------:|:---------------:|:------------:|:--------------:|:------------:|
+| Sequential progress | x | | | x | |
+| Average progress | x | | | | |
+| Mapped progress | x | | | | |
+| Parallel groups | x | x | x | | |
+| max_concurrency | x | | | | |
+| survive_failure | x | x | | | |
+| Non-cancellable tasks | | x | | | |
+| Indeterminate progress | | x | | | |
+| Parallel failure / cascading errors | | | x | | |
+| warning field | | | x | | |
+| params / metadata | | | | x | |
+| Metadata inheritance | x | | | x | |
+| Cron scheduling | | | | | x |
+| Cooperative cancellation | x | | | | |
+| Deep nesting (4 levels) | x | | | | |
+| Generated tasks (loop) | | | | x | |
+
+## Widget smoke test (Task 21)
+
+Exercises all four widget primitives end-to-end via a live marimo notebook.
+
+1. `docker compose up` in this directory to start MongoDB + Redis.
+2. `pnpm --filter optio-dashboard dev` in another terminal to serve the dashboard.
+3. `python -m optio_demo` in a third terminal to run the demo worker (make sure `pip install -e .` or equivalent has been run so the `optio-demo` package is available).
+4. Open the dashboard in a browser. Authenticate if prompted.
+5. Find the "Marimo Notebook" task in the process list. Click launch.
+6. Click the running process — the iframe widget should mount and show a live marimo notebook.
+7. Interact with the notebook. Reactive updates flow through the widget proxy.
+8. Cancel the process. The "session ended" banner overlays the iframe; the marimo subprocess is terminated.
+9. Dismiss. The iframe unmounts; `widgetUpstream` and `widgetData` are cleared on the process document.

optio_demo-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "optio-demo"
+version = "0.1.0"
+description = "Demo application exercising all optio-core features"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.11"
+authors = [
+    { name = "Kristof Csillag", email = "kristof.csillag@deai-labs.com" },
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Topic :: Software Development",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+]
+dependencies = [
+    "optio-core[redis]>=0.2,<0.3",
+    "marimo>=0.9",
+    "optio-opencode>=0.1,<0.2",
+    "optio-claudecode>=0.1,<0.2",
+    "watchfiles>=1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/deai-network/optio"
+Repository = "https://github.com/deai-network/optio"
+Issues = "https://github.com/deai-network/optio/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]

optio_demo-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

optio_demo-0.1.0/src/optio_demo/__main__.py

@@ -0,0 +1,37 @@
+"""Optio demo application — exercises all optio-core features."""
+
+import asyncio
+import os
+import logging
+
+from motor.motor_asyncio import AsyncIOMotorClient
+from optio_core.lifecycle import Optio
+
+from optio_demo.tasks import get_task_definitions
+
+logging.basicConfig(level=logging.INFO)
+
+
+async def main():
+    mongo_url = os.environ.get("MONGODB_URL", "mongodb://localhost:27017/optio-demo")
+    redis_url = os.environ.get("REDIS_URL", "redis://localhost:6379")
+    prefix = os.environ.get("OPTIO_PREFIX", "optio")
+
+    db_name = mongo_url.rsplit("/", 1)[-1]
+    client = AsyncIOMotorClient(mongo_url)
+    db = client[db_name]
+
+    fw = Optio()
+    await fw.init(
+        mongo_db=db,
+        prefix=prefix,
+        redis_url=redis_url,
+        services={"optio": fw, "db": db, "prefix": prefix},
+        get_task_definitions=get_task_definitions,
+    )
+
+    await fw.run()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

optio_demo-0.1.0/src/optio_demo/notebooks/sample.py

@@ -0,0 +1,20 @@
+import marimo
+
+__generated_with = "0.9.0"
+app = marimo.App()
+
+
+@app.cell
+def __():
+    import marimo as mo
+    return (mo,)
+
+
+@app.cell
+def __(mo):
+    mo.md("# Optio widget demo\n\nHello from marimo — this notebook is served through the optio widget proxy.")
+    return
+
+
+if __name__ == "__main__":
+    app.run()

optio_demo-0.1.0/src/optio_demo/tasks/__init__.py

@@ -0,0 +1,30 @@
+"""Task definitions for the optio demo application."""
+
+from optio_core.models import TaskInstance, ProcessMetadataFilter
+
+from optio_demo.tasks.terraforming import get_tasks as terraforming_tasks
+from optio_demo.tasks.home import get_tasks as home_tasks
+from optio_demo.tasks.heist import get_tasks as heist_tasks
+from optio_demo.tasks.festival import get_tasks as festival_tasks
+from optio_demo.tasks.wakeup import get_tasks as wakeup_tasks
+from optio_demo.tasks.marimo import get_tasks as marimo_tasks
+from optio_demo.tasks.opencode import get_tasks as opencode_tasks
+from optio_demo.tasks.client_directed import get_tasks as client_directed_tasks
+from optio_demo.tasks.claudecode import get_tasks as claudecode_tasks
+
+
+async def get_task_definitions(
+    services: dict,
+    metadata_filter: ProcessMetadataFilter | None = None,
+) -> list[TaskInstance]:
+    return [
+        *terraforming_tasks(),
+        *home_tasks(),
+        *heist_tasks(),
+        *festival_tasks(),
+        *wakeup_tasks(),
+        *marimo_tasks(),
+        *opencode_tasks(),
+        *client_directed_tasks(),
+        *await claudecode_tasks(services),
+    ]

optio_demo-0.1.0/src/optio_demo/tasks/claudecode.py

@@ -0,0 +1,215 @@
+"""Reference demo tasks for optio-claudecode — the seed lifecycle.
+
+Exposes a static **"Setup Claude Code seed"** task plus one dynamic
+**"Claude Code demo — {name}"** task per captured seed. The operator
+launches setup, logs into Claude Code interactively (``/login``) in the
+ttyd TUI, configures plugins, then stops the task; on teardown the
+environment is captured as a seed and a seed-pinned demo task appears
+(via in-process ``resync``). Authentication comes from the seed, not an
+``ANTHROPIC_API_KEY`` — claude runs under HOME-isolation
+(``HOME=<workdir>/home``), so the host user's ``~/.claude`` is not
+inherited; the seed supplies credentials/settings/plugins instead.
+
+Defaults to local mode; set the ``OPTIO_CLAUDECODE_DEMO_SSH_HOST``
+environment variable to run via SSH on a remote host. Relevant env vars
+(all optional except ``_HOST``):
+
+- ``OPTIO_CLAUDECODE_DEMO_SSH_HOST`` — enables remote mode.
+- ``OPTIO_CLAUDECODE_DEMO_SSH_USER`` — default: ``$USER`` on the worker.
+- ``OPTIO_CLAUDECODE_DEMO_SSH_KEY_PATH`` — default: ``~/.ssh/id_ed25519``.
+- ``OPTIO_CLAUDECODE_DEMO_SSH_PORT`` — default: ``22``.
+
+Hook walkthrough (mirrors the opencode demo), wired on each seed task:
+
+- ``before_execute`` runs ``whoami`` on the host (proves the hook fires
+  inside the session pipeline) and ships ``context.txt`` into the
+  workdir via ``copy_file`` (bytes source). The LLM is instructed to
+  read that file, so its presence is observable end-to-end.
+- ``on_deliverable`` prints the deliverable body to the worker's
+  terminal — additive to the framework's auto-emitted
+  ``"Deliverable: <path>"`` progress message.
+- ``after_execute`` reads ``./optio.log`` back via
+  ``read_text_from_host`` and reports a one-line summary, proving the
+  hook fires before workdir teardown.
+"""
+
+from __future__ import annotations
+
+import os
+from datetime import datetime, timezone
+
+from optio_claudecode import (
+    ClaudeCodeTaskConfig,
+    HookContext,
+    SSHConfig,
+    create_claudecode_task,
+)
+from optio_core.models import TaskInstance
+
+
+CONTEXT_TXT = b"""\
+Mission code-name: Project Petunia
+Authorized color: turquoise
+"""
+
+
+CONSUMER_PROMPT = (
+    "First, read the file `./context.txt` in your working directory. It "
+    "contains a mission code-name and an authorized color. Then ask the "
+    "human about their favorite color. Ship a deliverable file at "
+    "`./deliverables/mission-report.txt` containing the mission "
+    "code-name, the authorized color, the human's favorite color, and "
+    "the number 42. Then signal completion by appending a `DONE` line "
+    "to the `./optio.log` file (writing `DONE` in the chat has no "
+    "effect — it must go into that file)."
+)
+
+
+DEMO_SEED_COLLECTION_SUFFIX = "_demo_claude_seeds"
+
+SEED_SETUP_PROMPT = (
+    "This is a one-time setup session. Use the terminal to log into "
+    "Claude Code (run `/login` and follow the prompts) and install any "
+    "plugins or MCP servers you want available to demo tasks. When you "
+    "are done, STOP this task from the dashboard — your configuration "
+    "(credentials, settings, plugins) will be captured as a reusable "
+    "seed, and a new 'Claude Code demo' task pinned to that seed will "
+    "appear automatically."
+)
+
+
+def _resolve_ssh_config() -> SSHConfig | None:
+    host = os.environ.get("OPTIO_CLAUDECODE_DEMO_SSH_HOST")
+    if not host:
+        return None
+    user = (
+        os.environ.get("OPTIO_CLAUDECODE_DEMO_SSH_USER")
+        or os.environ.get("USER")
+        or "root"
+    )
+    key_path = os.environ.get(
+        "OPTIO_CLAUDECODE_DEMO_SSH_KEY_PATH",
+        os.path.expanduser("~/.ssh/id_ed25519"),
+    )
+    port_raw = os.environ.get("OPTIO_CLAUDECODE_DEMO_SSH_PORT", "22")
+    try:
+        port = int(port_raw)
+    except ValueError:
+        raise RuntimeError(
+            f"OPTIO_CLAUDECODE_DEMO_SSH_PORT must be an integer, got {port_raw!r}"
+        )
+    return SSHConfig(host=host, user=user, key_path=key_path, port=port)
+
+
+async def _before_execute(hook_ctx: HookContext) -> None:
+    out = await hook_ctx.run_on_host("whoami")
+    hook_ctx.report_progress(None, f"claude will run as {out.strip()}")
+    await hook_ctx.copy_file(CONTEXT_TXT, "context.txt")
+
+
+async def _on_deliverable(
+    hook_ctx: HookContext, path: str, text: str,
+) -> None:
+    print(f"[claudecode-demo] deliverable {path}:\n{text}")
+
+
+async def _after_execute(hook_ctx: HookContext) -> None:
+    try:
+        log = await hook_ctx.read_text_from_host("optio.log")
+    except FileNotFoundError:
+        hook_ctx.report_progress(None, "session log: not present")
+        return
+    lines = log.splitlines()
+    counts = {"STATUS": 0, "DELIVERABLE": 0, "DONE": 0, "ERROR": 0}
+    for line in lines:
+        for keyword in counts:
+            if line.startswith(keyword):
+                counts[keyword] += 1
+                break
+    summary = ", ".join(f"{n} {k}" for k, n in counts.items() if n)
+    hook_ctx.report_progress(
+        None,
+        f"session log: {len(lines)} lines ({summary or 'no keywords'})",
+    )
+
+
+def _make_on_seed_saved(db, prefix: str, fw):
+    coll = db[f"{prefix}{DEMO_SEED_COLLECTION_SUFFIX}"]
+
+    async def _on_seed_saved(seed_id: str) -> None:
+        # Cosmetic numbering; a concurrent-save race may reuse a number —
+        # acceptable, the seedId is the real key.
+        count = await coll.count_documents({})
+        name = f"Config #{count + 1}"
+        await coll.insert_one({
+            "seedId": seed_id,
+            "name": name,
+            "createdAt": datetime.now(timezone.utc),
+        })
+        # Regenerate the task list so a seed-pinned demo task appears.
+        await fw.resync()
+
+    return _on_seed_saved
+
+
+async def get_tasks(services: dict) -> list[TaskInstance]:
+    db = services["db"]
+    prefix = services["prefix"]
+    fw = services["optio"]
+    ssh = _resolve_ssh_config()
+
+    tasks: list[TaskInstance] = [
+        # The seed setup task: vanilla (no seed_id), on_seed_saved wired.
+        create_claudecode_task(
+            process_id="claudecode-seed-setup",
+            name="Setup Claude Code seed",
+            description=(
+                "One-time: log into Claude Code and configure plugins, "
+                "then stop the task to capture a reusable seed. A new "
+                "seed-pinned demo task appears afterward."
+            ),
+            config=ClaudeCodeTaskConfig(
+                consumer_instructions=SEED_SETUP_PROMPT,
+                ssh=ssh,
+                # Run setup in bypassPermissions so the operator accepts the
+                # bypass-mode warning once here; the acknowledgment lands in
+                # ~/.claude.json and is captured into the seed, so every
+                # seed-launched demo task (also bypassPermissions) starts
+                # pre-acked instead of warning on each launch.
+                permission_mode="bypassPermissions",
+                # Interactive login; no resume for a one-time setup session.
+                supports_resume=False,
+                on_seed_saved=_make_on_seed_saved(db, prefix, fw),
+            ),
+        ),
+    ]
+
+    # One seed-pinned demo task per recorded seed.
+    coll = db[f"{prefix}{DEMO_SEED_COLLECTION_SUFFIX}"]
+    async for rec in coll.find({}, projection={"seedId": 1, "name": 1}):
+        seed_id = rec["seedId"]
+        name = rec.get("name", seed_id)
+        tasks.append(
+            create_claudecode_task(
+                process_id=f"claudecode-demo-seed-{seed_id}",
+                name=f"Claude Code demo — {name}",
+                description=(
+                    "Fresh Claude Code session started from a captured "
+                    f"seed ({name}): logged-in and configured, new "
+                    "conversation. Reads context.txt, asks for a color, "
+                    "ships a deliverable."
+                ),
+                config=ClaudeCodeTaskConfig(
+                    consumer_instructions=CONSUMER_PROMPT,
+                    permission_mode="bypassPermissions",
+                    ssh=ssh,
+                    before_execute=_before_execute,
+                    after_execute=_after_execute,
+                    on_deliverable=_on_deliverable,
+                    seed_id=seed_id,
+                    supports_resume=True,
+                ),
+            )
+        )
+
+    return tasks

optio_demo-0.1.0/src/optio_demo/tasks/client_directed.py

@@ -0,0 +1,128 @@
+"""Client-directed events demo tasks (phase 2).
+
+Four tasks exercising the three new capabilities end-to-end:
+
+  - ``open-optio-repo``: pure-Python ``ctx.request_browser_open`` (view-scoped).
+  - ``open-browser-via-tool``: a host task that runs a tiny Python script
+    (``import webbrowser; webbrowser.open(URL)`` then ``DONE``) through the
+    optio-agents session driver with ``get_protocol(browser="redirect")`` —
+    shim → ``BROWSER:`` marker → parser → ``ctx.request_browser_open`` with no
+    claude/opencode involved.
+  - ``need-attention-demo``: ``ctx.need_attention`` (session-scoped).
+  - ``domain-message-demo``: ``ctx.domain_message`` (session-scoped).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+
+from optio_core.models import TaskInstance
+from optio_host.host import LocalHost
+from optio_agents import run_log_protocol_session, get_protocol
+
+
+OPTIO_REPO_URL = "https://github.com/deai-network/optio"
+
+
+async def _open_optio_repo(ctx) -> None:
+    ctx.report_progress(0, "Opening the optio repo in your browser")
+    rid = await ctx.request_browser_open(OPTIO_REPO_URL)
+    ctx.report_progress(100, f"Requested browser open (requestId={rid})")
+
+
+async def _open_browser_via_tool(ctx) -> None:
+    """Host-bridge capture test: run a Python opener under capture shims."""
+    taskdir = f"/tmp/optio-demo-browser-{os.getpid()}-{ctx.process_id}"
+    os.makedirs(taskdir, exist_ok=True)
+    host = LocalHost(taskdir=taskdir)
+    os.makedirs(host.workdir, exist_ok=True)
+
+    async def body(host, hook_ctx) -> None:
+        # The driver installed the redirect (capture) shims before the body
+        # ran and exposed their env on hook_ctx.browser_launch_env. A trivial
+        # opener: webbrowser.open routes through xdg-open (the shim), which
+        # appends the BROWSER: marker to optio.log. Then signal DONE.
+        script = (
+            "import webbrowser; "
+            f"webbrowser.open({OPTIO_REPO_URL!r}); "
+        )
+        await host.run_command(
+            f"python3 -c {script!r}",
+            env=hook_ctx.browser_launch_env,
+            cwd=host.workdir,
+        )
+        # The shim has appended BROWSER: by now; close out the session.
+        await host.run_command(f"echo DONE >> {host.workdir}/optio.log")
+
+    await run_log_protocol_session(
+        host, ctx, body=body, protocol=get_protocol(browser="redirect"),
+    )
+
+
+async def _need_attention_demo(ctx) -> None:
+    # Delay before asking, so the operator can navigate away to another task
+    # and observe the session-scoped attention request pull them back here.
+    DELAY = 10
+    for elapsed in range(DELAY):
+        ctx.report_progress(
+            int(100 * elapsed / DELAY),
+            f"Working… will request attention in {DELAY - elapsed}s "
+            f"(navigate away to test it)",
+        )
+        await asyncio.sleep(1)
+    rid = await ctx.need_attention("The demo task would like you to look at it.")
+    ctx.report_progress(100, f"Attention requested (requestId={rid})")
+
+
+async def _domain_message_demo(ctx) -> None:
+    ctx.report_progress(0, "Sending a domain message")
+    rid = await ctx.domain_message(
+        "demo-event",
+        {"severity": "info", "detail": "hello from the demo task"},
+    )
+    ctx.report_progress(100, f"Domain message sent (requestId={rid})")
+
+
+def get_tasks() -> list[TaskInstance]:
+    return [
+        TaskInstance(
+            execute=_open_optio_repo,
+            process_id="open-optio-repo",
+            name="Open the optio repo",
+            description=(
+                "Pure-Python browser_open: asks your browser to open the optio "
+                "GitHub repo. View-scoped — delivered to whoever is watching."
+            ),
+        ),
+        TaskInstance(
+            execute=_open_browser_via_tool,
+            process_id="open-browser-via-tool",
+            name="Open browser via tool (capture bridge)",
+            description=(
+                "Host task running a Python webbrowser.open under "
+                "get_protocol(redirect) capture shims; exercises shim → "
+                "BROWSER: marker → parser → ctx.request_browser_open "
+                "end-to-end (no agent)."
+            ),
+        ),
+        TaskInstance(
+            execute=_need_attention_demo,
+            process_id="need-attention-demo",
+            name="Request attention",
+            description=(
+                "Calls ctx.need_attention(...). Session-scoped — reaches the "
+                "browser session that launched it. The dashboard navigates to "
+                "this process via onAttention."
+            ),
+        ),
+        TaskInstance(
+            execute=_domain_message_demo,
+            process_id="domain-message-demo",
+            name="Send a domain message",
+            description=(
+                "Calls ctx.domain_message(keyword, data). Session-scoped; the "
+                "dashboard surfaces it via onDomainMessage (console/toast)."
+            ),
+        ),
+    ]