terok-executor 0.1.0__py3-none-any.whl

terok_executor/__init__.py

@@ -0,0 +1,179 @@
+# SPDX-FileCopyrightText: 2025 Jiri Vyskocil
+# SPDX-License-Identifier: Apache-2.0
+
+"""terok-executor: single-agent task runner for hardened Podman containers.
+
+Builds agent images, launches instrumented containers, and manages the
+lifecycle of one AI coding agent at a time.  Designed for standalone use
+(``terok-executor run claude .``) and as a library for terok orchestration.
+
+The public surface is ``__all__`` below.  Key entry points:
+
+- [`AgentRunner`][terok_executor.AgentRunner] — launch agents in containers
+- [`Authenticator`][terok_executor.Authenticator] — credential flow
+- [`ImageBuilder`][terok_executor.ImageBuilder] — image construction
+- [`AgentRoster.shared`][terok_executor.AgentRoster.shared] — YAML agent registry (process-wide cache)
+
+Implementation-detail types (raw config schema fragments, ACP error
+classes, internal result types, sidecar image / inject helpers) stay
+in their submodules; reach into ``terok_executor.<sub>`` when you
+need them.
+"""
+
+__version__: str = "0.1.0"  # placeholder; replaced at build time
+
+from importlib.metadata import PackageNotFoundError, version as _meta_version
+
+try:
+    __version__ = _meta_version("terok-executor")
+except PackageNotFoundError:
+    pass  # editable install or running from source without metadata
+
+# -- terok-util shared types (re-exported for convenience) --------------------
+from terok_util import ConfigStack
+
+# -- terok-sandbox protocol types (re-exported for convenience) ----------------
+from terok_executor.integrations.sandbox import ConfigScope
+
+# -- Commands + CLI surface ----------------------------------------------------
+from ._tree import COMMANDS
+
+# -- ACP host-proxy (per-task multi-agent aggregator) -------------------------
+from .acp import ACPEndpointStatus, acp_socket_is_live, list_authenticated_agents
+from .commands import COMMANDS as AGENT_COMMANDS
+
+# -- Config schema + read/write accessors for the executor-owned image: section --
+from .config_schema import ExecutorConfigView, RawImageSection
+
+# -- Container (build, env assembly, runner) -----------------------------------
+from .container.build import (
+    AGENTS_LABEL,
+    DEFAULT_BASE_IMAGE,
+    BuildError,
+    ImageBuilder,
+    ImageSet,
+    build_project_image,
+)
+from .container.cache import seed_workspace_from_clone_cache
+from .container.env import ContainerEnvSpec, assemble_container_env
+from .container.inject import inject_prompt
+from .container.runner import AgentRunner
+
+# -- Credentials (auth flows, extractors, vault commands) ----------------------
+from .credentials.auth import (
+    AUTH_PROVIDERS,
+    Authenticator,
+    AuthSession,
+    prepare_oauth_session,
+    store_api_key,
+)
+from .credentials.vault_commands import VAULT_COMMANDS, scan_leaked_credentials
+
+# -- Krun (KVM-microVM) provisioning + runtime factory -----------------------
+from .krun import KrunHost, KrunHostKeypair, ensure_krun_host_keypair
+
+# -- Provider (descriptor + headless behaviour, instructions, agent config) ----
+from .provider.agents import AgentConfigSpec, parse_md_agent, prepare_agent_config_dir
+from .provider.instructions import bundled_default_instructions, resolve_instructions
+from .provider.providers import (
+    AGENT_PROVIDERS,
+    PROVIDER_NAMES,
+    AgentProvider,
+    CLIOverrides,
+    get_provider,
+    resolve_provider_value,
+)
+
+# -- Roster (agent catalog + config resolution) --------------------------------
+from .roster import AgentRoster
+
+# -- Sandbox bootstrap composition ---------------------------------------------
+from .sandbox import ensure_sandbox_ready
+
+# -- Storage queries (filesystem footprint measurement) -------------------------
+from .storage import SharedMountStorageInfo, TaskStorageInfo
+
+# -- Bootstrap YAML roster into module-level dicts ---------------------------
+# AGENT_PROVIDERS and AUTH_PROVIDERS are empty dicts populated here to avoid
+# circular imports (roster → auth/providers → roster).
+
+
+def _bootstrap_roster() -> None:
+    """Populate module-level provider dicts from the YAML roster."""
+    global PROVIDER_NAMES  # noqa: PLW0603 — tuple requires rebind
+
+    import terok_executor.provider.providers as _reg
+
+    roster = AgentRoster.shared()
+    AGENT_PROVIDERS.update(roster.providers)
+    AUTH_PROVIDERS.update(roster.auth_providers)
+    PROVIDER_NAMES = _reg.PROVIDER_NAMES = roster.agent_names
+
+
+_bootstrap_roster()
+
+__all__ = [
+    "__version__",
+    # ACP host-proxy
+    "ACPEndpointStatus",
+    "acp_socket_is_live",
+    "list_authenticated_agents",
+    # Provider registry + behaviour
+    "AGENT_PROVIDERS",
+    "AgentProvider",
+    "CLIOverrides",
+    "PROVIDER_NAMES",
+    "get_provider",
+    "resolve_provider_value",
+    # Agent config preparation
+    "AgentConfigSpec",
+    "parse_md_agent",
+    "prepare_agent_config_dir",
+    # Auth
+    "AUTH_PROVIDERS",
+    "Authenticator",
+    "AuthSession",
+    "prepare_oauth_session",
+    "store_api_key",
+    # Instructions
+    "bundled_default_instructions",
+    "resolve_instructions",
+    # Config stack
+    "ConfigScope",
+    "ConfigStack",
+    # Config schema (executor-owned slice of the shared config.yml)
+    "ExecutorConfigView",
+    "RawImageSection",
+    # Build: image construction + resource staging
+    "AGENTS_LABEL",
+    "DEFAULT_BASE_IMAGE",
+    "BuildError",
+    "ImageBuilder",
+    "ImageSet",
+    "build_project_image",
+    # Vault credential scanning
+    "scan_leaked_credentials",
+    # Roster
+    "AgentRoster",
+    # Command registry
+    "AGENT_COMMANDS",
+    "COMMANDS",
+    "VAULT_COMMANDS",
+    # Storage queries
+    "SharedMountStorageInfo",
+    "TaskStorageInfo",
+    # Runner facade
+    "AgentRunner",
+    # Container environment assembly
+    "ContainerEnvSpec",
+    "assemble_container_env",
+    # Clone cache + injection helpers
+    "inject_prompt",
+    "seed_workspace_from_clone_cache",
+    # Sandbox bootstrap composition
+    "ensure_sandbox_ready",
+    # Krun (KVM-microVM) provisioning + runtime factory
+    "KrunHost",
+    "KrunHostKeypair",
+    "ensure_krun_host_keypair",
+]

