optio-agents 0.1.0__py3-none-any.whl

optio_agents/__init__.py

@@ -0,0 +1,45 @@
+"""optio-agents — agent-coordination layer for optio task types.
+
+Owns the optio.log keyword protocol (parser + session driver), the
+``HookContext`` passed to agent task hooks, and the single source of
+truth for the LLM-facing keyword-protocol documentation.
+"""
+
+from optio_agents.context import HookContext, HookContextProtocol
+from optio_agents.protocol import (
+    DELIVERABLE_QUEUE_BOUND,
+    DeliverableCallback,
+    DeliverableEvent,
+    DoneEvent,
+    ErrorEvent,
+    HookCallback,
+    LogEvent,
+    StatusEvent,
+    UnknownLine,
+    fetch_deliverable_text,
+    parse_log_line,
+    relativize_deliverable_path,
+    run_log_protocol_session,
+    validate_deliverable_path,
+)
+from optio_agents import browser_capture
+
+__all__ = [
+    "HookContext",
+    "browser_capture",
+    "HookContextProtocol",
+    "run_log_protocol_session",
+    "fetch_deliverable_text",
+    "DeliverableCallback",
+    "HookCallback",
+    "DELIVERABLE_QUEUE_BOUND",
+    "parse_log_line",
+    "DeliverableEvent",
+    "DoneEvent",
+    "ErrorEvent",
+    "LogEvent",
+    "StatusEvent",
+    "UnknownLine",
+    "validate_deliverable_path",
+    "relativize_deliverable_path",
+]

optio_agents/browser_capture.py

@@ -0,0 +1,53 @@
+"""Opt-in browser-open capture shims for the agent launch environment.
+
+`enable(host)` writes capture-only shims for the common browser-opener
+commands (xdg-open, gio, open, sensible-browser, www-browser) under
+``<workdir>/bin``. Each shim appends a ``BROWSER: "<url>"`` line to
+``<workdir>/optio.log`` and exits 0 — it never launches a real browser
+(there is none on the worker). It returns env additions to merge into
+the agent launch env: ``BROWSER`` pointing at the shim and a
+``<workdir>/bin`` PATH prepend.
+
+Opt-in (default off) so it never collides with opencode's own browser
+*suppression* shims (the two shim sets are never enabled together).
+
+Mirrors the opencode suppression-shim pattern in
+``optio_opencode.host_actions`` but captures instead of suppressing.
+"""
+
+from __future__ import annotations
+
+import os
+
+from optio_host.host import Host
+
+
+_SHIM_NAMES = ("xdg-open", "gio", "open", "sensible-browser", "www-browser")
+
+
+async def enable(host: Host) -> dict[str, str]:
+    """Write the capture shims under ``<workdir>/bin`` and return env additions.
+
+    Returns a dict with ``BROWSER`` and ``PATH`` keys to merge into the
+    agent launch env (``PATH`` prepends ``<workdir>/bin``).
+    """
+    # The shim appends `BROWSER: "<first-arg>"` to optio.log and exits 0.
+    # $1 is the URL the opener was invoked with. Quote it so the captured
+    # marker is unambiguous even if the URL contains spaces.
+    shim_body = (
+        "#!/bin/sh\n"
+        f'printf \'BROWSER: "%s"\\n\' "$1" >> {host.workdir}/optio.log\n'
+        "exit 0\n"
+    )
+    for name in _SHIM_NAMES:
+        await host.write_text(f"bin/{name}", shim_body)
+    await host.run_command(f"chmod +x {host.workdir}/bin/*")
+
+    workdir_bin = f"{host.workdir}/bin"
+    extra_path = workdir_bin + ":" + os.environ.get(
+        "PATH", "/usr/local/bin:/usr/bin:/bin",
+    )
+    return {
+        "BROWSER": f"{workdir_bin}/xdg-open",
+        "PATH": extra_path,
+    }

optio_agents/context.py

