intentframe-executor 0.1.0__py3-none-any.whl

executor/__init__.py

@@ -0,0 +1,24 @@
+"""
+IntentFrame Executor - A Standalone, Protocol-Driven Capability Service.
+
+"The Hands" -- the only entity that touches the real world.
+
+The Executor is an OS Capability Bridge that runs as a standalone,
+process-isolated service. It communicates exclusively through validated
+protocols (gRPC, REST, Unix socket) and secure channels.
+
+Core Invariants:
+    1. Fail-Closed: Any failure -> rejection, never silent approval
+    2. Authorization Required: Every request must carry valid auth proof
+    3. Credentials Never Leave: Creds stay in executor process memory
+    4. Virtual Paths Only: Agents see virtual paths, never real paths
+
+Architecture:
+    Transport Layer   -> How requests arrive (pluggable)
+    Auth Layer        -> How authorization is verified (pluggable)
+    Gateway           -> Orchestration: verify -> validate -> route -> execute
+    Adapter Layer     -> How capabilities are executed (pluggable per platform)
+    Services Layer    -> Cross-cutting: audit, credentials, state, VFS
+"""
+
+__version__ = "0.1.0"

executor/config/__init__.py

@@ -0,0 +1,106 @@
+"""
+Configuration loading and validation for the IntentFrame Executor.
+
+The executor is fully config-driven. A single executor.yaml file
+determines which transport, auth verifier, credential backend,
+and adapter set to load at startup.
+
+No code changes needed to switch deployment profiles.
+Just change the config file.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+from pydantic import ValidationError
+
+from executor.config.schema import ExecutorConfig
+from executor_sdk.constants import DEFAULT_CONFIG_FILENAME
+from executor_sdk.exceptions import ConfigurationError
+
+__all__ = ["ExecutorConfig", "load_config"]
+
+
+def load_config(
+    config_path: str | Path | None = None,
+    config_dict: dict | None = None,
+) -> ExecutorConfig:
+    """Load and validate executor configuration.
+
+    Accepts either a file path to a YAML config or a pre-loaded dict.
+    The config is validated against the Pydantic schema and returned
+    as a typed ExecutorConfig object.
+
+    Args:
+        config_path: Path to executor.yaml. If None and config_dict is None,
+                     searches default locations.
+        config_dict: Pre-loaded config dict (e.g., from tests). Takes
+                     priority over config_path if both are provided.
+
+    Returns:
+        Validated ExecutorConfig.
+
+    Raises:
+        ConfigurationError: If the config file is missing, unreadable,
+                            or fails schema validation.
+    """
+    if config_dict is not None:
+        raw = config_dict
+    elif config_path is not None:
+        raw = _load_yaml(Path(config_path))
+    else:
+        raw = _load_yaml(_find_default_config())
+
+    try:
+        return ExecutorConfig.model_validate(raw)
+    except ValidationError as exc:
+        raise ConfigurationError(
+            f"Invalid executor configuration: {exc.error_count()} validation errors",
+            details={"errors": exc.errors()},
+        ) from exc
+
+
+def _load_yaml(path: Path) -> dict:
+    """Load a YAML file and return as dict."""
+    if not path.exists():
+        raise ConfigurationError(f"Config file not found: {path}")
+
+    try:
+        with open(path) as f:
+            data = yaml.safe_load(f)
+    except yaml.YAMLError as exc:
+        raise ConfigurationError(f"Invalid YAML in {path}: {exc}") from exc
+
+    if not isinstance(data, dict):
+        raise ConfigurationError(f"Config file must be a YAML mapping: {path}")
+
+    return data
+
+
+def _find_default_config() -> Path:
+    """Search for executor.yaml in default locations.
+
+    Search order:
+        1. Current working directory
+        2. executor/config/ (relative to package)
+        3. ~/.config/intentframe/
+
+    Returns the first path that exists.
+    Raises ConfigurationError if none found.
+    """
+    candidates = [
+        Path.cwd() / DEFAULT_CONFIG_FILENAME,
+        Path(__file__).parent / DEFAULT_CONFIG_FILENAME,
+        Path.home() / ".config" / "intentframe" / DEFAULT_CONFIG_FILENAME,
+    ]
+
+    for path in candidates:
+        if path.exists():
+            return path
+
+    locations = "\n  ".join(str(p) for p in candidates)
+    raise ConfigurationError(
+        f"No {DEFAULT_CONFIG_FILENAME} found. Searched:\n  {locations}"
+    )

executor/config/executor.yaml

@@ -0,0 +1,156 @@
+# ═══════════════════════════════════════════════════════════════════════════════
+# IntentFrame Executor Configuration
+# ═══════════════════════════════════════════════════════════════════════════════
+#
+# This file configures the executor service for a specific deployment.
+# Only three things change between deployments:
+#   1. Transport protocol (how requests arrive)
+#   2. Auth verification (how authorization is checked)
+#   3. Credential backend (where secrets are stored)
+#
+# Everything else (gateway logic, adapter pattern, audit trail) is the same.
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# ─── Executor packs: which implementations to load ───────────────────────────
+# Packs are explicit and required -- the executor ships no built-in or
+# platform-default packs. Each pack registers transport / auth / credential /
+# storage / adapter implementations. List the packs your deployment needs, in
+# order. An entry is either an importable module path exposing register_all(),
+# or the short name of a pack advertised under the 'intentframe.executor_packs'
+# entry-point group (how a third-party org plugs in its own pack).
+#
+# First-party packs available in this repo:
+#   intentframe_native_kit.intentframe_executor_pack_posix    portable base (files VFS, sqlite, hmac, uds)
+#   intentframe_native_kit.intentframe_executor_pack_console  console_user_io + simulated_user_io (headless)
+#   intentframe_native_kit.intentframe_executor_pack_macos    native macOS adapters (+ portable base)
+packs:
+  - intentframe_native_kit.intentframe_executor_pack_posix
+
+# ─── Transport: How requests arrive ──────────────────────────────────────────
+# Types: unix_socket (device default), grpc (cloud/device), rest (admin/debug)
+transport:
+  type: unix_socket
+  options:
+    socket_path: /tmp/intentframe/executor.sock
+    # ── gRPC options (when type: grpc) ──
+    # host: "0.0.0.0"
+    # port: 50051
+    # ── REST options (when type: rest) ──
+    # host: "0.0.0.0"
+    # port: 8080
+
+# ─── Auth: How authorization is verified ─────────────────────────────────────
+# Types: guardian_hmac (IntentFrame default), mtls (cloud), bearer (admin/CI)
+auth:
+  type: guardian_hmac
+  options: {}
+    # ── guardian_hmac options ──
+    # secret_key_ref: "intentframe/guardian-hmac-key"
+    # ── mtls options ──
+    # ca_cert: "/path/to/ca.pem"
+    # ── bearer options ──
+    # issuer: "https://auth.intentframe.com"
+    # audience: "executor"
+
+# ─── Credentials: Where secrets are stored ───────────────────────────────────
+# Backends: service (vault service over UDS, default), keyring (OS native),
+#           hashicorp (HashiCorp Vault KV v2, headless/cloud), env (dev/test ONLY)
+credentials:
+  backend: service
+  options: {}
+    # ── keyring options (if backend: keyring) ──
+    # Uses OS-native keyring directly, bypassing the vault service.
+    #
+    # ── service options (default) ──
+    # Talks to the supervisor-managed vault over UDS.
+    # socket_path: "~/.intentframe/run/credential-vault.sock"
+    #
+    # ── hashicorp options (if backend: hashicorp) ──
+    # Stores secrets in HashiCorp Vault KV v2. Options override env vars
+    # (VAULT_ADDR, VAULT_TOKEN / VAULT_ROLE_ID+VAULT_SECRET_ID, etc.).
+    # addr: "https://vault.mycorp.com:8200"
+    # kv_mount: "secret"
+    # path_prefix: "intentframe"
+    # The vault SERVICE itself selects storage via IF_VAULT_BACKEND=hashicorp.
+
+# ─── Worker Pool: Concurrency limits ────────────────────────────────────────
+worker_pool:
+  max_workers: 4
+  default_timeout_seconds: 30.0
+
+# ─── Adapters: Which capabilities to load ────────────────────────────────────
+# Each ID must be registered by a platform-specific adapter module.
+# Uncomment the adapters available on your platform.
+adapters:
+  enabled: []
+    # ── macOS adapters ──
+    # - files
+    # - terminal
+    # - http_api
+    # - user_io
+    # - mail
+    # - calendar
+    # - contacts
+    # - notes
+    # - reminders
+    # - browser
+    # - messages
+    # - notifications
+    # - system
+    # - clipboard
+    # - shortcuts
+    # - spotlight
+    # - filesystem_watch
+
+    # ── Cloud adapters ──
+    # - s3
+    # - ses
+    # - lambda_invoke
+    # - cloud_storage
+
+# ─── Executor pack options ──────────────────────────────────────────────────
+# Opaque config slices owned and validated by executor packs.
+pack_options:
+  # VFS mount table for the files adapter.
+  # List virtual-to-real path mappings here when the ``files`` adapter is enabled.
+  # files:
+  #   base_path: null   # base for relative real_path values; null = home dir
+  #   mounts:
+  #     - virtual_path: /home/
+  #       real_path: ~/
+  #       writable: true
+  #   workspace_id: null  # optional: resolve mounts from resource registry instead
+
+  # Real-path allowlist for host-file tools.
+  # Empty lists + no ``host_files`` adapter means "no host-file access".
+  host_files:
+    allowed_read_paths: []
+    allowed_write_paths: []
+
+  # Kernel-enforced sandbox for shell commands (macOS Seatbelt / sandbox-exec).
+  # Write scope is controlled by allowed_write_paths below (independent of VFS).
+  # All commands run under the highest-privilege template in allowed_templates.
+  # If the sandbox engine is unavailable, every RUN_COMMAND is rejected (fail-closed).
+  sandbox:
+    enabled: true
+    working_directory: ~/
+    allowed_write_paths:
+      - ~/
+    allowed_templates:
+      - pure_compute
+      - file_read_only
+      - file_read_write
+      # - network_outbound    # uncomment to allow outbound network in sandboxed commands
+      # - network_full        # uncomment to allow port binding
+      # - unrestricted        # NOT recommended — bypasses most sandbox restrictions
+
+# ─── Storage: Database and log paths ────────────────────────────────────────
+# null = platform default (macOS: ~/Library/Application Support/IntentFrame/)
+storage:
+  database_path: null
+  log_path: null
+
+# ─── Logging ─────────────────────────────────────────────────────────────────
+logging:
+  level: INFO
+  format: json  # json (structured) or console (human-readable)

executor/config/schema.py

@@ -0,0 +1,223 @@
+"""
+Pydantic schema for executor.yaml configuration.
+
+Every configurable aspect of the executor is represented here.
+The schema provides:
+    - Type validation (catch typos at startup, not at 3am)
+    - Default values (sensible defaults for common deployments)
+    - Documentation (field descriptions serve as config docs)
+
+The config is intentionally flat where possible. Nesting is used
+only for logical grouping (transport, auth, etc.), not for
+hierarchy's sake.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from executor_sdk.constants import (
+    DEFAULT_ADAPTER_TIMEOUT,
+    DEFAULT_GRPC_PORT,
+    DEFAULT_MAX_WORKERS,
+    DEFAULT_REST_PORT,
+    DEFAULT_UNIX_SOCKET_PATH,
+)
+
+__all__ = [
+    "ExecutorConfig",
+    "TransportConfig",
+    "AuthConfig",
+    "CredentialConfig",
+    "WorkerPoolConfig",
+    "AdapterConfig",
+    "StorageConfig",
+    "LoggingConfig",
+]
+
+
+class TransportConfig(BaseModel):
+    """Configuration for the transport layer.
+
+    Only ONE transport is active per executor instance.
+
+    Types:
+        unix_socket: Local IPC (device default)
+        grpc: Cross-machine, high-performance
+        rest: Admin tools, debugging, broad compatibility
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: str = Field(
+        default="unix_socket",
+        description="Transport type: unix_socket, grpc, rest",
+    )
+    options: dict[str, Any] = Field(
+        default_factory=lambda: {"socket_path": DEFAULT_UNIX_SOCKET_PATH},
+        description="Transport-specific configuration options",
+    )
+
+
+class AuthConfig(BaseModel):
+    """Configuration for authorization verification.
+
+    Only ONE auth verifier is active per executor instance.
+
+    Types:
+        guardian_hmac: IntentFrame default (HMAC signature from Guardian)
+        mtls: Mutual TLS certificate verification (cloud)
+        bearer: JWT or opaque bearer token (admin/CI)
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: str = Field(
+        default="guardian_hmac",
+        description="Auth verifier type: guardian_hmac, mtls, bearer",
+    )
+    options: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Auth-specific configuration options",
+    )
+
+
+class CredentialConfig(BaseModel):
+    """Configuration for the credential vault backend.
+
+    Backends:
+        service: Vault service over UDS (default — uses the supervisor-managed vault)
+        keyring: OS native keyring directly (macOS Keychain, Windows Credential Locker)
+        hashicorp: HashiCorp Vault KV v2 over HTTP (headless / cloud / on-prem)
+        env: Environment variables (development/testing ONLY)
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    backend: str = Field(
+        default="service",
+        description="Credential backend: service, keyring, hashicorp, env",
+    )
+    options: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Backend-specific configuration options",
+    )
+
+
+class WorkerPoolConfig(BaseModel):
+    """Configuration for the capability worker pool."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    max_workers: int = Field(
+        default=DEFAULT_MAX_WORKERS,
+        ge=1,
+        le=32,
+        description="Maximum concurrent adapter executions",
+    )
+    default_timeout_seconds: float = Field(
+        default=DEFAULT_ADAPTER_TIMEOUT,
+        gt=0,
+        description="Default timeout per adapter execution (seconds)",
+    )
+
+
+class AdapterConfig(BaseModel):
+    """Configuration for capability adapters.
+
+    The enabled list determines which adapters are loaded at startup.
+    Each adapter ID must be registered via register_adapter() by
+    a platform-specific module.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    enabled: list[str] = Field(
+        default_factory=list,
+        description="List of adapter IDs to load at startup",
+    )
+
+
+class StorageConfig(BaseModel):
+    """Configuration for database, log file paths, and backend selection.
+
+    If paths are null/None, platform-specific defaults are used:
+        macOS:  ~/Library/Application Support/IntentFrame/
+        Linux:  ~/.local/share/intentframe/
+        Cloud:  /var/lib/intentframe/
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    audit_backend: str = Field(
+        default="sqlite",
+        description="Audit log backend: sqlite, cloud",
+    )
+    state_backend: str = Field(
+        default="sqlite",
+        description="State store backend: sqlite, redis",
+    )
+    database_path: str | None = Field(
+        default=None,
+        description="Path to SQLite database. None = platform default.",
+    )
+    log_path: str | None = Field(
+        default=None,
+        description="Path to log file. None = platform default.",
+    )
+
+
+class LoggingConfig(BaseModel):
+    """Configuration for structured logging."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    level: str = Field(
+        default="INFO",
+        description="Log level: DEBUG, INFO, WARNING, ERROR, CRITICAL",
+    )
+    format: str = Field(
+        default="json",
+        description="Log format: json (structured) or console (human-readable)",
+    )
+
+
+class ExecutorConfig(BaseModel):
+    """Root configuration schema for the IntentFrame Executor.
+
+    Loaded from executor.yaml and validated at startup.
+    Any validation error prevents the executor from starting (fail-closed).
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    packs: list[str] = Field(
+        default_factory=list,
+        description=(
+            "Executor packs to load at startup, in order (required -- there are "
+            "no built-in or platform-default packs). Each entry is either an "
+            "importable module path exposing register_all() (e.g. "
+            "'intentframe_native_kit.intentframe_executor_pack_posix'), or the short name of a pack "
+            "advertised via the 'intentframe.executor_packs' entry-point group "
+            "(e.g. an external org's installed pack). Packs register the "
+            "transport, auth, credential, storage and adapter implementations "
+            "this executor uses, so at least one base pack is required."
+        ),
+    )
+    transport: TransportConfig = Field(default_factory=TransportConfig)
+    auth: AuthConfig = Field(default_factory=AuthConfig)
+    credentials: CredentialConfig = Field(default_factory=CredentialConfig)
+    worker_pool: WorkerPoolConfig = Field(default_factory=WorkerPoolConfig)
+    adapters: AdapterConfig = Field(default_factory=AdapterConfig)
+    pack_options: dict[str, dict[str, Any]] = Field(
+        default_factory=dict,
+        description=(
+            "Opaque executor-pack/adaptor options keyed by pack-owned feature "
+            "or adapter ID. Core validates only that each slice is a mapping; "
+            "packs own their own schema validation."
+        ),
+    )
+    storage: StorageConfig = Field(default_factory=StorageConfig)
+    logging: LoggingConfig = Field(default_factory=LoggingConfig)

