Skip to content

Terok executor

terok_executor

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:

Every public name is served lazily (PEP 562 __getattr__): the submodule that defines a symbol is imported only when that symbol is first accessed, so a bare import terok_executor pays for neither the acp protocol stack nor terok_sandbox until something actually reaches for a symbol that needs them. The three ACP names (ACPEndpointStatus, acp_socket_is_live, list_authenticated_agents) are deliberately kept off the roster-bootstrap path so the host-side acp list probe stays cheap.

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__ = _meta_version('terok-executor') module-attribute

__all__ = ['__version__', *_LAZY] module-attribute

__getattr__(name)

Resolve a public name to its defining submodule on first access (PEP 562).

A "module:attr" target renames on the way through — the sole aliased export is AGENT_COMMANDS, which is COMMANDS in .commands (COMMANDS at the package root is the composed tree from ._tree).

Source code in src/terok_executor/__init__.py 
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
def __getattr__(name: str) -> object:
    """Resolve a public name to its defining submodule on first access (PEP 562).

    A ``"module:attr"`` target renames on the way through — the sole
    aliased export is ``AGENT_COMMANDS``, which is ``COMMANDS`` in
    [`.commands`][terok_executor.commands] (``COMMANDS`` at the package
    root is the *composed* tree from [`._tree`][terok_executor._tree]).
    """
    try:
        target = _LAZY[name]
    except KeyError:
        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from None
    if name not in _BOOTSTRAP_FREE:
        _ensure_bootstrapped()
    module_path, _, source_name = target.partition(":")
    value = getattr(importlib.import_module(module_path, __name__), source_name or name)
    globals()[name] = value  # cache so subsequent lookups skip __getattr__
    return value

__dir__()

Expose the lazy names to dir() / autocompletion.

Source code in src/terok_executor/__init__.py 
263
264
265
def __dir__() -> list[str]:
    """Expose the lazy names to ``dir()`` / autocompletion."""
    return sorted({*globals(), *_LAZY})