agents

agents

Agent providers, ACP, image build, instructions — public API surface.

Re-export catalog for everything agent-shaped: the provider registry, the runner abstraction, ACP-socket inspection, image build, and the instructions / config bundlers. Sources: terok.lib.integrations.executor for the executor wheel's surface, terok.lib.orchestration.image for terok's Dockerfile + image pipeline, terok.lib.core.images for installed-agent queries, terok.lib.domain.auth for the authenticate workflow, and terok.lib.orchestration.agent_config for stack resolution.

__all__ = ['ACPEndpointStatus', 'AGENTS', 'AGENT_NAMES', 'AUTH_PROVIDERS', 'AgentRoster', 'AgentRunner', 'BuildError', 'DEFAULT_BASE_IMAGE', 'EXECUTOR_COMMANDS', 'ExecutorConfigView', 'ImageBuilder', 'acp_socket_is_live', 'auth_provider_aliases', 'available_auth_modes', 'bundled_default_instructions', 'ensure_sandbox_ready', 'get_agent', 'load_auth_providers', 'providers_config_dir', 'resolve_auth_provider', 'resolve_instructions'] module-attribute

auth_provider_aliases()

Map an LLM-provider name to the auth entry that authenticates it.

A native agent is reached for auth under its own name (terok auth codex) yet authenticates a differently-named provider — codex → openai, claude → anthropic, vibe → mistral — so the user should be able to type either. Built from the AGENTS entries whose provider_binding.default differs from their name; tools (gh, sonar) and the collapsed harness-providers (blablador, …) aren't in AGENTS, so they yield no alias — each is already reached under its own name.

Source code in src/terok/lib/domain/auth.py

def auth_provider_aliases() -> dict[str, str]:
    """Map an LLM-provider name to the auth entry that authenticates it.

    A native agent is reached for auth under its own name (``terok auth codex``)
    yet authenticates a differently-named provider — codex → ``openai``, claude →
    ``anthropic``, vibe → ``mistral`` — so the user should be able to type either.
    Built from the ``AGENTS`` entries whose ``provider_binding.default`` differs
    from their name; tools (``gh``, ``sonar``) and the collapsed harness-providers
    (``blablador``, …) aren't in ``AGENTS``, so they yield no alias — each is
    already reached under its own name.
    """
    auth_providers = load_auth_providers()
    return {
        agent.provider_binding.default: name
        for name, agent in AGENTS.items()
        if agent.provider_binding
        and agent.provider_binding.default
        and agent.provider_binding.default != name
        and name in auth_providers
    }

available_auth_modes(provider)

Ordered auth methods provider effectively offers.

The single source of truth for "which login methods does this provider expose", honoring both the roster's declared capabilities and terok's OAuth gate (the experimental flag plus the per-provider allow_oauth). Returns mode ids drawn from "oauth", "device_auth", and "api_key": the device-code variant appears only alongside "oauth" — it is the same credential obtained headlessly — and only for providers that declare it. Shared by the CLI listing, the CLI/TUI method choosers, and the TUI's direct-vs-chooser gating so the two frontends can't drift.

provider is resolved from its LLM-provider alias (openai → codex) first. An unknown provider yields an empty list.

Source code in src/terok/lib/domain/auth.py

def available_auth_modes(provider: str) -> list[str]:
    """Ordered auth methods *provider* effectively offers.

    The single source of truth for "which login methods does this provider
    expose", honoring both the roster's declared capabilities and terok's
    OAuth gate (the ``experimental`` flag plus the per-provider
    ``allow_oauth``).  Returns mode ids drawn from ``"oauth"``,
    ``"device_auth"``, and ``"api_key"``: the device-code variant appears
    only alongside ``"oauth"`` — it is the same credential obtained
    headlessly — and only for providers that declare it.  Shared by the CLI
    listing, the CLI/TUI method choosers, and the TUI's direct-vs-chooser
    gating so the two frontends can't drift.

    *provider* is resolved from its LLM-provider alias (``openai`` → ``codex``)
    first.  An unknown provider yields an empty list.
    """
    from ..core.config import is_oauth_enabled_for

    provider = resolve_auth_provider(provider)
    info = load_auth_providers().get(provider)
    if info is None:
        return []
    modes: list[str] = []
    if info.supports_oauth and is_oauth_enabled_for(provider):
        modes.append("oauth")
        if info.supports_device_auth:
            modes.append("device_auth")
    if info.supports_api_key:
        modes.append("api_key")
    return modes

resolve_auth_provider(name)

Resolve an LLM-provider alias (openai) to its auth entry (codex).

Returns name unchanged when it is already an auth entry (or unknown).

Source code in src/terok/lib/domain/auth.py

def resolve_auth_provider(name: str) -> str:
    """Resolve an LLM-provider alias (``openai``) to its auth entry (``codex``).

    Returns *name* unchanged when it is already an auth entry (or unknown).
    """
    return auth_provider_aliases().get(name, name)

__getattr__(name)

Resolve a re-exported name to its source module on first access (PEP 562).

Source code in src/terok/lib/api/agents.py

def __getattr__(name: str) -> object:
    """Resolve a re-exported name to its source module on first access (PEP 562)."""
    try:
        target = _LAZY[name]
    except KeyError:
        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from None
    module_path, _, source_name = target.partition(":")
    value = getattr(importlib.import_module(module_path), 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/lib/api/agents.py

def __dir__() -> list[str]:
    """Expose the lazy names to ``dir()`` / autocompletion."""
    return sorted({*globals(), *_LAZY})