Skip to content

Wrappers

wrappers

Shell wrapper generation for agent CLI commands.

Produces per-provider bash functions (claude(), codex(), vibe(), etc.) that set git identity, handle session resume, and support both interactive and headless (--terok-timeout) modes.

The shell itself lives in the Jinja template resources/templates/agent-wrappers.sh.j2; this module only prepares the per-provider data the template renders. Keeping the shell in a template — rather than assembling it from Python string fragments — lets the wrapper logic be read as shell, with the vendor-specific blocks visible inline.

INITIAL_PROMPT_PATH = '/home/dev/.terok/initial-prompt.txt' module-attribute

Container path of the per-task initial prompt the TUI/CLI writes at launch.

INITIAL_PROMPT_CONSUMED_PATH = '/home/dev/.terok/initial-prompt.consumed.txt' module-attribute

Where the prompt file is moved after an agent picks it up (one-shot semantics).

INSTRUCTIONS_PATH = '/home/dev/.terok/instructions.md' module-attribute

Container path of the resolved terok per-task system instructions.

CONTAINER_WORKSPACE = '/workspace' module-attribute

Container path the host-side repo is bind-mounted at (see container/env.py).

OPENCODE_HARNESS = 'opencode' module-attribute

Agent whose wrapper the curated OpenCode providers delegate to.

Every provider in OPENCODE_PROVIDERS is driven by this harness: their one-word commands select a provider on it rather than naming an agent of their own.

IDENTITY_NAME_ENV = 'TEROK_AGENT_IDENTITY_NAME' module-attribute

Env var a provider alias sets to override the harness wrapper's git author name.

IDENTITY_EMAIL_ENV = 'TEROK_AGENT_IDENTITY_EMAIL' module-attribute

Env var a provider alias sets to override the harness wrapper's git author email.

generate_all_wrappers()

Render terok-executor.sh: a shell wrapper function for every agent.

The output file contains a shell function per agent (claude(), codex(), vibe(), …), each with correct git env vars, timeout support, and session-resume logic, plus the shared helper functions they call. This lets interactive CLI users invoke any agent regardless of which agent was configured as default.

Each curated OpenCode provider additionally gets a one-word alias (blablador(), kisski(), …) that delegates to the harness wrapper, so those commands inherit its feature set instead of reaching the launcher symlink directly and losing it.

Source code in src/terok_executor/provider/wrappers.py 
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
def generate_all_wrappers() -> str:
    """Render ``terok-executor.sh``: a shell wrapper function for every agent.

    The output file contains a shell function per agent (``claude()``,
    ``codex()``, ``vibe()``, …), each with correct git env vars, timeout
    support, and session-resume logic, plus the shared helper functions they
    call.  This lets interactive CLI users invoke any agent regardless of
    which agent was configured as default.

    Each curated OpenCode provider additionally gets a one-word alias
    (``blablador()``, ``kisski()``, …) that delegates to the harness wrapper, so
    those commands inherit its feature set instead of reaching the launcher
    symlink directly and losing it.
    """
    agents = [_wrapper_context(a) for a in AGENTS.values()]
    shortcuts = [_shortcut_context(name) for name in OPENCODE_PROVIDERS]
    return _env().from_string(_template_source()).render(agents=agents, shortcuts=shortcuts)

generate_agent_wrapper(agent)

Render a single agent's wrapper function, without the shared helpers.

Used to inspect one agent's wrapper in isolation; the full file (with the _terok_wrapper_help / _terok_resume_hint / _terok_trust_workspace_for_vibe helpers) is produced by generate_all_wrappers.

Source code in src/terok_executor/provider/wrappers.py 
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
def generate_agent_wrapper(agent: Agent) -> str:
    """Render a single agent's wrapper function, without the shared helpers.

    Used to inspect one agent's wrapper in isolation; the full file (with
    the ``_terok_wrapper_help`` / ``_terok_resume_hint`` /
    ``_terok_trust_workspace_for_vibe`` helpers) is produced by
    [`generate_all_wrappers`][terok_executor.provider.wrappers.generate_all_wrappers].
    """
    ctx = _wrapper_context(agent)
    # Jinja resolves macros dynamically, so the template module's macro
    # attributes (claude_wrapper / generic_wrapper) are not statically known.
    macros: Any = _env().from_string(_template_source()).module
    if ctx["is_claude"]:
        return str(macros.claude_wrapper(ctx))
    return str(macros.generic_wrapper(ctx))

generate_provider_shortcut(name)

Render one curated provider's one-word alias, without the shared helpers.

Companion to generate_agent_wrapper for inspecting a single alias; the full file is produced by generate_all_wrappers.

Source code in src/terok_executor/provider/wrappers.py 
104
105
106
107
108
109
110
111
112
113
def generate_provider_shortcut(name: str) -> str:
    """Render one curated provider's one-word alias, without the shared helpers.

    Companion to
    [`generate_agent_wrapper`][terok_executor.provider.wrappers.generate_agent_wrapper]
    for inspecting a single alias; the full file is produced by
    [`generate_all_wrappers`][terok_executor.provider.wrappers.generate_all_wrappers].
    """
    macros: Any = _env().from_string(_template_source()).module
    return str(macros.provider_shortcut(_shortcut_context(name)))