intentframe-executor 0.1.0__py3-none-any.whl

executor/server.py

@@ -0,0 +1,175 @@
+"""
+Executor -- FastAPI server on Unix Domain Socket.
+
+Wraps the ExecutorGateway with HTTP endpoints, consistent with
+the other IntentFrame services. Replaces the raw length-prefixed
+Unix socket transport with standard HTTP.
+
+Endpoints:
+    POST /execute   -- gateway.handle(request)
+    POST /rollback  -- gateway.handle_rollback(rollback_id)
+    GET  /health    -- health check
+
+Startup:
+    uvicorn executor.server:app --uds ~/.intentframe/run/executor.sock
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from contextlib import asynccontextmanager
+from typing import Any
+
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel
+
+from executor.config import load_config
+from executor_sdk.exceptions import ConfigurationError
+from executor_sdk.packs import ENTRY_POINT_GROUP
+from executor.main import build_gateway
+from executor_sdk.models import (
+    ExecutionRequest,
+    ExecutionResult,
+)
+
+logger = logging.getLogger(__name__)
+
+_gateway = None
+_worker_pool = None
+
+
+def _load_pack(ref: str) -> None:
+    """Load one executor pack by entry-point name or importable module path.
+
+    A pack is anything exposing a module-level ``register_all()`` (see
+    ``executor_sdk.packs``). There are no built-in or platform-default packs;
+    deployments wire packs purely through ``packs:`` in executor.yaml.
+
+    Resolution order for each ``ref``:
+      1. A distribution advertising ``ref`` under the
+         ``intentframe.executor_packs`` entry-point group (third-party packs
+         referenced by their short name).
+      2. An importable module path exposing ``register_all()`` (first-party
+         packs and anything referenced by full dotted module path).
+    """
+    from importlib import import_module
+    from importlib.metadata import entry_points
+
+    by_name = {ep.name: ep for ep in entry_points(group=ENTRY_POINT_GROUP)}
+    if ref in by_name:
+        register = by_name[ref].load()
+    else:
+        module = import_module(ref)
+        register = getattr(module, "register_all", None)
+        if register is None:
+            raise ConfigurationError(
+                f"Executor pack '{ref}' has no register_all() entry point and "
+                f"is not advertised under the '{ENTRY_POINT_GROUP}' group.",
+            )
+
+    register()
+    logger.info("Executor pack registered: %s", ref)
+
+
+def _register_packs(config) -> None:
+    """Load every configured executor pack once, in order (fail-closed).
+
+    Packs are entirely config-driven: ``executor.yaml`` must list the packs it
+    needs under ``packs:``. Nothing is loaded implicitly.
+    """
+    refs = list(config.packs)
+    if not refs:
+        raise ConfigurationError(
+            "No executor packs configured. Set `packs:` in executor.yaml, e.g.\n"
+            "  packs:\n"
+            "    - intentframe_native_kit.intentframe_executor_pack_posix   # portable base\n"
+            "    - intentframe_native_kit.intentframe_executor_pack_console # console / simulated user_io\n"
+            "(or a pack advertised under the "
+            f"'{ENTRY_POINT_GROUP}' entry-point group).",
+        )
+
+    for ref in refs:
+        try:
+            _load_pack(ref)
+        except ConfigurationError:
+            raise
+        except Exception as exc:
+            raise ConfigurationError(
+                f"Failed to load executor pack '{ref}': {exc}",
+            ) from exc
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    global _gateway, _worker_pool
+    config = load_config(config_path=os.environ.get("EXECUTOR_CONFIG"))
+    _register_packs(config)
+
+    # Platform-specific startup checks (e.g. macOS TCC permissions) are owned by
+    # the relevant executor pack and run when its adapters are constructed in
+    # build_gateway() -- core executor stays deployment-agnostic.
+    _gateway, _transport, _worker_pool = build_gateway(config)
+    logger.info("Executor gateway ready")
+    yield
+    if _worker_pool:
+        await _worker_pool.shutdown()
+    if _gateway:
+        _gateway.close()
+    logger.info("Executor gateway shut down")
+
+
+app = FastAPI(
+    title="IntentFrame Executor",
+    version="0.1.0",
+    lifespan=lifespan,
+)
+
+
+class HealthResponse(BaseModel):
+    status: str = "ok"
+    service: str = "executor"
+    uid: int = 0
+    euid: int = 0
+    running_as_root: bool = False
+    pid: int = 0
+
+
+class RollbackRequest(BaseModel):
+    rollback_id: str
+
+
+@app.get("/health", response_model=HealthResponse)
+async def health() -> HealthResponse:
+    euid = os.geteuid()
+    # ``running_as_root`` reflects machine-level root capability for
+    # RUN_COMMAND, not the executor process's own privilege.  Two paths
+    # to ``True``:
+    #   1. The executor actually runs as UID 0 (rare -- only if the
+    #      whole stack was launched with sudo).
+    #   2. The gateway advertised ``INTENTFRAME_ESCALATION_ARMED=1`` in
+    #      our env at spawn time, meaning ``/etc/sudoers.d/intentframe-run``
+    #      is installed and the sandbox engine is allowed to wrap
+    #      sandbox-exec with ``sudo -n``.
+    # No runtime probe, no YAML coupling -- the YAML only decides
+    # whether each individual command opts into the escalation.
+    env_armed = os.environ.get("INTENTFRAME_ESCALATION_ARMED") == "1"
+    return HealthResponse(
+        uid=os.getuid(),
+        euid=euid,
+        running_as_root=(euid == 0) or env_armed,
+        pid=os.getpid(),
+    )
+
+@app.post("/execute", response_model=ExecutionResult)
+async def execute(request: ExecutionRequest) -> ExecutionResult:
+    if _gateway is None:
+        raise HTTPException(status_code=503, detail="Gateway not initialized")
+    return await _gateway.handle(request)
+
+
+@app.post("/rollback", response_model=ExecutionResult)
+async def rollback(req: RollbackRequest) -> ExecutionResult:
+    if _gateway is None:
+        raise HTTPException(status_code=503, detail="Gateway not initialized")
+    return await _gateway.handle_rollback(req.rollback_id)

executor/worker_pool.py

@@ -0,0 +1,174 @@
+"""
+Worker pool -- manages concurrent adapter execution with limits and timeouts.
+
+The worker pool enforces:
+    - Concurrency limits (semaphore-based, configurable max_workers)
+    - Timeout enforcement (via adapter's safe_execute, which uses asyncio.wait_for)
+    - Clean shutdown (drain in-flight work before stopping)
+
+Design:
+    The skeleton uses asyncio.Semaphore for concurrency control.
+    All adapters run in the gateway's event loop via async execution.
+
+    Future enhancement (platform-specific):
+        ProcessPoolExecutor for crash isolation -- if an adapter crashes
+        the worker process, the gateway survives. This requires running
+        a new event loop per worker process and marshalling results back.
+        The interface stays the same; only the internal execution changes.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+
+from executor_sdk.adapters.base import CapabilityAdapter
+from executor_sdk.constants import DEFAULT_ADAPTER_TIMEOUT, DEFAULT_MAX_WORKERS
+from executor_sdk.models import ExecutionResult
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["WorkerPool"]
+
+
+class WorkerPool:
+    """Manages concurrent adapter execution with limits and timeouts.
+
+    Usage:
+        pool = WorkerPool(max_workers=4, default_timeout=30.0)
+        result = await pool.submit(adapter, "SEND_EMAIL", params, credentials)
+        # result is always an ExecutionResult (never raises)
+
+        await pool.shutdown()  # drain and stop
+
+    Guarantees:
+        - At most max_workers adapters execute concurrently.
+        - Each execution respects its timeout (via safe_execute).
+        - submit() always returns ExecutionResult (never raises).
+        - shutdown() waits for in-flight work to complete.
+    """
+
+    def __init__(
+        self,
+        max_workers: int = DEFAULT_MAX_WORKERS,
+        default_timeout: float = DEFAULT_ADAPTER_TIMEOUT,
+    ) -> None:
+        self._max_workers = max_workers
+        self._default_timeout = default_timeout
+        self._semaphore = asyncio.Semaphore(max_workers)
+        self._active_count = 0
+        self._shutdown_event = asyncio.Event()
+        self._is_shutdown = False
+
+    @property
+    def max_workers(self) -> int:
+        """Maximum number of concurrent workers."""
+        return self._max_workers
+
+    @property
+    def active_count(self) -> int:
+        """Number of currently executing workers."""
+        return self._active_count
+
+    @property
+    def is_shutdown(self) -> bool:
+        """Whether the pool has been shut down."""
+        return self._is_shutdown
+
+    async def submit(
+        self,
+        adapter: CapabilityAdapter,
+        action: str,
+        params: dict,
+        credentials: dict | None = None,
+        timeout: float | None = None,
+    ) -> ExecutionResult:
+        """Submit an action for execution with concurrency control.
+
+        Blocks (via semaphore) if max_workers are already executing.
+        Delegates to adapter.safe_execute() which handles timeout and
+        exception catching.
+
+        Args:
+            adapter: The capability adapter to execute.
+            action: The action type (e.g., "SEND_EMAIL").
+            params: Action-specific parameters.
+            credentials: Credentials from vault (if needed).
+            timeout: Override timeout for this execution. Uses default if None.
+
+        Returns:
+            ExecutionResult -- always, even on failure or pool shutdown.
+        """
+        if self._is_shutdown:
+            return ExecutionResult(
+                success=False,
+                error="Worker pool is shut down",
+            )
+
+        effective_timeout = timeout or self._default_timeout
+        adapter_id = adapter.manifest().adapter_id
+
+        async with self._semaphore:
+            self._active_count += 1
+            start_time = time.monotonic()
+
+            try:
+                logger.debug(
+                    "Worker starting: adapter=%s action=%s active=%d/%d",
+                    adapter_id,
+                    action,
+                    self._active_count,
+                    self._max_workers,
+                )
+
+                result = await adapter.safe_execute(
+                    action=action,
+                    params=params,
+                    credentials=credentials,
+                    timeout=effective_timeout,
+                )
+
+                elapsed_ms = int((time.monotonic() - start_time) * 1000)
+                result.duration_ms = elapsed_ms
+
+                logger.debug(
+                    "Worker completed: adapter=%s action=%s success=%s duration=%dms",
+                    adapter_id,
+                    action,
+                    result.success,
+                    elapsed_ms,
+                )
+
+                return result
+
+            finally:
+                self._active_count -= 1
+                if self._active_count == 0 and self._is_shutdown:
+                    self._shutdown_event.set()
+
+    async def shutdown(self, timeout: float = 10.0) -> None:
+        """Gracefully shut down the worker pool.
+
+        Stops accepting new work and waits for in-flight executions
+        to complete (up to timeout seconds).
+
+        Args:
+            timeout: Maximum seconds to wait for in-flight work.
+        """
+        self._is_shutdown = True
+
+        if self._active_count > 0:
+            logger.info(
+                "Worker pool shutting down: waiting for %d active workers",
+                self._active_count,
+            )
+            try:
+                await asyncio.wait_for(self._shutdown_event.wait(), timeout=timeout)
+            except asyncio.TimeoutError:
+                logger.warning(
+                    "Worker pool shutdown timed out with %d active workers",
+                    self._active_count,
+                )
+        else:
+            logger.info("Worker pool shut down (no active workers)")

intentframe_executor-0.1.0.dist-info/METADATA

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: intentframe-executor
+Version: 0.1.0
+Summary: IntentFrame executor service — dispatches approved actions to capability adapters
+Project-URL: Homepage, https://github.com/intentframe/intentframe
+Project-URL: Repository, https://github.com/intentframe/intentframe
+Project-URL: Issues, https://github.com/intentframe/intentframe/issues
+Author: IntentFrame Contributors
+License-Expression: AGPL-3.0-only
+License-File: LICENSE
+Keywords: agents,ai,executor,intentframe,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.14
+Requires-Dist: fastapi
+Requires-Dist: intentframe-executor-sdk==0.1.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: uvicorn[standard]
+Description-Content-Type: text/markdown
+
+# intentframe-executor
+
+The executor service for [IntentFrame](https://github.com/intentframe/intentframe).
+It receives approved actions from the runtime, dispatches them to capability
+adapters via a worker pool, and enforces the credential/audit boundary. It runs
+as a FastAPI app on a Unix domain socket (`executor.server:app`).
+
+Capability adapters are loaded as executor packs through the
+`intentframe.executor_packs` entry-point group, so deployments select packs
+without modifying this service. Built on `intentframe-executor-sdk`.
+
+```bash
+pip install intentframe-executor
+```

intentframe_executor-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+executor/__init__.py,sha256=uAEz0NxFkmWHWps5I5uP5vwgh5w592vBX91pNTGJ9Hw,1030
+executor/dispatch.py,sha256=M1qnrZUlKB1JdnNTzII0IZXLU4KZScmjJxg9VPAxWSw,4296
+executor/gateway.py,sha256=ygNjpJBX0hZlt2NepIJ6o2W3MEPbNT-KKPrKwwg90Us,15534
+executor/main.py,sha256=hhSZ-ShUofmrSO3XxGXEBpXnDJoGe18zxy0_SGKmy3s,11747
+executor/server.py,sha256=8-MBQb4h6er-_msvZ5wGvys-hqmqdqpgwS36EHxpsCM,5936
+executor/worker_pool.py,sha256=jkZRtOEeJykGeIUvTqE7woGkyaRWnYkm8iT5D_CIQL0,5887
+executor/config/__init__.py,sha256=SHtnvvzfB9TJPURmjDdNR7APwZ473Y3U4_7_W7ZXBo0,3211
+executor/config/executor.yaml,sha256=wjWN-Ary5fw3m8XdUF2U-gl_DZ65RlfYKp0gQPqN6H0,7411
+executor/config/schema.py,sha256=M1Hzyn418qiFV4YbBAx_m7VzWhFX5tvzcv34soyfSlQ,7047
+intentframe_executor-0.1.0.dist-info/METADATA,sha256=bjKwT3xdw--KPFUR9rkvq3185XnlJZg_RUcbTwdJHsg,1480
+intentframe_executor-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+intentframe_executor-0.1.0.dist-info/licenses/LICENSE,sha256=DZak_2itbUtvHzD3E7GNUYSRK6jdOJ-GqncQ2weavLA,34523
+intentframe_executor-0.1.0.dist-info/RECORD,,

intentframe_executor-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any