metaspn-ops 0.1.0__tar.gz

metaspn_ops-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MetaSPN Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

metaspn_ops-0.1.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: metaspn-ops
+Version: 0.1.0
+Summary: Standard inbox/outbox worker runtime for MetaSPN agent systems
+Author: MetaSPN Contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/metaspn/metaspn-ops
+Project-URL: Repository, https://github.com/metaspn/metaspn-ops
+Project-URL: Issues, https://github.com/metaspn/metaspn-ops/issues
+Keywords: metaspn,agents,worker,queue,scheduler
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build>=1.2.2; extra == "dev"
+Requires-Dist: twine>=5.1.1; extra == "dev"
+Dynamic: license-file
+
+# metaspn-ops
+
+Standard inbox/outbox worker runtime for MetaSPN agent systems.
+
+## Features
+
+- Filesystem queue backend with inbox/outbox semantics
+- Task leasing with lock files and lease expiration
+- Retries with exponential backoff and dead-letter queue
+- Worker runner with polling and parallel execution
+- CLI for worker runs and queue operations
+
+## Installation
+
+```bash
+pip install metaspn-ops
+```
+
+## Quickstart
+
+### 1) Define a worker
+
+```python
+# example_worker.py
+from metaspn_ops import Result, Task
+
+
+class EnrichWorker:
+    name = "enrich"
+
+    def handle(self, task: Task) -> Result:
+        payload = {"seen": task.payload}
+        return Result(task_id=task.task_id, status="ok", payload=payload)
+```
+
+### 2) Run a worker once
+
+```bash
+metaspn worker run example_worker:EnrichWorker --workspace . --once --max-tasks 10
+```
+
+### 3) Queue inspection
+
+```bash
+metaspn queue stats enrich --workspace .
+metaspn queue deadletter list enrich --workspace .
+metaspn queue retry enrich --workspace .
+```
+
+## Queue layout
+
+```text
+workspace/
+  inbox/{worker_name}/
+  outbox/{worker_name}/
+  runs/{worker_name}/
+  deadletter/{worker_name}/
+  locks/{worker_name}/
+```
+
+## Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .[dev]
+PYTHONPATH=src python -m unittest discover -s tests -v
+python -m build
+python -m twine check dist/*
+```
+
+## Release
+
+- Tag a release in GitHub (for example `v0.1.0`).
+- GitHub Actions builds and publishes to PyPI using trusted publishing.
+- Configure a PyPI Trusted Publisher for this repository before the first release.
+- See `/Users/leoguinan/MetaSPN/metaspn-ops/PUBLISHING.md` for the full flow.
+
+## License
+
+MIT

metaspn_ops-0.1.0/README.md

@@ -0,0 +1,81 @@
+# metaspn-ops
+
+Standard inbox/outbox worker runtime for MetaSPN agent systems.
+
+## Features
+
+- Filesystem queue backend with inbox/outbox semantics
+- Task leasing with lock files and lease expiration
+- Retries with exponential backoff and dead-letter queue
+- Worker runner with polling and parallel execution
+- CLI for worker runs and queue operations
+
+## Installation
+
+```bash
+pip install metaspn-ops
+```
+
+## Quickstart
+
+### 1) Define a worker
+
+```python
+# example_worker.py
+from metaspn_ops import Result, Task
+
+
+class EnrichWorker:
+    name = "enrich"
+
+    def handle(self, task: Task) -> Result:
+        payload = {"seen": task.payload}
+        return Result(task_id=task.task_id, status="ok", payload=payload)
+```
+
+### 2) Run a worker once
+
+```bash
+metaspn worker run example_worker:EnrichWorker --workspace . --once --max-tasks 10
+```
+
+### 3) Queue inspection
+
+```bash
+metaspn queue stats enrich --workspace .
+metaspn queue deadletter list enrich --workspace .
+metaspn queue retry enrich --workspace .
+```
+
+## Queue layout
+
+```text
+workspace/
+  inbox/{worker_name}/
+  outbox/{worker_name}/
+  runs/{worker_name}/
+  deadletter/{worker_name}/
+  locks/{worker_name}/
+```
+
+## Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .[dev]
+PYTHONPATH=src python -m unittest discover -s tests -v
+python -m build
+python -m twine check dist/*
+```
+
+## Release
+
+- Tag a release in GitHub (for example `v0.1.0`).
+- GitHub Actions builds and publishes to PyPI using trusted publishing.
+- Configure a PyPI Trusted Publisher for this repository before the first release.
+- See `/Users/leoguinan/MetaSPN/metaspn-ops/PUBLISHING.md` for the full flow.
+
+## License
+
+MIT

metaspn_ops-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "metaspn-ops"
+version = "0.1.0"
+description = "Standard inbox/outbox worker runtime for MetaSPN agent systems"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "MetaSPN Contributors" }
+]
+keywords = ["metaspn", "agents", "worker", "queue", "scheduler"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries",
+  "Topic :: System :: Distributed Computing",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2.2",
+  "twine>=5.1.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/metaspn/metaspn-ops"
+Repository = "https://github.com/metaspn/metaspn-ops"
+Issues = "https://github.com/metaspn/metaspn-ops/issues"
+
+[project.scripts]
+metaspn = "metaspn_ops.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

metaspn_ops-0.1.0/setup.cfg

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

metaspn_ops-0.1.0/src/metaspn_ops/__init__.py

@@ -0,0 +1,20 @@
+"""metaspn-ops public API."""
+
+from .backends import QueueBackend, SQLiteQueueStub
+from .fs_queue import FilesystemQueue
+from .lease import LeaseManager
+from .runner import Worker, WorkerRunner
+from .scheduler import TaskScheduler
+from .types import Result, Task
+
+__all__ = [
+    "FilesystemQueue",
+    "LeaseManager",
+    "QueueBackend",
+    "SQLiteQueueStub",
+    "Task",
+    "Result",
+    "TaskScheduler",
+    "Worker",
+    "WorkerRunner",
+]

metaspn_ops-0.1.0/src/metaspn_ops/backends.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Protocol
+
+from .types import Result, RunRecord, Task
+
+
+class QueueBackend(Protocol):
+    worker_name: str
+
+    def enqueue_task(self, task: Task, *, scheduled_for=None) -> Path:
+        ...
+
+    def lease_next_task(self, *, owner: str, lease_seconds: int) -> tuple[Task, Path] | None:
+        ...
+
+    def ack_task(self, leased_path: Path) -> None:
+        ...
+
+    def fail_task(self, leased_path: Path, task: Task, error: str) -> None:
+        ...
+
+    def write_result(self, result: Result) -> Path:
+        ...
+
+    def write_run_record(self, record: RunRecord) -> Path:
+        ...
+
+    def stats(self) -> dict[str, int]:
+        ...
+
+
+class SQLiteQueueStub:
+    """Interface placeholder for PRD milestone M3."""
+
+    def __init__(self, worker_name: str, db_path: str | Path):
+        self.worker_name = worker_name
+        self.db_path = Path(db_path)
+
+    def _not_implemented(self):
+        raise NotImplementedError("SQLite backend is a v0.1 stub; implement in M3")
+
+    def enqueue_task(self, task: Task, *, scheduled_for=None) -> Path:
+        self._not_implemented()
+
+    def lease_next_task(self, *, owner: str, lease_seconds: int) -> tuple[Task, Path] | None:
+        self._not_implemented()
+
+    def ack_task(self, leased_path: Path) -> None:
+        self._not_implemented()
+
+    def fail_task(self, leased_path: Path, task: Task, error: str) -> None:
+        self._not_implemented()
+
+    def write_result(self, result: Result) -> Path:
+        self._not_implemented()
+
+    def write_run_record(self, record: RunRecord) -> Path:
+        self._not_implemented()
+
+    def stats(self) -> dict[str, int]:
+        self._not_implemented()

metaspn_ops-0.1.0/src/metaspn_ops/cli.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+import argparse
+import importlib
+import json
+import sys
+from pathlib import Path
+
+from .fs_queue import FilesystemQueue
+from .runner import RunnerConfig, WorkerRunner
+
+
+def _load_worker(spec: str):
+    if ":" not in spec:
+        raise ValueError("Worker must be import path in form module:attr")
+    module_name, attr = spec.split(":", 1)
+    module = importlib.import_module(module_name)
+    worker = getattr(module, attr)
+    if isinstance(worker, type):
+        worker = worker()
+    if not hasattr(worker, "name") or not hasattr(worker, "handle"):
+        raise ValueError("Loaded worker must expose name and handle(task)")
+    return worker
+
+
+def _parse_every(raw: str | None) -> int | None:
+    if raw is None:
+        return None
+    raw = raw.strip().lower()
+    if raw.endswith("ms"):
+        return max(1, int(raw[:-2]) // 1000)
+    if raw.endswith("s"):
+        return int(raw[:-1])
+    if raw.endswith("m"):
+        return int(raw[:-1]) * 60
+    if raw.endswith("h"):
+        return int(raw[:-1]) * 3600
+    return int(raw)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="metaspn")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    worker_p = sub.add_parser("worker")
+    worker_sub = worker_p.add_subparsers(dest="worker_cmd", required=True)
+    run_p = worker_sub.add_parser("run")
+    run_p.add_argument("worker", help="Worker import path module:attr")
+    run_p.add_argument("--workspace", default=".")
+    run_p.add_argument("--every", default=None)
+    run_p.add_argument("--max-tasks", type=int, default=None)
+    run_p.add_argument("--parallel", type=int, default=1)
+    run_p.add_argument("--lease-seconds", type=int, default=120)
+    run_p.add_argument("--once", action="store_true")
+
+    queue_p = sub.add_parser("queue")
+    queue_sub = queue_p.add_subparsers(dest="queue_cmd", required=True)
+
+    stats_p = queue_sub.add_parser("stats")
+    stats_p.add_argument("worker")
+    stats_p.add_argument("--workspace", default=".")
+
+    retry_p = queue_sub.add_parser("retry")
+    retry_p.add_argument("worker")
+    retry_p.add_argument("--workspace", default=".")
+    retry_p.add_argument("--task-id", default=None)
+
+    deadletter_p = queue_sub.add_parser("deadletter")
+    deadletter_sub = deadletter_p.add_subparsers(dest="deadletter_cmd", required=True)
+    dl_list_p = deadletter_sub.add_parser("list")
+    dl_list_p.add_argument("worker")
+    dl_list_p.add_argument("--workspace", default=".")
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "worker" and args.worker_cmd == "run":
+        worker = _load_worker(args.worker)
+        queue = FilesystemQueue(workspace=Path(args.workspace), worker_name=worker.name)
+        cfg = RunnerConfig(
+            every_seconds=_parse_every(args.every),
+            max_tasks=args.max_tasks,
+            parallel=args.parallel,
+            lease_seconds=args.lease_seconds,
+            once=args.once,
+        )
+        runner = WorkerRunner(queue=queue, worker=worker, config=cfg)
+        processed = runner.run()
+        print(json.dumps({"processed": processed}))
+        return 0
+
+    if args.command == "queue" and args.queue_cmd == "stats":
+        queue = FilesystemQueue(workspace=Path(args.workspace), worker_name=args.worker)
+        print(json.dumps(queue.stats()))
+        return 0
+
+    if args.command == "queue" and args.queue_cmd == "retry":
+        queue = FilesystemQueue(workspace=Path(args.workspace), worker_name=args.worker)
+        retried = queue.retry_deadletter(task_id=args.task_id)
+        print(json.dumps({"retried": retried}))
+        return 0
+
+    if args.command == "queue" and args.queue_cmd == "deadletter" and args.deadletter_cmd == "list":
+        queue = FilesystemQueue(workspace=Path(args.workspace), worker_name=args.worker)
+        items = [str(p) for p in queue.deadletter_items()]
+        print(json.dumps({"items": items}))
+        return 0
+
+    parser.print_help()
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

metaspn_ops-0.1.0/src/metaspn_ops/fs_queue.py

@@ -0,0 +1,156 @@
+from __future__ import annotations
+
+import json
+import threading
+from datetime import datetime, timezone
+from pathlib import Path
+from uuid import uuid4
+
+from .lease import LeaseManager
+from .scheduler import TaskScheduler
+from .types import Result, RunRecord, Task
+
+
+def _ts_for_name(dt: datetime) -> str:
+    dt = dt.astimezone(timezone.utc).replace(microsecond=0)
+    return dt.strftime("%Y-%m-%dT%H%M%SZ")
+
+
+def _safe_task_id(task_id: str) -> str:
+    return "".join(ch if ch.isalnum() or ch in {"-", "_"} else "_" for ch in task_id)
+
+
+class FilesystemQueue:
+    def __init__(
+        self,
+        *,
+        workspace: str | Path,
+        worker_name: str,
+        scheduler: TaskScheduler | None = None,
+    ):
+        self.workspace = Path(workspace)
+        self.worker_name = worker_name
+        self.scheduler = scheduler or TaskScheduler()
+
+        self.inbox_dir = self.workspace / "inbox" / worker_name
+        self.outbox_dir = self.workspace / "outbox" / worker_name
+        self.runs_dir = self.workspace / "runs" / worker_name
+        self.deadletter_dir = self.workspace / "deadletter" / worker_name
+        self.lock_dir = self.workspace / "locks" / worker_name
+
+        for folder in [
+            self.inbox_dir,
+            self.outbox_dir,
+            self.runs_dir,
+            self.deadletter_dir,
+            self.lock_dir,
+        ]:
+            folder.mkdir(parents=True, exist_ok=True)
+
+        self.leases = LeaseManager(self.lock_dir)
+        self._io_lock = threading.RLock()
+
+    def enqueue_task(self, task: Task, *, scheduled_for: datetime | None = None) -> Path:
+        ts = scheduled_for or datetime.now(timezone.utc)
+        name = f"{_ts_for_name(ts)}__t_{_safe_task_id(task.task_id)}.json"
+        path = self.inbox_dir / name
+        with self._io_lock:
+            self._write_json(path, task.to_dict())
+        return path
+
+    def lease_next_task(self, *, owner: str, lease_seconds: int) -> tuple[Task, Path] | None:
+        now_name = _ts_for_name(datetime.now(timezone.utc))
+        for path in sorted(self.inbox_dir.glob("*.json")):
+            scheduled_name = path.name.split("__", 1)[0]
+            if scheduled_name > now_name:
+                continue
+            raw = self._read_json(path)
+            task = Task.from_dict(raw)
+            lease = self.leases.try_acquire(
+                task_id=task.task_id,
+                worker_name=self.worker_name,
+                owner=owner,
+                lease_seconds=lease_seconds,
+            )
+            if lease is not None:
+                return task, path
+        return None
+
+    def ack_task(self, leased_path: Path) -> None:
+        with self._io_lock:
+            if leased_path.exists():
+                raw = self._read_json(leased_path)
+                task_id = raw.get("task_id")
+                leased_path.unlink()
+                if task_id:
+                    self.leases.release(str(task_id))
+
+    def fail_task(self, leased_path: Path, task: Task, error: str) -> None:
+        task.attempt_count += 1
+        can_retry = task.attempt_count < task.max_attempts
+        with self._io_lock:
+            if leased_path.exists():
+                leased_path.unlink()
+            if can_retry:
+                retry_at = self.scheduler.next_retry_at(attempt_count=task.attempt_count)
+                self.enqueue_task(task, scheduled_for=retry_at)
+            else:
+                deadletter_name = f"{_ts_for_name(datetime.now(timezone.utc))}__t_{_safe_task_id(task.task_id)}.json"
+                self._write_json(
+                    self.deadletter_dir / deadletter_name,
+                    {
+                        "task": task.to_dict(),
+                        "final_error": error,
+                        "deadlettered_at": datetime.now(timezone.utc).isoformat(),
+                    },
+                )
+            self.leases.release(task.task_id)
+
+    def write_result(self, result: Result) -> Path:
+        name = f"{_ts_for_name(datetime.now(timezone.utc))}__r_{_safe_task_id(result.task_id)}__{uuid4().hex[:8]}.json"
+        path = self.outbox_dir / name
+        with self._io_lock:
+            self._write_json(path, result.to_dict())
+        return path
+
+    def write_run_record(self, record: RunRecord) -> Path:
+        name = f"{_ts_for_name(datetime.now(timezone.utc))}__run_{record.run_id}.json"
+        path = self.runs_dir / name
+        with self._io_lock:
+            self._write_json(path, record.to_dict())
+        return path
+
+    def stats(self) -> dict[str, int]:
+        return {
+            "inbox": len(list(self.inbox_dir.glob("*.json"))),
+            "outbox": len(list(self.outbox_dir.glob("*.json"))),
+            "runs": len(list(self.runs_dir.glob("*.json"))),
+            "deadletter": len(list(self.deadletter_dir.glob("*.json"))),
+            "locks": len(list(self.lock_dir.glob("*.lock"))),
+        }
+
+    def deadletter_items(self) -> list[Path]:
+        return sorted(self.deadletter_dir.glob("*.json"))
+
+    def retry_deadletter(self, *, task_id: str | None = None) -> int:
+        retried = 0
+        for item in self.deadletter_items():
+            raw = self._read_json(item)
+            task = Task.from_dict(raw["task"])
+            if task_id and task.task_id != task_id:
+                continue
+            task.attempt_count = 0
+            self.enqueue_task(task)
+            item.unlink()
+            retried += 1
+        return retried
+
+    @staticmethod
+    def _read_json(path: Path) -> dict:
+        with path.open("r", encoding="utf-8") as f:
+            return json.load(f)
+
+    @staticmethod
+    def _write_json(path: Path, payload: dict) -> None:
+        with path.open("w", encoding="utf-8") as f:
+            json.dump(payload, f, ensure_ascii=True)

metaspn_ops-0.1.0/src/metaspn_ops/lease.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+
+@dataclass(slots=True)
+class Lease:
+    task_id: str
+    worker_name: str
+    owner: str
+    acquired_at: datetime
+    expires_at: datetime
+
+    def to_dict(self) -> dict[str, str]:
+        return {
+            "task_id": self.task_id,
+            "worker_name": self.worker_name,
+            "owner": self.owner,
+            "acquired_at": self.acquired_at.isoformat(),
+            "expires_at": self.expires_at.isoformat(),
+        }
+
+
+class LeaseManager:
+    def __init__(self, lock_dir: Path):
+        self.lock_dir = lock_dir
+        self.lock_dir.mkdir(parents=True, exist_ok=True)
+
+    @staticmethod
+    def _now() -> datetime:
+        return datetime.now(timezone.utc)
+
+    def _lock_path(self, task_id: str) -> Path:
+        return self.lock_dir / f"{task_id}.lock"
+
+    def try_acquire(self, *, task_id: str, worker_name: str, owner: str, lease_seconds: int) -> Lease | None:
+        now = self._now()
+        expires_at = now + timedelta(seconds=max(1, lease_seconds))
+        lock_path = self._lock_path(task_id)
+
+        if lock_path.exists() and not self._is_expired(lock_path, now):
+            return None
+
+        lease = Lease(task_id, worker_name, owner, now, expires_at)
+
+        try:
+            fd = os.open(lock_path, os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+            with os.fdopen(fd, "w", encoding="utf-8") as f:
+                json.dump(lease.to_dict(), f)
+            return lease
+        except FileExistsError:
+            if self._is_expired(lock_path, now):
+                self.break_lease(task_id)
+                return self.try_acquire(
+                    task_id=task_id,
+                    worker_name=worker_name,
+                    owner=owner,
+                    lease_seconds=lease_seconds,
+                )
+            return None
+
+    def release(self, task_id: str) -> None:
+        lock_path = self._lock_path(task_id)
+        if lock_path.exists():
+            lock_path.unlink()
+
+    def break_lease(self, task_id: str) -> None:
+        self.release(task_id)
+
+    def _is_expired(self, lock_path: Path, now: datetime) -> bool:
+        try:
+            raw = json.loads(lock_path.read_text(encoding="utf-8"))
+            expires_at = datetime.fromisoformat(raw["expires_at"])
+            if expires_at.tzinfo is None:
+                expires_at = expires_at.replace(tzinfo=timezone.utc)
+            return expires_at <= now
+        except Exception:
+            return True

metaspn_ops-0.1.0/src/metaspn_ops/runner.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import concurrent.futures
+import socket
+import time
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Protocol
+from uuid import uuid4
+
+from .backends import QueueBackend
+from .types import Result, RunRecord, Task
+
+
+class Worker(Protocol):
+    name: str
+
+    def handle(self, task: Task) -> Result:
+        ...
+
+
+@dataclass(slots=True)
+class RunnerConfig:
+    every_seconds: int | None = None
+    max_tasks: int | None = None
+    parallel: int = 1
+    lease_seconds: int = 120
+    once: bool = False
+    poll_interval_seconds: float = 0.5
+
+
+class WorkerRunner:
+    def __init__(self, *, queue: QueueBackend, worker: Worker, config: RunnerConfig | None = None):
+        self.queue = queue
+        self.worker = worker
+        self.config = config or RunnerConfig()
+        self.owner = f"{socket.gethostname()}:{uuid4().hex[:8]}"
+
+    def run(self) -> int:
+        if self.config.once:
+            return self._run_batch()
+
+        processed = 0
+        while True:
+            start = time.monotonic()
+            processed += self._run_batch()
+            if self.config.every_seconds is None:
+                time.sleep(self.config.poll_interval_seconds)
+                continue
+            elapsed = time.monotonic() - start
+            sleep_for = max(0.0, self.config.every_seconds - elapsed)
+            time.sleep(sleep_for)
+        return processed
+
+    def _run_batch(self) -> int:
+        target = self.config.max_tasks or 1
+        processed = 0
+
+        with concurrent.futures.ThreadPoolExecutor(max_workers=max(1, self.config.parallel)) as pool:
+            futures = []
+            for _ in range(target):
+                leased = self.queue.lease_next_task(owner=self.owner, lease_seconds=self.config.lease_seconds)
+                if leased is None:
+                    break
+                task, path = leased
+                futures.append(pool.submit(self._process_one, task, path))
+
+            for future in concurrent.futures.as_completed(futures):
+                processed += 1
+                future.result()
+
+        return processed
+
+    def _process_one(self, task: Task, path):
+        started = datetime.now(timezone.utc)
+        error = None
+        status = "ok"
+        try:
+            result = self.worker.handle(task)
+            if result.task_id != task.task_id:
+                result.task_id = task.task_id
+            self.queue.write_result(result)
+            self.queue.ack_task(path)
+        except Exception as exc:
+            status = "error"
+            error = str(exc)
+            self.queue.fail_task(path, task, error)
+            self.queue.write_result(
+                Result(
+                    task_id=task.task_id,
+                    status="error",
+                    payload={},
+                    error=error,
+                    trace_context=task.trace_context,
+                )
+            )
+        finally:
+            finished = datetime.now(timezone.utc)
+            duration_ms = int((finished - started).total_seconds() * 1000)
+            self.queue.write_run_record(
+                RunRecord(
+                    run_id=uuid4().hex,
+                    worker_name=self.worker.name,
+                    task_id=task.task_id,
+                    started_at=started.isoformat(),
+                    finished_at=finished.isoformat(),
+                    duration_ms=duration_ms,
+                    status=status,
+                    error=error,
+                    trace_context=task.trace_context,
+                )
+            )

metaspn_ops-0.1.0/src/metaspn_ops/scheduler.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+
+
+class TaskScheduler:
+    def __init__(self, *, base_delay_seconds: int = 5, max_delay_seconds: int = 3600):
+        self.base_delay_seconds = max(1, base_delay_seconds)
+        self.max_delay_seconds = max(self.base_delay_seconds, max_delay_seconds)
+
+    def next_retry_at(self, *, attempt_count: int, now: datetime | None = None) -> datetime:
+        now = now or datetime.now(timezone.utc)
+        delay = min(self.max_delay_seconds, self.base_delay_seconds * (2 ** max(0, attempt_count - 1)))
+        return now + timedelta(seconds=delay)

metaspn_ops-0.1.0/src/metaspn_ops/types.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+
+UTC = timezone.utc
+
+
+def utc_now() -> datetime:
+    return datetime.now(tz=UTC)
+
+
+@dataclass(slots=True)
+class Task:
+    task_id: str
+    task_type: str
+    payload: dict[str, Any]
+    trace_context: dict[str, Any] = field(default_factory=dict)
+    attempt_count: int = 0
+    max_attempts: int = 3
+    created_at: str = field(default_factory=lambda: utc_now().isoformat())
+
+    @classmethod
+    def from_dict(cls, raw: dict[str, Any]) -> "Task":
+        return cls(
+            task_id=str(raw["task_id"]),
+            task_type=str(raw.get("task_type", "unknown")),
+            payload=dict(raw.get("payload", {})),
+            trace_context=dict(raw.get("trace_context", {})),
+            attempt_count=int(raw.get("attempt_count", 0)),
+            max_attempts=int(raw.get("max_attempts", 3)),
+            created_at=str(raw.get("created_at", utc_now().isoformat())),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "task_id": self.task_id,
+            "task_type": self.task_type,
+            "payload": self.payload,
+            "trace_context": self.trace_context,
+            "attempt_count": self.attempt_count,
+            "max_attempts": self.max_attempts,
+            "created_at": self.created_at,
+        }
+
+
+@dataclass(slots=True)
+class Result:
+    task_id: str
+    status: str
+    payload: dict[str, Any] = field(default_factory=dict)
+    error: str | None = None
+    trace_context: dict[str, Any] = field(default_factory=dict)
+    produced_at: str = field(default_factory=lambda: utc_now().isoformat())
+
+    @classmethod
+    def from_dict(cls, raw: dict[str, Any]) -> "Result":
+        return cls(
+            task_id=str(raw["task_id"]),
+            status=str(raw.get("status", "ok")),
+            payload=dict(raw.get("payload", {})),
+            error=raw.get("error"),
+            trace_context=dict(raw.get("trace_context", {})),
+            produced_at=str(raw.get("produced_at", utc_now().isoformat())),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "task_id": self.task_id,
+            "status": self.status,
+            "payload": self.payload,
+            "error": self.error,
+            "trace_context": self.trace_context,
+            "produced_at": self.produced_at,
+        }
+
+
+@dataclass(slots=True)
+class RunRecord:
+    run_id: str
+    worker_name: str
+    task_id: str
+    started_at: str
+    finished_at: str
+    duration_ms: int
+    status: str
+    error: str | None
+    trace_context: dict[str, Any]
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "run_id": self.run_id,
+            "worker_name": self.worker_name,
+            "task_id": self.task_id,
+            "started_at": self.started_at,
+            "finished_at": self.finished_at,
+            "duration_ms": self.duration_ms,
+            "status": self.status,
+            "error": self.error,
+            "trace_context": self.trace_context,
+        }

metaspn_ops-0.1.0/src/metaspn_ops.egg-info/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: metaspn-ops
+Version: 0.1.0
+Summary: Standard inbox/outbox worker runtime for MetaSPN agent systems
+Author: MetaSPN Contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/metaspn/metaspn-ops
+Project-URL: Repository, https://github.com/metaspn/metaspn-ops
+Project-URL: Issues, https://github.com/metaspn/metaspn-ops/issues
+Keywords: metaspn,agents,worker,queue,scheduler
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build>=1.2.2; extra == "dev"
+Requires-Dist: twine>=5.1.1; extra == "dev"
+Dynamic: license-file
+
+# metaspn-ops
+
+Standard inbox/outbox worker runtime for MetaSPN agent systems.
+
+## Features
+
+- Filesystem queue backend with inbox/outbox semantics
+- Task leasing with lock files and lease expiration
+- Retries with exponential backoff and dead-letter queue
+- Worker runner with polling and parallel execution
+- CLI for worker runs and queue operations
+
+## Installation
+
+```bash
+pip install metaspn-ops
+```
+
+## Quickstart
+
+### 1) Define a worker
+
+```python
+# example_worker.py
+from metaspn_ops import Result, Task
+
+
+class EnrichWorker:
+    name = "enrich"
+
+    def handle(self, task: Task) -> Result:
+        payload = {"seen": task.payload}
+        return Result(task_id=task.task_id, status="ok", payload=payload)
+```
+
+### 2) Run a worker once
+
+```bash
+metaspn worker run example_worker:EnrichWorker --workspace . --once --max-tasks 10
+```
+
+### 3) Queue inspection
+
+```bash
+metaspn queue stats enrich --workspace .
+metaspn queue deadletter list enrich --workspace .
+metaspn queue retry enrich --workspace .
+```
+
+## Queue layout
+
+```text
+workspace/
+  inbox/{worker_name}/
+  outbox/{worker_name}/
+  runs/{worker_name}/
+  deadletter/{worker_name}/
+  locks/{worker_name}/
+```
+
+## Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .[dev]
+PYTHONPATH=src python -m unittest discover -s tests -v
+python -m build
+python -m twine check dist/*
+```
+
+## Release
+
+- Tag a release in GitHub (for example `v0.1.0`).
+- GitHub Actions builds and publishes to PyPI using trusted publishing.
+- Configure a PyPI Trusted Publisher for this repository before the first release.
+- See `/Users/leoguinan/MetaSPN/metaspn-ops/PUBLISHING.md` for the full flow.
+
+## License
+
+MIT

metaspn_ops-0.1.0/src/metaspn_ops.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+README.md
+pyproject.toml
+src/metaspn_ops/__init__.py
+src/metaspn_ops/backends.py
+src/metaspn_ops/cli.py
+src/metaspn_ops/fs_queue.py
+src/metaspn_ops/lease.py
+src/metaspn_ops/runner.py
+src/metaspn_ops/scheduler.py
+src/metaspn_ops/types.py
+src/metaspn_ops.egg-info/PKG-INFO
+src/metaspn_ops.egg-info/SOURCES.txt
+src/metaspn_ops.egg-info/dependency_links.txt
+src/metaspn_ops.egg-info/entry_points.txt
+src/metaspn_ops.egg-info/requires.txt
+src/metaspn_ops.egg-info/top_level.txt
+tests/test_ops_queue.py

metaspn_ops-0.1.0/src/metaspn_ops.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

metaspn_ops-0.1.0/src/metaspn_ops.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+metaspn = metaspn_ops.cli:main

metaspn_ops-0.1.0/src/metaspn_ops.egg-info/requires.txt

@@ -0,0 +1,4 @@
+
+[dev]
+build>=1.2.2
+twine>=5.1.1

metaspn_ops-0.1.0/src/metaspn_ops.egg-info/top_level.txt

@@ -0,0 +1 @@
+metaspn_ops

metaspn_ops-0.1.0/tests/test_ops_queue.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+import json
+import tempfile
+import threading
+import time
+import unittest
+from datetime import datetime, timedelta, timezone
+
+from metaspn_ops.fs_queue import FilesystemQueue
+from metaspn_ops.types import Result, Task
+
+
+class FilesystemQueueTests(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.queue = FilesystemQueue(workspace=self.tmp.name, worker_name="enrich")
+
+    def tearDown(self):
+        self.tmp.cleanup()
+
+    def test_lock_correctness_under_concurrency(self):
+        task = Task(task_id="t1", task_type="enrich", payload={"x": 1})
+        self.queue.enqueue_task(task)
+
+        got = []
+        lock = threading.Lock()
+
+        def attempt():
+            leased = self.queue.lease_next_task(owner=threading.current_thread().name, lease_seconds=30)
+            with lock:
+                got.append(leased is not None)
+
+        threads = [threading.Thread(target=attempt) for _ in range(8)]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+
+        self.assertEqual(sum(1 for x in got if x), 1)
+
+    def test_lease_expiration_behavior(self):
+        task = Task(task_id="t-lease", task_type="enrich", payload={})
+        self.queue.enqueue_task(task)
+
+        first = self.queue.lease_next_task(owner="a", lease_seconds=1)
+        self.assertIsNotNone(first)
+
+        time.sleep(1.2)
+        second = self.queue.lease_next_task(owner="b", lease_seconds=10)
+        self.assertIsNotNone(second)
+
+    def test_retry_scheduling(self):
+        task = Task(task_id="t-retry", task_type="enrich", payload={}, max_attempts=3)
+        self.queue.enqueue_task(task)
+        leased = self.queue.lease_next_task(owner="runner", lease_seconds=10)
+        self.assertIsNotNone(leased)
+        leased_task, leased_path = leased
+
+        before = datetime.now(timezone.utc)
+        self.queue.fail_task(leased_path, leased_task, "boom")
+
+        inbox_files = sorted(self.queue.inbox_dir.glob("*.json"))
+        self.assertEqual(len(inbox_files), 1)
+        scheduled = inbox_files[0].name.split("__", 1)[0]
+        self.assertGreaterEqual(scheduled, before.strftime("%Y-%m-%dT%H%M%SZ"))
+
+        raw = json.loads(inbox_files[0].read_text())
+        self.assertEqual(raw["attempt_count"], 1)
+
+    def test_deadletter_handling(self):
+        task = Task(task_id="t-dead", task_type="enrich", payload={}, max_attempts=1)
+        self.queue.enqueue_task(task)
+        leased = self.queue.lease_next_task(owner="runner", lease_seconds=10)
+        self.assertIsNotNone(leased)
+        leased_task, leased_path = leased
+
+        self.queue.fail_task(leased_path, leased_task, "permanent")
+
+        self.assertEqual(len(list(self.queue.inbox_dir.glob("*.json"))), 0)
+        dead = list(self.queue.deadletter_dir.glob("*.json"))
+        self.assertEqual(len(dead), 1)
+
+    def test_deterministic_ordering(self):
+        base = datetime.now(timezone.utc) - timedelta(minutes=1)
+        self.queue.enqueue_task(Task(task_id="c", task_type="x", payload={}), scheduled_for=base + timedelta(seconds=3))
+        self.queue.enqueue_task(Task(task_id="a", task_type="x", payload={}), scheduled_for=base + timedelta(seconds=1))
+        self.queue.enqueue_task(Task(task_id="b", task_type="x", payload={}), scheduled_for=base + timedelta(seconds=2))
+
+        leased_ids = []
+        for _ in range(3):
+            leased = self.queue.lease_next_task(owner="runner", lease_seconds=20)
+            self.assertIsNotNone(leased)
+            t, p = leased
+            leased_ids.append(t.task_id)
+            self.queue.ack_task(p)
+
+        self.assertEqual(leased_ids, sorted(leased_ids))
+
+    def test_results_roundtrip_json(self):
+        path = self.queue.write_result(Result(task_id="t1", status="ok", payload={"x": 1}))
+        data = json.loads(path.read_text())
+        self.assertEqual(data["task_id"], "t1")
+        self.assertEqual(data["payload"]["x"], 1)
+
+
+if __name__ == "__main__":
+    unittest.main()