@@ -0,0 +1,244 @@
+"""HookContext: ProcessContext + host primitives for task-body hooks."""
+
+from __future__ import annotations
+
+import os
+from typing import Any, AsyncIterator, Awaitable, Callable, Protocol
+
+# Imported at module top so tests can monkeypatch this name on the module.
+from optio_host.download import create_download_task
+from optio_host.host import HostCommandError, RunResult
+
+
+class HookContext:
+    """ProcessContext + host primitives, passed to before/after_execute hooks
+    and to on_deliverable callbacks.
+
+    Attributes not defined on this class fall through to the wrapped
+    ProcessContext via __getattr__, so consumers can call e.g.
+    ``hook_ctx.report_progress(...)`` directly.
+    """
+
+    def __init__(self, ctx, host) -> None:
+        # Use object.__setattr__ to avoid __getattr__ recursion in __init__.
+        object.__setattr__(self, "_ctx", ctx)
+        object.__setattr__(self, "_host", host)
+
+    def __getattr__(self, name: str) -> Any:
+        # Only called if the attribute isn't found on the instance / class.
+        return getattr(self._ctx, name)
+
+    async def run_on_host(
+        self,
+        command: str,
+        *,
+        check: bool = True,
+        capture_stderr: bool = False,
+        cwd: str | None = None,
+    ):
+        result = await self._host.run_command(command, cwd=cwd)
+        if check:
+            if result.exit_code != 0:
+                raise HostCommandError(
+                    command=command,
+                    exit_code=result.exit_code,
+                    stdout=result.stdout,
+                    stderr=result.stderr,
+                )
+            return result.stdout + (result.stderr if capture_stderr else "")
+        return result
+
+    async def copy_file(
+        self,
+        source,
+        target: str,
+        *,
+        skip_if_unchanged: bool = False,
+    ) -> None:
+        from bson import ObjectId  # local import to avoid a hard top-level dep
+
+        host_home = await self._host.resolve_host_home()
+        abs_target = _resolve_target_path(target, self._host.workdir, host_home)
+        basename = os.path.basename(abs_target) or abs_target
+        ctx = self._ctx
+        skipped = False
+
+        def _progress_cb(percent, message):
+            nonlocal skipped
+            if message == "already up to date":
+                skipped = True
+                ctx.report_progress(None, f"Already up to date: {basename}")
+            elif percent is not None:
+                ctx.report_progress(percent, None)
+
+        # Resolve blob sources to (iterator, expected_sha) pair.
+        expected_sha: str | None = None
+        if isinstance(source, ObjectId):
+            payload = await self._read_blob_bytes(source)
+            if skip_if_unchanged:
+                import hashlib
+                expected_sha = hashlib.sha256(payload).hexdigest()
+
+            async def _gen():
+                # Yield the payload as one (or a few) chunks. For very large
+                # blobs we could stream via load_blob, but reading-then-iterating
+                # is simpler and correct.
+                yield payload
+
+            source = _gen()
+
+        if skip_if_unchanged:
+            ctx.report_progress(None, f"Verifying {basename}...")
+        else:
+            ctx.report_progress(None, f"Copying {basename}...")
+
+        await self._host.put_file_to_host(
+            source,
+            abs_target,
+            expected_sha256=expected_sha,
+            skip_if_unchanged=skip_if_unchanged,
+            progress_cb=_progress_cb,
+        )
+
+        if skip_if_unchanged and not skipped:
+            ctx.report_progress(None, f"Copying {basename}...")
+
+    async def _read_blob_bytes(self, file_id) -> bytes:
+        async with self._ctx.load_blob(file_id) as reader:
+            return await reader.read()
+
+    async def read_from_host(self, path: str, *, silent: bool = False) -> bytes:
+        host_home = await self._host.resolve_host_home()
+        abs_path = _resolve_target_path(path, self._host.workdir, host_home)
+        if not silent:
+            basename = os.path.basename(abs_path) or abs_path
+            self._ctx.report_progress(None, f"Reading {basename}...")
+
+        def _progress_cb(percent, message):
+            if percent is not None:
+                self._ctx.report_progress(percent, None)
+
+        return await self._host.fetch_bytes_from_host(
+            abs_path, progress_cb=_progress_cb,
+        )
+
+    async def read_text_from_host(self, path: str, *, silent: bool = False) -> str:
+        data = await self.read_from_host(path, silent=silent)
+        return data.decode("utf-8")
+
+    async def download_file(
+        self,
+        url: str,
+        target: str,
+        *,
+        description: str | None = None,
+        cleanup_on_fail: bool = True,
+    ) -> None:
+        """Download ``url`` to ``target`` on the host as a child task.
+
+        Spawns a child process under the current task that runs curl on the
+        same host the parent runs on. Reports a single "Downloading
+        <basename>" message followed by numeric progress percent updates on
+        the child's ProcessContext.
+
+        ``target`` is resolved by the same rules as ``copy_file``: absolute
+        path | ``~`` / ``~/...`` home-relative | workdir-relative. On a
+        workdir-escape attempt this raises ``ValueError`` without spawning
+        a child.
+
+        Returns None on success. Raises
+        ``optio_core.exceptions.ChildProcessFailed`` if the child fails;
+        the original ``DownloadFailed`` is preserved via ``__cause__``
+        (and on the child's ``ChildResult.original_exception`` when caller
+        uses ``parallel_group``). Parent-task cancellation propagates to
+        the child automatically.
+        """
+        host_home = await self._host.resolve_host_home()
+        abs_target = _resolve_target_path(target, self._host.workdir, host_home)
+        basename = os.path.basename(abs_target) or abs_target
+
+        n = self._ctx._child_counter.get("next", 0)
+        child_process_id = f"{self._ctx.process_id}.download-{n}"
+        child_name = f"download {basename}"
+
+        task = create_download_task(
+            process_id=child_process_id,
+            name=child_name,
+            url=url,
+            target=abs_target,
+            host=self._host,
+            description=description,
+            cleanup_on_fail=cleanup_on_fail,
+        )
+        await self._ctx.run_child_task(task)
+
+
+class HookContextProtocol(Protocol):
+    """Type-hint surface for hook authors who want IDE discoverability.
+
+    Subset of ProcessContext + the four new methods.
+    """
+
+    process_id: str
+
+    @property
+    def params(self) -> dict: ...
+
+    @property
+    def metadata(self) -> dict: ...
+
+    def report_progress(self, percent: float | None, message: str | None = None) -> None: ...
+    def should_continue(self) -> bool: ...
+    async def copy_file(
+        self,
+        source,
+        target: str,
+        *,
+        skip_if_unchanged: bool = False,
+    ) -> None: ...
+    async def run_on_host(
+        self,
+        command: str,
+        *,
+        check: bool = True,
+        capture_stderr: bool = False,
+        cwd: str | None = None,
+    ) -> "str | RunResult": ...
+    async def read_from_host(self, path: str, *, silent: bool = False) -> bytes: ...
+    async def read_text_from_host(self, path: str, *, silent: bool = False) -> str: ...
+    async def download_file(
+        self,
+        url: str,
+        target: str,
+        *,
+        description: str | None = None,
+        cleanup_on_fail: bool = True,
+    ) -> None: ...
+
+
+def _resolve_target_path(path: str, workdir: str, host_home: str) -> str:
+    """Resolve a user-supplied path to an absolute host path.
+
+    Three forms:
+      - starts with `/` → absolute, used as-is
+      - `~` or starts with `~/` → home-relative, expand once
+      - otherwise → workdir-relative; reject `..` and any escape
+
+    workdir and host_home must both be absolute paths.
+    """
+    if not path:
+        raise ValueError("path must not be empty")
+    if path.startswith("/"):
+        return path
+    if path == "~":
+        return host_home
+    if path.startswith("~/"):
+        return host_home + "/" + path[2:]
+    # workdir-relative
+    if ".." in path.split("/"):
+        raise ValueError(f"workdir-relative path may not contain '..': {path!r}")
+    resolved = os.path.normpath(os.path.join(workdir, path))
+    workdir_norm = os.path.normpath(workdir).rstrip("/")
+    if resolved != workdir_norm and not resolved.startswith(workdir_norm + "/"):
+        raise ValueError(f"workdir-relative path escapes workdir: {path!r}")
+    return resolved