terok_executor/_tree.py

@@ -0,0 +1,39 @@
+# SPDX-FileCopyrightText: 2026 Jiri Vyskocil
+# SPDX-License-Identifier: Apache-2.0
+
+"""Composes executor's full [`CommandTree`][terok_util.cli_types.CommandTree].
+
+Lives below the CLI surface so the package init can re-export the
+composed tree as ``terok_executor.COMMANDS`` (the cli module is at
+the top of the dependency graph; nothing below it may import it).
+
+Three views over one underlying ``SANDBOX_TREE`` instance:
+
+- ``terok-executor <own-verb>``        — executor's verbs (run, auth, …)
+- ``terok-executor sandbox <verb>``    — full sandbox tree, deep path
+- ``terok-executor vault <verb>``      — shortcut sharing identity with
+  the corresponding subtree under ``sandbox``
+"""
+
+from __future__ import annotations
+
+from terok_util import CommandDef, CommandTree
+
+from .commands import COMMANDS as OWN_COMMANDS
+from .credentials.vault_commands import SANDBOX_TREE, VAULT_COMMANDS
+
+#: Executor's top-level command tree.  See module docstring.
+COMMANDS: CommandTree = CommandTree(
+    OWN_COMMANDS
+    + (
+        CommandDef(
+            name="sandbox",
+            help="Sandbox subsystem (full deep tree — same verbs as terok-sandbox)",
+            children=SANDBOX_TREE.roots,
+        ),
+    )
+    + VAULT_COMMANDS
+)
+
+
+__all__ = ["COMMANDS"]

terok_executor/_util/__init__.py

@@ -0,0 +1,18 @@
+# SPDX-FileCopyrightText: 2025 Jiri Vyskocil
+# SPDX-License-Identifier: Apache-2.0
+
+"""Re-exports executor-only utilities (timezone, YAML loader) for internal use.
+
+Standalone — no terok-executor domain imports, safe to use from any layer.
+Cross-package helpers (``ensure_dir``, ``podman_userns_args``, ...) live in
+the shared [`terok_util`][terok_util] package and are imported from there
+directly at every call site.
+"""
+
+from ._timezone import detect_host_timezone
+from ._yaml import load as yaml_load
+
+__all__ = [
+    "detect_host_timezone",
+    "yaml_load",
+]

