optio-agents 0.1.0__tar.gz

optio_agents-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,28 @@
+# 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/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "optio-agents"
+version = "0.1.0"
+description = "Agent-coordination layer for optio task types: the optio.log keyword protocol, its session driver, and the LLM-facing keyword documentation (SSOT)."
+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 :: Libraries :: Python Modules",
+    "Topic :: System :: Distributed Computing",
+    "Framework :: AsyncIO",
+]
+dependencies = [
+    "optio-core>=0.2,<0.3",
+    "optio-host>=0.2,<0.3",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+]
+
+[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"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

optio_agents-0.1.0/setup.cfg

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

optio_agents-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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",
+]