optio_agents/protocol/__init__.py

@@ -0,0 +1,49 @@
+"""optio-agents log/deliverables coordination protocol.
+
+Built on top of optio_host.host primitives. Knows nothing about specific
+consumer task types (opencode, recipe execution, ...).
+"""
+
+from optio_agents.protocol.parser import (
+    AttentionEvent,
+    BrowserEvent,
+    DeliverableEvent,
+    DomainMessageEvent,
+    DoneEvent,
+    ErrorEvent,
+    LogEvent,
+    StatusEvent,
+    UnknownLine,
+    parse_log_line,
+    relativize_deliverable_path,
+    validate_deliverable_path,
+)
+from optio_agents.protocol.session import (
+    DELIVERABLE_QUEUE_BOUND,
+    DeliverableCallback,
+    HookCallback,
+    fetch_deliverable_text,
+    run_log_protocol_session,
+)
+
+__all__ = [
+    # parser
+    "parse_log_line",
+    "DeliverableEvent",
+    "DoneEvent",
+    "ErrorEvent",
+    "BrowserEvent",
+    "AttentionEvent",
+    "DomainMessageEvent",
+    "LogEvent",
+    "StatusEvent",
+    "UnknownLine",
+    "validate_deliverable_path",
+    "relativize_deliverable_path",
+    # session
+    "run_log_protocol_session",
+    "DeliverableCallback",
+    "HookCallback",
+    "fetch_deliverable_text",
+    "DELIVERABLE_QUEUE_BOUND",
+]

optio_agents/protocol/parser.py