terok_executor/_util/_timezone.py

@@ -0,0 +1,49 @@
+# SPDX-FileCopyrightText: 2026 Jiri Vyskocil
+# SPDX-License-Identifier: Apache-2.0
+
+"""Detects the host's IANA timezone for propagation into containers.
+
+Returned as a plain string (``"Europe/Prague"``, ``"UTC"``, …) suitable
+for use as a ``TZ`` env var inside the container — glibc resolves it
+against ``/usr/share/zoneinfo`` without needing the host's filesystem.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+_ZONEINFO_MARKER = "/zoneinfo/"
+
+
+def detect_host_timezone() -> str | None:
+    """Return the host's IANA timezone name, or ``None`` if it can't be detected.
+
+    Tried in order:
+
+    1. ``$TZ`` — the user's explicit override.
+    2. ``/etc/timezone`` — Debian/Ubuntu convention, single-line zone name.
+    3. ``/etc/localtime`` symlink — systemd-family hosts (and macOS) symlink
+       this into the zoneinfo database; the zone name is the path suffix
+       after the ``zoneinfo/`` component.
+
+    Returns ``None`` on hosts that expose none of the above (containers with
+    only a copied-in ``/etc/localtime`` file, for instance), letting the
+    caller fall back to the image default rather than guessing.
+    """
+    if tz := os.environ.get("TZ"):
+        return tz
+
+    try:
+        if zone := Path("/etc/timezone").read_text(encoding="utf-8").strip():
+            return zone
+    except OSError:
+        pass
+
+    try:
+        target = Path("/etc/localtime").resolve().as_posix()
+    except OSError:
+        return None
+    if _ZONEINFO_MARKER in target:
+        return target.split(_ZONEINFO_MARKER, 1)[1]
+    return None

terok_executor/_util/_yaml.py

@@ -0,0 +1,24 @@
+# SPDX-FileCopyrightText: 2025 Jiri Vyskocil
+# SPDX-License-Identifier: Apache-2.0
+
+"""Loads YAML strings with round-trip fidelity (comments, order, quotes preserved).
+
+Used for frontmatter parsing and config stack loading.  Vendored from
+terok.lib.util.yaml — only the load path is needed here.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ruamel.yaml import YAML
+
+__all__ = ["load"]
+
+_yaml = YAML(typ="rt")
+_yaml.preserve_quotes = True
+
+
+def load(text: str) -> Any:
+    """Round-trip load from a YAML string, preserving comments and order."""
+    return _yaml.load(text)

terok_executor/acp/__init__.py

@@ -0,0 +1,69 @@
+# SPDX-FileCopyrightText: 2026 Jiri Vyskocil
+# SPDX-License-Identifier: Apache-2.0
+
+"""Per-task host-side ACP (Agent Client Protocol) aggregator.
+
+Bridges a single ACP client (Zed, Toad, …) to one of several
+in-container agents (claude, codex, copilot, …) by namespacing models
+as ``agent:model`` (e.g. ``claude:opus-4.6``) under ACP's standard
+``category: "model"`` configOption.
+
+Module map:
+
+- [`daemon`][terok_executor.acp.daemon] — Unix-socket server, container
+  lifecycle supervision, and the standalone ``terok-executor acp``
+  entry point.  Owns [`serve_acp`][terok_executor.acp.daemon.serve_acp]
+  and the [`acp_socket_is_live`][terok_executor.acp.daemon.acp_socket_is_live]
+  probe used to distinguish live daemons from stale socket files.
+- [`roster`][terok_executor.acp.roster] — per-task aggregation: walks
+  the image's ``ai.terok.agents`` label, probes each agent, and answers
+  "what models does this container offer?"  Owns
+  [`ACPRoster`][terok_executor.acp.roster.ACPRoster] and the
+  vault-side [`list_authenticated_agents`][terok_executor.acp.roster.list_authenticated_agents].
+- [`proxy`][terok_executor.acp.proxy] — the typed bidirectional ACP
+  mediator: implements both `acp.Agent` (toward the connected
+  client) and `acp.Client` (toward the bound backend wrapper)
+  on one object.  Drives the bind handshake on first model pick.
+- [`probe`][terok_executor.acp.probe] — the minimal ``initialize +
+  session/new`` handshake that extracts an agent's model roster.
+- [`cache`][terok_executor.acp.cache] — thread-safe per-agent model
+  cache; survives reconnects, invalidated on credential rotation.
+- [`endpoint`][terok_executor.acp.endpoint] — the
+  [`ACPEndpointStatus`][terok_executor.acp.endpoint.ACPEndpointStatus]
+  enum the host CLI uses to classify endpoints in ``terok acp list``.
+- [`model_options`][terok_executor.acp.model_options] — the
+  ``agent:model`` namespace vocabulary and the typed builders +
+  rewriter that keep the proxy's frames schema-valid.
+
+Bind-trigger surfaces: explicit ``session/set_model`` /
+``session/set_config_option(configId="model")``, or — for clients
+that trust the advertised ``currentModelId`` — lazily on the first
+backend-needing method (e.g. ``session/prompt``).  Cross-agent
+switching mid-session is out of scope for v1; subsequent picks against
+a different agent are rejected at the protocol level.
+
+The exports below are re-exported from ``terok_executor`` so the
+host-side caller (terok) doesn't have to reach into the submodules.
+"""
+
+from __future__ import annotations
+
+from .cache import AgentRosterCache, CacheKey
+from .daemon import acp_socket_is_live, serve_acp
+from .endpoint import ACPEndpointStatus
+from .probe import ProbeError, probe_agent_models
+from .proxy import AgentBindError
+from .roster import ACPRoster, list_authenticated_agents
+
+__all__ = [
+    "ACPEndpointStatus",
+    "ACPRoster",
+    "AgentBindError",
+    "AgentRosterCache",
+    "CacheKey",
+    "ProbeError",
+    "acp_socket_is_live",
+    "list_authenticated_agents",
+    "probe_agent_models",
+    "serve_acp",
+]

