Instructions

instructions

Resolves agent instructions from layered config with bundled defaults.

Supports flat strings, per-provider dicts, and lists with _inherit splicing. Falls back to a bundled default that describes the standard container environment.

Two independent layers control what a task receives:

1. YAML instructions key — controls the inheritance chain via config stack. Uses _inherit in list form to splice the bundled default at that position. Absent/None ⇒ bundled default.
2. Standalone instructions.md file in project_root — always appended at the end of whatever the YAML chain resolved. Purely additive. If empty or absent, nothing is appended.

resolve_instructions(config, agent_name, project_root=None, *, family=None)

Resolve instructions from a merged config dict.

Supports: - Flat string: returned as-is - Per-agent dict: uses resolve_agent_value, falls back to _default - List (with _inherit): splices bundled default at each _inherit sentinel - Absent/None: returns bundled default

family is the task image's package family ("deb"/"rpm", or None when unknown) — wherever the bundled default is used, its package-manager guidance is rendered for that family.

After resolving the YAML value, appends the contents of project_root/instructions.md (if it exists and is non-empty).

Returns the final instructions text.

Source code in src/terok_executor/provider/instructions.py

def resolve_instructions(
    config: dict[str, Any],
    agent_name: str,
    project_root: Path | None = None,
    *,
    family: str | None = None,
) -> str:
    """Resolve instructions from a merged config dict.

    Supports:
    - Flat string: returned as-is
    - Per-agent dict: uses [`resolve_agent_value`][terok_executor.resolve_agent_value], falls back to ``_default``
    - List (with ``_inherit``): splices bundled default at each ``_inherit`` sentinel
    - Absent/None: returns bundled default

    *family* is the task image's package family (``"deb"``/``"rpm"``, or
    ``None`` when unknown) — wherever the bundled default is used, its
    package-manager guidance is rendered for that family.

    After resolving the YAML value, appends the contents of
    ``project_root/instructions.md`` (if it exists and is non-empty).

    Returns the final instructions text.
    """
    from .providers import resolve_agent_value

    val = config.get("instructions")
    default = bundled_default_instructions(family)

    if val is None:
        base = default
    elif isinstance(val, dict):
        resolved = resolve_agent_value("instructions", config, agent_name)
        if resolved is None:
            base = default
        elif isinstance(resolved, list):
            base = _splice_inherit(resolved, default)
        elif resolved == _INHERIT_SENTINEL:
            base = default
        else:
            base = str(resolved)
    elif isinstance(val, list):
        base = _splice_inherit(val, default)
    elif val == _INHERIT_SENTINEL:
        # Bare _inherit string → same as absent (use bundled default)
        base = default
    else:
        base = str(val)

    # Append standalone instructions file (purely additive)
    file_text = _read_instructions_file(project_root)
    if file_text:
        return f"{base}\n\n{file_text}" if base else file_text
    return base

has_custom_instructions(config, project_root=None)

Check if config has explicit (non-default) instructions.

Returns True when either the YAML instructions key is set or a standalone instructions.md file exists under project_root.

Source code in src/terok_executor/provider/instructions.py

def has_custom_instructions(
    config: dict[str, Any],
    project_root: Path | None = None,
) -> bool:
    """Check if config has explicit (non-default) instructions.

    Returns True when either the YAML ``instructions`` key is set or a
    standalone ``instructions.md`` file exists under *project_root*.
    """
    if config.get("instructions") is not None:
        return True
    return bool(project_root and (project_root / "instructions.md").is_file())

bundled_default_instructions(family=None)

Render the bundled default instructions for a package family.

The bundled default.md is a Jinja2 template branching on family, like the Dockerfile templates: package-manager guidance renders as apt for "deb" bases and dnf for "rpm" bases, and stays deliberately generic when the family is unknown (None) — better no tool advice than wrong tool advice.

Source code in src/terok_executor/provider/instructions.py

def bundled_default_instructions(family: str | None = None) -> str:
    """Render the bundled default instructions for a package *family*.

    The bundled ``default.md`` is a Jinja2 template branching on *family*,
    like the Dockerfile templates: package-manager guidance renders as
    ``apt`` for ``"deb"`` bases and ``dnf`` for ``"rpm"`` bases, and stays
    deliberately generic when the family is unknown (``None``) — better no
    tool advice than wrong tool advice.
    """
    from jinja2 import BaseLoader, Environment

    ref = importlib.resources.files("terok_executor.resources.instructions").joinpath("default.md")
    env = Environment(  # nosec B701 — Markdown output, not HTML
        loader=BaseLoader(),
        trim_blocks=True,
        lstrip_blocks=True,
        keep_trailing_newline=True,
        autoescape=False,
    )
    return env.from_string(ref.read_text(encoding="utf-8")).render(family=family)