@@ -0,0 +1,169 @@
+"""Parse lines from the optio.log file that the on-host agent appends to.
+
+The format is keyword-prefixed, one line per event. See the design spec
+Section 6 of the optio-opencode design (the protocol's original home;
+unchanged after the optio-host split).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from dataclasses import dataclass
+from typing import Union
+
+
+@dataclass(frozen=True)
+class StatusEvent:
+    percent: int | None
+    message: str
+
+
+@dataclass(frozen=True)
+class DeliverableEvent:
+    path: str
+
+
+@dataclass(frozen=True)
+class DoneEvent:
+    summary: str | None
+
+
+@dataclass(frozen=True)
+class ErrorEvent:
+    message: str | None
+
+
+@dataclass(frozen=True)
+class BrowserEvent:
+    url: str
+
+
+@dataclass(frozen=True)
+class AttentionEvent:
+    reason: str
+
+
+@dataclass(frozen=True)
+class DomainMessageEvent:
+    keyword: str
+    data: object
+
+
+@dataclass(frozen=True)
+class UnknownLine:
+    text: str
+
+
+LogEvent = Union[
+    StatusEvent, DeliverableEvent, DoneEvent, ErrorEvent,
+    BrowserEvent, AttentionEvent, DomainMessageEvent, UnknownLine,
+]
+
+
+_RE_STATUS = re.compile(r"^STATUS:\s*(?:(\d{1,3})%\s+)?(.*)$")
+_RE_DELIVERABLE = re.compile(r"^DELIVERABLE:\s*(.+?)\s*$")
+_RE_DONE = re.compile(r"^DONE(?::\s*(.*))?\s*$")
+_RE_ERROR = re.compile(r"^ERROR(?::\s*(.*))?\s*$")
+_RE_BROWSER = re.compile(r"^BROWSER:\s*(.+?)\s*$")
+_RE_ATTENTION = re.compile(r"^ATTENTION:\s*(.+?)\s*$")
+_RE_DOMAIN_MESSAGE = re.compile(r"^DOMAIN_MESSAGE:\s*(\S+)\s+(.*)$")
+
+
+def parse_log_line(line: str) -> LogEvent:
+    """Classify one line from optio.log into a LogEvent."""
+    stripped = line.rstrip("\r\n").rstrip()
+    m = _RE_STATUS.match(stripped)
+    if m:
+        pct_raw, msg = m.group(1), m.group(2)
+        percent: int | None
+        if pct_raw is None:
+            percent = None
+        else:
+            percent = min(int(pct_raw), 100)
+        return StatusEvent(percent=percent, message=msg)
+
+    m = _RE_DELIVERABLE.match(stripped)
+    if m:
+        return DeliverableEvent(path=m.group(1))
+
+    m = _RE_DONE.match(stripped)
+    if m:
+        summary = m.group(1) if m.group(1) else None
+        return DoneEvent(summary=summary)
+
+    m = _RE_ERROR.match(stripped)
+    if m:
+        msg = m.group(1) if m.group(1) else None
+        return ErrorEvent(message=msg)
+
+    m = _RE_BROWSER.match(stripped)
+    if m:
+        return BrowserEvent(url=m.group(1))
+
+    m = _RE_ATTENTION.match(stripped)
+    if m:
+        return AttentionEvent(reason=m.group(1))
+
+    m = _RE_DOMAIN_MESSAGE.match(stripped)
+    if m:
+        keyword, payload = m.group(1), m.group(2)
+        try:
+            data = json.loads(payload)
+        except (ValueError, json.JSONDecodeError):
+            # Malformed JSON: drop (not dispatched). Surfaced as UnknownLine
+            # so the tail loop logs the raw line for diagnosis.
+            return UnknownLine(text=stripped)
+        return DomainMessageEvent(keyword=keyword, data=data)
+
+    return UnknownLine(text=stripped)
+
+
+def validate_deliverable_path(path: str, workdir: str) -> str:
+    """Resolve ``path`` against ``workdir`` and ensure it stays inside.
+
+    Returns the absolute, normalized path.  Raises ValueError on escape.
+    """
+    workdir_abs = os.path.realpath(workdir)
+    if os.path.isabs(path):
+        candidate = os.path.realpath(path)
+    else:
+        candidate = os.path.realpath(os.path.join(workdir_abs, path))
+
+    # Ensure the resolved path is inside workdir_abs.
+    rel = os.path.relpath(candidate, workdir_abs)
+    if rel == ".." or rel.startswith(".." + os.sep):
+        raise ValueError(
+            f"deliverable path escapes workdir: {path!r} (resolved to {candidate!r}, "
+            f"workdir={workdir_abs!r})"
+        )
+    return candidate
+
+
+DELIVERABLES_SUBDIR = "deliverables"
+
+
+def relativize_deliverable_path(absolute_path: str, workdir: str) -> str:
+    """Return ``absolute_path`` made relative to ``<workdir>/deliverables/``.
+
+    Precondition: ``absolute_path`` has already been validated to be
+    inside ``workdir`` (via :func:`validate_deliverable_path`). Both
+    arguments may be any absolute paths; this function realpaths them
+    internally before relativizing.
+
+    Raises ``ValueError`` if ``absolute_path`` is not strictly under
+    ``<workdir>/deliverables/`` (including when it equals the
+    deliverables root itself or escapes outside it).
+    """
+    deliverables_root = os.path.realpath(
+        os.path.join(workdir, DELIVERABLES_SUBDIR)
+    )
+    target = os.path.realpath(absolute_path)
+    rel = os.path.relpath(target, deliverables_root)
+    if rel == "." or rel == ".." or rel.startswith(".." + os.sep):
+        raise ValueError(
+            f"deliverable path is not under <workdir>/{DELIVERABLES_SUBDIR}/: "
+            f"{absolute_path!r} (workdir={workdir!r})"
+        )
+    return rel

optio_agents/protocol/prompt.py

@@ -0,0 +1,54 @@
+"""Single source of truth for the LLM-facing keyword-protocol documentation.
+
+This module lives next to ``parser.py`` so the prose that teaches an agent
+how to speak the protocol cannot drift from the regexes that enforce it.
+Consumers (e.g. optio-opencode) compose ``LOG_CHANNEL_PROMPT`` into their
+own AGENTS.md framing.
+
+Documents the keywords parsed by ``optio_agents.protocol.parser``:
+``STATUS:`` / ``DELIVERABLE:`` / ``DONE`` / ``ERROR`` / ``BROWSER:`` /
+``ATTENTION:`` / ``DOMAIN_MESSAGE:``.
+"""
+
+
+LOG_CHANNEL_PROMPT = """## Log channel
+
+Append one line per entry to `./optio.log` in this directory. Each line
+must start with one of:
+
+- `STATUS:` — progress update for the human. Optional leading percent,
+  e.g. `STATUS: 50% counting my fingers`.
+- `DELIVERABLE:` — absolute or workdir-relative path to a file you've
+  just produced, e.g. `DELIVERABLE: ./deliverables/summary.md`.
+- `DONE` — you have finished the task. May be followed by an optional
+  summary on the same line: `DONE: wrote the report`.
+- `ERROR` — you cannot continue. May be followed by an optional
+  message: `ERROR: provider auth failed`.
+- `BROWSER:` — ask the operator's browser to open a URL, e.g.
+  `BROWSER: https://example.com/login`. Use for flows that require the
+  human to visit a page (e.g. an auth/login URL).
+- `ATTENTION:` — request human attention with a short reason, e.g.
+  `ATTENTION: waiting for your approval`.
+- `DOMAIN_MESSAGE:` — push an application-specific message: a keyword
+  token followed by single-line JSON, e.g.
+  `DOMAIN_MESSAGE: build-finished {"artifact":"app.zip"}`. The JSON must
+  be valid and on one line; malformed JSON is dropped.
+
+**Every entry must end with a newline character (`\\n`).** The host
+reads `optio.log` with a line-oriented tailer that only emits a line
+once it sees `\\n`; an entry written without a trailing newline (e.g.
+via `printf 'DONE'`) will be buffered indefinitely and never reach the
+host. Use `echo`, `>>` redirection of a heredoc, or any other mechanism
+that guarantees a trailing newline. If unsure, double-check with
+`tail -c 1 ./optio.log` — the result must be a newline.
+
+After writing `DONE` or `ERROR`, the session will terminate. Do not
+write further lines.
+
+## Deliverables
+
+Place files you want to hand back to the host under `./deliverables/`.
+For each file, write a `DELIVERABLE:` log line *after* the file exists
+and its contents are final. The host fetches files by reading these
+log lines.
+"""

optio_agents/protocol/session.py

@@ -0,0 +1,330 @@
+"""Generic log/deliverables session driver.
+
+`run_log_protocol_session` runs a caller-supplied ``body`` callable
+against a ``Host`` while two cooperating tasks consume the
+``<workdir>/optio.log`` channel:
+
+  - ``_tail_and_dispatch`` parses each log line into a typed event
+    (STATUS / DELIVERABLE / DONE / ERROR) and dispatches accordingly.
+  - ``_deliverable_fetch_loop`` drains the deliverable queue, fetches
+    each file from the host, decodes UTF-8, and invokes the
+    consumer's ``on_deliverable`` callback.
+
+The driver knows nothing about specific consumers (opencode,
+recipe-execution, ...). Each consumer's body is responsible for its
+own subprocess management and arranging for the agent on the host to
+write events to ``<workdir>/optio.log``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import TYPE_CHECKING, Awaitable, Callable
+
+from optio_agents.context import HookContext
+from optio_host.host import Host
+from optio_agents.protocol.parser import (
+    AttentionEvent,
+    BrowserEvent,
+    DeliverableEvent,
+    DomainMessageEvent,
+    DoneEvent,
+    ErrorEvent,
+    LogEvent,
+    StatusEvent,
+    UnknownLine,
+    parse_log_line,
+    relativize_deliverable_path,
+    validate_deliverable_path,
+)
+
+if TYPE_CHECKING:
+    from optio_core.context import ProcessContext
+
+
+_LOG = logging.getLogger(__name__)
+
+
+DELIVERABLE_QUEUE_BOUND = 64
+
+
+# Public type aliases. ``HookContext`` is forward-quoted in these aliases
+# so consumers don't need to import HookContext to type-check.
+DeliverableCallback = Callable[["HookContext", str, str], Awaitable[None]]
+"""Consumer callback invoked per fetched DELIVERABLE.
+
+Arguments: ``(hook_ctx, deliverable_path, decoded_text)``.
+
+``deliverable_path`` is the path of the deliverable file relative to
+``<workdir>/deliverables/`` (e.g. ``"summary.md"`` or
+``"sub/summary.md"``). It matches the value emitted in the
+auto-generated ``"Deliverable: <path>"`` progress message.
+"""
+
+
+HookCallback = Callable[["HookContext"], Awaitable[None]]
+"""Hook callback receiving a HookContext. Used by before_execute and
+after_execute."""
+
+
+class _SessionFailed(Exception):
+    """Internal signal: drive the surrounding session to ``failed``.
+
+    Re-raised by ``run_log_protocol_session`` when:
+      * the agent emits ERROR
+      * the body returns without DONE having fired
+
+    Consumers catch this and translate to their own failure semantics.
+    """
+
+
+async def fetch_deliverable_text(host: Host, absolute_path: str) -> str:
+    """Read the host file at ``absolute_path`` and decode it as UTF-8.
+
+    Thin wrapper around ``host.fetch_bytes_from_host`` for the common
+    text-deliverable case used by the protocol session driver.
+    """
+    data = await host.fetch_bytes_from_host(absolute_path)
+    return data.decode("utf-8")
+
+
+async def run_log_protocol_session(
+    host: Host,
+    ctx: "ProcessContext",
+    *,
+    body: Callable[[Host, HookContext], Awaitable[None]],
+    on_deliverable: DeliverableCallback | None = None,
+    before_execute: HookCallback | None = None,
+    after_execute: HookCallback | None = None,
+) -> None:
+    """Run ``body`` against ``host`` while the log/deliverables protocol
+    cooperates with it.
+
+    Lifecycle:
+      1. ``host.setup_workdir()`` (mkdir workdir).
+      2. Create ``<workdir>/deliverables/`` and an empty
+         ``<workdir>/optio.log``.
+      3. ``before_execute(hook_ctx)`` if set.
+      4. Spawn three concurrent tasks:
+         - ``_tail_and_dispatch``: parse lines from ``optio.log``,
+           emit progress / queue deliverables / set done/error flags.
+         - ``_deliverable_fetch_loop``: drain queue, fetch + decode,
+           invoke ``on_deliverable``.
+         - ``body(host, hook_ctx)``: caller's work.
+      5. Await ``{tail, body, cancel}`` with ``FIRST_COMPLETED``.
+      6. Drain queue, cancel the still-running watchers.
+      7. ``after_execute(hook_ctx)`` if set, with the same failure
+         semantics: re-raises if the session was healthy, logged
+         otherwise.
+
+    Outcomes:
+      * Agent emits ``DONE`` → returns clean.
+      * Agent emits ``ERROR`` → raises ``_SessionFailed``.
+      * Body returns without ``DONE`` having fired → raises
+        ``_SessionFailed`` (the body finished prematurely; no
+        successful completion signal observed).
+      * Process cancellation → returns clean (caller decides what to
+        do next).
+
+    What this driver does NOT do:
+      * Workdir teardown / ``host.cleanup_taskdir`` — caller's
+        responsibility (caller may want to capture a snapshot first).
+      * Subprocess termination — body owns its handles.
+      * Snapshot / resume — caller brackets around this call.
+    """
+    hook_ctx = HookContext(ctx, host)
+
+    # Workdir + protocol artifacts. ``setup_workdir`` mkdirs the workdir
+    # only; the protocol-specific deliverables/ dir + empty optio.log
+    # channel are owned by the protocol driver itself.
+    await host.setup_workdir()
+    deliverables_dir = f"{host.workdir}/deliverables"
+    await host.run_command(f"mkdir -p {deliverables_dir}")
+    await host.write_text("optio.log", "")
+
+    session_error: BaseException | None = None
+    cancelled = False
+    fetch_task: asyncio.Task | None = None
+    tail_task: asyncio.Task | None = None
+    body_task: asyncio.Task | None = None
+    cancel_task: asyncio.Task | None = None
+
+    try:
+        # before_execute runs inside the try so a failure here still
+        # triggers the after_execute cleanup in the outer finally.
+        if before_execute is not None:
+            await before_execute(hook_ctx)
+
+        deliverable_queue: asyncio.Queue[tuple[str, str]] = asyncio.Queue(
+            maxsize=DELIVERABLE_QUEUE_BOUND,
+        )
+        done_flag = asyncio.Event()
+        error_flag: list[str | None] = []  # [message] or [] if not fired
+
+        fetch_task = asyncio.create_task(
+            _deliverable_fetch_loop(host, on_deliverable, deliverable_queue, ctx, hook_ctx),
+        )
+        tail_task = asyncio.create_task(
+            _tail_and_dispatch(host, ctx, deliverable_queue, done_flag, error_flag),
+        )
+        body_task = asyncio.create_task(body(host, hook_ctx))
+        cancel_task = asyncio.create_task(_watch_cancellation(ctx))
+
+        done, _pending = await asyncio.wait(
+            {tail_task, body_task, cancel_task},
+            return_when=asyncio.FIRST_COMPLETED,
+        )
+
+        cancelled = (
+            cancel_task in done
+            and not cancel_task.cancelled()
+            and cancel_task.exception() is None
+            and cancel_task.result() is True
+        )
+
+        if error_flag:
+            raise _SessionFailed(error_flag[0] or "agent reported ERROR")
+
+        if body_task in done and not cancelled and not done_flag.is_set():
+            # Body completed without DONE — premature exit.
+            exc = body_task.exception()
+            if exc is not None:
+                raise exc
+            raise _SessionFailed("body returned before DONE was observed")
+
+        # Drain remaining deliverables before returning.
+        await deliverable_queue.join()
+
+    except BaseException as exc:
+        session_error = exc
+        raise
+
+    finally:
+        active_tasks = [
+            t for t in (tail_task, body_task, cancel_task, fetch_task)
+            if t is not None
+        ]
+        for t in active_tasks:
+            if not t.done():
+                t.cancel()
+        if active_tasks:
+            await asyncio.gather(*active_tasks, return_exceptions=True)
+
+        if after_execute is not None:
+            try:
+                await after_execute(hook_ctx)
+            except BaseException as after_exc:
+                if session_error is None:
+                    raise
+                ctx.report_progress(
+                    None,
+                    f"after_execute callback raised: {after_exc!r}",
+                )
+
+
+# --- private helpers ---------------------------------------------------
+
+
+async def _tail_and_dispatch(
+    host: Host,
+    ctx: "ProcessContext",
+    deliverable_queue: asyncio.Queue[tuple[str, str]],
+    done_flag: asyncio.Event,
+    error_flag: list,
+) -> None:
+    """Consume tail_file(optio.log), parse each line, dispatch by keyword."""
+    async for line in host.tail_file(f"{host.workdir}/optio.log"):
+        ev: LogEvent = parse_log_line(line)
+        if isinstance(ev, StatusEvent):
+            ctx.report_progress(ev.percent, ev.message)
+        elif isinstance(ev, DeliverableEvent):
+            try:
+                absolute = validate_deliverable_path(ev.path, host.workdir)
+            except ValueError:
+                ctx.report_progress(
+                    None, f"invalid deliverable path {ev.path!r}, skipping",
+                )
+                continue
+            try:
+                display = relativize_deliverable_path(absolute, host.workdir)
+            except ValueError:
+                ctx.report_progress(
+                    None,
+                    f"deliverable {ev.path!r}: not under deliverables/, "
+                    "skipping (malfunction)",
+                )
+                continue
+            ctx.report_progress(None, f"Deliverable: {display}")
+            item = (absolute, display)
+            try:
+                deliverable_queue.put_nowait(item)
+            except asyncio.QueueFull:
+                await deliverable_queue.put(item)
+        elif isinstance(ev, BrowserEvent):
+            await ctx.request_browser_open(ev.url)
+        elif isinstance(ev, AttentionEvent):
+            await ctx.need_attention(ev.reason)
+        elif isinstance(ev, DomainMessageEvent):
+            await ctx.domain_message(ev.keyword, ev.data)
+        elif isinstance(ev, DoneEvent):
+            if ev.summary:
+                ctx.report_progress(None, ev.summary)
+            done_flag.set()
+            return
+        elif isinstance(ev, ErrorEvent):
+            error_flag.append(ev.message)
+            return
+        else:
+            assert isinstance(ev, UnknownLine)
+            if ev.text:
+                ctx.report_progress(None, ev.text)
+
+
+async def _deliverable_fetch_loop(
+    host: Host,
+    callback: DeliverableCallback | None,
+    queue: asyncio.Queue[tuple[str, str]],
+    ctx: "ProcessContext",
+    hook_ctx: HookContext,
+) -> None:
+    """Drain the deliverable queue: fetch each file, decode UTF-8,
+    invoke the consumer callback."""
+    while True:
+        absolute, display = await queue.get()
+        try:
+            try:
+                text = await fetch_deliverable_text(host, absolute)
+            except UnicodeDecodeError:
+                ctx.report_progress(
+                    None,
+                    f"Deliverable {display}: not valid UTF-8, skipping callback",
+                )
+                continue
+            except FileNotFoundError:
+                ctx.report_progress(None, f"Deliverable {display}: not found")
+                continue
+            except Exception as exc:  # noqa: BLE001
+                ctx.report_progress(
+                    None,
+                    f"Deliverable {display}: fetch failed: {exc!r}, skipping",
+                )
+                continue
+
+            if callback is None:
+                continue
+            try:
+                await callback(hook_ctx, display, text)
+            except Exception as exc:  # noqa: BLE001
+                ctx.report_progress(
+                    None, f"on_deliverable callback raised: {exc!r}",
+                )
+        finally:
+            queue.task_done()
+
+
+async def _watch_cancellation(ctx: "ProcessContext") -> bool:
+    """Return True when the process is cancelled."""
+    while ctx.should_continue():
+        await asyncio.sleep(0.1)
+    return True