executor/dispatch.py

@@ -0,0 +1,122 @@
+"""
+Action dispatcher -- routes action types to capability adapters.
+
+The dispatcher maintains a registry of action_type -> CapabilityAdapter
+mappings. When the gateway receives an ExecutionRequest, it asks the
+dispatcher to resolve the action_type to the correct adapter.
+
+Design:
+    - Simple dict-based dispatch. No magic, no reflection.
+    - Each action type maps to exactly ONE adapter.
+    - Action types must be globally unique across all registered adapters.
+    - Unknown action types cause immediate rejection (fail-closed).
+    - Adapters register their supported actions at startup.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from executor_sdk.adapters.base import CapabilityAdapter
+from executor_sdk.exceptions import AdapterNotFoundError
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["ActionDispatcher"]
+
+
+class ActionDispatcher:
+    """Routes action types to their registered capability adapters.
+
+    Usage:
+        dispatcher = ActionDispatcher()
+        dispatcher.register(mail_adapter)
+        dispatcher.register(files_adapter)
+
+        adapter = dispatcher.resolve("SEND_EMAIL")
+    """
+
+    def __init__(self) -> None:
+        self._action_to_adapter: dict[str, CapabilityAdapter] = {}
+        self._adapter_registry: dict[str, CapabilityAdapter] = {}
+
+    def register(self, adapter: CapabilityAdapter) -> None:
+        """Register an adapter and all its supported actions.
+
+        Each action type in adapter.supported_actions() is mapped to
+        this adapter. Duplicate action types raise ValueError to catch
+        configuration errors at startup (not at runtime).
+
+        Args:
+            adapter: The adapter instance to register.
+
+        Raises:
+            ValueError: If any action type is already registered
+                        to a different adapter.
+        """
+        manifest = adapter.manifest()
+        adapter_id = manifest.adapter_id
+
+        for action in adapter.supported_actions():
+            existing = self._action_to_adapter.get(action)
+            if existing is not None:
+                existing_id = existing.manifest().adapter_id
+                if existing_id != adapter_id:
+                    raise ValueError(
+                        f"Action '{action}' is already registered to adapter "
+                        f"'{existing_id}'. Cannot register to '{adapter_id}'. "
+                        f"Each action type must map to exactly one adapter."
+                    )
+
+            self._action_to_adapter[action] = adapter
+
+        self._adapter_registry[adapter_id] = adapter
+
+        logger.info(
+            "Registered adapter: id=%s actions=%s",
+            adapter_id,
+            adapter.supported_actions(),
+        )
+
+    def resolve(self, action_type: str) -> CapabilityAdapter:
+        """Resolve an action type to its registered adapter.
+
+        Args:
+            action_type: The action to look up (e.g., "SEND_EMAIL").
+
+        Returns:
+            The CapabilityAdapter registered for this action.
+
+        Raises:
+            AdapterNotFoundError: If no adapter handles this action type.
+        """
+        adapter = self._action_to_adapter.get(action_type)
+        if adapter is None:
+            registered = ", ".join(sorted(self._action_to_adapter)) or "(none)"
+            raise AdapterNotFoundError(
+                f"No adapter registered for action: '{action_type}'. "
+                f"Registered actions: {registered}",
+            )
+        return adapter
+
+    def get_adapter(self, adapter_id: str) -> CapabilityAdapter | None:
+        """Look up an adapter by its ID. Returns None if not found."""
+        return self._adapter_registry.get(adapter_id)
+
+    @property
+    def registered_actions(self) -> list[str]:
+        """All action types that have a registered adapter."""
+        return sorted(self._action_to_adapter.keys())
+
+    @property
+    def registered_adapters(self) -> list[str]:
+        """All registered adapter IDs."""
+        return sorted(self._adapter_registry.keys())
+
+    def __contains__(self, action_type: str) -> bool:
+        """Check if an action type is registered."""
+        return action_type in self._action_to_adapter
+
+    def __len__(self) -> int:
+        """Number of registered action types."""
+        return len(self._action_to_adapter)