terok_executor/acp/cache.py

@@ -0,0 +1,81 @@
+# SPDX-FileCopyrightText: 2026 Jiri Vyskocil
+# SPDX-License-Identifier: Apache-2.0
+
+"""Per-agent model roster cache for the ACP host-proxy.
+
+Probing an agent (initialize + session/new + read configOptions) is
+expensive and the result is stable for the lifetime of an authenticated
+session.  The cache is keyed ``(image_id, auth_identity, agent_id)``:
+same image, same auth, same agent ⇒ same model list.
+
+The cache is populated lazily on the first ``session/new`` after a new
+auth, and never re-probed mid-session.  ``invalidate_auth`` lets workflows
+flush an entire identity's worth of entries when credentials change (today
+auth is global so this is rarely useful; the hook exists for future
+per-project auth).
+"""
+
+from __future__ import annotations
+
+import threading
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class CacheKey:
+    """Composite key for one agent's roster within one auth scope.
+
+    ``auth_identity`` is the constant ``"global"`` today (terok auth is
+    process-wide); the field exists from day one so per-project auth can
+    slot in without a key-schema migration.
+    """
+
+    image_id: str
+    auth_identity: str
+    agent_id: str
+
+
+class AgentRosterCache:
+    """Thread-safe map from [`CacheKey`][terok_executor.acp.cache.CacheKey] to a tuple of model ids.
+
+    Models are stored as a tuple so cache entries are immutable once
+    inserted — callers can return them directly without defensive copying.
+    Empty tuples are valid and signal "probe ran but yielded nothing"
+    (saved to avoid hammering a misconfigured agent on every session).
+    """
+
+    def __init__(self) -> None:
+        self._models: dict[CacheKey, tuple[str, ...]] = {}
+        self._lock = threading.Lock()
+
+    def get(self, key: CacheKey) -> tuple[str, ...] | None:
+        """Return cached models for *key*, or ``None`` if not yet probed."""
+        with self._lock:
+            return self._models.get(key)
+
+    def put(self, key: CacheKey, models: tuple[str, ...]) -> None:
+        """Store *models* under *key*, replacing any existing entry."""
+        with self._lock:
+            self._models[key] = models
+
+    def invalidate_auth(self, auth_identity: str) -> None:
+        """Drop every entry tied to *auth_identity*.
+
+        Used when credentials for an identity rotate — the next
+        ``session/new`` re-probes affected agents.
+        """
+        with self._lock:
+            self._models = {
+                k: v for k, v in self._models.items() if k.auth_identity != auth_identity
+            }
+
+    def __len__(self) -> int:
+        """Return the number of cached entries (for tests / introspection)."""
+        with self._lock:
+            return len(self._models)
+
+
+# Module-level singleton: most callers get this implicitly via
+# [`ACPRoster`][terok_executor.acp.roster.ACPRoster]'s default.  Tests inject a fresh
+# [`AgentRosterCache`][terok_executor.acp.cache.AgentRosterCache] via the constructor.
+GLOBAL_CACHE = AgentRosterCache()