optio_agents-0.1.0.dist-info/METADATA

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: optio-agents
+Version: 0.1.0
+Summary: Agent-coordination layer for optio task types: the optio.log keyword protocol, its session driver, and the LLM-facing keyword documentation (SSOT).
+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 :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Classifier: Framework :: AsyncIO
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: optio-core<0.3,>=0.2
+Requires-Dist: optio-host<0.3,>=0.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+
+# optio-agents
+
+The agent-coordination layer for [optio](https://github.com/deai-network/optio) task types.
+
+`optio-agents` owns the **log/deliverables keyword protocol** that long-running on-host agents use to talk back to optio, the **session driver** that parses and dispatches it, the **`HookContext`** handle passed to agent task hooks, and the **single source of truth** for the LLM-facing keyword documentation.
+
+## What's in the box
+
+- **`optio_agents.protocol`** — a line-oriented session driver. A long-running agent on the host writes lines prefixed `STATUS:`, `DELIVERABLE:`, `DONE`, or `ERROR` to `./optio.log`. `run_log_protocol_session` tails the log, dispatches progress events, fetches deliverable files, and resolves the session on `DONE` / `ERROR`.
+- **`optio_agents.protocol.parser`** — the keyword parser (`parse_log_line`, the typed `*Event` dataclasses, deliverable-path validation).
+- **`optio_agents.protocol.prompt`** — `LOG_CHANNEL_PROMPT`, the canonical LLM-facing documentation of the keywords, co-located with the parser regexes it documents so the two cannot drift. Consumers compose it into their own agent-facing prompt.
+- **`HookContext` / `HookContextProtocol`** — the handle passed into task hooks and `on_deliverable` callbacks, wrapping a `ProcessContext` plus host primitives (`run_on_host`, `copy_file`, `read_from_host`, `download_file`).
+
+## Dependency direction
+
+`optio-agents` depends on `optio-host` (host transport: running commands, file transfer, tunnels) and `optio-core`. It is consumed by agent task packages such as `optio-opencode`.
+
+## Installation
+
+```bash
+pip install optio-agents
+```
+
+Python 3.11+.
+
+## License
+
+Apache-2.0.

optio_agents-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+optio_agents/__init__.py,sha256=IIzBvFpaF0UEr2jSPEamWRTuld2hUHstovoDrDLIS0M,1153
+optio_agents/browser_capture.py,sha256=Ac6dGfkS4LYYnvpx287pebxpbAP8bhGPXJ2Ak__z3MA,1944
+optio_agents/context.py,sha256=mYSe4ihp-z1rGyQJVZAVHCocNp9OMkmSfxfEL1cs5cE,8631
+optio_agents/protocol/__init__.py,sha256=S-AsTRcnSytulOnk5q_Bl8YRhlIgl6gMPDxZ-doMoPQ,1111
+optio_agents/protocol/parser.py,sha256=kgKhcFsLgqUzDK1iOt_r5BGFM0CdafTPK3JZvp6-u4Q,4819
+optio_agents/protocol/prompt.py,sha256=cqxGFG6YRB7p2JGSZwYgxWmD2sbGnO-iGwi2ur4a_m4,2474
+optio_agents/protocol/session.py,sha256=g6B2-MA5hPrGIhLyx-It0_x9SdAzsubIIdCyS9BjTHk,11719
+optio_agents-0.1.0.dist-info/METADATA,sha256=3SHUdk9Ba0Y6JQxzdd3S871VYpSjsoUXw5PO-pw-0dE,2925
+optio_agents-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+optio_agents-0.1.0.dist-info/top_level.txt,sha256=AysTbkJKGJoarjJEZ2Nc34HZ2Pyakz7VtavQlpm8CPo,13
+optio_agents-0.1.0.dist-info/RECORD,,

optio_agents-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

optio_agents-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+optio_agents